agent-isolation

Agent isolation

Parallel agents that share one working tree corrupt each other. Not "might" — do.

The default developer method is: write the files, then git checkout -b feat/APP-NNN and commit. Run two of those concurrently in one tree and the sequence is:

dev A writes  ui/TodoListUiState.kt          (on main, untracked)
dev B writes  data/InMemoryTodoRepository.kt (on main, untracked)
dev A runs    git checkout -b feat/APP-001   -> B's file comes along
dev A runs    git add . && git commit        -> A ships B's half-finished work
dev B runs    git checkout -b feat/APP-002   -> from A's branch, inheriting A's commit

Both branches are now wrong, and neither agent can tell. Worse, this is silent: every agent reports DONE, tests pass, and the review reads a diff that contains someone else's changes.

A read-only agent is not exempt. A verification agent sharing a working tree once left a billing file with its guest-purchase guard deleted. Only explicit-path staging kept it out of the commit. One git add -A ships a removed billing guard.

Rule 1 — one worktree per WRITING AGENT, always

Before spawning any agent that writes, the orchestrator leases its slot:

node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-slot.mjs" lease --owner ios-developer --tickets APP-001,APP-002

The agent is given that path — .agent-wt/ios-developer — as its project root and never leaves it. Its git commands are confined there. It cuts feat/APP-001-short-slug, commits, then cuts feat/APP-002-short-slug from the same base and commits: one branch per ticket, unchanged. Parallel agents cannot see each other's uncommitted state, because they do not share a tree.

The slot is keyed by the WRITER, and it used to be keyed by the ticket. That was a contradiction, not a preference. parallel-orchestrator step 2 says one agent invocation per owner, batched; step 3 says each agent's prompt names its worktree path, singular. An ios-developer owning three tickets was spawned once, given three worktrees, and told to stand in one path that did not exist. Working all three in one of them makes every branch carry its siblings' files, which code-reviewer check 9 rejects — sending tech-manager to hunt a shared-tree collision the orchestrator caused.