fix(skills): worktree-isolated agents cannot invoke a skill whose pre-compute block contains a $-expansion (21 skills; NOT git — see correction comment)

[kyle-sexton]

Summary

A worktree-isolated agent (Agent with isolation: "worktree", or any subagent with a pinned cwd)
cannot invoke any skill that declares two or more ! precompute commands when at least one is a
git command. The invocation fails before the skill body is ever reached.

Discovered while running /session-flow:handoff at the end of an inbox item. It is not a
handoff-specific bug — handoff is just where it surfaced. 42 skills across this marketplace
match the pattern, including most of the core workflow: source-control:commit,
source-control:pull-request, source-control:worktree, implementation:implement,
verification:confirm, review:fanout, session-flow:retro, session-flow:handoff,
planning:plan, testing:plan, toolchain:check.

Reproduction

From an agent isolated in .claude/worktrees/<name>:

Skill(session-flow:handoff)

fails with:

This agent is isolated in the worktree C:\...\.claude\worktrees\agent-a4324d31193dece2f, but this
command is too complex to verify that it stays inside the worktree; break it into plain, separate
commands. Refusing to run it — a worktree-isolated agent's git operations must target its own
worktree.

Identical failure with and without arguments. The skill body never runs.

Root cause

plugins/session-flow/skills/handoff/SKILL.md declares four precompute lines:

Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`
Claude session: !`echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown"`
Uncommitted changes: !`git status --porcelain 2>/dev/null | head -20 || echo "clean"`
Recent commits: !`git log --oneline -5 2>/dev/null || echo "no commits"`

Each line passes the guard individually — verified one at a time:

precompute line	result
git branch --show-current 2>/dev/null || echo "unknown"	ok — main
git status --porcelain 2>/dev/null | head -20 || echo "clean"	ok — (clean)
git log --oneline -5 2>/dev/null || echo "no commits"	ok — 5 commits

Joined with ; into a single invocation, the exact guard error reproduces:

git branch --show-current 2>/dev/null || echo "unknown"; echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown"; git status --porcelain 2>/dev/null | head -20 || echo "clean"; git log --oneline -5 2>/dev/null || echo "no commits"

…this command is too complex to verify that it stays inside the worktree…

So the skill runner appears to concatenate all ! precompute commands into one shell
invocation. The guard's complexity heuristic rejects the compound form, even though every component
is individually safe and every one of them is read-only.

Blast radius

Counted across plugins/**/SKILL.md:

• 172 ! precompute lines across 62 skills
• 123 git-bearing precompute lines across 49 skills
• 42 of those 49 declare two or more git precompute lines

Any skill with ≥2 precompute lines and ≥1 git command is affected, so the true count is at least 42.

This makes worktree-isolated agents unable to use the marketplace's own core workflow skills — which
is precisely the context those skills are most needed in, since CLAUDE.md and the worktree
convention push agents into worktrees for parallel work.

Impact

Fails closed and loudly, which is the good news — no silent degradation, no wrong output. But the
skill is simply unavailable, and the fallback is for the agent to hand-write whatever the skill would
have produced. In the session that found this, the handoff document had to be written by hand and
could not be placed in its canonical .work/handoffs/ location at all (see the second issue below).

Suggested directions (not verified end to end)

1. Run precompute commands separately rather than joined. Each line already passes the guard on
   its own; if the runner issued them as N invocations, the problem disappears with no change to any
   skill. This looks like the correct fix and it is upstream of the marketplace.
2. Failing that, simplify the precompute lines in the affected skills so the joined form stays
   within the guard's tolerance — e.g. drop the || echo "…" fallbacks, which mostly guard against a
   non-git directory that the guard itself already implies is not the case.
3. Degrade rather than abort. A precompute that cannot run could yield an empty value and let the
   skill body proceed; every one of these lines is contextual, none is load-bearing for correctness.

Direction 1 is the only one that fixes all 42 skills at once, but it may live in the harness rather
than in this repository — worth confirming before any skill here is edited.

Related observation (separate, may warrant its own issue)

A cwd-pinned subagent also cannot call ExitWorktree:

ExitWorktree cannot be called from a subagent with a cwd override … This agent is already
isolated; use Bash with cd for directory changes within it.

Combined with the guard refusing writes to the shared checkout, an isolated agent has no path to
write a file that is meant to live outside its worktree — such as a handoff in .work/handoffs/,
which is deliberately shared so it survives worktree cleanup. In this session the worktree was
reclaimed by cleanup within minutes of the merge, so a handoff written inside it would have been
destroyed anyway.

[kyle-sexton]

Diagnosis completed — with a control experiment, and the "complexity" framing in the issue body was wrong

I went back and tested this properly rather than trusting the guard's own wording. Complexity is
not the trigger. The presence of git in the composed precompute command is.

Control experiment

skill	precompute lines	contains git?	result under worktree isolation
session-flow:handoff	4 (pipes, ||, redirects)	yes (3)	REFUSED by the guard
session-flow:find-handoff	4 (pipes, ||, redirects)	yes (1)	REFUSED by the guard
knowledge:course-digest	4 (pipes, ||, two multi-statement node -e payloads)	no	RAN — precompute output rendered normally

course-digest's precompute is unambiguously more complex than handoff's — it embeds two
inline Node programs with require, process.env, ternaries and fs.existsSync calls — and it
sails through. So the guard is not rejecting compound shell.

Why find-handoff is the decisive case

find-handoff has exactly one git precompute line among four:

Claude session: !`echo "${CLAUDE_CODE_SESSION_ID:-unknown}" || echo "unknown"`
Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`
Default-location handoffs: !`ls -1t .work/handoffs/*-handoff-*.md 2>/dev/null | head -5 || echo "none…"`
Transcript project dirs: !`ls -1dt "${HOME}/.claude/projects/"*/ 2>/dev/null | head -8 || echo "none"`

That single git line passes the guard when run on its own — I ran the exact string and got
main. The other three contain no git at all. Yet the skill is refused.

If precompute commands were evaluated individually, nothing here would trip. They are therefore
not evaluated individually — the harness composes them into one shell invocation, that
invocation contains git, and the worktree guard refuses a git-bearing command whose target it
cannot statically verify.

Where the fix lives

Both halves are harness-owned, not marketplace-owned:

• The guard string (too complex to verify that it stays inside the worktree, isolated in the worktree) appears nowhere in this repository, and nowhere in ~/.claude/settings.json,
  ~/.claude/hooks, or ~/.claude/references. It is not a plugin hook we control.
• Precompute is documented harness preprocessing:
  https://code.claude.com/docs/en/skills#inject-dynamic-context — "The !`<command>` syntax
  runs shell commands before the skill content is sent to Claude… This is preprocessing, not
  something Claude executes."

Notably the same page says "Each !`<command>` executes immediately", which reads as
per-command execution. The observed behaviour contradicts that, so either the composition is an
undocumented implementation detail or the docs are imprecise — worth raising upstream either way.

So the root fix is not actionable in this repository.

But there IS an actionable in-repo workaround, and it is now proven

Since a precompute block with no git runs fine under isolation, any affected skill can be made
isolation-safe without touching the harness:

1. Move git context out of precompute and into the skill body, acquired with ordinary Bash tool
   calls. This is the cleanest option and loses nothing — a worktree-isolated agent can run
   git branch --show-current, git status --porcelain, and git log --oneline -5 perfectly well
   one at a time (I did so throughout the session that found this). Cost is one extra round-trip and
   the model doing the acquisition rather than the preprocessor.
2. Drop the git precompute lines where the value is merely contextual. For handoff
   specifically, branch/status/log are nice-to-have framing, not load-bearing for correctness.
3. Leave it and accept the skill is unavailable to isolated agents — the status quo, which is
   the worst option for exactly the 42 skills most needed in worktree workflows.

Option 1 is the one I would take, and it is a mechanical, testable change per skill.

Suggested split

This issue is really two:

• (upstream) precompute commands should be issued individually, as the docs describe — fixes all
  42 skills at once, no marketplace change.
• (here) migrate git precompute out of the affected skills as a workaround until that lands.

Happy to take the second on a per-plugin basis; the first needs to go to Anthropic.

[kyle-sexton]

This was generated by AI during triage.

Triage: the defect is real and reproducible — but the stated predicate is falsified, and 42 is not the blast radius

This was verified by running real worktree-isolated agents against real skills, not by re-reading the report. Three independent isolated agents, fresh contexts, different worktrees.

The bug reproduces exactly as described

Skill(session-flow:handoff) from a worktree-isolated agent errors before the skill body loads, with the guard text the report quotes verbatim. Confirmed 3 out of 3 attempts across 2 separate agents, including a same-agent repeat — deterministic, not a flake.

The report's supporting reproduction also holds. In an isolated worktree:

• each of the three git precompute commands run as its own Bash call → succeeds
• the same commands joined with ; into one Bash call → refused, identical guard text

So the report is right that a joined form is refused where the components are individually fine, and right that the failure is loud and fails closed. That much is solid and needed no defence.

What the count claims actually check out to

The grep-level tallies mostly reproduce against origin/main (fe331930), with drift consistent with the tree having moved since filing:

Reported	Measured now
172 precompute lines / 62 skills	181 / 65
123 git-bearing lines / 49 skills	125 / 49
42 with ≥2 git precompute lines	42 — reproduces exactly

So 42 is an honest count. It is just not a count of affected skills.

The predicate does not predict failure — this is the finding

The report states: "Any skill with ≥2 precompute lines and ≥1 git command is affected, so the true count is at least 42." Directly tested:

Skill	Precompute block	Result
session-flow:handoff	4 lines, 3 git	ERRORED
session-flow:orient	4 lines, 3 git	ERRORED
session-flow:retro	5 lines, 4 git	ERRORED
review:fanout	5 lines, 4 git	ERRORED
source-control:commit	8 lines, 6 git	loaded fine
planning:plan	3 lines, 3 git	loaded fine
discovery:explore	3 lines, 3 git	loaded fine
docs-hygiene:audit-noise	3 lines, 2 git	loaded fine
toolchain:check	2 lines, 2 git	loaded fine
toolchain:lint	2 lines, 2 git	loaded fine
docs-hygiene:compress	2 lines, 2 git	loaded fine

7 of 11 skills satisfying the report's predicate load without incident. Every one of them is on the list of 42.

Order was ruled out as the confound: one agent invoked commit as its very first tool call (loaded), then handoff (errored); another invoked orient first (errored). Results are stable per skill regardless of position.

The stated root cause is therefore under-determined

The report infers the runner "concatenates all ! precompute commands into one shell invocation" and that the complexity heuristic rejects the compound form. If that were the whole story, source-control:commit would be the first casualty — it has the largest precompute block in the marketplace and by far the hairiest lines, including command substitution, { … } grouping, a ${R:-} parameter expansion, and chained &&/||. It loads. Meanwhile handoff's four comparatively plain lines are refused.

Every simple discriminator was checked against the observed results and each is contradicted by at least one row: it is not the line count, not the git-command count, not the presence of 2>/dev/null, not git status --porcelain | head, not || fallbacks, and not ${VAR:-default} expansion. Whatever the guard is keying on, this triage could not isolate it, and neither the report's explanation nor any hypothesis tried here survives the data.

That is not a reason to doubt the bug. It is a reason not to act on the stated mechanism.

Consequences for the suggested directions

• Direction 1 (run precompute commands separately) may well be correct, but the report itself says it "may live in the harness rather than in this repository." The guard is Claude Code's, not this marketplace's. Nothing here can implement it; the choice is to depend on an upstream fix we do not own.
• Direction 2 (simplify the affected skills' precompute lines) is the in-repo option and is now far more attractive than the report assumed — the confirmed set is 4, not 42. But "simplify until it passes" cannot be aimed without knowing the trigger, so it risks cargo-culting edits across skills that were never broken.
• Direction 3 (degrade rather than abort) is also harness-side.

Why human-gated rather than agent-ready

1. Cross-repo ownership is unresolved. The most likely correct fix is upstream in the harness. Deciding between waiting on an upstream fix and working around it locally is a cross-repo policy call, and the report explicitly flags it as needing confirmation "before any skill here is edited."
2. The mechanism is unknown. A worked example of what an agent would otherwise do — trust "42", edit 42 skill files, and change 38 that were never broken — is exactly the outcome this triage exists to prevent. Under this repo's fresh-docs mandate every one of those files is a contract surface.
3. It bundles a second, distinct problem. The closing observation — a cwd-pinned subagent cannot call ExitWorktree, and combined with the write guard has no path to write a file outside its worktree, such as the deliberately-shared handoff location — is a different defect with a different owner. The report says it "may warrant its own issue"; it does. Splitting it is a maintainer call, not something to decide inside a fix PR.

For whoever picks this up

• Do not use 42. Re-derive the affected set empirically by invoking skills from worktree-isolated agents. It is a per-skill observation; no static grep predicate tested here predicts it.
• Isolate the trigger before editing anything. The cheapest experiment: in a throwaway worktree, remove precompute lines from session-flow:handoff one at a time and re-invoke until it loads. That identifies the offending construct in minutes and turns direction 2 from guesswork into a targeted change.
• Confirmed-failing so far: session-flow:handoff, session-flow:orient, session-flow:retro, review:fanout. Three of the four are session-management skills, which is worth noting given they are most needed in exactly the isolated, disposable context where they fail.
• Confirmed-working, so leave alone unless the trigger analysis says otherwise: source-control:commit, planning:plan, discovery:explore, docs-hygiene:audit-noise, toolchain:check, toolchain:lint, docs-hygiene:compress.
• Nothing was edited and no skill's work was performed during this verification; every probe stopped at body load.

On priority

Filed priority: medium. It fails closed and loudly with no silent degradation or wrong output, and the confirmed set is 4 skills rather than the reported 42 — but the impact on those 4 is total, and the worktree convention actively pushes agents into the context where they break. If the empirical enumeration comes back substantially larger than 4, this should be re-rated up rather than left at the tier this triage assigned on a 4-skill sample.

_{Role labels resolved from .work-item-tracker.json, which declares no config.role_labels — the canonical roles therefore run on their documented defaults (agent-ready / needs-human); both were confirmed present in this repo's live label set before use.}

[kyle-sexton]

Probe results — the composition mechanism is now confirmed, not inferred

Run from a real Agent with isolation: "worktree" at main = f6fda808. Everything below is
observed, not derived.

The decisive pair

skill	precompute lines	git lines	result
code-tidying:batch-simplify	1	1 (compound: 2>/dev/null || echo)	LOADED — returned the branch name
knowledge:course-digest	4 (pipes, redirects, ||)	0	LOADED
session-flow:find-handoff	4	1, pipe-free, byte-identical in shape to the passing one	REFUSED
session-flow:handoff	4	3	REFUSED

batch-simplify and find-handoff are the discriminator: the same git precompute line passes
alone and fails inside a multi-line block. That rules out per-line evaluation, and it also
falsifies the narrower "just simplify each git line" theory — find-handoff's git line has no pipe
and is about as simple as a git precompute line gets.

Refusal text, verbatim and identical for both refused skills:

This agent is isolated in the worktree C:\…\.claude\worktrees\agent-…, but this command is too
complex to verify that it stays inside the worktree; break it into plain, separate commands.
Refusing to run it — a worktree-isolated agent's git operations must target its own worktree. Run
the equivalent from C:\…\.claude\worktrees\agent-… without the redirect.

Note the tail of that message: it names a redirect, but course-digest is full of redirects and
loads fine. The redirect is not the trigger; git inside a composed block is.

Rule, as observed: a skill is refused iff its precompute block contains a git command and
has more than one precompute line.

The fix is viable — this was the load-bearing unknown

Four ordinary git commands, each as its own Bash call from inside the isolation:

• git rev-parse --show-toplevel — PASS
• git branch --show-current — PASS
• git status --porcelain — PASS
• git log --oneline -5 — PASS

So "delete the git precompute lines and re-acquire the values in the skill body, one command per
Bash call" works. That was previously inferred from the rejection reason and had never been tested.

Corrected blast radius

Repo-wide sweep of plugins/**/SKILL.md at 9f73fc2e, classified by total precompute lines:

• 49 skills have at least one git precompute line.
• 6 of those have a single precompute line and therefore load today:
  code-tidying:batch-simplify, discovery:research, discovery:research-deep,
  planning:audit-answers, planning:design, planning:design-handoff.
• 43 have a multi-line block and are refused in a worktree-isolated agent — spanning
  18 plugins: session-flow (7), planning (7), source-control (5), testing (4), docs-hygiene (4),
  discovery (4), code-tidying (3), toolchain (2), review (2), prototype (2), claude-ops (2), and one
  each in verification, repo-hygiene, implementation, debugging, codebase-health, bug-report,
  architecture.

Two of the 43 were verified by direct invocation; the other 41 are classified by the confirmed
mechanism, not individually invoked.

This supersedes the ready-to-apply spec's file list, which covers session-flow + source-control
only — 12 of the 43. The spec's per-file rule and its verification method are both still correct;
only its scope was short.

Scoping consequence

Each plugin owns its own plugin.json version and CHANGELOG.md, so a full remediation is one PR
per affected plugin — 18 PRs, not 2. Worth deciding explicitly whether to do the full sweep, do
the highest-traffic plugins first and track the rest, or hold.

Also worth noting: research / research-deep / design / design-handoff sit in the
loads-today set only because they have exactly one precompute line. Any future PR that adds a second
precompute line to one of them silently moves it into the refused set. That is a sharp edge no gate
currently catches.