Worktree Isolation
Subagents can run in an isolated git worktree (a separate working directory tied to the same repo) so their changes don't affect the parent's working tree. Specified via the isolation: 'worktree' parameter on the Agent tool.
Worktree isolation is letting a contractor work on the spare bedroom (separate worktree) — they can paint it any color. If you don't like it, you close the door and never go back. Works only because the rest of the house is unaffected.
When isolation: 'worktree' is set, the harness creates a temporary worktree on a new branch, the subagent operates there, and the result includes the worktree path and branch name. If the subagent makes no changes, the worktree is auto-cleaned. Useful for risky exploratory work — refactor experiments, dependency upgrades, parallel test runs — where you want the option to keep or discard the entire result.
Worktree isolation is git's worktree feature underneath — same .git directory, different working tree. This means the subagent sees the same git history but commits go to a separate branch. Disk cost: a full checkout per worktree, which adds up fast for monorepos. Cleanup: the parent should delete worktrees after merging or discarding. Worktree isolation pairs well with parallel agents — three agents trying three different approaches to the same problem, in three separate worktrees, none stepping on each other. Limitations: not all tools respect cwd — Bash commands need explicit cd or absolute paths; some MCP servers operate on the original directory.
Worktree isolation gives a subagent its own branch and working directory so its changes don't pollute the parent's tree. I use it for risky or exploratory work — try three refactor approaches in parallel, keep the best, discard the rest. The harness cleans up empty worktrees automatically; non-empty ones stay around for me to merge or delete. The catch is disk usage in monorepos and that not all tools handle cwd correctly — I prefer absolute paths in worktree-bound subagents.
Forgetting to clean up. Worktrees with abandoned changes accumulate over weeks and burn disk. A periodic 'git worktree list' + cleanup is worth automating.