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 using the Task tool to launch sub-agents (architecture-explorer, repo-specific agents, etc.), there's no visibility into:

• Which sub-agents were spawned
• How many tokens each sub-agent consumed
• What files each sub-agent read
• Total token usage across all sub-agents

Current Behavior:

• /context command shows only main session token usage
• Task tool returns only the final report from sub-agents
• Sub-agent exploration work is invisible to the user

Requested Behavior:

1. Enhanced /context output:
   Messages: 7.4k tokens (3.7%)
   └─ agents: 185k tokens (not counted in main session)
   ├─ main-agent: 45k tokens
   │ ├─ service1-sub-agent: 35k tokens
   │ ├─ service2-sub-agent: 40k tokens
   │ ├─ service3-sub-agent: 30k tokens
   │ └─ service4-sub-agent: 35k tokens
   └─ Total agent tokens: 185k

Benefits:

• Better understanding of actual cost/token usage
• Visibility into which agents did the work
• Debugging aid when agents don't find expected information
• Helps users optimize their sub-agent delegation strategies

Use Case:
Multi-repo projects with complex sub-agent architectures benefit from understanding which agents were invoked and how much context they consumed during parallel exploration.

Proposed Solution

Add a new section showing sub-agent token usage with hierarchical visualization:

Context Usage
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛁ ⛁ claude-sonnet-4-5-20250929 · 75k/200k tokens (38%)
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ System prompt: 2.2k tokens (1.1%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ System tools: 13.2k tokens (6.6%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ Memory files: 7.2k tokens (3.6%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ Messages: 7.4k tokens (3.7%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ Free space: 125k (62.5%)
⛶ ⛶ ⛶ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ Autocompact buffer: 45.0k tokens (22.5%)

Sub-Agent Sessions (separate contexts)
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ Total: 140k tokens across 4 agents
│ ├─ service1-agent: 35k tokens
│ ├─ service2-agent: 40k tokens
│ ├─ service3-agent: 30k tokens
│ └─ service4-agent: 35k tokens

Alternative Solutions

No response

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

User Interaction Examples

Example 1: Quick check after Task completes
User: [sees agent report at top of response]
User: /context
[sees "Sub-Agent Sessions: 185k tokens across 5 agents"]
User: [decides if they want more detail]
User: /agents
[sees full breakdown with file access details]

Example 2: Debugging why agent didn't find something
User: "Why didn't the agent find the permission configuration?"
Claude: "Let me check the agent session details..."
[runs /agents internally or references cached session data]
Claude: "The architecture-explorer read 25 files but didn't search
the resources/ directory. Let me launch it again with
explicit instructions to check config.role-permission/"

Example 3: Optimizing multi-repo workflows
User: "That took a while. Can we optimize?"
Claude: "Looking at the sub-agent usage:"
[shows /agents output]
Claude: "The 4 sub-agents ran in parallel but instrument-api-agent
used 40k tokens. We could skip it since permissions are
defined in user-management only. Next time I'll only launch
user-management-agent and frontend-agent."

Additional Context

Benefits of This Solution

✅ Transparency: Users understand the actual cost of multi-agent operations
✅ Debugging: Quickly identify why agents missed information
✅ Optimization: Users can request more targeted agent delegation
✅ Education: New users learn how sub-agent architecture works
✅ Cost awareness: Important for teams monitoring token usage
✅ Trust: Users see the work happening "behind
the scenes"