How the guardrail works

One path from a tool call or prompt to a verdict. Each type of guardrail, what it checks, when it runs, what it costs in time and money, how good it is, and how the layers combine, in observe and action mode, and when one fails.

The guardrail looks at what an agent is about to do, and what it just read, and decides: allow, alert, ask you, or block. It does this in layers. Each layer can only add to what the earlier layers found, except one optional policy that you write yourself.

This page is the map. It lists every type of guardrail, then shows how they combine into one verdict. Each row links to the page that goes deeper.

The path of one decision

findings
answer
finding
action
Tool call, prompt ortool result arrives
1. Ruleslocal, always on
2. System Onedecision model, optional
3. LLM judgeoptional
4. Rego policyyour own, optional
5. CRITICAL floorand admin locks
6. Observe or actionand what the agent can do
Allow, alert, askor block

List view for small screens. Use the expand button to open the drawing.

  1. 1.Tool call, prompt ortool result arrives
    • 1. Rules
  2. 2.1. Ruleslocal, always on
    • findings2. System One
  3. 3.2. System Onedecision model, optional
    • answer3. LLM judge
  4. 4.3. LLM judgeoptional
    • finding4. Rego policy
  5. 5.4. Rego policyyour own, optional
    • action5. CRITICAL floor
  6. 6.5. CRITICAL floorand admin locks
    • 6. Observe or action
  7. 7.6. Observe or actionand what the agent can do
    • Allow, alert, ask
  8. 8.Allow, alert, askor block
The order the layers answer a tool call in. Rules always run. System One and the LLM judge run only when you turn them on. The Rego policy runs only when you set one. The floor and the locks apply last. Observe mode then records the result instead of enforcing it.

The same order is in the gateway code (internal/gateway/cascade.go), and defenseclaw guardrail cascade explain prints what each layer does for one connector.

Types of guardrails

TypeWhat it checksRuns onDefault
Rules (rule packs)Findings from 279 to 299 local rules, depending on the pack, in seven families: commands, sensitive paths, secrets, prompt injection, exfiltration hosts, personal data, agent files. The pack's levels turn findings into block or alert.Prompts, tool calls, tool results, model responsesOn. The default pack.
Shell and PowerShell readersThe effect of a command, not its words: what it reads, writes, deletes, runs or sends, and where. A block needs this proof.Tool callsOn, part of the rules
Secret and PII patternsProvider keys, tokens, private keys, connection strings, card and bank numbers, contact data.Prompts, tool calls, tool resultsOn. The opt-in privacy pack adds more.
Regex, CEL and YARA detectorsThe matchers behind the rules. Your own rules use the same ones. YARA scans MCP tool descriptions.The same surfaces as the rulesOn. Custom rules: none until you add them.
Decision model (System One, Gemini Decision 1)A small fast model answers "allow, confirm or block?" with probabilities.Tool callsOff
LLM judgeA model reads the call, the user's request and recent calls, and reports a finding with a severity.Prompts, tool calls, tool results, model responsesOff
Intent-based checksWhether a call matches what the user asked for: the alignment check (ALIGNMENT-DRIFT) and the send-to-an-unnamed-place check (INTENT-SCOPE-SEND).Tool calls that have a side effect or send dataAlignment check off. Send check records only.
Tool-result checksText in a tool's output that is written to steer the agent (indirect prompt injection), and secrets in it.Tool resultsOn. Alerts in the default pack.
Secret flow trackingA secret the agent read that later reaches a network send, even in a different call.Tool calls and their results, per sessionShadow: records, changes nothing
Protected filesA change to authorized_keys, shell startup files or autostart entries while an agent ran.The file system, after the factOn in the per-user gateway: alert
Rego final-decision policyYour own policy sees every layer's answer and sets the final action within limits you set.Every surfaceOff until you set a policy
Human approvalA risky call below the block level pauses and asks you, in the agent.Tool calls, on agents that can askOff
CRITICAL floor and admin locksA proven CRITICAL finding never ends below the floor. Locks keep a key at the administrator's value.Every decisionFloor: alert. Locks: none.

Where to read more:

Time, cost and how good

The numbers come from the 1.0.10 benchmarks (Guardrail benchmarks). The whole-cascade rows are pooled over 13 public tool-call sets (1,147 attack cases and 4,930 benign cases). The alignment check was scored on nine of those sets. "Benign alerted" is the share of harmless calls that raised an alert. Hook time is per tool call, at the 50th and 95th percentile. A dash means the layer has no score on its own.

TypeTimeCostHow good
Rules, default pack17 ms and 30 msLocal CPU onlyPrecision 0.884, recall 0.212, 0.6% of benign calls alerted, 0.1% blocked
Rules, strict pack17 ms and 30 msLocal CPU onlyPrecision 0.876, recall 0.221, 0.7% alerted, 0.4% blocked
Command readersPart of the rulesLocal CPU onlyOn 7,908 benign commands, no false finding in default or permissive
Secret and PII patternsPart of the rulesLocal CPU onlyEnglish privacy pack F1 89.08%, independent PII holdout F1 96.88%, no false findings on either
Decision model, after the rules209 ms and 363 msAbout USD 0.115 per 1,000 callsRecall 0.907, but 25.8% of benign calls alerted. Do not run it as the only layer after the rules.
Decision model and LLM judge834 ms and 2,905 msAbout USD 0.229 per 1,000 callsPrecision 0.728, recall 0.554, 4.8% of benign calls alerted, F1 0.629
Alignment check, aloneUp to 3 seconds when it asks. A call it asks about takes 580 ms and 1,558 ms.About USD 0.015 per 1,000 callsPrecision 0.722, recall 0.583, 4.9% alerted, F1 0.645
Tool-result checksPart of the rulesLocal CPU only. The judge adds model cost when on.Rules alone: 0.635 recall on AgentDojo results, 0.010 on BIPIA email. With the cascade: 0.973 and 0.913.
Secret flow, protected filesLocal; the file watch checks every 2 secondsNoneNot benchmarked
Rego policy5 ms by default, 50 ms at mostNoneNot benchmarked: it applies your own rules

Read these with the benchmarks page: it lists the data, the build and how to repeat each run. Blocking is rarer than alerting. A block needs a proof and an agent that can block before the tool runs.

What each layer can and cannot change

LayerIt canIt cannot
RulesSet the first verdict. A proven finding at the block level blocks the call.See what a child program writes after a command starts.
System OneAdd a finding. A confident answer from both its probability and its risk score is a CRITICAL block.Lower what the rules found. Block a call the rules already flagged: that call goes to the judge, or asks.
LLM judgeAdd a finding with a severity.Lower the rules' verdict, or a confident System One block. Turning it on never weakens an earlier layer.
Rego policyRaise or lower the action, between the lowest and highest you set.Go below the unknown tier for input DefenseClaw did not read in full, below the CRITICAL floor, or use the network.
CRITICAL floorHold a proven CRITICAL finding at alert or higher.It is not a block by itself; the administrator sets it.
Admin locksKeep a key at the top-level value on a managed host, so a profile or connector cannot weaken it.Hide a locked value: doctor and cascade explain name every value it ignored.

Unsure answers: an unsure System One answer has no verdict of its own. With the judge on, the judge decides, never below the rules' verdict. Without the judge, it asks (or alerts where the agent cannot ask). A call DefenseClaw could not read in full (too long, too deep, too many paths) is judged at least at the unknown tier, never as a silent allow.

The full rules, settings and examples are on Configure the cascade.

Observe and action

  • Observe records every finding and enforces none. Start here. The config default is observe. One exception: a change to DefenseClaw's own files by an agent is blocked in every mode by the strict and managed-strict packs, and raises a HIGH alert in the default and permissive packs.
  • Action applies the block and alert levels. In the default pack, CRITICAL blocks and MEDIUM and above alerts. With human approval on, a HIGH call asks you where the agent can ask.

Only some agents can ask: for example Claude Code (in Manual permission mode only), Antigravity, Amp and OpenClaw. Claude Code in any other permission mode, and GitHub Copilot CLI, block the call instead. The rest get an alert, and the audit log keeps raw_action: confirm. Human approval has the list.

What happens when a layer fails

What failedWhat the call gets
The LLM judge: timeout, error, late answer, busy, or offThe verdict the rules and System One gave without it. A System One question or alert stays. The failure is counted and reported.
The decision model is down or slowThe rule verdict stands. After three failures in a row it is skipped for 30 seconds.
The Rego policy errors or runs out of timeThe call is judged at the unknown tier.
The gateway cannot answer at allThe hook fail mode decides.

Two cases turn a missing judge answer into a refusal, never an allow: an unattended Agent Substrate run and the strict policy (JUDGE-UNAVAILABLE), and, with hook_fail_mode: closed, a call the rules escalated to the judge as CRITICAL.

The hook fail mode is open (the call runs, with a warning and a record) or closed (it blocks):

  • Per user. A saved guardrail.hook_fail_mode wins. With none saved, the default and permissive packs let a call run while the gateway is not running, and the strict pack blocks it. A gateway that took the call and gave no answer in time blocks in every tier, with one exception for ordinary calls on Claude Code and Codex.
  • Managed. closed is the default. An administrator can choose open for a proven outage only.
  • Secure Client. An unset mode is open.
  • By connector. Each connector's result is in the gateway outage table. Fail modes has every case.

How long a decision may take

LayerLimit
RulesLocal, no wait
Decision modeldecision_model.timeout, 1 second by default. In front of the judge, at most a quarter of the time left, about 0.85 seconds.
LLM judgeguardrail.judge.hook_timeout, 8 seconds by default, but a hook that reports progress waits at most 3.4 seconds from when the gateway got the call for the model layers
Alignment checkUp to 3 seconds, never past the hook's answer window. With less than 1 second left it does not ask.
Rego policycascade.policy.timeout_ms, 5 by default, 50 at most

A late model answer never removes a finding. It is ignored, and the verdict that stood stays.

How many calls a host can check each second depends on the OS and the install: see Hook sizing on the support matrix.