Why This Matters

In Chapters 5 and 6, you built safe file editing and policy gates. But your agent still works directly in the main repository. If the agent is halfway through a multi-file refactor and crashes, you are left with a partially modified codebase. If two agents work on different tasks simultaneously, their file edits collide.

This is the same problem that git branches solve for human developers — but branches alone are not enough. A branch is a pointer in the commit graph; it does not give you a separate working directory. Git worktrees do: each worktree is a full checkout of a branch in its own directory, sharing the same .git database.

Claude Code, Codex, and other production agents use isolation to run tasks safely. Worktrees are the lightweight way to achieve this without spinning up containers or VMs.

What You Will Build

A WorktreeManager that creates a worktree for each agent task, tracks the lifecycle (create, active, merged, abandoned), and cleans up when the task is done.

Each task gets its own directory and branch. The agent operates entirely within that directory. When the task is done, changes merge back to the main branch. If the task fails, the worktree is simply removed — no cleanup needed on the main branch.

What's Next

You now have three layers of safety: structured patches (Chapter 5), policy gates (Chapter 6), and workspace isolation (Chapter 7). Each agent task gets its own directory, its own branch, and its own policy context. Changes merge back only when the task succeeds.

But you have been using one execution mode: local worktree. What about tasks that need more isolation — running untrusted code, or executing in a fresh environment? What about tasks that are so simple they do not need a worktree at all?

In Chapter 8: Execution Lanes, you will build a system that chooses between local, worktree, and cloud-like execution modes based on the task's requirements and risk level.