[Workstream D] PR 3 of 8: Codex parity — register PreToolUse and PreCompact/PostCompact after the hook failure is attributed

[zaxbysauce]

Order: third in Phase 3, and hard-gated on A-3. Registering more Codex hooks while an existing Codex hook fails proves nothing. Part of #100.

Why now (verified 2026-09-02 from Codex source and the local CLI)

Upstream supports what we do not register:

• The canonical event enum (codex-rs/app-server-protocol/schema/typescript/v2/HookEventName.ts) is: preToolUse, permissionRequest, postToolUse, preCompact, postCompact, sessionStart, sessionEnd, userPromptSubmit, subagentStart, subagentStop, stop, interrupt. There is no PostToolUseFailure, so our second PostToolUse entry is the correct shape and should stay.
• PreToolUse additionalContext was added by openai/codex#20692 (merged 2026-05-05); issue #19385, which our docs once cited as the blocker, was closed 2026-08-04. codex-rs/hooks/src/events/pre_tool_use.rs sets an additional_context_limit.
• PreToolUse input carries tool_name, tool_input, tool_use_id, cwd, session_id, turn_id; SubagentStart carries agent_id/agent_type and no task text.
• Our side already implements both verbs: hooks/zmem-launch.js:63-74 lists pretool-recall and precompact and :103-115 maps them to PreToolUse/PreCompact. Only hooks/hooks.codex.json omits them, and tests/test_pretool_inject.py:392-411 pins that omission to this issue.

Claim freshness: the facts above are dated 2026-09-02 against codex-cli 0.152.1. Re-verify before wiring, per the convention set by #103/#104.

Scope

1. Blocking prerequisite: #A-3 must have attributed the failing Codex SessionStart hook and the canary must show a zmem line in the log. Do not proceed on a host where the existing hooks do not demonstrably run.
2. Live-dump the tool names Codex actually emits for shell and patch operations (do not assume Bash), and write the matcher from the dump. Record the dump in a comment here.
3. Register PreToolUse with the verified matcher and an explicit additional-context limit below the host's spill threshold.
4. Register PreCompact and PostCompact, wired to the same handlers D-2 ([Workstream D] PR 2 of 8: Query-aware re-injection after compaction (and settle whether the PreCompact fence survives) #118) defines for Claude.
5. Extend tests/test_codex_adapter.js with real envelope tests, and flip the pin at tests/test_pretool_inject.py:392-411 — the failure message on that assertion should name this issue so the next reader knows the flip is intentional.

Acceptance criteria

• The A-3 ([Workstream A] PR 3 of 5: Attribute the failing Codex SessionStart hook, then add a per-host injection canary #108) canary passes on Codex for session start, user prompt, pre-tool and compaction.
• The pinned absence test is inverted, not deleted.
• SKILL's timing matrix updates for Codex, with the probe date.

Depends on / blocks

• Depends on: A-3 ([Workstream A] PR 3 of 5: Attribute the failing Codex SessionStart hook, then add a per-host injection canary #108), D-1 ([Workstream D] PR 1 of 8: Session delivery ledger — cross-moment dedup, and retire the pending sidecar #117), D-2 ([Workstream D] PR 2 of 8: Query-aware re-injection after compaction (and settle whether the PreCompact fence survives) #118).

Addendum — Muse Spark 1.3 report, validated 2026-09-03

Three additions, all verified against Codex source on 2026-09-03:

• Units trap (verified). Codex's hook-output limit is 2,500 tokens by default (codex-rs/hooks/src/output_spill.rs:12, DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT = 2_500); above it the text is spilled to a file and the model receives a head/tail preview (:59-90). zmem's envelope budget is characters — hooks/zmem-launch.js:356 sets ZMEM_CTX_BUDGET to 9,000 on Codex, ≈ 2,250 tokens by the plugin's own 4-chars-per-token estimator — so a full fence sits within ~10% of the spill point, and C-5 ([Workstream C] PR 5 of 6: Make the 1500-token injection budget a measured hard ceiling #116) measured a single real prompt rendering 3,231 tokens before any cap. Add a Codex-specific token clamp with margin (or set the per-handler additionalContextLimit) and a unit test that a maximal fence never spills.
• Trust gate. Codex requires hash-based trust review of hooks before they run (~/.codex/config.toml carries per-hook trusted hashes on this box). Every new hook entry changes its hash and must be re-trusted; deployment docs must say so, or the new hooks silently do not run.
• Contract. Surfacing-only on every host: never emit permissionDecision, never deny, --no-bump, fail-open exit 0. The hazard-prevention "deny with reason" idea stays out (see D-7 [Workstream D] PR 7 of 8: Hermes parity — query-aware remote prefetch, shared gate and budget, derived namespace #122 for the same reasoning on Hermes).

Acceptance additions: the live tool_name dump must cover the shell tool and the patch/apply tool shape, and decide MCP/local-function tools in or out; a launcher end-to-end test with a Codex-shaped payload proves fence injection; the token-clamp test above.

[zaxbysauce]

Live tool_name dump — codex-cli 0.153.0, Windows 11, 2026-09-09 (scope item 2)

Captured with an isolated CODEX_HOME (scratch dir, no contact with the user's real config), user-level capture-only hooks, and codex exec --dangerously-bypass-hook-trust (the documented flag for automation that vets its own hook sources) in a throwaway workdir. The matcher in PR #152 is written from this dump, not assumed:

operation	tool_name	tool_input
shell command (echo zmem95-shell-probe)	Bash	{"command": "echo zmem95-shell-probe"}
file creation (patch mechanism)	apply_patch	{"command": "*** Begin Patch\n*** Add File: …probe.txt\n+hello-from-patch\n*** End Patch"}

Also captured on the same run: SessionStart (source: "startup", plus model/permission_mode fields), UserPromptSubmit (prompt), and PostToolUse (mirrors both tool names, carries tool_response). Codex matcher semantics (verified from codex-rs source at tag rust-v0.153.0, which matches the local CLI): a matcher containing only [A-Za-z0-9_|] is EXACT alternation, so Bash|apply_patch matches precisely these two names. MCP tools emit mcp__<server>__<tool> (source-verified) and are decided OUT (pre-tool recall derives queries from shell/patch inputs, not arbitrary MCP arguments); write_stdin also OUT. A -c model_context_window=1500 run did not trigger live compaction, so PreCompact/PostCompact shapes were verified from source instead: upstream Codex PreCompact/PostCompact carry trigger: manual|auto only and accept no additionalContext (decision control only); SessionStart carries source ∈ {startup, resume, clear, compact} and upstream queues SessionStartSource::Compact immediately after compaction.

Wiring decisions recorded (PR #152)

• PreToolUse registered with the dump-verified matcher above (re-probe with a live dump before changing it — the pin test's failure message says so).
• PreCompact registered to the same shared precompact handler Claude uses; on Codex its functional payload is the delivery-ledger clear (upstream drops additionalContext on that event), and post-compaction re-injection rides the already-registered SessionStart source=compact moment.
• PostCompact NOT registered — deferred to [Workstream D] PR 2 of 8: Query-aware re-injection after compaction (and settle whether the PreCompact fence survives) #118 (D-2), which owns the shared compaction handlers. Pinned by a new absence test naming [Workstream D] PR 2 of 8: Query-aware re-injection after compaction (and settle whether the PreCompact fence survives) #118 (tests/test_codex_adapter.js) so it cannot silently appear; SKILL.md carries the same pointer. This is the one part of this issue's scope item 4 that lands as an explicit, pinned deferral rather than wiring — it cannot be wired before [Workstream D] PR 2 of 8: Query-aware re-injection after compaction (and settle whether the PreCompact fence survives) #118 defines the handlers this issue's own text requires.

Trace note

In the PR's acceptance-run logs, the canonical post-fix results are runs-post-check_pretool_registered_e2e.log and runs-post-check_ac2b_inverted_pin.log; the .py.log siblings are pre-AMEND captures kept for traceability (four AMEND rows in the checkpoint manifest document each check-harness fix with a closed reason).

Merge gate: PR #152 awaits human review/approval — the agent does not merge.