[FEATURE] Feature Request: Expose agent token usage metrics in Task tool response

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

When using the Task tool to spawn sub-agents, the CLI displays useful metrics about each agent's execution (tool uses, token consumption). However, these metrics are not accessible in the Task tool's response, making it impossible to include them in aggregated reports or summaries.

Current Behavior

The CLI displays metrics after sub-agent completion:
⏺ 3 Task agents finished (ctrl+o to expand)
├─ Generate tests for music_search.go · 14 tool uses · 43.5k tokens
├─ Generate tests for utils.go · 7 tool uses · 42.4k tokens
└─ Generate tests for video_search.go · 13 tool uses · 45.0k tokens

But the Task tool only returns the text output and agent ID.

Proposed Enhancement

Include execution metrics in the Task tool response:
{
"output": "...",
"agentId": "a958364",
"metrics": {
"toolUses": 14,
"inputTokens": 35000,
"outputTokens": 8500,
"totalTokens": 43500,
"durationMs": 45000,
"turns": 14
}
}

Use Cases

1. Aggregated Reporting - Skills that spawn multiple sub-agents could include total token usage in summary reports
2. Cost Estimation - Accurate cost breakdowns for multi-agent workflows
3. Performance Optimization - Identify resource-heavy sub-agents

Proposed Solution

Ideal User Experience

When spawning sub-agents via the Task tool, the metrics should be automatically included in the tool response. Additionally, the master agent should have access to its own cumulative token usage to provide a complete picture. These metrics should be easily extractable for programmatic use.

Example workflow:

1. I spawn 3 parallel sub-agents to process files:

<invoke name="Task">
<parameter name="description">Generate tests for file1.go</parameter>
<parameter name="prompt">...</parameter>
<parameter name="subagent_type">general-purpose</parameter>
</invoke>

1. When each agent completes, the tool result includes metrics:

<result>
<name>Task</name>
<output>## Summary
Functions tested: foo, bar
Test cases added: 12
...</output>
<agentId>a958364</agentId>
<metrics>
<toolUses>14</toolUses>
<turns>8</turns>
<inputTokens>35000</inputTokens>
<outputTokens>8500</outputTokens>
<totalTokens>43500</totalTokens>
<durationMs>45000</durationMs>
</metrics>
</result>

1. The master agent can also access its own metrics (via a new tool or system variable):

<invoke name="GetSessionMetrics" />

<result>
<metrics>
<toolUses>27</toolUses>
<turns>12</turns>
<inputTokens>85000</inputTokens>
<outputTokens>15000</outputTokens>
<totalTokens>100000</totalTokens>
<durationMs>180000</durationMs>
</metrics>
</result>

1. I can then aggregate all metrics and include them in my final report:

### Execution Metrics

#### Sub-Agent Metrics
| File | Tool Uses | Turns | Tokens | Duration |
|------|-----------|-------|--------|----------|
| file1.go | 14 | 8 | 43.5k | 45s |
| file2.go | 7 | 5 | 42.4k | 32s |
| file3.go | 13 | 7 | 45.0k | 41s |
| Sub-Total | 34 | 20 | 130.9k | 118s |

#### Master Agent Metrics
| Metric | Value |
|--------|-------|
| Tool Uses | 27 |
| Turns | 12 |
| Tokens | 100k |
| Duration | 180s |

#### Total Session
| Metric | Value |
|--------|-------|
| Total Tokens | 230.9k |
| Total Duration | 298s |

1. I can write these metrics to a file for external processing:

<invoke name="Write">
<parameter name="file_path">/tmp/session_metrics.json</parameter>
<parameter name="content">{
"timestamp": "2026-01-30T01:30:00Z",
"skill": "go-unit-test-pr",
"pr_number": 156280,
"user": "xiaohui_sai",
"master_agent": {
"tool_uses": 27,
"turns": 12,
"input_tokens": 85000,
"output_tokens": 15000,
"total_tokens": 100000,
"duration_ms": 180000
},
"sub_agents": [
{"file": "file1.go", "tool_uses": 14, "turns": 8, "total_tokens": 43500, "duration_ms": 45000},
{"file": "file2.go", "tool_uses": 7, "turns": 5, "total_tokens": 42400, "duration_ms": 32000},
{"file": "file3.go", "tool_uses": 13, "turns": 7, "total_tokens": 45000, "duration_ms": 41000}
],
"totals": {
"total_tokens": 230900,
"total_duration_ms": 298000
}
}</parameter>
</invoke>

1. External script can consume and emit metrics:

#!/bin/bash
# emit_metrics.sh - Send Claude Code metrics to monitoring system

METRICS_FILE="/tmp/session_metrics.json"

# Parse JSON and emit to Prometheus/Datadog/CloudWatch/etc.
jq -r '.sub_agents[] | "claude_code_subagent_tokens{file=\"\(.file)\"} \(.total_tokens)"' "$METRICS_FILE" | \
while read metric; do
echo "$metric" >> /var/lib/prometheus/textfile_collector/claude_code.prom
done

# Emit totals
TOTAL_TOKENS=$(jq '.totals.total_tokens' "$METRICS_FILE")
SKILL=$(jq -r '.skill' "$METRICS_FILE")
USER=$(jq -r '.user' "$METRICS_FILE")

curl -X POST "https://metrics.example.com/api/v1/series" \
-H "Content-Type: application/json" \
-d "{
\"series\": [{
\"metric\": \"claude_code.session.tokens\",
\"points\": [[$(date +%s), $TOTAL_TOKENS]],
\"tags\": [\"skill:$SKILL\", \"user:$USER\"]
}]
}"

Key Points

• Zero configuration - Metrics should be included by default
• Structured data - Returned as structured fields, not embedded in text output
• Consistent with CLI display - Same metrics shown in CLI should be available programmatically
• Works for both foreground and background agents - Metrics available regardless of run_in_background setting
• Master agent access - Master agent can query its own cumulative metrics to provide complete session totals
• Hierarchical visibility - Master agent sees both its own usage AND aggregated sub-agent usage
• Machine-readable output - Metrics can be written to JSON/CSV files for external consumption
• Integration-friendly - Easy to integrate with monitoring systems (Prometheus, Datadog, CloudWatch, Splunk, etc.) for:
• Tracking token usage over time
• Cost allocation by skill/user/project
• Performance dashboards
• Alerting on anomalous usage patterns

---
This enables full observability and integration with existing monitoring infrastructure!

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_