Reason codes

Every decision carries a reason_code — in raxit audit tail, raxit explain, and the [raxit BLOCKED] message an agent sees. This page lists all 68, grouped by family. Codes are the stable wire vocabulary: third-party tools parsing audit records depend on these exact strings.

`permit.*` (3)

Code	Meaning	What to do
`permit`	The call was permitted by policy.	Nothing — this is the normal path.
`permit.warrant`	A standing warrant upgraded a deferred call to permit; no human loop was needed.	Nothing — confirm the warrant that fired is the one you expect (`raxit explain <call_id>`).
`permit.approved`	A human approved this deferred call; the approval token was valid and consumed.	Nothing — this is `raxit approvals approve` completing normally.

`defer.*` (8)

Code	Meaning	What to do
`defer.policy`	An allow-with-`@effect("defer")` rule matched (a non-`review` defer path — budget/cost/context-completeness, not a `rules[].effect: review`).	`raxit approvals approve <token>`.
`defer.step_up`	A `rules[].effect: review` rule matched — explicit human approval required.	`raxit approvals approve <token>`.
`defer.budget_exceeded`	Session or daily call budget reached and `budgets.on_exceed: defer`.	`raxit approvals approve <token>`, or raise `budgets.session_calls` / `budgets.daily_calls`.
`defer.cost_exceeded`	Dollar cost budget reached and `budgets.on_exceed: defer`.	`raxit approvals approve <token>`, or raise `budgets.cost` limits.
`defer.context_incomplete`	A required context key (`context_guard.required`) is missing for this resource; suspended, not denied.	Resupply the listed context keys and retry.
`defer.output_policy`	A post-execution output-gate rule routed the tool result to human review.	`raxit approvals approve <token>`.
`defer.spend_anomaly`	`budgets.anomaly.action: defer` — the principal's last cost sample scored as a Z-score anomaly.	Approve or wait; raise `budgets.anomaly.z_threshold` if this fires too eagerly.
`defer.circuit_reattest`	`limits.breaker.on_open: defer` — this key's circuit breaker is OPEN after repeated tool-execution failures.	Approve to re-probe, or wait for `limits.breaker.recovery`.

`deny.*` — identity & principal (4)

Code	Meaning	What to do
`deny.identity_unverified`	The identity token is missing or invalid.	Ensure the agent presents a valid SPIFFE SVID, OIDC token, or dev identity token.
`deny.principal_untrusted_method`	The identity is verified but its verification method isn't allowlisted.	Check `identity.trusted_methods` in `security.yaml`.
`deny.principal_mismatch`	The attested principal matches no rule's `agent:` — structurally unmatchable.	Run without `--agent` to auto-derive the id, or set `agent:` in `security.yaml` to the presented principal. See Common issues.
`deny.agent_killed`	This principal was kill-switched by an operator.	`raxit agent unkill <id>`.

`deny.*` — policy, evaluation & modify (5)

Code	Meaning	What to do
`deny.default_or_forbid`	A `block` rule matched, or no rule covered this call (default-deny).	Add a matching `allow`/`review` rule if this call should be permitted.
`deny.eval_error`	The policy engine raised an internal error.	Check Cedar policy syntax (`raxit check`) and engine logs; retry.
`deny.not_ready`	No policy bundle is loaded yet.	Run `raxit serve` or `raxit dev` to start the governor with a valid policy.
`deny.modify_error`	A `modify:` rule's transform couldn't be applied.	Check the `modify:` config on the contributing rule and the logs of the enforcement point that intercepted the call — the SDK or launcher output.
`deny.audit_error`	The audit write failed before the decision could return (audit-before-execute).	Check disk space/permissions on the audit path; the governor failed closed to protect the log.

`deny.*` — credentials, budgets & rate limiting (7)

Code	Meaning	What to do
`deny.credential_error`	The credential broker failed to mint a short-lived credential.	Check broker configuration and IAM permissions.
`deny.budget_exceeded`	Session or per-day call budget exhausted (`budgets.on_exceed` unset or `block`).	Raise `budgets.session_calls` / `budgets.daily_calls`, start a new session, or wait for the daily reset.
`deny.cost_exceeded`	Dollar cost budget exhausted.	Raise `budgets.cost.session_max` / `daily_max`, or wait for the daily reset.
`deny.rate_limited`	Too many calls in the configured rate window.	Reduce call frequency or raise `limits.rate_max`.
`deny.loop_detected`	Repeated identical calls detected — a possible runaway agent.	Review the agent's own control logic.
`deny.spend_anomaly`	`budgets.anomaly.action: deny` — the last cost sample scored as a Z-score anomaly.	Review recent spend, or raise `budgets.anomaly.z_threshold`.
`deny.circuit_open`	`limits.breaker.on_open: deny` (the default) — this key's breaker is OPEN.	Wait for `limits.breaker.recovery`, or investigate the failing tool.

`deny.*` — delegation (6)

Code	Meaning	What to do
`deny.delegation_invalid`	The delegation token is missing, forged, or expired.	Re-issue a delegation grant from the delegating principal.
`deny.delegation_depth_exceeded`	The delegation chain is deeper than `delegation.max_depth`.	Reduce chain depth or raise `delegation.max_depth`.
`deny.delegation_scope_exceeded`	The requested resource is outside the delegated scope.	Re-issue the delegation grant covering this resource.
`deny.delegation_presenter_mismatch`	A delegation token was presented by the wrong principal.	Ensure the correct delegatee presents the token.
`deny.delegation_ttl_exceeded`	The grant's remaining validity exceeds `delegation.max_ttl`.	Re-issue a shorter-lived grant.
`deny.delegation_issuer_not_allowed`	The grant's issuer isn't in `delegation.allowed_issuers`.	Re-issue from an allowed issuer, or update the allowlist.

`deny.*` — approvals, taint & output (6)

Code	Meaning	What to do
`deny.approval_denied`	A human explicitly denied this deferred call.	Review the denial with the approver; the call cannot proceed as-is.
`deny.approval_expired`	The deferred call timed out (120s default) before a human approved it.	Resubmit the call to generate a new approval request.
`deny.taint_trifecta`	Tainted session data would reach an external destination — the lethal-trifecta break.	Review the data flow, or pre-approve the egress with a warrant. See Taint.
`deny.output_policy`	An output-gate rule denied the tool result post-execution.	Check `output_rules` in `security.yaml` for the matching deny condition.
`deny.output_unknown_scanner`	An output rule named an unsupported scanner.	Fix or remove the scanner name in `security.yaml`.
`deny.output_postcondition`	A `postcondition` scanner rule denied the tool output.	Check `postcondition.rules` and the tool result for a policy violation.

`deny.*` — control plane, state & session (5)

Code	Meaning	What to do
`deny.control_plane_unreachable`	A state-bearing decision needed the control plane, which was unreachable (degrade-closed).	Restore connectivity; the call was correctly denied rather than answered with stale local state.
`deny.deferral_limit`	This session already has the max number of concurrently deferred actions pending.	Resolve or wait for one to time out, or raise `budgets.max_concurrent_deferred`.
`deny.warrant_state_unavailable`	A covering warrant matched, but the shared consume-once counter couldn't be reached or gave an unusable answer.	Restore connectivity to the state service (`RAXIT_STATE_ENDPOINT`), or resolve via human approval instead.
`deny.saga_journal_unconfirmed`	A permitted compensatable step's saga event couldn't be durably journaled before execution.	Restore connectivity to the state service and retry.
`deny.multiagent_budget_cancelled`	A shared aggregate or per-agent multiagent-pool budget breach cancelled this call.	Check `multiagent.pool` budget settings.

`deny.*` — context guard (3, + 1 dead code)

Code	Meaning	What to do
`deny.context_stale`	The call timestamp is outside the configured clock-skew window.	Sync the agent clock, or raise `context_guard.max_clock_skew`.
`deny.context_replay`	The context sequence number is missing, malformed, or not strictly increasing.	Send a strictly increasing integer under `context_guard.sequence_key`.
`deny.context_incomplete`^†	Documented as "a required context key is missing," but has no emission site anywhere in the codebase.	Don't expect to see this fire. If you're chasing a missing-context denial, look for `defer.context_incomplete` instead — that's the code that actually fires for this condition (as a suspend, not a deny).

^† deny.context_incomplete is defined, registered, and hinted, but is currently dead — grepping the source finds no call site outside the reason-code registry itself. Documented here for completeness only; do not use it as a "this is how missing context denies" reference.

`deny.*` — MCP fingerprinting (3)

Code	Meaning	What to do
`deny.mcp_fingerprint_changed`	An MCP tool's description/schema hash changed since it was first observed or pinned (`mcp.fingerprint.on_change: deny`).	Review the tool for tampering; if legitimate, update the pin in `security.yaml`.
`deny.mcp_fingerprint_unknown`	No pin or trusted baseline covers this MCP tool (`mcp.fingerprint.on_unknown: deny`).	Add a pin under `mcp.fingerprint.pins`, or switch `mode: tofu` to learn a baseline.
`deny.mcp_description_scan`	A hidden-instruction or invisible-Unicode signal was found in a tool's description/schema (`mcp.description_scan.on_hit: deny`).	Review the tool description for supply-chain tampering.

`deny.*` — drift, phases & pipeline (7)

Code	Meaning	What to do
`deny.semantic_drift`	Aggregate multi-agent output cosine-distance exceeded the configured threshold.	Review the multi-agent output for divergence.
`deny.intent_baseline_missing`	`session_drift.require_intent_warrant` is set but no attested intent-warrant exists for this session.	Issue an intent-warrant (`Kind: intent`) from an attested, non-agent principal before the session's calls can be scored.
`deny.nondeterministic_gate`	A programmatic caller configured session-drift enforcement with a non-deterministic provider — never allowed to gate a verdict.	Use a deterministic local provider, or set `enforce: false` for advisory-only scoring.
`deny.phase_tool_blocked`	This tool matched a `blocked_tools` pattern in the current workflow phase.	Check the `blocked_tools` list for the active phase.
`deny.phase_tool_not_allowed`	`allowed_tools` is non-empty for the current phase and this tool matched none of it.	Check the `allowed_tools` list for the active phase.
`deny.phase_expired`	The current workflow phase exceeded its `max_duration`.	Advance to the next phase, or raise `max_duration`.
`deny.pipeline_tamper_detected`	A multi-agent handoff seal mismatch — content received by B doesn't match what A sent.	Investigate for tampering between agents; treat as a security incident, not a config issue.

`deny.*` — classification (1)

Code	Meaning	What to do
`deny.classification_receipt_error`	A non-sealed classifier's audit receipt write failed before its labels could enter session taint.	The governor failed closed and applied none of that classifier's labels for this call; check audit-write health.

`modify.*` (1)

Code	Meaning
`modify.policy`	The call was permitted and executed with policy-transformed arguments — the declared `modify:` transform was applied before forwarding.

`policy.*` — operator lifecycle, not per-call decisions (3)

These are audit tags for operator actions on the policy itself, not decisions on an agent's tool call — they show up in the audit trail when a human changes the active policy.

Code	Meaning
`policy.rollback`	An operator rolled back to a prior policy snapshot (`raxit rollback`).
`policy.reload`	An operator hot-reloaded the policy via `POST /v1/reload` or SIGHUP.
`policy.apply`	An operator applied a new policy version via `raxit apply` (validate → tests-gate → push).

`compensation.*` — undo-directive signals, not Cedar decisions (4)

Per the source: these are not Decision.ReasonCode values from a Cedar evaluation — a compensation ("undo") call is governed normally and carries its own ordinary reason code (e.g. deny.budget_exceeded). These are separate signals surfaced so a post-permit output-block's fate is never silently swallowed.

Code	Meaning	What to do
`compensation.build_failed`	A compensatable tool's output was blocked, but `compensation.tools[].arg_mapping` couldn't resolve a source path from the original call's args — no undo was built.	Review the `arg_mapping` against what the tool actually received.
`compensation.uncompensatable`	A blocked tool's declared `reversibility` is `irreversible` (or declares no compensation) — nothing to undo.	Alert-only; review the blocked call manually.
`compensation.undo_denied`	The built undo call didn't itself permit when re-governed (deny or defer).	Review the undo's own Decision Provenance Record (DPR) (`CompensationFor` links back to the original call) and resolve manually.
`compensation.terminal`	A compensation ("undo") call's own output was blocked — an undo is never itself compensated (depth cap 1).	Review the undo call manually; this is terminal, no further auto-undo happens.

`classification.*` — receipt tags, not Cedar decisions (2)

Code	Meaning
`classification.recorded`	A non-sealed classifier's receipt was durably recorded to the audit log before its labels entered session taint.
`classification.degraded`	The configured classifier errored or was unreachable; the governor recorded this as evidence and either degraded to the sealed regex floor (`on_classifier_unavailable: regex_degrade`, the default) or surfaced the failure (`fail_closed`).

Several deny/defer pairs share the same detector but route differently by config: — deny.budget_exceeded / defer.budget_exceeded (budgets.on_exceed), deny.spend_anomaly / defer.spend_anomaly (budgets.anomaly.action), and deny.circuit_open / defer.circuit_reattest (limits.breaker.on_open). These aren't redundant — each pair is the same underlying condition, routed to a different resolution path by an explicit operator knob.

Reason codes

On this page