[FEATURE] Expose usage-credit state to the session (status line payload) — the plan-limit percentage alone makes agents mis-pace

Feature request: expose usage-credit balance to the session (status line payload)

Summary

Claude Code tells the model how much of the plan limit is used, but nothing about
usage credits — whether they are enabled, and what balance remains. When credits are
on, the plan-limit percentage is no longer a ceiling: hitting it means spending credits,
not stopping. A session that can only see the percentage will therefore reason about its
remaining capacity incorrectly, and it does so confidently, because the number it has
looks complete.

What the session can see today

The status line receives a JSON payload on stdin. Its rate_limits object is exactly:

{
  "five_hour":  { "used_percentage": 3,  "resets_at": 1787396400 },
  "seven_day":  { "used_percentage": 88, "resets_at": 1787652000 }
}

There is no credit field anywhere in the payload. Full list of top-level keys:
context_window, cost, cwd, effort, exceeds_200k_tokens, fast_mode, model,
output_style, prompt_id, rate_limits, session_id, session_name, thinking,
transcript_path, version, workspace.

The second source exists but is stale and incomplete

~/.claude.json → .cachedUsageUtilization.utilization does carry credit fields:

"extra_usage": { "is_enabled": true, "monthly_limit": 20000, "used_credits": 44,
                 "utilization": 0.22, "currency": "USD", "spend_limit_reached": false },
"spend":       { "used": { "amount_minor": 44 }, "limit": { "amount_minor": 20000 },
                 "balance": null, "auto_reload": null, "severity": "normal" }

Two problems, both measured on 2026-08-22:

1. It is stale, and nothing in the data says so. fetchedAtMs resolved to

2026-08-12 — ten days old. Every field around it reads as current: severity
is "normal", spend_limit_reached is false. The cached figure was
used_credits: 44 ($0.44); the web dashboard at that same moment showed $1.41.

1. balance is null. The dashboard showed a $99.32 current balance. Nothing

locally carries it. monthly_limit: 20000 is a spend cap ($200), not a balance —
reporting "$0.44 of $200" overstates the remaining headroom by a wide margin, since
the actual purchased balance is a different and smaller number.

So the only accurate answer available to a session is "unknown", and the only place the
balance exists is the dashboard the user has to read manually.

Why it matters — a concrete misjudgement

Working session, 2026-08-22. The seven_day figure read 88% with ~73h to reset. On
that basis the assistant recommended shrinking the remaining work — dropping a planned
adversarial review pass to conserve limit. The user then shared a dashboard screenshot:
usage credits were enabled, balance $99.32, with $1.41 spent against a $200
monthly cap. The 88% was never a wall. The recommendation to cut scope was wrong, and it
was wrong in the direction that quietly costs the user work they had already paid to be
able to do.

This is not a one-off: any agent pacing itself against the plan limit will systematically
under-use a paid-for capacity it cannot observe.

Proposal

Add credit state to the status line payload, alongside rate_limits:

"usage_credits": {
  "enabled": true,
  "balance":       { "amount_minor": 9932, "currency": "USD", "exponent": 2 },
  "spent_this_period": { "amount_minor": 141, "currency": "USD", "exponent": 2 },
  "monthly_limit":     { "amount_minor": 20000, "currency": "USD", "exponent": 2 },
  "resets_at": 1788220800,
  "auto_reload": false
}

Ranked, in case the full shape is not feasible:

1. enabled alone would fix most of the harm. Knowing credits are on tells a session

that the limit percentage is a soft edge rather than a hard stop.

1. balance turns pacing from guesswork into arithmetic.
2. Freshness — if the ~/.claude.json cache stays the delivery mechanism instead,

please refresh it on session start and let a consumer distinguish stale from current.
A number that is silently ten days old is worse than an absent one: absence prompts a
question, staleness produces a confident wrong answer.

Related, but not the same ask

• #77993 — make the billing identity visible and attribute limits to it. Adjacent: that

one is about which account a limit belongs to; this one is about a quantity that is
missing regardless of whose it is.

• #77703 — purchased credits unusable behind the monthly spend limit. Adjacent: that one

is about credits not being spendable; this one is about them not being visible to
the running session even when they are working correctly.

Environment

• Claude Code, macOS (Darwin 25.5.0)
• Observed 2026-08-22
• Payload inspected via a status-line script that mirrors stdin to a file