claude-code - 💡(How to fix) Fix `bgIsolation` guard recovery path is broken: error tells agents to call `EnterWorktree`, which is a deferred tool

Summary

The bgIsolation guard refuses Edit/Write in a background session that hasn't called EnterWorktree, and the error tells the agent the recovery path:

"This background session hasn't isolated its changes yet. Call EnterWorktree first so edits land in a worktree instead of the shared checkout, then retry this edit using the worktree path."

But EnterWorktree is a deferred tool in current Claude Code (its schema is not loaded; it must be fetched via ToolSearch first). The guard message doesn't mention this. Agents that follow the instruction literally either:

1. Call EnterWorktree directly and get InputValidationError (tool not loaded), or
2. Don't connect "the worktree path" with "the cwd EnterWorktree returns," re-issue Edit on the original path, hit the guard again, and bail.

End-result: from the user's perspective, the Edit tool appears to return a mysterious internal error and subagents stall. The first error message (the actual guard) gets buried under a follow-on InputValidationError, so the user-visible symptom is just "Edit broke."

Environment

• Claude Code v2.1.150
• Windows 11 Pro 10.0.26200, PowerShell
• Subagents dispatched via the vanilla Agent tool (no isolation parameter set)
• Project has no .claude/settings.json override for worktree.bgIsolation

Evidence from session logs

Deferred-tool list shown to background sessions (confirmed in this session's SessionStart system reminder) includes EnterWorktree:

"The following deferred tools are now available via ToolSearch. Their schemas are NOT loaded — calling them directly will fail with InputValidationError: CronCreate, CronDelete, ... EnterWorktree, ExitWorktree, ..."

Guard fire from a background session transcript under ~/.claude/projects/<project>/<session>.jsonl:

[191] tool_use Write {"file_path": "<repo>\\.mise.local.toml"}
[192] tool_result ERR: <tool_use_error>This background session hasn't isolated its changes yet.
       Call EnterWorktree first so edits land in a worktree instead of the shared checkout,
       then retry this edit using the worktree path. (To disable this guard for this repo,
       set `"worktree": {"bgIsolation": "none"}` in .claude/settings.json.)</tool_use_error>
[194] text: "The background isolation guard won't let me write directly to your main checkout
       — but this is a 4-line file, so let me just give you the command. Paste this into your
       PowerShell at the repo root: ..."

Note step 194: the agent did not attempt ToolSearch + EnterWorktree. It rationalized failure and asked the user to run the command manually. This is the recovery the guard's message implicitly relies on, and it doesn't happen.

Repro

1. Start a background claude session in a git repo (no worktree.bgIsolation override).
2. From the parent session, dispatch a subagent with Agent and instruct it to write a small new file (no isolation: "worktree").
3. Observe: the subagent's first Edit/Write returns the guard error, and the subagent typically either errors with InputValidationError on a direct EnterWorktree call or gives up and tells the user to run the command themselves.

Suggested fixes (any one helps; ideally all three)

1. Make the guard message reference ToolSearch. Something like:

   "Call EnterWorktree first (load its schema via ToolSearch({query: "select:EnterWorktree"}) if not already available), then retry this edit using the path returned by EnterWorktree."

2. Pre-load EnterWorktree's schema in any session where the bgIsolation guard can fire. The agent shouldn't need a hop to reach its own documented recovery path.
3. Default Agent subagent dispatches to isolation: "worktree" when the dispatched agent has Edit/Write in its tool allowlist, OR inherit the parent's worktree state. Today the parent session can be in a worktree but the subagent it spawns isn't, which is surprising.

Why this is worse than it looks

The user-visible symptom is "Edit returns an internal error" — the actual guard text is hidden inside the subagent's transcript and not surfaced to the parent. Users don't realize there's a guard at all; they just see flaky parallel agents. In my data this is biting across multiple sessions on the same machine. Compounding bug #59848 (bg guards firing on foreground sessions on some platforms), this will become a frequent confusion source.

Related (but distinct) issues

• #59848 — interactive sessions classified as background, causing bg-only guards to fire (different root cause; same downstream UX)
• #58507 (closed) — catch-22 when cwd is already a worktree
• #59580 — worktree.bgIsolation setting missing from docs
• #58435 (closed) — opt-out for forced-worktree enforcement