claude-code - 💡(How to fix) Fix [BUG] bgIsolation worktree tries shared checkout edit before entering worktree

Preflight Checklist

• I have searched existing issues and this has not been reported with the same behavior yet
• This is a single bug report
• I am using the latest version of Claude Code

What's Wrong?

With worktree isolation explicitly enabled in settings.json:

{
  "worktree": {
    "baseRef": "head",
    "bgIsolation": "worktree"
  }
}

a background session still appears to attempt its first file modification in the shared/root checkout. That write/edit attempt is blocked or fails, and only after that failure does Claude Code create/enter a worktree and perform the change there.

So the final result is correct, but the execution path is unnecessarily:

1. Try to edit the shared/root checkout.
2. Get blocked/fail because background worktree isolation is required.
3. Create/enter a worktree.
4. Repeat the edit successfully inside the worktree.

This burns context and wall-clock time, and it makes the agent reason about a failure that should not happen when bgIsolation is already set to worktree.

What Should Happen?

When worktree.bgIsolation is worktree, background sessions should create/enter the worktree before the first write/edit attempt.

The first file-modifying tool call should target the isolated worktree. There should be no preliminary failed attempt in the project root/shared checkout.

Error Messages/Logs

Exact raw log text was not captured. The visible behavior is a failed/blocked first edit attempt against the root/shared checkout, followed immediately by worktree creation and a successful retry.

Steps to Reproduce

1. Use Claude Code v2.1.165.

2. Set the following in settings.json:

   {
     "worktree": {
       "baseRef": "head",
       "bgIsolation": "worktree"
     }
   }

3. Start a background session that needs to modify a file.

4. Observe the first file modification attempt.

5. Actual: the first edit/write targets the repo root/shared checkout and fails or is blocked. The session then creates/enters a worktree and succeeds on retry.

6. Expected: the session creates/enters the worktree first, then performs the initial edit there.

Claude Model

Not sure / Multiple models

Is this a regression?

I do not know.

Last Working Version

Unknown.

Claude Code Version

2.1.165 (Claude Code)

Platform

Other / normal Claude Code usage. Exact API platform was not specified.

Operating System

Ubuntu/Debian Linux

Terminal/Shell

bash

Additional Information

This looks related to the same background/worktree isolation area as these open reports, but it is not the same failure mode:

• #64640: remote-control sessions inherit worktree isolation defaults / baseRef behavior.
• #64452: a subagent already inside a worktree is blocked from Write/Edit.
• #48811: isolation: "worktree" is ignored for concurrent background agents.

This report is specifically about ordering: even with explicit "bgIsolation": "worktree" and "baseRef": "head", the session seems to spend one failed modification attempt in the shared checkout before entering the worktree. The eventual edit is correct, but the unnecessary failed attempt wastes tokens, context, and time.