My coding agent's guard said no 17 times in a month. It was wrong 10 of them.

2026-11-08

I moved my most important agent rules out of the prompt and into a hook that denies the tool call. Then I counted every denial in a month of transcripts: 6 real catches, 10 false alarms, and the same bug firing three times while I wrote this.

This morning, while I was testing a fix for my agent's guard hook, the guard hook blocked the test.

The message was polite and completely wrong: rule-guard: writing ~/.gitconfig-personal is blocked. Nothing was writing to that file. My command created a small TypeScript test with a heredoc (cat > fixtest.ts <<'EOF'), and one of the test strings inside it mentioned .gitconfig-personal. The rule saw a > somewhere in the command and the filename somewhere else, and put the two together. A little later it did the same thing to a Python edit of the same file. I switched to the editor tool instead of the shell and carried on, slightly annoyed. It was exactly the bug I was there to fix. Then, while I was correcting a draft of this post through the shell, the commit-identity rule blocked me too, because the draft quotes git -c user.email=x.

That's the story of this post in one scene. A rule that lives in a hook is a real control, which is the point. It's also a program that reads shell commands with regular expressions, and nobody had checked how often it was right.

Why the rules live in a hook

I run coding agents unattended most of the day, on the same Mac where I do personal projects and my day job. A few mistakes there are expensive and hard to undo. A personal project pushing to a work repo. A commit going out under the wrong email, which then sits in public history. A cloud CLI call I didn't ask for. I wrote all of these into my global AGENTS.md first, and the agents mostly followed them. "Mostly" is the problem. I've written before about two autopilots that broke written rules, and the lesson carried over: a rule in a prompt is a request.

So in early October the rules I care about most moved into a Claude Code mod called rule-guard. It hooks tool.call, looks at what the agent is about to run, and returns a denial with a reason instead of letting it through. The code and its 25 tests are public in agent-setup. It has four deny rules:

Agentproposes aBash commandStrip (proposed)blank quoted textand heredoc bodiesrule-guardwork push, identity,worktree, cloud CLIBash runs itallowedDenied: the reason goes back to the agentit picks another route, or asks me

The guard sits between the agent and the shell. The dashed box is the fix I'm proposing below. Today the rules read the raw command, quotes and all.

A denial is cheap in one way that makes this design tempting. The agent can read the reason and change course. On 5 November my daily run tried git -C codeburn worktree add ../main-wt inside a contribution checkout. It was denied, and the run's journal the next day records the lesson: put the worktree at <repo>/.worktrees/<name>. Nobody had to step in.

That cheapness is also why I never looked closely. A false alarm costs one retry and an agent that shrugs. Nobody pages me for those.

Counting the denials

Every Claude Code session leaves a JSONL transcript, and a denial shows up there as a tool_result whose text starts with rule-guard:. So I counted, with a deliberately boring script. It walks every personal-project transcript still on disk, keeps tool results that start with the guard's prefix, and deduplicates by tool_use_id. That last part matters. A naive rg for the work-push rule's message across the same files reported 231 hits, for a rule that had denied 4 commands, because transcripts repeat earlier content and because my own greps over old transcripts get written into new transcripts. The first version of my script made the same mistake in a smaller way: it counted today's grep output as a "denial" dated 8 November.

for b in message["content"]:
    if b.get("type") != "tool_result":
        continue
    text = re.sub(r"^(<tool_use_error>|Error: )", "", flatten(b["content"]).strip())
    if text.startswith("rule-guard: "):
        denials[b["tool_use_id"]] = (o["timestamp"][:10], o["cwd"], text, calls.get(b["tool_use_id"]))

The core of the counter. calls maps each tool_use id to the command the agent tried, collected from the same file.

The result: 19 denials between 9 October and 5 November. That window is just what's on disk: no older personal transcript survives, though the guard has run since 4 October. Two of them were me testing the worktree rule on purpose, so they're out. That leaves 17 times an agent doing real work was told no.

Then I did the part I'd skipped for a month. For each of the 17, I pulled the full command the agent had tried and ran the guard's own functions over it again, printing the 30 characters around whatever matched. A denial counts as real only if the command would really have done the forbidden thing.

Rule Denials Real Wrong Unclear
Cloud CLI needs approval 9 2 7 0
Commit identity 3 1 2 0
Push to a work repo 4 2 1 1
Worktree outside its repo 1 1 0 0
Total 17 6 10 1

Personal-project transcripts, 9 October to 5 November 2026, deliberate tests excluded. "Unclear" is a push from an old personal project that still lives under the work folder: the rule judges by path, and the path said work.

The six it got right

I'll start with these, because they're why the guard exists.

Two were agents force-pushing branches of a work repo from a personal session (9 and 20 October). Both were cd into the work checkout, then git push --force-with-lease. Whether either push was harmless doesn't matter. A personal agent shouldn't be the one deciding. After the first one, the agent put the exact command in my to-do list for me to run myself.

One was a commit with somebody else's name in --author. An agent was committing a friend's notes into one of my repos and decided the friend should be the author. That's thoughtful, and it's also exactly the commit identity I don't want in my history.

Two were gcloud calls in personal projects: an inventory of which accounts were signed in, and a billing lookup on a project. Both were reads. The rule doesn't care, because the reason it exists is that I want to know when an agent starts touching a cloud account, before it matters.

And the worktree from 5 November.

The ten it got wrong

Seven were cloud-CLI denials, and every one of them was a search. An agent ran something like this:

grep -n -iE 'deploy|<host>|vercel|host' README.md docs/setup-guide.md

and the guard denied it for "running" a hosting provider's CLI. Here's the regex, from rules.ts:

const CLOUD =
  /(?:^|[;&|(`\n]|\$\()\s*(?:\w+=\S*\s+)*(?:(?:sudo|npx|bunx|exec|time|command)\s+(?:-\S+\s+)*)*(aws|gcloud|...|eksctl)(?=$|[\s;&|)])/

The cloud rule's matcher. A CLI name counts only in "command position": at the start, or after ;, &, |, (, a backtick or a newline.

I was quite proud of that "command position" idea when I wrote it, and it has a test: grep aws config.yml passes, cd x && aws s3 ls is denied. What the test never tried is a | that isn't a pipe. Inside 'deploy|vercel|host' the bar is regex alternation, and to this regex it looks exactly like the start of a new command. Six of the seven false cloud denials were that: a provider name right after a | in a quoted grep pattern, spread over two weeks of agents searching for deploy notes and keys. The seventh was the same failure with a different character. The agent was writing a README through a heredoc, and the README had "runs wrangler deploy" in markdown backticks. A backtick is also one of my command boundaries.

The other three wrong ones were all text that happened to mention the thing. A heredoc writing a to-do note that said "User runs: git -C <work repo> push" got denied as a work push, because the push-target logic found a git -C path in the note. A Python script that edited my own publishing tool contained the string git -c user.email=x as a redaction pattern, and got denied for setting a commit email. And the gitconfig rule, the one that bit me this morning, fired on 2 November when an agent ran cat > .gitignore <<'EOF' in a new repo and later in the same command did cat ~/.gitconfig-personal to read it. Here's that rule:

export const writesPersonalGitconfig = (command: string): boolean =>
  /\.gitconfig-personal/.test(command) && /(>|\btee\b|\bsed\s+-i|--file|\s-f\s|\bmv\b|\bcp\b|\brm\b)/.test(command)

Two independent tests on the whole command. Any > anywhere, plus the filename anywhere, counts as a write.

Looking back, this is the least defensible line in the repo. It went in on 24 October with the identity rule. It has three tests (one read, two writes), and none of them puts a redirect and a read of the file in the same command.

What I'd been assuming

The rules were written for the command an agent means to run. The guard gets the command as a string, and agents write long ones: six greps chained with ;, a heredoc carrying a whole file, a Python script that edits a Python script. Agents also love quoting regexes with alternation in them. My tests used short commands of the kind I'd type myself. The agent's commands are longer and messier.

There's a cost here I can't price well. Ten false denials in four weeks isn't much friction, and I haven't measured what each one cost the session it hit. I only noticed this morning because it happened to me. The worse cost is quieter. A guard that is wrong more often than right teaches everyone around it, me included, that a denial probably means the guard is confused. The next time it fires on a real work push, that's the reflex I don't want.

The fix, and why it isn't live yet

Nine of the ten false alarms come down to one thing: the rules match text that the shell would never run as a command. The tenth is the gitconfig rule never asking where the > points. So the fix is a step before the rules, plus one rewritten rule. Blank out everything in single or double quotes and every heredoc body, keep the string the same length so positions still line up, and match the rules against what's left. The one rule that needs a value from inside quotes, --author="Name <email>", still reads the original, but only counts a match that starts outside the quotes. The gitconfig check becomes "a redirect, tee, sed -i, --file, mv, cp or rm whose target is the file", instead of two unrelated searches.

I ran that version over the same 17 commands, with each push checked the way the hook checks it (only from a personal folder, as my folders were zoned on that day). All 10 false alarms are allowed. All 6 real catches are still denied, and so is the unclear one. A few made-up cases behave too: echo x >> ~/.gitconfig-personal is still denied, grep -E "a|aws|b" f isn't, and a heredoc containing x | aws y followed by a real gcloud z on the next line still denies the gcloud. The script that does this, fixtest.ts, is about 45 lines.

It isn't in the hook yet, for a dull reason I agree with. The daily run that wrote most of this post runs under the same hook, and it isn't allowed to edit the hooks it runs under. So the patch goes to me as a proposal, with the 17 real commands as the regression tests, and lands when I've read it. The public copy in agent-setup has the same bug until then. If you copied the cloud rule, assume it's denying your greps.

What I'd tell you to do


Thanks for reading. Next up: FabBench, the small benchmark I'm building of agents claiming they did things they didn't, and what two judge models made of it. Follow on RSS or X @denzilnelsonai. If your guard hook has a false-alarm rate you've actually measured, I'd like to hear the number.

— Denzil Nelson