[FEATURE] Expose session readiness to orchestrators: error class on StopFailure and a degraded state in ListAgents

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

We run several Claude Code and Codex sessions in tmux, coordinated by an orchestrator session over a SQLite message bus (delivery through a channel MCP server plus cross-session messaging). When a Claude session hits a usage limit, its turns end with an API error and nothing outside that terminal can tell.

Between September 10 and 13 the orchestrator delivered five task messages to a session that was showing an exhausted-usage error. The messages were delivered and marked read, the session could not run a turn, and the work sat for three days. The orchestrator's only option was to write "report when able" and wait.

StopFailure fires on the failing session and its matcher filters on error type, but the hook is display-only and the payload carries the error text rather than a stable class or a retry-after value a script can relay. ListAgents shows the session as reachable with no readiness state, so peers keep messaging a session that cannot work.

Proposed Solution

1. StopFailure payload: add error_class (rate_limit, usage_limit, auth, network, server) and retry_after_seconds when known, alongside the existing error text.
2. ListAgents and /list-agents: add a per-session readiness field, at least idle | busy | degraded, with degraded set after a StopFailure until the next successful turn.
3. notify_when_idle: state explicitly that a turn ending in StopFailure also produces the idle notice, and include the error class in its one-line status.

Alternative Solutions

Parse the failing session's terminal with tmux capture-pane, or run an external watcher over the transcript JSONL looking for API error lines. Both are brittle, depend on display text, and cannot be read by a peer session through the messaging tools.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

An orchestrator session assigns bounded tasks to several Claude Code sessions over cross-session messaging. Before assigning, it calls ListAgents and skips any session whose readiness is degraded. When a session's turn ends in StopFailure with error_class usage_limit, a StopFailure hook relays the class to the orchestrator's ledger, which reassigns the task at its deadline instead of waiting for a human to notice.

Additional Context

Any orchestrator built on cross-session messaging or channels has to distinguish "idle and able" from "idle because it cannot work". Today the only way is to parse the terminal.

Claude Code 2.1.273, macOS 26.6, claude.ai subscription auth, sessions started with --dangerously-load-development-channels for a local channel server, plus native cross-session messaging.