Expose Codex SDK context window usage, matching CLI "Context XX% used"

What would you like?

Please expose current context window usage through the Codex SDK / JSON event stream, similar to the Context XX% used indicator shown in the Codex CLI.

Today, @openai/codex-sdk@0.121.0 exposes per-turn token usage on turn.completed:

• input_tokens
• cached_input_tokens
• output_tokens

But it does not appear to expose the current thread context usage percentage, total context tokens, or effective/max context window size.

Why is this useful?

Applications embedding Codex SDK can show users the same operational signal available in the CLI, for example:

Context 37.2% used (74,480 / 200,000 tokens)

This is useful for long-lived agent sessions, chat bots, and UI integrations that need to warn users before context gets too full or suggest compaction.

Suggested API shape

Any of these would work:

1. Include context usage in turn.completed:

{
  type: "turn.completed",
  usage: {
    input_tokens: number,
    cached_input_tokens: number,
    output_tokens: number,
    context_tokens?: number,
    context_window?: number,
    context_percentage?: number
  }
}

1. Add a dedicated event:

{
  type: "context.updated",
  context: {
    total_tokens: number,
    max_tokens: number,
    percentage: number,
    model?: string
  }
}

1. Add a thread/client method such as:

await thread.getContextUsage()

Related comparison

Claude Agent SDK exposes a dedicated get_context_usage() API returning percentage, totalTokens, maxTokens, category breakdowns, etc. A similar SDK-level capability in Codex would let integrations keep parity with the CLI without estimating from per-turn token usage.

Related existing issues

This is related to, but distinct from:

• #16258, which asks to expose cumulative session cost in TokenCountEvent / event stream
• #19464, which asks for 1M token context support