claude-code - 💡(How to fix) Fix Background subagents cannot work in a separate worktree or run tooling commands (sandbox + cwd limitations) [1 comments, 2 participants]

Summary

Background subagents (the Agent tool called with run_in_background: true) cannot run a non-trivial autonomous workflow in an isolated worktree, because two limitations compound:

1. Subagents inherit the parent session's cwd and have no way to change it. EnterWorktree rejects with "cannot be called from a subagent with a cwd override". git checkout <branch> is denied by the bash sandbox in this context.
2. Subagents run under a tighter bash sandbox than the parent, and that sandbox does NOT appear to honor the project's .claude/settings.local.json permissions. Commands the parent can run freely (uv, make, npm, npx, node, gh, even echo and which) get denied in the subagent.

The combination makes the documented "spawn an autonomous agent in a worktree, do brainstorm → plan → TDD → review → PR" workflow impossible. The subagent can't reach the right worktree, and even if it could, it can't run any of the tools needed to verify the work.

Repro

In an existing repo with multiple git worktrees:

# Worktree A: where the parent session is running
.claude/worktrees/parent-session/  (branch: claude/parent-session)

# Worktree B: where we want the subagent to work
.claude/worktrees/feature-branch/  (branch: feature-branch, off main)

.claude/settings.local.json (in the parent's worktree, both worktrees share .git) contains:

{
  "permissions": {
    "allow": [
      "Bash(make:*)", "Bash(uv:*)", "Bash(npm:*)", "Bash(npx:*)",
      "Bash(node:*)", "Bash(git:*)", "Bash(gh:*)",
      "Bash(command:*)", "Bash(which:*)", "Bash(cd:*)",
      "Bash"
    ]
  }
}

Spawn a background subagent:

Agent(
  subagent_type="general-purpose",
  run_in_background=True,
  prompt="""
  cd into /Users/me/repo/.claude/worktrees/feature-branch.
  Run `make sync`, then `make test-unit`.
  Implement the plan, push, open PR.
  """
)

Observed:

• The subagent reports its cwd is the parent's worktree, not the path it was told to use.
• cd /Users/me/repo/.claude/worktrees/feature-branch is denied.
• git checkout feature-branch is denied.
• EnterWorktree returns "cannot be called from a subagent with a cwd override".
• Bare make, uv, npm, gh --version, which uv, even echo "$PATH" are denied — yet all of these are runnable from the parent session in the same harness, with the same settings file.

Expected:

• Either: subagents should be able to switch into a target worktree (via EnterWorktree or cd), OR the prompt's cwd parameter should be honored when the subagent is spawned.
• Subagent bash sandbox should respect the same .claude/settings.local.json rules the parent uses, OR there should be a documented way to pass permissions through to the subagent.

Why this matters

The Anthropic docs describe subagent-driven-development and using-git-worktrees as a flagship pattern: spawn a worktree, dispatch a subagent to do TDD inside it, get a PR back. With the current behavior:

• The "in a worktree" half of the workflow doesn't function — subagents are stuck in the parent's cwd.
• The "TDD" half doesn't function — they can't run any test command.
• The "PR" half doesn't function — gh is denied.

Net: subagents are usable for read-only research (Read, Grep, Glob), but not for the autonomous lifecycle workflows the documentation suggests.

Workaround

Drop the autonomous-subagent dream and have the parent session do the work directly, foregoing the parallel-execution advantage subagents are supposed to provide.

Environment

• Claude Code version: as of 2026-05-04
• OS: macOS Darwin 24.6.0
• Shell: zsh
• Subagent type: general-purpose (also tried with explicit subagent_type="general-purpose" and the result is the same)

Suggested fix priorities (in user-impact order)

1. Make subagents respect .claude/settings.local.json. Even if they keep a stricter default, allowing project-local opt-in fixes 80% of the lifecycle.
2. Allow subagents to switch worktrees — at minimum, accept a cwd or worktree_path parameter to the Agent tool, OR allow EnterWorktree from a subagent under explicit user-permission.
3. Document the current limitations in the subagent-driven-development and using-git-worktrees skills so users don't bake the wrong workflow into their muscle memory (as I did — three dispatches before realizing it wouldn't work).

Happy to provide a session transcript privately if helpful.