Deliver cmux agent messages to Codex through its hooks

[teamleaderleo]

Summary

Stacked on #15279 (review that first; this PR's diff is only the last commit). It gives Codex sessions the agent messages from cmux agent message. Part of manaflow-ai/cmuxterm-hq#847.

Codex hooks can't wake an idle session, so a message waits for Codex's next hook:

• When the human submits a prompt, hooks codex inbox-drain attaches queued messages to it as additionalContext.
• When Codex is about to stop, hooks codex inbox-stop returns {"decision":"block","reason":…}, so Codex continues the turn with the message instead of going idle.
• An idle Codex sees the message at its next prompt. Nothing is ever typed into the terminal, so a draft in Codex's prompt is never touched.

How it's wired:

• The UserPromptSubmit and Stop groups that the Codex wrapper injects now hold a second handler, run directly so its stdout reaches Codex. It is still one cmux group per event, as Codex wrapper injection replaces existing per-event hook arrays #12081 requires. The lifecycle handlers stay queued.
• CodexHookInjectionEvent gets an optional companion, and configValue(command:) renders the -c value. Generation and the tests use that one renderer.
• The previous schema moves into the exact recognized shapes, so saved launches from before this change still sanitize.
• The replay sanitizer accepts the two-handler group only when both handlers are cmux's. If the second handler is someone else's, the whole block is kept.
• codex exec runs get CMUX_CODEX_HEADLESS=1 from the wrapper, and the inbox handlers then return {}. So a headless run in an agent's pane can't take that agent's messages. claude -p works the same way in Agent messages that never land in a human's draft: cmux agent message #15279.

Not covered yet: sessions whose cmux hooks come from cmux hooks codex install instead of the launch wrapper. Their persistent events aren't re-injected, so they don't get the companions. The docs say so.

Testing

• CodexHookInjectionStrippingTests and CodexHookPathSafetyTests: 30 tests pass on Swift 6.1.3 in a minimal scratch package with the sanitizer and schema sources. That run was on Linux, where the full CMUXAgentLaunch package can't build. New tests cover:
  • the companion shape;
  • stripping the pre-companion block;
  • keeping a block whose second handler is foreign.
• CLICodexQueuedHookContractTests gains a check that hooks codex inject-args emits two handlers for UserPromptSubmit and Stop, the second direct, and one handler for the other events. It is not run locally (macOS only).
• tests/test_codex_wrapper_hook_append.py now expects the companion in those two groups, and in its live codex exec run exactly one call to each inbox handler. CI does not provision Codex, so the live part is skipped there.
• python3 scripts/verify-local.py --affected origin/main: 14/14 checks passed.
• Not yet run against a live Codex in a tagged build; that will be part of the dogfood.

Changelog

Added: Codex sessions receive cmux agent message messages when the human next submits a prompt, or before Codex goes idle

Checklist

• Behavior changes have added or updated tests, or Testing says why not
• User-facing docs updated if needed
• Reviewed with a subagent before merge, and all bot and human review comments resolved

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Delivers cmux agent message messages to Codex sessions through the injected Codex hooks. Since Codex hooks can't wake an idle session, a message waits for the next hook: it's attached as context to the human's next prompt, or Codex continues its turn with it instead of going idle.

• The UserPromptSubmit and Stop hook groups carry a second direct handler for the inbox; the lifecycle handlers stay queued. The inbox handlers fail open, answering {} when the app is unreachable, so a dead app doesn't surface as a failed hook on every prompt.
• Headless codex exec runs skip the inbox via a new CMUX_CODEX_HEADLESS env var, matching how claude -p behaves. The check accounts for every value-taking option, so codex --add-dir ../lib exec is treated as headless too.
• The previous hook schema is preserved as a recognized shape, and the sanitizer accepts the two-handler groups only when both handlers are cmux's.
• Sessions whose hooks come from cmux hooks codex install rather than the launch wrapper don't receive messages yet.

^{Written for commit 1e79f3c. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ee83967a-9dd0-43b7-b695-72641d0bb935

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Dogfood build of 201d08f3c1a1cf8fc25986fe6540ce608a193c7e

cmux DEV pr-15313-201d08f3.app

The link opens this exact commit in the cmux dev menu bar app. The build starts on each push and the page waits until it is ready; a newer push replaces it. It signs in against production, so Cloud or backend changes still need a tagged build with a development backend.

[teamleaderleo]

Review: a review subagent read the diff and tested it against Codex 0.154 with a local fake model provider. Confirmed: one hook group with two command handlers is accepted, {} merges with additionalContext, and a Stop decision:block continues the turn with the message. The old recognized schema still strips pre-PR blocks, and 41 sanitizer tests pass, including probes that must not be stripped.

Fixed:

• The headless check missed Codex options that take a value (--add-dir, -i/--image, --local-provider, --remote-auth-token-env), so codex --add-dir ../lib exec ... could take messages meant for the interactive Codex in the same pane. Regression test first (bf4afaa), then the fix. The same list decides hook injection, which is now more accurate too.
• The message handlers did not fail open when the CLI itself failed (socket down, bad binary), so Codex showed "hook failed" on every prompt and stop while the app was unreachable. Regression test first (2cca0cf), then the fix.
• Corrected the sanitizer comment that claimed the separator can only occur once.

Left:

• Codex reads hook timeout in seconds, but cmux's injected -c config has always written milliseconds, so every injected timeout is 1000 times too long. This predates the PR. The persistent installer already converts. I'll fix it in a separate PR against main, since it changes every event's injected value and needs a new recognized schema.
• The inline-command check in the sanitizer is a substring match, so a crafted user handler that mentions cmux's markers is dropped from replayed argv. This looseness already existed for single-handler values, and the only effect is that the user's handler isn't replayed.
• Not verified: whether Codex fires Stop or UserPromptSubmit for subagent threads, which would hand them a message.
• Not run here: the app and CLI targets and cmuxCLITests, which don't build on Linux. CI covers them.

[teamleaderleo]

Cross-model review (Codex gpt-5.6-sol)

• CLI/CMUXCLI+CodexFireAndForgetHooks.swift:201-204 — wrapper generation suppresses an entire event when it finds any cmux-owned persistent hook for that event. Existing persistent installs add only the lifecycle handler for UserPromptSubmit/Stop, while this PR adds inbox-drain/inbox-stop only as wrapper companions; users who previously ran the persistent installer therefore lose the companion handler and queued agent messages are not delivered. Suppress per handler (inject a missing companion beside an existing lifecycle handler), or make persistent installation add both and suppress only when the complete pair is present; add a fixture for the current single-handler install.

[github-actions]

CI failure attribution

CI failed on e0c8821c52 (run 36410774535 attempt 1): 1 machine.

Job	Verdict	Why
macos / app-host unit tests (changed suites)	machine	a binary loaded a framework from another build (stale products on the runner) (runner cmux10s-mac-mini-glaeda-4)

Matched log lines

macos / app-host unit tests (changed suites): ↳ status=6 reason=exit timedOut=false stdout=^D��dyld[24426]: Symbol not found: _$s15CMUXAgentLaunch05AgentB7CommandV10rejectedOn8launcher16externalLauncher14executablePath16workingDirectory11environment16verificationHome10capturedAt6sourceAcA0cB22CaptureRejectionReasonV_SSSgA3OSDyS2SGSgAOSdSgAOtcfC

Every failure is a machine failure: re-ran the failed jobs as attempt 2 (the checks show its result).

Written by scripts/ci/classify_failures.py (ci-failure-attribution.yml); signatures are its SIGNATURES table. A machine verdict is the runner's fault, not this PR's.