feat: type ResultMessage.model_usage as dict[str, ModelUsage] (#1143)

Adds a `ModelUsage` TypedDict mirroring the TypeScript SDK's
`ModelUsage` shape and tightens `ResultMessage.model_usage` from
`dict[str, Any]` to `dict[str, ModelUsage]`. The value is passed through
verbatim from the CLI's `modelUsage` field, so this is type-only — no
runtime behavior change.

The two new `NotRequired` fields (`canonicalModel`, `provider`) are
emitted by the CLI once anthropics/claude-cli-internal#50283 lands. They
give callers a stable key for their own rate-table lookups across
provider-specific model ids and aliases (e.g. Bedrock ARNs →
`claude-opus-4-7`), so cost drift like "Opus 4.6/4.7 priced as 4.5" is
detectable client-side. Per-token rates were intentionally left out of
this pass (not authoritative); may follow separately with a source
marker.

**Verification:** type-annotation-only; `py_compile` clean on changed
files; existing `test_parse_result_message_with_model_usage` covers the
passthrough shape.

Co-authored-by: Claude <noreply@anthropic.com>

Author: benlehrburger-ant

src/claude_agent_sdk/__init__.py

@@ -85,6 +85,7 @@
     McpToolInfo,
     Message,
     MirrorErrorMessage,
+    ModelUsage,
     NotificationHookInput,
     NotificationHookSpecificOutput,
     PermissionMode,
@@ -555,6 +556,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "TERMINAL_TASK_STATUSES",
     "TaskUsage",
     "ResultMessage",
+    "ModelUsage",
     "DeferredToolUse",
     "RateLimitEvent",
     "RateLimitInfo",

src/claude_agent_sdk/types.py

@@ -1197,6 +1197,31 @@ class DeferredToolUse:
     input: dict[str, Any]
 
 
+class ModelUsage(TypedDict):
+    """Per-model token usage and cost breakdown.
+
+    Keys match the TypeScript SDK's ``ModelUsage`` shape (camelCase), since
+    the value is passed through verbatim from the CLI's ``modelUsage`` field.
+    """
+
+    inputTokens: int
+    outputTokens: int
+    cacheReadInputTokens: int
+    cacheCreationInputTokens: int
+    webSearchRequests: int
+    costUSD: float
+    contextWindow: int
+    maxOutputTokens: int
+    canonicalModel: NotRequired[str]
+    """Canonical model id used for the pricing lookup (e.g.
+    ``'claude-opus-4-7'``). May differ from the raw model string this entry
+    is keyed by (provider-specific ids, aliases)."""
+    provider: NotRequired[str]
+    """API provider that served this model (``'firstParty'``, ``'bedrock'``,
+    ``'vertex'``, ``'foundry'``, ``'anthropicAws'``, ``'anthropicGoogleCloud'``,
+    ``'mantle'``, ``'gateway'``)."""
+
+
 @dataclass
 class ResultMessage:
     """Result message with cost and usage information."""
@@ -1212,7 +1237,7 @@ class ResultMessage:
     usage: dict[str, Any] | None = None
     result: str | None = None
     structured_output: Any = None
-    model_usage: dict[str, Any] | None = None
+    model_usage: dict[str, ModelUsage] | None = None
     permission_denials: list[Any] | None = None
     deferred_tool_use: DeferredToolUse | None = None
     errors: list[str] | None = None