[FEATURE] Hook which fires when you run out of tokens; expose time when they will be available again

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 would like for there to be a mechanism to run a hook when Claude runs out of tokens, with machine-readable information about when they will be replenished.

The concrete use case I have in mind is to send myself a Slack message when my hard-working agent is unable to proceed, so that I can decide whether I want to authorize additional spend or otherwise plan my other work accordingly.

There is an earlier related issue which however has been closed; it is slightly different in scope and ask:

• #26551 asks for a hook which fires when a limit is _approaching_ so it is different in that mine fires a single time at a well-defined boundary. It was closed as stale a few weeks ago.

It has links to other issues about user visibility and management of hitting the token limit, but none of those are about exposing this information via a hook or making the resume date and time available in machine-readable format.

Proposed Solution

When you are about to display the "You've hit your limit · resets Apr 1 at 9pm (America/New_York)" notification, fire a NotificationUsageLimit hook. Pass in the date and time when the tokens will be reset as a hook parameter, or perhaps as an environment variable, expressed as a Unix time stamp.

Alternative Solutions

I suppose you could write a wrapper which identifies this situation, but it would have to be updated each time the localization of this notification message changes, and contain somewhat contorted logic to convert the human-readable time stamp (which can be relative or absolute) into a machine-readable time stamp.

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

• As in the near-duplicate, play a sad sound when the usage limit is hit.
• Send a Slack message (or Discord, Telegram, SMS, etc) to notify the user when running in headless mode.
• As part of a larger system to manage resources, run scripts which need for Claude to be idle while they are running. Capture the session before compacting? Save a backup?
• Suggest the user to take a well-deserved break? Display the time until you can resume in a screen saver?

Additional Context

_No response_