fix: clarify Codex hook trust and require supervision checks

[mremond]

Current validation: all checks passed for restored commit f0611e21.

Earlier pipeline result: PASSED WITH OVERRIDE, not passing checks. The initial no-mistakes run overrode Behavior portable serial 4; that lane was cancelled rather than passing. Firstmate instructed the driver to approve ci-1, and no-mistakes accepted it as non-blocking under that explicit override.

The lane was cancelled at the twenty-minute job cap, not failed by a test assertion. Firstmate's investigation reproduced this cancellation on trunk without this documentation change. The duration-table repair is a separate delivery in flight. Our upstream repository access is read-only, so we cannot rerun that job ourselves.

The restored follow-up f0611e21 is now published. Its new no-mistakes run returned checks-passed: review, documentation, lint, and all CI checks passed. No CI override was needed for this follow-up run.

Intent

Our adapter notes for the new worker runtime describe a DIRECTORY trust gate, and NOT the dialog met on 2026-09-08 at the very first launch after workers were switched over.

THE DIALOG, as observed: it announces that four hooks are new or changed and offers to let them run outside the sandbox. Three choices, with the cursor sitting on "review" rather than on either of the two trust options.

WHY WE CANNOT ANSWER IT: our key plane carries a confirm, an escape and an interrupt, with no way to MOVE a selection. So confirming opens a review flow we cannot navigate, and the declining option would switch off precisely the hooks that make a worker visible to supervision. Escape - which the dialog itself offers as going back, and which grants nothing - cleared it.

THE MOST SERIOUS CONSEQUENCE, to be written first in the notes: a worker whose hooks are not granted works, produces and finishes without anything ever waking anyone. It is INVISIBLE to supervision, silently. That is the worst failure shape of the day, aimed straight at the mechanism everything else depends on.

UNCERTAINTY TO PRESERVE AS IT STANDS: nothing proves the hooks are granted rather than merely dismissed. Do not resolve it by reasoning.

TO DELIVER:

1. Document this dialog in that adapter's notes, with escape as the only safe key, and the reason.
2. Document the mandatory verification: after every launch on this runtime, confirm the turn-end signal genuinely exists before treating the worker as supervised. Never infer it from a successful launch.
3. Establish whether operator acceptance is a once-per-machine gate, like the same runtime's directory gate. If it is, say so in the notes.

DO NOT attempt to automate an answer to this dialog. A key plane that cannot move a selection must not guess.

What Changed

• Lead Codex adapter guidance with the silent supervision failure warning; distinguish directory trust from hook review, require Escape for the latter, and forbid automated answers.
• Require fresh turn-end evidence and a corresponding supervisor wake after every launch before treating a worker as supervised.
• Document content-hash-bound hook approval, the observed shared-file changes and dismissals, and unresolved approval status; route common trust guidance to these instructions.

Risk Assessment

✅ Low: The documentation-only change preserves the required safety guidance and uncertainty, mandates fresh supervision evidence, and introduces no automated trust handling.

Testing

Inspected the exact target and both documentation changes; no runtime tests or baseline suite ran. Historical observations were not counted as live evidence. No rendered UI changed, no visual artifacts were captured, and no files were modified.

• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
An operator reads the notes and encounters silent loss of supervision as the first warning.	⏸️ untested	no	Documentation-only change with no live-validatable surface; reading the warning cannot prove operator behavior.
An operator encounters hook review and uses Escape without confirming the default review selection or inferring approval.	⏸️ untested	no	No executable dialog handling changed. Live corroboration would require an isolated operator-driven terminal session and dialog capture; no dialog answer was automated.
An operator relaunches a worker with an old marker and requires a fresh turn-end signal plus its corresponding received wake.	⏸️ untested	no	The change documents verification without adding runtime enforcement. A live demonstration would require isolated worker launches and correlated supervisor records; the documented historical observati…
An operator changes previously accepted hook definitions and requires renewed review instead of assuming permanent machine-wide approval.	⏸️ untested	no	Documentation-only persistence guidance. Live corroboration requires an operator-controlled acceptance and changed-definition experiment, outside this documentation test surface.

• Outcome: ⚠️ 1 warning across 1 run (2m56s)

Evidence restored after pipeline removal

The automatic documentation step in 1b2a253f removed required incident evidence. Follow-up f0611e21 put it back: both launch/signal timestamp pairs (14:54:17 to 14:55:57, 100 seconds; 15:01:55 to 15:02:58, 63 seconds), the first-worker supervision wake and verification example, recurrence on the second launch after Escape, Orca rewriting shared ~/.codex/hooks.json as the cause, and the trust-entry inventory with no project hooks file entries. These observations identify another tool's shared-file rewrite as the trigger, preventing a misleading investigation of Firstmate's spawn.

The second documentation pass preserved every restored observation and made no additions or removals. Useful earlier pipeline additions remain: the common-reference pointer and the distinction between crewmate/scout notifications and secondmate supervision. The observations are incident corroboration, not newly executed runtime tests; trusted versus merely dismissed remains unresolved.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 1 warning

• ⚠️ this change has no live-validatable surface; proceed without live validation? (0 of 4 scenarios were driven live against the product); An operator reads the notes and encounters silent loss of supervision as the first warning.: Documentation-only change with no live-validatable surface; reading the warning cannot prove operator behavior.; An operator encounters hook review and uses Escape without confirming the default review selection or inferring approval.: No executable dialog handling changed. Live corroboration would require an isolated operator-driven terminal session and dialog capture; no dialog answer was automated.; An operator relaunches a worker with an old marker and requires a fresh turn-end signal plus its corresponding received wake.: The change documents verification without adding runtime enforcement. A live demonstration would require isolated worker launches and correlated supervisor records; the documented historical observations were not replayed.; An operator changes previously accepted hook definitions and requires renewed review instead of assuming permanent machine-wide approval.: Documentation-only persistence guidance. Live corroboration requires an operator-controlled acceptance and changed-definition experiment, outside this documentation test surface.
• Live validation: ⚠️ no-surface - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
An operator reads the notes and encounters silent loss of supervision as the first warning.	⏸️ untested	no	Documentation-only change with no live-validatable surface; reading the warning cannot prove operator behavior.
An operator encounters hook review and uses Escape without confirming the default review selection or inferring approval.	⏸️ untested	no	No executable dialog handling changed. Live corroboration would require an isolated operator-driven terminal session and dialog capture; no dialog answer was automated.
An operator relaunches a worker with an old marker and requires a fresh turn-end signal plus its corresponding received wake.	⏸️ untested	no	The change documents verification without adding runtime enforcement. A live demonstration would require isolated worker launches and correlated supervisor records; the documented historical observati…
An operator changes previously accepted hook definitions and requires renewed review instead of assuming permanent machine-wide approval.	⏸️ untested	no	Documentation-only persistence guidance. Live corroboration requires an operator-controlled acceptance and changed-definition experiment, outside this documentation test surface.

• git diff --stat b84e0e362face25f3dd8945297a3df1320d7668c f0611e21c6f2a6908aa3e372f0e0108c134ae1a3 and full scoped diff inspection
• git rev-parse HEAD HEAD^{tree} confirmed the requested target
• Manually inspected both changed Markdown references against the required intent and assessed existing adapter tests for relevant behavioral coverage
• git status --short confirmed no working-tree changes

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

_{Reviews (2): Last reviewed commit: "docs(codex): restore observed hook trust..." | Re-trigger Greptile}

[mremond]

Overtaken by trunk: the Codex hook trust dialog this documented is now pre-approved at launch (#3944), and harness trust handling changed again in #4262. Closing rather than refreshing a documentation-only change whose subject has moved.