[FEATURE] Independent Context Windows for Sub-Agents

[ravikalla]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• 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"

2. 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]"

3. 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

2. 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

3. Split large tasks into smaller chunks:

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

4. 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)"

2. 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"

3. 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

4. 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"

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

3. 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)

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

5. 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)

6. 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:

• Feature Request: Parallel Agent Execution Mode #3013 - Parallel Agent Execution (focuses on 100s of agents, this is for 5-10)
• Feature request: non-blocking tasks / notification to main agent when a background bash session finishes #6854 - Non-blocking tasks (notification-based, this is about independent contexts)
• Feature Request: Allow Hooks to Bridge Context Between Sub-Agents and Parent Agents #5812 - Hooks for context bridging (inter-agent communication, complementary)
• Feature Request: Scoped Context Passing for Subagents #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

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Add context_isolation parameter to Task tool #9284
2. [FEATURE] Allow automatic splitting into multiple sessions from within main session #7706
3. [BUG] New Explore subagent frequently tries to return more than 8192 tokens. #9634

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #9284.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.