Rate-limit and plan-quota windows in usage_update

[tahaburak]

Problem

The session-usage RFD covers context size and cost, and leaves rate limits and quotas to a future RFD ("What about rate limits and quotas?"). Subscription-backed agents all have plan windows (a rolling 5-hour window, a weekly window, per-model quotas). Today a client that shows plan limits gets them, if at all, through a different vendor-specific route per agent:

• claude-agent-acp (0.81.2): usage_update with _meta["_claude/rateLimit"] (status, resetsAt, rateLimitType, optional utilization). One window per event, sent only when the info changes; the percentage is left out while the status is allowed. An event that arrives before the turn's first usage is dropped (rate_limit_event dropped when it arrives before the turn's first usage (first turn of a fresh process) claude-agent-acp#1127).
• codex-acp (1.13.1): receives account/rateLimits/updated from the Codex app server but doesn't forward it; the numbers are only in the /status reply, as Markdown with local reset times (Surface Codex RateLimitSnapshot (usage windows) over ACP, not just in /status text codex-acp#227).
• antigravity-acp (1.2.1, from the registry): reads per-model quotaInfo (remainingFraction, resetTime) but doesn't forward it. A quota stop is sent as agent message text and the turn ends with end_turn, so a client can't tell it from a normal reply.

The underlying data has the same shape in all three: a set of windows, each with how much is used and when it resets.

Proposal

An optional limits field on usage_update:

{
  "sessionUpdate": "usage_update",
  "used": 53000,
  "size": 200000,
  "limits": [
    { "id": "five_hour", "label": "5-hour limit", "usedPercent": 40, "resetsAt": "2026-09-26T16:40:00Z", "status": "allowed" },
    { "id": "weekly",    "label": "Weekly limit", "usedPercent": 10, "resetsAt": "2026-09-30T09:00:00Z" }
  ]
}

• id: agent-defined, stable across updates, so a client can follow one window over time.
• label: human-readable name.
• usedPercent: 0 to 100, optional (absent when the agent doesn't know).
• resetsAt: RFC 3339, optional.
• status: optional, allowed | warning | exhausted.
• Updates may be sparse: a window not listed keeps its last value.

Open points:

• size is required on usage_update; a limits change can arrive when the agent has no fresh context numbers. A sibling session/update variant would avoid that coupling.
• A quota stop should be distinguishable from a normal end of turn, e.g. a distinct stopReason or an error code, ideally naming the exhausted window's id and its resetsAt, so a client knows when the agent can work again.