[FEATURE] Include limit-reset grants in the headless get_usage control response (read-only)

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

I pay for several Claude Max subscriptions for my own work and keep a small private dashboard that shows, for each account, its limits and what is about to expire. It reads the limits the supported way: it runs Claude Code headless (claude -p --input-format stream-json --output-format stream-json) and sends the get_usage control request, the one behind the Agent SDK's usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET. Session and weekly limits, included credits and extra usage all arrive.

Limit resets do not. There is no non-interactive way to read how many limit resets an account has left and when they expire:

• the get_usage control response carries the limit-resets block as null, while the same account shows a grant on claude.ai (Settings → Usage → Limit resets);
• claude -p "/limit-reset" answers that the command "opens an interactive panel and isn't available in this environment";
• the status line input has rate_limits.five_hour and rate_limits.seven_day and nothing about limit resets (that part is requested in #99699).

Limit resets expire. The Opus 5.5 launch grant on my accounts ends on 22 October; with several accounts it is easy to let one lapse unused, and the only reminder is to open each account's settings page by hand.

Proposed Solution

ill the limit-resets block in the get_usage control response, read-only. If the extra request to the usage endpoint is a concern, put it behind an opt-in field on the control request (for example include_limit_resets: true).

Per grant, the useful fields are the ones claude.ai already shows or uses: a label, resets left and total, start and end time, which limits it clears, whether it needs a limit to be reached, and whether it is paused. An empty list should mean "none"; an absent or null block should mean "not available to this caller".

Spending a reset can stay interactive. This request is only about reading.

Alternative Solutions

• The same data in the status line input (#99699). That would help status lines, but not a headless caller that has no interactive session.
• A headless status form of the command, for example claude -p "/limit-reset status", that prints what is left and until when and never spends anything.
• What I do today: I copy the numbers into the dashboard by hand from the settings page of each account. It works, and it goes stale the moment a reset is spent or granted.

The automated alternatives outside Claude Code are to imitate a first-party client against the usage endpoint or to script the interactive UI. The updated Usage Policy rules the first out, rightly, and I do not want to do either. I would much rather use a supported path.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. A cron job runs Claude Code headless once an hour for each of my accounts and sends get_usage.
2. The response says: account A has 1 limit reset, clearing the session and weekly limits, usable any time, expiring 2026-10-22T16:00Z.
3. Three days before the expiry the dashboard reminds me that account A still has an unused reset.
4. I decide myself whether to use it, in the client or on claude.ai.

Additional Context

Claude Code 2.1.291 (in a container) and 2.1.293 (on the host), Linux, Claude Max 20x. The control request used: {"type":"control_request","request_id":"u1","request":{"subtype":"get_usage","skip_behaviors":true}}.