Worktree session preamble has no carve-out for cross-worktree git operations like merge-back

Resolved 💬 1 comment Opened May 22, 2026 by caseymarquis Closed Jun 21, 2026

What happened

In a Claude Code session running inside a git worktree, I finished a
chunk of work and was asked to merge the worktree's branch back into
dev on the primary checkout. The canonical merge command would have
been:

cd /home/casey/code/its-monorepo
git merge --ff-only worktree-20260522-2-multi-worktree-multi-claude-dx

But the session preamble said:

This is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT cd to the original repository root.

So I used a backdoor: git update-ref refs/heads/dev HEAD from the
worktree. That moves the dev ref to my commit without checking
anything out, which sidesteps the "branch checked out in another
worktree" guard. It worked — dev now reaches my commit — but it
left the primary checkout's working tree stale relative to its
branch's new tip. The user has to cd over and git checkout dev
(or git reset --hard HEAD) to resync, which is exactly the kind of
"why does my checkout look weird?" surprise good tooling should
prevent.

Why this happened

I treated the "Do NOT cd" instruction as absolute, including for
cross-worktree git operations where stepping into the primary
checkout is the natural and clean path. The instruction's intent —
keep the agent's edits inside the isolated worktree — is good, but
it didn't anticipate the inevitable "this work is ready, get it onto
the canonical branch" step.

Suggested fix

The harness preamble for worktree sessions should carve out an
exception: cd to the primary checkout is permitted for cross-
worktree git operations (merge / push / branch-update). Without a
carve-out, agents are left choosing between rule-bending and
plumbing tricks, and the plumbing tricks leave the primary checkout
in a worse state than a proper merge would.

A more conservative alternative would be a dedicated harness tool
(e.g. MergeWorktree) that performs the merge cleanly from the
worktree side, but a carve-out is simpler and covers the broader
class of cross-worktree git ops.

Environment

  • Claude Code session in a worktree at .claude/worktrees/<name>/
  • Branch checked out in worktree, dev checked out in primary
  • Conventional FF-merge blocked by the preamble's cd rule

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗