Agent tool: isolation: "worktree" creates worktree from default branch instead of parent HEAD

Status Fixed / completed

Reported on v2.1.138

Maintainer reply ✓ Yes — claude[bot]

Activity 4 comments · opened May 10, 2026 · closed May 10, 2026

💡 Likely answer: A maintainer (claude[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

When dispatching a subagent via the Agent tool with isolation: "worktree", the created git worktree is sometimes based on the repository's default branch (main) or the initial commit, rather than the parent session's current HEAD. This causes subagents to operate on a stale tree and either silently regress files or fail downstream consistency checks.

Environment

Claude Code 2.1.138
macOS (Darwin 25.3.0)
Repos affected: multiple, all using a feature/epic branch off develop (i.e. not the repository's default branch)

Reproduction

In a git repo, check out a feature/epic branch that is not the repository's default branch and has commits beyond it.
From a Claude Code session on that branch, dispatch a subagent with isolation: "worktree".
Have the subagent run git rev-parse HEAD and git log -1 --oneline as its first action.
Compare to the parent session's git rev-parse HEAD.

Expected: worktree HEAD == parent HEAD (or at minimum, contains parent HEAD as an ancestor with no divergence).

Actual: worktree HEAD is the repository's default branch tip, or in some cases the repository's initial commit. The current branch's commits are absent.

Impact

Subagents see "out-of-date" files (config, build manifests, lockfiles) and "helpfully fix" them, producing edits that look like regressions when merged. We have observed this twice in production multi-agent runs across two different repos.

Workaround

We routed around it by avoiding isolation: "worktree" entirely and running subagents in the parent checkout sequentially. We also added a guard that captures EXPECTED_BASE=\$(git rev-parse HEAD) in the parent and asks the subagent to verify on entry; the guard reliably fires when the bug occurs, confirming the divergence is between parent HEAD and worktree HEAD (not stale-parent vs current-parent).

Asks

Document what base ref isolation: "worktree" uses (HEAD? default branch? something else?).
If it is not parent HEAD, expose a parameter (e.g. worktreeBase: "HEAD" | <ref>) so callers can pin it.

View original on GitHub ↗

4 Comments

petervines · 5 months ago

Still reproduces on 2.1.138 (2026-05-10).

Test setup

Repository on branch main at commit 113ca78.
From the parent Claude Code session, ran:

``git checkout -b test-worktree-base-2026-05-10 date > .test-worktree-marker git add .test-worktree-marker && git commit -m "test: marker commit"`Parent HEAD nowb186e18 on the feature branch, one commit ahead of main (113ca78). The marker file .test-worktree-marker` exists only on the feature branch.

From that parent state, dispatched a subagent via the Agent tool with isolation: "worktree". The probe agent's only job was to report git rev-parse HEAD, git log -1 --oneline, git branch -a, and ls .test-worktree-marker. No file edits, no commits.

Result

Probe's worktree:

HEAD:    113ca78  ← main tip, NOT parent's b186e18
branch:  worktree-agent-a7a4a1126f52cac3c (branched off main)
marker:  ls: .test-worktree-marker: No such file or directory

The worktree was created from main rather than the parent's HEAD on the feature branch. The marker file added in the feature commit is absent.

Cross-check

Initially I assumed v2.1.128's EnterWorktree fix and v2.1.133's worktree.baseRef setting had resolved this. A probe run from main itself returned the correct HEAD — but that's a false positive, since when the parent is on the default branch, parent HEAD ≡ default-branch-tip and the buggy and fixed paths are indistinguishable. The bug only surfaces when the parent is on a non-default branch with commits beyond it (the precondition in the original report). The Agent tool's isolation: "worktree" therefore appears to be a different code path from EnterWorktree, or the fix is incomplete.

petervines · 5 months ago

Update: workaround found, partially self-resolving.

After more research, this isn't strictly a bug — the behavior I observed is the documented default (worktree.baseRef: "fresh" = origin/<default>). The fix for my use case is the project setting:

// .claude/settings.json
{"worktree": {"baseRef": "head"}}

This applies to all worktree surfaces — --worktree, EnterWorktree, and Agent-tool isolation: "worktree" — confirmed by re-running the same feature-branch repro on v2.1.138 with the setting in place: worktree HEAD now matches parent HEAD as expected, and the marker file from the feature commit is present in the worktree. Setting takes effect mid-session.

The docs gap that misled me: this is documented at https://code.claude.com/docs/en/worktrees ("Choose the base branch") but does not appear on the settings reference page, which is what I checked first. That gap is already tracked in #57148.

What I'd still like from this issue

The framing as "bug" is wrong, but two asks remain valid as feature requests:

Per-call override on the Agent tool — currently worktree.baseRef is a session/settings-level knob; there's no way for a controller to dispatch one subagent rooted at parent HEAD and another rooted at origin/main. A worktreeBase: "head" | "fresh" | <ref> parameter on the Agent tool would close this.
Surface the default in the Agent tool docs / parameter help — the isolation: "worktree" description should mention that base ref selection is governed by worktree.baseRef, so users don't need to discover it via the worktrees docs page.

Feel free to close, repurpose, or split into a separate feature-request issue — whichever is most useful.

claude[bot] contributor · 5 months ago

This issue was fixed as of version 2.1.133.

github-actions[bot] · 3 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.