Reference › Reason codes

Reason codes

Every non-PASS Doberman decision carries one or more ReasonCode values plus a human explanation. ReasonCode itself is defined in src/doberman/models.py. This page catalogues every member of that enum: where in the code it actually gets attached to a decision, and what it means in plain language. The enum currently defines 65 codes. doberman log and doberman tune --json (see CLI reference) both surface these values directly, so matching on the name here is the stable way to script against a decision.

View as Markdown Edit on GitHub ↗

Code	Group	Raised in	Meaning
`normalization_failed`	General	`engine/rules/normalization.py`, `proxy/normalize.py`	The proxy's `normalize()` step raised, so the action falls back to a conservative high-risk placeholder and escalates to authentication instead of passing through un-normalized.
`unknown_tool`	General	(reserved, enum only)	Reserved for a requested tool name absent from the downstream tool list. Defined for that purpose but not wired to a raise site in shipped code.
`downstream_error`	General	`proxy/executor.py`	The downstream tool call, made over MCP (Model Context Protocol, the interface Doberman's proxy uses to reach real tools), raised while being forwarded, so the result is denied and the failure is never exposed to the agent.
`single_use_elevation_unclaimable`	General	`proxy/executor.py`	A single-use elevation covered the action, but the atomic claim taken just before the forward found it already spent (a concurrent call won it) or could not be recorded, so the forward is refused rather than let two calls release on one approval.
`effect_set_diverged`	General	`proxy/executor.py`	The proxy recomputes a delete-class command's bounded blast-radius effect set right before forwarding it. If that recompute's digest disagrees with what was shown to the human at approval time, in either direction, or a previously-known count becomes unknown, the forward is refused with a synthetic `BLOCK` rather than executed against a stale preview.
`ambient_scoring_error`	General	`monitor/daemon.py`	The ambient monitor (FM.2) could not reconstruct a `SecurityObject` from a redacted `ActivityEvent`, or scoring it through `decide()` raised. Per-event isolation records a conservative alert row instead of dropping the event silently or letting one poisoned event kill the daemon's tick loop. Never produced on the live/inline decision path.
`objective_guardrail_error`	General	`engine/decision_engine.py`, `proxy/executor.py`	The objective guardrail, or a post-decision integrity check such as the output secret scan or artifact digest check, raised an unhandled exception, so the action fails closed to `BLOCK`.
`subjective_guardrail_error`	General	`engine/decision_engine.py`, `engine/subjective.py`	The subjective guardrail raised an unhandled exception after the objective guardrail already passed, so the action escalates to authentication instead of silently passing.
`subjective_block_clamped`	General	`engine/decision_engine.py`, `policy/drift.py`	The subjective guardrail returned `BLOCK`, but none of its reason codes sit on the hard-block allowlist, so the execution rule clamps that `BLOCK` down to `AUTH` and records that the clamp happened.
`proxy_handler_error`	General	`proxy/executor.py`	An unhandled exception escaped the proxy's top-level tools/call handler, outside `normalize()`'s and `decide()`'s own error handling, so the call is denied carrying only the exception's class name, never its message.
`secret_exfiltration`	Objective guardrail	`engine/rules/secrets.py`, `hosthooks/hookio.py`, `policy/modes.py`, `proxy/executor.py`	A known credential or secret pattern, or a base64/hex payload that decodes to one, appeared in an action headed to an external destination. The rule hard-blocks it in every mode.
`sensitive_secret_access`	Objective guardrail	`auth/challenge.py`, `engine/rules/secrets.py`, `proxy/executor.py`	The action reads or targets a file recognized as holding secrets, such as `.env` or a private key, with no evidence it is leaving the session, so it requires authentication.
`possible_high_entropy_secret`	Objective guardrail	`engine/rules/secrets.py`	Only the weak, purely statistical high-entropy heuristic matched: no known credential shape and no secret file, so the action requires authentication. It is a lower-confidence sibling of `sensitive_secret_access`, kept separate so output scanning can pass through likely-benign hashes, UUIDs, and base64 fragments instead of hard-blocking a benign read.
`protected_path_blocked`	Objective guardrail	`engine/rules/commands.py`, `engine/rules/paths.py`, `policy/modes.py`	The target path resolves inside a location explicitly protected by policy, such as Doberman's own control-plane files, so the rule hard-blocks the action.
`sensitive_path_access`	Objective guardrail	`auth/challenge.py`, `engine/rules/paths.py`, `policy/drift.py`	The target path matches a sensitive-but-not-protected location, so the action requires authentication before it proceeds.
`destructive_command`	Objective guardrail	`engine/rules/commands.py`, `policy/modes.py`	A shell or git command matched a pattern that irreversibly destroys data or history: a recursive force-delete, a history rewrite, or piping a downloaded payload into a shell. Also covers process kill/signal commands (`kill`/`pkill`/`killall`/`taskkill`, `os.kill`, psutil kill/terminate) at the AUTH tier; own-job targets (`%N`, `$!`) and probes (`-0`, `-l`) stay PASS.
`environment_dump_command`	Objective guardrail	`engine/rules/commands.py`	A shell command whose sole effect is to enumerate or print the process environment (bare `env`, any form of `printenv`, `export`/`export -p`, `declare -x`/`typeset -x` with no named variable, or a PowerShell `Env:` drive listing). This is a locally scoped read of a common secret carrier, so it requires authentication before it runs.
`bulk_operation`	Objective guardrail	`auth/challenge.py`, `engine/rules/commands.py`, `policy/drift.py`	A command deletes at or above the configured bulk-operand threshold, so it requires authentication before the mass operation proceeds.
`opaque_command`	Objective guardrail	`auth/challenge.py`, `engine/rules/commands.py`	A command's effect cannot be determined statically: an inline shell payload (`-c ...`), or a command that fails to parse safely. It requires authentication before it runs. This also covers `runuser -c`/`--command`/`--command=`, which is opaque exactly like `su -c` and never a transparently-consumed wrapper option. It also covers an inline Python/Node payload (`python -c`/`node -e`) that opens a socket directly with no shell-spawn, a raw-egress shape folded into this general opaque-inline-payload code rather than `raw_socket_channel`. (A payload that opens a socket AND spawns a subprocess/shell is a reverse shell, which goes to `raw_socket_channel` BLOCK instead, not this code.) It also covers an interpreter one-liner that spawns a subprocess (`subprocess`, `os.system`, `child_process`, …); the command literals it passes are walked by the same rule and can raise the step-up to BLOCK. Finally, it covers an inline payload fragmented into more than 128 candidates (a length proxy: ordinary one-liners measure 7–43) or naming more than 32 absolute/`~`/`..` paths (the filesystem-resolve budget; every path is still matched textually). This last check is a floor applied after every stronger check, so a control-plane/destructive/socket/kill/privilege match on the same payload still BLOCKs/AUTHs at its own tier first.
`unknown_external_destination`	Objective guardrail	`auth/challenge.py`, `egress/local.py`, `engine/rules/destinations.py`	A network destination is not on the trusted-host allowlist and cannot otherwise be classified as safe, so it requires authentication, subject to mode thresholds and any proven-broker override.
`egress_requires_auth`	Objective guardrail	`engine/rules/destinations.py`	A shell, package-install, or git command has an external destination whose runtime route static parsing cannot prove, so it requires authentication regardless of how trusted the parsed host looks.
`encoded_exfiltration`	Objective guardrail	`auth/challenge.py`	Reserved for a base64/hex-encoded payload that decodes to a secret pattern. It is wired into auth tiering and policy, but the shipped secrets rule currently reports such decoded hits as `secret_exfiltration` or `possible_high_entropy_secret`, so this code is not presently emitted.
`tool_schema_changed`	Objective guardrail	`proxy/executor.py`	The tool's `(name, description, inputSchema)` fingerprint no longer matches the pinned one, a possible rug-pull. This is `AUTH` in Light/Balanced and `BLOCK` in Strict/Paranoid until a human re-approves the pin.
`rule_error`	Objective guardrail	`engine/objective.py`, `engine/subjective.py`	An individual objective or subjective rule raised, or returned something other than a `GuardrailResult`, while being evaluated. That one rule's result is isolated to `AUTH` instead of forcing a silent `PASS` or an unrelated hard `BLOCK`.
`role_blocked_target`	Role policy	`engine/rules/role_boundary.py`, `policy/modes.py`	The active agent role's boundary matcher explicitly denies this target, so the rule hard-blocks the action.
`role_out_of_scope`	Role policy	`auth/challenge.py`, `engine/rules/role_boundary.py`, `policy/drift.py`	The action falls outside the boundaries declared for the agent's active role without being on an explicit block list, so it requires authentication (a role elevation).
`policy_source_blocked`	Role policy	`engine/rules/policy_source.py`, `policy/modes.py`	The instruction's originating source is on a higher-authority policy source's block list, so the rule hard-blocks the action.
`policy_source_sensitive`	Role policy	`auth/challenge.py`, `engine/rules/policy_source.py`	The instruction's originating source is classified as sensitive, but not blocked, by the policy source, so it requires authentication.
`unusual_for_workflow`	Subjective layer	`engine/subjective.py`, `policy/drift.py`	The action deviates from this agent's own learned per-workflow behavioral baseline (a running profile of what normal, everyday actions look like for that workflow), raising the subjective verdict.
`unusual_for_deployment`	Subjective layer	`engine/subjective.py`, `policy/drift.py`	The action's surprise score, computed across the universal three-axis algebra, exceeds this deployment's care threshold, raising the subjective verdict.
`confidentiality_sensitive_destination`	Subjective layer	`engine/subjective.py`	An above-threshold action's dominant care dimension is confidentiality, and the destination itself is sensitive.
`irreversible_high_blast`	Subjective layer	`engine/subjective.py`	An above-threshold action's dominant care dimension is irreversibility and blast radius rather than confidentiality: it would be hard to undo and would affect a lot if it went wrong.
`lethal_trifecta`	Subjective layer	`engine/decision_engine.py`, `engine/subjective.py`, `subjective/revealed.py`	The action's algebra shows untrusted-data provenance, access to private data, and an external communication channel all at once, flooring the verdict to `AUTH` (`BLOCK` in Strict/Paranoid). It is the only subjective code allowed onto the hard-block allowlist.
`unclassified_action`	Subjective layer	`engine/subjective.py`, `policy/drift.py`	The action's algebra classification is still effectively unknown by the time the subjective layer runs, so it is flagged rather than treated as benign.
`pii_data_class_egress`	Objective guardrail	`engine/rules/data_classes.py`	The outbound payload contains checksum-valid personal or financial data: a payment card number (issuer prefix plus Luhn check), an IBAN (mod-97), or a dashed US SSN. Because the action has an external destination, every mode requires authentication. Only the class label is recorded, never the matched value.
`smuggled_token_channel`	Token-channel defense	`engine/rules/token_channels.py`	A deterministic, near-zero-false-positive objective token-channel signature matched: tokens smuggled through an unexpected channel. It produces `AUTH` or `BLOCK` depending on severity.
`anomalous_token_pattern`	Token-channel defense	`engine/detectors/token_channels.py`	The subjective token-channel detector found a soft, probabilistic out-of-distribution signal: homoglyph confusables (characters from a different alphabet that look identical to the expected one, like a Cyrillic "а" standing in for a Latin "a"), under-trained glitch fragments, NFKC-normalization smuggling, or anomalous control/private-use characters. It requires authentication.
`oversized_encoded_blob`	Encoded-exfiltration detector	`engine/detectors/base64_blob.py`	The subjective base64-blob detector found a suspiciously large base64-looking payload in a tool argument, a common encode-and-exfiltrate shape (file or secret contents smuggled out as one blob). It checks shape and size only, never decodes, and raises only to `AUTH`.
`multi_step_exfil`	Host-hook containment	`engine/taint_floor.py`, `hosthooks/hookio.py`	This egress action's session already carries taint, a marker meaning a secret was read earlier in the session, so anything sent out afterward is treated as suspect. Even though this call's own payload looks clean, the verdict is raised (`AUTH`, or `BLOCK` in Strict/Paranoid) as a potential cross-call exfiltration.
`confirmed_exfil`	Host-hook containment	`engine/taint_floor.py`, `hosthooks/hookio.py`	An outbound value's keyed-HMAC fingerprint (a one-way hash computed with a locally held key, so the value's identity can be matched without storing or exposing the value itself) matches a secret read earlier in this same session, confirming a read-then-send exfiltration. The rule hard-blocks it in every mode.
`untrusted_value_echo`	Host-hook containment	`engine/taint_floor.py`, `hosthooks/spine.py`, `proxy/executor.py`	A host, URL, or email address in this call's outbound payload matches, by keyed-HMAC fingerprint, a value that first entered this session's context from an untrusted read (a `WebFetch`/`WebSearch` result). Whole-value match only, not flow analysis. Raises to `AUTH`, capped there in every mode (v1). Mail addresses are matched after undoing common `[at]`/`(dot)`/spaced obfuscation, so `user [at] host [dot] com` fingerprints the same as `user@host.com`. This is mechanical, not semantic, so a preposition next to a stray spaced period can occasionally be read as an address that was never actually named. That only ever produces an extra `AUTH` prompt on a later send to that exact address, never a silent allow.
`turn_gate_error`	Turn gate	`engine/decision_engine.py`, `turngate/heuristics.py`, `turngate/hook.py`	The turn gate, either its Tier 0 signature scan or its Tier 1 heuristics, raised while evaluating a turn. It escalates to authentication (fails upward) instead of silently passing.
`instruction_nullification`	Turn gate	`turngate/repeat.py`, `turngate/signatures.py`	A turn's text matched a Tier 0 pattern telling the agent to ignore, disregard, or override its previous instructions. Doberman blocks it outright if issued or found in untrusted content, and requires authentication if merely discussed in typed text.
`authority_override`	Turn gate	`turngate/repeat.py`, `turngate/signatures.py`	A turn's text matched a Tier 0 authority-impersonation, jailbreak/mode-switch, or system-prompt-exfiltration pattern. Doberman blocks it outright if issued or found in untrusted content, and requires authentication if merely discussed.
`secret_export`	Turn gate	`turngate/repeat.py`, `turngate/signatures.py`	A turn's text matched a Tier 0 credential, key, or token export request, for example "send me the API key." Doberman blocks it outright if issued or found in untrusted content, and requires authentication if merely discussed.
`encoded_payload`	Turn gate	`turngate/repeat.py`, `turngate/signatures.py`	A turn contains a long, high-entropy base64/hex run or a punycode host, an encoded-carrier signature. Doberman blocks it in untrusted content and steps it up to authentication in typed content, since a user pasting base64 is plausibly legitimate.
`indirect_injection`	Turn gate	`turngate/repeat.py`, `turngate/signatures.py`	A Tier 0 signature matched inside an untrusted, pasted or tool-fetched, content segment. Doberman treats this as indirect prompt injection and blocks it unconditionally, regardless of issue or mention framing.
`embedded_instruction`	Turn gate	`turngate/heuristics.py`	Tier 1 heuristics detected an agent-directed imperative embedded in an untrusted content segment, escalating the turn to authentication.
`persona_override`	Turn gate	`turngate/heuristics.py`	Tier 1 heuristics matched a persona- or role-override phrase in the turn, requiring authentication.
`obfuscated_content`	Turn gate	`turngate/heuristics.py`	Tier 1 heuristics found obfuscated or sub-threshold encoded content that does not reach the hard `encoded_payload` carrier threshold, requiring authentication.
`urgency_secrecy_framing`	Turn gate	`turngate/heuristics.py`	Tier 1 heuristics matched language that combines urgency and secrecy framing, a common social-engineering pattern, requiring authentication.
`stylometric_outlier`	Turn gate	`turngate/heuristics.py`	The turn's writing style is an extreme statistical outlier for this session and coincides with a sensitive apparent intent, requiring authentication. Style alone never triggers this on its own.
`repeat_after_block`	Turn gate	`turngate/hook.py`, `turngate/repeat.py`	An identical, same-fingerprint turn was resubmitted after being blocked. This converts the automatic block into a one-time `AUTH` challenge for the first repeat instead of blocking again outright.
`turn_blocked_repeatedly`	Turn gate	`turngate/repeat.py`	A resubmitted turn's repeat challenge was already denied once, and the lockout threshold is reached. The rule hard-blocks further resubmission for a cooldown window instead of re-challenging.
`egress_route_divergence`	Egress broker	`engine/rules/destinations.py`	A broker-observed connection for this entity, within a bounded recent window, actually went somewhere that diverges from this rule's static host-trust classification. This retroactively raises the already-computed verdict.
`egress_broker_enforced`	Egress broker	`engine/rules/destinations.py`	A broker proven to enforce egress attests that this exact destination is allowlisted and will itself be enforced at the socket, so the rule contributes `PASS` instead of its usual `AUTH`.
`egress_blocked_by_mode`	Egress broker	`engine/rules/destinations.py`	In Paranoid mode only, a broker proven to enforce egress attests that this exact destination is not allowlisted and will itself drop it at the socket, so the rule hard-blocks instead of its usual `AUTH`. This code is dormant in every other mode, and with no broker present.
`anomalous_egress_velocity`	Egress broker	`engine/rules/destinations.py`	A bounded, in-memory per-entity velocity tracker detected a burst, volume, or fan-out anomaly across this entity's broker-observed connections in the same recent window `egress_route_divergence` uses. This retroactively raises the already-computed verdict.
`artifact_digest_mismatch`	Artifact digest verification	`proxy/executor.py`	A pinned expected sha256 digest exists for a previously fetched identity, and the freshly returned tool-result content's digest disagrees with it. The result is withheld from the agent post-fetch.
`correlated_trifecta`	Session correlator	`engine/correlator.py`	This session's recent decision history shows an untrusted-provenance ingress and a sensitive or secret read as separate earlier calls, and the current action is an external egress: a lethal trifecta assembled across calls rather than within one.
`correlated_destructive_flow`	Session correlator	`engine/correlator.py`	This session's recent decision history shows a broad read or enumeration and a shell command as separate earlier calls, and the current action is an external egress: a possible archive-then-exfiltrate flow.
`raw_socket_channel`	Objective guardrail	`engine/rules/commands.py`	A shell command opens a raw network channel outside the normal HTTP/tool egress path: a `/dev/tcp`/`/dev/udp` redirection target, netcat/ncat/socat used in its exec-on-connect (reverse/bind-shell) form, or any `openssl s_client` invocation (a TLS client connection, whatever flag names the target). Detection reasons about command shape only and is deliberately narrow to keep the false-positive rate near zero. There are two tiers: the exec-on-connect subset (a socket wired to command execution, such as `nc`/`ncat` `-e`/`--sh-exec`, socat `EXEC:`/`SYSTEM:`, or an interpreter payload that opens a socket AND spawns a subprocess/shell) is an unambiguous reverse/bind shell and BLOCKs. The other shapes (`/dev/tcp`/`/dev/udp` redirection, a port probe, `openssl s_client`, a bare inline socket) raise only to `AUTH`.
`verification_bypass_flag`	Verification integrity	`engine/rules/commands.py`	A `git commit` command carries `--no-verify`, `--no-gpg-sign`, or the short alias `-n` (including combined short flags like `-an`), skipping the commit's pre-commit/pre-push hooks or its cryptographic signature. This is a narrower, dedicated code, never `destructive_command`, so it can never sit on the mode-independent hard-block floor.
`test_file_removal`	Verification integrity	`engine/rules/paths.py`	The target of a `file_delete` action, or of a `file_write`/`file_delete` action whose tool name contains "rename"/"move", matches a test-file glob (`test_.py`, `tests/`, `.test.js`, `.test.tsx`, `.spec.mjs`, etc.). This is another shape of an agent quietly disabling its own safety net rather than fixing what it flags. The rule is scoped to the action type: an ordinary edit of a test file, or a non-mutating action (e.g. a read) whose tool merely happens to be named "rename"/"move", stays `PASS`.
`dependency_known_malicious`	Objective guardrail	`engine/rules/dependency_admission.py`	An installed package name (from a `pip`/`npm`/`cargo`/`gem`/`go`/... install command) exactly matches a name on Doberman's bundled known-malicious list, so the rule hard-blocks the install in every mode.
`dependency_name_typosquat`	Objective guardrail	`engine/rules/dependency_admission.py`	An installed package name is exactly one character away (insertion, deletion, or substitution) from a name on Doberman's bundled popular-package list, and is not itself on that list, so it requires authentication before installing (a possible typosquat/slopsquat).

Notes#

Match on the enum name in automation. Values are stable strings, but the name is what the code actually branches on.
Evidence may be redacted before it reaches a log or a UI. Reason codes are the machine-stable half of explainability; the explanation string on a Decision is the human-readable half.
When you add a ReasonCode, update this table in the same PR. tests/unit/test_reason_codes_documented.py fails the build otherwise.