Feature request: programmatic access to session usage/cost data

Feature Request

Problem

There is no programmatic way for Claude Code (the model or a script running alongside it) to access the session's usage/cost data. The /usage slash command is interactive-only — it requires manual user input and cannot be invoked by the model, a hook, or a shell script.

Use Case

I'm building a workflow orchestrator (as a Claude Code skill/plugin) that spawns multiple agents across phases (TDD → Plan → Execute → Review → Doc → PR). At the end of the workflow, I want to automatically include the total session cost in the PR body — no manual step.

Today this is impossible because:

1. /usage can only be typed by the user, not invoked programmatically
2. The local JSONL transcripts have raw token counts but miss subagent sessions and require maintaining a hardcoded pricing table
3. There is no claude usage CLI subcommand or API to query accumulated cost

Proposed Solution

Any of these would unblock the use case:

1. CLI flag: claude usage --format json — outputs current session cost/token data to stdout
2. Environment variable or file: Claude Code writes a usage.json to a known path (e.g., ~/.claude/sessions/<id>/usage.json) that includes aggregated cost across all subagents
3. Model-accessible tool: A built-in tool (like Read or Bash) that the model can call to retrieve its own session metrics
4. Hook event: An onUsageUpdate hook that receives cumulative cost data, allowing scripts to capture it

Why JSONL Parsing Is Insufficient

• Subagent Agent() calls spawn separate sessions with separate JSONL files — there's no parent→child linkage to aggregate them
• Token pricing must be hardcoded and maintained manually
• Server-tool costs (web search/fetch) are tracked as request counts, not dollar values
• The model itself has no way to read its own transcript mid-session

Environment

• Claude Code CLI v2.1.185
• macOS (Darwin 25.5.0)