Sub-Agent Delegation with Context Isolation
Delegate bounded work to sub-agents that run in fresh context and return only distilled results - the pattern behind scalable long tasks.
The route
4 steps to Done
- 01
Specify the delegation contract
Isolation only works if the interface between agents is narrow and typed.
Preview prompt + verify gate ▾ Hide ▴
Design the dispatch_agent tool contract. Input: a task prompt that must contain (a) the question or job, (b) the exact deliverable format (e.g. 'a list of file paths with one-line reasons'), and (c) what to do if the answer cannot be found. Output: a single report string plus metadata (turns used, tools called, truncated: bool). Rules: sub-agent receives its own system prompt describing it as a focused researcher; it gets read-only tools unless the parent explicitly grants more; depth limit 1; turn budget 10. Write this contract as the tool description the parent model will read.
- ✓ Task prompt must specify the deliverable
- ✓ Read-only default is explicit
- ✓ Depth and turn budgets are stated
- 02
Implement the isolated sub-loop
A sub-agent is your existing loop with a different context and leash.
Preview prompt + verify gate ▾ Hide ▴
Implement the sub-agent runner by reusing the main loop code with: a fresh message history seeded only with the sub-agent system prompt and the task; a filtered tool registry (read_file, search, list_dir - no write, no command execution by default); a hard turn budget that on expiry forces a final 'partial report' turn where the model must summarize what it found so far. The runner returns {report, turns_used, tools_called, truncated}. Log the full sub-transcript to its own JSONL file keyed by a dispatch ID so it is auditable but never enters parent context.
- ✓ Fresh history per dispatch - nothing inherited
- ✓ Write tools absent from the sub registry
- ✓ Budget expiry produces a partial report
- 03
Wire dispatch into the parent and distill
The payoff: exploration happens elsewhere, conclusions come home.
Preview prompt + verify gate ▾ Hide ▴
Register dispatch_agent in the parent's tool registry and run the acceptance task: ask the parent 'Where is user authentication handled in this codebase and what would I touch to add a password-reset flow?' The parent should dispatch a research sub-agent rather than exploring inline. Verify: the parent context gains only the task and the report (measure the tokens); the report names concrete files and reasons; the parent then answers using the report. If the parent explores inline instead of dispatching, strengthen the parent system prompt with guidance on when to delegate (open-ended search, multi-file reading, anything expected to take more than 2 tool calls of exploration).
- ✓ Parent context grows by task + report only
- ✓ Report contains concrete, usable findings
- ✓ Parent actually uses the report in its answer
- 04
Test isolation, budgets, and failure reporting
Trust the pattern only after you have watched it fail safely.
Preview prompt + verify gate ▾ Hide ▴
Run three adversarial tests. Test A (isolation): instruct a sub-agent task that involves reading a huge file - verify the parent context stays small while the sub transcript shows the reads. Test B (restriction): craft a task where the sub-agent will want to edit a file - verify the write attempt is rejected by the registry filter and the report says so honestly. Test C (honest failure): ask about something that does not exist in the codebase - verify the report says 'not found' with what was checked, not a fabrication. Fix anything where a sub-agent's limitation was hidden from the parent.
- ✓ Huge-file task does not bloat parent context
- ✓ Write attempt is blocked and reported
- ✓ Not-found case reports honestly with evidence
Research-backed
Sources behind this flow
Tier 1 · claude-code-internals
Claude Code Orange Book
A book-length analysis ('Orange Book') dissecting Anthropic's AI engineering decisions from the 510,000 lines / 1,902 TypeScript files that shipped inside an npm package. Chapters cover the agent loop, context compaction, the hook system, and sub-agents - the concepts, not just the code.
Tier 1 · claude-code-internals
claude-code-decompiled (research reports)
A documentation-only collection of 20 independent research reports on Claude Code v2.1.88 covering architecture, agent behavior, permission design, prompt assembly, MCP integration, and context management. Deliberately ships analysis rather than extracted code.
Tier 1 · claude-code-internals
Deep Dive: Multi-Agent Dispatch - Spawn, Fork, Direct
Source-level analysis of the three ways Claude Code dispatches work: Spawn (a named sub-agent with a fresh context, its own tool pool, permission mode, and model), Fork (a synthetic agent that inherits the parent conversation byte-for-byte so parallel workers share the prompt cache), and Direct (the main agent just does the task itself). Covers sync-to-background promotion via a promise race, recursion guards on forking, git-worktree isolation, and a decision matrix for picking a strategy per task.
Tier 1 · claude-code-internals
Deep Dive: Agent Orchestration Patterns
Follows a dispatched agent through its full lifecycle - foreground vs background execution, auto-backgrounding of long tasks, sidechain transcripts for resume, layered tool filtering, and result handoff - then catalogs six reusable orchestration patterns: worker pool, pipeline, supervisor-worker, adversarial verification, fork-join, and resume chain. The adversarial verification agent, which must run real commands and issue a PASS/FAIL verdict while being forbidden from editing the project, gets special attention as a defense against LLM self-verification failure modes.