Every skill's start preamble is refused by worktree-isolated Claude Code sessions (compound shape; 49 SKILL.md files)
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Symptom
Claude Code sessions that are **isolated to a git worktree** refuse to run the skill-start preamble that every gstack skill ships. The operator has to hand-rewrite a documented command before any skill can start, on every invocation.
Verbatim refusal:
```
This session is isolated in the worktree /path/to/repo/.claude/worktrees/,
but this command is too complex to verify that it stays inside the worktree. Refusing
to run it — a worktree-isolated session's git operations must target its own worktree.
Split it into plain, separate commands and run them from ...
```
## What is refused
The shipped preamble, verbatim:
```bash
_SS="$HOME/.claude/skills/gstack/bin/gstack-skill-start"
[ -x "$_SS" ] || _SS=".claude/skills/gstack/bin/gstack-skill-start"
"$_SS" --skill "review" --model "claude" --parent-pid "$PPID" \
|| echo "SKILL_START: unavailable — stale install; run ./setup or /gstack-upgrade (...)"
```
The harness objects to the **compound shape** — variable assignment, a conditional fallback, then an invocation through the variable — not to any individual command. It cannot statically verify the whole thing stays inside the worktree.
## Scale
In the installed tree at `07b59e3`:
- **49** `SKILL.md` files carry that skill-start preamble
- **41** carry the `eval "$(~/.claude/skills/gstack/bin/gstack-slug ...)"` context snippet, refused for the same reason
So this is every skill, every invocation, for any session running in an isolated worktree.
## Provenance — please read, the two halves differ in strength
- **Verified directly:** the preamble shape above, and the 49/41 counts, checked against the installed tree.
- **Reported, not reproduced by me:** the refusal itself. My session is not worktree-isolated, so I cannot trigger it. The verbatim message and the repeated hits come from a colleague's session running in `.claude/worktrees/`, which is that workflow's default. I am filing rather than relaying because the shape is verifiable and the fix is in gstack's templates either way.
Anyone with a worktree-isolated Claude Code session should reproduce it by invoking any gstack skill.
## Suggested fix
Any of these, in the templates:
1. **Resolve the binary in one absolute-path line** and drop the `[ -x "$_SS" ] ||` fallback chain. Smallest change. The fallback covers a vendored `.claude/skills/gstack` layout that is deprecated anyway.
2. **Split the preamble into separate plain commands**, so each is individually verifiable. This is the general fix — the objection is to compound shape, so anything compound will keep hitting it.
3. **Make the snippets tolerate line-by-line execution**, which is what an operator ends up doing regardless.
2 is the durable one. 1 is a one-line improvement worth taking on its own.
## Why it is worth fixing rather than documenting
The workaround has been known locally for over three weeks and recorded as two separate operator-side notes. It works, and it costs a hand-rewrite of a documented command every single time. A workaround that stable is a signal the defect should move into the tool.
Contributor guide
Research direction
Search the 49 SKILL.md files for the shown gstack-skill-start preamble and the 41 files containing the gstack-slug context snippet. Inspect the corresponding templates and choose a command form that worktree-isolated Claude Code sessions can verify, then invoke a skill in an isolated worktree to confirm the refusal no longer occurs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, shell
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 66/100