claude-code - 💡(How to fix) Fix Add opt-out for forced-worktree enforcement on background-session Edit/Write tools

Summary

Background Claude Code sessions (launched via claude agents, with CLAUDE_JOB_DIR set) currently refuse Edit / Write tool calls unless the session is inside .claude/worktrees/. The error is:

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.

The worktree.baseRef setting introduced in v2.1.133 changes the worktree's base commit but does not disable the requirement. The enforcement appears built into the tool-handling layer (not a hook), so PreToolUse hooks cannot disable it. No documented opt-out exists.

Pain points (solo / single-user workflow)

1. Merge divergence. Default baseRef: "fresh" branches from origin/<default-branch>. If local main is ahead of origin/main (unpushed commits), the worktree is built from a stale state. Merging back to local main is no longer fast-forward — requires resolving divergence or copying files manually. baseRef: "head" mitigates this but still forces the worktree workflow.
2. Two-step commit flow. Background-session edits land on a temporary branch in a worktree. Getting them to main requires either git merge (fails fast-forward per #1) or manual file copy + commit.
3. Cleanup overhead. Each background session creates .claude/worktrees/<name>/ + a worktree-<name> branch. Both need cleanup after merge.
4. Concept-load. Newcomers to background mode hit this guard immediately and must learn the worktree lifecycle (EnterWorktree → edit → commit → ExitWorktree → merge) before doing real work.

Use case where opt-out matters

• Solo developer, single concurrent background job.
• Repo already isolated (no parallel agents).
• Local main often ahead of origin/main (WIP not pushed).
• User wants background-session edits to land directly in the active checkout, same as foreground sessions.

Current default makes sense for parallel-agent / shared-CI scenarios. Over-protective for solo workflows.

Proposed solution

Add a settings.json knob:

{
  "backgroundJobs": {
    "requireWorktree": false
  }
}

Default: true (current behavior, preserves parallel-safety).

When false:

• Background sessions skip the Edit/Write worktree guard.
• Edits land directly in the current checkout (same as foreground).
• User accepts responsibility for parallel-safety.

Matches existing pattern of opt-out settings (permissions.bypassPermissionsMode, dangerouslyDisableSandbox) — safe default, advanced opt-out.

Alternative considered

PreToolUse hook override. Rejected: guard appears built into tool layer, not hook-based — hook can't intercept.

Adjacent open issue: #57112 requests skipping paranoid auto-spawn when cwd is already inside a worktree — different specific bug (auto-spawn race in user-prepared worktree) but same family (cwd-aware opt-out around forced-worktree behavior).

Environment

• Claude Code: v2.1.139
• OS: macOS (Darwin 25.3.0)
• Workflow: solo, single-user, one concurrent background job