5.2 KiB

Raw Blame History

Delegation Patterns for Context Preservation

How to delegate work to preserve main conversation context.

TL;DR: Subagents run in isolated contexts—only their summary returns. Delegate: 5+ file reads, codebase searches, specialized reviews. Keep in main: user Q&A, simple edits, files already in context. Use run_in_background: true for parallel work. Track delegated tasks with Tasks and agent IDs.

The Context Problem

Main conversation context is ~128K tokens. Every operation consumes it:

Reading a file: file contents enter context
Search results: matches enter context
Reasoning: your analysis consumes tokens
Tool results: outputs accumulate

Subagents run in isolated contexts. When they complete, only their final output (summary, findings, results) returns to main context. The files they read, searches they ran, reasoning they did — all stay in their isolated context.

Delegation Decision Matrix

Task Type	Delegate?	Agent	Why
Read 1-2 files	No	Main	Already focused
Read 5+ files	Yes	Explore	Preserves main context
Codebase search	Yes	Explore	Returns summary, not raw results
Security review	Yes	outfitter:reviewer	Specialized + isolated
Performance analysis	Yes	outfitter:analyst	Research-heavy
Simple edit	No	Main	Quick, in-context
Multi-file refactor	Yes	outfitter:engineer	Coordinates changes
Test validation	Yes	outfitter:tester	Isolated execution
User Q&A	No	Main	Needs conversation history

Pattern: Research Delegation

Instead of reading many files yourself:

{
  "description": "Find auth implementation",
  "prompt": "Locate all authentication-related files. Summarize: (1) auth flow, (2) libraries used, (3) key entry points",
  "subagent_type": "Explore"
}

Returns to main context: ~50 lines of summary Stayed in subagent context: contents of 15 files

Pattern: Parallel Independent Reviews

When multiple concerns need analysis:

// All in single message, all run_in_background: true
{
  "description": "Security review",
  "prompt": "Review src/auth/ for security vulnerabilities",
  "subagent_type": "outfitter:reviewer",
  "run_in_background": true
}
{
  "description": "Performance review",
  "prompt": "Analyze src/auth/ for performance issues",
  "subagent_type": "outfitter:analyst",
  "run_in_background": true
}
{
  "description": "Test coverage",
  "prompt": "Assess test coverage for src/auth/",
  "subagent_type": "outfitter:tester",
  "run_in_background": true
}

Three reviews run simultaneously. Main agent stays responsive. Collect results with TaskOutput when ready.

Pattern: Sequential Handoff with Context

When later agents need earlier agents' output:

1. outfitter:analyst researches → returns findings
2. Main agent extracts key points
3. outfitter:engineer implements → receives key points in prompt
4. outfitter:reviewer reviews → receives implementation summary

Don't pass full agent output to next agent. Extract and summarize.

Pattern: Resumable Long-Running Work

For multi-stage work:

// Stage 1
{
  "description": "Begin auth analysis",
  "prompt": "Analyze authentication patterns in src/auth/",
  "subagent_type": "outfitter:analyst"
}
// Returns agent-id: abc123

// Stage 2 (later)
{
  "description": "Continue auth analysis",
  "prompt": "Now examine the session management aspect",
  "subagent_type": "outfitter:analyst",
  "resume": "abc123"
}

Agent preserves its full context across invocations. Main agent stays lean.

What to Keep in Main Context

Not everything should be delegated:

Keep in main:

Direct user interaction
Final synthesis and decisions
Coordination logic
Files already read (don't re-delegate)
Simple, quick operations

Delegate:

Exploratory research
Multi-file analysis
Specialized reviews
Test execution
Background validation

Task Integration

Track delegated work with Tasks:

#1: "[analyst] Research caching patterns" - pending, metadata: {agentId: "abc123", background: true}
#2: "Wait for analyst results" - pending, blockedBy: #1
#3: "[engineer] Implement cache layer" - pending, blockedBy: #2
#4: "[reviewer] Review implementation" - pending, blockedBy: #3

Update when agents complete:

#1: "[analyst] Research caching patterns" - completed, description: "Redis recommended"
#2: "Wait for analyst results" - completed, description: "Redis approach confirmed"
#3: "[engineer] Implement Redis cache layer" - in_progress

Anti-Patterns

Delegating simple work: Single file edit doesn't need an agent.

Over-parallelization: Don't run 10 agents when 3 would do.

Missing handoff context: Agents need enough info to act independently.

Forgetting to collect: Background agents finish but results never retrieved.

Re-delegating: If file already in context, don't send agent to read it again.

Context Budget Mental Model

Think of context as a budget:

Total: 128K tokens
System prompts: ~10K
User messages: ~5K
Your reasoning: ~20K
Tool results: ~???

Every file read, search result, and agent output draws from tool results. Delegation shifts that cost to isolated contexts, keeping main budget available for synthesis and user interaction.

5.2 KiB Raw Blame History