[FEATURE] Expose remaining API credit balance in statusLine JSON (or via CLI)

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

The statusLine stdin JSON exposes two kinds of spend data today:

• cost.total_cost_usd — estimated spend for this session only, and
• rate_limits.five_hour / rate_limits.seven_day — rolling quota windows, populated only for subscription (Pro/Max/Team) sessions.

There is nothing for the third billing mode: an account running on prepaid Console API credits. A session billed against a credit balance has no way, from inside Claude Code, to know how much money is left. cost.total_cost_usd tells you what this session burned; it does not tell you what remains, and it resets every session, so it can't be accumulated into a balance either.

The practical failure mode is that you find out you're out of credits by hitting credit_balance_too_low mid-run — typically in the middle of a long agentic task, after the work has already been partially done and paid for. The only way to check beforehand is to open console.anthropic.com and read the billing page, which is exactly the out-of-band workflow interruption that exposing rate_limits to statusLine already established is worth fixing for subscription users.

The asymmetry is the core of the request: subscription users got an at-a-glance "how much have I got left" surface. Credit-billed users did not, despite being the cohort where running out has a harder stop (the session fails outright rather than degrading to a reset timer).

Proposed Solution

Add an account-balance object to the stdin JSON already sent to statusLine commands, alongside the existing cost and rate_limits objects, e.g.:

{
  "cost": { "total_cost_usd": 0.42 },
  "rate_limits": { "five_hour": { "used_percentage": 23, "resets_at": 1751234567 } },
  "credits": {
    "remaining_usd": 128.40,
    "as_of": 1751234567,
    "expires_at": 1782770567
  }
}

• remaining_usd — current prepaid Console credit balance.
• as_of — epoch seconds, so a script can tell a fresh reading from a cached one and grey out/annotate a stale value rather than silently showing a wrong number.
• expires_at — optional, epoch seconds; Console credits expire a year after purchase and that date is currently only reachable from invoice history (see #95082).
• Populated only for credit/usage-billed sessions, following the exact conditional-population pattern rate_limits already uses (absent entirely for subscription-only or third-party-backend sessions, the same way five_hour/seven_day are absent for API-key sessions).
• Epoch seconds throughout, consistent with how resets_at is already represented.

If per-render freshness is a concern, a cached reading refreshed on session start and after each billed call would be entirely sufficient — the value moves slowly relative to statusline render frequency, and as_of makes the staleness explicit rather than hidden.

If a stdin field isn't feasible short-term, a documented machine-readable command (e.g. claude credits --json, or a Console GET /v1/credits endpoint) would unblock this — though the stdin field is strongly preferred, since shelling out on every statusline render adds a process spawn to the hot path.

Alternative Solutions

| Workaround | Why it fails |
|---|---|
| Check console.anthropic.com before starting | Out-of-band and manual — the same workflow interruption that exposing rate_limits to statusLine was accepted to fix for subscription users |
| Accumulate cost.total_cost_usd across sessions locally | total_cost_usd is an estimate and per-session; it drifts from actual billed amounts, knows nothing about top-ups made elsewhere, and every statusLine script would have to reimplement the bookkeeping |
| Let the run fail and top up when it does | Failure lands mid-task, after partial work is already paid for; on long unattended runs it's discovered long after the fact |
| Scrape the Console billing page | Fragile, unsupported, and not something a local CLI should be doing |

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

1. I start a long batch task on an account billed against prepaid API credits.
2. Before committing, I want to know whether the remaining balance covers it — the same decision subscription users make by glancing at their 5h window.
3. Today: the statusline can show what this session has cost so far, but nothing about what's left, so the answer is either "open the Console" or "start and find out".
4. With this: the statusline shows remaining balance at a glance, and the run either starts with confidence or gets topped up first — instead of dying at credit_balance_too_low partway through.

Additional Context

This came up while building super-status, a community statusLine script that surfaces plan usage, context, cost, and session-quality metrics as labeled lines. The subscription side has everything it needs since rate_limits shipped in v2.1.80; the credit-billed side has a blank where the equivalent line would go, and no data source to fill it from.

Related issues

| # | Issue | Status |
|---|---|---|
| 1 | #80725 — Add remaining credit balance field to statusLine JSON payload | Closed (not planned / stale) — same core ask, closed without a stated rationale |
| 2 | #67436 — Usage/spending API endpoint + status line integration | Closed (duplicate) — asked for the endpoint and the statusline surface together |
| 3 | #95082 — Warn before Console API credits expire | Closed — adjacent: the expiry date this issue proposes surfacing as expires_at |
| 4 | #67083 — "Credit balance" and "Current balance" use identical framing for unrelated billing systems | Open — context on why the two balance concepts need to stay distinct in any exposed field name |