BMAD-METHOD/core/token-isolation/token-isolation.md

Token Isolation Architecture

Overview

Token isolation prevents context bloat in multi-agent scenarios by running agents in isolated subprocesses. Each agent gets its own 150K token context window without consuming the main session's tokens.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                     TOKEN ISOLATION ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────────┤
│   Main Session (150K tokens preserved)                                  │
│                       │                                                  │
│                       ▼ Task Tool spawns subprocess                     │
│              ┌────────────────────┐                                      │
│              │   Agent Instance   │ ◄── Own 150K token context          │
│              │    (subprocess)    │ ◄── Doesn't consume main session    │
│              └─────────┬──────────┘                                      │
│                        │                                                 │
│                        ▼ Only summary returns                           │
│              "Task complete. Output: temp/raw/file.md"                  │
└─────────────────────────────────────────────────────────────────────────┘

Core Rules

1. ALWAYS use Task tool to invoke agents (preserves main session tokens)
2. Agents write to files, not return full content to main session
3. Use run_in_background: true for parallel independent agents
4. Sequential agents receive previous output via content injection
5. Summaries returned to main session must be < 2000 tokens

Agent Execution Template

Task({
    description: "agent-name: brief task description",
    prompt: agentPrompt,
    subagent_type: "general-purpose",
    model: "sonnet",  // or "haiku" for quick tasks
    run_in_background: false  // true for parallel
});

Collaboration Patterns

Sequential Pattern

Agent A → Agent B → Agent C

Use when each step depends on previous output.

Parallel Pattern

Agent A ─┐
Agent B ─┼→ Synthesis
Agent C ─┘

Use when analyses are independent.

Debate Pattern

Proposer ↔ Challenger → Refined Output

Use for critical decisions requiring adversarial review.

War Room Pattern

All Agents → Intensive Collaboration → Solution

Use for complex urgent problems.

Output Management

File-Based Output

Agents should write outputs to:

• {output_folder}/temp/ - Temporary working files
• {output_folder}/raw/ - Raw agent outputs
• {output_folder}/final/ - Validated final outputs

Summary Protocol

When an agent completes:

1. Write full output to designated file
2. Return only: status, file path, key findings (< 2000 tokens)
3. Main session can read file if details needed

Token Budget Tracking

Threshold	Action
0-80%	Normal operation
80-90%	Warning: Consider wrapping up
90-100%	Critical: Summarize and hand off
100%+	HALT: Must spawn new subprocess

Best Practices

1. Pre-plan agent work - Know what each agent needs to do
2. Minimize cross-agent data - Pass file references, not content
3. Use haiku for simple tasks - Reduces cost and latency
4. Batch related work - One agent, multiple related tasks
5. Checkpoint frequently - Save progress to files regularly