Codex has lifecycle hooks now — verify, then stop guessing at Codex turn state

[openwong2kim]

The gap

For a Claude Code pane, wmux knows what happened because the hook bridge tells it: turn ended, permission prompt raised, subagent activity. For a Codex pane it does not. The only thing wmux installs into Codex is the notify bridge (registerCodexNotify, src/shared/configIO.ts), which is effectively a single completion ping. Everything else — turn boundaries, approval prompts, subagent starts — falls back to reading the screen: regex detection plus the byte-rate promotion from #935.

That fallback is why completion detection on Codex panes is a heuristic with tuned thresholds instead of a fact.

What changed upstream

codex-cli 0.149.1 ships lifecycle hooks that look structurally like Claude Code's. Observed event names in the binary:

PreToolUse · PostToolUse · Notification · UserPromptSubmit · SessionStart · SessionEnd · PreCompact · PostCompact · SubagentStart · SubagentStop · Stop

with matching UI copy for each ("Before a tool executes", "When permission is requested", "After a tool executes", "Before/After context compaction", "When a new session starts", "Right before a session ends", "When the user submits a prompt", "When a subagent is created", "Right before a subagent ends its turn", "Right before Codex ends its turn"). The payload field names match too — hook_event_name, stop_hook_active, permission_mode, tool_name, tool_input, agent_transcript_path, last_assistant_message.

There is also a trust model around them: [hooks] in config.toml, plugin_hooks, allow_managed_hooks, and a review UI ("New hook - review required" / "Modified since last trusted" / "Managed hooks are always on"). Sources are enumerated as Admin config, User config, Project config, Session flags, Cloud-managed config.

If those behave the way the names suggest, the Codex side of completion detection stops being a guess.

This is not verified yet

The above is binary string inspection, not a working hook. This repo has been wrong before by reading a competitor's surface and declaring a gap, so nothing here gets promoted to a track until someone actually installs a hook against a live Codex session and watches it fire. Blocking questions:

• What is the on-disk shape of a [hooks] entry in ~/.codex/config.toml, and does it accept a command the way Claude's settings.json does?
• What exactly arrives on stdin per event, and is Stop a real turn boundary or a session-level signal?
• What does the trust flow demand of a programmatic installer? "New hook - review required" implies wmux writing a hook is not enough on its own — the operator may have to approve it, which changes the install UX and possibly rules out silent reconciliation.
• Does any of it work on Windows, which is the platform wmux ships on?

Suggested order

1. Spike: hand-write one Stop hook against a live Codex pane, confirm it fires and capture the payload. Nothing else until this lands.
2. If it holds: extend lifecycleIntegrations to install a Codex hook bridge next to the notify bridge, keeping notify for older Codex versions.
3. Fold Codex panes onto the same signal path Claude panes use, and let the screen heuristic become the fallback rather than the primary.

Note the version floor: hooks are in 0.149.1 and were not always there, so any install path needs a capability check rather than assuming the local Codex has them.

Related

• The notify bridge is the current, weaker integration point.
• [Bug]: Roster status and "N need you" disagree with what panes are doing (working panes shown as waiting/complete, ended panes as running) #935 is the byte-rate promotion this would let Codex panes stop relying on.

[openwong2kim]

[wmux-hermes] Triage Summary

Spike to verify codex-cli 0.149.1 lifecycle hooks (Stop, SessionStart, SubagentStart) — if they hold, a Codex hook bridge replaces the screen-heuristic turn-state detection Codex panes currently rely on. Scope is lifecycleIntegrations plus a version capability check, spike-first: no code until a live payload is captured. P2 — big correctness payoff, still unverified upstream.

[openwong2kim]

Schema extracted — blocking question 1 is answered, the spike is smaller now

Still static inspection of the codex-cli 0.149.1 binary, not a hook that fired. But it answers most of what the spike was going to have to discover by trial, so recording it here.

The config shape. The binary carries internally tagged enum HookHandlerConfig next to matcher and hooks, plus a HookStateToml with enabled and trusted. Handler fields observed: handler_type, command, commandWindows, timeout / timeout_ms, execution_mode with values sync and async, and matcher / matchers. That is the Claude Code settings.json hook shape transposed to TOML: an event name, a matcher, and a list of handlers.

The contract is the same one wmux's bridge already speaks. Verbatim error strings:

hook exited without a status code
hook process terminated without an exit code
hook returned invalid pre-tool-use JSON output
PreToolUse hook exited with code 2 but did not write a blocking reason to stderr

Exit code 2 blocks, the reason goes on stderr, and PreToolUse can return JSON. If that holds at runtime, wmux-bridge.mjs needs a Codex entry point, not a new protocol.

Windows is contemplated by the format itself — commandWindows is a distinct field beside command, which is how a cross-platform hook gets a different invocation per OS. That was blocking question 4 and it now looks like a smaller risk than assumed.

Trust state is data, not just UI. HookStateToml { enabled, trusted } plus allow_managed_hooks_only means the review gate has an on-disk representation. That does not tell us whether a programmatic installer can pre-trust its own hook — almost certainly it should not be able to — so the install UX question stands: wmux may have to write the hook and then tell the operator to approve it in Codex, which is a different shape from the Claude install where writing the file is the whole job.

Also observed: run_turn_stop_hooks and run_session_end_hooks as separate call sites, which is mild evidence that Stop really is a turn boundary distinct from session end — the thing that would let Codex panes stop guessing.

What the spike still has to do

The schema no longer needs discovering; only behavior does.

1. Write a [hooks] entry with a Stop handler against a live Codex session, confirm it fires, and capture the stdin payload. Blocked here on auth — this machine's Codex account returns 402 deactivated_workspace, so no turn can start. Whoever picks this up needs a working Codex login.
2. Confirm Stop marks a turn boundary and not a session-level signal.
3. Determine what the trust flow demands of an installer, and whether an untrusted hook silently does not run.
4. Confirm the commandWindows path on Windows.

Version floor stays 0.149.1 with a capability check; none of this is in older Codex.

[openwong2kim]

Verified — and three of the assumptions were wrong. Implemented in PR #1144.

The 402 turned out not to be the blocker. A hook needs a completed turn, not a live account, so I ran codex-cli 0.151.0 against a stub Responses endpoint on localhost with an isolated CODEX_HOME. The stub only supplies the model's side of the wire; the hook machinery is entirely local. All four questions are answered.

1. Stop is a turn boundary. Across two turns of one session it fired once per turn carrying that turn's turn_id; SessionEnd fired separately, once, with none. A run whose model call failed produced SessionStart → UserPromptSubmit → SessionEnd and no Stop at all.

2. The config shape is TOML, not hooks.json. [[hooks.<Event>]] in config.toml. A .codex/hooks/hooks.json is inert — I tried it first on the strength of the static read and got nothing. Handler fields are as extracted, and the payload envelope is Claude Code's verbatim, down to tool names being normalized into Claude's vocabulary (a shell call arrives as tool_name: "Bash").

3. The trust gate is silent. An untrusted hook does not run, and codex exec prints no warning, no "hooks need review" line, and exits 0 — the config parses clean and nothing happens. My first three runs failed exactly this way with zero diagnostics. This changes the install story: writing the file is explicitly not the job.

4. Version floor is 0.141.0, not 0.149.1. Bisected: 0.135.0 no, 0.140.0 no, 0.141.0 yes. The uncomfortable part is that no capability probe works — 0.135.0 reports hooks stable true from codex features list, accepts --dangerously-bypass-hook-trust, and parses [[hooks.*]] without complaint, while firing nothing. Only the version distinguishes them.

Also confirmed: WMUX_PTY_ID reaches the hook, and unlike Kiro, resume binding is possible (source: "resume" with a stable session_id).

Still blocked: PermissionRequest — the event that would retire the three approval regexes in AgentDetector.ts. codex exec forces approval: never, so an approval pause needs an interactive TUI (approval_policy = "untrusted" is rejected outright in 0.151.0). Left unmapped; guessing at its field names would trade a brittle signal for a wrong one.

A pre-existing bug the wiring exposed: hooks.rpc.ts dropped an unclaimed agent.user_prompt_submit before the alarm feed, while the daemon path feeds it first. Since this bridge deliberately doesn't map PreToolUse, that is the only 'working' cue for a Codex pane — so the drop made CompletionAlarm's turn gate swallow the same turn's agent.stop (no notification, no lifecycle event), and it also blocked relaying to the daemon. Fixed in the PR with two non-vacuous regression tests.

Installation is deliberately not wired into the installer: Codex requires an operator to trust the hook and says nothing when they haven't, so an installer that wrote the block and reported success would be reporting a lie. Automating approve-then-verify is what's left, and it needs a machine with a working Codex login.

[openwong2kim]

The bridge landed in #1144. Keeping this open for the two things that could not be finished without a working Codex login:

1. PermissionRequest mapping — the event that would retire the three transcribed approval regexes in AgentDetector.ts:296-300. It needs an interactive TUI session, since codex exec forces approval: never.
2. Installation — Codex requires an operator to trust the hook and says nothing when they haven't, so the install flow has to be approve-then-verify rather than write-and-report-success.

When #1111 lands, the new bridge also needs adding to the BRIDGES list in hookBridge.lockstep.test.ts (it carries a local duplicate of that guard in the meantime).

[openwong2kim]

Scope check while triaging: the core spike landed in PR #1144 (stub Responses endpoint working around the 402 account, Stop confirmed as the turn boundary, TOML [[hooks.<Event>]] shape, 0.141.0 version floor, silent trust gate documented, plus the agent.user_prompt_submit drop fix in hooks.rpc.ts). Remaining here:

1. PermissionRequest mapping to replace the three approval-prompt regexes in AgentDetector.ts — needs an interactive-TUI approval pause; first attempt should be a stub endpoint returning a shell tool call (would unblock without an account), live account only if that fails.
2. Install flow honesty: the trust gate is silent, so "installed" must render as installed-but-untrusted in lifecycleIntegrations until a hook actually fires post-approval.
3. When Close the grandfather lane (Stage 3): no-clientName callers are allowed, and two enforcement points must move together #1111 lands, add the codex bridge to hookBridge.lockstep.test.ts's BRIDGES list.