[FEATURE] Expose account usage % to hooks and CLI so automated workflows can yield tokens for manual use

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

Claude Code has no way to observe current account usage against plan limits. When running long automated workflows (multi-phase code generation, autonomous agent chains, etc.), there is no mechanism to interrupt work at a safe threshold — say 80% — to preserve remaining tokens for manual queries. The workflow runs until the account limit is hit, at which point the user is completely locked out: no capacity left to ask a quick question, review output, or prepare for a meeting. The only recourse is to wait for the usage window to reset.

This has nothing to do with context window size, which is already managed well. This is about account-level token quotas — the daily and weekly usage limits tied to a Claude plan.

Proposed Solution

Expose current account usage as a queryable value available to both hooks and a CLI command.

CLI command:

claude usage
{
  "daily": {
    "used": 820000,
    "limit": 1000000,
    "pct": 0.82,
    "resets_at": "2026-03-25T00:00:00Z"
  },
  "weekly": {
    "used": 3100000,
    "limit": 5000000,
    "pct": 0.62,
    "resets_at": "2026-03-28T00:00:00Z"
  }
}

Hook payload addition (PreToolUse, PostToolUse, Stop):

{
  "account_usage": {
    "daily_pct": 0.82,
    "weekly_pct": 0.62
  }
}

Both daily and weekly are needed. A workflow that looks healthy on a daily basis may be close to a weekly ceiling, or vice versa.

Alternative Solutions

1. Polling the Anthropic API

The API is stateless — there is no session or account endpoint that exposes live usage data mid-session. Each request is independent with no concept of cumulative quota state.

1. Proxy layer between Claude Code and the API

You could intercept every API response (which includes per-request token counts) and accumulate a running total. This is fragile, requires routing Claude Code's traffic through a local proxy, and still wouldn't give you the authoritative account-level quota figure — only a locally-counted approximation.

1. Claude Code Stop hook with stop_reason

Adding a stop_reason: "usage_limit" to the Stop hook payload would tell you after the limit was hit, but by then you're already locked out. It doesn't help you interrupt early to preserve reserve capacity. Less flexible than observable usage % for the same reason.

1. Context window management

Already handled well by Claude Code's compression. Not the same problem — account usage limits are a separate ceiling entirely.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

A developer runs /gsd:autonomous — an agentic workflow that plans and executes multiple phases of code generation across parallel subagents. Each phase takes 80–150k tokens. With a weekly limit of 5M tokens, three phases costs roughly 60% of the weekly budget.

Today: the workflow runs until the limit hits. The developer goes to ask a quick question — "what did we just build?" — and gets a rate limit error. They have nothing left for the rest of the week.

With this feature:

1. A PreToolUse hook checks account_usage.weekly_pct
2. At 80%, the hook writes a resume_pending flag and sends a stop signal
3. The developer still has ~20% of their weekly budget for manual queries, meeting prep, code review questions
4. When the weekly limit resets, a startup hook detects the flag and resumes the workflow automatically

The key insight: automated work should be interruptible and resumable; manual capacity should never be zero.

Additional Context

• The Anthropic API is stateless — there is no session endpoint that currently exposes this data. The values would need to come from the same account metering the dashboard already uses.
• Both dimensions matter independently. A user might burn through daily quota quickly but have weekly headroom, or be fine daily but near the weekly ceiling. The hook needs both to make a safe interrupt decision.
• The threshold at which to interrupt should remain user-configurable (not hardcoded) — different workflows have different tolerance. An --interrupt-at-daily 80 --interrupt-at-weekly 75 flag on autonomous commands, or a config value in settings.json, would be the natural home for this.
• This is a quality-of-life issue that compounds significantly for users running agentic/automated workflows, which are exactly the use cases Claude Code is designed for.