Update Codex hooks feature flag

Context

A newer Codex version now emits this deprecation warning when reading the repo-local Codex config:

[features].codex_hooks is deprecated. Use [features].hooks instead.

Enable it with --enable hooks or [features].hooks in config.toml. See https://developers.openai.com/codex/config-basic#feature-flags for details.

This is a friction-to-gold maintenance item: the warning is small, but it hits every Codex session that has copied the repo template into the ignored local config and makes the harness bootstrap surface look stale.

The Problem

The committed Codex template still advertises the old feature flag:

[features]
codex_hooks = true

Local evidence:

• .codex/config.template.toml:86-87 still uses codex_hooks = true.
• The ignored operator-local .codex/config.toml currently mirrors the same old key.
• The current OpenAI Codex Config Basics docs list hooks as the supported feature flag and document codex --enable hooks / [features].hooks as the enable path.

Duplicate sweep:

• Knowledge Base ticket sweep for Codex codex_hooks deprecated features hooks config template ticket found older Codex template setup context (#10485 / #10552) but no matching deprecation ticket.
• Repo content sweep found PR #10728, which introduced codex_hooks when that was current, but no active issue to migrate the flag.
• Live GitHub issue search for codex_hooks, features.hooks, and Codex hooks found no duplicate issue.

The Architectural Reality

Codex-specific runtime configuration is intentionally harness-scoped:

• .codex/config.template.toml is the tracked onboarding template.
• .codex/config.toml is ignored and customizable per checkout.
• .codex/hooks.json is the hook definition that injects .codex/CODEX.md as trusted project-local Codex context.
• .codex/CODEX.md documents the hook injection model but does not own the feature-flag key itself.

The source-of-authority is external but official: OpenAI Codex Config Basics documents the [features] table and lists hooks as the lifecycle-hook feature flag. The repo should track that public config surface before the deprecated alias disappears.

The Fix

Update the committed Codex template and any tracked Codex setup note that names the deprecated key:

1. Replace [features].codex_hooks = true with [features].hooks = true in .codex/config.template.toml.
2. If any tracked Codex-facing prose names codex_hooks, update it to hooks and preserve the existing explanation that .codex/config.toml is ignored/local.
3. Do not edit or commit the ignored .codex/config.toml; local operators can copy/merge the template or update their private config manually.

Contract Ledger Matrix

Acceptance Criteria

• .codex/config.template.toml uses hooks = true under [features].
• No tracked Codex setup surface still instructs users to set codex_hooks.
• The ignored .codex/config.toml remains untracked and is not committed.
• The PR body includes the observed deprecation warning and the official Codex docs URL.
• Verification includes rg -n "codex_hooks" .codex AGENTS.md learn/agentos or a narrower equivalent proving tracked references are migrated.

Out of Scope

• Changing .codex/hooks.json behavior.
• Changing the hook script implementation.
• Editing operator-local ignored .codex/config.toml in a tracked PR.
• Reworking Codex Desktop onboarding beyond the feature-flag rename.

Avoided Traps

• Do not remove hooks because the feature default is currently documented as true. The repo template deliberately makes hook dependence explicit for fresh checkouts and self-documents the harness contract.
• Do not commit ignored local config. The template/custom split is the point of the Codex setup.
• Do not treat this as a Neo framework hook issue. This is Codex harness configuration, not Neo reactive lifecycle hooks.

Related

• #10485 - original Codex Desktop harness support ticket.
• PR #10728 - introduced the Codex hook injection path and old codex_hooks flag.
• OpenAI Codex Config Basics: https://developers.openai.com/codex/config-basic#feature-flags

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

Retrieval Hint: query_raw_memories("Codex codex_hooks deprecated features hooks config.template hooks.json CODEX.md")