Preflight Checklist

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

Problem Statement

Currently, hooks receive session metadata (session_id, transcript_path, cwd, permission_mode) but NO token usage or cost information. This limitation prevents:

1. Real-time budget monitoring: Cannot trigger warnings when approaching token limits
2. Context-aware decisions: Cannot adapt behavior based on current token consumption
3. Automated session management: Cannot implement intelligent save/compact strategies based on cost
4. Integration with external systems: Cannot automatically log usage metrics to monitoring tools

Users must manually run /cost or /usage commands, or parse transcript JSONL files post-session, neither of which supports real-time automation.

Use Case: my tool for context monitoring
I'm building a tool (semantic memory system for engineering context) that needs to monitor Claude Code's 200k token window. A PostToolUse hook could automatically:

#!/bin/bash
# PostToolUse hook for my tool context monitoring

input=$(cat)
current_tokens=$(echo "$input" | jq -r '.usage.total_tokens')
session_cost=$(echo "$input" | jq -r '.usage.total_cost_usd')

# Alert if approaching context limit (80% threshold)
if [ "$current_tokens" -gt 160000 ]; then
  echo '{"type": "warning", "message": "Context usage at 80% ('"$current_tokens"'/200k tokens). Consider /compact or saving."}'
fi

 Log to external monitoring system
curl -s -X POST http://localhost:8081/context/monitor \
  -H 'Content-Type: application/json' \
  -d "{\"current_tokens\": $current_tokens, \"cost\": $session_cost}"

Currently impossible because hooks don't receive token/cost data.

Related Issues

• [FEATURE] Add token usage details to status line API #8861: Requests token data in status line API (different feature)
• [FEATURE] Pre-Exit Hook ( or bring us back Automatic Cost Display on Exit) #9293: Pre-Exit hook for cost display (closed as duplicate)
• [FEATURE] Real-time Token Usage Indicator in CLI #10593: Real-time token usage indicator
• [FEATURE] Full Customizable Status Bar #8832: Customizable status bar with token widgets

None of these specifically address exposing token data TO hooks as input.

Proposed Solution

Add token usage and cost fields to the JSON input passed to hooks via stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/project/path",
  "permission_mode": "ask",
  "hook_event_name": "PostToolUse",
  "usage": {
    "total_tokens": 45230,
    "input_tokens": 38000,
    "output_tokens": 7230,
    "cache_read_tokens": 12000,
    "cache_creation_tokens": 5000,
    "total_cost_usd": 0.87,
    "percentage_of_context_window": 22.6
  },
  "limits": {
    "context_window_tokens": 200000,
    "session_remaining_tokens": 1250000,
    "weekly_remaining_tokens": 8500000
  }
}

Implementation Notes

• Token data is already tracked internally (visible via /cost and /usage)
• Status line API already receives token data (per [FEATURE] Add token usage details to status line API #8861 discussion)
• Extending hook inputs to include this data should be straightforward
• All hook types would benefit, but PostToolUse and PreCompact are highest priority

Benefits

1. Proactive context management: Hooks can trigger compaction before hitting limits
2. Budget enforcement: Organizations can implement hard spending caps
3. Usage analytics: Stream metrics to external monitoring/observability platforms
4. Intelligent session management: Auto-save expensive sessions to memory systems
5. User experience: Automated warnings prevent surprise context window errors

Alternative Workarounds (Why They're Insufficient)

1. Parse transcript JSONL: Requires file I/O, complex parsing, only works post-session
2. Status line API: Display-only, not accessible to hooks
3. Manual /cost command: Requires user intervention, not automatable in hooks

Community Interest

Multiple issues (#8861, #10593, #7111) demonstrate strong demand for better token visibility. Exposing this data to hooks would enable the community to build powerful automation on top of 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