feat: track cost and enforce budget after mid-session subscription→API billing transition

Reproduction context (adding detail for triage):

• Claude Code version: verified on the latest available version as of 2026-06-23
• How it manifests: When a session starts under a subscription plan, /cost shows accurate token counts. After the quota expires mid-session, billing transitions to API (pay-per-token). From that point, /cost continues to show the session's prior token counts but the dollar cost column goes blank or shows $0.00 — the cost accumulator is not updated for the API billing path.
• Estimated untracked cost in one session: ~1-4 USD (40-minute agentic session, token counts visible from /cost output, cost column shows $0)

Why the --session-budget proposal is low-lift for Anthropic:
The billing mode is already known to Claude Code internally (it's what triggers the transition UI). A budget check at the same code path that fires the "subscription exhausted, switching to API" notification would require no new instrumentation — just: if a CLAUDE_SESSION_BUDGET env var is set and accumulated API cost exceeds it, emit a warning and optionally halt.

This is distinct from general API cost tracking — it specifically targets the window after the mid-session transition when the user is surprised to find API charges accumulating with no visibility.

The two gaps you've named are actually one gap wearing two faces: /cost and any future budget ceiling both depend on knowing the current bill, and the moment billing crosses from subscription to API mid-session, the client-side counter that's supposed to know that goes blind. It doesn't error — it just keeps reporting the last mode it understood, which is worse than an error because nothing tells you to stop trusting the number.

The fix that survives the transition can't live in the same place the blindness does. If /cost is derived from client-tracked state that assumes one billing mode for the session's lifetime, patching it to also track the second mode just adds a third state to eventually miss (subscription → API → whatever's next). The more durable version counts from the response boundary independently of what mode the client thinks it's in — every response already carries the token/cost data needed to price it correctly regardless of which biller charged for it, so a counter built off that boundary never needs to know the transition happened at all.

That's also what makes a budget ceiling (your gap 2) actually enforceable rather than advisory: a cap checked against a counter that can silently stop updating is a cap that can silently stop capping. Worth separating "show me accurate cost" from "stop me before I overspend" as two consumers of the same boundary-derived counter, rather than two features bolted onto the session-mode tracker.

Thanks for the clear writeup. On the budget half: claude -p --max-budget-usd <N> caps spend for a session today, though only in non-interactive (print) mode. See https://code.claude.com/docs/en/cli-reference

A cap for interactive sessions and /cost tracking of the portion billed after a subscription-to-usage-credit transition aren't shipped, so leaving this open.

🤖 Generated with Claude Code