Readiness and idle signals for orchestrators: provider-error notify event, Stop payload with turn usage, and a SessionIdle hook event

What variant of Codex are you using?

CLI (codex-cli 0.153.4 on macOS 26.6, ChatGPT auth)

What feature would you like to see?

Hooks give orchestrators turn boundaries (Stop, SessionStart, SessionEnd) and notify reports turn completion, but nothing reports that a session cannot work (rate limit, usage limit, auth failure) or that it has gone idle with input waiting. In our tmux team of Codex and Claude Code sessions, a task assigned to a session that had hit its usage limit sat unnoticed; the orchestrator could not tell "idle" from "stuck".

Proposal

1. notify and hooks: a provider-error event with a stable error_class (rate_limit | usage_limit | auth | network | server), retry_after_seconds when known, thread id and turn id, so a watchdog can mark the session degraded and reassign work.
2. Stop hook payload: include the turn's token usage (input, cached input, output, reasoning) and the thread and turn ids, so per-task cost can be recorded at the boundary where work is accepted.
3. SessionIdle hook event: fires once when a turn ends with an empty queue and at a configurable debounce while idle, with queued_items and idle duration in the payload; decision: "block" with a reason starts a continuation turn exactly as Stop does today. This lets a hook wake the session from a shared task ledger without codex queue injecting text as the user.

Additional information

The [features].codex_hooks deprecation warning we hit while setting this up is correct and the rename to [features].hooks works; this request is about what hooks can observe, not the flag.

codex-cli 0.153.4 on macOS 26.6, ChatGPT auth, features.hooks = true, agents.enabled default.

Start by tracing the existing hooks paths for Stop, SessionStart, SessionEnd, and notify; the issue names no files or tests, so these event entry points are the first place to investigate. Compare the current Stop continuation behavior with codex queue, then verify that provider-error, enriched Stop, and SessionIdle cover the payloads and lifecycle cases described here.