Fix setup problems

Fixes for DefenseClaw guardrail setup problems - hooks that do not load, stale scripts, a gateway that is down, a rejected rule pack, an agent that is never asked - each with the cause, the fix and a check.

Each entry gives the cause, the fix and a check. If a call was blocked and you want to know why, start with Why was this blocked?. To stop a false block, see Fix a false block.

The agent is not guarded: no events, no blocks

Cause. The agent was open when you ran init, so it never loaded the hooks. Or setup did not run for it.

Fix. Quit and reopen the agent. Then defenseclaw status and defenseclaw doctor. Run defenseclaw setup <connector> if the agent is not listed.

Check. Ask the agent to use a tool; a new event shows in defenseclaw tui within a second or two.

Doctor: Claude Code hooks - ... settings.json not found

Cause. The hooks were never written, or the settings file moved.

Fix. defenseclaw setup claude-code --yes, then restart Claude Code.

Check. defenseclaw doctor shows the hooks row as [PASS].

Doctor: stale generated script

Cause. A hook script was rendered by an older build, or bakes a different fail mode than config.yaml.

Fix. Run the command the row names, for example defenseclaw setup codex --yes --restart or defenseclaw-gateway restart. A script edited by hand shows a generated script is not the one setup rendered and a Hook runtime files FAIL instead: run defenseclaw doctor --fix.

Check. The freshness row clears.

The gateway refuses to start because an agent changed

The message reads <connector>'s agent changed.

Cause. The agent's version changed after DefenseClaw recorded its hook contract.

Fix. defenseclaw setup <connector>, then defenseclaw-gateway restart.

Check. defenseclaw-gateway status shows running.

A connector was switched to observe with a warning

Cause. init could not read its installed version (not probed, or the binary is outside a trusted install prefix), and action mode needs a verified version. A version with no hook contract (below the supported floor or known broken) is not switched to observe: setup, init and quickstart refuse it in both modes (Hook contracts).

Fix. Run the command the warning names: defenseclaw setup trusted-paths add <dir> for a binary outside a trusted prefix, or the setup command it prints to choose action mode again. For a version with no contract, update the agent to a supported version, then run defenseclaw setup <connector>. DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1 overrides the check for exploratory testing only.

Check. defenseclaw doctor shows Connector compatibility as [PASS].

Hook failed: hook exited with code 1 after uninstall

Cause. An agent session stayed open while DefenseClaw was removed.

Fix. Restart the session.

Check. The message no longer appears.

Cowork says "DefenseClaw blocked this: its Claude Code hook script is missing or cannot be run"

Cause. The DefenseClaw plugin that defenseclaw setup cowork added to your Claude account is still installed, but the hook script it runs is gone: defenseclaw uninstall --all, defenseclaw reset, a deleted data folder or a moved home folder. The plugin blocks Cowork tool calls until the script is back or the plugin is removed. On Windows the notice names the hook launcher instead of the script.

Fix. Either install DefenseClaw again and run defenseclaw setup cowork, then upload the new zip. Or remove the plugin: in Claude Desktop open Customize > Plugins, then the ... menu on DefenseClaw, and choose Remove. See Remove the Cowork plugin.

Check. A Cowork tool call runs, or defenseclaw status shows the Cowork row as protected.

Every tool call is blocked while the gateway is down

Cause. The connector runs the strict policy (or the install is managed), whose hooks block while the gateway is not running. With the default or permissive policy an outage lets calls run with a warning instead; an install or upgrade in progress blocks in every policy.

Fix. Start the gateway: defenseclaw-gateway start. If it does not start, defenseclaw doctor names the repair. To let calls run with a warning during an outage, use the default policy: defenseclaw guardrail use-pack default (your decision; hook-failures.jsonl records each unchecked call).

Check. defenseclaw guardrail fail-mode shows each connector's outage mode and policy tier.

The agent says "DefenseClaw is not checking this session"

Cause. This account's gateway is not running (stopped, crashed or not started after a reboot), and the connector runs the default or permissive policy, so its hooks let calls run unchecked and record each one in ~/.defenseclaw/logs/hook-failures.jsonl.

Fix. defenseclaw-gateway start. If it does not start, defenseclaw doctor names the repair. To block calls during an outage instead: defenseclaw guardrail use-pack strict.

Check. defenseclaw-gateway status shows it running; when it starts, defenseclaw alerts lists a guardrail-degraded alert for the calls that ran unchecked.

A custom rule pack is rejected: digest ... does not match

Cause. The pack's files changed after you pinned its digest.

Fix. defenseclaw guardrail validate-pack <dir>; if the change was intended, pin the files digest value it prints (the guardrail.custom_packs pin, not the digest line): defenseclaw config set guardrail.custom_packs.<name>.digest sha256:<files digest>. That works for a pack already registered; register a new pack with defenseclaw guardrail use-pack <name>, or set both its path and digest.

Check. defenseclaw doctor shows Config file (canonical schema valid) and Rule pack as [PASS], and Policy is no longer skipped. Config validation appears only as a failure or warning.

Human approval never asks

Cause. The agent has no native approval prompt. The call takes the connector's fallback right away, and the audit log records that approval was asked for.

Fix. None needed. See which agents can ask on the capability matrix.

Check. The matrix lists the agent's ask support.

Nothing is blocked

Cause. The agent is in observe mode, or the finding is below the block level. The default blocks CRITICAL and only alerts on HIGH and MEDIUM.

Fix. defenseclaw guardrail status. To enforce: defenseclaw guardrail mode action --connector <agent>. To change the level: defenseclaw guardrail block-at HIGH.

Check. defenseclaw alerts --limit 5 shows decision=blocked.