Feature: expose session token usage to hooks and statusline commands

Feature Request

Problem

The statusline command (settings.json → statusLine.command) runs an external shell script, but there is no way to display cumulative session token usage (input + output tokens) in that badge. Token counts are rendered internally by Claude Code and not written to any accessible file or passed to hooks via stdin.

Similarly, hook events (PreToolUse, PostToolUse, UserPromptSubmit, Stop) receive session context but no token usage data.

Requested Change

Expose per-session token usage to:

1. Hooks — include a usage object in the stdin JSON payload for Stop (and optionally PostToolUse):

``json
{
"session_id": "abc123",
"usage": {
"input_tokens": 45231,
"output_tokens": 8120,
"cache_read_tokens": 12000,
"cache_write_tokens": 3000
}
}
``

1. Statusline — write a small JSON file to $CLAUDE_CONFIG_DIR/.session-usage.json (or similar) after each response turn, so statusline scripts can read it:

``json
{
"session_id": "abc123",
"input_tokens": 45231,
"output_tokens": 8120,
"total_tokens": 53351,
"updated_at": "2026-04-22T10:30:00Z"
}
``

Use Case

Plugin authors and power users want to show live token spend in the statusline — e.g. a badge like [CAVEMAN] 53k tok — to monitor costs and context usage without switching away from the terminal.

Alternatives Considered

• Scraping CLI output — not reliable
• Estimating tokens client-side — inaccurate
• Neither Stop hook stdin nor any disk file currently contains this data

Environment

• Claude Code CLI (macOS)
• Custom statusline plugin using statusLine.type: "command"