[FEATURE] Independent Context Windows for Sub-Agents

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When orchestrating multiple sub-agents for complex analysis tasks (e.g., analyzing 8 feature tracks in a large codebase), all sub-agents share the parent session's 200K token budget and hit the 8192 output token limit.

Real Example:
While building an operational dashboard, I needed 5 sub-agents to analyze database schema, testing patterns, API design, etc. in parallel.

What Happened:

• 3 out of 5 sub-agents exceeded the 8192 token output limit
• Each failure consumed 10-15K tokens from the shared budget before truncation
• Error: "API Error: Claude's response exceeded the 8192 output token maximum"
• Forced to use workaround: sub-agents write to files, return only 500-word summaries

Impact on Workflow:

• Cannot get comprehensive analysis back from sub-agents (truncated)
• Parent token budget exhausted after 3-4 sub-agent failures
• Must run sub-agents sequentially instead of in parallel (5-10x slower)
• Manual file management adds complexity

Current Workaround:
Instruct sub-agents: "Write full analysis to docs/file.md, return only summary" - but this prevents interactive follow-up and adds overhead.

Proposed Solution

Ideal Experience:

When I launch a sub-agent that will generate large output, Claude Code automatically runs it in a separate terminal with its own 200K token budget, then returns the full result to me.

How I'd Interact:

1. Launch sub-agent normally - no change to current workflow:

"Launch a sub-agent to analyze Track 1.0 implementation patterns across 50+ files"

1. Automatic routing - Claude Code detects this will generate 20K+ tokens and says:

"This analysis will generate ~60KB output. I'm running this sub-agent in a separate terminal to preserve our token budget here. Status: [Sub-agent analyzing... 45% complete]"

1. Get full results - Sub-agent completes and I receive:

• Executive summary in current chat (500 words)
• Option to see full output: "Show full analysis" → displays all 60KB
• Results auto-saved to workspace for reference

What I expect:

• Small tasks (<5K tokens) still run instantly in current terminal (no overhead)
• Large tasks automatically get independent context (no manual setup)
• Can launch 5-10 sub-agents in parallel without token exhaustion
• Zero "output exceeded token limit" errors
• Full analysis returned, not truncated

Current workaround that validates this:
I manually instruct sub-agents to write to files - this proves independent execution works, just needs automation.

Alternative Solutions

Alternatives Tried:

1. File-based workaround (CURRENT):

• Sub-agents write full analysis to docs/analysis.md
• Return only 500-word summary to parent
• Downside: No interactive follow-up, manual file management, breaks conversational flow

1. Sequential sub-agents instead of parallel:

• Run one sub-agent at a time to avoid token budget exhaustion
• Downside: 5-10x slower (hours instead of minutes), defeats purpose of parallelism

1. Split large tasks into smaller chunks:

• Break 60KB analysis into 6 smaller 10KB tasks
• Downside: Loses coherence, overhead of coordination, still hits limits eventually

1. Manual separate terminals (WORKS but tedious):

• Manually open new Claude Code terminal for large tasks
• Copy/paste context and instructions
• Downside: Manual overhead, context loss, not scalable for 5+ sub-agents

Why these aren't sufficient:

The file-based workaround proves the concept works (independent execution), but requires too much manual orchestration. What's needed is automation of what I'm already doing manually - intelligent routing of large tasks to independent contexts.

Ideal solution validates against real usage:
I've successfully used manual separate terminals for deep analysis - confirming this approach works. Just needs to be automated by Claude Code.

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Scenario: Building an operational dashboard for an enterprise application with 8 feature tracks (Sensitive Types CRUD, Regex Patterns, Provider Config, Flow Config, User/RBAC, System Settings, Alerts, Compliance).

Step-by-step with current limitations:

1. I start planning: "Analyze the existing codebase to plan Track 1.1 (Regex Pattern Management)"

1. Launch analysis sub-agents:

• Sub-agent 1: "Analyze Track 1.0 implementation patterns (database schema, service layer, controllers)"
• Sub-agent 2: "Analyze existing test patterns and coverage strategy"
• Sub-agent 3: "Review REST API design patterns from similar CRUD features"
• Sub-agent 4: "Examine MapStruct usage for DTO transformations"
• Sub-agent 5: "Identify reusable components and utilities"

1. What happens NOW:

• Sub-agent 1 returns 8,000 tokens → ❌ Error: "Output exceeded 8192 token limit"
• Consumed 12K tokens from my 200K budget before truncation
• Sub-agent 2 returns 6,500 tokens → ✅ Success (but close to limit)
• Sub-agent 3 hits limit → ❌ Another failure, another 10K tokens wasted
• Token budget now at 166K (consumed 34K, got 50% useful output)
• Must run remaining sub-agents sequentially to avoid exhaustion

1. Current workaround:

• Restart: "Write analysis to docs/track-10-analysis.md, return 500-word summary"
• Works, but I can't ask follow-up questions without reading the file manually
• Takes 2-3 hours instead of 30 minutes

How it would work WITH this feature:

1. Same start: "Analyze existing codebase to plan Track 1.1"

1. Launch all 5 sub-agents in parallel (same as before)

1. Claude Code intelligently routes:

• Sub-agent 1 (60KB output expected) → Separate terminal, independent 200K budget
• Sub-agent 2 (40KB output) → Separate terminal
• Sub-agent 3 (45KB output) → Separate terminal
• Sub-agent 4 (30KB output) → Separate terminal
• Sub-agent 5 (15KB output) → Current terminal (small enough)

1. I see progress: "Running 4 sub-agents in parallel terminals... [75% complete]"

1. All return full results:

• Executive summaries in chat (2K tokens total)
• Full analyses available: "Show Track 1.0 analysis" → displays all 60KB
• Zero truncation errors
• My token budget: 198K remaining (only 2K used for summaries)

1. Time saved: 30 minutes vs 2-3 hours (80% reduction)

This is my actual workflow - I do this 2-3 times per week when planning new features.

Additional Context

Related GitHub Issues:
This builds on existing requests but addresses a specific gap:

• #3013 - Parallel Agent Execution (focuses on 100s of agents, this is for 5-10)
• #6854 - Non-blocking tasks (notification-based, this is about independent contexts)
• #5812 - Hooks for context bridging (inter-agent communication, complementary)
• #4908 - Scoped Context Passing (partial solution, this proposes full isolation)

Technical Considerations:

Context Transfer Strategy:

• Parent → Sub-agent: Task description, relevant file paths, environment variables
• Sub-agent → Parent: Default 500-word summary, full output on demand
• Configurable modes: full, partial, minimal context copying

Token Budget Allocation:

• Each independent sub-agent: 200K token budget (same as parent)
• Optional: Custom budgets (50K-500K) based on task complexity
• Advanced: Token pooling (5 sub-agents share 1M tokens)

Proof of Concept:
The manual workaround (opening separate terminals) already validates this approach works. Key observations:

• Separate terminals DO provide independent 200K budgets ✅
• Full analysis completes without truncation ✅
• No parent token budget impact ✅
• Only missing: Automation and orchestration intelligence

Implementation Hint:
Could be phased approach:

1. Phase 1: Document manual hybrid pattern (works TODAY, zero dev needed)
2. Phase 2: Add execution_mode parameter to Task tool
3. Phase 3: Automatic routing based on estimated output size

Similar Features in Other Tools:

• VS Code: Multiple terminal instances with independent contexts
• tmux/screen: Session isolation
• Kubernetes: Pod-level resource limits

ANTHROPIC_FEATURE_REQUEST.md