Extend `usage` schema with cache / reasoning / duration / cost fields

Current state

The protocol's usage object is defined at spec/protocol.md lines 262-264:

usage:
  input_tokens: number       # already documented
  output_tokens: number      # already documented
  total_tokens: number       # already documented

These cover the minimal token accounting needed for cost display. They are too thin for current mainstream providers:

• Anthropic reports prompt caching under separate fields (cache_read_input_tokens, cache_creation_input_tokens). For long-running agents that hit cache 90%+ of the time, ignoring cache vs. non-cache input token counts misrepresents cost by an order of magnitude.
• OpenAI o-series (o1, o1-mini, o3, …) reports completion_tokens_details.reasoning_tokens separately from output_tokens — billing is different.
• Anthropic Claude with extended thinking also splits reasoning tokens.
• Turn duration (duration_ms) is something the bridge/agent can measure locally more accurately than the host (host wall-clock includes spawn + IPC overhead).
• Estimated cost (cost_usd) lets bridges that ship a pricing file surface a single cost number; hosts that don't have a pricing source can ignore it.

Proposal

Add the following recommended keys to the usage schema, all optional:

usage:
  # Existing (lines 262-264)
  input_tokens: number
  output_tokens: number
  total_tokens: number

  # New recommendations:
  cache_read_input_tokens: number       # Anthropic cache hits
  cache_creation_input_tokens: number   # Anthropic cache writes (first-write cost)
  reasoning_tokens: number              # o1 / Claude thinking

  duration_ms: number                   # Agent-measured wall-clock for the turn
  cost_usd: number                      # Estimated cost; bridge may compute from input/output/cache/reasoning + model pricing

Document them as:

• Optional, forward-compatible. Hosts that don't recognise them MUST ignore them (already a property of the existing recommendation).
• Recommended semantics:
  • cache_*_tokens count toward input_tokens only if the implementation chooses to. The standard convention is input_tokens = non-cached input + cache_read_input_tokens + cache_creation_input_tokens, so totals stay consistent. Document this convention explicitly.
  • reasoning_tokens is a subset of output_tokens (when applicable), not additive.
  • duration_ms excludes spawn/IPC overhead — measures the CLI's own work.
  • cost_usd is best-effort; bridges without a pricing source emit no value rather than guess.

Why now

The Node runner currently drops usage entirely (separate bug report). Once that bug is fixed and usage is plumbed through, the field becomes usable. Adding the additional keys now — alongside the plumbing fix — keeps us from having to bump the spec again in six months when Anthropic ships a new token type.

Compatibility

Purely additive. Hosts that already understand the three documented keys continue to work. Hosts that don't understand the new keys ignore them (per the existing forward-compatibility rule).

Cross-SDK

This is a spec change, so it should mirror across both the Node and Python SDKs. The Node fix is the trigger; Python follows.

Suggested labels

spec, enhancement, sdk/python, sdk/node

Start with spec/protocol.md lines 262-264, then inspect the Node runner's usage handling and the Python SDK's corresponding schema or serialization path. Add the optional fields with the stated token, duration, cost, and forward-compatibility semantics, and ensure both SDKs preserve them once usage is plumbed through.