What happens
- The active provider prints its usage-limit message.
- uuldana-cli recognizes the wording and waits until the provider has been quiet for 1.5 seconds.
- uuldana-cli stops the provider gracefully. You do not press Ctrl+C.
- That entry rests for
cooldown_minutes(default 300), or until the time the provider reports if it ever reports one. uuldana-cli does not read a reset time from the message today. - The next entry that is available starts, with the visible conversation as its first prompt, inside the same permission ceiling. If nobody had spoken to the agent that stopped, there is nothing to carry and the next one starts without a prompt.
- If every entry is resting, uuldana-cli says when the first one returns.
The new run belongs to the same uuldana-cli session, so uuldana resume still finds the whole history across providers.
Turning it off
Set "failover": false to keep a session on its first provider. Failover also needs at least two entries in providers.
How a limit is recognized
Detection reads the text a provider prints and waits until the provider has been quiet. A provider that quits on its own with a failing exit status after a limit message counts the same way. A normal exit after the message is treated as you leaving.
One general reader reads every agent that runs in a native terminal, including ones you add with a manifest. It keeps no list of sentences. It looks for a word that says an allowance is gone (hit, reached, exceeded, exhausted, out of) next to a word that names it (limit, quota, credits), or for an error code that says the same, and then scores what stands around it: when the allowance returns or what to do about it, a time, being addressed to you, a short line. Weekly, 5-hour, per-session, and per-model limits are the same to it.
Only when the allowance is gone
The work moves only when an allowance is gone. A warning that one is only partly used is not a stop: a share below 100% (“You’ve used 85% of your weekly limit”), “approaching”, “almost”, “close to”, “running low”, and “10 left” all leave the session where it is. A limit per minute, a question, source code, and a quoted string are not taken for a stop either.
If an agent keeps working for 20 seconds after text that looked like a limit, the text is taken for something else and the agent is left running. Text that looked like a stop and was turned down is not dropped without a trace: the header says that text like a usage limit was ignored, and the session journal records it, so a missed stop can be seen afterwards. A manifest may list limit_phrases of its own for wording the reader does not understand.
The text that stopped an agent is taken out of what the next agent is given, so the new agent is not shown the limit message and does not take it for its own.
These messages are not a documented interface of the providers and may change. The limit event is labeled inferred, not native.
What carries over
Only the visible conversation. Hidden reasoning, provider memory, approvals, and tool calls still running do not move, and the prompt given to the next provider says so. See Context handoff.
Tested how
The failover sequence is covered by tests that run real child processes in real pseudo terminals and print what an agent’s screen prints. The general reader is checked against a set of messages that must stop and a larger set that must not, including warnings at 50% to 99%, a limit per minute, and a question about a limit.
On 2026-10-31, in a real Windows Terminal window, a stand-in program printed a weekly-limit line in front of a real Claude Code session, and the work moved to Codex. A usage-limit line printed in front of a real Codex session moved the work back to Claude Code. The same session with “You’ve used 85% of your weekly limit” stayed where it was. These used printed text, not an exhausted account. A limit on a real account that was genuinely out of quota moved a session to another agent earlier in development, before the per-agent wording was removed. The wording of other agents has not been seen from a real exhausted account, so the general reader has only seen example sentences for them.