4. Sub-Agent Architecture

Confidence: 100% (Tier 1 - Documented behavior) Source: code.claude.com/docs + System prompt (visible in tool definitions)

The Task tool spawns sub-agents for parallel or isolated work.

Isolation Model

┌─────────────────────────────────────────────────────────────┐
│                        MAIN AGENT                           │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Context: Full conversation + all file reads           │  │
│  │                                                       │  │
│  │         Task("Explore authentication patterns")       │  │
│  │                        │                              │  │
│  │                        ▼                              │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │             SUB-AGENT (Spawned)                 │  │  │
│  │  │                                                 │  │  │
│  │  │  • Own fresh context window                     │  │  │
│  │  │  • Receives: task description only              │  │  │
│  │  │  • Has access to: same tools (except Task)      │  │  │
│  │  │  • CANNOT spawn sub-sub-agents (depth = 1)      │  │  │
│  │  │  • Returns: summary text only                   │  │  │
│  │  │                                                 │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  │                        │                              │  │
│  │                        ▼                              │  │
│  │         Result: "Found 3 auth patterns: JWT in..."    │  │
│  │         (Only this text enters main context)          │  │
│  │                                                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why Depth = 1?

Limiting sub-agents to one level prevents:

1. Recursive explosion: Agent-ception would consume infinite resources
2. Context pollution: Each level would accumulate context
3. Debugging nightmares: Tracking multi-level agent chains is hard
4. Unpredictable costs: Nested agents = unpredictable token usage

Sub-Agent Types

Claude Code offers specialized sub-agent types via the subagent_type parameter:

Type	Purpose	Tools Available
Explore	Codebase exploration	All read-only tools
Plan	Architecture planning	All except Edit/Write
Bash	Command execution	Bash only
general-purpose	Complex multi-step	All tools

When to Use Sub-Agents

Use Case	Why Sub-Agent Helps
Searching large codebases	Keeps main context clean
Parallel exploration	Multiple searches simultaneously
Risky exploration	Errors don't pollute main context
Specialized analysis	Different "mindset" for different tasks

Hub-and-Spoke Orchestration

The dominant multi-agent pattern in production is hub-and-spoke: one coordinator agent sits at the center, manages N worker sub-agents, and is the only entity that holds the full picture.

                    ┌─────────────────────┐
                    │    COORDINATOR      │
                    │  (Hub / Orchestrator)│
                    │                     │
                    │  • Decomposes goal  │
                    │  • Passes context   │
                    │  • Aggregates results│
                    │  • Resolves conflicts│
                    └──┬──────┬──────┬───┘
                       │      │      │
            ┌──────────┘      │      └──────────┐
            │                 │                 │
     ┌──────▼──────┐  ┌───────▼─────┐  ┌───────▼─────┐
     │  WORKER A   │  │  WORKER B   │  │  WORKER C   │
     │             │  │             │  │             │
     │  Specific   │  │  Specific   │  │  Specific   │
     │  task only  │  │  task only  │  │  task only  │
     └─────────────┘  └─────────────┘  └─────────────┘
           │                 │                 │
           └────────────────►│◄────────────────┘
                     (results flow back to coordinator only)

The critical rule: context is never inherited automatically. When the coordinator spawns Worker A to analyze file X, Worker B gets no knowledge of that analysis unless the coordinator explicitly passes it in the task description. Workers are isolated by design: they receive only the task string, nothing else.

This is the most common mistake in multi-agent design: assuming sub-agents share context. They don't.

Explicit context passing pattern:

# Wrong — Worker B won't know about Worker A's findings
task_a = Task("Analyze auth.py and find the session token logic")
task_b = Task("Find all callers of the session token logic")  # doesn't know where it is

# Correct — coordinator passes findings explicitly
result_a = run_task("Analyze auth.py and return the exact function name(s) handling session tokens")
task_b = Task(f"Find all callers of {result_a} across the codebase")  # explicit context

Coordinator responsibilities:

1. Decompose: Break the goal into independent subtasks with clear boundaries
2. Pass context explicitly: Each worker task description must be self-contained
3. Aggregate: Collect text results from all workers, combine into coherent output
4. Decide cross-cutting questions: Only the coordinator can make decisions that span workers

Workers should never need to communicate with each other. If they do, that's a sign the decomposition is wrong and the task belongs in the coordinator.