fix(guardrails): block-hook-bypass.sh fails CLOSED on a Windows stdin read stall, blocking valid tool calls with 'hook stdin is not valid JSON'

[kyle-sexton]

Summary

hooks/block-hook-bypass.sh blocked a well-formed, non-bypassing Bash tool call on Windows with:

PreToolUse:Bash hook error:
[.../guardrails/0.29.24/hooks/block-hook-bypass.sh]: BLOCKED: hook stdin is not valid JSON.

The command was a plain read with no redirect, no heredoc, and no interpreter:

jq -r '{installMethod, autoUpdates, numStartups}' "$HOME/.claude.json"

Nothing in it is a hook-bypass form. The block came from stdin buffering, not from the guard's own matching.

Environment

• Windows 11 Pro 26200, Git Bash (MSYS)
• Claude Code 2.1.251, native install
• guardrails 0.29.24

Root cause (from reading the shipped source)

hook::buffer_stdin in hooks/hook-utils.sh reads fd0 in timed slices and treats a bounded stall as fatal. block-hook-bypass.sh lines 77-89:

# hook::buffer_stdin encapsulates the Win32-pipe-safe bounded fd0 read. rc 1
# (empty stdin) skips like the empty-COMMAND guard below; rc 2 (read timed out
# ...) stop. buffer_stdin already printed the BLOCKED reason to stderr.
INPUT=$(hook::buffer_stdin) || {

The loop already acknowledges the Win32 hazard it is compensating for (hook-utils.sh ~line 894):

# ... but stop immediately if what we already hold is a whole JSON
# document. That is the Win32 late-EOF case — the payload arrived, the
# pipe just never closed ...

So the design anticipates a Windows pipe that delivers the payload but never signals EOF. The gap is the case where the payload itself arrives late or partially within the slice bound: hook::json_complete then returns false, the bound expires, and the hook exits non-zero — which Claude Code interprets as a block.

Why this is the wrong failure direction

This hook fails closed. Its sibling failure path deliberately fails open — line 91-95:

# jq is required to parse the tool payload. hook::require_jq fails OPEN

A missing jq lets the call through; a slow pipe does not. Those should agree. A guard that cannot read its own input has learned nothing about the command, so it has no basis to block it. Failing closed here converts a transport flake into a false positive on arbitrary user commands.

This is made much worse by the machine's hook latency: on this host every recorded PreToolUse:Bash duration is >= 19s and 1,778 hook runs hit their timeout over 9 days (tracked separately). A stdin slice bound that is adequate on Linux is routinely exceeded here.

Impact

Arbitrary, entirely legitimate Bash commands are randomly blocked. The message names JSON validity, which points the user at their own command rather than at the hook, so it is hard to diagnose. It is also non-deterministic — re-running the same command usually succeeds.

Proposed fix

1. Fail open on stdin-read failure. rc 2 (bounded read stalled/incomplete) should exit 0 with a stderr notice, matching hook::require_jq's documented fail-open posture, rather than exiting non-zero.
2. Keep rc 1 (genuinely empty stdin) as the existing skip.
3. Reserve a hard block for the case where stdin parsed successfully and the guard actually matched a bypass form.
4. Emit telemetry on the degraded path so silent fail-open is still observable.

Acceptance criteria

• A stalled or incomplete stdin read allows the tool call and logs a notice; it never blocks.
• A genuine bypass form is still blocked when the payload parses.
• A regression test covers a truncated/slow stdin payload and asserts exit 0.
• The same audit is applied to every guardrails hook that calls hook::buffer_stdin — the fail-open/fail-closed decision should be consistent across the set, not per-file.

Sources

• Shipped source: guardrails/0.29.24/hooks/block-hook-bypass.sh (lines 77-95), hooks/hook-utils.sh (hook::buffer_stdin, ~lines 858-905)
• https://code.claude.com/docs/en/hooks (PreToolUse exit-code semantics: non-zero blocks the call)

[kyle-sexton]

Correction: this issue argued against a documented design decision without quoting it. That was unfair to the code and would rightly get the proposal bounced.

My quote of the shipped comment truncated it at "rc 2 (read timed out ...) stop". What block-hook-bypass.sh actually says at that point, in 0.29.24 and at HEAD, is:

FAILS CLOSED — the guard cannot evaluate the tool call, and a silent skip would pass exactly the traffic this guard exists to stop.

So fail-closed here is deliberate and argued, not an oversight, and the asymmetry with hook::require_jq failing open is a considered distinction rather than an inconsistency. The issue should have engaged that rationale head-on. Doing so now.

The counter-argument, stated properly. The recorded rationale is sound for its threat model: an adversarial payload that defeats parsing must not be waved through, because a bypass attempt is exactly what would try that. But the observed failure is a different class of event — a transport flake, not adversarial input:

• The blocked command was jq -r '{installMethod, autoUpdates, numStartups}' "$HOME/.claude.json" — a plain read with no redirect, no heredoc, no interpreter, nothing the guard exists to catch.
• It is non-deterministic: the identical command succeeds on retry. An adversary who can defeat the parser can do so repeatedly; a slow pipe cannot be relied on by an attacker to fail at a chosen moment.
• The trigger is host contention, independently measured in perf(hooks): Windows process-creation tax makes the hook set unusable - 1,778 timeouts / 20.6 hours blocked over 9 days #3508 at a bimodal 180-2,841 ms per no-op spawn under 501 concurrent processes. A stdin slice bound that is generous on Linux is routinely exceeded there.
• A parallel session independently observed the same class of contention-induced false denial from a different guard: two read-only grep commands denied with internal deadline of 10s exceeded, both succeeding on identical retry.

So the question is not "fail open or closed" but "can the two cases be told apart". A revised proposal that respects the recorded rationale:

1. Distinguish stall from malformity. A bounded read that times out with a well-formed prefix or zero bytes is a transport event; a read that completes and yields unparseable content is the adversarial case the comment describes. Only the latter needs to fail closed.
2. Retry once before deciding. A single re-read costs one spawn and removes the entire non-deterministic class, without weakening the adversarial path.
3. If it must stay fail-closed, make it say so. The current message names JSON validity, which points the operator at their own command. BLOCKED: could not read hook input (transport); retry would be diagnosable.
4. Emit telemetry either way, so the rate is observable rather than anecdotal.

Also a precision fix to the original report. I wrote that "Claude Code interprets non-zero as a block". That is wrong: exit 2 blocks; exit 1 is non-blocking for PreToolUse. The shipped code exits 2 on this path, which is why it blocks. (The distinction matters elsewhere — #3528 depends on exit 1 being non-blocking, which is what makes a silent abort there a fail-open.)

None of this changes that a legitimate command was blocked. It changes what a correct fix looks like.

[kyle-sexton]

Claimed by the autonomous worker lane.

• instance: vm-worker-202609050257
• lease expires: 2026-09-05T04:15:00Z (60 min TTL, renewed while the worker is active)
• scope: implement, test, independently review, open a close-linked draft PR. This lane does not merge.

Label resolution caveat: this repository's .work-item-tracker.json has no role_labels map, so agent-ready was resolved by documented default rather than from config. Corroborated by the label's own description ("eligible for autonomous pickup from the frontier"), but flagged here for the record.

---

Generated by Claude Code

[kyle-sexton]

Lease renewed — draft PR open, independent review in progress.

• instance: vm-worker-202609050257
• lease expires: 2026-09-05T04:45:00Z (renewed from 04:15Z)
• draft PR: fix(hook-utils): a hook payload cut short at EOF is a loud allow; a stall stays a block #3740 (claude/3507-block-hook-bypass-stdin, commit f91a4c60)

Held rather than released because the PR is a draft pending independent review, not a completed handoff. The lane's handoff boundary is a review-ready PR; releasing at draft would let another instance claim an item already under review.

Two fresh-context reviewers are auditing with the producer's rationale withheld: one on the security question (the change introduces a new allow-path in a guard whose purpose is blocking bypasses), one on correctness, scope, and validation claims. The PR flips to ready only after their findings are resolved.

---

Generated by Claude Code

[kyle-sexton]

Escalated to the human floor — instance vm-worker-202609050257. Claim released, agent-ready removed, needs-human applied. Draft PR #3740 is open and stays a draft.

This is not a triage error. work-class: scoped was correct and the brief was sound. The escalation is about the fix approach, which turned out to land on a security surface.

What was built

The root cause is real and correctly diagnosed: hook::buffer_stdin folded a truncated-but-well-formed JSON payload into the same rc 2 as non-JSON text (bash reports early EOF and a pipe read error with the same rc 1), so on a starved Windows host every blocking guard denied the call. The fix splits the verdict using jq's own diagnostic: rc 2 (not JSON, still fails closed) and a new rc 3 (cut short, allow).

Two independent reviewers audited it with the producer's rationale withheld. The engineering is clean — sync parity byte-identical across all 17 copies, scope gate-mandated rather than creep, a genuine revert-detecting test, and the validation claims verified rather than taken on trust. Detail in #3740.

Why it needs you

The reviewers agree on every fact and split on the verdict: one says ship with a follow-up, one says this needs a human security decision. They are not disputing evidence — they are disputing whether the tradeoff is acceptable. That judgment is yours.

rc 3 is not forgeable by payload content, but it is reachable by inducing a transport stall, and an agent influences both drivers (payload size, host load). Three properties raise the stakes:

1. It skips every guard, not one. run-guards.sh:107-110 exits 0 before any guard is sourced — all 8 on the Bash lane, including secret scanning and dangerous-git.
2. No durable record on the wired path. The skipped telemetry envelope is only written by standalone block-hook-bypass.sh, which hooks.json never invokes. Headless and CI runs leave nothing behind.
3. No cap. The fail-open is retryable without limit against a guard whose single success is permanent.

The fix is also wider than the defect: the reported incident was the early-EOF arm, but lib/hook-utils.sh:1632-1636 folds in the stall arm too — the one host load most directly drives.

Decision needed

• (a) Narrow it. Keep the stall arm fail-closed; allow only on early-EOF, the arm the incident actually reported. Likely removes the attacker-influenceable vector rather than trading it away, at the cost of still denying some genuine stalls.
• (b) Accept the tradeoff, harden it. Ship the current shape plus telemetry on the dispatcher path and a per-session counter reverting to rc 2 after N cut-short allows.
• (c) Accept as-is and take findings 1–3 as follow-ups.

Option (b)'s telemetry fix is strictly beneficial under any choice; I did not implement it pre-emptively because (a) would change what needs recording.

Not verified on a real Windows Git Bash host — the exact platform in the report. Worktree /home/user/wt-3507 and branch claude/3507-block-hook-bypass-stdin are retained so follow-up commits do not need to rebuild them.

---

Generated by Claude Code

[kyle-sexton]

Owner decision received — narrowing the fix. Re-claimed, needs-human cleared.

The security tradeoff surfaced in review has been decided by the repo owner: keep the stall arm fail-closed, allow only on the early-EOF arm — the one the reported incident actually produced.

Rationale, recorded so the choice is legible later: the attacker-influenceable driver was host load inducing pipe stalls. Narrowing to early-EOF removes that vector rather than trading it away for a bounded-but-permanent fail-open. The accepted cost is that some genuine stalls will still be denied, so #3507's symptom may recur in a narrower band.

Not taken: the alternative option of keeping the wide allow plus dispatcher telemetry and a per-session cap. The session counter and dispatcher-path telemetry belong to that path and are not being added here.

PR #3740 stays a draft while the narrowed diff is built and re-reviewed. Lease extended to 2026-09-05T05:45:00Z.

---

Generated by Claude Code