From 0d9a5d20ecc4022dfa3b1ab7924e561d1b0a3360 Mon Sep 17 00:00:00 2001
From: Abhinav <abhinav@openai.com>
Date: Thu, 30 Apr 2026 17:46:33 -0700
Subject: [PATCH] Alias codex_hooks feature as hooks (#20522)

# Why

The hooks feature flag should use the concise canonical name `hooks`,
while existing configs that still use `codex_hooks` continue to work
during the rename.

# What

- change the canonical `Feature::CodexHooks` key from `codex_hooks` to
`hooks`
- register `codex_hooks` through the existing legacy-alias path
- update the config schema and canonical config fixtures to prefer
`hooks`
- add regression coverage that both `hooks` and `codex_hooks` resolve to
`Feature::CodexHooks`

# Verification

- `cargo test -p codex-features`
- `cargo test -p codex-core config::schema_tests`
- `cargo test -p codex-core
pre_tool_use_blocks_shell_when_defined_in_config_toml`
- `cargo test -p codex-app-server
hooks_list_uses_each_cwds_effective_feature_enablement`
---
 codex-rs/app-server/tests/suite/v2/hooks_list.rs | 6 +++---
 codex-rs/core/config.schema.json                 | 6 ++++++
 codex-rs/core/tests/suite/hooks.rs               | 2 +-
 codex-rs/features/src/legacy.rs                  | 4 ++++
 codex-rs/features/src/lib.rs                     | 2 +-
 codex-rs/features/src/tests.rs                   | 6 ++++++
 6 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/codex-rs/app-server/tests/suite/v2/hooks_list.rs b/codex-rs/app-server/tests/suite/v2/hooks_list.rs
index 87f4decc24..f80d59d96d 100644
--- a/codex-rs/app-server/tests/suite/v2/hooks_list.rs
+++ b/codex-rs/app-server/tests/suite/v2/hooks_list.rs
@@ -63,7 +63,7 @@ fn write_plugin_hook_config(codex_home: &std::path::Path, hooks_json: &str) -> R
         r#"[features]
 plugins = true
 plugin_hooks = true
-codex_hooks = true
+hooks = true
 
 [plugins."demo@test"]
 enabled = true
@@ -230,7 +230,7 @@ async fn hooks_list_uses_each_cwds_effective_feature_enablement() -> Result<()>
     std::fs::write(
         codex_home.path().join("config.toml"),
         r#"[features]
-codex_hooks = false
+hooks = false
 "#,
     )?;
     std::fs::create_dir_all(workspace.path().join(".git"))?;
@@ -238,7 +238,7 @@ codex_hooks = false
     std::fs::write(
         workspace.path().join(".codex/config.toml"),
         r#"[features]
-codex_hooks = true
+hooks = true
 
 [hooks]
 
diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json
index 4d9e3d2d27..d7b7bba6a0 100644
--- a/codex-rs/core/config.schema.json
+++ b/codex-rs/core/config.schema.json
@@ -448,6 +448,9 @@
             "guardian_approval": {
               "type": "boolean"
             },
+            "hooks": {
+              "type": "boolean"
+            },
             "image_detail_original": {
               "type": "boolean"
             },
@@ -3859,6 +3862,9 @@
         "guardian_approval": {
           "type": "boolean"
         },
+        "hooks": {
+          "type": "boolean"
+        },
         "image_detail_original": {
           "type": "boolean"
         },
diff --git a/codex-rs/core/tests/suite/hooks.rs b/codex-rs/core/tests/suite/hooks.rs
index daf3053adc..695e908ed8 100644
--- a/codex-rs/core/tests/suite/hooks.rs
+++ b/codex-rs/core/tests/suite/hooks.rs
@@ -315,7 +315,7 @@ elif mode == "exit_2":
         .unwrap_or_default();
     let config_toml = format!(
         r#"[features]
-codex_hooks = true
+hooks = true
 
 [hooks]
 
diff --git a/codex-rs/features/src/legacy.rs b/codex-rs/features/src/legacy.rs
index 0dfaf0b1cb..e87f14f590 100644
--- a/codex-rs/features/src/legacy.rs
+++ b/codex-rs/features/src/legacy.rs
@@ -49,6 +49,10 @@ const ALIASES: &[Alias] = &[
         legacy_key: "telepathy",
         feature: Feature::Chronicle,
     },
+    Alias {
+        legacy_key: "codex_hooks",
+        feature: Feature::CodexHooks,
+    },
 ];
 
 pub fn legacy_feature_keys() -> impl Iterator<Item = &'static str> {
diff --git a/codex-rs/features/src/lib.rs b/codex-rs/features/src/lib.rs
index 5c2a76eb81..04c3f4921d 100644
--- a/codex-rs/features/src/lib.rs
+++ b/codex-rs/features/src/lib.rs
@@ -782,7 +782,7 @@ pub const FEATURES: &[FeatureSpec] = &[
     },
     FeatureSpec {
         id: Feature::CodexHooks,
-        key: "codex_hooks",
+        key: "hooks",
         stage: Stage::Stable,
         default_enabled: true,
     },
diff --git a/codex-rs/features/src/tests.rs b/codex-rs/features/src/tests.rs
index d1c0ae0c55..cb6310e089 100644
--- a/codex-rs/features/src/tests.rs
+++ b/codex-rs/features/src/tests.rs
@@ -267,6 +267,12 @@ fn collab_is_legacy_alias_for_multi_agent() {
     assert_eq!(feature_for_key("collab"), Some(Feature::Collab));
 }
 
+#[test]
+fn codex_hooks_is_legacy_alias_for_hooks() {
+    assert_eq!(feature_for_key("hooks"), Some(Feature::CodexHooks));
+    assert_eq!(feature_for_key("codex_hooks"), Some(Feature::CodexHooks));
+}
+
 #[test]
 fn multi_agent_is_stable_and_enabled_by_default() {
     assert_eq!(Feature::Collab.stage(), Stage::Stable);