EnterWorktree fails from a subagent with a pinned cwd (isolation/explicit cwd), with no documented fallback

Summary

EnterWorktree unconditionally errors when called from within an agent/subagent that was spawned with a pinned working directory (either isolation: "worktree" on the parent's Agent call, or an explicit cwd override). The tool's own error message correctly diagnoses this but there's no way for that subagent to actually enter a worktree short of manually shelling out to git worktree add.

Repro

1. From a top-level session in a git repo, use the Agent tool to spawn any subagent (in our case a custom agent type, qa-orchestrator, invoked via Agent({ subagent_type: "qa-orchestrator", ... })).
2. Inside that subagent's turn, call EnterWorktree (e.g. EnterWorktree({ name: "some-branch-slug" })).
3. Observe:

``
<tool_use_error>EnterWorktree cannot create a worktree from a subagent with a cwd override (isolation: "worktree" or explicit cwd) — it would mutate the parent session's process-wide working directory. To work in a different directory (including a worktree), spawn an Agent with cwd set to it.</tool_use_error>
``

Why this is a real gap

Our project's CLAUDE.md has a hard rule: every task that edits a tracked file must start with EnterWorktree so work never lands directly on main/the primary checkout. We route multi-step "edit code" tasks to a custom subagent (qa-orchestrator) via the Agent tool specifically so it can do the actual editing work. But because that agent is always invoked as a subagent, EnterWorktree is never usable inside it — the hard rule as designed is structurally unsatisfiable by the exact agent meant to carry it out.

The subagent successfully worked around this by calling git worktree add <path> -b <branch> origin/main directly and doing the isolation/cleanup manually — so the capability clearly exists, it's just not reachable through EnterWorktree once you're already inside a pinned-cwd subagent.

Suggested fix (one of)

• Let EnterWorktree succeed inside a pinned-cwd subagent by scoping the cwd change to that subagent's own turn (not the parent session's process-wide cwd), since the tool already has the isolation logic to do this safely for the top-level session.
• Alternatively, if that's intentionally disallowed, document the manual git worktree add/git worktree remove fallback pattern in EnterWorktree's own tool description, so agents (and the humans reading transcripts) don't have to rediscover it via a runtime error each time.

Environment

• Claude Code CLI, custom subagent (.claude/agents/*.md) invoked via the Agent tool with subagent_type.
• Observed 2026-07-30.