fix(guardrails): block-hook-bypass wrongly blocks echo/printf ... >&N as a file-write bypass

[kyle-sexton]

Summary

block-hook-bypass.sh (PreToolUse, guardrails v0.17.3) blocks the extremely common, completely safe shell idiom echo "message" >&2 (and printf ... >&2, and any bare >&N redirect with no explicit leading fd digit) as a "Write/Edit bypass," even though it never touches the filesystem. Root cause identified and a working, test-suite-clean fix verified below — independently re-verified twice (once by a fresh audit subagent, once again while drafting this issue) rather than taken on a single pass's word.

Reproduction (verified, runnable)

This only fires through the actual hook — piping a bare shell command at a terminal does nothing (echo x >&2 just prints x). It requires feeding the hook the same JSON-on-stdin PreToolUse payload Claude Code sends it:

#!/usr/bin/env bash
HOOK="<install>/hooks/block-hook-bypass.sh"
export CLAUDE_PLUGIN_ROOT="<install>"   # the hook sources lib/ relative to this

run_case() {
  local cmd="$1"
  local payload rc
  payload=$(jq -n --arg cmd "$cmd" '{tool_name:"Bash", tool_input:{command:$cmd}}')
  printf '%s' "$payload" | bash "$HOOK" >/tmp/out 2>&1
  rc=$?
  printf '%s (rc=%s): %s\n' "$cmd" "$rc" "$( [[ $rc -eq 2 ]] && echo BLOCKED || echo allowed )"
}

run_case 'echo x >&2'                  # BLOCKED — false positive, never touches a file
run_case 'echo "hello world" >&2'      # BLOCKED — same
run_case "printf '%s' x >&2"           # BLOCKED — same, printf variant
run_case 'echo x 1>&2'                 # allowed — explicit leading fd digit sidesteps a DIFFERENT, unrelated check
run_case 'echo x 2>&1'                 # allowed — same reason
run_case 'echo x > realfile.txt'       # BLOCKED — correct, real write
run_case 'echo x &> realfile.txt'      # BLOCKED — correct, real write (both streams to a file)

Independently reproduced against the installed guardrails 0.17.3 hook, this exact result set, twice.

Root cause

producer_redirect_bypass() neutralizes a real >& redirect before splitting the command into ;/\n/|/&/(/)-delimited segments (so the redirect's own & isn't mistaken for a separator), using a \x01 (SOH) sentinel:

normalized="${normalized//>&/>$soh}"
# ... split into segments on separators ...
normalized="${normalized//"$soh"/&}"   # restore SOH back to a literal &

On bash ≥5.2 (the patsub_replacement shell option, enabled by default since bash 5.2 per bash's own NEWS file and the GNU manual — confirmed on this session's Git-Bash/Cygwin bash 5.3.9 on Windows, and independently confirmed on Ubuntu 24.04's actual bash 5.2.21 — this is not a Windows-only bug), an unquoted, unescaped bare & in the replacement position of ${var//pattern/replacement} means "the text the pattern matched," the same convention sed uses. So ${normalized//"$soh"/&} doesn't insert a literal ampersand — it re-inserts whatever "$soh" matched, i.e. the SOH byte itself. The restore is a no-op by construction, not a silent failure to substitute; the sentinel simply survives, invisibly, into the later regex scan.

Net effect: echo x >&2 becomes, internally, echo x > + (inert SOH byte) + 2 — which the scanner then reads as a bare >2 redirect target, passing the "is this a real file write" check. Quoting ("&") or backslash-escaping (\&) the replacement restores literal-ampersand semantics and fixes it; an unquoted variable holding only & (e.g. ${normalized//"$soh"/$amp} where amp='&') is equally broken — the same-meaning rule applies to the expanded value, not just a bare literal, so "assign it to a variable first" is not a workaround.

Blast radius, precisely scoped: only the bare >&N form (implicit fd 1) is affected. N>&M forms with an explicit leading digit (1>&2, 2>&1) are unaffected by this specific bug, because a separate, unrelated exclusion (the leading-digit check in _echo_file_out/_echo_devnull) already protects them regardless.

Verified fix — exact diff, tested clean against the existing suite

A quote-only fix is NOT sufficient on its own and was verified to reopen a real bypass. Quoting just the sentinel-restore line correctly stops the false positive, but then echo/printf x &>real-file (a genuine file write via bash's both-streams redirect) is silently allowed — verified empirically. The tested, working fix touches 3 lines total:

--- a/hooks/block-hook-bypass.sh
+++ b/hooks/block-hook-bypass.sh
@@ -307,2 +307,2 @@
-_echo_file_out='(^|[^0-9&])>>?[[:space:]]*[^|&>[:space:]]'
-_echo_devnull='(^|[^0-9&])>>?[[:space:]]*/dev/null'
+_echo_file_out='(^|[^0-9])>>?[[:space:]]*[^|&>[:space:]]'
+_echo_devnull='(^|[^0-9])>>?[[:space:]]*/dev/null'
@@ -375,1 +375,1 @@
-  normalized="${normalized//"$soh"/&}"
+  normalized="${normalized//"$soh"/"&"}"

(The $esc-restore line a few lines below, which quotes a space rather than &, was checked and is not affected by patsub_replacement — bare vs. quoted space substitution is byte-identical on this bash. No change needed there; leave it alone.)

Removing & from the two regexes' leading-exclusion class is necessary because the sentinel restore now correctly produces a literal & again — without that change, the now-correctly-restored & in >&file would itself get excluded by the old class, silently reopening the exact bypass the quote fix alone was shown to reopen. Verified: dropping only the _echo_devnull half of this change (leaving _echo_file_out alone) creates a NEW false positive on echo x &>/dev/null — both regexes need the same change together.

Test result: the fixed hook passes the plugin's own existing suite clean, 203/203, plus reproduces every case in the Reproduction section above correctly (false positives now allowed, all genuine-write cases still blocked).

One accepted, honest trade-off — not swept under "pre-existing"

The fix has one narrow, real cost: echo x >&2>file — a glued redirect-then-re-redirect where the trailing >file is a real write to a real file — is blocked by the CURRENT (buggy) hook but is NOT blocked by the fixed hook. Verified directly (both hooks tested side by side against this exact command). This is a regression the fix introduces, not a pre-existing gap it merely fails to close — a maintainer applying this diff should know that one specific glued form goes from over-blocked-by-accident to under-blocked. The already-existing, separate 2>&1>file glued-form gap is unaffected either way (present before and after). Whether this narrow trade-off is acceptable (the fix removes a much more common, much more disruptive false positive at the cost of one uncommon glued form) is a judgment call for whoever owns this hook, not something this report should decide unilaterally.

Test-suite gap

The existing 203-case suite is green today only because no fixture isolates the exact bare >&N-alone shape — adjacent near-miss tests create false confidence that this path is covered. Recommend adding explicit regression fixtures for: echo x >&2 / printf x >&2 (expect: allowed), echo x &>file / printf x &>file (expect: blocked), and — now that it's a known, accepted trade-off — echo x >&2>file (expect: allowed, with a comment noting why).

Suggestion (lower priority)

The block message ("BLOCKED: echo/printf > file write bypasses Write/Edit hooks") discards the form/segment data the hook already computed internally, forcing manual byte-level tracing to diagnose why a specific command was blocked. Including the matched segment/form in the stderr message (not just the telemetry envelope) would make future false-positive triage much faster than what this investigation required.

Severity

CRITICAL — false positive on an extremely common, safe shell idiom, shipping since v0.9.5 (confirmed: the commit that introduced producer_redirect_bypass and the unquoted & restore together is the same commit that bumped to 0.9.5). The fix must be applied as the full 3-line diff, not partially — a partial (quote-only) fix reopens a real bypass, verified.

Provenance

Surfaced by /plugin-quality:audit. Root cause and initial fix diagnosed by a dispatched auditor subagent; independently re-verified against the actual installed hook (both the false-positive claim and the fix's regression-free-ness) by a second, fresh review pass before filing — including catching and correcting the auditor's own draft errors (a malformed/duplicated diff, an overstated "≥5.1" bash-version claim corrected to the verified ≥5.2, and an initial "pre-existing" framing of the >&2>file trade-off corrected to state it plainly as a fix-introduced regression).

[kyle-sexton]

This was generated by AI (triage lane, gate-audit pass — cycle 2 retry, instance melo-lap-001-triage-20260727T125559Z).

Verdict: real, critical, exceptionally well-evidenced — and it stays human-gated for two independent reasons, despite having a verified diff attached.

The report is about as complete as an intake item gets: runnable reproduction against the installed hook, a correctly-identified patsub_replacement root cause with the "assign to a variable first" non-workaround explicitly ruled out, a 3-line diff, and 203/203 on the existing suite, all double-verified. That quality is not what decides the gate here.

1. Security floor. block-hook-bypass.sh is a PreToolUse write-gate. Getting this wrong widens what an agent may write without passing Write/Edit — area: security applies as a hard floor.
2. An open judgment call the report itself declines to make. The fix is a documented regression trade-off: echo x >&2>file goes from blocked to allowed. The body states plainly that whether this is acceptable "is a judgment call for whoever owns this hook, not something this report should decide unilaterally." An agent must not make that call on its behalf.

work-class: structural rather than scoped: three lines, but it changes what a fleet-wide guardrail permits, and it ships a known behavior regression.

For the human who takes this: the diff must be applied whole. The body verifies that a quote-only partial fix reopens a genuine &>file bypass, and that changing _echo_devnull without _echo_file_out creates a new false positive on echo x &>/dev/null. The recommended regression fixtures (bare >&N, &>file, and the accepted >&2>file trade-off) should land with it — the suite is green today only because no fixture isolates this shape.

Labels: priority: critical, work-class: structural, area: security, needs-human, status: needs-decision (removed priority: needs-triage).

[kyle-sexton]

This was generated by AI during triage (gate-audit pass, instance KYLE-DESKTOP-triage-20260729).

Claim takeover

Taking over from instance melo-lap-001-triage-20260727T125559Z, whose lane-claim on this item
expired at 2026-07-29T05:09:11Z. Not contending a live lease.

That instance's gate-audit verdict stands and this pass does not disturb it. Independently reviewed
and concurred: this stays human-gated for the two reasons it gave — a security floor (block-hook-bypass.sh
is a PreToolUse write-gate, so getting it wrong widens what an agent may write without passing
Write/Edit) and an open judgment call the report itself explicitly declines to make. Adding only what
was missing: a fresh reproduction against the current version, and a RECOMMENDED-first framing so the
operator can clear this in one glance.

---

New finding: still reproduces on 0.18.0, not just the reported 0.17.3

The report cites guardrails v0.17.3. This pass reproduced it against the currently-installed
0.18.0 — the newest version in the local plugin cache — on GNU bash 5.3.9(1)-release (x86_64-pc-cygwin),
feeding the hook the same JSON-on-stdin PreToolUse payload Claude Code sends it:

echo x >&2                       -> BLOCKED     <-- false positive
printf '%s' x >&2                -> BLOCKED     <-- false positive
echo x 1>&2                      -> allowed     (explicit leading fd digit; different check)
echo x > realfile.txt            -> BLOCKED     (correct — real write)
echo x &> realfile.txt           -> BLOCKED     (correct — real write)
echo x &>/dev/null               -> allowed

So the defect has survived at least one further release. Every result matches the report's
Reproduction section exactly — this is now three independent reproductions (the original auditor, the
filing re-verification, and this pass), on a newer version than any of them.

Two incidental corroborations from this same session: the hook correctly blocked two genuine
cat > file / echo > file write attempts by this lane, so the guard is live and its true-positive path
works. The bug is narrowly the bare >&N form, exactly as scoped.

---

Decision-ready summary

The question: the fix trades one false positive for one regression. Is that trade acceptable?

Precisely: echo x >&2>file — a glued redirect-then-re-redirect whose trailing >file is a real write —
is blocked by the current (buggy) hook and not blocked by the fixed hook. The report states plainly
that whether this is acceptable "is a judgment call for whoever owns this hook."

✅ RECOMMENDED — Option A: accept the trade-off, apply the full 3-line diff, land the regression fixtures with it

Why the asymmetry favours it:

• What it fixes is common and disruptive. echo "msg" >&2 is the standard idiom for writing to
  stderr — it appears throughout ordinary shell work and in this repo's own scripts. Every occurrence is
  currently blocked, and it has shipped that way since v0.9.5.
• What it regresses is rare. echo x >&2>file is an uncommon glued form, and the already-existing
  2>&1>file glued-form gap is unaffected either way — present before and after. The fix does not open a
  new class of bypass, it widens one narrow, adjacent form of an existing one.
• The status quo is not safe-by-default either. A guard that blocks a ubiquitous safe idiom trains
  operators to work around it, which erodes the guard generally.

Apply it whole. The report verifies that a quote-only partial fix reopens a genuine &>file
bypass, and that changing _echo_devnull without _echo_file_out creates a new false positive on
echo x &>/dev/null. A partial application is worse than no application.

Land with it the recommended regression fixtures — bare >&N (expect allowed), &>file (expect
blocked), and >&2>file (expect allowed, commented with why). The existing 203-case suite is green today
only because no fixture isolates this shape.

Option B: accept the trade-off but close the glued form separately first

Apply the diff and add explicit handling for glued redirect-then-write forms, so neither
>&2>file nor the pre-existing 2>&1>file gap is open.

Trade-off: strictly better coverage and removes the "we knowingly shipped a regression" framing — but
it is a larger, unverified change against a hook where the report's central lesson is that partial and
unverified edits reopen bypasses. The 3-line diff is tested at 203/203; an extension to it is not.

Option C: reject the trade-off — keep the false positive

Not recommended. Preserves a blocked-by-accident glued form at the cost of continuing to block a
ubiquitous safe idiom fleet-wide. If chosen, it should be recorded as a deliberate decision with the
false positive documented, so it stops being rediscovered.

Lower-priority follow-up worth a separate item

The block message discards the form/segment data the hook already computes internally, which is what
made this investigation require manual byte-level tracing. Surfacing the matched segment in the stderr
message (not only the telemetry envelope) would make the next false-positive triage far cheaper.

---

Labels unchanged: needs-human, status: needs-decision, priority: critical, area: security,
work-class: structural. The gate is legitimate; this comment only makes it one-glance clearable.

[kyle-sexton]

This was generated by AI during triage. Gate-audit pass complete for this item; claim released. Left human-gated — the gate is legitimate, and the prior instance's verdict was concurred with rather than replaced.