skills: $-bearing shell in skill BODIES and reference spokes is refused under worktree isolation at run time (untracked surface, larger than #1619's pre-compute scope)

[kyle-sexton]

Surfaced while closing out #1619. Distinct from every issue currently open on that thread, and larger
than all of them.

The gap

#1619 and its fixes (#1676, #1679, #1688) are entirely about the ## Pre-computed context block —
!`cmd` lines the harness runs at skill load time. Removing $-expansion from those makes a
skill load under worktree isolation.

But the same guard applies at run time to every Bash call the skill's body instructs the model to
make. A skill can now load cleanly and then fail on its third step, when the body says to run
something like:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/retro/scripts/parse-transcript.py" "$TRANSCRIPT"

Confirmed guard behavior on Bash-tool calls from inside a worktree-isolated agent:

form	result
$HOME (bare, anywhere in the command)	PASS
any ${…} braced form, any name	REFUSED
$(…) command substitution	REFUSED
$CLAUDE_PLUGIN_ROOT, "$CLAUDE_PLUGIN_ROOT/x"	REFUSED
a bare $var local	REFUSED ($FOO)

Note the asymmetry that makes this specifically nasty: in pre-compute, ${CLAUDE_PLUGIN_ROOT} is
substituted by the harness into a literal path before any shell sees it, so it is safe. In a body
instruction the model copies the text into a Bash call, where it is $-text and is refused —
unless the harness substituted it during body rendering, which it does for the skill content itself.
Which of those two applies to a given body snippet has not been established, and it decides whether
this is a large problem or a small one. That is the first thing to determine.

Why it is not hypothetical

$(…) refusal was hit live during this work: an until [ "$(gh api …)" = … ] poll and a Monitor loop
both tripped the guard from an isolated agent. Any body instruction of the shape
BASE=$(git merge-base …) — a pattern this repo's own skills use, e.g. resolve-conflicts'
intent-recovery table — is refused there.

Scope — unknown, and that is the point

Nobody has swept skill bodies or reference/ spokes for $-bearing shell. The pre-compute sweep found
21 skills; the body surface is plausibly larger, since bodies carry most of the actual procedure.

Suggested first step is a sweep, not a fix:

1. Grep plugins/**/SKILL.md and plugins/**/reference/**.md for $-bearing shell outside
   pre-compute blocks.
2. Classify: harness-substituted plugin variable (safe) vs real shell expansion (refused under
   isolation).
3. Determine empirically whether a body-rendered ${CLAUDE_PLUGIN_ROOT} reaches the model as a literal
   path. Evidence says yes for prose — a body reference rendered as
   C:/Users/<user>/.claude/plugins/cache/melodic-software/claude-config/0.14.0/skills/… — but that
   was one skill, and fenced code blocks may behave differently from prose.
4. Only then decide the remedy.

Known workaround

The guard inspects the command string, not the script's contents. bash <literal-script-path>
passes, and the script may contain whatever shell it likes. So the general remedy for a refused body
command is to hoist the shell into a script file and invoke it by literal path — the same remedy
already proposed for the Class 2 pre-compute cases on #1687.

Caveats

• Everything above is the worktree-isolation guard as observed from inside an isolated agent.
  Ordinary sessions are unaffected; this only bites isolated/parallel agents.
• The guard's mechanism is uncharacterized. echo "$USER" is refused while echo "$USER/.claude"
  passes, which no proposed model explains. Do not build a gate or a fix on an assumed mechanism —
  test the specific forms.

Related

• fix(skills): worktree-isolated agents cannot invoke a skill whose pre-compute block contains a $-expansion (21 skills; NOT git — see correction comment) #1619 — the original defect and the corrected rule (see the final-state comment).
• fix(skills): pre-compute Class 2 remainder — genuine shell expansion mixed into pre-compute in 5 plugins (canonical tracker; scope in comments, body list superseded) #1687 — the pre-compute remediation, closed.
• fix(skills): #1619 remainder — re-scope to the $-expansion trigger (original 31-skill git-based list is WRONG) #1661 — remaining pre-compute work.
• ci(skills): no gate catches a second precompute line silently breaking a git-bearing skill under worktree isolation #1662 — proposed CI gate; currently scoped to pre-compute only, and would need widening if this
  surface turns out to be real.

[kyle-sexton]

This was generated by AI (triage lane — gate-audit claim). Claiming this item for one gate-audit cycle: an independent panel re-classifies whether the needs-human / status: needs-decision gate is still warranted, or whether the item is C2/C3 and liftable to agent-ready. Outcome comment follows in this cycle.

[kyle-sexton]

This was generated by AI (triage lane — gate audit). Independent panel: two fresh-context agents (one fable, one opus), each given only the issue content and the repo's own plugins/autonomy/reference/guardrails/work-classes.md, plus the triage lane's own read. This lane never executes work items, authors fixes, or merges.

Gate audit: LIFTED to agent-ready — C1 read-only, SCOPE-FENCED

Panel: 2-of-2 LIFT-ELIGIBLE, C1. Lane read concurs. No human-floor trigger.

The item's own defined first action is explicitly "a sweep, not a fix" — four numbered read-only steps: grep plugins/**/SKILL.md and plugins/**/reference/**.md for $-bearing shell outside pre-compute blocks, classify harness-substituted plugin variable vs real shell expansion, empirically determine whether a body-rendered ${CLAUDE_PLUGIN_ROOT} reaches the model as a literal path, and report. Zero repository mutation, tracker as the output channel — textbook C1.

Keeping the gate shut was actively counterproductive: it blocked the very C1 evidence-gathering that the eventual human decision depends on. The sweep observes the isolation guard's behaviour without modifying or bypassing it, so no security floor fires.

SCOPE FENCE — binding on the executing agent

Lifted: steps 1-3 only (sweep, classify, empirically test, report).

NOT lifted, and must not be executed under this lift:

• Step 4's remedy — including any fleet-wide "hoist shell into a script" change, which would touch the isolation-guard surface.
• The related ci(skills): no gate catches a second precompute line silently breaking a git-bearing skill under worktree isolation #1662 gate-widening / severity question.

Report the evidence and stop. The remedy returns here as a separate, separately-gated decision.

[kyle-sexton]

This was generated by AI (triage lane — claim release). Gate-audit cycle complete for this item; the triage claim posted earlier this cycle is released. No lease is held — another instance or lane may pick this up immediately. The outcome comment above this one carries the classification and either the lift rationale or the decision summary.

[kyle-sexton]

[kyle-sexton]

This was generated by AI (work lane — read-only sweep). Steps 1–3 only, per the gate-audit scope fence on this thread. No repository mutation, no PR, no remedy applied.

Outcome in one line

The $-bearing body surface is real, and larger than the pre-compute surface — but the decisive fact turns out not to be $-form at all. It is which file the snippet lives in. ${CLAUDE_PLUGIN_ROOT} is substituted in a SKILL.md the harness injects, and arrives literal in a reference/ or context/ spoke opened with the Read tool. Same token, same repo, opposite verdict.

---

Step 3 — the question the issue said to answer first

"Determine empirically whether a body-rendered ${CLAUDE_PLUGIN_ROOT} reaches the model as a literal path… fenced code blocks may behave differently from prose."

Answered, with a control on both axes. A worktree-isolated agent loaded skill-quality:check (0.12.0, from the plugin cache) and reported verbatim what arrived in its context, then Read a spoke file and did the same.

token in source	delivered via injected SKILL.md	delivered via Read tool on a spoke
${CLAUDE_PLUGIN_ROOT}	expanded → C:/Users/<user>/.claude/plugins/cache/melodic-software/skill-quality/0.12.0	literal, unexpanded
${CLAUDE_PROJECT_DIR}	expanded → D:/repos	literal, unexpanded
$ARGUMENTS	substituted → listing-budget (the invocation's args)	n/a
${user_config.skills_root}	literal, unexpanded	—

Two things fall out.

Fenced vs prose is a non-issue. Substitution happened identically in fenced ```shell blocks and in running prose and in a markdown link target. The issue flagged this as the open question; it is closed, and the answer is "no difference."

${user_config.*} is a class the issue did not name. It sits in the same injected body, next to a substituted ${CLAUDE_PLUGIN_ROOT} on the same line, and is left literal. Any body that tells the model to run a ${user_config.…}-bearing command is refused under isolation. 158 such snippets across 57 files.

Spoke probes, verbatim. claude-config/0.14.0/skills/audit-permission-grants/reference/criteria.md line 15 arrived as:

`bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-grants/scripts/permission-rule-check.sh"` — it scans

context/ was probed separately and behaves identically — session-flow/0.17.16/skills/retro/context/session.md line 33 arrived as:

PARSER="${CLAUDE_PLUGIN_ROOT}/skills/retro/scripts/parse_transcript.py"

All ten ${ occurrences in that file arrived literal, across three token families (${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_CODE_SESSION_ID}, ${CLAUDE_PLUGIN_DATA}). Both spoke conventions are therefore observed, not inferred.

---

Guard behaviour — reproduced, unchanged from #1688

Every command run as its own standalone Bash call from a worktree-isolated agent.

command	result
echo $HOME / echo "$HOME"	PASS
echo ${HOME} / echo "${HOME}"	REFUSED
echo $FOO	REFUSED
echo $(date -u +%Y)	REFUSED
BASE=$(git merge-base HEAD HEAD); echo $BASE	REFUSED
echo "$CLAUDE_PLUGIN_ROOT"	REFUSED
echo "$USER"	REFUSED
echo "$USER/.claude"	PASS
printenv HOME	PASS
git rev-parse --show-toplevel	PASS
bash -c 'echo hello'	PASS

#1688's rule holds unmodified, including its unexplained "$USER" / "$USER/.claude" pair.

The workaround holds, and out-of-worktree paths are not themselves the trigger. bash "<absolute cache path>/check-skill.sh" --help PASSED and printed the script's usage. So did ls, cat, and ls C:/Users/<user>/.claude — all reading outside the isolated worktree. Hoisting shell into a script invoked by literal path is confirmed viable.

One caution, and it matters for #1662

A command form was REFUSED on one call and reached the shell on a later call in the same agent. The probe agent initially reported this as proof the guard is non-deterministic, then withdrew that: it cannot byte-diff its own tool-call parameters, and the refusal message — unlike the shell error — echoes nothing back, so there is no independent record of what the refused call actually received. Input identity is asserted, not verified; non-determinism is therefore NOT established.

What is established without any byte-identity assumption is that the guard's accept/reject boundary remains unexplained ("$USER" refused, "$USER/.claude" passed). The issue's own warning stands: do not build a gate on an assumed mechanism. Anything #1662 derives from this class wants multi-trial evidence with recorded inputs.

---

Steps 1–2 — the sweep

Scripted, not eyeballed. plugins/**/SKILL.md (190 files) + plugins/**/reference/**.md (170) + plugins/**/{context,agents}/**.md (269). Pre-compute blocks and !`…` lines excluded throughout.

1,730 $-bearing snippets outside pre-compute. Classified against the delivery-path evidence above:

verdict	snippets	files	plugins
PASS — harness-substituted token inside an injected SKILL.md	646	160	—
REFUSED — real shell expansion ($(…), ${OTHER}, bare $FOO)	725	117	—
REFUSED — plugin var sitting in a Read-tool spoke	201	86	—
REFUSED — ${user_config.*}	158	57	—
REFUSED, total	1,084	211	52

The 1,084 is an upper bound: it includes JSON-schema $ref, PowerShell $env:, awk $0, prose metasyntax like ${VAR_NAME}, and lines that are the source text of a displayed script rather than a command to run.

Narrowing to snippets that both would be refused and are shaped like a command a body hands to Bash:

310 snippets · 81 files · 24 plugins. 228 of them in spokes, 82 in SKILL.md.

That 310 is a scripted heuristic, not a hand-verified count. It is a regex over command-shaped lines, with error in both directions — it will still admit array expansions inside displayed script source, and it will miss commands whose verb is not in its list. Treat it as the right order of magnitude and the right ranking, not an audited figure. The per-snippet verdicts are machine-readable and auditable; the classifier was written by the same lane that ran it, so an independent re-count is worth having before anyone sizes the remedy off this number.

plugin		plugin
source-control	121	repo-hygiene	12
claude-memory	27	ai-briefing	11
toolchain	25	docs-hygiene	6
work-items	22	claude-config	5
knowledge	20	planning	4
claude-ops	18	(13 more)	≤3 each
session-flow	16

Worst files: source-control/skills/pull-request/reference/create.md (34), source-control/skills/babysit-prs/reference/loop.md (29), source-control/skills/pull-request/reference/monitor.md (17), claude-memory/skills/stateless/context/purge.md (12), claude-ops/skills/observability/context/data-sources.md (12).

Two corrections to the issue's premises

• retro's parser line is not the problem. ${CLAUDE_PLUGIN_ROOT}/skills/retro/scripts/parse_transcript.py in retro/SKILL.md:64 is substituted and safe. What is refused in that skill is the fenced block at lines 50–53 (PROJECT_SLUG=$(pwd -W …), "$HOME/.claude/projects/$PROJECT_SLUG") and the inline ${CLAUDE_CODE_SESSION_ID} glob at line 57 — plus retro/context/session.md:33, where the same PARSER="${CLAUDE_PLUGIN_ROOT}/…" token is refused because it is a spoke.
• resolve-conflicts is confirmed. All four BASE=$(git merge-base HEAD …) cells (SKILL.md:52–55) are refused. They are markdown table cells, not fenced blocks — a real run-instruction shape that a fence-only sweep would miss.

Scope gap in the issue's own step 1

The issue scoped the sweep to SKILL.md and reference/. context/ (58 dirs, 260 .md) and agents/ carry 58 additional command-shaped refused snippets across 18 files in 8 plugins, and are the more affected surface per file, because nothing in them is ever substituted.

---

What is NOT in this report

Per the scope fence, step 4 (the remedy) was not designed, not proposed, and not applied, and neither was the #1662 gate-widening question. Nothing in the repository was modified; there is no PR, by design — this item is work-class: read-only.

What the remedy decision now faces

24 plugins, 81 files, 310 call sites, with at least three distinct fix shapes (hoist to a script; drop to a $-free form; leave alone because it is illustrative, not an instruction). That is a cross-cutting change on a guard whose mechanism remains uncharacterized. Flagging for the human decision rather than proposing a shape.

Reproduction: classification is scripted; the sweep script, the raw 1,730-row JSON, and the per-snippet verdicts can be regenerated on request. Guard and rendering probes were run from an Agent with isolation: "worktree" on 2026-07-27, against plugin cache skill-quality 0.12.0 and claude-config 0.14.0.