Expose execution mode in hook listings (#37538)

abhinav-oai · copyberry · commit 3aae5d885bac · 2026-08-08T04:57:06.000Z
## What changed

- Add `executionMode` to `HookMetadata` returned by `hooks/list`, with `sync` as the default for compatibility.
- Propagate each discovered hook's `sync` or `async` mode through the app-server protocol and generated schemas.
- Show the execution mode in the TUI hooks browser.

## Testing

- Cover async and default-sync modes in `hooks/list` tests and TUI snapshots.

GitOrigin-RevId: 9c9f2890798fe417face76c15847616b2dea9db4
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
diff --git a/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json b/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst
diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/HookMetadata.ts b/codex-rs/app-server-protocol/schema/typescript/v2/HookMetadata.ts
diff --git a/codex-rs/app-server-protocol/src/protocol/v2/hook.rs b/codex-rs/app-server-protocol/src/protocol/v2/hook.rs
@@ -28,8 +28,11 @@ v2_enum_from_core!(
 );
 
 v2_enum_from_core!(
+    #[derive(Default)]
     pub enum HookExecutionMode from CoreHookExecutionMode {
-        Sync, Async
+        #[default]
+        Sync,
+        Async
     }
 );
 
diff --git a/codex-rs/app-server-protocol/src/protocol/v2/plugin.rs b/codex-rs/app-server-protocol/src/protocol/v2/plugin.rs
@@ -1,5 +1,6 @@
 use super::AppSummary;
 use super::HookEventName;
+use super::HookExecutionMode;
 use super::HookHandlerType;
 use super::HookSource;
 use super::HookTrustStatus;
@@ -524,6 +525,8 @@ pub struct HookMetadata {
     pub key: String,
     pub event_name: HookEventName,
     pub handler_type: HookHandlerType,
+    #[serde(default)]
+    pub execution_mode: HookExecutionMode,
     pub matcher: Option<String>,
     pub command: Option<String>,
     pub timeout_sec: u64,
diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md
@@ -1926,6 +1926,8 @@ For linked Git worktrees, project hook declarations come from the matching `.cod
 
 Hooks are returned even when disabled so clients can render and re-enable them. User-controlled state lives under `hooks.state`. Managed hooks are non-configurable, and user entries for managed hook keys are ignored during loading.
 
+`executionMode` reports how a command hook runs. `sync` hooks participate in the current operation, while `async` hooks run in the background and deliver informational output through the existing steer-based injection path. Output is injected immediately into an active turn or persisted without starting a new turn when the session is idle.
+
 For unmanaged hooks, `currentHash` and `trustStatus` describe whether the current definition is first-seen, approved, or changed since approval. Only trusted unmanaged hooks become runnable. Hook keys combine the source identity with a trailing event/group/handler selector that is currently positional.
 
 ```json
@@ -1948,6 +1950,7 @@ For unmanaged hooks, `currentHash` and `trustStatus` describe whether the curren
         "key": "/Users/me/.codex/config.toml:pre_tool_use:0:0",
         "eventName": "pre_tool_use",
         "handlerType": "command",
+        "executionMode": "sync",
         "isManaged": false,
         "matcher": "Bash",
         "command": "python3 /Users/me/hook.py",
diff --git a/codex-rs/app-server/src/request_processors/catalog_processor.rs b/codex-rs/app-server/src/request_processors/catalog_processor.rs
@@ -70,6 +70,7 @@ fn hooks_to_info(hooks: &[codex_hooks::HookListEntry]) -> Vec<HookMetadata> {
             key: hook.key.clone(),
             event_name: hook.event_name.into(),
             handler_type: hook.handler_type.into(),
+            execution_mode: hook.execution_mode.into(),
             matcher: hook.matcher.clone(),
             command: hook.command.clone(),
             timeout_sec: hook.timeout_sec,
diff --git a/codex-rs/app-server/tests/suite/v2/hooks_list.rs b/codex-rs/app-server/tests/suite/v2/hooks_list.rs
@@ -8,6 +8,7 @@ use app_test_support::create_mock_responses_server_sequence_unchecked;
 use codex_app_server_protocol::ConfigBatchWriteParams;
 use codex_app_server_protocol::ConfigEdit;
 use codex_app_server_protocol::HookEventName;
+use codex_app_server_protocol::HookExecutionMode;
 use codex_app_server_protocol::HookHandlerType;
 use codex_app_server_protocol::HookMetadata;
 use codex_app_server_protocol::HookSource;
@@ -45,6 +46,7 @@ fn command_hook_hash(
     matcher: Option<&str>,
     command: &str,
     timeout_sec: u64,
+    execution_mode: HookExecutionMode,
     status_message: Option<&str>,
     additional_context_limit: Option<usize>,
 ) -> String {
@@ -56,7 +58,7 @@ fn command_hook_hash(
                 command: command.to_string(),
                 command_windows: None,
                 timeout_sec: Some(timeout_sec),
-                r#async: false,
+                r#async: execution_mode == HookExecutionMode::Async,
                 status_message: status_message.map(ToOwned::to_owned),
                 additional_context_limit,
             }],
@@ -80,6 +82,7 @@ matcher = "Bash"
 type = "command"
 command = "python3 /tmp/listed-hook.py"
 timeout = 5
+async = true
 statusMessage = "running listed hook"
 additionalContextLimit = 4096
 "#,
@@ -161,6 +164,7 @@ async fn hooks_list_shows_discovered_hook() -> Result<()> {
                 key: format!("{}:pre_tool_use:0:0", config_path.as_path().display()),
                 event_name: HookEventName::PreToolUse,
                 handler_type: HookHandlerType::Command,
+                execution_mode: HookExecutionMode::Async,
                 matcher: Some("Bash".to_string()),
                 command: Some("python3 /tmp/listed-hook.py".to_string()),
                 timeout_sec: 5,
@@ -177,6 +181,7 @@ async fn hooks_list_shows_discovered_hook() -> Result<()> {
                     Some("Bash"),
                     "python3 /tmp/listed-hook.py",
                     /*timeout_sec*/ 5,
+                    HookExecutionMode::Async,
                     Some("running listed hook"),
                     /*additional_context_limit*/ Some(4_096),
                 ),
@@ -240,6 +245,7 @@ async fn hooks_list_shows_discovered_plugin_hook() -> Result<()> {
                 key: "demo@test:hooks/hooks.json:pre_tool_use:0:0".to_string(),
                 event_name: HookEventName::PreToolUse,
                 handler_type: HookHandlerType::Command,
+                execution_mode: HookExecutionMode::Sync,
                 matcher: Some("Bash".to_string()),
                 command: Some("echo plugin hook".to_string()),
                 timeout_sec: 7,
@@ -256,6 +262,7 @@ async fn hooks_list_shows_discovered_plugin_hook() -> Result<()> {
                     Some("Bash"),
                     "echo plugin hook",
                     /*timeout_sec*/ 7,
+                    HookExecutionMode::Sync,
                     Some("running plugin hook"),
                     /*additional_context_limit*/ None,
                 ),
@@ -436,6 +443,7 @@ timeout = 5
                     ),
                     event_name: HookEventName::PreToolUse,
                     handler_type: HookHandlerType::Command,
+                    execution_mode: HookExecutionMode::Sync,
                     matcher: Some("Bash".to_string()),
                     command: Some("echo project hook".to_string()),
                     timeout_sec: 5,
@@ -452,6 +460,7 @@ timeout = 5
                         Some("Bash"),
                         "echo project hook",
                         /*timeout_sec*/ 5,
+                        HookExecutionMode::Sync,
                         /*status_message*/ None,
                         /*additional_context_limit*/ None,
                     ),
diff --git a/codex-rs/hooks/src/engine/discovery.rs b/codex-rs/hooks/src/engine/discovery.rs
@@ -558,6 +558,7 @@ fn append_matcher_groups(
                         is_managed: source.is_managed,
                         current_hash,
                         trust_status,
+                        execution_mode,
                     });
                     if enabled
                         && (source.bypass_hook_trust
diff --git a/codex-rs/hooks/src/engine/mod.rs b/codex-rs/hooks/src/engine/mod.rs
@@ -108,6 +108,7 @@ pub struct HookListEntry {
     pub is_managed: bool,
     pub current_hash: String,
     pub trust_status: HookTrustStatus,
+    pub execution_mode: codex_protocol::protocol::HookExecutionMode,
 }
 
 #[derive(Clone)]
diff --git a/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs b/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs
@@ -1,4 +1,5 @@
 use codex_app_server_protocol::HookEventName;
+use codex_app_server_protocol::HookExecutionMode;
 use codex_app_server_protocol::HookMetadata;
 use codex_app_server_protocol::HookSource;
 use codex_app_server_protocol::HookTrustStatus;
@@ -492,6 +493,11 @@ impl HooksBrowserView {
             width,
             Some(MAX_COMMAND_DETAIL_LINES),
         ));
+        let execution_mode = match hook.execution_mode {
+            HookExecutionMode::Sync => "Sync",
+            HookExecutionMode::Async => "Async",
+        };
+        lines.push(detail_line("Mode", execution_mode));
         lines.push(detail_line("Timeout", &format!("{}s", hook.timeout_sec)));
         if let Some(limit) = hook.additional_context_limit {
             let value = if limit == 0 {
@@ -883,6 +889,7 @@ mod tests {
     use crate::test_support::test_path_display;
     use codex_app_server_protocol::HookErrorInfo;
     use codex_app_server_protocol::HookEventName;
+    use codex_app_server_protocol::HookExecutionMode;
     use codex_app_server_protocol::HookHandlerType;
     use codex_app_server_protocol::HookMetadata;
     use codex_app_server_protocol::HookSource;
@@ -947,6 +954,7 @@ mod tests {
             key: key.to_string(),
             event_name,
             handler_type: HookHandlerType::Command,
+            execution_mode: HookExecutionMode::Sync,
             is_managed,
             matcher: Some("Bash".to_string()),
             command: Some(command.to_string()),
@@ -1142,6 +1150,7 @@ mod tests {
             /*display_order*/ 0,
         );
         untrusted_hook.trust_status = HookTrustStatus::Untrusted;
+        untrusted_hook.execution_mode = HookExecutionMode::Async;
         let mut view = HooksBrowserView::new(
             vec![untrusted_hook],
             Vec::new(),
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_additional_context_limit.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_additional_context_limit.snap
@@ -12,6 +12,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    User config - /tmp/hooks.json                                                                       
   Command   /tmp/pre-tool-use.sh                                                                                
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Context   unlimited                                                                                           
   Trust     Trusted                                                                                             
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_capped_command_details.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_capped_command_details.snap
@@ -14,6 +14,7 @@ expression: "render_lines(&view, 44)"
   Command   one two three four five six     
             seven eight nine ten eleven     
             twelve thirteen fourteen…       
+  Mode      Sync                            
   Timeout   30s                             
   Trust     Trusted                         
                                             
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_handlers.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_handlers.snap
@@ -13,6 +13,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    Plugin - superpowers@openai-curated                                                                 
   Command   ${CODEX_PLUGIN_ROOT}/hooks/pre-tool-use-check.sh                                                    
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Trust     Trusted                                                                                             
                                                                                                                 
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_managed_handler.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_managed_handler.snap
@@ -12,6 +12,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    Admin config                                                                                        
   Command   /enterprise/hooks/permission-check.sh                                                               
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Trust     Managed                                                                                             
                                                                                                                 
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_review_needed_handler.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_review_needed_handler.snap
@@ -12,6 +12,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    User config - /tmp/hooks.json                                                                       
   Command   /tmp/pre-tool-use-check.sh                                                                          
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Trust     New hook - review required                                                                          
                                                                                                                 
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_scrolled_handlers.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_scrolled_handlers.snap
@@ -19,6 +19,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    User config - /tmp/hooks.json                                                                       
   Command   /tmp/hook-8.sh                                                                                      
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Trust     Trusted                                                                                             
                                                                                                                 
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_selected_managed_handler.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_selected_managed_handler.snap
@@ -13,6 +13,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    Admin config                                                                                        
   Command   /enterprise/hooks/pre-tool-use-2.sh                                                                 
+  Mode      Sync                                                                                                
   Timeout   30s                                                                                                 
   Trust     Managed                                                                                             
                                                                                                                 
diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_untrusted_enabled_handler.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_untrusted_enabled_handler.snap
@@ -12,6 +12,7 @@ expression: "render_lines(&view, 112)"
   Matcher   Bash                                                                                                
   Source    User config - /tmp/hooks.json                                                                       
   Command   ~/bin/untrusted.sh                                                                                  
+  Mode      Async                                                                                               
   Timeout   30s                                                                                                 
   Trust     New hook - review required                                                                          
                                                                                                                 
diff --git a/codex-rs/tui/src/startup_hooks_review.rs b/codex-rs/tui/src/startup_hooks_review.rs
@@ -305,6 +305,7 @@ mod tests {
     use crate::test_support::PathBufExt;
     use crate::test_support::test_path_buf;
     use codex_app_server_protocol::HookEventName;
+    use codex_app_server_protocol::HookExecutionMode;
     use codex_app_server_protocol::HookHandlerType;
     use codex_app_server_protocol::HookMetadata;
     use codex_app_server_protocol::HookSource;
@@ -320,6 +321,7 @@ mod tests {
             key: key.to_string(),
             event_name: HookEventName::PreToolUse,
             handler_type: HookHandlerType::Command,
+            execution_mode: HookExecutionMode::Sync,
             is_managed: false,
             matcher: Some("Bash".to_string()),
             command: Some("/tmp/hook.sh".to_string()),
