Fail modes

DefenseClaw has one persisted connector fail-mode policy plus two environment overrides. The effective connector mode applies consistently to both transport and invalid-response failures.

Controls

Effective behavior

The final row is intentional and important. Hook fail mode governs delivery, authentication, parsing, and response availability. It does not fabricate a policy denial after an internal evaluator panic. Treat that condition as a degraded security incident and inspect gateway health.

Ordered chains follow the same non-weakening rule. A SQLite timeout, closed store, missing canonical session, or integrity conflict can prevent a new chain match, but it cannot turn an independently blocked tool call into allow. An exact unexpired deny receipt can replay its stable denial without emitting duplicate finding telemetry.

Persisted fail mode

Show current global and connector-effective values:

defenseclaw guardrail fail-mode
defenseclaw guardrail status

Set one connector closed:

defenseclaw guardrail fail-mode closed --connector codex --yes
defenseclaw guardrail fail-mode closed --connector claudecode --yes

Omitting --connector writes the broad posture. On a multi-connector install, a broad write reconciles active connector overrides so an old per-connector value cannot silently keep one peer on the prior mode.

The command restarts the gateway and reconciles native hook state by default. --no-restart persists desired state but can leave the running generation on the prior value. guardrail status reports configured and runtime values so that drift is visible.

Connector response shapes

Fail mode can block only where the agent protocol has a block shape:

• Codex can deny/block its declared prompt, tool, permission, post-tool, and stop events. It has no native ask response.
• Claude Code can deny/block its declared prompt, expansion, tool, permission, batch, task, stop, subagent, config, compaction, and elicitation events. PreToolUse also has native ask.
• An already-completed result event cannot undo its original side effect.
• An observation-only event remains observation-only even when fail mode is closed.

See the native Windows connector details or the capability matrix before relying on a specific event.

Strict availability

DEFENSECLAW_STRICT_AVAILABILITY=1 is an unconditional closed override for transport and missing-token failures. It exists for managed or compatibility deployments that must never open during a gateway outage. It does not add a missing hook, convert native OTLP into enforcement, or make an unsupported connector block-capable.

Because a strict outage can make the agent unavailable, use persisted status, gateway monitoring, and a tested restart path before applying it broadly. On native Windows, set normal posture with guardrail fail-mode so setup, doctor, and status can reconcile and report it.

Administrator-managed hooks force the relevant unavailable-home and transport failures closed rather than trusting a user-controlled process environment.

Temporary process override

DEFENSECLAW_FAIL_MODE can replace the persisted mode for one agent process. It is useful only for bounded compatibility diagnosis. It is not the normal policy surface because it can disagree with configuration, status, and a different agent process. Remove the override and use defenseclaw guardrail fail-mode for durable posture.

Environment keys are case-insensitive on Windows. Do not define multiple case-variants with different values.

Reporting and diagnosis

defenseclaw version
defenseclaw-gateway status
defenseclaw status
defenseclaw guardrail status
defenseclaw doctor

# Avoid synthetic telemetry, LLM, and inspection-content probes
defenseclaw doctor --passive

# Machine-readable schema v2 (--json is an alias)
defenseclaw doctor --json-output

Hook delivery and response failures can also be recorded under $DEFENSECLAW_HOME/logs/hook-failures.jsonl; on a packaged native Windows install the pinned default is %USERPROFILE%\.defenseclaw\logs\hook-failures.jsonl. Treat it as sensitive operational data and do not publish the whole file.

Schema-v2 Doctor output keeps health checks/summary separate from repairs/repair_summary. A failed health check or failed/dependency-blocked repair sets the top-level outcome to failed and exits 1; manual, declined, or confirmation-required work remains visible without being counted as a repaired health check. Each repair record includes its stable ID, risk, dependencies, effects, blockers, restart potential, and platform.

If doctor identifies a missing token or token drift, preview its safe repair plan with defenseclaw doctor --fix --dry-run. Dry-run invokes planners only, is always passive, and cannot write or restart anything. --fix-id REPAIR_ID is repeatable and selects the exact repair plus its declared dependencies. A real JSON repair requires --yes; blanket --yes cannot opt into policy or experimental repairs. The real repair runs before the diagnostic pass, so its health summary describes the repaired state.

Doctor may generate a local token, start a stopped managed gateway, or restart a gateway whose in-memory token or subsystem state is stale; it does not overwrite a custom token_env. Generated tokens are stored with mode 0600 on POSIX or a private DACL on Windows and are never printed. An intentional master-token rotation uses defenseclaw setup rotate-token --yes, reconciles all active connectors, and requires each agent to be restarted afterward. Never diagnose auth by printing or comparing token values.

When .env was readable by another local principal, Doctor does not simply tighten permissions around the exposed value. It crosses a verified stop-A/commit-B/start-B boundary and authenticates B before reporting the rotation as repaired. A failed activation does not intentionally revive compromised A. Rotate every other credential that was present in the exposed file separately. Doctor refuses to consume a foreign-owned, attacker-writable, linked/reparsed, non-regular, or oversized .env.

Credential dotenv files cannot set process-control variables such as PATH, dynamic-loader injection variables, connector-home overrides, proxy variables, TLS trust overrides, or DefenseClaw security opt-outs. Supply those through the trusted service environment instead.

For an absent audit database, preview or select the safe recovery explicitly:

defenseclaw doctor --fix --dry-run \
  --fix-id doctor.state.audit-db.initialize

Doctor creates and validates an empty current schema only when the target name is safely absent and gateway inactivity is established. Publication is atomic and no-overwrite on Linux, macOS, and Windows. Existing, corrupt, linked/reparsed, foreign-custody, or ambiguous database state must be restored or migrated; Doctor never erases it.

A missing device identity has a stricter recovery boundary:

# Attended only; do not add --yes
defenseclaw doctor --fix \
  --fix-id doctor.identity.device-key.initialize

The prompt warns that prior pairings cannot be recovered. If approved, Doctor publishes HMAC-bound provenance before exposing a new Ed25519 key. It refuses blanket --yes, an existing key, and any ambiguous continuity evidence.

Unsupported or untested active connector versions are health findings and appear under doctor.connector.compatibility.review in a repair plan. Doctor reports the registered range or interactive vendor/setup guidance. Exact attended selection may refresh bounded local version evidence without telemetry, but never installs, upgrades, downgrades, or launches an unsupported connector workload; unresolved compatibility remains manual/experimental.

DefenseClaw component release drift appears separately under doctor.component.compatibility.review, with authenticated upgrade or trusted reinstall guidance. Doctor does not bypass the upgrade controller by changing components inside its repair transaction.

Repeated optional observability export failures open a per-destination, per-signal circuit for logs, traces, or metrics. Transient and payload-specific failures must reach the bounded threshold, so a single bad payload does not suppress later valid telemetry. Authentication and unsafe-endpoint failures open that signal route immediately. While open, export work for that route is suppressed before adapter and size-estimation work, but mandatory local SQLite, sibling signals, and sibling destinations continue. Doctor reports the bounded failure class and recovery window; it warns for transient/half-open recovery and fails an open authentication, permanent-payload, or unsafe-endpoint circuit. This does not silently edit policy. Repair and reload the destination, or disable the optional route explicitly:

defenseclaw setup observability disable NAME

Legacy connector fields

Fields such as claude_code.fail_mode and codex.fail_mode are legacy policy-layer hints. Generated and native hook runtime behavior comes from guardrail.hook_fail_mode and its per-connector entries. Use the guardrail command and status output; do not hand-edit the legacy fields expecting runtime behavior to change.