[Feature Request] Streaming per-subagent token usage events during execution

[ArielSmoliar]

Problem

• The SDK provides token usage in two places: RateLimitEvent.utilization (session-level, lagging) and model_usage in ResultMessage (per-agent, but only after completion). During
  execution, there's no way to observe how many tokens a specific subagent has consumed so far.

• This makes it impossible to build real-time resource management on top of the SDK. You can set a static max_budget_usd kill switch, but you can't dynamically adjust agent behavior based on actual consumption mid-execution.

Proposal

Emit a TokenUsageEvent (or extend the existing RateLimitEvent) per subagent during execution:

{
"type": "token_usage",
"agent_id": "researcher-agent",
"input_tokens": 14200,
"output_tokens": 3800,
"cache_read_input_tokens": 600,
"cumulative_cost_usd": 0.042,
"turn": 3
}

This could be emitted after each LLM call within a subagent, similar to how RateLimitEvent is already streamed.

Use case

• I'm building an open-source agent scheduler that sits above agent frameworks and manages resource allocation across concurrent agents.
• The Anthropic SDK's hook architecture (PreToolUse/PostToolUse at zero token cost) is already the most scheduler-friendly integration point across all the major agent platforms I analyzed.
• Streaming per-agent token usage would complete the picture by providing hooks for admission control and usage events for real-time accounting.

Concrete scenarios:

• Throttle a subagent that's consuming disproportionate tokens before it hits max_budget_usd.
• Downgrade a subagent to a cheaper model mid-execution if utilization patterns suggest the task is simpler than expected.
• Rebalance max_turns across concurrent subagents based on actual vs. projected consumption.

[emigre459]

Strong +1 — this is the missing primitive for per-sub-agent cost/observability, not just budgets.

Concrete use case: we run headless query() orchestrations that fan out to many named sub-agents (one per analysis task), all routed through a shared LiteLLM→Langfuse gateway. Today per-sub-agent token/cost is unrecoverable: the gateway sees a flat, unattributed call stream (no sub-agent id), and the OpenInference instrumentor emits no per-generation usage for the agentic path (calls happen in the CLI subprocess), so neither side can answer "which sub-agent was expensive." Related: openinference#3255 (sub-agent tool spans mis-parented via parent_tool_use_id=None), langfuse#14338 (multi-agent cost mis-aggregates because sub-agent cost is never emitted as nested generation spans).

A streamed TokenUsageEvent carrying agent_id/parent_tool_use_id + input/output/cache tokens (ideally cost) during execution — as you propose — would let us attribute spend the moment each sub-agent finishes, kill-proof, without post-hoc transcript reconciliation. Even exposing per-sub-agent usage on SubagentStop (alongside agent_transcript_path) would unblock most of this. Would love to see this prioritized.