[FEATURE] Include per-request peak context usage in sub-agent result data

Preflight Checklist

• [x] I've searched existing issues and didn't find a match
• [x] I've read the documentation
• [x] I can reproduce this issue consistently

What's Wrong?

When Claude Code spawns sub-agents (e.g., Haiku for Explore agents), the parent session only receives cumulative token totals in the result JSON modelUsage object:

"claude-haiku-4-5-20251001": {
  "inputTokens": 3208,
  "cacheReadInputTokens": 429633,
  "cacheCreationInputTokens": 67285,
  "outputTokens": 6977,
  "contextWindow": 200000,
  "maxOutputTokens": 32000
}

The sum of input+cache tokens (500,126) far exceeds the context window (200,000) because it's cumulative across all sub-agent API requests, not a single request's context usage.

There is no way to determine the peak per-request context usage for sub-agent models, which is needed to accurately display "how full was the context window" metrics.

The parent session's JSONL file does not contain per-request entries for sub-agent API calls — only the parent's own requests are logged.

What Should Happen?

Include peakContextUsage (the maximum single-request context fill) in the per-model modelUsage data returned by sub-agent sessions. For example:

"claude-haiku-4-5-20251001": {
  "inputTokens": 3208,
  "cacheReadInputTokens": 429633,
  "cacheCreationInputTokens": 67285,
  "outputTokens": 6977,
  "contextWindow": 200000,
  "maxOutputTokens": 32000,
  "peakContextUsage": 145000
}

This would allow consumers to display accurate context window usage percentages for sub-agent models without needing access to the sub-agent's JSONL file.

Use Case

• Accurate context window reporting: Display "Context window: 145K / 200K input tokens (73%)" instead of hiding it or showing impossible 250% values
• Token budget optimization: Know whether sub-agents are approaching context limits
• Monitoring and alerting: Detect when sub-agents need compactification

Related: #43456 (exposes sub-agent token data in hooks — this issue requests peak context specifically in result JSON)

Claude Model

claude-opus-4-6

Is this a regression?

No, this data was never included

Claude Code Version

2.1.88

Platform

Other

Operating System

Linux

Terminal/Shell

bash