[FEATURE] Per-Subagent Token Usage Tracking

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

Summary

Add visibility into token consumption by individual subagents spawned via the Task tool to help users understand resource usage and optimize their workflows.

Problem

Currently, Claude Code only provides:

• Aggregate session-level token usage warnings (e.g., "Token usage: 40123/200000")
• Daily totals in ~/.claude/stats-cache.json

When using custom subagents (like agent-1, agent-2, etc.), there's no way to measure how many tokens each agent consumed. This makes it difficult to:

• Optimize agent prompts and instructions
• Budget token usage across multiple agents
• Identify which agents are most/least efficient
• Debug unexpected token consumption

Proposed Solution

Option 1: Enhanced Agent Completion Messages

When an agent completes, include token usage in the tool result:

<function_results>
[Agent output...]

Agent Token Usage:
  Input tokens: 42,100
  Output tokens: 3,134
  Cache read: 12,500
  Cache write: 1,800
  Total: 45,234 tokens
</function_results>

Option 2: Task Management Integration

Extend the claude tasks command to show token metrics:

$ claude tasks

ID  Status      Subject                    Tokens
1   completed   Analyze config push        45.2K
2   in_progress Investigate issue2     12.8K
3   pending     Review  code for feature1    -

Option 3: Dedicated Metrics Log

Create ~/.claude/agent-metrics.jsonl with per-invocation records:

{
  "timestamp": "2026-02-02T21:32:10.980Z",
  "sessionId": "6d22acaa-30ce-4aa0-bc67-701e63f10040",
  "agentId": "ac6ccde",
  "agentType": "agent1",
  "taskDescription": "Build end-to-end workflow for config push workflow",
  "usage": {
    "input_tokens": 42100,
    "output_tokens": 3134,
    "cache_read_tokens": 12500,
    "cache_creation_tokens": 1800
  },
  "duration_ms": 45230,
  "model": "claude-sonnet-4-5-20250929"
}

Option 4: CLI Query Tool

Add a command to query agent metrics:

$ claude agent-stats --agent agent1 --last 7d

agent1 (last 7 days):
  Invocations: 23
  Total tokens: 892K
  Avg per invocation: 38.8K
  Model: claude-sonnet-4-5-20250929

Top 3 invocations by token usage:
  1. 2026-02-01 14:23 - "Analyze HA failover flow" - 125K tokens
  2. 2026-01-31 09:15 - "Debug cert allocation" - 98K tokens
  3. 2026-01-30 16:42 - "Review config push" - 87K tokens



## Implementation Notes

The data is likely already available since:
1. Agent invocations make API calls with tracked usage
2. `stats-cache.json` shows the system tracks model-level tokens
3. Agent IDs are already generated (e.g., `agentId: ac6ccde`)

The main work would be:
- Capturing usage per agent invocation (not just per session)
- Associating usage with agent metadata (type, task description)
- Exposing this data through UI/CLI/logs

### Alternative Solutions


Current manual approach:
1. Note session token count before spawning agent
2. Spawn agent
3. Note session token count after completion
4. Calculate difference


### Priority

High - Significant impact on productivity

### Feature Category

CLI commands and flags

### Use Case Example

## Use Cases

### 1. Agent Development & Optimization
When building custom agents, developers need metrics to refine their prompts:
```bash
# Current: No visibility
Task(agent1, "analyze config push flow")
# ??? tokens used

# Desired: See breakdown
Task(agent1, "analyze config push flow")
# Agent consumed: 45,234 tokens (input: 42,100, output: 3,134)

2. Multi-Agent Workflows

When running parallel agents or agent chains, understand which agent is the bottleneck:

# Spawn 3 agents in parallel
- agent1: 28K tokens
- agent2: 65K tokens (outlier - needs investigation)
- agent3: 31K tokens

3. Cost Management

For teams using Claude Code at scale, track token usage per agent type to optimize spending.

Additional Context

Benefits

1. Transparency: Users understand where tokens are being consumed
2. Optimization: Data-driven refinement of agent prompts and workflows
3. Debugging: Quickly identify runaway token consumption
4. Cost Control: Better budgeting for teams and enterprises
5. Agent Quality: Metrics to compare agent efficiency over time