Subagents & Context Isolation

What You’ll Learn

When Claude Code encounters a complex subtask — like exploring a codebase or researching an API — it doesn’t always handle it in the main conversation. Instead, it can spawn a subagent: a child process with its own clean context window.

By the end, you’ll understand:

• Why context isolation matters
• How subagents are spawned and managed
• The parent-child communication pattern
• When to use subagents vs. direct execution

The Problem

Every token matters. The context window (the total amount of text the AI can process at once) is finite. When Claude Code reads a large file, runs a complex search, or explores multiple directories, all that output consumes context.

The problem: research work pollutes the working context. If Claude Code reads 50 files to find the right one, those 49 irrelevant file contents are still in the context window, making subsequent work less effective.

How It Works

The Subagent Pattern

┌─────────────────────────────────────────┐
│           Parent Agent                   │
│                                          │
│  Messages: [user prompt, ...]            │
│                                          │
│  "I need to find where auth is           │
│   implemented. Let me spawn an           │
│   explorer agent."                       │
│       │                                  │
│       │ Spawn                            │
│       ▼                                  │
│  ┌──────────────────────────────┐        │
│  │      Child Agent              │       │
│  │  Messages: [task prompt only] │       │
│  │                               │       │
│  │  • Read file A (irrelevant)   │       │
│  │  • Read file B (irrelevant)   │       │
│  │  • Read file C (found it!)    │       │
│  │                               │       │
│  │  Return: "Auth is in          │       │
│  │  src/middleware/auth.ts,      │       │
│  │  uses JWT with refresh        │       │
│  │  tokens..."                   │       │
│  └──────────────┬───────────────┘        │
│                 │                         │
│                 │ Result (summary only)   │
│                 ▼                         │
│  Parent receives: concise summary        │
│  (not all the files the child read)      │
│                                          │
└──────────────────────────────────────────┘

The key insight: only the result flows back, not the full exploration history. The parent’s context stays clean.

How Subagents Are Spawned

In Claude Code, subagents are spawned via the Agent tool:

{
  "type": "tool_use",
  "name": "Agent",
  "input": {
    "description": "Explore auth implementation",
    "prompt": "Find where authentication is implemented in this codebase. Look for middleware, route guards, and token management. Return a concise summary.",
    "subagent_type": "Explore",
    "model": "haiku"
  }
}

Key parameters:

• prompt: The task for the child agent
• subagent_type: Specialized behavior (Explore, Plan, general-purpose, etc.)
• model: Can use a cheaper/faster model for simple tasks

Context Window Comparison

Without subagents:

Parent context: [user prompt] + [50 file reads] + [actual work]
                 └── context window nearly exhausted ──┘

With subagents:

Parent context: [user prompt] + [agent result: 200 words] + [actual work]
                 └── context window mostly available ──┘

Child context:  [task prompt] + [50 file reads] + [summary]
                 └── separate context, discarded after ──┘

Parallel Subagents

Multiple subagents can run concurrently:

[
  {
    "type": "tool_use",
    "name": "Agent",
    "input": {
      "description": "Research database schema",
      "prompt": "Find and summarize the database schema..."
    }
  },
  {
    "type": "tool_use",
    "name": "Agent",
    "input": {
      "description": "Research API routes",
      "prompt": "List all API routes and their handlers..."
    }
  }
]

Both agents execute in parallel, each in their own isolated context.

Key Insight

Subagents are not just about parallelism — they’re about context management. The most precious resource in an AI coding session is context window space. Every unnecessary token in context reduces the quality of subsequent work.

Think of it like delegation in a real team:

• You (the parent) stay focused on the big picture
• Team members (subagents) do the research and report back
• You only need to know the conclusions, not every step they took

This is why experienced users configure Claude Code to use subagents aggressively — it’s not about speed (though that helps), it’s about keeping the main conversation context clean and focused.

Hands-On Example

Here’s how to design effective subagent prompts:

# Bad: vague, returns too much
"Look at the codebase"

# Good: specific, asks for structured output
"Find all React components that handle user input forms.
For each, report:
1. File path
2. What data it collects
3. How it validates input
Return as a bullet list. Skip components not related to user data."

The prompt should be:

• Specific about what to find
• Structured in what to return
• Bounded to avoid unbounded exploration

Model Selection for Subagents

Choose the right model for the task:

Haiku (fast, cheap):
  → Simple searches, file exploration, listing tasks
  → "Find all files matching *.test.ts"

Sonnet (balanced):
  → Code analysis, refactoring plans, moderate complexity
  → "Analyze the error handling patterns in this module"

Opus (powerful):
  → Complex reasoning, architecture decisions, critical tasks
  → "Design a migration strategy for the database schema"

What Changed

Without Subagents	With Subagents
All work in one context	Research in child, decisions in parent
Context fills up quickly	Context stays clean
Sequential exploration	Parallel exploration possible
One model for everything	Right model for each task
Full history visible	Only summaries returned

Next Session

Session 5 covers Skills & Knowledge Loading — how Claude Code’s two-layer injection system loads skill names upfront but defers full content until needed, keeping the system prompt lean.