Claude Code guardrails

Claude Code guardrails and a spend cap, in CI and headless

Auto mode already screens destructive commands in an interactive session, and this page says so before it says anything else. What it does not do is cap spend, and it is not there when the session did not start in auto mode: claude -p, the Agent SDK and the cloud-provider deployments start in the permissive default mode. Hooks are loaded in all of them. Two commands arm 44 deterministic rules plus a dollar cap that refuses the next tool call once the day is over budget, with no package, no account and no server.

Last updated 16 September 2026

What auto mode already does, and where it does not run

Start with the part that is not ours. On Pro, Max and Team plans the built-in starting permission mode for an interactive session is auto mode, and Anthropic's own documentation describes what it does:

Claude Code also runs git status itself before a command that would discard uncommitted work, such as git reset --hard or rm -rf, and shows the classifier whether staged, modified, or untracked work is present.

Claude Code never lets a permissions.allow rule or a PreToolUse hook that returns "allow" approve an rm or rmdir command that targets a critical path.

The 2.1.183 changelog, dated 20 June 2026, says the same thing about git: destructive git commands (git reset --hard, git checkout -- ., git clean -fd, git stash drop) are blocked when you did not ask to discard local work, and terraform destroy, pulumi destroy and cdk destroy are blocked unless you asked for the specific stack. If an interactive session is the only place you run an agent, you already have most of what a destructive-command guard sells, for free, and this page is not going to pretend otherwise.

Two things are still open, and they are what the rest of this page is about.

One. The classifier is auto mode's, and plenty of runs do not start in auto mode. Anthropic lists claude -p and the Agent SDK under the permissive default mode, along with Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry and Claude Platform on AWS. The headless documentation puts it more bluntly: "For -p, the built-in starting permission mode is Manual on every plan." The documented CI story is a static allowlist, --allowedTools "Bash(npm test)", with no target resolution and no record. Hooks, meanwhile, are read in all of those: "Without --bare, a -p session runs the hooks in a project's .claude/settings.json", and the Agent SDK runs settings-file hooks by default through setting_sources. A rule you wrote is what is left deciding there.

Two. No classifier is a cost control. A -p run reports total_cost_usd when it finishes. That is the invoice, discovered afterwards.

Sources, read 16 September 2026: code.claude.com/docs/en/permission-modes, code.claude.com/docs/en/headless, code.claude.com/docs/en/agent-sdk/hooks, code.claude.com/docs/en/hooks. A starting mode is a starting point; anyone can switch modes mid-session.

A day cap, enforced at the tool boundary

The PreToolUse payload carries transcript_path, and the transcript carries each assistant message's model and token usage. So the hook can price the session it is sitting inside. Provenrail reads the transcript from where it last stopped, prices every new message, adds the delta to a ledger shared across hook processes, and refuses the next tool call once the day is over budget.

pr guard budget 25          # or /guard-budget 25 with no CLI installed
pr guard status             # what is armed, and what has been spent today

There is no default cap. A cap you did not choose is a claim about your money, and the CLI refuses to invent one. What a refusal looks like, verbatim from the engine:

denied  budget.day

Provenrail guardrail budget.day: estimated day spend is $25.5000, over the
$25.0000 cap, so this tool call is refused. Stop here and tell the person what
happened rather than working around it. Raise or remove the cap in
.provenrail.json to continue. Spend is estimated at API list price, and
notional on Pro and Max flat-rate plans.

Crossing the warning line (80% of the cap by default) journals a warning and lets the call through, so the agent gets a chance to wind down rather than stopping mid-edit.

What actually goes wrong

Most guardrail tools, including an earlier version of this one, screen the verb. That is the wrong half of the command. Nobody has ever lost work to the letters rm -rf; they lost it to what came after them. rm -rf .next comes back in twelve seconds. rm -rf ~/ is the end of a laptop. The two are indistinguishable to a pattern, because the difference is not in the text, it is in where the text points.

So this guard resolves the target. A delete inside your repository, under a temp directory, in a package cache or in a build directory runs without a word. A delete of a home directory, a whole disk, a two-segment system path, or a variable that becomes / when it is unset is refused. A delete that merely leaves the project asks.

The same idea runs the git rules. git reset --hard on a tree with nothing uncommitted and nothing unpushed destroys nothing at all, so it is allowed in silence. The rule runs git status --porcelain, checks for commits your remote has not seen, and asks only when there is work here that exists nowhere else.

We measured both halves against one frozen corpus: 36,977 Bash commands pulled from 1,247 real agent sessions, replayed offline with the directory each one actually ran in. The rules that shipped in 0.3.1 interrupted 923 of them and refused 305, and reading the samples was the whole argument for this release: a build directory being cleaned, a coverage file being deleted, a Tailwind class read as a SQL TRUNCATE. The rules in 0.4.0 interrupt 222 and refuse 16, and fifteen of the sixteen refusals are this repository's own adversarial test fixtures, files that contain rm -rf / as a test payload. On 40 commands taken from public data-loss reports, 0.3.1 allowed all 40 and 0.4.0 allows none. You can run the same measurement over your own transcripts: python tools/measure_guard.py, which makes no network call and prints counts and samples to your terminal. Widening the hook to every tool rather than a named list of seven brings the corpus to 56,761 calls of every kind, where 0.4.0 interrupts 273 and refuses 21.

Install

Two commands inside Claude Code, and that is the whole setup:

/plugin marketplace add pofky/provenrail
/plugin install provenrail-guard@provenrail

No package to install, no account, no server, nothing to configure. The plugin carries its own dependency-free engine, so 45 rules are armed on the next tool call your agent makes. Installing a plugin called "guard" is the opt-in; a guard that waits for a config file protects nobody.

No signup, no API key, no network call in the decision path. The verdict is computed locally before anything is sent anywhere, so a guardrail never waits on a server and never fails because one is down.

/guard-status   what is armed, and what it has actually stopped
/guard-card     a summary of what it stopped, safe to paste anywhere
/guard-rules    every rule, including the packs that are off by default

/guard-status leads with what the guard has stopped rather than with what it is configured to watch, because a guardrail that has never fired and one that is silently broken look identical from the outside.

/guard-card prints the same history in a form you can post. What makes it postable is what it leaves out: every command is reduced to its verb and its flags and every operand is dropped, so git reset --hard origin/main becomes git reset --hard and an environment assignment carrying an API key becomes export. The directory is a truncated hash rather than a name. We checked the reduction against all 36,977 commands in the corpus: no path, hostname, URL or key survives it.

Turning it up, or off

Write a .provenrail.json at your repo root. It wins over the defaults completely:

{"policy": {"use": ["git-worktree", "destructive", "database", "cloud",
                    "secrets", "production", "access", "money"]}}

An empty list arms nothing and says so once a day, so a disarmed guard can never quietly look like a working one. You can name a single rule id instead of a whole pack, and add your own rules with a regex.

Making the record into evidence

The plugin keeps a local history of every block and every prompt. That is enough for you to see what happened and not enough to show anybody else, because you could have written it yourself. Installing the CLI upgrades the same file, in the same directory, with no migration:

uv tool install provenrail   # or: pip install provenrail
pr guard receipt             # a signed, hash-chained export of what was blocked
pr verify guard-receipt.json

Prefer not to install a plugin at all? pr guard install writes the same hooks into the project's .claude/settings.json directly, preserving any hooks already there.

Headless and CI

This is the case the plugin install does not cover on its own, and the one the classifier is absent from. pr guard install is the whole setup: Anthropic documents that "without --bare, a -p session runs the hooks in a project's .claude/settings.json", and the Agent SDK loads the same settings hooks by default. Commit that file and every pipeline run decides against the same rules as your laptop.

uv tool install provenrail
pr guard install
pr guard budget 25
claude -p "run the migration" --allowedTools Bash --output-format json

--bare skips settings discovery, and Anthropic says it "will become the default for -p in a future release". When that lands, pass the settings file explicitly with --settings rather than relying on discovery.

What is blocked

Eight rule packs are armed by default with no configuration (fan-out, git-worktree, destructive, database, cloud, secrets, production, access), which is 45 rules. 55 rules across eleven packs are available. Every row below is asserted in the test suite against the default install, so this table cannot drift away from what the code does:

Rules are declared in a .provenrail.json file in the repo, so the policy is reviewable in a pull request like any other code. Nothing is "suspicious by default": if a rule did not declare it, it is not flagged.

Why some things ask instead of deny

This is the part most guardrail tools get wrong. A tool that hard-blocks everything risky gets uninstalled by lunchtime, because half of what it blocks is the work.

Provenrail rules carry an effect. deny stops the call and tells the agent which rule fired. require_oversight turns the call into a Claude Code permission prompt instead, and records your answer as human oversight in the log. Reading .env, running a migration, deploying: these should involve a human, not be impossible.

The distinction matters after the fact too. "The agent was blocked" and "a human approved this" are different facts, and a log that flattens them into one is not evidence of anything.

The receipt

Every decision, allowed, denied, or escalated, is Ed25519 signed and hash-chained to the one before it. Export it:

pr guard receipt
pr verify guard-receipt.json

Change one byte of that file and the verifier exits non-zero and names the broken link. Two independent implementations, a Python CLI and a browser verifier, are held in lockstep by frozen conformance vectors, so verification does not depend on running our code or trusting our servers. You can watch it happen in your own browser on a real record and on a tampered one.

Limits, stated plainly

• A hook is not an unconditional block. Anthropic's hooks documentation says the permissionDecision field on PreToolUse and PermissionRequest hooks "is ignored in bypassPermissions mode, when the classifier hasn't finished running (indicated by pendingClassifier: true), or when the API has denied the call". Under --dangerously-skip-permissions Provenrail journals the decision and tells the agent, and does not stop it. permissions.deny rules are a different mechanism and do block in every mode; a hook is not one of those, and we will not imply it is.
• A hook can only see calls that go through Claude Code's tool boundary. A process that never calls the hooks is not constrained and not recorded. Provenrail never claims completeness, here or anywhere.
• The hook is wired to every tool rather than to a list of names, so an MCP server's method and a Read of a credential file reach the rules. Scope is declared per rule instead, which is why a rule about shell commands does not fire on a document being written, a search query, or a subagent prompt that quotes one.
• The policy is read from the nearest .provenrail.json at or above your working directory, so a monorepo package inherits the repo root's rules. pr guard status prints the exact file it used. If the hooks are wired but nothing is armed, the hook says so once a day rather than allowing in silence.
• If Provenrail is not installed, the plugin's hook exits silently and nothing is blocked or recorded. It warns once a day rather than failing on every tool call. pr guard status always tells you the truth about what is armed.
• A rule matches text. A command written to defeat a pattern (V=-rf; rm $V, a script invoked by name, a delete inside a Python one-liner) is not caught, and this is not a claim we hedge: it is a property of every hook of this kind, ours included. What the target resolution buys is precision on the commands agents actually emit, not immunity to a command written to get past it.
• The path logic is POSIX. A PowerShell or cmd recursive delete cannot be told safe from catastrophic here, so it always asks.
• The git rules run git status in your working directory. If the repository cannot be read for any reason, the answer is "there is work at risk", because a guard that could not look has not checked.
• Per-session blast-radius caps carry their counts in a local state file, so a cap holds across hook processes. That file is local and editable, which makes it a convenience rather than evidence. deny and require_oversight never read it, so editing it cannot unblock anything.

Guardrails reduce the blast radius of a mistake. They are not a security boundary against an adversary with shell access, and nobody should sell them as one.

Questions

Does this slow the agent down?

The decision is a local pattern match with no network call, so it costs milliseconds. Recording is written to a local journal and shipped asynchronously.

Does it work in claude -p and in CI?

Yes, and that is the case it exists for. A -p session runs the hooks in the project's .claude/settings.json unless you pass --bare, and the Agent SDK loads the same settings hooks by default, so pr guard install plus a committed settings file is the setup. The same engine also runs as a Python SDK if you want to wrap tool calls in a loop of your own.

Is it free?

Everything on this page is MIT licensed and free, including for commercial use: the rules, the spend cap, the journal, the signed local receipts and both verifiers. The one paid option is $9 a month for unlimited independent RFC 3161 timestamps on the root of your receipts, which is the part you cannot issue to yourself.

Does anything leave my machine?

Not with pr quickstart. That configures a local sink and no account. Sending records off-box is a separate, explicit step, and it is the step that makes them tamper-evident to a third party.

Can the agent turn the guardrail off?

The hook runs outside the model's context and the model does not get a vote on the verdict. It can, like any process with write access, edit the settings file, and that edit is itself a tool call the guardrail sees.