My agent guard blocked its own health check
I build ThumbGate, a check that runs before every Claude Code, Codex or Cursor tool call and blocks the risky ones. Free install:
npx thumbgate init. Pro is $19/month: https://thumbgate.ai/pricing?utm_source=devto&utm_medium=article&utm_campaign=daily-2026-11-19
I build Mac YOLO Safeguards, a set of guards for AI coding agents that run with approvals turned off. One of them is a credential guard: a hook that Claude Code, Codex and Cursor run before every tool call, and that refuses things like keychain reads and copies of browser login stores. Both it and ThumbGate, my other project, are mine, and this post is about a bug that showed up as soon as the hook was switched on.
What happened
The first version of the guard shipped in commit 1319269 on 2026-11-19. It includes a rule called guard-config, whose job is self-protection. An agent must not be able to switch off the thing that is watching it, so the guard refuses install, uninstall and edits to its own settings and to the hook files of each agent.
With the hook live, the guard's own health check, node tools/mac-yolo-credential-guard.js doctor run after a cd, was denied as a guard-config change. So was a grep of ~/.claude/settings.json to see whether the hook was registered. Same rule both times. A read-only look at the guard was being treated as an attack on the guard. The fix is in commit 86f295d, and its message describes both failures.
Why it happened
The original check combined two questions about the whole command string. Did the command contain a write-capable operation or an interpreter anywhere? Did it name the guard anywhere? If both answers were yes, deny.
That sounds careful, and it is, in the way a smoke alarm that goes off when you make toast is careful. node counts as an interpreter, because an interpreter can write any file it names. The path to the guard file contains the guard's name. So node .../mac-yolo-credential-guard.js doctor matched both questions without writing a single byte. The grep of the settings file hit the same pair from the other side.
The deeper problem is the unit of judgment. A command line is not one action. cd /repo && node tool.js doctor 2>&1 | head -20 is three parts, and what matters is what each part does to which file.
The fix
The new check, guardConfigWrite in tools/mac-yolo-credential-guard.js, splits the command into parts and judges each one. The rules from the commit message:
- The guard's own
install,uninstall,fixandwork-folders addorremoveare denied.doctor,check,work-folders listand--helppass. - A shell write is denied only when its target is a guarded path: the config folder, the installed guard, or an agent's hook file. The target can be a redirect, or the destination of
rm,mv,ln,chmod,sed -i,jq -i,teeorcp. - Paths are resolved through any
cdearlier in the same command, socd ~/.cursor && echo {} > hooks.jsonis still caught. - An Edit or Write to a hook file is denied only when it removes the guard's entry. Changing the model name in the same file is fine.
One excerpt shows the shape of it:
// Redirect targets: `> file`, `>> file`, `2> file` (not `2>&1`). for (const m of seg.text.matchAll(/(?:^|[^<>&\d])\d?>>?\s*([^\s>&]\S*)/g)) { const t = resolve(m[1]); if (t && isGuarded(t, false)) return true; } if (DESTRUCTIVE_HEADS.has(seg.head) && paths.some((p) => isGuarded(p, true))) return true; Interpreters keep a conservative rule. An interpreter can write any file it names, so if one appears in the command and a guarded path is also named, the guard still denies. That is why python3 -c "json.dump({}, open('<hook file>', 'w'))" is blocked.
I did not trust myself to get the boundary right by reading it, so the test file tests/test-mac-yolo-credential-guard.js now holds two lists, added in the same commit. Seventeen read-only commands that must pass, including doctor, grep and jq on the hook files, and fifteen write commands that must be denied, including sed -i on the settings file, rm ~/.cursor/hooks.json and the interpreter case above. Both lists run on every change. A guard that blocks too much gets switched off, and a guard that blocks too little is decoration, so each list covers one of those two failures.
The same commit made --help exit 0, since a usage screen should not look like a failure.
Why it matters if you are not me
If you run agents with approvals off, you will write hooks like this. Two lessons transfer.
First, a deny rule written against the whole command string will eventually block you. Agents chain commands with &&, pipes and cd, and a guard that cannot tell doctor from uninstall pushes you toward turning the guard off, which loses everything it was protecting.
Second, a guard that is too noisy trains you to approve things without reading them. The credential guard's design is also meant to fail safe: commit 5bdef17 made a crash inside the guard deny the call, and an invalid settings file only makes it stricter. Those choices only work if the normal path is quiet enough that you leave it on.
How to do it yourself
- Split commands into parts before matching. Break on
;,&&,||and pipes, and look at the program each part runs, not at words that appear anywhere in the line. - Track
cd. Resolve relative paths against the working folder the command will have when that part runs. - Separate reads from writes. Name the write operations you care about (redirects,
rm,mv,cpdestination,sed -i,tee) and check only their targets. - Keep a conservative fallback for interpreters, since they can do anything, and test that fallback on purpose.
- Write a table of commands that must pass next to the table that must fail. If you only test the denials, your guard will drift toward blocking everything.
- Give every denial one line that says why and what to do instead. A guard that explains itself gets fixed. One that does not gets deleted.
Try it
- ThumbGate (free):
npx thumbgate init. It installs in under a minute and blocks the mistakes your agent repeats. https://thumbgate.ai/install?utm_source=devto&utm_medium=article&utm_campaign=daily-2026-11-19 - ThumbGate Pro ($19/month): unlimited blocks per day, a dashboard, and recall and search of past lessons. https://thumbgate.ai/pricing?utm_source=devto&utm_medium=article&utm_campaign=daily-2026-11-19
- Mac YOLO Safeguards (free and open source): the credential guard from this post. https://github.com/IgorGanapolsky/mac-yolo-safeguards. A star helps.
Follow me here for one of these build notes every day.
原文:https://www.a8q9.cn/en/article/my-agent-guard-blocked-its-own-health-check-029a15.html