Claude Code Hooks Fail Open: What onFailure Can't See
My secret-scan hook failed open for 75 days, and onFailure: "block" wouldn't have caught it. I tested my Claude Code gates: what blocks and what gets through.
My secret-scanning hook failed open for 75 days on one of my most common commit shapes. Claude Code's new onFailure: "block" wouldn't have caught it, because the hook ran fine and gave the wrong answer.
A hook is a script Claude Code runs before or after a tool call; a PreToolUse hook can deny the call. When I tested my gates on 12 October 2026, block stopped every hook that crashed, timed out or exited 1, and let through the failures that look like success.
The test was nine broken or misled hooks and one working gate, each run once with the default and once with block: 20 headless sessions, plus a control. Claude Code hooks fail open by default, so without block every crashing hook let the command run. With it, three things still got through: JSON cut off before its closing brace, a hook that couldn't run its own check, and a hook that ran and misread the command.
What does onFailure: "block" change?
The changelog entry for 2.1.295 (8 October 2026) added onFailure: "block" for command and HTTP hooks. The hooks reference states the default it replaces: on most events, "a policy hook with a wrong path or a crashing script lets everything through."
Three details from the reference matter for a gate:
- Exit 1 doesn't block by default. "Without valid JSON on stdout, Claude Code treats exit code 1 as a non-blocking error, even though 1 is the conventional Unix failure code." A hand-written gate that exits 1 on a bad match doesn't block unless
onFailureisblock. Exit 2 always blocks. - Some hooks are out of scope. The field has no effect on
Stop,SubagentStop,TaskCompleted,TeammateIdleor async hooks, and it is documented only forcommandandhttphooks. - The default timeout is 600 seconds for a command hook. A gate with no
timeoutthat hangs holds the tool call for ten minutes beforeblockdoes anything.
Here's the shape of a gate in settings.json. My destructive-command gate has onFailure set and, as of 14 October, no timeout; the timeout below is the one I'm adding:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "node \"$HOME/.claude/hooks/block-destructive.js\"",
"onFailure": "block",
"timeout": 10
}
]
}
]
}
}developersdigest ran six configurations on 2.1.295 on 9 October and got the same core result. I ran the same kinds of failure on my own gates and added three cases they didn't test: truncated JSON, schema-invalid JSON, and a real secret scanner with a staged key.
Test 1: what happens when a hook crashes?
Setup: a scratch git repo, a PreToolUse hook on Bash, and claude -p (2.1.296, Haiku) asked to run touch marker.txt once. If the file exists afterwards, the command ran. User settings were excluded with --setting-sources local, so only the test hook loaded.
| What the hook does | Default | block |
|---|---|---|
| Script path doesn't exist | ran | blocked |
| Exits 1 | ran | blocked |
Sleeps 8 s with timeout: 2 | ran | blocked |
Prints {"hookSpecificOutput": oops} (invalid JSON) | ran | blocked |
Prints valid JSON with permissionDecision: "maybe" | ran | blocked |
Prints {"hookSpecificOutput": {"permissionDecision": and exits 0 (cut off) | ran | ran |
The last row surprised me until I read the parsing rules. Output that starts with { and doesn't end with } is treated as plain text, and the reference says "plain-text stdout from a command hook isn't a failure." A gate that writes half of its deny decision and then exits 0, for example by catching its own error, passes.
Test 2: what happens when a hook runs and gets it wrong?
Setup: copies of my real secret-scan.js and its helper in a scratch directory, a repo with a staged file holding a fake AWS-style access key, and Claude asked to commit. The result is whether the key reached git history.
| Case | Default | block |
|---|---|---|
git commit -m test | refused | refused |
git diff fails inside the hook (simulated) | refused | refused |
| The hook can't work out which repo the command targets (simulated) | committed | committed |
bash -c 'git commit -m test' (12 Oct, before the 14 Oct fix) | committed | committed |
Row 2 is the in-script handling working: the hook couldn't read the diff, so it denied the commit. It checks error, a null status and a non-zero exit as separate cases, which is the first rule in my CLAUDE.md.
Row 3 is a gap I chose and wrote down. When the hook can't work out which repo a command targets, it allows the commit, logs it and names CI's secret scan as the backstop. That exception still stands, by design, and onFailure can't see it.
Row 4 was a bug. On 12 October the hook decided whether a command was a commit with a regex that expected git at the start of a command segment, so a prefix such as bash -c or sudo hid it. Fed directly into the hook, 2 of 8 commit shapes were scanned and 6 skipped it. I fixed it on 14 October, below.
onFailure saw none of rows 2 to 4. In each one the hook exited 0.
75 days of a scanner that wasn't scanning
The worst failure of this hook wasn't in the lab. From the day I shipped it, 9 July 2026, it couldn't resolve the repo when a command started with cd ~/..., because it never expanded the ~. An unresolved repo is one of its written exceptions, so it allowed the commit. My agents write commits in that shape all the time.
I fixed it on 22 September. In the 75 days before that, the hook logged 269 commit and push attempts it let through unscanned, on 24 different days. One attempt can log more than once, so 269 is an upper bound. The hook ran, exited 0 and logged an allowed exception every time, so onFailure had nothing to see.
After the fix, from 22 September to 14 October, 783 commit attempts reached the hook. 75% were scanned. 18% carried the audited skip token, and 7% still couldn't resolve their repo. So about 1 in 4 still reached git without a scan. The skip token is its own story, in my CLAUDE.md post: once an agent saw the override in a deny message, it kept using it. These counts cover all my Claude Code accounts, client work included, as totals only.
The audit that found the rest
On 20 September I had three read-only agents audit my hooks. They found five instances of one failure class, a gate that allows when it can't run its check. The two worth testing on your own setup:
- Prefixed commands. The secret scan skipped commits behind
bash -c,sudoand the like (row 4 above). Fixed on 14 October. Another of my gates has the same kind of gap, and I'll describe it once it's closed. - Unusual config. Gates that allowed an action when they couldn't read part of the repo's git setup. Those are still on my list, so I'm leaving the details out until they're fixed.
On 22 September I fixed two neighbours of the same class: the ~ bug above, and my PR-creation gate, which moved from a regex to a command parser. Both were verified the same day.
All five were still open on 12 October. I re-tested the first end to end (the table above) and re-read the code for the other four. The fix was already in the codebase: base.js has invokesCommand(), a parser that finds a command behind sudo, bash -c and quoted text, and the PR gate used it. On 14 October I moved the secret scan onto the same parser, for commits and pushes, and added tests for a commit behind bash -c and behind sudo. Both pass. The other findings are next.
What would have closed them sooner is a failing test in the hook's own suite. An audit report doesn't block a commit.
What does failing closed cost?
A fail-closed gate blocks good work too. On 9 August 2026 block-destructive.js denied a harmless commit because its message contained "git push origin main". I fixed the parser so quoted text isn't read as a command, and kept the gate as strict.
Every exception has to be written down. My secret scan has three: a logged skip token for test fixtures, the unresolved-repo case from row 3, and a first push whose range can't be resolved. Each is written in the hook with its reason. While testing I found an unwritten fourth: when the hook couldn't parse its own input, it allowed, though the comment above that line said it should fail closed for commits. That was a fail-open bug, and it was mine. Since 14 October it fails closed when the unparsed input mentions a git commit or push, with a test for that case and a control that still allows everything else.
What I'd set up today
- Set
"onFailure": "block"and atimeouton every gate: secrets, destructive commands, merges. Leave formatting and logging hooks on the default. Without atimeout, a hung gate holds the call for the full 600 seconds. - Block with exit 2 or a JSON
deny, never exit 1. - Prefer exit 2 with the reason on stderr. It doesn't depend on stdout, so a half-written JSON object can't turn a deny into a pass. If you use JSON, write it in one call.
- Match commands with a parser, not a regex. Test
sudo,bash -c,timeout,envandxargsforms of every command the gate watches. - Run the lab. It took me under an hour, and this is the whole loop:
# settings.json in a scratch repo holds one PreToolUse hook on Bash
claude -p "Run exactly: touch marker.txt. If blocked, don't retry." \
--setting-sources local --settings ./settings.json \
--allowedTools Bash --model haiku < /dev/null
test -f marker.txt && echo RAN || echo BLOCKEDChange one thing in settings.json per run: a missing path, exit 1, a sleep past the timeout, half a JSON object, then your real gate with the prefixed command. Until you've seen a gate fail, you haven't tested it. The kinds of fail-open code I look for when I review an agent's gate, alongside the other failures agents ship, are in How to Review AI-Generated Code.
- Log every allowed exception with a count you look at weekly. My 75 days were in the log the whole time.
Any gate I install in a client repo gets these ten cases before I hand it over, with the result of each one in the handover notes. That's the Agent Fleet Setup on my services page.
Questions
What does onFailure: "block" do in Claude Code hooks?
It makes a failed command or HTTP hook block the action instead of letting it through. A failure means the hook can't start, times out, exits with a code other than 0 or 2, or prints JSON that can't be parsed or fails validation. The default is "continue". It needs Claude Code 2.1.295 or later, and it has no effect on Stop, SubagentStop, TaskCompleted, TeammateIdle or async hooks.
Are Claude Code hooks fail-open by default?
Yes, on most events. Without onFailure set, a hook that can't start, times out or exits 1 is a non-blocking error and the action goes ahead. In my test on Claude Code 2.1.296, all six broken hooks let the command run. Only exit code 2, or a JSON deny decision, blocks it.
Does onFailure: "block" catch a hook that prints broken JSON?
Only if the output starts with { and ends with }. Output that starts with { but is cut off before the closing brace counts as plain text, which isn't a failure. In my test, a truncated JSON write let the command run even with onFailure set to block.
Is onFailure: "block" enough to make a hook a safe gate?
No. It only sees the hook process. If the hook runs, misreads the command or can't run its own check, and still exits 0, Claude Code records a pass. In my test on 12 October 2026, a staged AWS-style key committed through bash -c went straight through with onFailure set to block. I fixed that hook on 14 October.
Agent Fleet Setup · from €4,000
Want this setup in your repo?
I install the agent harness I run in your repo: project rules, the worktree and dispatch workflow, and review gates your team keeps.
or book a free 30-minute scoping call →