---
id: 11807
title: Add Codex hooks feature-flag migration guard
state: CLOSED
labels:
  - bug
  - developer-experience
  - ai
  - build
assignees:
  - neo-gpt
createdAt: '2026-05-22T23:57:23Z'
updatedAt: '2026-05-23T01:57:34Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11807'
author: neo-gpt
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-23T01:57:34Z'
---
# 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:
  ```toml
  [features]
  hooks = true
  ```
- `.codex/config.toml` is intentionally ignored/local and can still contain stale copied config:
  ```toml
  [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

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| Codex local feature flag config | OpenAI Codex docs feature flags + repo `.codex/config.template.toml` | Users should use `[features].hooks = true`; stale `[features].codex_hooks = true` should be migrated or clearly diagnosed | If no diagnostic is added, docs must make the local ignored-config migration explicit | `.codex/CODEX.md` or adjacent Codex config docs | Grep verifies tracked template uses `hooks`; local stale config warning reproduced by operator |

## 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

| Trap | Why rejected |
|---|---|
| Editing only `.codex/config.template.toml` | Already correct; would create a no-op PR. |
| Committing `.codex/config.toml` | Violates the local-custom-config split. |
| Treating hook loading as broken | The hook mechanism can be fine while the local feature flag key is stale. |

## 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")`

## Timeline

- 2026-05-22T23:57:25Z @neo-gpt added the `bug` label
- 2026-05-22T23:57:25Z @neo-gpt added the `developer-experience` label
- 2026-05-22T23:57:25Z @neo-gpt added the `ai` label
- 2026-05-22T23:57:25Z @neo-gpt added the `build` label
- 2026-05-23T01:12:06Z @neo-gpt cross-referenced by #11812
- 2026-05-23T01:22:53Z @neo-gpt assigned to @neo-gpt
- 2026-05-23T01:26:56Z @neo-gpt cross-referenced by PR #11814
- 2026-05-23T01:57:34Z @tobiu referenced in commit `eb84687` - "fix(codex): document hooks flag migration (#11807) (#11814)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-23T01:57:34Z @tobiu closed this issue
- 2026-05-23T02:16:42Z @neo-opus-ada cross-referenced by PR #11815

