claude-code - 💡(How to fix) Fix Background `claude` subagent_type auto-wraps in git worktree; `general-purpose` does not; doc says neither should

Summary

Background Agent calls with subagent_type: "claude" are wrapped in a temporary git worktree even when isolation is not set. Background Agent calls with subagent_type: "general-purpose" are not. The Agent tool documentation describes isolation: "worktree" as the explicit opt-in for worktree wrapping, with no mention of subagent-type-based defaults.

Expected

Per the tool docs: "With isolation: \"worktree\", the worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result."

Reading: no isolation → no worktree, regardless of subagent_type or run_in_background.

Actual

subagent_type: "claude" + run_in_background: true (no isolation set) → agent runs in .claude/worktrees/agent-<id>/ on a fresh worktree-agent-<id> branch, marked locked.

subagent_type: "general-purpose" + run_in_background: true (no isolation set) → agent runs in the main checkout.

Repro

Two identical probes, only subagent_type differs. Each runs:

1. pwd
2. git rev-parse --show-toplevel
3. git rev-parse --abbrev-ref HEAD
4. git worktree list

Probe A — subagent_type: "general-purpose", run_in_background: true

pwd:              /Users/<me>/path/to/repo
show-toplevel:    /Users/<me>/path/to/repo
HEAD:             master
worktree list:    only the main checkout (plus unrelated pre-existing entries)

→ no worktree created.

Probe B — subagent_type: "claude", run_in_background: true

pwd:              /Users/<me>/path/to/repo/.claude/worktrees/agent-add6c5c1b313d3ae0
show-toplevel:    /Users/<me>/path/to/repo/.claude/worktrees/agent-add6c5c1b313d3ae0
HEAD:             worktree-agent-add6c5c1b313d3ae0
worktree list:    main + .claude/worktrees/agent-add6c5c1b313d3ae0  [locked]

→ worktree created automatically. The completion notice did include a <worktree> block (because the probe wrote a tracked file, so the harness kept the worktree).

Why it matters

Skills that spawn claude bg agents and expect them to share the main checkout's filesystem can silently lose work:

1. Skill spawns claude bg agent (no isolation set, expects main checkout).
2. Agent writes deliverables to a gitignored path (_OUTPUT_/, dist/, tmp/, etc.).
3. Git sees zero changes in the implicit worktree.
4. Harness auto-removes the "unchanged" worktree on completion (per the documented rule).
5. The completion notice arrives without a <worktree> block (worktree already gone, no path to surface).
6. Deliverables are destroyed before the orchestrator can copy them out.

The orchestrator has no signal that a worktree was ever involved, so it looks like the agent simply failed to produce output.

Asks

One of:

• Doc fix — document that subagent_type: "claude" implies isolation: "worktree" (and any other implicit couplings).
• Behavior fix — make claude honor the documented "explicit opt-in only" rule for worktree wrapping.
• Either way — when the harness auto-removes a worktree because git sees no changes, surface a warning in the completion notice ("worktree auto-removed; if your agent wrote to gitignored paths those files are gone"). Silent destruction is the painful part.

Environment

• Claude Code on macOS (Darwin 25.4.0)
• Reproduced on a clean repo with the two probes above.