Parallel Subagents: Decide Who Edits Which File

The bug is located, and two fixes need trying, so you hand one to each of two subagents. Both fixes turn out to change the same interface contract. Each edits it its own way, the results won't merge, and both report "done."

You open Git and see a wall of conflicts, but the conflicts are only the surface.

The real problem is that nobody settled the shared interface before the work started, and nobody owns the integration. Subagents each have their own context, so their thinking stays separate, yet they work on the same filesystem.

A worktree separates branches and working files, while the database and network are still shared. Treating context isolation and file isolation as the same thing is the most common reason parallel work goes wrong.

The lines have to be drawn before the work goes parallel. A subtask needs a goal, a scope, and a deliverable. Whether tasks can run side by side depends on whether each can produce its result on its own.

Shared files get one writer, and several read-only investigations get combined only after you check that they share an environment and a time window. Integration belongs to a named person, and that is what makes parallel work pay off.

A division chart at the end turns the two-fix task above into a plan you can actually run.

01 Context isolation and file isolation are two things

A Subagent runs a subtask in its own context. The official documentation lists what you can configure: tools, model, permissions, maximum turns, and memory. Noisy exploration, such as searching a large repository, reviewing a directory, or boiling down a test failure, can keep its output inside the subtask. The main conversation gets a structured summary.

A subtask needs a clear goal, scope, and deliverable. An incident investigation, for example, might read:

Investigate errors within the incident's time window read-only and assess
whether they relate to the latest deployment.
Scope: the supplied sanitized logs and the most recent deployment diff.
Do not modify files, restart services, write to databases, or send external messages.
Return:
1. Relevant records and timestamps.
2. Evidence consistent or inconsistent with the deployment changes.
3. A leading hypothesis and unconfirmed items.
4. One next check that can distinguish between hypotheses.
Explore for at most 8 turns. At the budget limit or if key input is missing,
return the evidence collected and the remaining gaps.

That turns "just look at the incident" into an investigation with inputs, a scope, and deliverables. The real configuration should limit tools and permissions too. Enforce the turn limit with maxTurns, because a budget written in natural language is only a hint. The result should keep evidence, hypotheses, and unfinished work apart, and when the budget runs out, the unfinished part should be preserved.

A worktree gives the same Git repository another working directory, usually on its own branch. For experimental changes, use a setting such as isolation: worktree and then ask:

Try approach A in an isolated worktree.
Modify only auth-related files.
When finished, report the changes, test results, and whether you recommend merging.

A worktree separates branches and working files. It doesn't isolate all Git state, the network, or a database. If the experimental code connects to the same database, its writes can still reach that database, so execution permissions and external resource limits have to be set separately.

In short, read-only noisy exploration needs only a Subagent. Add a worktree when code changes have to stay apart. When execution permissions and external resources are involved, keep using permissions, the sandbox, and server-side controls, as covered in The Hook errored, but the dangerous action still ran.

02 Schedule parallel work by task dependency

Reviewing three directories, researching three approaches, locating several failing tests, and checking several documents can each end with the results being merged. That works when every task has clear enough input to proceed alone and produce a result.

Before you start parallel work, list each subtask's inputs, outputs, file scope, and how the results will be combined. The key test for parallelism is whether the tasks can produce results independently.

When tasks depend closely on each other's state, do them in order. For a shared core file, name one writer, and have the other tasks read only or offer suggestions. A worktree lets experiments stay apart, but the design dependency on a shared interface and the final integration work are still there.

The main conversation owns the overall goal, combines the evidence, and checks how changes affect each other. When three summaries each say "done," you still have to verify the combined result.

03 Read-only investigation: integrating after you delegate

Say the current authorization is only "find the likely cause." You may read sanitized logs and deployment records, and you may not change production state. The main conversation keeps the goal and the job of combining evidence. With a lot of logs, send the log analysis and the recent-change analysis to separate read-only Subagents, and have each return its evidence before anything is edited. Both read-only explorations can share the existing working directory.

Suppose the log subtask suggests "a restart may be needed." It should still return the suggestion, the evidence, and the unconfirmed impact. The scope of authorization stays with the user.

When you combine the results, check that both pieces of evidence come from the same environment, version, and time window. If the logs came from an old deployment, then even when both summaries say "done," you have to investigate the current root cause again. Delegating spreads out the work, and integration still depends on checking the facts they share.

04 Code changes: settle the interface, then split the work

Back to the opening. The bug is located in code, and two fixes need testing. Files will get written, so the controls have to change with that.

You can prepare separate worktrees for the experiments. First spell out each approach's inputs, edit scope, verification standard, and the person who integrates. The directories are separate, but the database and network services are still shared, so tests should still point at an approved isolated environment.

If both approaches change the same interface contract, one owner should settle the contract first, and implementation follows. When two subtasks go ahead before the shared interface is decided, the conflicts that follow usually come from a design dependency, and Git is only where they surface.

You can organize it like this:

Main conversation: confirm the shared goal, interface boundaries, and acceptance criteria
  ├─ Read-only subtask: inspect callers and compatibility
  ├─ Read-only subtask: inspect test coverage and missing conditions
  └─ Change owner: implement one candidate using the confirmed conclusions
       ↓
Review the diff and verify the candidate
       ↓
After integration, recheck behavior affected by interactions between changes

This is an example split, and a real refactor can use more tasks or fewer. Work that can produce a result on its own suits parallel running. For shared files, name one writer and let the other tasks offer suggestions. Even with several worktrees, someone has to be responsible for integration.

For keeping noisy exploration out of the main conversation, see the subtask examples in Claude Code session getting messy? Clear or compact

Back to the two fixes from the opening: one person settles the interface contract, the work then splits, and the main conversation integrates and verifies again at the end. That last step belongs to the main conversation, and each subtask's "done" is only an input to it.