[FEATURE] Decouple subagents from mandatory worktree isolation and add automatic non-git fallback

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code currently appears to tightly couple subagents with worktree isolation, which creates a poor experience in non-git directories and forces users to deal with low-level implementation details.

In practice, launching a subagent in a non-git directory fails unless the user configures WorktreeCreate / WorktreeRemove hooks. However, once those hooks are configured, they appear to take over the worktree lifecycle more broadly, including in git repositories.

This creates an awkward tradeoff:

• Without hooks:
• git repositories work
• non-git directories fail
• With hooks:
• non-git directories can work
• but users must now implement and maintain custom worktree behavior
• and the hooks seem to replace, rather than simply supplement, the default git worktree path

The core problem is that subagents and worktrees are not the same concept:

• a subagent is an isolated execution/context unit
• a worktree is one specific filesystem isolation strategy

Users may want subagents in many situations that have nothing to do with git worktrees, such as:

• temporary script directories
• prototypes
• documentation folders
• read-only analysis tasks
• non-git local workspaces
• lightweight research/exploration tasks

The current design effectively makes worktree isolation a mandatory prerequisite for subagents, which feels too rigid and exposes too much internal plumbing to end users.

Proposed Solution

Please decouple subagents from mandatory worktree isolation and support a more flexible isolation model.

A good solution would be one of the following:

Option 1: isolation: "auto"
Allow Claude Code to automatically choose the best strategy:

• if the current directory is a git repository → use native git worktree behavior
• if the current directory is not a git repository → automatically fall back to a non-worktree mode, such as:
• running in-place
• using a temporary copy
• or another built-in lightweight isolation strategy

Option 2: isolation: "none"
Allow subagents to run without filesystem isolation when the user is willing to accept that tradeoff.

This would be especially useful for:

• read-only tasks
• non-git directories
• lightweight exploration
• temporary local work

Option 3: make worktree isolation optional rather than mandatory

Instead of making worktree isolation the only available subagent mode, allow subagents to run by default without requiring a worktree-capable environment.

Option 4: if hooks remain part of the solution, make them true fallback hooks

If WorktreeCreate / WorktreeRemove hooks are configured, they should ideally only be used when native git worktree support is unavailable, rather than replacing default git behavior entirely.

At minimum, the product/documentation should clearly state whether these hooks:

• act only as fallback mechanisms
• or fully replace the default worktree lifecycle

Alternative Solutions

If a full redesign is not feasible, even one of these would improve the situation significantly:

1. Add a built-in fallback mode for non-git directories only
2. Add a CLI/config option to disable filesystem isolation for subagents
3. Add a config mode that preserves native git worktrees but allows a separate strategy outside git
4. Improve documentation to explicitly explain that WorktreeCreate can replace default behavior, so users can make informed decisions

Priority

Medium - Would be very helpful

Feature Category

API and model interactions

Use Case Example

A user is working in a local directory that is not a git repository and wants to launch a subagent for a simple task such as:

• exploring files
• summarizing project structure
• drafting code changes
• read-only analysis

Today, this fails unless the user configures WorktreeCreate / WorktreeRemove hooks.

The user then tries to add hooks only to make non-git subagents work, but discovers that those hooks are also involved in git repositories and may replace the default worktree lifecycle there as well.

The user’s actual goal is simple:

• in git repositories: keep the normal native worktree behavior
• in non-git directories: allow subagents to run without requiring custom worktree infrastructure

This should ideally work out of the box, without forcing users to implement low-level lifecycle hooks just to use subagents outside git.

Additional Context

I tested this behavior and observed:

• in a non-git directory, subagent launch failed with an error indicating that no WorktreeCreate hooks were configured
• after configuring WorktreeCreate / WorktreeRemove, subagent launch in a non-git directory succeeded
• in git repositories, those hooks were also triggered
• WorktreeCreate appears to determine the directory used by the subagent via stdout, suggesting that it is not just advisory but actively provides the working directory

This makes the current hook model feel more like a replacement mechanism than a simple compatibility fallback.

The current design seems optimized around one strong assumption:

“subagents should always use worktree isolation”

That assumption may be valid for some workflows, but it is too restrictive as the only supported model.