[FEATURE] Background agent should pause (not fail) when hitting session limit with known reset time

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

When a background agent hits a session/usage limit mid-task, it is terminated with status "failed" even though the API error response already includes a specific reset time (e.g. "You've hit your session limit · resets 9pm (Asia/Bangkok)").

This means:

• Any in-progress work by the agent (partial file edits, analysis, generated code) is lost with no checkpoint.
• The user has to manually re-dispatch the same task from scratch after the limit resets, re-explaining context that the orchestrator/agent already had.
• The system clearly has the reset time available (it's printed in the error message) but doesn't use it to distinguish a temporary, resumable condition from a genuine failure.

This is especially painful in multi-agent/orchestrator workflows, where a background subagent doing a long implementation task (e.g. a bug fix with regression tests) fails partway through, and the orchestrator has no way to know it should retry later rather than treat it as a dead end.

Proposed Solution

When a background agent's task fails specifically due to a rate limit / session limit error that includes a reset time:

1. Mark the task status as "paused" (or "paused: rate limited") instead of "failed", and store the reset time alongside it.
2. Preserve the task's state (prompt, conversation history, any partial progress) so it can resume from where it left off, the same way claude --continue / --resume works for interactive sessions.
3. Surface this clearly in the UI/CLI, e.g.:

⏸ Agent "FT2 Bridge Fix" paused — resumes automatically at 9pm (Asia/Bangkok)

1. Optionally, auto-resume the task once the limit window resets (with a setting to opt in/out), or at minimum prompt the user to resume with one command/click once it's available again, rather than requiring them to manually re-dispatch the whole task and re-supply context.

This mirrors how permission prompts already "pause" execution until the user responds — a rate-limit hit with a known reset time is conceptually the same: a temporary blocking condition with a clear resolution path, not a terminal failure.

Alternative Solutions

Currently, the only workaround is:

• Wait for the limit to reset manually.
• Run claude --continue or /resume to reload the orchestrator's conversation context.
• Manually ask the orchestrator to re-dispatch the failed subagent, hoping enough context survived in the conversation history to avoid redoing work.

This works for recovering conversational context, but does not recover the subagent's in-progress work, and requires manual intervention every time instead of automatic recovery.

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

1. I run Claude Code with an orchestrator that dispatches a background subagent to implement a bug fix plus regression tests.
2. The subagent has been running for ~20 minutes, has already written part of the fix, when it hits the session limit.
3. The task is marked "failed": Agent terminated early due to an API error: You've hit your session limit · resets 9pm (Asia/Bangkok).
4. All progress on the fix is lost. I have to wait until 9pm, then manually tell the orchestrator to redo the entire FT2 task from scratch, re-explaining the design gate decisions that were already agreed on.
5. Instead, I'd like the task to show as "paused, resumes at 9pm" and pick back up automatically (or with one command) from where it left off, without losing the partial implementation work.

Additional Context

Related existing issues showing background task lifecycle problems:

• #68992 (background tasks stuck "running" forever, no cancel)
• #28875 (Claude autonomously stopped a background task without confirmation, causing financial/progress loss)
• #58662 (background tasks from closed sessions persist/can't be stopped)

These suggest background task state management (running/paused/failed/stopped) needs a clearer, more reliable model in general, and treating "rate limit with known reset time" as a distinct "paused" state would be a good first step.