Sub-Agent Context Isolation

Note

Sub-agent context isolation is the single most powerful context engineering pattern available. If you remember only one technique from this guide, make it this one.

Why Sub-Agents Are Transformative

When the AI agent researches a codebase, it reads files — lots of them. Each file read consumes 3,000-6,000 tokens. Exploring 10 files costs 30,000-60,000 tokens. That’s 15-30% of the context window consumed by exploration alone.

Sub-agents solve this by running in their own context windows:

Main Agent Context                  Sub-Agent Context
────────────────────               ─────────────────────
Task description      500 tokens   Task: "find all auth files"
Agent config         2000 tokens   Reads auth.ts       5000 tokens
Sub-agent summary     800 tokens   Reads session.ts    4000 tokens
                                   Reads token.ts      3000 tokens
Implementation       5000 tokens   Reads middleware.ts  6000 tokens
                                   Reads rbac.ts       4000 tokens
────────────────────               ─────────────────────
Total: ~8,300 tokens               Total: ~22,000 tokens
                                   Returns: 800 token summary

The sub-agent consumed 22,000 tokens of exploration. The main agent received an 800-token summary. Context savings: 96%.

When to Use Sub-Agents

Use Sub-Agents	Don’t Use Sub-Agents
Exploring unknown code	Reading 1-2 specific files
Searching across many files	Making targeted edits
Research before planning	Simple, well-scoped tasks
Code review (unbiased)	Tasks where context history is valuable
Parallel investigation tasks	Sequential reasoning chains

Sub-Agent Patterns

Pattern 1: Research Delegation

Use sub-agents to investigate:
1. How our auth middleware handles session tokens
2. What rate limiting patterns exist in the codebase
3. Which endpoints are currently unprotected

Report findings in a structured summary with file locations.

Pattern 2: Parallel Investigation

Use sub-agents to simultaneously:
1. Agent A: Find all files that import from src/auth/
2. Agent B: List all API endpoints and their auth requirements
3. Agent C: Check test coverage for auth-related code

Synthesize the results into a unified assessment.

Pattern 3: Verification in Isolation

Use a sub-agent to review the rate limiter implementation
in src/middleware/rateLimit.ts.

Check for:
- Race conditions in the sliding window logic
- Correct Redis key expiration
- Proper error handling when Redis is down
- Edge cases around window boundaries

Because the reviewer runs in a fresh context, it’s unbiased by the implementation decisions made during coding.

Pattern 4: Research → Summary → Implementation

Phase 1 (sub-agent):
Research how webhooks are handled. Document the flow,
key files, and patterns in .sdlc/research/webhooks.md.

Phase 2 (main agent, after sub-agent completes):
Read .sdlc/research/webhooks.md and create an implementation
plan for adding Stripe webhook support.

Custom Sub-Agent Definitions

For recurring patterns, define custom agents in your tool’s agent directory. See the Tool Configuration Reference for your tool’s agent directory location.

agents/codebase-researcher.md

---
name: codebase-researcher
description: Researches codebase patterns and produces structured summaries
tools: Read, Grep, Glob, Bash
# use a cost-efficient model for this task
---

Research the topic provided and produce a structured summary:

## Output Format
### Overview
[2-3 sentence summary]

### Key Files
| File | Purpose | Relevance |
|------|---------|-----------|

### Code Flow
[Step-by-step description of how the code works]

### Patterns Used
[Design patterns, conventions, and architectural decisions]

### Potential Issues
[Any concerns or areas that need attention]

Using a smaller/faster model for research agents is cost-effective — they primarily read and summarize, which doesn’t require the full reasoning capability of a frontier model.

Sub-Agent Communication

Sub-agents communicate with the main agent through:

1. Return value — the summary at the end of their task
2. File artifacts — writing to .sdlc/research/ or NOTES.md
3. Git commits — for implementation agents in worktrees

Tip

For complex research, have sub-agents write to files rather than relying solely on their return summary. Files persist across compaction events; return values don’t.

Anti-Patterns

Over-Delegation

Don’t use sub-agents for simple, focused tasks. The overhead of spawning a sub-agent isn’t worth it when you just need to read one file.

# Overkill — just read the file directly
Use a sub-agent to check what's in config.ts

# Appropriate — this explores many files
Use a sub-agent to understand how configuration flows
from config.ts through the application

Missing Context in Delegation

Sub-agents don’t inherit your conversation context. Provide enough information for them to succeed:

# Bad — sub-agent has no context
Investigate the auth bug.

# Good — sub-agent has what it needs
Investigate why token refresh fails after session timeout.
The auth middleware is in src/middleware/auth.ts.
Token storage uses Redis (src/lib/redis.ts).
The error occurs when refreshToken() returns null.

Key Takeaways

• Sub-agents provide 90%+ context savings for exploration tasks
• Use them for research, parallel investigation, and unbiased review
• Define custom agents for recurring patterns (research, review, testing)
• Use a cost-efficient model for read-only tasks to save cost
• Write to files for information that must survive compaction
• Provide sufficient context when delegating — sub-agents don’t inherit history