[Bug] Skill dynamic-context injection (!`cmd`) failure semantics undocumented; non-zero exit aborts skill load

Status Open
Reported on v2.1.222
Maintainer reply None cached
Activity 0 comments · opened Aug 5, 2026

Bug Description

  1. Skills docs — !command`` injection failure semantics undocumented

Title: Docs: skill dynamic-context injection (!cmd) doesn't document exit-code, stderr, cwd, or failure semantics

The "Inject dynamic context" section of https://code.claude.com/docs/en/skills documents
that !command runs at preprocessing time and that its output replaces the placeholder,
but not what happens when the command misbehaves. Empirically (v2.1.209–2.1.222):

  • A non-zero exit aborts the ENTIRE skill load ("Shell command failed for pattern…") —

the skill is unavailable for that invocation, not just missing one block. This makes
exit-code hygiene load-bearing for skill authors (e.g. a health-check script that
exits 1 on findings kills its own skill), yet it is undocumented.

  • Only stdout appears to be captured; stderr is silently dropped.
  • The working directory is the session's current cwd (which moves if Bash cd'd

elsewhere), not the project root.

  • No timeout or output cap is documented either way.

Request: document these four semantics on the skills page. The failure-mode one matters
most — authors currently discover "non-zero exit = skill gone" in production. A gentler
alternative (inject the error text instead of aborting the load) would also be worth
considering as a product change.

  1. Worktrees docs — the isolation guard's command-shape refusals undocumented

Title: Docs: worktree-isolation Bash guard ("too complex to verify") is undocumented — including that it applies to non-git commands

Sessions/agents isolated in a worktree (--worktree, Agent isolation: "worktree",
EnterWorktree) run a built-in guard on every Bash call that can refuse commands with:

"…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 session's git
operations must target its own worktree. Run the equivalent from <root> without the
redirect."

https://code.claude.com/docs/en/worktrees does not mention it; the sub-agents page
documents only the working-directory half (v2.1.203/v2.1.210 notes). Observed on
v2.1.222, the refusal fires on command shape, not git content: >&-style dup redirects
(including the ubiquitous 2>&1), while/until/if/case constructs, heredocs, brace
expansion, and runtime-computed redirect targets are refused even when the command
contains no git at all. The message says "git operations", which misleads users whose
non-git command was refused (e.g. until pgrep …; do sleep 5; done).

This interacts badly with skill dynamic-context injection: an injected !cmd containing
2>&1 is refused in isolated sessions, and the resulting non-zero exit aborts the whole
skill load — a skill that works everywhere else silently fails to load only in worktree
sessions.

Request: document on the worktrees page (1) that the guard exists and is built-in,
(2) which constructs are refused vs analyzed, (3) that it applies to all Bash commands
in isolated sessions, not just git, and (4) whether any opt-out is intended (none exists
today). Fixing the error message to not say "git operations" for non-git refusals would
help too.

Environment Info

  • Platform: darwin
  • Terminal: ghostty
  • Version: 2.1.222
  • Feedback ID: 4520e283-dfcc-47cb-892e-9412e7a2cf9a

Errors

[]

View original on GitHub ↗