Claude Code extra usage, told through the 8-field event the SDK actually fires

Extra usage is the Anthropic billing setting on Pro and Max plans that, once toggled on, lets Claude Code keep running after you blow past your subscription allowance by charging the overflow at standard API rates. It is opt-in per account, capped by a monthly dollar ceiling you set in the console, and can be rejected mid-session if you hit that ceiling or if Anthropic's risk signals disable it. Docs: support.claude.com article 12429409. What the docs do not document is the wire format Claude Code actually emits while you consume it. That format is a `rate_limit_event` with 8 fields, and this guide walks through all 8 against real code.

They are declared in Fazm's ACP bridge at `acp-bridge/src/protocol.ts` lines 245-256, because the bridge forwards the Claude Agent SDK's `rate_limit_event` verbatim so a Mac app can consume it. The 8 fields: `status` ("allowed" | "allowed_warning" | "rejected" | "unknown"), `resetsAt` (Unix seconds), `rateLimitType` ("five_hour" | "seven_day"), `utilization` (0-1 float), `overageStatus` ("allowed" | "rejected"), `overageDisabledReason` (string or null), `isUsingOverage` (boolean), `surpassedThreshold` (0-1 float). Together, those tell a client app which of the two rolling windows you are in, how close to the ceiling, whether extra usage is picking up the slack, and if not, why.

Three patterns dominate. One, long-running agent sessions that never compact, because the input token count grows cubically with tool-call loops. Two, anything screenshot-based, because every frame is a multi-hundred-thousand-token image and vision models charge per token in, not per pixel. Three, scheduled background agents that fire without a human in the loop. Fazm's repo ships three of those: `com.m13v.fazm-inbox` (5 min), `com.m13v.fazm-founder-chat` (15 sec), `com.m13v.fazm-session-replay` (20 min). Each plist is a Claude Code session per tick. If you run a similar cron without a utilization guard, extra usage is the line item that absorbs the cost.

Because the Claude Code CLI in terminal mode has a human at the prompt. Fazm runs Claude Code over ACP inside a desktop chat surface, sometimes autonomously, sometimes at 3am when nobody is watching. If the session throws `credit_exhausted` silently, the user's inbox pipeline just stops. By forwarding the SDK's own rate_limit_event into Swift (see `Desktop/Sources/Chat/ACPBridge.swift` line 183), Fazm can render a warning banner at utilization > 0.8, auto-fall back to the bundled API key if `overageStatus` is `rejected`, and log `overageDisabledReason` to the session transcript so the user understands why their Pro plan stopped paying. None of that is possible from the terminal CLI alone.

`ACPBridge` has two `BridgeMode` values: `.personalOAuth` (your own Claude account, uses your extra usage allowance) and `.bundledKey(apiKey:)` (a bundled Anthropic API key Fazm pays for). When your personal plan returns a `credit_exhausted` event, the `BridgeError.creditExhausted` path at line 1599 fires, which the user-facing message formatter turns into "You've hit Claude's usage limit (resets X). Upgrade to Claude Pro at claude.ai for higher limits." The CHANGELOG at 2.0.7 describes the auto-fallback: "Fixed chat failing silently when personal Claude account lacks access to the selected model, now auto-falls back to built-in account." So the session survives the limit instead of dying on a silent 402.

Claude Code runs two rolling windows on Pro and Max. The five-hour window is the classic session budget; it resets as a sliding window relative to your first request. The seven-day window is the weekly ceiling Anthropic added in August 2025. Either can trigger extra usage consumption. The SDK's `rate_limit_event` tells you which one via `rateLimitType`, and `utilization` is your 0-to-1 position inside that window. Fazm uses both: a utilization banner in the chat UI, and, via `rateLimitType`, a message like "Your five-hour limit resets at 7:15pm" rather than a generic "rate limit" string. Source: `ACPBridge.swift` line 886 uses `rateLimitType` as the label.

Yes, three ways, with tradeoffs. First, keep sessions short and compact often. Every unnecessary context carry-over is a future input-token charge. Second, avoid screenshot-based agents for repetitive GUI work, since vision tokens are the dominant cost. Fazm uses real macOS accessibility APIs (AXUIElement and CGEvent) for clicking and reading state, which is why a Fazm workflow that toggles a Mail rule uses a few hundred tokens while a screenshot-based equivalent burns tens of thousands. Third, route autonomous cron agents through a cheaper model. Fazm's inbox and session-replay pipelines let you pin the model per pipeline so the 20-minute replay loop can run on Haiku while the 15-second founder chat uses Sonnet.

Yes. The ACP bridge logs every `rate_limit_event` to stderr with `Rate limit: status=..., type=..., utilization=..., resets=...` at `acp-bridge/src/index.ts` line 2464. Fazm's bridge stderr lands in `/tmp/fazm-dev.log` for dev builds or `/tmp/fazm.log` for production. Tail that file while you chat and you can watch your utilization climb in real time. When it crosses `surpassedThreshold`, the SDK changes `status` from `allowed` to `allowed_warning`, and at `rejected` you know the window closed.

Yes, when you sign in with `.personalOAuth` (the default), the extra usage pool is a single allowance on your Claude account, shared across anthropic.com chat, the Claude Code CLI in terminal, and any Fazm session. This is the practical consequence of OAuth: you are not running two accounts, you are running one account from two clients. So a long Fazm session at 2pm can push your five-hour utilization high enough that a 4pm Claude Code terminal session inherits a rejected rate limit. The UI banner in Fazm is deliberately the same fact the CLI would show, sourced from the same SDK event.

They answer different questions. `status=rejected` means your subscription allowance is exhausted for this window. `overageStatus=rejected` means the fallback billing at API rates has itself been disabled, which can happen if you hit your monthly spending cap, if the org turned extra usage off, or if Anthropic's payment risk layer rejects the card. `overageDisabledReason` is the human-readable string explaining which of those. A well-behaved client renders both: if `status=rejected` but `overageStatus=allowed`, the session continues on extra usage silently. If both are `rejected`, that is when your session actually dies and you need the fallback path Fazm wires up in `BridgeMode.bundledKey`.