[FEATURE] Expose context usage breakdown via Agent SDK

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Description

The Claude Code CLI has a /context command that shows a detailed breakdown of context window usage:

• System prompt tokens
• System tools tokens
• Memory files tokens
• Messages tokens
• Free space remaining

Request: Expose this information programmatically via the Claude Agent SDK, either as:

1. A method on the SDK client (e.g., session.get_context_usage())
2. A field on ResultMessage with the breakdown
3. A standalone API endpoint for session introspection

## Use Case

When building applications on top of Claude Code via the Agent SDK (like REST API wrappers), it's valuable to:

• Monitor context utilization per session
• Alert when approaching context limits
• Optimize prompts/tools based on actual token usage
• Provide users visibility into what's consuming their context

Currently only input_tokens/output_tokens totals are available, not the categorical breakdown the CLI shows.

Proposed Solution

  # Option 1: Method on session
  context = await session.get_context_usage()
  # Returns: {"system_prompt": 3100, "tools": 14900, "memory": 5000, "messages": 16700, "free": 115000}

  # Option 2: Field on ResultMessage
  result.context_usage  # Same structure

  Environment

  - Claude Agent SDK version: latest
  - Use case: REST API wrapper for Claude Code

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_