Repository navigation
Description
Problem
block-root-delete-target refuses a valid Bash call that feeds a quoted heredoc to a python or node
program (python3 - <<'EOF', node - <<'EOF') when the program text holds a backtick or $( span
whose text contains ( and a prefilter substring such as rm (in "form"). Typical triggers: a
python string holding a markdown backtick span, or a JS template literal. The refusal is the shared
shfmt one and blames syntax, not the guard:
BLOCKED: the guard reads a command through shfmt and got no parse (shfmt rejects it as bash:
:1:42: a command can only contain words and redirects; encountered(), so it
cannot check this call. Fix the syntax, or install shfmt and jq, then reissue the call.
Bash expands nothing in a <<'EOF' body, Python 3 has no backtick syntax, and a JS backtick is a
template literal, so nothing in that span is a command.
Cause (origin/main 999cb91, guardrails 3.1.5):
- The guard's substitution scan runs on the whole command before its parse, on purpose
(plugins/guardrails/hooks/block-root-delete-target.sh:8191-8218). - The scan treats a quoted heredoc body as data only for the fix(guardrails): block-root-delete-target judges backticks inside a quoted heredoc body #6625 plain-reader shape: the whole
command is onecat,gh pr|issue|api|releaseorgit commit|tag -F -line with nothing after
the body (plugins/guardrails/hooks/block-root-delete-target.sh:6491-6507,
plugins/guardrails/hooks/block-root-delete-target.sh:6547-6593,
plugins/guardrails/hooks/block-root-delete-target.sh:6612-6646,
plugins/guardrails/hooks/block-root-delete-target.sh:6696-6708). Every other quoted body,
including a python or node program, is walked as shell text, so a backtick inside a python
"..."string opens a live substitution
(plugins/guardrails/hooks/block-root-delete-target.sh:6750-6818). - A lifted span is tokenized whenever its text holds a prefilter substring anywhere
(plugins/guardrails/hooks/block-root-delete-target.sh:6533-6545), throughrdt_parseand
shfmt (plugins/guardrails/hooks/block-root-delete-target.sh:5743-5775). shfmt rejects the
prose at the(, andhook::_bps_refuse(lib/hook-utils.sh:4676-4688) prints the generic
message.
That scan of a python or node body is not redundant, though. The parse judges the body as a
program (rdt_interp_check, plugins/guardrails/hooks/block-root-delete-target.sh:4785-4910;
rdt_ix_heredocs, plugins/guardrails/hooks/block-root-delete-target.sh:4912-4965), but it reads
a command-running call only when its argument is a literal
(plugins/guardrails/hooks/block-root-delete-target.sh:5536-5546). A backticked delete handed to
os.system through a variable is refused today only by the scan (Evidence, h1 rows). So the fix
narrows which spans the scan tokenizes in those bodies; it does not skip the bodies.
This issue fixes the false positive. The refusal-wording change first proposed here (name the
guard, say the position is inside a lifted span) moves to the sub-issue below: it edits the shared
lib/hook-utils.sh (20 generated copies) and does not depend on this fix.
Evidence
Verified this pass by piping PreToolUse JSON on stdin to plugins/guardrails/hooks/run-guards.sh
from a git archive extract of origin/main 999cb91, with the full 15-guard Bash row from
plugins/guardrails/hooks/hooks.json (the issue first said 14; block-foreground-wait was added
since). No payload was executed. "Refused" below means exit 2 or a permissionDecision of ask.
Repro and stay-quiet targets (refused on main, should pass):
| Case | Shape |
|---|---|
| c3 | W=wt; F=docs/x.md; python3 -I - <<'EOF', a python string "- Save awaits `the schedule check before the form check (Reviewer 1's race fix)`.\n", EOF, then gh pr view 1 (exit 2, shfmt 1:42) |
| node-tpl | node - <<'EOF' with `the schedule check before the form check (Reviewer 1's race fix)` (exit 2, 1:42) |
| py-dollar-paren | python3 - <<'EOF' with "cost $(the form check (draft))" (exit 2, 1:16) |
| cd-quoted-c3 | cd "$HOME/wt" && python3 - <<'EOF' with the c3 string and print(old) (exit 2) |
| c3-line2 | cd sub on line 1, the c3 heredoc on line 2, gh pr view 1 after (exit 2) |
d3 (c3 with "before the form check " removed, so no prefilter hit in the span) passes on main.
Cases that must stay refused, all refused on main (case files: Plan step 1):
| Group | Cases |
|---|---|
| Shell reads the body | bash <<'EOF', cat <<'EOF' | sh, python3 - <<'EOF' | sh, perl - <<'EOF', unquoted python3 - <<EOF, each with a backticked root delete |
Python or node hands a span to a shell through indirection (refused only by the scan; each -c/-e twin passes on main) |
h1-var-bt-hd: cmd = "echo `rm -rf /`"; os.system(cmd); h1-concat-dp-hd: subprocess.run("echo " + "$(rm -rf /)", shell=True); h1-asyncio-bt-hd: asyncio.create_subprocess_shell("echo `rm -rf /`"); h1-node-var-hd: const c = "echo $(rm -rf /)"; execSync(c) |
| Python output piped to a shell through a compound (refused only by the scan) | m1-grp-bt: { / python3 - <<'EOF' printing a backticked delete / } | sh; m1-while-bt: if true; then ... fi | sh; m2-exec-procsub-bt: exec > >(sh) on line 1 |
The body reaches a shell or a -c program |
m2-bashc-clobber-bt: bash -c sh >|python3 - <<'EOF'; sh -s >|python3 - <<'EOF'; bash -s \; python3 - <<'EOF'; m5-pyIc-stdin-bt: python3 -Ic 'import os,sys; os.system(sys.stdin.read())' <<'EOF'; m4-node-eval-stdin-bt: node --eval '...execSync(readFileSync(0))' - <<'EOF'; m3-fd3-bt: python3 - <<'A' 3<<'B' with A reading fd 3 |
| Interpreter name rebound earlier | python3() { bash; };, node() { bash; };, PATH=/opt/evil:$PATH python3 -, hash -p /bin/sh python3;, cp /bin/sh ~/bin/python3; |
| Interpreter judgment of literals | py-system: os.system('rm -rf /'); rmtree-trailing: W=x; F=y; python3 - <<'EOF' with shutil.rmtree('/') then gh pr view 1; node-exec-tpl: execSync(`rm -rf /`) |
Pre-existing gaps, unchanged by this fix and out of scope: python3() { bash; }; python3 - <<'EOF'
with a plain rm -rf / line passes on main (the parse reads the body as python); python output
piped to a shell passes when nothing in the body holds a deleter word (python3 -c 'print(1)' | sh).
Prototype check: a scratch prototype of the Plan step 2 change (diff below), run over 97 case
files (the tables above, guard-trigger probes, and the stress-test cases) against
block-root-delete-target.sh alone, changed exactly five verdicts: c3, node-tpl, py-dollar-paren,
cd-quoted-c3 and c3-line2, each from refused to pass. Every stay-refused case above stays refused.
Those five also exit 0 from the full 15-guard row on the prototype.
The guard's own test suites were not run on the prototype (the main suite runs past 15 minutes on
this host).
Guard row audit. Each other guard in the Bash row was probed with a python quoted heredoc whose
string holds that guard's own trigger, plain and inside a backtick span: --no-verify,
push --force, reset --hard, gh pr create, commit -m wip, > /tmp/x,
export MSYS_NO_PATHCONV=1, ~/.aws/credentials (with block_credential_read_enabled=true),
gh pr merge, the PR-fix phrase, cd x && git, and until ...; do.
| Guard | Result | Scope |
|---|---|---|
| block-root-delete-target | refuses c3, node-tpl, py-dollar-paren | in |
| block-exported-msys-pathconv | refuses the backtick form only. It is a regex matcher that treats a backtick as command position, and this is a documented deliberate fail-closed residual (plugins/guardrails/hooks/block-exported-msys-pathconv.sh:66-73, pinned by plugins/guardrails/hooks/block-exported-msys-pathconv.test.sh:227-232) |
out: different mechanism, declared residual |
| the other 13 | pass every probe. Their nested parses read -c operands and git alias bodies, never a heredoc body |
out |
block-cross-domain needs a machine-local map that the probe did not have, so its probe was inert.
shfmt v3.14.1 rejects the lifted span text alone at 1:42 and parses the whole c3 command cleanly.
Research
| Claim | Sources fetched this pass | Settles |
|---|---|---|
| Bash does no expansion in a body whose delimiter is quoted | bash(1) Here Documents, https://man7.org/linux/man-pages/man1/bash.1.html ; POSIX 2.7.4, https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html ; local bash 5.3.15 run | the body is data to the shell that reads the command |
Functions run before hashed or PATH commands; hash -p binds a name to a file; aliases need expand_aliases in a non-interactive shell and never apply on their own line; name ( ) is a valid definition |
bash(1) COMMAND EXECUTION, ALIASES, hash; POSIX 2.9.1.4, 2.9.5; local runs |
which earlier words can rebind the interpreter name |
Python 3 removed backticks; python3 - reads the program from stdin; of the short options only -c, -m, -W, -X take an argument |
https://docs.python.org/3/whatsnew/3.0.html ; https://docs.python.org/3/using/cmdline.html (3.15.2); local Python 3.14.3 run (a backtick is a SyntaxError) | python's allowed shapes |
A JS backtick delimits a template literal; node - reads the script from stdin (bare node runs piped stdin too, local run) |
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals ; https://nodejs.org/api/cli.html (v26.13.1) | node's backticks are data |
Perl backticks/qx and Ruby backticks/%x run commands |
https://perldoc.perl.org/perlop ; https://docs.ruby-lang.org/en/master/Kernel.html ; local perl run | perl and ruby keep today's scan |
| shfmt v3.14.1 is the latest release and rejects the span at 1:42 | gh api repos/mvdan/sh/releases/latest (v3.14.1, 2026-09-06); local run |
not a shfmt bug |
| A PreToolUse hook's exit 2 blocks the call and its stderr is the reason the model sees | https://code.claude.com/docs/en/hooks | why the misleading message reaches the agent |
gnu.org returned HTTP 429, so the bash manual was read through its man7.org copy.
Plan
-
Tests first. In
plugins/guardrails/hooks/block-root-delete-target.test.sh, after the
fix(guardrails): block-root-delete-target judges backticks inside a quoted heredoc body #6625 quoted-heredoc block (plugins/guardrails/hooks/block-root-delete-target.test.sh:647-691),
addexpect_bothcases (each runs direct and underrun-guards.sh). Write the root-delete
spelling the way that block already does.- Stay quiet (exit 0; each fails on main): c3 in the prefix-plus-trailing-
ghshape, node-tpl,
py-dollar-paren, cd-quoted-c3, c3-line2. - Stay blocked (pass on main too): every row of the Evidence "must stay refused" table, plus
./python3 -,env python3 -,sudo python3 -,FOO=1 python3 -,python3 -m x,
python3 -X dev,python3 -W error,python3 run.py,node -e 1,node -p 1,
node -r x,node run.js, an opener-line suffix&& true, an opener inside
x=$(python3 - <<'EOF' ...),alias python3=bashaftershopt -s expand_aliases,
eval "$x";and. ./defs.sh;earlier, a python body whose variable holds
`\rm -rf /`, and aruby - <<'EOF'body. Each carries a backticked or$(root
delete in a python or node string (or in the body for a shell or perl or ruby reader). - Run the suite on main and record that exactly the stay-quiet cases fail, in both arms.
- Stay quiet (exit 0; each fails on main): c3 in the prefix-plus-trailing-
-
Fix in
plugins/guardrails/hooks/block-root-delete-target.shonly. Nothing below line 8190
moves: the scan stays ahead of the parse.rdt_hd_interp <text before the opener>, a new predicate besiderdt_hd_reader, accepts a
python or node program heredoc:stmtis the opener line's text before<<, after its last;,&or|. It must match
^[[:blank:]]*(python|python3|python3\.[0-9]+)([[:blank:]]+-[BEIOPqRsSuv]+)*([[:blank:]]+-)?[[:blank:]]*$
or^[[:blank:]]*(node|nodejs)([[:blank:]]+-)?[[:blank:]]*$. Only no-argument python
flags are allowed, and node takes no option, path, script or argument word.before, all command text ahead ofstmt, must hold no\,<,>,{,},(or
). It must not containPATHor the interpreter word, must have nohashorexecword,
and must not matchRDT_LIT_RESERVED_REorRDT_LIT_FORBID_RE
(plugins/guardrails/hooks/block-root-delete-target.sh:6278-6280), applied tobefore
only. The</>rule keeps>|,>&and<&from being read as separators.
- In
rdt_scan_substitutions, add a per-heredochd_interpflag besidehd_quoted.- Set it at the opener when the scan is top level (
nestedempty),pd == 0, no comment is
open (hcmt < 0), the delimiter word matcheshd_word_re(quoted), andrdt_hd_interp
passes. - At the body's newline, clear it unless the opener-line suffix (up to a comment) is all
[[:space:]], so CR counts as blank. - A flagged body is still scanned, nested, with a dynamic
rdt_span_gate=word. The
nothing-follows rule (plugins/guardrails/hooks/block-root-delete-target.sh:6637) keeps
clearinghd_quotedonly.
- Set it at the opener when the scan is top level (
- In
rdt_scan_body, after the existing substring prefilter: whenrdt_span_gateisword
and the span holds no$, tokenize only if its lowercased text matches
(^|[^a-z0-9_])(rm|unlink|rsync|robocopy|worktree|remove|mv|truncate|shred|delete|base64|base32|basenc|xxd|cmd)|of=.
That is a prefilter stem starting a word;\,/, quotes and operators count as word
starts. Then resetrdt_span_gateto empty (local) beforerdt_parse, so deeper readings
are not gated. - Update both header comments
(plugins/guardrails/hooks/block-root-delete-target.sh:6491-6507and
plugins/guardrails/hooks/block-root-delete-target.sh:6635-6637) and the residual list (see
Constraints).
Prototype used for the Evidence (a sketch; finish it to the repo's comment and test standards,
it was not run against the suites):@@ rdt_scan_body, after the prefilter case + if [[ "${rdt_span_gate:-}" == word && "$b" != *'$'* ]]; then + local lb="${b,,}" wre='(^|[^a-z0-9_])(rm|unlink|rsync|robocopy|worktree|remove|mv|truncate|shred|delete|base64|base32|basenc|xxd|cmd)|of=' + [[ "$lb" =~ $wre ]] || return 0 + fi + local rdt_span_gate= @@ new functions beside rdt_hd_reader +rdt_hd_interp() { + local t="$1" pre stmt before w0 + pre="${t##*$'\n'}" + stmt="${pre##*[;&|]}" + before="${t:0:${#t}-${#stmt}}" + if [[ "$stmt" =~ ^[[:blank:]]*(python|python3|python3\.[0-9]+)([[:blank:]]+-[BEIOPqRsSuv]+)*([[:blank:]]+-)?[[:blank:]]*$ ]] || + [[ "$stmt" =~ ^[[:blank:]]*(node|nodejs)([[:blank:]]+-)?[[:blank:]]*$ ]]; then + w0="${BASH_REMATCH[1]}" + else + return 1 + fi + [[ "$before" == *[\\\<\>\{\}\(\)]* || "$before" == *PATH* || "$before" == *"$w0"* ]] && return 1 + local wre='(^|[^A-Za-z0-9_])(hash|exec)([^A-Za-z0-9_]|$)' + [[ "$before" =~ $wre || "$before" =~ $RDT_LIT_RESERVED_RE || "$before" =~ $RDT_LIT_FORBID_RE ]] && return 1 + return 0 +} +rdt_scan_gated() { + local rdt_span_gate=word + rdt_scan_substitutions "$1" nested +} @@ rdt_scan_substitutions locals - local -i len=${#s} i=0 pd=0 sd=0 k st ansi=0 hok hs hq - local -a st_start=() st_q=() st_kind=() hd_delim=() hd_strip=() hd_quoted=() hd_sfx=() + local -i len=${#s} i=0 pd=0 sd=0 k st ansi=0 hok hs hq hi + local -a st_start=() st_q=() st_kind=() hd_delim=() hd_strip=() hd_quoted=() hd_sfx=() hd_interp=() @@ at the newline, per opener rdt_hd_plain "${s:hd_sfx[k]:hend - hd_sfx[k]}" || hd_quoted[k]=0 + [[ "${s:hd_sfx[k]:hend - hd_sfx[k]}" == *[![:space:]]* ]] && hd_interp[k]=0 @@ body loop - ((${hd_quoted[k]:-0})) || rdt_scan_substitutions "${hd_body[k]}" nested + if ((${hd_quoted[k]:-0})); then + : + elif ((${hd_interp[k]:-0})); then + rdt_scan_gated "${hd_body[k]}" + else + rdt_scan_substitutions "${hd_body[k]}" nested + fi @@ reset with the other per-heredoc arrays + hd_interp=() @@ at the opener, after hq is decided + hi=0 + if [[ -z "$nested" && hcmt -lt 0 ]] && ((pd == 0)) && [[ "${s:hstart:i-hstart}" =~ $hd_word_re ]] && + rdt_hd_interp "$hfull"; then + hi=1 + fi + hd_interp+=("$hi")
-
Release. Run
scripts/new-changelog-fragment.sh --stdin guardrails patchwith a
### Fixedbody, for example: "block-root-delete-targetno longer refuses a python or node
program fed on a quoted heredoc because a backtick or$(span in its strings holds a word
like "form" and a paren; such a span is still read when a deleter name starts a word in it."
guardrails is inscripts/fragment-plugins.txt, so there is noplugin.jsonbump and no
CHANGELOG.mdedit. No shared-library change, so noscripts/sync-shared-copies.shrun.
Files: plugins/guardrails/hooks/block-root-delete-target.sh,
plugins/guardrails/hooks/block-root-delete-target.test.sh, one new .changes/guardrails/*.md.
Alternatives rejected:
| Alternative | Why rejected | Switch condition |
|---|---|---|
| Skip the whole body for an accepted python or node heredoc | Loses real coverage: the h1 rows are refused today only by the scan | never |
Key the skip on rdt_hd_lang, as first proposed |
A local of rdt_parse (plugins/guardrails/hooks/block-root-delete-target.sh:5748), filled after the scan returns (plugins/guardrails/hooks/block-root-delete-target.sh:8214-8217) |
the scan moves after the parse |
| Defer quoted bodies until after the parse | Reorders a documented load-bearing sequence; heredoc indexes are untrusted (plugins/guardrails/hooks/block-root-delete-target.sh:4916-4919); EOF is reused freely |
the parse records body offsets per reader |
| Soft-fail an unparsable lifted span | bash runs a backtick body's earlier commands before its syntax error | never |
| Word gate on every lifted span, not only python and node bodies | A wider change to a security guard than this report needs | a false-positive report outside python or node bodies |
| Include perl and ruby | Their backticks run commands | a false-positive report from a perl or ruby string |
Configurability
Fix, not a setting: the guard refuses a correct call, so the guard's reading is corrected. Nothing
here is a threshold, budget or scope a consumer would want differently. The existing kill switch
block_root_delete_target_enabled is unchanged.
Baseline
Host: Windows 11, Git Bash (GNU bash 5.3.15, cygwin), 32 logical CPUs, shfmt v3.14.1, node v24.18.0.
It is an interactive workstation, so wall time is noisy: min-to-max spread is 1.5x to 4x per case.
The binding measure is how many times shfmt and jq launch per guard-row run.
Main 999cb91, full 15-guard row via run-guards.sh, one warm-up then 9 timed runs:
| Case | min ms | median ms | max ms | shfmt | jq | exit |
|---|---|---|---|---|---|---|
ordinary (git status --short && git log --oneline -5 | head -3) |
744 | 1323 | 1642 | 1 | 1 | 0 |
| c3 | 1575 | 1993 | 2355 | 3 | 2 | 2 |
| d3 | 726 | 1124 | 1265 | 1 | 1 | 0 |
| rmtree-trailing | 1571 | 2238 | 2984 | 1 | 1 | 0 (ask) |
| node-tpl | 1384 | 2501 | 3241 | 3 | 2 | 2 |
On main, c3 costs two extra shfmt launches (the span parse, then shfmt again for the error line)
and one extra jq launch. Both arms in one later session, 9 runs each (the prototype is the diff
above, not a target):
| Case | main median ms (shfmt/jq) | prototype median ms (shfmt/jq) |
|---|---|---|
| ordinary | 1216 (1/1) | 978 (1/1) |
| c3 | 2348 (3/2), exit 2 | 1089 (1/1), exit 0 |
| d3 | 1405 (1/1) | 1041 (1/1) |
| node-tpl | 2206 (3/2), exit 2 | 1029 (1/1), exit 0 |
Target after the fix: c3 and node-tpl launch shfmt 1 and jq 1, and c3's median is within 15% of
d3's median from the same run.
Rerun both arms in one session on your host. <scratch> is any empty temp directory.
mkdir -p <scratch>/main <scratch>/branch <scratch>/home <scratch>/plugin-data <scratch>/cases <scratch>/bin
git archive origin/main plugins/guardrails | tar -x -C <scratch>/main
git archive HEAD plugins/guardrails | tar -x -C <scratch>/branch
git init -q <scratch>/repoWrite each payload below to <scratch>/cases/<name>.txt and the script to
<scratch>/bin/time-case.sh, using your editor tool rather than a shell redirect. Then run:
SC_ROOT=<scratch> bash <scratch>/bin/time-case.sh <scratch>/main/plugins/guardrails/hooks 9 <scratch>/cases/ordinary.txt <scratch>/cases/c3.txt <scratch>/cases/d3.txt <scratch>/cases/rmtree-trailing.txt <scratch>/cases/node-tpl.txt
SC_ROOT=<scratch> bash <scratch>/bin/time-case.sh <scratch>/branch/plugins/guardrails/hooks 9 <scratch>/cases/ordinary.txt <scratch>/cases/c3.txt <scratch>/cases/d3.txt <scratch>/cases/rmtree-trailing.txt <scratch>/cases/node-tpl.txtc3.txt:
W=wt; F=docs/x.md; python3 -I - <<'EOF'
import pathlib
p = pathlib.Path("docs/x.md")
s = p.read_text()
old = "- Save awaits `the schedule check before the form check (Reviewer 1's race fix)`.\n"
new = "- Save awaits the schedule check.\n"
assert old in s
p.write_text(s.replace(old, new))
EOF
gh pr view 1
d3.txt is c3.txt with before the form check deleted from the old = line.
ordinary.txt:
git status --short && git log --oneline -5 | head -3
rmtree-trailing.txt:
W=x; F=y; python3 - <<'EOF'
import shutil
shutil.rmtree('/')
EOF
gh pr view 1
node-tpl.txt:
node - <<'EOF'
const fs = require("fs");
const s = `the schedule check before the form check (Reviewer 1's race fix)`;
console.log(s);
EOF
time-case.sh runs one warm-up, then N timed runs of the row, then one run under a PATH shim that
counts shfmt and jq launches. It never runs a payload.
#!/usr/bin/env bash
set -u
H="$1"; N="$2"; shift 2
SC="${SC_ROOT:?}"
SHIM="$(cygpath -u "$SC" 2>/dev/null || printf '%s' "$SC")/shim"
mkdir -p "$SHIM"
real_shfmt=$(command -v shfmt); real_jq=$(command -v jq)
printf '#!/usr/bin/env bash\necho x >>"$SPAWN_LOG.shfmt"\nexec "%s" "$@"\n' "$real_shfmt" >"$SHIM/shfmt"
printf '#!/usr/bin/env bash\necho x >>"$SPAWN_LOG.jq"\nexec "%s" "$@"\n' "$real_jq" >"$SHIM/jq"
chmod +x "$SHIM/shfmt" "$SHIM/jq"
ROW=(block-no-verify.sh block-dangerous-git.sh flag-commit-pr-skill-bypass.sh
block-noncanonical-commit.sh block-convention-violation.sh block-windows-drive-tmp.sh
block-exported-msys-pathconv.sh block-root-delete-target.sh block-credential-read.sh
block-unresolved-pr-merge.sh block-fix-request-post.sh block-github-post-content.sh
block-cross-domain.sh block-cd-prefix.sh block-foreground-wait.sh)
run_once() {
local p=(); [[ -n "${2-}" ]] && p=(PATH="$SHIM:$PATH" SPAWN_LOG="$SC/spawn")
printf '%s' "$1" | env -u HOOK_TELEMETRY_SINK HOME="$SC/home" CLAUDE_PLUGIN_DATA="$SC/plugin-data" \
CLAUDE_PROJECT_DIR="$SC/repo" "${p[@]}" bash "$H/run-guards.sh" --lib lib/powershell/ps-command.sh \
--max-substitutions 256 --max-command-len 16384 "${ROW[@]}" >/dev/null 2>&1
}
for CASE in "$@"; do
payload=$(jq -n --rawfile c "$CASE" --arg cwd "$SC/repo" \
'{session_id:"t",hook_event_name:"PreToolUse",tool_name:"Bash",cwd:$cwd,tool_input:{command:($c|rtrimstr("\n"))}}')
run_once "$payload"
ts=()
for ((r = 0; r < N; r++)); do
t0=$(date +%s%N); run_once "$payload"; rc=$?; t1=$(date +%s%N)
ts+=($(((t1 - t0) / 1000000)))
done
mapfile -t s < <(printf '%s\n' "${ts[@]}" | sort -n)
rm -f "$SC/spawn.shfmt" "$SC/spawn.jq"
run_once "$payload" shim
printf '%-16s min=%s median=%s max=%s ms shfmt=%s jq=%s exit=%s\n' "$(basename "$CASE" .txt)" \
"${s[0]}" "${s[N / 2]}" "${s[N - 1]}" "$(cat "$SC/spawn.shfmt" 2>/dev/null | wc -l)" \
"$(cat "$SC/spawn.jq" 2>/dev/null | wc -l)" "$rc"
doneAcceptance criteria
- c3 (prefix-plus-trailing-
ghshape), node-tpl, py-dollar-paren, cd-quoted-c3 and c3-line2 exit 0 from the full Bash guard row. - Every case in the Evidence "must stay refused" table, and every stay-blocked case in Plan step 1, is still refused (exit 2 or ask).
- The predicate accepts only the step 2 grammar: no path, prefix assignment or launcher on the interpreter; no option outside the allow-list; no script or argument word; nothing after the delimiter on the opener line; no opener inside
$( ); and a before text with no\ < > { } ( ), noPATH,hash,execor interpreter word, and noRDT_LIT_RESERVED_REorRDT_LIT_FORBID_REmatch. - The regression tests fail on main (exactly the stay-quiet cases, both arms) and pass on the branch;
block-root-delete-target{,-b,-c,-d,-e,-resolve}.test.shandrun-guards.test.shpass. - Timing no worse than baseline: on the branch, c3 and node-tpl launch shfmt 1 and jq 1, c3's median is within 15% of the same run's d3 median, and the ordinary and d3 medians sit inside main's min-max band from the same session.
- Performance-and-waste pass done and its result in the PR body.
- One
.changes/guardrails/fragment (bump: patch,### Fixed); no other plugin,lib/or shared-copy change.
Required stages for the implementer
-
The fix with the regression tests written first:
/testing:writefor Plan step 1, then
/implementation:implementfor step 2. -
/toolchain:checkand/toolchain:lint;/testing:auditon the new tests. -
A performance and waste pass:
- compare timing to the Baseline section's numbers, using its rerun commands;
- run
/code-metrics:auditfor complexity and duplication on the changed functions; - run
/simplify; - check for repeated process launches, slow loops, repeated git calls, and unclear block or
error messages.
Make the in-scope fixes; list the rest in the PR body.
-
/review:quality-gatecode, and security (this changes a guard's block decision). -
/verification:confirmagainst these acceptance criteria, line by line. -
The PR, with the before/after timing table and launch counts in its body.
Constraints and gotchas
- The scan must stay ahead of the parse
(plugins/guardrails/hooks/block-root-delete-target.sh:8191-8196says why). Leave the fix(guardrails): block-root-delete-target judges backticks inside a quoted heredoc body #6625
reader rule (rdt_hd_plain,rdt_hd_reader) unchanged, and do not reuse it. - Do not skip python or node bodies outright; the gate only narrows which spans are tokenized
(Problem, h1 rows). - c3's backtick span does not end at its closing backtick. The apostrophe in "1's" opens a quote
inside the span, so the span runs to the end of the body and takes in the\nescapes. That is
why the gate does not treat a backslash as a reason to tokenize:\rmis still caught, because
\counts as a word start. - Hook false-positive fixes land with a stay-quiet test that fails first
(docs/conventions/hook-precision/README.md#the-discipline). - Feed the guard command text as JSON on stdin in tests; never run a payload.
- The skip list is security-relevant. Do not add launchers (
env,sudo,xargs,nice,
time), interpreter code options (-c,-e,--eval,-m), perl or ruby, or any shape
beyond the step 2 grammar. When unsure, keep today's scan. rdt_scan_body's prefilter stays a substring match; the gate is an extra test after it, only
for flagged bodies.rdt_ix_heredocsjudges every body in every language that a reader in the command records
(plugins/guardrails/hooks/block-root-delete-target.sh:4912-4922). When a shell in the same
command also reads a heredoc, a python body is still read as shell there, and a c3-like span still
refuses. That is expected and not in scope.- Remaining false positives, documented in the header:
- a span that never closes (c3's does not, see above) takes in the rest of the body, so a later
line holding a stem at a word start or any$brings the refusal back. Verified on the
prototype: c3's string followed byos.remove("build/tmp.txt"), or by
re.compile(r"fix\)$"), is still refused. Do not fix this by changing quote tracking inside
spans; that is security-sensitive and out of scope; - a stem that starts a word inside a span with a paren, such as
`Remove the old check (x)`; - a node template literal holding
${...}, a prefilter substring and a paren; - any command text before the opener that the predicate rejects (
set -e;,${VAR}, a
reserved word), which falls back to today's behavior.
- a span that never closes (c3's does not, see above) takes in the rest of the body, so a later
- Residuals to add to the header list:
- a python or node body that writes a file a later line runs;
- an interpreter binary replaced under another name;
NODE_OPTIONSorPYTHON*environment that loads other code;- python or node output piped to a shell when no span holds a deleter word (already unjudged on
main); - readers the parse does not model (
bash -c sh).
Context
- Source: local handoff item
20261105-195546-guardrails-shfmt-rejects-quoted-heredoc.md, raised
from a work-domain session on WSL against guardrails 2.0.0. - The original report quoted an elided body with no backticks. It suspected the apostrophe, joined
lines, trailing commands or a missing shfmt; none of those matter. The message text "shfmt
rejects it as bash" is produced only after shfmt has run (lib/hook-utils.sh:4643-4649), so
shfmt was installed. - c3 was also refused on the 2.0.0 release commit (c772e1a), per this issue's first draft.
- Related: fix(guardrails): block-root-delete-target judges backticks inside a quoted heredoc body #6625 (quoted heredoc bodies treated as data for plain readers), refactor(guardrails): read hook commands from shfmt's parse tree instead of the hand-written segmenter #12471 (shfmt
parse-tree reader), fix(guardrails): parse the substitutions in an unquoted here-doc body into segments the guards judge #12354 (substitutions in unquoted heredoc bodies), perf(guardrails, discovery, multi-agent): about 160 ms of hooks on every Bash call; docs-fetcher gates run in the main thread #6634 (hook cost). - Sub-issue below: the refusal wording for a nested parse. It is independent of this fix; either
can land first.
Runner portability (overrides the timing criteria above where they conflict)
The Baseline numbers above were measured on Windows 11 with Git Bash, where these hooks run far slower than on Linux. The issue lane (.github/workflows/work-resolve-issue.yml) runs on ubuntu-24.04 and installs no shfmt, typos or hyperfine; only the PR checks install a pinned shfmt (.github/actions/setup-pinned-shfmt). Windows seconds are context, not a pass bar.
- Binding timing gate: counts. The process-launch or call counts the Baseline commands report are measured on origin/main and on the branch in the same run on the same host. The branch meets the count target stated above (or does not exceed main where none is stated). Counts go in the PR body.
- Wall time, same host only. If the Baseline commands can run on the host, time origin/main and the branch in the same run (median of 5; a plain
timeloop is fine, hyperfine is not required). The branch median is at most main's slowest run. Seconds from a different host are never compared. - Missing tool. Where a test or timing needs a tool the host lacks, use the stub approach the plan gives if it has one. Otherwise do not install an unpinned tool: name the missing tool in the PR body, report the count evidence, and leave the wall-time check for a maintainer to rerun with the Baseline commands (on Windows where the symptom is Windows-only). That is not a failed stop.
- Windows-only symptoms (command-line length, Git Bash process cost) are proved on Linux by the deterministic test the plan names (for example a stub that fails when paths arrive on argv).
pr-test-platforms.ymlruns the Windows suites a change selects.
Metadata
Metadata
Assignees
Labels
Type
Fields
Work status
Priority
Activity
github-actions commentedon Nov 13, 2026
Size: Small
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: none
Understood:
block-root-delete-targetwrongly refuses a valid Bash call. The call feeds a quoted python or node heredoc whose strings hold a backtick or$(span with a paren and a prefilter word such as "form". The refusal is the generic shfmt-parse message. The issue gives a plan: tests first, then a narrow word gate on those spans, then a changelog fragment. It also lists the must-stay-refused cases and the acceptance criteria. Intent and scope are exact, so no owner question is open. I found no open duplicate and no merged pull request that already fixes this.Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 13, 2026
Not admitted to the issue lane: its body or a criterion names .github/workflows/pr-test-platforms.yml, .github/workflows/work-resolve-issue.yml, which the issue lane cannot push (patch-protected-path); a builder session takes it. Admission takes the issue once each of those is met, when intake triages it again (
.github/actions/resolve-config/admission-rules.json).