[FEATURE] Expose cumulative token/cost usage in hook payloads for session budget warnings

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

Summary

Allow users to receive warnings as they consume their daily session budget (e.g., at every 10% of usage). This would help prevent surprise cut-offs and encourage mindful usage.

Motivation

Currently there is no way to automatically surface usage progress during a session. The /cost command exists but requires manual invocation. There is no mechanism to trigger warnings or custom scripts when usage crosses a threshold.

Proposed Solution

Expose cumulative token and cost usage in hook event payloads (e.g., UserPromptSubmit, Stop, or a new UsageThreshold hook event).

Example payload addition:

{
  "session_usage": {
    "input_tokens": 45000,
    "output_tokens": 12000,
    "cost_usd": 0.42,
    "daily_limit_usd": 5.00,
    "daily_usage_pct": 8.4
  }
}

This would allow hooks to fire custom scripts when thresholds are crossed:

# ~/.claude/scripts/usage-warning.sh
if [ "$DAILY_USAGE_PCT" -ge 10 ]; then
  osascript -e "display notification \"${DAILY_USAGE_PCT}% of daily budget used\" with title \"Claude Code\""
fi

Alternative Solutions

• /cost command — manual, not automatic
• OpenTelemetry — server/org-level only, not accessible to individual users in hooks

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Show a system notification every 10% of daily session budget consumed, so users can pace their usage throughout the day.

Additional Context

_No response_