source-control: block-hook-bypass.sh round-3 non-converging findings on PR #568 — comment-# quote-carry regression (highest priority), leading-redirect, coproc header

[kyle-sexton]

Lane: babysit. Triggering PR: #568 (fix/546-block-hook-bypass-false-positive), head 3f7f28a.

Worker fixed 2 rounds of genuine branch-owned regressions (command-prefix peel; fd-dup redirect + control-header peel) but hit the fix-round cap (3, per babysit lane rule 6b) on round 3 without convergence — codex kept re-reviewing every push and surfacing new findings. Per decide-and-defer (#375): shipped what's strictly better (2 fixed rounds, pushed), deferred round 3, filing this tracked follow-up instead of continuing to churn.

Open round-3 P1 findings (still on the live PR, threads left OPEN):

1. [HIGHEST PRIORITY] Comment-# quote-carry regression — a # inside a quoted string can still be mis-treated as a comment start by the detector, changing what's classified as the command word.
2. Leading-redirect form: >f echo x (redirect token appears before the producer word).
3. coproc header not peeled the same way if/elif/while/until/! headers are.

Category: bug. Root question for the next fix round: is a regex-based command-word peel fundamentally unable to keep up with shell grammar edge cases (needs real shell tokenization), or is this a finite enumerable list that a few more peel rules close out? Recommend deciding that before round 4.

[kyle-sexton]

This was generated by AI during triage.

T3 — routing needs-human + wayfind: design. The issue's own text names the real fork: is block-hook-bypass.sh's regex-based command-word peel a finite enumerable list a few more rules close out, or does it need real shell tokenization? That's an architectural choice about the detector's whole approach (maintainability/complexity tradeoff), not a maintainer-vetoable default — genuinely open design space, recommended to decide before round 4 per the issue itself.

[kyle-sexton]

Decision brief (AI-generated for the wayfind: design lane). Read time ~2 min. All code cites are to PR #568 head 3f7f28a3.

Problem

block-hook-bypass.sh decides whether a Bash command is an echo/printf > file write that bypasses the Write/Edit hooks — a decision that requires knowing which token is the command word of each simple command. PR #568 has run three review rounds without converging: each round, codex finds another shell-grammar position the current detector mis-reads, a rule is bolted on, and the next round finds the next one. The issue asks us to settle the architecture before round 4: is command-word detection a finite enumerable list a few more peel rules close out, or does it need real shell tokenization?

Today (verified against 3f7f28a3)

Detection is a two-stage pipeline, not "just regex":

1. strip_literals (L98–186) — a hand-rolled char-by-char lexer that walks the command honoring bash quoting (single/double), carries an open quote across physical lines (L100–102, L150–182), and drops heredoc bodies. This is already a small state machine, not a regex.
2. producer_redirect_bypass (L242–277) — sentinel-protects fd-dup ampersands (L251–253), splits on separators ;\n|&() (L257), then per segment: peels a leading-token allow-list _cmd_prefix (L209) in a loop (L267–270), then requires the segment to start with ^(echo|printf) (_producer_head, L198/L271) and contain a real-file redirect (_echo_file_out, L213/L272).

_cmd_prefix today enumerates 13 header/modifier tokens (command|builtin|exec|env|if|elif|then|else|while|until|do|!|{) + env-assignments. Two structural gaps are already accepted floors with SCOPE comments + tests: group-level redirect { echo x; } > f (L226–231) and external runners nohup/sudo/timeout (L233–241) — both justified as "structurally unusual for LLM output."

The three non-converging round-3 findings (codex on 3f7f28a3, still OPEN):

#	Finding	Shape	Verified
1 — HIGHEST, a REGRESSION	strip_literals' new multi-line open_quote carry records an unmatched quote inside a comment as real quoting: true # " then newline echo x > real.txt exits 0.	Lexer correctness bug in the L150–182 state machine — introduced by this PR (prior line-oriented strip had no cross-line carry). Not fixable by a naive "ignore after #": # opens a comment only at a word boundary, so it must not fire on echo a#b > f or ${v#x}, or it re-introduces the false positives the PR exists to kill.	L166
2 — leading-redirect	Bash allows a redirect before the command word: > real.txt echo x writes the file but the head-anchored `^(echo	printf)` never matches.	Word-position problem, NOT a peel. The maintainer's own note: the leading redirect is the write signal, so peeling it to reach the producer discards exactly what must be detected. Needs a distinct code path.
3 — coproc header	coproc is a bash command header that can precede the producer; it's absent from _cmd_prefix, so coproc echo x > real.txt exits 0.	Pure enumeration gap — one bounded token.	L209

External facts

• Shell grammar is not regular — nested quoting, command substitution, and heredocs are context-free / require a stack — so regex alone provably cannot fully identify a command word. (Well-established; POSIX Shell Command Language grammar and the Bash Reference Manual are the authoritative sources. General principle, not a fresh per-line citation.)
• Bash reserved words are a fixed, closed, grammar-defined set — ! case coproc do done elif else esac fi for function if in select then time until while { } [[ ]] — and coproc is in it (verified against the GNU Bash manual this session). This is the crux: the header-peel dimension is genuinely finite and enumerable — it can be completed once from the authoritative list rather than one keyword per round.

The triage note's fork ("regex vs real tokenization") is a false binary: the script is already a hybrid — a hand-rolled lexer (strip_literals) feeding a regex producer-scan. And the three findings are three different shapes, not three more peel rules: #3 is enumeration, #1 is a lexer bug, #2 is word-position. "A few more peel rules" is false (two of three aren't peels); "rewrite as a real tokenizer" is overkill (the lexer already exists).

---

Options

✅ RECOMMENDED — Option A: Finish the lexer you already have + close the enumeration once + set a STOP rule

Three concrete moves, each landing the finding at its true home:

1. Fix chore: initialize marketplace scaffold #1 in the existing strip_literals state machine (L150–182): add word-boundary-aware unquoted-# comment handling to the same char loop that already tracks quote state (comment starts only at a word boundary; leave a#b and ${v#x} alone). It's a regression this PR caused — it must be code-fixed, and this closes the whole comment class, not one case.
2. Complete the header enumeration in ONE pass from the closed reserved-word set (adds coproc feat: markdown-formatter plugin (pilot migration) #3, and audit time + confirm which reserved words can actually front a bare producer) — instead of another single-token commit that re-triggers a full review round.
3. Give fix: correct plugin-system inaccuracies and harden references #2 its own small "leading file-redirect + producer word in one segment" path (the redirect is the signal, per the maintainer) — or, if judged structurally-unusual-for-LLM, accept-floor it explicitly. Unlike chore: initialize marketplace scaffold #1 it's a fresh gap, not a regression, so a floor is defensible.
4. Adopt a documented threat-model STOP rule: the detector exists to defeat naive LLM bypass, not a determined human crafting > f echo x. Make "structurally unusual for LLM output" (the floor line the script already uses at L226–241) the explicit convergence boundary, so codex findings past it become accepted floors, not fix rounds. This is what makes round 4 the last round.

Tradeoffs: medium effort; root-cause-aligned (no band-aids); adds the convergence mechanism the three rounds have lacked. Reversibility: high (one file). Risk: the #1 word-boundary lexer change needs its own tests to avoid re-introducing false positives.

Option B: Replace the regex producer-scan with a real minimal shell tokenizer

Tokenize each simple command into words / operators / redirects; command word = first word regardless of interspersed redirects. Structurally closes #2 and future position-based edges in one move. Tradeoffs: highest upfront effort, largest new test surface, its own new-bug risk; arguably over-built for the LLM threat model. Reversibility: high (one file) but the most code to unwind. Worth reaching for only if leading-redirect-class edges keep recurring after Option A.

Option C: Keep regex, add just the three fixes, accept future iteration

Lowest effort to ship round 4. Tradeoffs: no STOP rule → the exact three-round churn recurs at round 5/6 as new grammar dimensions surface. The non-convergence is the evidence this alone won't converge. Reversibility: high.

Option D: Status quo + document all three as accepted floors, stop

Rejected for #1: it is a regression this PR introduced — you cannot accept-floor a correctness regression you just shipped. #2/#3 could be floored, but #1 forces a code fix, which collapses D into A.

---

Recommendation: Option A. It answers the issue's fork honestly — the header dimension is finite (close it once from the verified-closed grammar set), while comment-lexing (#1) and word-position (#2) belong in / beside the lexer that already exists, not in the peel list. It fixes the mandatory regression at root, pre-empts the next single-keyword round, and — critically — installs the threat-model STOP rule that converts "codex finds another edge" from a fix round into a documented floor. That is the missing piece across all three rounds.

Cross-links: PR #568 (fix/546-block-hook-bypass-false-positive) · originating false-positive issue #546 · decide-and-defer precedent #375.

[kyle-sexton]

Research brief (control-tower agent, Opus) — operator decision required (security guardrail, Class C).

Grounding for the wayfind: design decision brief already on this issue. That brief lands Option A and traces the three round-3 findings against head 3f7f28a3; this comment independently corroborates its architecture call from the authoritative shell-parsing literature and answers the settling question from primary sources. It changes no labels and does not re-run that brief's option analysis.

Settling question

Can shell command-word identification be done correctly with regex peel rules, or does correct handling of quoting, comments, redirection, and compound-command headers require a real shell tokenizer?

Consensus answer

Literally: no — regex peel rules provably cannot correctly identify a command word. Shell token recognition is not a regular language and is context-sensitive. The authoritative statement is Morbig (Régis-Gianas, Jeannerod, Treinen, A Static Parser for POSIX Shell, SLE 2018), whose authors built a real static POSIX parser and report that "token recognition cannot be specified by regular expressions, lexical analysis depends on the parsing context and the evaluation context, and the shell grammar given in the specification is ambiguous." They needed speculative parsing, parser-state introspection, context-dependent lexing and LR(1) to do it. POSIX Shell Command Language §2.3 (Token Recognition) and §2.2 (Quoting) confirm the mechanism: quoting state and word boundaries are decided character-by-character, so the same bytes tokenize differently by context. The serious tools reflect this — ShellCheck ships a hand-written parser (Parser.hs), not regex.

But the literal answer invites the wrong conclusion ("so use a real tokenizer"), because a real tokenizer does not move the security needle here. Any static command-word detector — regex or full parser — shares the same hard floor: dynamic constructs defeat static detection entirely. echo x | base64 -d | sh, $(printf '>'...), eval "$cmd", an indirect command name in a variable — a complete parser identifies the syntax but still cannot know the effect, so it cannot "correctly" catch these either. This hook's own header already concedes the point: a write inside a command substitution in double quotes "needs a shell parser" and is deliberately left uncaught, with the deny-list plus human oversight named as the real adversarial layers. So "correctly" is unreachable by every static approach against an adversary who is trying. The question therefore collapses from regex vs tokenizer into the cheapest approach that covers the naive-LLM threat surface this guard actually targets — because the only adversary a full tokenizer would additionally beat also clears the dynamic-eval floor and escapes anyway.

The four named dimensions are not symmetric — which is why "a few more peel rules" and "rewrite as a tokenizer" are both wrong, and maps the three OPEN round-3 findings to their true homes:

Dimension	Nature	Correct home
Compound-command headers (finding #3, coproc)	Finite / enumerable. Bash reserved words are a closed, grammar-defined set — verified against the GNU Bash manual: if then elif else fi time for in until while do done case esac coproc select function { } [[ ]] !. coproc and time are both in it.	Regex/peel can close this dimension correctly — in one pass from the closed set, not one keyword per review round.
Redirection (finding #2, leading redirect)	Word-position, not a peel. POSIX grammar: simple_command : cmd_prefix cmd_word cmd_suffix, and cmd_prefix : io_redirect | ... — a redirect legitimately precedes the command word. Peeling the leading redirect to reach the producer discards the very write signal being detected.	A distinct position-aware path (or an explicit accepted floor), not an addition to the prefix list.
Quoting + comments (finding #1, unmatched quote in a comment)	Lexer-level, context-sensitive. # introduces a comment only at a word boundary (POSIX §2.3) — so it must not fire inside echo a#b or ${v#x}. This is exactly the class regex alone cannot decide.	The hand-rolled strip_literals lexer that already exists — this is a correctness regression this PR introduced by carrying quote state across lines.

So the codebase is already a hybrid — a hand-written multi-line lexer feeding a regex producer-scan — and the honest answer to the fork is: complete the finite dimension once, fix the lexer regression in the lexer, and give redirection-position its own treatment; a full tokenizer is not required and would not raise the security floor.

Options (RECOMMENDED first)

✅ RECOMMENDED — Option A: Finish the existing hybrid + close the enumeration once + document a threat-model STOP rule

Mechanically identical to the design brief's Option A already on this issue (fix #1 in the strip_literals state machine with word-boundary-aware comment handling; complete the reserved-word enumeration in one pass incl. coproc, auditing time; give #2 a position-aware path or an explicit floor; adopt "structurally unusual for LLM output" as the documented convergence boundary so future codex edges past it become named floors, not fix rounds). The research grounding strengthens this choice: the reserved-word set really is closed and completable in one pass, and the dynamic-eval floor proves the remaining edges are inherent to any approach — so a documented STOP rule is not a shortcut, it is the correct acknowledgement that static detection has a principled boundary.
Threat-model residual risk: command-substitution writes, eval/decode-pipe-to-shell, indirect command names — all explicitly out of reach and already owned by the deny-list + human oversight layers. Medium effort; one file; root-cause aligned. This is the convergence mechanism the three rounds have lacked.

Option B: Replace the regex producer-scan with a real in-process tokenizer (steelman: mvdan/sh / shfmt)

The strongest form is not ShellCheck (Haskell) or Morbig (OCaml) but mvdan/sh — a single static Go binary with a real, well-tested shell parser. It would structurally close redirection-position (#2) and future position edges in one move.
Reject on merits, not effort: (a) it adds an external binary dependency to a hook whose design deliberately fails open when even jq is missing — a hard parser dependency either regresses that posture or fails open exactly where the guard matters; (b) Git Bash on Windows has no such parser on PATH by default, so it becomes a bundled-binary supply-chain and update burden; (c) most decisively, it does not beat the dynamic-eval floor — the only adversary it additionally catches (a determined human hand-crafting > f echo x) also clears that floor and bypasses anyway. Highest effort, largest new-bug surface, no security gain over A. Reach for it only if leading-redirect-class edges keep recurring after A ships. (Note: driving bash's own parser via eval/-c is a non-starter — arbitrary code execution inside a security hook.)

Option C: Ship just the three point-fixes, no STOP rule

Lowest effort for one more round. Rejected as the documented failure mode: the non-convergence over three rounds is the evidence that point-fixes-without-a-boundary regenerate the churn at round 5/6 as the next grammar dimension surfaces. The STOP rule is the load-bearing difference between A and C.

Impact on PR #568 — park vs proceed

Lean: proceed, with one explicit condition — but the hinge is a genuine operator call, so I am surfacing it rather than deciding it.

Findings #2 and #3 are pre-existing gaps (forms the previous anywhere-in-command detector's narrowing exposed); flooring or deferring them is defensible. Finding #1 is different: it is a bypass regression this PR introduces — the pre-PR line-oriented strip had no cross-line quote carry, so true # " / newline / echo x > real.txt did not exit 0 before this branch. You cannot silently "accept-floor" a regression you are shipping the way you floor a pre-existing gap.

The discriminating question for the operator: does the guard's threat bar tolerate knowingly shipping a narrow, LLM-unlikely, newly-introduced bypass and tracking its fix as #596 convergence work?

• If yes → fix(guardrails): scope block-hook-bypass echo redirect to the actual producer (#546) #568 proceeds; all three findings become source-control: block-hook-bypass.sh round-3 non-converging findings on PR #568 — comment-# quote-carry regression (highest priority), leading-redirect, coproc header #596's convergence set under Option A; finding chore: initialize marketplace scaffold #1 gets an explicit operator acknowledgement in the PR (not a silent "deferred to follow-up"), since it is a self-introduced regression.
• If the bar is "this PR introduces no new bypass" → park fix(guardrails): scope block-hook-bypass echo redirect to the actual producer (#546) #568 until chore: initialize marketplace scaffold #1's word-boundary comment fix lands (it is a lexer change with its own false-positive risk and needs its own tests), then proceed.

Either way #2/#3 ride the same #596 Option-A follow-up. No labels changed by this brief.

---

Sources: Morbig: A Static Parser for POSIX Shell (Régis-Gianas, Jeannerod, Treinen; SLE 2018) — hal.science/hal-01890044 · POSIX Shell Command Language (IEEE Std 1003.1-2017) §2.2 Quoting, §2.3 Token Recognition, §2.10.2 Shell Grammar Rules — pubs.opengroup.org · GNU Bash Reference Manual, Reserved Words — gnu.org/software/bash/manual · ShellCheck Parser.hs (hand-written parser) — github.com/koalaman/shellcheck · mvdan/sh shell parser — github.com/mvdan/sh.

[kyle-sexton]

Update from babysit lane, round 5 on PR #568 (now head 3b1841d4).

All 3 round-3 findings above are now fixed and their threads resolved:

1. Comment-# quote-carry — fixed (part of the PR's original 3-P1 pass, commit 7eadee48).
2. Leading-redirect (>f echo x) — fixed, same commit.
3. coproc header peel — fixed, same commit.

Two more rounds (4 fixed command/exec option-peel + escaped-separator forms at 3b1841d4) also converged cleanly.

Round 5 surfaced a new, related finding — same root phenomenon this issue already asked about:
strip_literals erases a quoted redirect target, not just quote state — so echo x > "$out", echo x > 'out.txt', printf … > "file" all bypass the guard (verified: bash actually writes the file; the detector reports OK). This is the most common real-world redirect form (quoted paths), unlike the round-3/round-4 findings which were edge-case syntax. Classified VALID by this round's worker; reacted and replied on the PR thread (comment 3616677601); deliberately left open rather than auto-fixed, for the same reason this issue already flagged: it's core-detection-logic (a strip_literals-level placeholder fix), a naive patch risks a false-positive on a legitimately-quoted /dev/null-style target, and it needs independent review rather than a 6th autonomous round under the fix-round cap (rule 6b).

This answers your root question, partially: five rounds in, new forms keep surfacing rather than the list closing out — leaning the answer toward "a regex/heuristic peel genuinely can't keep up with shell grammar" rather than "finite enumerable list." Worth deciding whether round 6 attempts the quoted-target fix, or whether this guardrail needs a real shell-tokenization pass (e.g. via bash -n/AST-level parsing instead of string heuristics) as the actual fix instead of another peel rule.