Add Codex hooks feature-flag migration guard

Context

Codex now warns that [features].codex_hooks is deprecated and that users should use [features].hooks or --enable hooks instead. This surfaced in the Codex Desktop harness during the v13 night-shift lane.

Official current Codex docs confirm the supported feature flag is hooks under [features], and that features can also be enabled via codex --enable <feature>: https://developers.openai.com/codex/config-basic#feature-flags

Repo reality check:

• .codex/config.template.toml already uses the current tracked shape:

    [features]
  hooks = true

• .codex/config.toml is intentionally ignored/local and can still contain stale copied config:

    [features]
  codex_hooks = true

So this is not a tracked-template fix. The friction is that existing local Codex users can keep seeing a deprecation warning even though the committed template is already correct.

The Problem

The repo has a template/custom-config split for Codex Desktop. That is correct, but it also means a Codex feature-flag rename in a user's ignored local config is invisible to normal review and CI. Future Codex sessions can keep paying warning/noise cost and may misdiagnose hook loading when the actual problem is stale local config.

This is small friction, but it is exactly the kind of harness drift that turns into repeated debugging if not captured: the hook system is how Codex receives .codex/CODEX.md despite root AGENTS.md winning project-doc discovery.

Architectural Reality

• .codex/hooks.json is tracked and remains the project-local hook definition.
• .codex/config.template.toml is tracked and already current.
• .codex/config.toml is ignored by design, so the repository cannot directly update each user's local copy.
• .codex/CODEX.md explains the trusted UserPromptSubmit hook path, but does not currently document this feature-flag migration hazard.

The Fix

Add a lightweight migration guard for stale local Codex configs. Acceptable implementation shapes:

1. Documentation-only: add a short Codex troubleshooting note that stale local configs must use [features].hooks, not [features].codex_hooks, and point users to re-copy from .codex/config.template.toml.
2. Diagnostic: add a tiny repo-local check, if an existing Codex hook/setup surface is the right owner, that detects local .codex/config.toml containing codex_hooks and prints a clear migration hint.
3. If Codex itself already emits a sufficient warning in all relevant surfaces, close this as documentation-only after verifying the warning is visible in Codex Desktop startup logs and not only CLI output.

Do not change .codex/config.template.toml just for this; it is already correct.

Contract Ledger Matrix

Decision Record Impact

none. This is Codex harness maintenance, not an Agent OS architectural decision.

Acceptance Criteria

• AC1 — Confirm current tracked .codex/config.template.toml already uses [features].hooks = true and does not reintroduce codex_hooks.
• AC2 — Add a Codex-facing migration note or diagnostic for ignored local .codex/config.toml files that still contain [features].codex_hooks.
• AC3 — The migration note/diagnostic distinguishes tracked template state from local ignored config state.
• AC4 — Verification includes the exact warning shape: [features].codex_hooks is deprecated. Use [features].hooks instead.
• AC5 — No unrelated Codex MCP/server config changes are bundled into this ticket.

Out of Scope

• Changing Codex's upstream deprecation behavior.
• Committing .codex/config.toml; it remains local/ignored.
• Redesigning the Codex hook system.
• The separate exploration ticket for Codex external-model / 1M-context routing.

Avoided Traps

Related

• Prior Codex Desktop harness support work: #10485.
• Current official docs: https://developers.openai.com/codex/config-basic#feature-flags

Origin Session ID: d60db68f-8ff0-48a6-b168-237ca9dca2a0

Handoff Retrieval Hint: query_raw_memories("codex_hooks deprecated hooks feature flag .codex config.template.toml Codex Desktop")