Ch 7: Worktree Isolation
Imagine a neighborhood bookshop getting ready for spring. The owner wants a brighter front window, but not a half-finished mess facing the sidewalk all afternoon.
So the staff keeps a practice window in the stockroom. Same shelves. Same signs. Same baskets. The helper can move everything around there first.
If a ribbon falls down, a sign looks crowded, or the whole arrangement feels wrong, that mess stays backstage. Customers still see the calm, working storefront.
Only when the practice version looks right does the team copy it into the real front window.
That is what isolation does. Give the helper a safe copy to experiment in. Then move over only the version that already works.
Why the Real Storefront Should Stay Calm
Without a safe practice area, every experiment happens in public.
- The helper rearranges half the display, then gets interrupted. Now customers stare at an unfinished window.
- Two helpers adjust the same welcome sign in the real storefront. One quietly undoes the other.
- A bold idea falls apart halfway through, and the old display is already gone.
None of those problems start with bad intentions. They start because the risky work happened in the real place.
A safe copy changes the rules. The helper can test ideas in the practice window, throw away weak attempts, and only move over the finished layout.
The bookshop wants a fresh spring front window, but customers are still walking past outside.
Put the safe rollout in order
Drag to reorder, or use Tab + Enter + Arrow keys.
- Prepare a practice window backstage
- Try the new arrangement there
- Check whether the trial really works
- Move the finished layout into the real storefront
- Clear away the practice setup
Key Insight
The point is not to make the helper perfect. The point is to make mistakes cheap.
When the risky work happens in a safe copy, a bad attempt is just a draft you can throw away. The real storefront stays usable the whole time.
That changes the helper's job from "never slip" to "try carefully, keep the mess contained, and only move over what proved itself."
If you remember one sentence from this chapter, make it this one: let the helper experiment in the practice space, not in the real storefront.
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 a simulated isolated subprocess mode based on the task's requirements and risk level.