Capability-gate subscription-backed Codex hook launchers

A launcher that depends on a fast-moving Codex hook handler must gate on runtime capability, not merely on the generic hooks feature flag; parser support and execution support can ship separately. When a launcher preserves the normal Codex home to reuse ChatGPT subscription authentication, it also inherits unrelated user MCP configuration, so startup warnings must be treated separately from the assessment MCP's own readiness. This applies to local subscription-backed launchers; it does not imply that every inherited MCP must be disabled, nor that client-observed hooks provide provider-stream fidelity.

Method: 1. Probe codex --version and the exact hook handler contract before generating project-local hooks. 2. Fail early with a one-command upgrade path when the required handler is absent; do not let a parse warning silently downgrade observability. 3. Verify the required MCP by name. Do not infer its failure from warnings emitted by unrelated inherited servers. 4. Keep evidence coverage labeled client-observed/partial; missing hook events are unknown, not zero. 5. For low-friction interactive subscription use, prefer the normal auth home, but explicitly design how unrelated config is isolated or tolerated. For higher-fidelity traces, use an app-server/SDK bridge that owns the event stream.

Evidence/example — 2026-09-09: - A Codex 0.144.4 interactive subscription session launched successfully but rejected a project hook handler with unknown variant mcp_tool; the parser listed only command, prompt, and agent. - OpenAI's current Hooks documentation supports command and mcp_tool, while OpenAI PR #37363 (2026-08-07) added recognition and PR #39296 (2026-08-18) added execution through the shared MCP runtime. This demonstrates the recognition/execution rollout boundary. - Preserving the normal Codex home caused unrelated configured MCPs with missing environment tokens or OAuth grants to warn, while the required assessment MCP was absent from the failed-server list. Sources: https://learn.chatgpt.com/docs/hooks ; https://github.com/openai/codex/pull/37363 ; https://github.com/openai/codex/pull/39296

Uncertainty: exact minimum usable release should be verified against the published binary chosen for deployment; updating to the current stable release is safer than depending on a guessed cutoff.