Set up the guardrail
The central command. Configures how DefenseClaw guards your agent (connector, observe or action mode, scanner, judge, human approval and rule pack), then restarts the gateway.
defenseclaw setup guardrail sets the connector, mode, scanner, judge, human approval and rule pack, then restarts the gateway. Run it interactively the first time; re-run it with flags and --non-interactive for scripts and CI. To build a command in the browser, use the command generator.
The guardrail checks what your agent is about to do (a prompt, a shell command, a tool call) against rules, and answers allow, alert, ask you, or block. It runs in the gateway. The agent's hook only carries the question and the answer.
Watch the interactive flow
defenseclaw setup (a checkbox picker), and it asks no hook fail mode question because the guardrail was already on and the mode did not change: an OSS per-user install with no saved choice fails open and the policy tier decides.The picker's "never block" covers policy findings. Observe still blocks an agent that changes DefenseClaw's own files, such as a copy into ~/.defenseclaw (rule tamper.detector_state_write, with every rule pack). See Two modes.
Same setup, no prompts
defenseclaw setup guardrail \
--non-interactive \
--connector claudecode \
--mode observe \
--scanner-mode local \
--detection-strategy regex_only \
--restart--non-interactive (aliases --accept-defaults and --yes) skips every prompt; missing flags fall back to the wizard defaults. The judge stays off until you pass --judge-model. The saved detection strategy defaults to regex_judge, but with the judge off only the regex lane runs, so the setup summary and guardrail status show the strategy that runs: regex_only.
Prompt-flag mapping
Each row is one wizard prompt, with the default that Enter selects and the flag to use in scripts.
| Prompt (default) | Flag, or how to script it |
|---|---|
| Which agent framework are you using? (first setup only; suggests an agent it finds) | --connector / --agent: claudecode, codex, cursor, devin, copilot, hermes, antigravity, opencode, amp, kiro; on Linux and macOS also openclaw and zeptoclaw. Native Windows refuses those two (they need the guardrail proxy, which Windows does not run) and names the reason. |
| Enable guardrail? (Y) | Implied by running setup. --disable turns the guardrail off. |
| Select mode (observe on first setup, then the current mode) | --mode observe|action. observe records; action enforces. |
| Select hook fail mode (asked only when this run turns the guardrail on or switches between observe and action; Enter keeps the saved choice, or none so the policy tier decides) | No flag on setup guardrail. Use defenseclaw setup <connector> --fail-mode open|closed, defenseclaw init --fail-mode, or defenseclaw guardrail fail-mode open|closed afterwards. |
| Human approval for risky actions? (action mode only; current setting) | --human-approval / --no-human-approval. |
| Approval minimum severity (if HITL is on; HIGH) | --hilt-min-severity high|medium|low|critical, matched case-insensitively. |
| Select engine (local) | --scanner-mode local|remote|both. The wizard offers only local and remote; pass both to run the two together. |
| API endpoint / API key env var name / Timeout (remote scanner only) | --cisco-endpoint, --cisco-api-key-env, --cisco-timeout-ms. Defaults come from the existing cisco_ai_defense config. |
| Select action connector(s) for LLM judge. (a checkbox of the action-mode connectors, unchecked unless the judge already covers them), or Add LLM judge on top of rule scanning? (when there is no action-mode hook connector; current setting) | --judge-model turns the judge on. --detection-strategy regex_only turns it off; there is no --no-judge flag on this command. |
| Use this LLM for the judge? (Y, when an LLM is already configured) | --judge-provider, --judge-model, --judge-api-key-env; --inherit-llm or --inherit-from guardrail|scanners.skill|scanners.mcp|scanners.plugin copies another LLM block. To start from the saved judge settings, use defenseclaw setup llm --role judge --inherit-from guardrail.judge. |
| How should DefenseClaw use the LLM? (proxy connectors only) | --llm-role judge_only|judge_and_agent. Hook connectors always get judge_only; see Hook-based vs proxy-based connectors. |
| Configure fallback models? (N) | No flag. Set guardrail.judge.fallbacks (a list of model ids) in ~/.defenseclaw/config.yaml. |
| Configure advanced options? (N) | Opens the next two prompts. |
| Guardrail proxy port (4000) | --port. Used by the proxy connectors; hook connectors bind no proxy. |
| Use a custom block message? (action mode only) | --block-message. |
For the remote Cisco AI Defense scanner, an unset or empty
cisco_ai_defense.enabled_rules sends no config.enabled_rules list; the AI
Defense connection's own policy applies. A nonempty operator list is sent in
the order configured.
On a multi-connector install, --connector <name> scopes this setup run to that
connector. When --block-message is passed without --connector, setup treats
it as broad operator intent: it updates the shared block message and reconciles
the active connector overrides, so no connector keeps stale block text.
Two wizard choices have no setup guardrail flag. The hook fail mode question appears only when the run turns the guardrail on or changes the mode; defenseclaw init already turns the guardrail on, so a later run that keeps the mode does not ask it. Set the fail mode with defenseclaw setup <connector> --fail-mode or defenseclaw guardrail fail-mode. Judge fallback models live in guardrail.judge.fallbacks in config.yaml.
Redaction has its own workflow
Telemetry redaction is configured per destination with defenseclaw setup redaction, not by this command. See Redaction.
Two modes you have to choose between
You choose how strict it is per agent with a mode:
- Observe records policy findings without enforcing them. Start here. One exception: an agent that changes DefenseClaw's own files, such as a copy into
~/.defenseclaw, is blocked in every mode (ruletamper.detector_state_write, with every rule pack). - Action applies the block and alert levels below.
- Human approval (HITL) is an option in action mode. A risky call below the block level pauses and asks you first, on agents that can ask.
How a tool call is decided
List view for small screens. Use the expand button to open the drawing.
- Gateway rates the callby its worst finding
- At the block level?
- At the block level?CRITICAL by default
- yesBlocked
- noNeeds approval?
- Needs approval?HITL on · HIGH and up
- noAlert or allow
- yesCan this event ask?
- Blockedno prompt
- Can this event ask?native agent prompt
- yesAgent asks the user
- noAlert, no pause
- Alert or allowalerts at MEDIUM and up
- Alert, no pauseconfirm kept in audit
- Agent asks the userapprove runs · deny stops
Block and alert levels
Findings have a severity: CRITICAL, HIGH, MEDIUM or LOW. The rule pack sets the default levels.
| Rule pack | Blocks at | Alerts at | Notes |
|---|---|---|---|
default | CRITICAL | MEDIUM and up | Shipped baseline. |
strict | MEDIUM and up | LOW and up | Blocks more. |
permissive | CRITICAL | HIGH and up | Favors availability. |
With the default pack in action mode:
| Finding | HITL off | HITL on (minimum HIGH) |
|---|---|---|
| CRITICAL | Block | Block |
| HIGH | Alert | Ask (or alert where the agent cannot ask) |
| MEDIUM | Alert | Alert |
| LOW | Allow | Allow |
Human approval is off by default. Its default minimum severity is HIGH. Change the levels with defenseclaw guardrail block-at and alert-at, or per rule pack, connector or profile (Thresholds shows which scope wins).
Fail mode
The hook fail mode decides what happens when the gateway cannot answer (unreachable, bad response, authentication failure). On a per-user install with no saved mode, a gateway that is not running follows the policy tier: the default and permissive policies let the call run with a warning and a record, while the strict policy blocks it. A verified gateway that gives no final decision, an answered failure, or a local failure blocks. On a managed host the default is closed and an administrator can choose open for an outage only. See Fail modes.
Which agents can ask
Only these agent events can pause for your approval. Every other agent applies an alert and keeps raw_action: confirm in the audit log.
| Agent | Event that can ask |
|---|---|
| Claude Code | PreToolUse, in Manual mode only (any other permission mode blocks the call) |
| Antigravity | PreToolUse |
| Amp | tool.call and tool.result in the active foreground thread |
| OpenClaw | before_tool_call |
Codex, Cursor, Hermes, OpenCode, Devin, Kiro and ZeptoClaw cannot ask. GitHub Copilot CLI blocks a confirmation, because its hook does not show whether an approval prompt is available; Copilot in VS Code (Local) uses its own native ask. The capability matrix lists block events and fail-closed support for every agent.
What it does not do
- It cannot see what a child program writes after a command starts. For protected files, add a sandbox or file permissions.
- Observe mode does not enforce policy findings, whatever the levels say. Hook fail mode and proxy availability still apply. One exception: an agent that changes DefenseClaw's own files, such as a copy into
~/.defenseclaw, is blocked in every mode (ruletamper.detector_state_write, with every rule pack). - The TUI does not hold or resume a paused call. Approval happens in the agent.
Connector resolution
When you omit --connector, DefenseClaw resolves it in this order:
- The
--connectorflag. - The
guardrail.connectoran earlier setup run saved. - The
<data_dir>/picked_connectorhint, written byinstall.sh --connector ...and by connector setup, when that agent is installed on this machine. - Otherwise pass
--connector. The interactive wizard suggests an agent it finds on this machine; the non-interactive path does no detection.
Tabs by mode (non-interactive recipes)
defenseclaw setup guardrail --non-interactive --connector claudecode --mode observe --scanner-mode local --restartFindings go to the audit database. Nothing blocks.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action --scanner-mode local --rule-pack default --restartWith the default pack, CRITICAL blocks, HIGH and MEDIUM alert, LOW is allowed.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action --rule-pack default \
--human-approval --hilt-min-severity high --restartHIGH findings are eligible for confirmation. CRITICAL still blocks. See which agents can ask.
defenseclaw keys set DEFENSECLAW_LLM_KEY
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action \
--detection-strategy regex_judge \
--judge-model anthropic/claude-sonnet-4-20250514 \
--judge-api-key-env DEFENSECLAW_LLM_KEY --restartRegex runs first and the judge adjudicates what regex flags. --detection-strategy judge_first flips the order. To cut judge calls on tool calls, put a decision model in front of the judge. Hook connectors are judged only in action mode; --judge-hook-connectors chooses which. A judge verdict goes through block_at and alert_at like a rule finding.
defenseclaw setup guardrail --non-interactive --connector codex --mode action --scanner-mode local --restart
defenseclaw setup decision-model --base-url http://127.0.0.1:8791/v1/systemone --model my-model --connectors codex --pingTool calls go through one of three cascades per connector: rules only (the default); rules, then the decision model with no judge (the connectors in --connectors); or rules, the decision model, then the LLM judge (the connectors the judge covers). Without a judge, a confident allow allows, a confident block blocks, and anything else asks the user where the agent can ask and is a HIGH alert where it cannot. A decision model that is down leaves the rule verdict, as a judge outage does.
defenseclaw setup guardrail --non-interactive --connector claudecode --mode action \
--detection-strategy regex_judge \
--judge-provider bedrock \
--judge-model us.anthropic.claude-sonnet-4-6 \
--judge-bedrock-region us-east-1 \
--judge-bedrock-auth-mode iam_credentials \
--judge-bedrock-access-key-env AWS_ACCESS_KEY_ID \
--judge-bedrock-secret-key-env AWS_SECRET_ACCESS_KEY \
--judge-bedrock-inference-profile us. --restartGive defenseclaw setup llm --provider bedrock the full Bedrock model id, for example us.anthropic.claude-haiku-4-5-20251001-v1:0. The short names haiku-4.5 and luna become their full ids, and setup refuses any other name that is not a Bedrock model id. Without --bedrock-region, setup saves AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1, and prints which one it used.
When you write a Bedrock model into a config file yourself, for example llm.model or guardrail.judge.llm.model in the managed admin config, write it with or without the bedrock/ prefix: bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0 and us.anthropic.claude-haiku-4-5-20251001-v1:0 both use Bedrock. In 1.0.5 an id without the prefix made the administrator's scan skill report Authentication failed and scan mcp report an analyzer DNS error.
The hook judge works with GPT-5.6 Luna on Bedrock (us.openai.gpt-5.6-luna) as well as with the Anthropic models: it calls Luna through the Bedrock Converse API, as the skill and MCP scans do, and leaves out the sampling temperature the model refuses. In 1.0.5 every hook-time judge call with Luna failed (Bedrock 502) and verify warned judge_failing; hooks kept the rule verdict.
Use --judge-provider vertex_ai with the --judge-vertex-* flags, or --judge-provider azure with the --judge-azure-* flags. For a self-signed endpoint add --judge-tls-ca-cert-file. If the settings are already on a custom provider entry, --judge-instance-name <name> inherits them; role-level flags win field by field. See LLM providers.
A judge on a local model
Lemonade and Gemma 4
For Gemma 4 served by Lemonade's OpenAI-compatible endpoint, the judge can
disable the model's thinking mode so its bounded response contains the
classification. Point base_url at your Lemonade server:
guardrail:
judge:
enabled: true
llm:
provider: openai-compatible
model: gemma-4
base_url: http://127.0.0.1:8000/v1
api_key_env: LEMONADE_API_KEY
extra_body:
chat_template_kwargs:
enable_thinking: falseSet LEMONADE_API_KEY in the environment before starting the gateway;
the OpenAI-compatible client needs a key value even if the local server
does not use it. The option is also available through defenseclaw config set guardrail.judge.extra_body --json '{"chat_template_kwargs":{"enable_thinking":false}}'.
Use defenseclaw config get guardrail.judge.extra_body to inspect it and
defenseclaw config validate to check the saved configuration. It affects
only the judge's OpenAI-compatible chat requests.
A judge on a local model (Ollama, vLLM or LM Studio on your own machine) answers one call at a time, so judge calls queue behind each other. With the judge on, a prompt can start up to three judge calls (prompt injection, exfiltration and PII), each tool result and reply can start a PII call, and the agent's next tool call waits behind them. These settings keep the tool-call judge and stop the other calls:
# ~/.defenseclaw/config.yaml
guardrail:
detection_strategy: regex_judge # the judge reviews what the rules leave open
detection_strategy_prompt: regex_only # prompts get the rules only, no judge calls
detection_strategy_completion: regex_only # tool results and replies: rules only
judge:
enabled: true
tool_injection: true # keep the tool-call judge
hook_connectors: [claudecode] # the hook connectors you want judgedOr with flags: defenseclaw setup guardrail --detection-strategy regex_judge --detection-strategy-prompt regex_only --detection-strategy-completion regex_only plus your usual --judge-* flags. Pass
--detection-strategy-completion every time: when init or setup guardrail turns the judge on for a hook connector, it sets
detection_strategy_completion: regex_judge unless you name a value.
What you get and what you give up:
- Faster turns. Each tool call makes one judge call, and it no longer waits behind the prompt and tool-output calls.
- Prompts and tool output are still checked. The rules still scan every prompt, tool result and reply, and can block them. You lose only the judge's second look at them.
- The tool judge still knows the task. The prompt you type is kept as the session's user intent for the tool judge whatever the prompt strategy is.
- Slow answers keep the rule verdict. A judge call that does not answer
within
guardrail.judge.hook_timeout(8 seconds when unset; 3.4 seconds for a tool call) is dropped, and the hook keeps the rule verdict, so a slow model never blocks by mistake. Raising the timeout gives prompt and tool-output judges more time.
Let tool calls go first
DefenseClaw defaults to one model request at a time when the judge endpoint is
loopback, private, or link local. Public endpoints keep the unlimited default.
You can set the number your model server runs at once (for Ollama, its
OLLAMA_NUM_PARALLEL):
defenseclaw config set guardrail.judge.max_parallel 1
defenseclaw-gateway restartDefenseClaw then sends at most that many judge calls at a time. A tool-call
judge goes ahead of every waiting prompt or tool-output judge, and with 2 or
more it always has one slot kept for it. A tool call then waits at most for
the one judge call already running. Prompt and tool-output judges wait their
turn within their own timeout. A tool call cannot wait long in any case: the
Claude Code and Codex hooks give DefenseClaw about 4 seconds, so a tool-call
judge that has not answered after 3.4 seconds is reported as late and the
rule verdict stands. DefenseClaw cancels its pending model request and records
that cancellation in the judge response. A response received before cancellation
is still recorded.
A judge that answers in time gives the same verdict as before. Set
guardrail.judge.max_parallel to 0 explicitly for no limit, or unset it to
restore the endpoint-based default.
Releases before 1.0.6 refuse this key. Remove it before you go back to one:
defenseclaw config unset guardrail.judge.max_parallel.
When the judge did not answer
When the rules decide a hook check because the judge gave no verdict in
time, DefenseClaw reports it. The verdict stays the rule verdict. The reason is
one of timeout, error, late (the hook answer could not wait longer),
busy (too many hook judge
calls at once) or budget (earlier judge calls of the same hook used its
time). You see it in these places:
- the hook's audit row (
judge_fallbackin its extra fields) and itshook.decisionrecord (defenseclaw.guardrail.judge_fallback); - the counter
defenseclaw.guardrail.judge.fallbacks, by connector and reason; defenseclaw status(Judge fallbacks),defenseclaw-gateway status, the TUI overview and theDetectionrow ofdefenseclaw doctor, per connector, counted since the gateway started its judge.
Every flag
The table follows defenseclaw setup guardrail --help.
Prop
Type
What setup writes
The tree below shows Claude Code on Linux and macOS. On Windows the registered
command runs defenseclaw-hook.exe through a small guarded launcher; the system cmd.exe checks that guard on
events other than PreToolUse. Shell scripts are compatibility assets. See the Claude Code paths.
setup guardrail saves config.yaml. The picked_connector hint in ~/.defenseclaw is written by the connector aliases (defenseclaw setup <connector>) and by install.sh --connector, not by setup guardrail. The gateway writes the connector files when it starts: for Claude Code, the hook scripts under ~/.defenseclaw/hooks/ and the hook entries in ~/.claude/settings.json. A hash-checked backup is stored before edits; teardown restores the file or removes only the DefenseClaw-owned entries. The connector pages list the files each agent uses.
Verify it worked
defenseclaw doctor
defenseclaw status
defenseclaw guardrail status
defenseclaw alerts --limit 25status --json is for automation. guardrail status shows the resolved posture of each connector. alerts --connector <name> filters, --show <n> prints one alert and --json prints the list as JSON. Which commands prompt and which are flag-only is in the interactive vs non-interactive matrix.
Protected-file write proof
The write proof checks command text before a tool runs. It does not see what child programs write. A write inside a script, interpreter or shell built-in that the command only names cannot be fully checked from the command text. A rule that needs the complete action cannot block that inner write; an eligible rule about the complete outer argument list can still block the call in action mode. For protected files, use a sandbox or file permissions as an additional control.
Allow a blocked call
Pick the narrowest option that works. All of them take effect on the next gateway reload, with no restart.
Choose one
| You want to | Use |
|---|---|
| Allow one call, once | Human approval (Ask before risky calls). Works for findings below the block level only. |
| Turn a rule off for one agent | guardrail rule disable |
| Silence one false positive but keep the rule | guardrail suppress add |
| Skip the scan for a tool you vetted | tool allow |
| Log instead of block while you tune | guardrail mode observe |
CRITICAL findings cannot be approved. Change the rule, not the call.
Steps
-
List Claude Code's alerts and note the number of the blocked finding. Show that number to find its rule ID. The
1below is an example; if the finding is older than 25 rows, increase--limitin both commands.defenseclaw alerts --connector claudecode --limit 25 defenseclaw alerts --connector claudecode --limit 25 --show 1The
Rule:line names it, for exampleC2-WEBHOOK-SITE. -
Turn the rule off for one agent.
defenseclaw guardrail rule disable C2-WEBHOOK-SITE --connector claudecodeOK Rule C2-WEBHOOK-SITE is turned off for Claude Code. Saved (config generation 18). The running gateway applies it on its next reload.Or suppress only the matching finding, with a recorded reason:
defenseclaw guardrail suppress add webhook-demo \ --finding C2-WEBHOOK-SITE \ --reason "Documentation example, sends no data" \ --connector claudecodeOK Suppression WEBHOOK-DEMO added for Claude Code. Saved (config generation 19). The running gateway applies it on its next reload. -
Or allow a vetted tool. An allowed tool skips rule scanning, so allow only what you reviewed. Write tools still get a code check.
defenseclaw tool allow Bash --connector claudecode --reason "vetted"[tool] 'Bash' (connector 'claudecode') added to allow list
Check it worked
Run the same call again. No alert appears for it, and defenseclaw alerts --limit 5 shows no new row for the rule.
Undo
defenseclaw guardrail rule enable C2-WEBHOOK-SITE --connector claudecode
defenseclaw guardrail suppress remove WEBHOOK-DEMO --connector claudecode
defenseclaw tool unblock Bash --connector claudecodeChange what a rule matches
To change what a bundled rule matches, copy the pack, edit it, validate it and select it. Do not edit a bundled pack in place.
cp -R ~/.defenseclaw/policies/guardrail/default ~/my-guardrail-pack
defenseclaw guardrail validate-pack ~/my-guardrail-pack
defenseclaw guardrail use-pack ~/my-guardrail-pack --connector claudecodeRule pack valid: "/home/alice/my-guardrail-pack"
rules: 242/246 enabled across 7 files
…
files digest: a86e…b6314d (the guardrail.custom_packs pin)use-pack pins the pack by digest and checks every existing pin of the same pack directory by file identity, so another spelling of the path (a symlink, or a different letter case on a case-insensitive volume) cannot leave a stale pin. use-pack --clear --connector X and guardrail mode --clear --connector X remove the connector's entry when nothing else is set on it, and keep it only when it is what puts the connector on the roster. guardrail mode observe runs the same refusals setup runs for every agent it moves out of action mode, and stops with the reason if one holds in every mode, so a switch can always be undone. If you edit the pack later, the gateway keeps the old policy; defenseclaw doctor fails the Config validation and Rule pack rows and skips Policy until you pin the new files digest (the Rule pack row prints the config set command). Rules and custom packs has the details.
Next
Troubleshooting
Fixes for hooks that do not load and for blocking that is too little or too much.
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 tested 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.
The judge blocks an agent-run configuration command
Cause. With the LLM judge on and the connector in action mode, the judge can block a configuration command the agent runs for you, such as claude mcp add --transport http <name> <url> for a remote MCP server. The judge reads the call as a change to a security control, and the audit log shows a judge-tool-injection block. The judge in action mode is an option you turn on, not the default; with the defaults the command runs. The same command typed in your own terminal is not an agent tool call, so the hook does not check it.
Fix. Add the server outside the agent session: type the same command in your own terminal, or use defenseclaw mcp set <name> --url <url>, which scans the server before it adds it (MCP scanner). If agents must change their own configuration, take the connector off the judge: defenseclaw guardrail judge remove <agent>. The connector keeps its mode and its rule checks. On a managed computer the administrator makes this change.
Check. defenseclaw mcp list lists the server.
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.
Common follow-ups
Quick aliases
Each connector has a setup alias that runs setup guardrail --connector <id> with a smaller, connector-oriented flag set.
User- and group-based policies
Give a directory group, a user, a connector or one agent its own guardrail profile, and see which profile decided.
Multi-connector
One gateway guards several agents at once, each with its own mode.
Changing connectors
Guard a second agent next to the first, replace one with another, or remove one.
Disabling
Turn DefenseClaw off for every agent, check the agent files were restored, and turn it back on.
HITL
Turn on human approval so a confirmable HIGH-severity tool call pauses in the agent and waits for your yes or no.
Turn on blocking
Switch an agent from observe to action.
Thresholds
block_at and alert_at: scopes, precedence, the rule pack's default, and how to read and set them.
Rules and custom packs
Choose a rule pack, pin your own by digest, and tune rules, suppressions and protection packs with guardrail.rules.
Reference: guardrail profiles, LLM providers, fail modes.