How do I roll out enforcement safely?

The three modes

• enforce— the real thing. Each call is evaluated against the key's policy and the verdict is applied: allow forwards, deny blocks, and require_approval holds the call for a human.
• shadow — the call is evaluated exactly as it would be under enforce and the real verdict is written to the audit log, but the caller always gets allow. Nothing is ever blocked. This is how you validate a policy against real traffic before it can break anything.
• off — the gateway is a pass-through. No policy is evaluated, no verdict is recorded, and the call is simply allowed. Use it to disable enforcement for a key without deleting it.

What each mode returns

The mode is visible in the /v1/check response (and applied identically on the /mcp proxy). Take a delete_file call that a policy denies:

{
  "decision": "deny",
  "reason": "rule 2 (delete_file) in policy \"my-policy\"",
  "policyId": "…",
  "toolCallId": "…"
}

{
  "decision": "allow",
  "reason": "(shadow) rule 2 (delete_file) in policy \"my-policy\"",
  "policyId": "…",
  "toolCallId": "…",
  "enforcementMode": "shadow"
}

{
  "decision": "allow",
  "reason": "enforcement off",
  "policyId": null,
  "toolCallId": null,
  "enforcementMode": "off"
}

In shadow the reason is prefixed with (shadow) and still names the rule that would have fired — so the live feed shows you every call the policy would have blocked or held, with zero risk to the agent.

The recommended rollout

1. Point the agent at the gateway with the key in off (or shadow) and confirm traffic flows and appears in the feed.
2. Switch the key to shadow. Watch the audit log for a few days: every (shadow) deny/approval is a call that would have been stopped. Tune the policy until the only shadow-blocks are the ones you actually want stopped.
3. Flip to enforce. Nothing about the policy changes — you're just turning the verdicts you already validated into real outcomes.

Where it's set

Enforcement mode is a property of the API key, not the policy — so the same policy can be enforced on one key and shadowed on another. Set it when you create or edit a key. Shadow and off never write approval holds or send notifications, so a shadowed key is safe to leave running indefinitely as a monitoring probe.

Because shadow still records the true verdict, it pairs naturally with trust scores and the security-insights charts: you get a full picture of what a policy would do before it does it.