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)

[kyle-sexton]

Follow-up to #1619, which now carries the corrected diagnosis. This issue tracks the fix that
actually addresses the defect.

Why a new issue

#1676 merged a remediation for session-flow based on the wrong mechanism. It removed git
commands from seven skills' pre-compute blocks — but the trigger is a $-expansion, not git, and six
of those seven skills still carry !`echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown"`.
They are still refused from a worktree-isolated agent at 0.17.15.

The work #1676 did is not wasted — moving git into individual body Bash calls is sound and those calls
demonstrably pass under isolation. It simply did not remove the blocker.

The rule (evidence on #1619)

A command is refused iff it contains a $-expansion in any form other than bare $HOME or
"$HOME". Git, pipes, 2>/dev/null, ||, and multi-line composition are irrelevant.

A skill is refused iff its pre-compute block contains at least one such $-expansion.

Controlled pair, both lines verbatim from real skills, run standalone under isolation:
git status --porcelain 2>/dev/null | head -20 || echo clean → PASS;
echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown" → REFUSED.

Scope — 21 skills

plugin	skills	the $ in question
session-flow	handoff, continue-in-background, orient, retro, running-retro, find-handoff	${CLAUDE_CODE_SESSION_ID:-unknown}; find-handoff also ${HOME}
source-control	commit	${CLAUDE_PLUGIN_ROOT}, $HOME, and two R="$(git rev-parse …)" one-liners
claude-memory	audit	${CLAUDE_PLUGIN_ROOT}, $d
claude-ops	lanes, observability	${CLAUDE_OPS_LANES_CONFIG:-…}, ${CC_OTEL_STORE:-…}, ${CLAUDE_PLUGIN_ROOT}
code-tidying	audit-comment-residue, tidy	${CLAUDE_SKILL_DIR}, ${CLAUDE_PLUGIN_ROOT}
docs-hygiene	audit-noise, audit-derivability, compress	${CLAUDE_SKILL_DIR}; note audit-derivability/compress hit it only via $NF-style awk/sed in a pipeline — confirm per file
prototype	explore-directions, pressure-test	${CLAUDE_PLUGIN_ROOT}
claude-config	audit-automation-gaps	${CLAUDE_PLUGIN_ROOT}
education	teach	${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_DATA}, several locals
firecrawl	update	${CLAUDE_SKILL_DIR}
review	fanout	$D in a compound fallback

Verify each file individually before editing — the sweep is a starting list, not a contract.

The fix

Per affected skill: remove the $-expansion from the pre-compute block. Either

• move the read into the skill body as an ordinary Bash call (the #1676 pattern, which works), or
• emit the value without ${} where a literal will do.

${CLAUDE_PLUGIN_ROOT} cases need thought: that variable is how a plugin references its own bundled
scripts, and the plugins-reference documents it as the supported mechanism. Moving such a probe into
the body means the body must resolve the plugin root some other way, or the probe becomes a body-run
command that still needs the variable. This may not have a clean in-plugin answer, which would make
those skills genuinely harness-blocked rather than fixable here — decide that explicitly rather than
forcing a workaround.

Grouping

One PR per plugin (each owns its own plugin.json version and CHANGELOG.md): up to 11 PRs.
session-flow and source-control are the highest-traffic and should go first.

Verification — mandatory shape

Invoke from an Agent with isolation: "worktree":

• before: the skill is refused with the worktree-isolation guard message;
• after: it renders and runs;
• negative control (required): a skill predicted to STILL refuse. A green result without a control
  is exactly what produced the original wrong diagnosis;
• positive control: knowledge:course-digest (four complex pre-compute lines, no $, no git).

CI cannot prove any of this — it never invokes a skill from an isolated agent. The plugin cache is
version-keyed (~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/), so nothing is verifiable
until the fix ships and plugins are updated.

Open question worth settling first

Bare $HOME is the only expansion observed to pass; ${HOME} refuses. Whether that is a stable
allowlist or an artifact of one guard version is uncharacterized, and it decides whether $HOME is a
safe target form or should also be removed. Probe before relying on it.

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 defect and the corrected diagnosis.
• fix(skills): #1619 remainder — re-scope to the $-expansion trigger (original 31-skill git-based list is WRONG) #1661 — the superseded remainder list, re-scoped by comment.
• ci(skills): no gate catches a second precompute line silently breaking a git-bearing skill under worktree isolation #1662 — the CI gate that would catch this class, also re-scoped.
• fix(session-flow): move git out of skill pre-compute so worktree-isolated agents can invoke these skills #1676 — merged, fixed the wrong thing, left the $ lines in place.
• fix(source-control): move git out of skill pre-compute so worktree-isolated agents can invoke these skills #1679 — in flight; its source-control git migration does not remove commit's ${CLAUDE_PLUGIN_ROOT} line.

[kyle-sexton]

session-flow half is done — #1688 merged (a0021aef, 0.17.16)

All six ${CLAUDE_CODE_SESSION_ID:-unknown} lines removed; find-handoff's ${HOME} glob narrowed to bare "$HOME", which is the one expansion form directly observed to pass. Exactly one $ remains in the plugin's pre-compute and it is that "$HOME".

Still unverified, and it cannot be verified yet: the plugin cache is version-keyed and currently holds 0.17.15, not 0.17.16. Nothing has exercised the shipped fix. The confirmation run needs a plugin update first, then invocation from an Agent with isolation: "worktree" including a negative control — a skill predicted to still refuse.

A finding that narrows the remaining scope

The probe tested bare forms of several variables, not just HOME:

form	result
echo $HOME	PASS
echo "$HOME"	PASS
echo ${HOME}	REFUSED
echo $CLAUDE_PLUGIN_ROOT	REFUSED
echo $CLAUDE_PROJECT_DIR	REFUSED
echo $PATH / $PWD / $USERNAME / $TMPDIR / $SHELL	REFUSED
printenv CLAUDE_CODE_SESSION_ID	PASS (no $ at all)

So dropping the braces is not a general remedy — it works for HOME and nothing else tested. $HOME appears to be specifically allowlisted.

Consequence for the ${CLAUDE_PLUGIN_ROOT} cases (source-control:commit, claude-memory:audit, claude-ops:*, code-tidying:*, docs-hygiene:*, prototype:*, claude-config:audit-automation-gaps, firecrawl:update): the bare form is refused too, so there is no in-pre-compute fix.

But there is a plausible route worth testing before declaring them blocked. ${CLAUDE_PLUGIN_ROOT} in body prose is substituted by the harness at skill-load time into a literal path — plugin-variable substitution, not shell expansion. A body instruction reading bash "${CLAUDE_PLUGIN_ROOT}/skills/x/scripts/y.sh" would therefore reach the model as a literal path with no $ in it, and run clean. In pre-compute the same text is handed to a shell, which is where it trips.

If that holds, the remedy for every ${CLAUDE_PLUGIN_ROOT} case is the same as the session-id one: move the invocation from pre-compute into the body. Verify it before building on it — that is the assumption class that produced two wrong diagnoses on #1619 already.

printenv caveat for any remaining session-id-style case

printenv NAME clears the guard but is not semantically equivalent to echo "${NAME:-default}": when the variable is unset it exits 1 and prints nothing, instead of emitting the sentinel and exiting 0. Any body instruction using it must handle the unset path explicitly.

[kyle-sexton]

Third correction — the ~15-skill scope in this issue is WRONG, and the population splits in two

A probe testing whether \ skills are fixable found the premise itself false. Plugin variables never reach the shell as $-text.

Mechanism (observed)

\, \, and \ are substituted by the harness into literal paths before any shell sees them — in pre-compute as well as body. There is no $ left for the guard to catch.

Evidence:

• printenv CLAUDE_PLUGIN_ROOT → exit 1, no value. The variable is not in the Bash tool's environment at all, including immediately after a skill loaded.
• A skill body's \/skills/x/scripts/y.sh rendered as C:/Users/<user>/.claude/plugins/cache/melodic-software/claude-config/0.14.0/skills/….
• Tell-tale: the harness's own Base directory header renders backslashes while every substituted reference renders forward slashes. A shell expanding an env var cannot produce that divergence; string substitution with path normalization can.

The class split

Class 1 — pre-compute using ONLY plugin variables: NOT BROKEN. No fix needed.

Confirmed loading under isolation: claude-config:audit-automation-gaps (returned real script output — Hook scripts: 0 / Skills: 0 / …, byte-identical to running the script by hand, not the || echo fallback), prototype:pressure-test (also returned worktree-agent-… from its own git branch --show-current pre-compute, which rules out "the parent rendered this before isolation applied"), docs-hygiene:audit-noise.

Inferred from identical line shape, untested: prototype:explore-directions, code-tidying:tidy, code-tidying:audit-comment-residue, source-control:commit, firecrawl:update.

This means source-control:commit is probably fine as merged in #1679 — its \ exec-bit line and "$HOME" config line are both in the passing class. My comment on that PR saying it "remains uninvocable" is likely wrong; it is inferred, not confirmed, and worth a direct check.

Class 2 — a plugin variable MIXED with a genuine shell expansion in the same block: REFUSED, but the plugin variable is not the cause.

Confirmed: claude-memory:audit — d=$(bash "\/…"); ls "$d"/*.md. The $d is what kills it.

Inferred, same shape: claude-ops:observability ($f, $(git rev-parse …), \…), claude-ops:lanes ($c, $(claude --version)), education:teach ($p/$b/$h), review:fanout ($D).

Remediation for Class 2 is to hoist the shell logic into a script and call it through the plugin variable — not to remove \.

Counter-case that pins the rule down

session-flow:orient at installed 0.17.15 has exactly ONE pre-compute line — echo "\8c753c62-9716-407c-bfde-9533f6c7b0ec", a real shell env var, not a plugin variable. REFUSED, whole skill failed to load. That is the clean discriminator: plugin variable passes, shell variable refuses, same position in the same kind of block.

Also observed, stated narrowly

docs-hygiene:audit-noise LOADED despite grep '\.md$' in pre-compute. A trailing $ before a quote is not an expansion. This is equally explained by a lexical rule ($ not followed by an identifier char or {) as by real shell parsing — do not conclude the guard parses shell.

Consequence for this issue

Neither "all ~15 broken" nor "all ~15 fine" is right. Rewrite the scope as the two classes above, and re-verify the Class 1 inferences before closing anything on them.

[kyle-sexton]

Final state of the rule — with one contradiction resolved and one thing still unexplained

Three independent isolated-agent probes have now run. This supersedes my earlier comments, including
the "bare $HOME only" formulation.

Confirmed by observation

The discriminator is brace syntax, not embedding, and not position.

form	result
echo $HOME	PASS
echo "$HOME"	PASS
echo "$HOME/.claude"	PASS
echo "prefix $HOME suffix"	PASS
ls -1dt "$HOME/.claude/projects/"*/ 2>/dev/null | head -8 || echo "none"	PASS
echo ${HOME}	REFUSED
echo "${HOME}"	REFUSED
echo "${HOME}/.claude"	REFUSED
echo "$USER/.claude"	PASS
echo "$PATH/x"	PASS
echo "$USER"	REFUSED
echo $CLAUDE_CODE_SESSION_ID	REFUSED
echo $CLAUDE_PLUGIN_ROOT / echo "$CLAUDE_PLUGIN_ROOT/x"	REFUSED
echo "$FOO/x"	REFUSED
printenv CLAUDE_CODE_SESSION_ID	PASS (no $ at all)
$(…) command substitution	REFUSED

My earlier "bare $HOME or \"$HOME\" only" rule was under-tested and too narrow: $HOME passes
anywhere in a command, and $USER/$PATH pass in some forms too. Any ${…} braced form is refused
regardless of name.

The load-bearing result

session-flow:find-handoff's shipped line — the exact text merged in #1688 —
passes. So #1688 did fix that skill's pre-compute and no follow-up is needed on its account. That
was the open risk in merged code; it is closed.

A contradiction between probes, resolved in favor of the direct evidence

One probe concluded ${CLAUDE_PLUGIN_ROOT} pre-compute lines would be refused, listing
claude-config:audit-automation-gaps, prototype:pressure-test, and source-control:commit among
the casualties. That inference is wrong, and it was drawn from Bash-tool behavior rather than from
invoking the skills.

An earlier probe invoked those skills under isolation and they LOADED —
audit-automation-gaps returning real script output (Hook scripts: 0 / Skills: 0 / …,
byte-identical to running the script by hand, not its || echo fallback), and pressure-test
returning worktree-agent-… from its own git branch --show-current pre-compute.

Both are consistent once you separate the two paths:

• Bash-tool calls are checked by the isolation guard, which refuses $CLAUDE_PLUGIN_ROOT.
• Pre-compute lines never contain that text by the time a shell sees them: the harness substitutes
  plugin variables into literal paths first. Corroboration: printenv CLAUDE_PLUGIN_ROOT returns
  exit 1, no value — the variable is not in the shell environment at all — and substituted
  references render with forward slashes while the harness's own Base directory header renders
  backslashes, which a shell expanding an env var cannot produce.

So a skill whose pre-compute uses only plugin variables is fine. A skill mixing a plugin variable
with a genuine shell expansion ($d, $(…), ${VAR:-default}) is refused because of the shell
expansion — confirmed on claude-memory:audit.

Still unexplained — do not paper over it

echo "$USER" is refused while echo "$USER/.claude" passes. No model I have fits that. Two
candidates, neither distinguished by anything run so far:

1. a name allowlist plus a brace-syntax block; or
2. the guard resolves known session values and refuses what it cannot resolve — $USER is empty in
   this environment, which might make the bare form unresolvable while the concatenated form is not.

$USER being empty here is consistent with (2), but nothing tested separates them. Treat the
mechanism as uncharacterized. Every practical conclusion above rests on the observed
pass/refuse table, not on either model.

Scope bound on all of it

Everything observed is the worktree-isolation Bash guard, from inside a worktree-isolated agent.
Pre-compute injection at skill-load time in an ordinary session is a different execution path that
none of these probes can exercise. Read "the line passes" as "passes the isolation guard," not as
end-to-end verification.

Also still unverified and unverifiable until plugins update: that the edited session-flow skills
load at 0.17.16. The cache is version-keyed and sits at 0.17.15. There are now ~15 $-bearing skills
available to serve as the negative control that confirmation requires.

A larger surface nothing tracks

Removing $-expansion from pre-compute makes a skill load. $-bearing shell in skill bodies
and in reference/ snippets remains subject to the same guard at run time — e.g. retro's
transcript-parser invocation. That is a distinct and larger surface, and no issue currently covers it.

[kyle-sexton]

This was generated by AI (autonomous drain lane, delegated decision authority for this session: decisions recorded as comments for human review/veto; no merges).

DECISION — reopened as the single canonical tracker for the pre-compute remainder

What happened to the bookkeeping. #1688 carried Closes #1687 (the pr-issue-linkage gate requires a closing keyword), so this issue auto-closed as completed at 02:28:56Z on 2026-07-27 when only the session-flow six of its list were done. Fifteen minutes later (02:44:24Z), the comment on #1661 recommended "closing it in favor of #1687" — evidently unaware this issue had already closed. Result: the recommended canonical surface was closed-as-completed with its work unfinished, and the open surface (#1661) had a twice-superseded body. Nothing accurate was live.

Decision: reopen this issue and retitle it; close #1661 as superseded. Rationale:

• This thread carries the current analysis (the Class 1 / Class 2 split and the final-state guard rule); fix(skills): #1619 remainder — re-scope to the $-expansion trigger (original 31-skill git-based list is WRONG) #1661's body is the original wrong 31-skill git list, corrected only in comments.
• The completed close state was factually wrong — Class 2 work is still live on origin/main.
• This executes the direction of the owner's last comment (consolidate on 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), adjusted for the fact it was already closed.
• Cross-vendor advisory (codex-cli, read-only) concurred with this option over (a) keeping fix(skills): #1619 remainder — re-scope to the $-expansion trigger (original 31-skill git-based list is WRONG) #1661 as tracker or (b) opening a fresh issue.

Canonical remaining scope — verified against origin/main @ 848df9e9 (2026-07-30)

A fresh mechanical sweep of every ## Pre-computed context line containing $ confirms the Class 2 population (genuine shell expansion — $local, $(…), ${VAR:-default} — in a pre-compute line):

plugin	skill	lines	expansions
claude-memory	audit	15–16	$d, $(bash …)
claude-ops	lanes	16, 19	$(claude --version), $c, ${CLAUDE_OPS_LANES_CONFIG:-…}, $(git rev-parse …)
claude-ops	observability	19, 21	$f, $d, ${CC_OTEL_STORE:-…}, $(git rev-parse …)
education	teach	58	$p, $b, $h, $(realpath …), $(basename …), $(printf … sha256sum …)
review	fanout	18	$D, $(git ls-remote …), awk $2

One PR per plugin (each owns its plugin.json version + CHANGELOG.md) — 5 PRs. Remedy per the class-split comment above: hoist the shell logic into a bundled script invoked through ${CLAUDE_PLUGIN_ROOT} (harness-substituted to a literal path before any shell sees it), or rewrite the line $-free where a trivial form exists.

Undetermined, probe in flight: code-tidying:audit-comment-residue line 17 carries $NF inside awk single quotes — no probe has characterized awk positional parameters against the guard. A worktree-isolated probe (with echo ${HOME} as the negative control) is running; its disposition lands as a follow-up comment here. It is included in scope only if the probe refuses that form.

Explicitly NOT in scope (do not edit):

• session-flow:find-handoff and source-control:commit — their "$HOME/…" forms are recorded PASSes in this thread's probe table. Editing passing skills is the mistake class that produced fix(session-flow): move git out of skill pre-compute so worktree-isolated agents can invoke these skills #1676.
• All plugin-variable-only lines (Class 1): claude-config:audit-automation-gaps, prototype:*, code-tidying:tidy, claude-memory:audit lines 20–21, claude-ops:observability line 20, firecrawl:update.
• docs-hygiene grep '\.md$' trailing-$ lines — observed non-trigger (audit-noise loaded under isolation with one).
• The ${CLAUDE_SKILL_DIR} documentation/substitution question — tracked separately as skills: ${CLAUDE_SKILL_DIR} used in pre-compute but not documented as harness-substituted — three skills may silently report fake pre-compute data #1824.
• $-bearing shell in skill bodies and reference/ spokes — 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) #1691's surface, gate-fenced there.

Closure criterion

All five (or six) plugin PRs merged, plus post-ship verification: plugin update, then invocation of each fixed skill from an Agent with isolation: "worktree", with a negative control predicted to still refuse. Because no partial PR completes this, the PRs carry No linked issue + a ## Related reference here rather than a closing keyword — this issue must not auto-close again on a partial merge. It closes manually after verification.

[kyle-sexton]

This was generated by AI (autonomous drain lane; probe follow-up to the canonical-scope comment above).

Probe result — code-tidying:audit-comment-residue is OUT of scope

Worktree-isolated probe (fresh Agent with isolation: "worktree", one command per Bash call), negative control included:

#	command	result
1	echo hello	PASS
2	echo ${HOME} (negative control)	REFUSED — verbatim isolation-guard text
3	git status --porcelain 2>/dev/null | awk '{print $NF}' | head -5	PASS
4	same + grep -Ei '\.(cs|ts|md)$' | head -10 || echo "none" (the audit-comment-residue line-17 shape)	PASS
5	printf 'ref: refs/heads/main\tHEAD\n' | awk '/^ref:/{print $2; exit}' (the fanout awk-$2 shape)	PASS
6	git branch --show-current 2>/dev/null || echo "unknown"	PASS

The negative control refused, so the guard was active — the passes are meaningful. awk positional parameters inside single quotes ($NF, $2) do not trip the guard.

Dispositions:

• code-tidying:audit-comment-residue — its only genuine-shell candidate was the awk $NF; not affected, will not be edited. (Its ${CLAUDE_SKILL_DIR} line remains skills: ${CLAUDE_SKILL_DIR} used in pre-compute but not documented as harness-substituted — three skills may silently report fake pre-compute data #1824's separate question.)
• review:fanout — still in scope: line 18's $D assignment and $(git ls-remote …) / $(…) substitutions are the trigger, not its awk $2.

Canonical remainder is therefore exactly 5 plugins / 6 skills: claude-memory:audit, claude-ops:lanes, claude-ops:observability, education:teach, review:fanout. Implementation PRs (one per plugin) follow on this thread.

Caveat carried from the thread: this probes the isolation guard on standalone Bash calls, the same proxy every prior probe used; pre-compute injection is only end-to-end verifiable post-ship (version-keyed cache).