Agents View: configurable git worktree behavior for Agent Workers

Summary

Currently, when an Agent Worker in Agents View (claude agents) needs to update files inside a git repository, it defaults to creating a new git worktree and operating inside it. This is sometimes overkill (e.g. trivial single-file edits with no concurrent work) and other times surprising for users who expect the agent to operate directly on their working tree.

This proposal adds a user/project-level setting in .claude/settings.json (and ~/.claude/settings.json) to let users choose the default behavior.

Proposed setting

A new setting under Agents View configuration, e.g.:

{
  "agents": {
    "worktreeMode": "auto" // "auto" | "manual" | "worktree"
  }
}

Modes

• auto (recommended default) — A smart mode. Before editing, the agent detects whether the required changes would conflict with other activity in the repo (e.g. another Claude Code process recently used Edit/MultiEdit on the same file, or there are uncommitted local changes that overlap). If a likely conflict is detected, the agent uses AskUserQuestion to suggest creating a new git worktree and offers to bring previously-made non-conflicting changes across to the new worktree. If no conflict is detected, it edits in place.
• manual — The agent will never create a git worktree on its own. Worktree management is fully the user's responsibility. Useful for users with their own worktree workflow or scripted setups.
• worktree — Current behavior: the agent always creates a git worktree whenever it needs to update files inside a git repository.

Motivation

• The current always-create-a-worktree behavior is invisible friction for small changes and adds cognitive overhead (extra branches, extra paths to clean up).
• Power users running multiple parallel Claude processes do want worktree isolation — keep that available via worktree mode.
• auto strikes a balance: edit-in-place by default, but surface a worktree prompt the moment the agent sees a real risk of stepping on concurrent work.
• Making this configurable per-user and per-project lets teams standardize the behavior that matches their workflow.

Suggested behavior details for auto

• Detect concurrent activity by checking, e.g.: other live Claude Code sessions touching the same file, recent edits within a short window, dirty index/working tree on overlapping paths.
• When prompting via AskUserQuestion, offer at minimum: "Create new worktree and migrate pending changes", "Edit in place anyway", "Cancel".
• Migrating pending changes should preserve any previously-made non-conflicting edits in the current session.

Acceptance criteria

• New agents.worktreeMode setting honored at both user and project level (project overrides user).
• Default value is auto when unset.
• Documented in the Agents View / settings docs.