Repository navigation
Hooks stop firing after rate-limit stops or live hooks.json edits #21160
Description
What variant of Codex are you using?
CLI / TUI
Which version are you using?
codex-cli 0.128.0
What operating system are you using?
- Ubuntu 24.04 LTS on WSL2
- Kernel:
6.6.87.2-microsoft-standard-WSL2 - Node:
v22.22.0 - npm:
11.12.1
Bug description
Hooks can stop firing in a live Codex session under two conditions:
- When Codex hits a rate limit and stops, the expected lifecycle hook does not appear to run.
- When
hooks.jsonis edited while Codex is already running, hooks stop firing entirely for the remainder of that session.
This is more severe than hooks not hot-reloading. After a live hooks.json update, the session appears to lose hook execution altogether. The only reliable workaround I have found is to restart the Codex session.
The hook configuration file is valid JSON. In the affected workspace, the repo-local hook file exists at .codex/hooks.json, and jq validates it successfully.
Expected behavior
For rate-limit stops:
- The appropriate stop/session lifecycle hook should still run when Codex stops because of a rate limit, or Codex should explicitly document and surface that hooks are skipped for that stop reason.
- Hook-driven cleanup, logging, or continuation workflows should not fail silently.
For live hooks.json edits, one of these behaviors would be acceptable:
- Keep using the previously loaded hook configuration until the session restarts.
- Hot-reload the updated hook configuration safely.
- Detect the change, report that hooks require a restart, and keep the previous working hook set active.
What should not happen is that all hooks silently stop firing for the rest of the live session.
Actual behavior
Observed behavior:
- After a rate-limit stop, the stop-related hook does not appear to run.
- After modifying
hooks.jsonduring an active session, no hooks appear to run again in that session, even though the resultinghooks.jsonremains valid JSON. - Restarting Codex/session restores hook behavior.
Steps to reproduce
Scenario A: rate-limit stop
- Configure a simple hook that produces a visible side effect, such as appending a timestamp to a temporary log file.
- Start a long-running Codex CLI/TUI session with hooks enabled.
- Continue working until Codex hits a rate limit and stops.
- Check whether the stop/session lifecycle hook ran.
Scenario B: live hooks.json edit
- Configure a simple hook that appends to a temporary log file on each relevant event.
- Start a Codex CLI/TUI session and verify the hook fires.
- Edit
.codex/hooks.jsonwhile the session is still running. Keep the file syntactically valid. - Continue the same session and trigger more hook events.
- Observe that hooks no longer fire until the Codex session is restarted.
Impact
This breaks long-running workflows that rely on hooks for:
- cleanup after stop/session lifecycle events
- logging and audit traces
- user-defined guardrails
- continuation or handoff generation when a run stops unexpectedly
The failure mode is particularly costly because it is silent. The user may assume the hook-based workflow is still active when it is not.
Related issues
Possibly related, but not the same failure mode:
- Hot-reload hook configuration during a live session #17636 requests hot-reloading hook configuration during a live session.
- codex_hooks do not fire in interactive sessions when configured via repo-local .codex/config.toml #17532 reports repo-local hooks not firing in interactive sessions.
- Codex exec does not fire Stop / SessionStop / PostToolUse hooks (only UserPromptSubmit fires) #18607 mentions missing Stop / SessionStop hooks in
codex exec.
This report is specifically about hooks becoming non-functional in an existing CLI/TUI session after a rate-limit stop or after editing hooks.json during the live session.
Additional notes
A robust fix could be either:
- keep the previous validated hook registry active until restart,
- hot-reload hooks transactionally only after successful validation,
- or surface a clear warning/error when hooks are disabled or skipped.
Activity
oxysoft commentedon May 8, 2026
Indexed this hook ticket in the umbrella tracker: #21753
Goal: collect the scattered Codex hook requests and bugs into one parity matrix for Full Claude Code Hook Parity (29+), while preserving this issue as the detailed thread for its specific behavior.
kc961163 commentedon Aug 27, 2026
Additional reproduction from Codex Desktop and CLI:
codex-cli 0.150.0-alpha.8, signed in with ChatGPT.hooks.jsonchanged, the task continued recording successfultask_started/task_completeevents, but no further hook events were recorded and the hook's local side-effect state stopped changing. New prompts did not invokeUserPromptSubmitorStop.codex exectask also invokedSessionStartandUserPromptSubmit, which isolates the failure to hook dispatch in the existing Desktop task rather than the hook command itself.Stopdid not run, leaving the observed turn without a terminal lifecycle event.This appears to expose two producer-side gaps:
UserPromptSubmitwithout a correspondingStopor error lifecycle hook.Authentication does not appear to explain the first gap: Codex authentication selects ChatGPT subscription access or API-key usage-based access, while hooks are executed locally by the Codex client. I reproduced ChatGPT authentication only, not API-key mode. A successful fresh API-key task should use the same local hook dispatcher, while an API quota/provider failure may have the same missing-terminal-event risk described in #22774.
Expected behavior: retain the previously validated hook registry until restart or reload it atomically; surface when hooks become inactive; and dispatch
Stopor a dedicated error event for quota/provider termination.kc961163 commentedon Oct 12, 2026
Still reproduces on a newer build, with a cleaner signal: the turn is recorded as complete, but
Stopnever runs.codex-cli 0.162.0-alpha.17.2(bundled with the desktop app), ChatGPT sign-in, user-levelhooks.jsonwithPreToolUse,PostToolUse,UserPromptSubmitandStopcommand hooks (all trusted).codex execwith a prompt that makes 25 separate shell tool calls. After 22 of them the CLI printedERROR: Selected model is at capacity. Please try a different model.and exited.task_started, 22 tool calls, thentask_complete.PostToolUseran for all 22 tool calls.Stopdid not run: our hook deletes its per-turn state file inStop, and that file is still on disk with no pending tools.-mset to a model that had capacity completed all 25 calls, andStopran normally.So when a provider error ends a turn, the turn still gets
task_complete, but neitherStopnor any error hook runs, and a hook that finalizes per-turn work onStopcan't tell the turn ended. Same gap as point 2 in my earlier comment, and what #22774 asks for.