Expose session token usage to hooks (UserPromptSubmit additionalContext, env var, or hook payload field)

Problem

There is no first-class way for Claude (the model) to be aware of the session's token usage during a long-running conversation. /usage and /cost are interactive-only and not machine-readable. Hooks don't receive token usage in their event payload, and no env var or file is documented as carrying live session token counts.

This matters for long sessions where I want Claude to factor token spend into decisions ("we're at 600k, wrap up the investigation rather than spawning another subagent"). Today the only path is for the user to manually run /cost and paste it in.

With a functionality like this, we can ask Claude to estimate a token budget, then push it to try and stay within that budget, stop working if it thinks it needs to blow through the budget, etc. like we would with any employee / service provider etc.

Workaround we ended up with

A UserPromptSubmit hook that parses the transcript jsonl pointed to by transcript_path in the hook event, sums the usage records (input, output, cache_read, cache_creation), and emits the totals as hookSpecificOutput.additionalContext. This works but:

• It's parsing an undocumented internal file format that could change without notice.
• Every user has to write the same script.
• It double-counts if multiple model providers/iterations are interleaved oddly, and is fragile across transcript schema changes.

Requests (any one would solve this)

1. Best: include a token_usage field in the UserPromptSubmit (and ideally Stop / PreToolUse) hook event payload, with cumulative session totals (input, output, cache_read, cache_creation, plus cost if available).
2. Good: a documented env var (e.g. CLAUDE_SESSION_INPUT_TOKENS, CLAUDE_SESSION_OUTPUT_TOKENS) the harness exports into hook subprocesses.
3. Acceptable: a --json flag on /usage or /cost that emits machine-readable output, callable from a hook subprocess.

Why a hook field beats a CLI flag

Hooks already run on every prompt submission, so a payload field has zero extra cost. A CLI flag still requires shelling out and parsing, and /usage being interactive-only means today's workaround has to read transcript jsonl directly.

Environment

• Claude Code (VSCode extension)
• macOS Darwin 25.2.0
• Model: Opus 4.7 (1M)

Filed at user request via Claude Code session.