Skip to content

fix(guardrails): stop parsing backticks in a python quoted heredoc as shell in root-delete #15977

Closed

Description

@kyle-sexton

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 one cat, gh pr|issue|api|release or git 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), through rdt_parse and
    shfmt (plugins/guardrails/hooks/block-root-delete-target.sh:5743-5775). shfmt rejects the
    prose at the (, and hook::_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

  1. 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),
    add expect_both cases (each runs direct and under run-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-gh shape, 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=bash after shopt -s expand_aliases,
      eval "$x"; and . ./defs.sh; earlier, a python body whose variable holds
      `\rm -rf /`, and a ruby - <<'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.
  2. Fix in plugins/guardrails/hooks/block-root-delete-target.sh only. Nothing below line 8190
    moves: the scan stays ahead of the parse.

    • rdt_hd_interp <text before the opener>, a new predicate beside rdt_hd_reader, accepts a
      python or node program heredoc:
      • stmt is 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 of stmt, must hold no \, <, >, {, }, ( or
        ). It must not contain PATH or the interpreter word, must have no hash or exec word,
        and must not match RDT_LIT_RESERVED_RE or RDT_LIT_FORBID_RE
        (plugins/guardrails/hooks/block-root-delete-target.sh:6278-6280), applied to before
        only. The </> rule keeps >|, >& and <& from being read as separators.
    • In rdt_scan_substitutions, add a per-heredoc hd_interp flag beside hd_quoted.
      • Set it at the opener when the scan is top level (nested empty), pd == 0, no comment is
        open (hcmt < 0), the delimiter word matches hd_word_re (quoted), and rdt_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
        clearing hd_quoted only.
    • In rdt_scan_body, after the existing substring prefilter: when rdt_span_gate is word
      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 reset rdt_span_gate to empty (local) before rdt_parse, so deeper readings
      are not gated.
    • Update both header comments
      (plugins/guardrails/hooks/block-root-delete-target.sh:6491-6507 and
      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")
  3. Release. Run scripts/new-changelog-fragment.sh --stdin guardrails patch with a
    ### Fixed body, for example: "block-root-delete-target no 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 in scripts/fragment-plugins.txt, so there is no plugin.json bump and no
    CHANGELOG.md edit. No shared-library change, so no scripts/sync-shared-copies.sh run.

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>/repo

Write 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.txt

c3.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"
done

Acceptance criteria

  • c3 (prefix-plus-trailing-gh shape), 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 \ < > { } ( ), no PATH, hash, exec or interpreter word, and no RDT_LIT_RESERVED_RE or RDT_LIT_FORBID_RE match.
  • 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.sh and run-guards.test.sh pass.
  • 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

  1. The fix with the regression tests written first: /testing:write for Plan step 1, then
    /implementation:implement for step 2.

  2. /toolchain:check and /toolchain:lint; /testing:audit on the new tests.

  3. A performance and waste pass:

    • compare timing to the Baseline section's numbers, using its rerun commands;
    • run /code-metrics:audit for 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.

  4. /review:quality-gate code, and security (this changes a guard's block decision).

  5. /verification:confirm against these acceptance criteria, line by line.

  6. 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-8196 says 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 \n escapes. That is
    why the gate does not treat a backslash as a reason to tokenize: \rm is 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_heredocs judges 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 by os.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.
  • 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_OPTIONS or PYTHON* 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

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 time loop 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.yml runs the Windows suites a change selects.

Activity

  1. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Nov 13, 2026
  2. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 13, 2026
  3. github-actions commented on Nov 13, 2026

    @github-actions
    Contributor

    Size: Small
    Complexity: Medium
    Uncertainty: Known
    Flags: none
    Blocked by: none

    Understood: block-root-delete-target wrongly 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.

  4. removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 13, 2026
  5. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Nov 13, 2026
  6. melodic-automation-lanes commented on Nov 13, 2026

    @melodic-automation-lanes
    Contributor

    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).

  7. added
    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.
    on Nov 13, 2026
  8. removed
    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.
    on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.

    Type

    Fields

    Work status

    confirmed

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions