VI · Multi-AgentEmerging★

Subagent Isolation

also known as Worktree Subagent, Parallel Subagent, Isolated Worker

Run subagents in isolated workspaces so their writes do not collide and parallelism is safe.

This pattern helps complete certain larger patterns —

  • specialisesOrchestrator-Workers★★— An orchestrator dynamically breaks a task into subtasks at runtime and delegates each to a worker LLM, then synthesises results.
  • used-byClone Fan-Out Research·— Spawn 100 or more identical, full-capability agent instances in parallel — each a complete general agent rather than a role-specialised worker — and aggregate their independent outputs into a single answer.

Context

A coding agent — or any agent that edits files, runs commands, or mutates a workspace — delegates to several sub-agents that should work in parallel. Each sub-agent has its own bounded task: one refactors a module, another updates tests, a third writes documentation. They all want to touch the same repository at the same time.

Problem

If the sub-agents share one working directory, their edits race each other: one sub-agent's commit clobbers another's uncommitted changes, two sub-agents edit the same file with incompatible diffs, and a failure in one leaves the workspace in a state that breaks the others. Serialising them removes the parallelism that was the point of spawning sub-agents in the first place. Without isolated workspaces, the team has to choose between racing writes and giving up on parallel execution.

Forces

  • Isolation has setup cost (new worktree, branch, container).
  • Reconciling work back to the main workspace is its own problem.
  • Excessive isolation prevents subagents from seeing each other's progress when that would help.

Example

A research agent is asked to write a market report. Instead of doing every sub-task in its main loop, it spawns three sub-agents in parallel: one to research competitors, one to pull pricing data, one to summarise news. Each sub-agent has its own tool set and step budget. The main agent only sees the three structured results that come back, not the dozens of intermediate web searches each sub-agent ran.

Diagram

Solution

Therefore:

Each subagent runs in its own workspace (git worktree, container, branch, sandbox). The supervisor reconciles results back to the main workspace on completion (merge, cherry-pick, replay). Only one workspace can land changes at a time.

What this pattern forbids. Subagents may only write to their own isolated workspace; cross-workspace writes are forbidden.

The smaller patterns that complete this one —

  • generalisesLLM Map-Reduce Isolation★— Process each untrusted document in its own sealed sub-agent and merge only structured outputs, so an injection in one document cannot steer the processing of others.

And the patterns that stand alongside it, or against it —

  • composes-withSandbox Isolation★★— Run agent-emitted code or actions in a contained environment with restricted filesystem, network, and process privileges.
  • composes-withLLMCompiler·— Take ReWOO's plan-as-DAG and run independent steps in parallel through a task-fetching dispatcher.
  • complementsAgent-as-Tool Embedding★— Wrap a sub-agent (with its own loop, prompt, and tool palette) behind a single function-shaped tool signature, so the parent agent calls it like any other tool and never sees the sub-agent's internal turns.
  • complementsUnbounded Subagent Spawn✕— Anti-pattern: a supervisor or orchestrator spawns sub-agents that can themselves spawn sub-agents without a global cap.
  • alternative-toCascading Agent Failures✕— Anti-pattern: build a multi-agent system where one agent's failure or hallucination propagates as input to peers, until the whole system has drifted.
  • alternative-toMemory Extraction Attack✕— Anti-pattern: let any session prompt the agent to read out, summarise, or paraphrase long-term memory entries belonging to other users, prior sessions, or system state, with no read-time isolation by principal.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

Used in recipes

Used in frameworks

Show 9 more

References

Provenance