Expose usage/rate limit data via CLI flag or hook event

Feature Request

Problem

There's no programmatic way to access the current usage percentage against the 5-hour rolling window. The /usage command exists in interactive mode, but the data isn't available to:

• Hooks (no usage data in hook input payloads)
• CLI flags (no claude --usage or claude usage command)
• Local files (no usage stats written to ~/.claude/)

This makes it impossible to build custom alerts, dashboards, or automation around usage tracking.

Proposed Solutions (any of these would work)

Option A: CLI subcommand

claude usage --format json

{
  "plan": "max",
  "window_hours": 5,
  "usage_percent": 47.2,
  "tokens_used": 2360000,
  "tokens_limit": 5000000,
  "window_resets_at": "2026-03-24T18:30:00Z"
}

Option B: Hook event
Add a UsageThreshold hook event that fires when usage crosses configurable thresholds (e.g., 50%, 75%, 90%).

Option C: Session file enrichment
Write usage stats to ~/.claude/sessions/<pid>.json so external tools can read it.

Use Cases

• Custom early-warning notifications (e.g., desktop toast at 50% usage)
• Team dashboards tracking aggregate usage
• CI/CD pipelines that gate on remaining budget before launching expensive agent workflows
• Hooks that switch to cheaper models or reduce context when budget is low (relates to #38367)

Environment

• Claude Code on Windows 11
• Plan: Max/Pro subscription

🤖 Generated with Claude Code