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 index b25c8572e0..96ab1b43c9 100644 --- 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 @@ -11031,6 +11031,13 @@ ], "type": "object" }, + "ConfiguredHookFailurePolicy": { + "enum": [ + "continue", + "block" + ], + "type": "string" + }, "ConfiguredHookHandler": { "oneOf": [ { @@ -11056,6 +11063,16 @@ "null" ] }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/v2/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "statusMessage": { "type": [ "string", @@ -11092,6 +11109,16 @@ "additionalProperties": true, "type": "object" }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/v2/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "server": { "type": "string" }, 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 index 2b24736f16..d7a360b267 100644 --- 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 @@ -6785,6 +6785,13 @@ ], "type": "object" }, + "ConfiguredHookFailurePolicy": { + "enum": [ + "continue", + "block" + ], + "type": "string" + }, "ConfiguredHookHandler": { "oneOf": [ { @@ -6810,6 +6817,16 @@ "null" ] }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "statusMessage": { "type": [ "string", @@ -6846,6 +6863,16 @@ "additionalProperties": true, "type": "object" }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "server": { "type": "string" }, diff --git a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json index 5a6cc34788..09ca61d93f 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json @@ -673,6 +673,13 @@ }, "type": "object" }, + "ConfiguredHookFailurePolicy": { + "enum": [ + "continue", + "block" + ], + "type": "string" + }, "ConfiguredHookHandler": { "oneOf": [ { @@ -698,6 +705,16 @@ "null" ] }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "statusMessage": { "type": [ "string", @@ -734,6 +751,16 @@ "additionalProperties": true, "type": "object" }, + "onFailure": { + "anyOf": [ + { + "$ref": "#/definitions/ConfiguredHookFailurePolicy" + }, + { + "type": "null" + } + ] + }, "server": { "type": "string" }, 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 index 5178d6e31c..3453edc8b4 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differ 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 index 3851d9456d..758197e7cb 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookFailurePolicy.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookFailurePolicy.ts new file mode 100644 index 0000000000..21bdab872d --- /dev/null +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookFailurePolicy.ts @@ -0,0 +1,5 @@ +// GENERATED CODE! DO NOT MODIFY BY HAND! + +// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. + +export type ConfiguredHookFailurePolicy = "continue" | "block"; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookHandler.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookHandler.ts index 6ee1b16ba3..f70d35ccef 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookHandler.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ConfiguredHookHandler.ts @@ -2,12 +2,13 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. import type { JsonValue } from "../serde_json/JsonValue"; +import type { ConfiguredHookFailurePolicy } from "./ConfiguredHookFailurePolicy"; -export type ConfiguredHookHandler = { "type": "command", command: string, commandWindows: string | null, timeoutSec: bigint | null, async: boolean, statusMessage: string | null, +export type ConfiguredHookHandler = { "type": "command", command: string, commandWindows: string | null, timeoutSec: bigint | null, async: boolean, statusMessage: string | null, onFailure: ConfiguredHookFailurePolicy | null, /** * Approximate token threshold for spilling this hook's `additionalContext` to disk. * `null` uses 2,500 tokens; `0` disables spilling for this hook. The threshold is * evaluated against the original context; a spilled preview also includes recovery * metadata. */ -additionalContextLimit: number | null, } | { "type": "mcp_tool", server: string, tool: string, input: { [key in string]?: JsonValue }, timeoutSec: bigint | null, statusMessage: string | null, } | { "type": "prompt", } | { "type": "agent", }; +additionalContextLimit: number | null, } | { "type": "mcp_tool", server: string, tool: string, input: { [key in string]?: JsonValue }, timeoutSec: bigint | null, statusMessage: string | null, onFailure: ConfiguredHookFailurePolicy | null, } | { "type": "prompt", } | { "type": "agent", }; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts b/codex-rs/app-server-protocol/schema/typescript/v2/index.ts index 3368881f4a..936f74e6f7 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/index.ts @@ -126,6 +126,7 @@ export type { ConfigRequirementsReadResponse } from "./ConfigRequirementsReadRes export type { ConfigValueWriteParams } from "./ConfigValueWriteParams"; export type { ConfigWarningNotification } from "./ConfigWarningNotification"; export type { ConfigWriteResponse } from "./ConfigWriteResponse"; +export type { ConfiguredHookFailurePolicy } from "./ConfiguredHookFailurePolicy"; export type { ConfiguredHookHandler } from "./ConfiguredHookHandler"; export type { ConfiguredHookMatcherGroup } from "./ConfiguredHookMatcherGroup"; export type { ConnectorMetadata } from "./ConnectorMetadata"; diff --git a/codex-rs/app-server-protocol/src/protocol/v2/config.rs b/codex-rs/app-server-protocol/src/protocol/v2/config.rs index 4e4e5d920c..1d40b7451c 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/config.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/config.rs @@ -738,6 +738,14 @@ pub struct ConfiguredHookMatcherGroup { pub hooks: Vec, } +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)] +#[serde(rename_all = "camelCase")] +#[ts(rename_all = "camelCase", export_to = "v2/")] +pub enum ConfiguredHookFailurePolicy { + Continue, + Block, +} + #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)] #[serde(tag = "type")] #[ts(tag = "type", export_to = "v2/")] @@ -756,6 +764,9 @@ pub enum ConfiguredHookHandler { #[serde(rename = "statusMessage")] #[ts(rename = "statusMessage")] status_message: Option, + #[serde(rename = "onFailure")] + #[ts(rename = "onFailure")] + on_failure: Option, /// Approximate token threshold for spilling this hook's `additionalContext` to disk. /// `null` uses 2,500 tokens; `0` disables spilling for this hook. The threshold is /// evaluated against the original context; a spilled preview also includes recovery @@ -776,6 +787,9 @@ pub enum ConfiguredHookHandler { #[serde(rename = "statusMessage")] #[ts(rename = "statusMessage")] status_message: Option, + #[serde(rename = "onFailure")] + #[ts(rename = "onFailure")] + on_failure: Option, }, #[serde(rename = "prompt")] #[ts(rename = "prompt")] diff --git a/codex-rs/app-server/src/request_processors/config_processor.rs b/codex-rs/app-server/src/request_processors/config_processor.rs index 722c796453..d0104942dc 100644 --- a/codex-rs/app-server/src/request_processors/config_processor.rs +++ b/codex-rs/app-server/src/request_processors/config_processor.rs @@ -29,6 +29,7 @@ use codex_app_server_protocol::ConfigRequirementsReadResponse; use codex_app_server_protocol::ConfigValueWriteParams; use codex_app_server_protocol::ConfigWriteErrorCode; use codex_app_server_protocol::ConfigWriteResponse; +use codex_app_server_protocol::ConfiguredHookFailurePolicy; use codex_app_server_protocol::ConfiguredHookHandler; use codex_app_server_protocol::ConfiguredHookMatcherGroup; use codex_app_server_protocol::ExperimentalFeatureEnablementSetParams; @@ -865,6 +866,7 @@ fn map_hook_handler_to_api(handler: CoreHookHandlerConfig) -> ConfiguredHookHand timeout_sec, r#async, status_message, + on_failure, additional_context_limit, } => ConfiguredHookHandler::Command { command, @@ -872,6 +874,7 @@ fn map_hook_handler_to_api(handler: CoreHookHandlerConfig) -> ConfiguredHookHand timeout_sec, r#async, status_message, + on_failure: on_failure.map(map_hook_failure_policy_to_api), additional_context_limit, }, CoreHookHandlerConfig::McpTool { @@ -880,18 +883,29 @@ fn map_hook_handler_to_api(handler: CoreHookHandlerConfig) -> ConfiguredHookHand input, timeout_sec, status_message, + on_failure, } => ConfiguredHookHandler::McpTool { server, tool, input, timeout_sec, status_message, + on_failure: on_failure.map(map_hook_failure_policy_to_api), }, CoreHookHandlerConfig::Prompt {} => ConfiguredHookHandler::Prompt {}, CoreHookHandlerConfig::Agent {} => ConfiguredHookHandler::Agent {}, } } +fn map_hook_failure_policy_to_api( + policy: codex_config::HookFailurePolicy, +) -> ConfiguredHookFailurePolicy { + match policy { + codex_config::HookFailurePolicy::Continue => ConfiguredHookFailurePolicy::Continue, + codex_config::HookFailurePolicy::Block => ConfiguredHookFailurePolicy::Block, + } +} + fn map_sandbox_mode_requirement_to_api(mode: CoreSandboxModeRequirement) -> Option { match mode { CoreSandboxModeRequirement::ReadOnly => Some(SandboxMode::ReadOnly), diff --git a/codex-rs/app-server/tests/suite/v2/config_rpc.rs b/codex-rs/app-server/tests/suite/v2/config_rpc.rs index aac5e1c456..30da8cce18 100644 --- a/codex-rs/app-server/tests/suite/v2/config_rpc.rs +++ b/codex-rs/app-server/tests/suite/v2/config_rpc.rs @@ -261,20 +261,23 @@ async fn config_requirements_read_includes_remote_control_and_managed_hooks() -> [hooks] -[[hooks.SessionStart]] +[[hooks.PreToolUse]] +matcher = "config-read-fixture" -[[hooks.SessionStart.hooks]] +[[hooks.PreToolUse.hooks]] type = "command" command = "echo managed" additionalContextLimit = 4096 +onFailure = "block" -[[hooks.SessionStart.hooks]] +[[hooks.PreToolUse.hooks]] type = "mcp_tool" server = "security" tool = "scan" input = { path = "${tool_input.file_path}", metadata = { enabled = true, retries = 2 } } timeout = 30 statusMessage = "Scanning file" +onFailure = "continue" "#, )?; let mut mcp = TestAppServer::builder() @@ -294,7 +297,10 @@ statusMessage = "Scanning file" requirements .hooks .expect("managed hooks should be returned") - .session_start[0] + .pre_tool_use + .into_iter() + .find(|group| group.matcher.as_deref() == Some("config-read-fixture")) + .expect("fixture hook group should be returned") .hooks, vec![ ConfiguredHookHandler::Command { @@ -303,6 +309,7 @@ statusMessage = "Scanning file" timeout_sec: None, r#async: false, status_message: None, + on_failure: Some(codex_app_server_protocol::ConfiguredHookFailurePolicy::Block), additional_context_limit: Some(4_096), }, ConfiguredHookHandler::McpTool { @@ -314,6 +321,7 @@ statusMessage = "Scanning file" }))?, timeout_sec: Some(30), status_message: Some("Scanning file".to_string()), + on_failure: Some(codex_app_server_protocol::ConfiguredHookFailurePolicy::Continue), }, ] ); 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 a7f1b41754..1246a36448 100644 --- a/codex-rs/app-server/tests/suite/v2/hooks_list.rs +++ b/codex-rs/app-server/tests/suite/v2/hooks_list.rs @@ -66,6 +66,7 @@ fn command_hook_hash( timeout_sec: Some(timeout_sec), r#async, status_message: status_message.map(ToOwned::to_owned), + on_failure: None, additional_context_limit, }], }, diff --git a/codex-rs/config/src/hook_config.rs b/codex-rs/config/src/hook_config.rs index 913ad56500..5599be5dbe 100644 --- a/codex-rs/config/src/hook_config.rs +++ b/codex-rs/config/src/hook_config.rs @@ -3,6 +3,7 @@ use std::path::Path; use std::path::PathBuf; pub use codex_protocol::hooks::HookEventsToml; +pub use codex_protocol::hooks::HookFailurePolicy; pub use codex_protocol::hooks::HookHandlerConfig; pub use codex_protocol::hooks::MatcherGroup; use schemars::JsonSchema; diff --git a/codex-rs/config/src/hooks_tests.rs b/codex-rs/config/src/hooks_tests.rs index e3b9721e89..8154f50130 100644 --- a/codex-rs/config/src/hooks_tests.rs +++ b/codex-rs/config/src/hooks_tests.rs @@ -47,6 +47,7 @@ fn hooks_file_deserializes_existing_json_shape() { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: Some(4096), }], }], @@ -95,6 +96,7 @@ fn hooks_file_deserializes_mcp_tool_handler_with_json_inputs() { ]), timeout_sec: Some(30), status_message: Some("Scanning file".to_string()), + on_failure: None, }] ); } @@ -181,6 +183,7 @@ additionalContextLimit = 4096 timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: Some(4096), }], }], @@ -219,6 +222,7 @@ command = "python3 /tmp/pre.py" timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -248,6 +252,7 @@ matcher = "^Bash$" [[PreToolUse.hooks]] type = "command" command = "python3 /enterprise/place/pre.py" +onFailure = "block" "#, ) .expect("requirements hooks TOML should deserialize"); @@ -266,6 +271,7 @@ command = "python3 /enterprise/place/pre.py" timeout_sec: None, r#async: false, status_message: None, + on_failure: Some(super::HookFailurePolicy::Block), additional_context_limit: None, }], }], @@ -303,6 +309,7 @@ command_windows = "powershell -File C:\\enterprise\\hooks\\pre.ps1" timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -339,6 +346,7 @@ commandWindows = "powershell -File C:\\enterprise\\hooks\\pre.ps1" timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -348,17 +356,29 @@ commandWindows = "powershell -File C:\\enterprise\\hooks\\pre.ps1" } #[test] -fn hook_handler_omits_unset_additional_context_limit() { +fn hook_handler_omits_unset_optional_policies() { let handler = HookHandlerConfig::Command { command: "python3 /tmp/pre.py".to_string(), command_windows: None, timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }; let serialized = serde_json::to_value(handler).expect("hook handler should serialize"); assert_eq!(serialized.get("additionalContextLimit"), None); + assert_eq!(serialized.get("onFailure"), None); +} + +#[test] +fn hook_failure_policy_rejects_unknown_values() { + for handler in [ + serde_json::json!({"type": "command", "command": "echo hello", "onFailure": "deny"}), + serde_json::json!({"type": "mcp_tool", "server": "scanner", "tool": "check", "onFailure": "deny"}), + ] { + assert!(serde_json::from_value::(handler).is_err()); + } } diff --git a/codex-rs/config/src/lib.rs b/codex-rs/config/src/lib.rs index 2cd2a0742b..b2589949d8 100644 --- a/codex-rs/config/src/lib.rs +++ b/codex-rs/config/src/lib.rs @@ -173,6 +173,7 @@ pub use diagnostics::io_error_from_config_error; pub use fingerprint::version_for_toml; pub use guardian::GuardianPolicyLoader; pub use hook_config::HookEventsToml; +pub use hook_config::HookFailurePolicy; pub use hook_config::HookHandlerConfig; pub use hook_config::HookStateToml; pub use hook_config::HooksFile; diff --git a/codex-rs/core-plugins/src/executor_hooks_tests.rs b/codex-rs/core-plugins/src/executor_hooks_tests.rs index b029863f27..fcffe68ac4 100644 --- a/codex-rs/core-plugins/src/executor_hooks_tests.rs +++ b/codex-rs/core-plugins/src/executor_hooks_tests.rs @@ -100,6 +100,7 @@ fn expected_source(index: usize) -> ExecutorPluginHookSource { .expect("executor hook input"), timeout_sec: None, status_message: None, + on_failure: None, }], }], ..Default::default() @@ -247,6 +248,7 @@ fn preserves_allowlisted_executor_plugin_hook_options() { .expect("manifest-provided executor hook input"), timeout_sec: Some(30), status_message: Some("Cleaning up Computer Use".to_string()), + on_failure: None, }; expected.hooks.interrupt = expected.hooks.stop.clone(); diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json index d78af74de9..4635d21a83 100644 --- a/codex-rs/core/config.schema.json +++ b/codex-rs/core/config.schema.json @@ -2598,6 +2598,13 @@ } ] }, + "HookFailurePolicy": { + "enum": [ + "continue", + "block" + ], + "type": "string" + }, "HookHandlerConfig": { "oneOf": [ { @@ -2619,6 +2626,14 @@ "default": null, "type": "string" }, + "onFailure": { + "allOf": [ + { + "$ref": "#/definitions/HookFailurePolicy" + } + ], + "description": "Failure policy for synchronous hooks that support blocking. Defaults to continue; block applies the event's blocking behavior on failure." + }, "statusMessage": { "default": null, "type": "string" @@ -2649,6 +2664,14 @@ "default": {}, "type": "object" }, + "onFailure": { + "allOf": [ + { + "$ref": "#/definitions/HookFailurePolicy" + } + ], + "description": "Failure policy for MCP hooks that support blocking. Defaults to continue; block applies the event's blocking behavior on failure." + }, "server": { "type": "string" }, diff --git a/codex-rs/core/src/hook_runtime.rs b/codex-rs/core/src/hook_runtime.rs index f23ea6ac80..22b0506bc4 100644 --- a/codex-rs/core/src/hook_runtime.rs +++ b/codex-rs/core/src/hook_runtime.rs @@ -247,6 +247,8 @@ pub(crate) async fn run_pre_tool_use_hooks( }; }; + let reason = reason.trim_end_matches('.'); + if (tool_name.name() == "Bash" || tool_name.name() == "apply_patch") && let Some(command) = tool_input.get("command").and_then(Value::as_str) { diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rs index 1bc4dfe910..ec508e97df 100644 --- a/codex-rs/core/src/session/tests.rs +++ b/codex-rs/core/src/session/tests.rs @@ -1946,6 +1946,7 @@ async fn refresh_runtime_config_refreshes_hooks() -> anyhow::Result<()> { timeout_sec: Some(600), r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }, diff --git a/codex-rs/core/tests/suite/hooks.rs b/codex-rs/core/tests/suite/hooks.rs index fe6a5126d4..611cda6bd9 100644 --- a/codex-rs/core/tests/suite/hooks.rs +++ b/codex-rs/core/tests/suite/hooks.rs @@ -176,11 +176,20 @@ fn non_openai_model_provider(server: &wiremock::MockServer) -> ModelProviderInfo provider } -fn write_stop_hook(home: &Path, block_prompts: &[&str]) -> Result<()> { +pub(super) fn write_stop_hook( + home: &Path, + block_prompts: &[&str], + on_failure: Option<&str>, +) -> Result<()> { let script_path = home.join("stop_hook.py"); let log_path = home.join("stop_hook_log.jsonl"); let prompts_json = serde_json::to_string(block_prompts).context("serialize stop hook prompts for test")?; + let fail = if on_failure == Some("block") { + "True" + } else { + "False" + }; let script = format!( r#"import json from pathlib import Path @@ -199,6 +208,8 @@ with log_path.open("a", encoding="utf-8") as handle: invocation_index = len(existing) if invocation_index < len(block_prompts): + if {fail}: + sys.exit(1) print(json.dumps({{"decision": "block", "reason": block_prompts[invocation_index]}})) else: print(json.dumps({{"systemMessage": f"stop hook pass {{invocation_index + 1}} complete"}})) @@ -213,6 +224,7 @@ else: "type": "command", "command": format!("python3 {}", script_path.display()), "statusMessage": "running stop hook", + "onFailure": on_failure, }] }] } @@ -1322,6 +1334,7 @@ async fn stop_hook_can_block_multiple_times_in_same_turn() -> Result<()> { write_stop_hook( home, &[FIRST_CONTINUATION_PROMPT, SECOND_CONTINUATION_PROMPT], + /*on_failure*/ None, ) .expect("failed to write stop hook test fixture"); }) @@ -2660,7 +2673,7 @@ async fn stop_hook_spills_large_continuation_prompt() -> Result<()> { .with_pre_build_hook({ let continuation_prompt = continuation_prompt.clone(); move |home| { - write_stop_hook(home, &[&continuation_prompt]) + write_stop_hook(home, &[&continuation_prompt], /*on_failure*/ None) .expect("failed to write stop hook test fixture"); } }) @@ -2705,7 +2718,7 @@ async fn resumed_thread_keeps_stop_continuation_prompt_in_history() -> Result<() let mut initial_builder = test_codex() .with_pre_build_hook(|home| { - write_stop_hook(home, &[FIRST_CONTINUATION_PROMPT]) + write_stop_hook(home, &[FIRST_CONTINUATION_PROMPT], /*on_failure*/ None) .expect("failed to write stop hook test fixture"); }) .with_config(trust_discovered_hooks); diff --git a/codex-rs/core/tests/suite/hooks_mcp.rs b/codex-rs/core/tests/suite/hooks_mcp.rs index 79a03bc4e1..0165bd6aba 100644 --- a/codex-rs/core/tests/suite/hooks_mcp.rs +++ b/codex-rs/core/tests/suite/hooks_mcp.rs @@ -46,6 +46,7 @@ use core_test_support::wait_for_mcp_server; use pretty_assertions::assert_eq; use serde_json::Value; use serde_json::json; +use test_case::test_case; use super::rmcp_client::remote_aware_environment_id; use super::rmcp_client::remote_aware_stdio_server_bin; @@ -57,6 +58,123 @@ const RMCP_ECHO_TOOL_NAME: &str = "mcp__rmcp__echo"; const RMCP_HOOK_MATCHER: &str = RMCP_ECHO_TOOL_NAME; const RMCP_ECHO_MESSAGE: &str = "hook e2e ping"; +#[test_case("PreToolUse", "continue", RMCP_SERVER; "pre_tool_error_continues")] +#[test_case("PreToolUse", "block", RMCP_SERVER; "pre_tool_error_blocks")] +#[test_case("PreToolUse", "continue", "unavailable-scanner"; "pre_tool_unavailable_continues")] +#[test_case("PermissionRequest", "continue", RMCP_SERVER; "permission_error_continues")] +#[test_case("PermissionRequest", "block", RMCP_SERVER; "permission_error_blocks")] +#[test_case("PermissionRequest", "block", "unavailable-scanner"; "permission_unavailable_blocks")] +#[test_case("PostToolUse", "continue", RMCP_SERVER; "post_tool_error_continues")] +#[test_case("PostToolUse", "block", RMCP_SERVER; "post_tool_error_blocks")] +#[test_case("PostToolUse", "block", "unavailable-scanner"; "post_tool_unavailable_blocks")] +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn mcp_hook_failure_policy_controls_tool_execution( + event: &'static str, + policy: &'static str, + scanner: &'static str, +) -> Result<()> { + skip_if_no_network!(Ok(())); + skip_if_wine_exec!( + Ok(()), + "requires a Windows test_stdio_server in the Wine-exec environment" + ); + failed_mcp_hook_scenario(event, policy, scanner).await?; + Ok(()) +} + +pub(super) async fn failed_mcp_hook_scenario( + event: &'static str, + policy: &'static str, + scanner: &'static str, +) -> Result> { + let server = start_mock_server().await; + let call_id = "failed-mcp-hook-echo"; + let responses = mount_sse_sequence( + &server, + vec![ + sse(vec![ + ev_response_created("resp-1"), + ev_function_call_with_namespace( + call_id, + RMCP_PREFIXED_NAMESPACE, + "echo", + &json!({ "message": RMCP_ECHO_MESSAGE }).to_string(), + ), + ev_completed("resp-1"), + ]), + sse(vec![ + ev_response_created("resp-2"), + ev_assistant_message("msg-1", "done"), + ev_completed("resp-2"), + ]), + ], + ) + .await; + let rmcp_test_server_bin = remote_aware_stdio_server_bin()?; + let test = test_codex() + .with_pre_build_hook(move |home| { + let hooks = json!({"hooks": {event: [{ + "matcher": RMCP_HOOK_MATCHER, + "hooks": [{ + "type": "mcp_tool", "server": scanner, "tool": "js", + "input": {"code": "nodeRepl.fail()"}, "onFailure": policy, "timeout": 5, + }, { + "type": "mcp_tool", "server": RMCP_SERVER, "tool": "image_scenario", + "input": {"scenario": "text_only", "caption": if event == "PermissionRequest" { + r#"{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}"# + } else { "{}" }}, + }], + }]}}); + fs::write(home.join("hooks.json"), hooks.to_string()).expect("write failing MCP hook"); + }) + .with_config(move |config| { + trust_discovered_hooks(config); + config.approvals_reviewer = ApprovalsReviewer::AutoReview; + let approval = if event == "PermissionRequest" { + AppToolApproval::Prompt + } else { + AppToolApproval::Approve + }; + insert_rmcp_test_server( + config, + rmcp_test_server_bin, + approval, + remote_aware_environment_id(), + ); + let mut servers = config.mcp_servers.get().clone(); + if let McpServerTransportConfig::Stdio { env, .. } = + &mut servers.get_mut(RMCP_SERVER).expect("test server").transport + { + *env = Some(HashMap::from([( + "MCP_TEST_ENABLE_NODE_REPL_JS".to_string(), + "1".to_string(), + )])); + } + config.mcp_servers.set(servers).expect("test MCP config"); + }) + .build_with_auto_env(&server) + .await?; + wait_for_mcp_server(&test.codex, RMCP_SERVER).await?; + test.submit_turn_with_approval_and_permission_profile( + "call the echo tool", + AskForApproval::OnRequest, + PermissionProfile::Disabled, + ) + .await?; + let requests = responses.requests(); + assert_eq!(requests.len(), 2); + let output = requests[1].function_call_output(call_id)["output"].to_string(); + assert_eq!( + output.contains("hook failed. This hook is configured to block continuation on failure."), + policy == "block" + ); + assert_eq!(output.contains("ECHOING:"), policy == "continue"); + assert!(requests.iter().all(|request| { + request.body_json()["client_metadata"]["x-openai-subagent"].as_str() != Some("guardian") + })); + Ok(requests) +} + #[derive(Clone, Copy)] enum PermissionRequestHookOutcome { Allow, @@ -981,8 +1099,18 @@ async fn mcp_tool_hook_blocks_model_tool_without_recursive_hooks_or_approval() - Ok(()) } +#[test_case("UserPromptSubmit", None; "prompt_default_continues")] +#[test_case("UserPromptSubmit", Some("continue"); "prompt_continues")] +#[test_case("UserPromptSubmit", Some("block"); "prompt_blocks")] +#[test_case("SessionStart", Some("continue"); "session_continues")] +#[test_case("SessionStart", Some("block"); "session_blocks")] +#[test_case("SubagentStart", Some("continue"); "subagent_continues")] +#[test_case("SubagentStart", Some("block"); "subagent_blocks")] #[tokio::test(flavor = "multi_thread", worker_threads = 2)] -async fn mcp_tool_hook_fails_open_when_server_is_unavailable() -> Result<()> { +async fn unavailable_mcp_hook_controls_sampling( + event: &'static str, + policy: Option<&'static str>, +) -> Result<()> { skip_if_no_network!(Ok(())); let server = start_mock_server().await; @@ -995,31 +1123,46 @@ async fn mcp_tool_hook_fails_open_when_server_is_unavailable() -> Result<()> { ]), ) .await; - let test = test_codex() - .with_pre_build_hook(|home| { - write_mcp_tool_hook( - home, - "UserPromptSubmit", - /*matcher*/ None, - "missing-server", - r#"{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"this must not appear"}}"#, + let mut test = test_codex() + .with_pre_build_hook(move |home| { + fs::write( + home.join("hooks.json"), + json!({"hooks": {event: [{"hooks": [{ + "type": "mcp_tool", "server": "missing-server", "tool": "check", + "onFailure": policy, + }]}]}}) + .to_string(), ) .expect("write unavailable MCP server fixture"); }) .with_config(trust_discovered_hooks) - .build(&server) + .build_with_auto_env(&server) .await?; + if event == "SubagentStart" { + let child = test + .thread_manager + .start_thread(StartThreadOptions { + session_source: Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn { + parent_thread_id: test.session_configured.thread_id, + depth: 1, + agent_path: None, + agent_nickname: None, + agent_role: None, + })), + ..test.start_thread_options().await + }) + .await?; + test.codex = child.thread; + test.session_configured = child.session_configured; + } tokio::time::timeout(Duration::from_secs(5), test.submit_turn("continue")) .await .context("unavailable MCP hook server must fail immediately")??; - assert!( - !response - .single_request() - .message_input_texts("developer") - .iter() - .any(|message| message.contains("this must not appear")) + assert_eq!( + response.requests().len(), + usize::from(policy != Some("block")) ); Ok(()) diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs index 0f821009aa..fc957f5b61 100644 --- a/codex-rs/core/tests/suite/scenarios.rs +++ b/codex-rs/core/tests/suite/scenarios.rs @@ -727,6 +727,95 @@ async fn additional_context_tool_outputs(tool_outputs: bool) -> Result<()> { Ok(()) } +// The shared MCP scenario is compiled only on non-Windows hosts. +#[cfg(not(target_os = "windows"))] +#[test_case::test_case("PreToolUse"; "pre_tool_use")] +#[test_case::test_case("PostToolUse"; "post_tool_use")] +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn hook_failure_blocks_tool_execution(event: &'static str) -> Result<()> { + skip_if_no_network!(Ok(())); + skip_if_wine_exec!( + Ok(()), + "requires a Windows test_stdio_server in the Wine-exec environment" + ); + let requests = + super::hooks_mcp::failed_mcp_hook_scenario(event, "block", "unavailable-scanner").await?; + let (name, description) = if event == "PreToolUse" { + ( + "hook_failure_blocks_tool_execution", + "A required PreToolUse check fails; onFailure:block rejects the tool call and reports the failure to the model.", + ) + } else { + ( + "hook_failure_blocks_tool_result", + "A required PostToolUse check fails; onFailure:block withholds the completed tool's result and reports the failure to the model.", + ) + }; + insta::assert_snapshot!( + name, + context_snapshot::format_request_history_snapshot( + description, + &requests, + &ContextSnapshotOptions::default().rewrite_known_segments(), + ) + ); + Ok(()) +} + +#[cfg(not(target_os = "windows"))] +#[tokio::test] +async fn hook_failure_blocks_completion_until_recovery() -> Result<()> { + skip_if_no_network!(Ok(())); + let server = start_mock_server().await; + let responses = mount_sse_sequence( + &server, + vec![ + sse(vec![ + ev_assistant_message("draft", "initial draft"), + ev_completed("resp-1"), + ]), + sse(vec![ + ev_assistant_message("final", "reviewed draft"), + ev_completed("resp-2"), + ]), + ], + ) + .await; + let test = test_codex() + .with_pre_build_hook(|home| { + super::hooks::write_stop_hook(home, &["failed check"], Some("block")) + .expect("write failing stop hook"); + }) + .with_config(core_test_support::hooks::trust_discovered_hooks) + // Command hooks execute on the host and need a host-native working directory. + .build(&server) + .await?; + test.submit_turn("write a draft").await?; + let requests = responses.requests(); + assert_eq!(requests.len(), 2); + let mut bodies = requests + .iter() + .map(core_test_support::responses::ResponsesRequest::body_json) + .collect::>(); + for body in &mut bodies { + // Normalize the hook run's temporary path before snapshot truncation and hashing. + body["input"] = serde_json::from_str(&body["input"].to_string().replace( + test.codex_home_path().to_string_lossy().as_ref(), + "", + ))?; + } + let entries = bodies.iter().map(SnapshotEntry::body).collect::>(); + insta::assert_snapshot!( + "hook_failure_blocks_completion_until_recovery", + context_snapshot::format_context_snapshot( + "A Stop hook fails once with onFailure:block; completion resumes only after a subsequent hook run succeeds.", + &entries, + &ContextSnapshotOptions::default().rewrite_known_segments(), + ) + ); + Ok(()) +} + #[tokio::test] async fn cached_stdio_stays_dormant_in_a_new_chat_until_first_use() -> Result<()> { skip_if_no_network!(Ok(())); diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_completion_until_recovery.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_completion_until_recovery.snap new file mode 100644 index 0000000000..d573449b3d --- /dev/null +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_completion_until_recovery.snap @@ -0,0 +1,25 @@ +--- +source: core/tests/suite/scenarios.rs +expression: "context_snapshot::format_context_snapshot(\"A Stop hook fails once with onFailure:block; completion resumes only after a subsequent hook run succeeds.\",\n&entries, &ContextSnapshotOptions::default().rewrite_known_segments(),)" +--- +Scenario: A Stop hook fails once with onFailure:block; completion resumes only after a subsequent hook run succeeds. + +## Window 1 +-- request 1 (request) -- +00:message/developer: + +01:message/developer[2]: + [01] + [02] + Deferred tool namespaces: + - multi_agent_v1: Tools for spawning and managing sub-agents. + +02:message/user: + +03:message/user: + write a draft +-- request 2 (request) -- +04:message/assistant: + initial draft +05:message/user: + Stop hook failed. This hook is configured to block continuation on failure. diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_execution.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_execution.snap new file mode 100644 index 0000000000..c1ce42d949 --- /dev/null +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_execution.snap @@ -0,0 +1,24 @@ +--- +source: core/tests/suite/scenarios.rs +expression: "context_snapshot::format_request_history_snapshot(description, &requests,\n&ContextSnapshotOptions::default().rewrite_known_segments(),)" +--- +Scenario: A required PreToolUse check fails; onFailure:block rejects the tool call and reports the failure to the model. + +## Window 1 +-- request 1 (turn) -- +00:message/developer: + +01:message/developer[2]: + [01] + [02] + Deferred tool namespaces: + - mcp__rmcp: Use these tools to exercise the rmcp test server. + - multi_agent_v1: Tools for spawning and managing sub-agents. + +02:message/user: + +03:message/user: + call the echo tool +-- request 2 (turn) -- +04:function_call/mcp__rmcp.echo:{"message":"hook e2e ping"} +05:function_call_output:Tool call blocked by PreToolUse hook: PreToolUse hook failed. This hook is configured to block continuation on failure. Tool: mcp__rmcp__echo diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_result.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_result.snap new file mode 100644 index 0000000000..5d98f315f6 --- /dev/null +++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__hook_failure_blocks_tool_result.snap @@ -0,0 +1,24 @@ +--- +source: core/tests/suite/scenarios.rs +expression: "context_snapshot::format_request_history_snapshot(description, &requests,\n&ContextSnapshotOptions::default().rewrite_known_segments(),)" +--- +Scenario: A required PostToolUse check fails; onFailure:block withholds the completed tool's result and reports the failure to the model. + +## Window 1 +-- request 1 (turn) -- +00:message/developer: + +01:message/developer[2]: + [01] + [02] + Deferred tool namespaces: + - mcp__rmcp: Use these tools to exercise the rmcp test server. + - multi_agent_v1: Tools for spawning and managing sub-agents. + +02:message/user: + +03:message/user: + call the echo tool +-- request 2 (turn) -- +04:function_call/mcp__rmcp.echo:{"message":"hook e2e ping"} +05:function_call_output:PostToolUse hook failed. This hook is configured to block continuation on failure. diff --git a/codex-rs/hooks/src/declarations.rs b/codex-rs/hooks/src/declarations.rs index 42ca76a2ed..0ebeed7ce3 100644 --- a/codex-rs/hooks/src/declarations.rs +++ b/codex-rs/hooks/src/declarations.rs @@ -69,6 +69,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }, ], diff --git a/codex-rs/hooks/src/engine/command_runner_tests.rs b/codex-rs/hooks/src/engine/command_runner_tests.rs index 5f67b64db5..bf40efdd0c 100644 --- a/codex-rs/hooks/src/engine/command_runner_tests.rs +++ b/codex-rs/hooks/src/engine/command_runner_tests.rs @@ -117,6 +117,7 @@ async fn hook_shell_startup_does_not_stop_on_controlling_terminal() { matcher: None, timeout_sec: 2, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: AbsolutePathBuf::try_from(temp.path().join("hooks.json")) .expect("absolute hook configuration path") @@ -222,6 +223,7 @@ async fn cmd_shell_runs_quoted_hook_command_path() { matcher: None, timeout_sec: 10, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: source_path.into(), source: HookSource::User, @@ -273,6 +275,7 @@ async fn fast_exiting_hook_preserves_stdout_when_stdin_is_not_consumed() { matcher: None, timeout_sec: 10, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: source_path.into(), source: HookSource::User, @@ -362,6 +365,7 @@ async fn command_hook_does_not_expose_configured_noise_auth_token() { matcher: None, timeout_sec: 10, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: source_path.into(), source: HookSource::User, @@ -501,6 +505,7 @@ fn write_handler(temp: &TempDir, source: &str) -> ConfiguredHandler { matcher: None, timeout_sec: 10, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: AbsolutePathBuf::try_from(temp.path().join("hooks.json")) .expect("absolute test hook path") diff --git a/codex-rs/hooks/src/engine/discovery.rs b/codex-rs/hooks/src/engine/discovery.rs index 055ad8f05b..4095adde5d 100644 --- a/codex-rs/hooks/src/engine/discovery.rs +++ b/codex-rs/hooks/src/engine/discovery.rs @@ -649,6 +649,28 @@ fn append_matcher_groups( } }; for (handler_index, handler) in group.hooks.iter().cloned().enumerate() { + let on_failure = match &handler { + HookHandlerConfig::Command { on_failure, .. } + | HookHandlerConfig::McpTool { on_failure, .. } => *on_failure, + HookHandlerConfig::Prompt {} | HookHandlerConfig::Agent {} => None, + }; + if on_failure == Some(codex_config::HookFailurePolicy::Block) + && (matches!( + event_name, + HookEventName::SessionEnd + | HookEventName::PreModelRequest + | HookEventName::PostModelRequest + ) || matches!(handler, HookHandlerConfig::Command { r#async: true, .. })) + { + source.record_load_failure( + format!( + "onFailure:block requires a synchronous hook that supports blocking in {}", + source.path.display() + ), + warnings, + ); + continue; + } let expected_app_connector_id = source.plugin_id.as_deref().and_then(|plugin_id| { bundled_hook_app_connector_id( plugin_id, @@ -664,6 +686,7 @@ fn append_matcher_groups( timeout_sec, r#async, status_message, + on_failure, additional_context_limit, } => { let command = if cfg!(windows) { @@ -718,6 +741,7 @@ fn append_matcher_groups( timeout_sec: Some(timeout_sec), r#async, status_message: status_message.clone(), + on_failure, additional_context_limit: normalized_additional_context_limit, }; let command = source.env.iter().fold(command, |command, (key, value)| { @@ -741,6 +765,7 @@ fn append_matcher_groups( input, timeout_sec, status_message, + on_failure, } => { if event_name == HookEventName::SessionEnd { source.record_load_failure( @@ -775,6 +800,7 @@ fn append_matcher_groups( input: input.clone(), timeout_sec: Some(timeout_sec), status_message: status_message.clone(), + on_failure, }; NormalizedHandler { config, @@ -940,6 +966,7 @@ fn append_matcher_groups( matcher: compiled_matcher.clone(), timeout_sec, status_message, + on_failure: on_failure.unwrap_or_default(), additional_context_limit: AdditionalContextLimit::from_config( additional_context_limit, ), @@ -1199,6 +1226,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], } @@ -1215,6 +1243,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: Some(additional_context_limit), }], } @@ -1249,6 +1278,7 @@ mod tests { input, timeout_sec: Some(30), status_message: Some("Scanning file".to_string()), + on_failure: None, }], }], ); @@ -1290,6 +1320,7 @@ mod tests { input: serde_json::Map::new(), timeout_sec: None, status_message: None, + on_failure: None, }], }], ); @@ -1330,6 +1361,7 @@ mod tests { input: serde_json::Map::new(), timeout_sec: None, status_message: None, + on_failure: None, }, HookHandlerConfig::McpTool { server: "security".to_string(), @@ -1337,6 +1369,7 @@ mod tests { input: serde_json::Map::new(), timeout_sec: Some(600), status_message: None, + on_failure: None, }, ], }], @@ -1395,6 +1428,52 @@ mod tests { (handlers.remove(0), entries.remove(0), warnings) } + #[test] + fn failure_policy_is_preserved_in_discovery_and_trust_hashes() { + for mut hook in [ + serde_json::json!({"type": "command", "command": "echo hello"}), + serde_json::json!({"type": "mcp_tool", "server": "scanner", "tool": "check"}), + ] { + let source_path = source_path(); + let hook_states = std::collections::HashMap::new(); + let mut handlers = Vec::new(); + let mut entries = Vec::new(); + let mut warnings = Vec::new(); + let mut display_order = 0; + for policy in [None, Some("continue"), Some("block")] { + if let Some(policy) = policy { + hook["onFailure"] = serde_json::json!(policy); + } + append_matcher_groups( + &mut handlers, + &mut entries, + &mut warnings, + &mut display_order, + &mut hook_handler_source(&source_path, &hook_states), + HookEventName::PreToolUse, + vec![MatcherGroup { + matcher: None, + hooks: vec![serde_json::from_value(hook.clone()).expect("hook")], + }], + ); + } + assert!(warnings.is_empty()); + assert_eq!( + handlers + .iter() + .map(|handler| handler.on_failure) + .collect::>(), + vec![ + codex_config::HookFailurePolicy::Continue, + codex_config::HookFailurePolicy::Continue, + codex_config::HookFailurePolicy::Block, + ] + ); + assert_ne!(entries[0].current_hash, entries[2].current_hash); + assert_ne!(entries[1].current_hash, entries[2].current_hash); + } + } + #[test] fn supported_events_retain_per_handler_additional_context_limit_and_hash_it() { for event_name in [ @@ -1484,6 +1563,7 @@ mod tests { matcher: None, timeout_sec: 600, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: source_path.clone().into(), source: hook_source(), @@ -1525,6 +1605,7 @@ mod tests { matcher: Some(HookMatcher::new("^Bash$").expect("valid matcher")), timeout_sec: 600, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: source_path.clone().into(), source: hook_source(), @@ -1563,6 +1644,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }, HookHandlerConfig::Command { @@ -1571,6 +1653,7 @@ mod tests { timeout_sec: Some(600), r#async: true, status_message: None, + on_failure: None, additional_context_limit: None, }, ], @@ -1653,6 +1736,7 @@ mod tests { timeout_sec: Some(600), r#async: true, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -1844,6 +1928,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -1875,6 +1960,7 @@ mod tests { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], diff --git a/codex-rs/hooks/src/engine/dispatcher.rs b/codex-rs/hooks/src/engine/dispatcher.rs index 2dc70c78ae..905c6444e3 100644 --- a/codex-rs/hooks/src/engine/dispatcher.rs +++ b/codex-rs/hooks/src/engine/dispatcher.rs @@ -412,6 +412,7 @@ mod tests { .map(|pattern| crate::engine::HookMatcher::new(pattern).expect("valid matcher")), timeout_sec: 5, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: HookSource::User, diff --git a/codex-rs/hooks/src/engine/failure_policy_tests.rs b/codex-rs/hooks/src/engine/failure_policy_tests.rs new file mode 100644 index 0000000000..672418a6e0 --- /dev/null +++ b/codex-rs/hooks/src/engine/failure_policy_tests.rs @@ -0,0 +1,482 @@ +//! Regression coverage for opt-in failure blocking through managed hook discovery and execution. + +use super::*; +use crate::PermissionRequestDecision; +use crate::PermissionRequestRequest; +use crate::PostCompactRequest; +use crate::PostToolUseRequest; +use crate::PreCompactRequest; +use crate::SessionStartRequest; +use crate::SessionStartSource; +use crate::StartHookTarget; +use crate::StopHookTarget; +use crate::UserPromptSubmitRequest; +use codex_protocol::protocol::HookCompletedEvent; +use pretty_assertions::assert_eq; +use serde_json::Value; +use serde_json::json; + +const MCP_EVENTS: [HookEventName; 11] = [ + HookEventName::PreToolUse, + HookEventName::PermissionRequest, + HookEventName::PostToolUse, + HookEventName::PreCompact, + HookEventName::PostCompact, + HookEventName::SessionStart, + HookEventName::UserPromptSubmit, + HookEventName::SubagentStart, + HookEventName::SubagentStop, + HookEventName::Stop, + HookEventName::Interrupt, +]; + +#[derive(Clone, Copy)] +struct McpResult(Result<&'static str, &'static str>); + +impl HookMcpExecutor for McpResult { + fn execute(&self, _call: HookMcpCall) -> BoxFuture<'_, anyhow::Result> { + async move { + match self.0 { + Ok(text) => Ok(HookMcpOutput { + text: text.to_string(), + structured_content: None, + source_tool_namespace: None, + }), + Err(error) => anyhow::bail!(error), + } + } + .boxed() + } +} + +fn engine(event: HookEventName, handlers: Vec, output: McpResult) -> ClaudeHooksEngine { + let hooks = serde_json::from_value(json!({ + format!("{event:?}"): [{ "hooks": handlers }], + })) + .expect("managed hooks"); + let stack = required_hooks_stack( + ManagedHooksRequirementsToml { + hooks, + ..Default::default() + }, + RequirementSource::LegacyManagedConfigTomlFromMdm, + ); + ClaudeHooksEngine::new( + /*enabled*/ true, + /*bypass_hook_trust*/ false, + Some(&stack), + Vec::new(), + Vec::new(), + command_runtime(CommandShell { + program: "missing-hook-shell-for-test".to_string(), + args: Vec::new(), + }), + Arc::new(output), + ) +} + +async fn run(engine: &ClaudeHooksEngine, event: HookEventName) -> (bool, Vec) { + match event { + HookEventName::PreToolUse => { + let outcome = engine + .run_pre_tool_use(PreToolUseRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd(), + tool_cwd: None, + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + tool_name: "Bash".to_string(), + matcher_aliases: Vec::new(), + tool_use_id: "call".to_string(), + tool_input: json!({ "command": "echo hello" }), + }) + .await; + assert_eq!(outcome.updated_input, None); + (outcome.should_block, outcome.hook_events) + } + HookEventName::PermissionRequest => { + let outcome = engine + .run_permission_request(PermissionRequestRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd().to_path_buf(), + tool_cwd: None, + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + tool_name: "Bash".to_string(), + matcher_aliases: Vec::new(), + run_id_suffix: "call".to_string(), + tool_input: json!({ "command": "echo hello" }), + }) + .await; + ( + matches!( + outcome.decision, + Some(PermissionRequestDecision::Deny { .. }) + ), + outcome.hook_events, + ) + } + HookEventName::PostToolUse => { + let outcome = engine + .run_post_tool_use(PostToolUseRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd(), + tool_cwd: None, + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + tool_name: "Bash".to_string(), + matcher_aliases: Vec::new(), + tool_use_id: "call".to_string(), + tool_input: json!({"command": "echo hello"}), + tool_response: json!("hello"), + }) + .await; + assert_eq!(outcome.should_block, outcome.feedback_message.is_some()); + (outcome.should_block, outcome.hook_events) + } + HookEventName::UserPromptSubmit => { + let outcome = engine + .run_user_prompt_submit(UserPromptSubmitRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + prompt: "hello".to_string(), + }) + .await; + assert_eq!(outcome.should_stop, outcome.stop_reason.is_some()); + (outcome.should_stop, outcome.hook_events) + } + HookEventName::SessionStart | HookEventName::SubagentStart => { + let target = if event == HookEventName::SessionStart { + StartHookTarget::SessionStart { + source: SessionStartSource::Startup, + } + } else { + StartHookTarget::SubagentStart { + turn_id: "turn".to_string(), + agent_id: "agent".to_string(), + agent_type: "default".to_string(), + } + }; + let outcome = engine + .run_session_start( + SessionStartRequest { + session_id: ThreadId::new(), + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + target, + }, + Some("turn".to_string()), + ) + .await; + assert_eq!(outcome.should_stop, outcome.stop_reason.is_some()); + (outcome.should_stop, outcome.hook_events) + } + HookEventName::PreCompact => { + let outcome = engine + .run_pre_compact(PreCompactRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + trigger: "manual".to_string(), + }) + .await; + assert_eq!(outcome.should_stop, outcome.stop_reason.is_some()); + (outcome.should_stop, outcome.hook_events) + } + HookEventName::PostCompact => { + let outcome = engine + .run_post_compact(PostCompactRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + subagent: None, + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + trigger: "manual".to_string(), + }) + .await; + assert_eq!(outcome.should_stop, outcome.stop_reason.is_some()); + (outcome.should_stop, outcome.hook_events) + } + HookEventName::Stop | HookEventName::SubagentStop => { + let target = if event == HookEventName::Stop { + StopHookTarget::Stop + } else { + StopHookTarget::SubagentStop { + agent_id: "agent".to_string(), + agent_type: "default".to_string(), + agent_transcript_path: None, + } + }; + let outcome = engine + .run_stop(StopRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + request_metadata: None, + stop_hook_active: false, + last_assistant_message: None, + target, + }) + .await; + assert_eq!( + outcome.should_block, + !outcome.continuation_fragments.is_empty() + ); + (outcome.should_block, outcome.hook_events) + } + HookEventName::Interrupt => { + let outcome = engine + .run_interrupt(InterruptRequest { + session_id: ThreadId::new(), + turn_id: "turn".to_string(), + cwd: cwd(), + transcript_path: None, + model: "test".to_string(), + permission_mode: "default".to_string(), + request_metadata: None, + }) + .await; + // Cancellation has already happened; only the hook lifecycle status changes. + ( + outcome + .hook_events + .iter() + .any(|event| event.run.status == HookRunStatus::Blocked), + outcome.hook_events, + ) + } + HookEventName::SessionEnd + | HookEventName::PreModelRequest + | HookEventName::PostModelRequest => { + unreachable!("event does not support blocking MCP hooks") + } + } +} + +#[tokio::test] +async fn mcp_failures_block_only_when_opted_in() { + for event in MCP_EVENTS { + for policy in [None, Some("continue"), Some("block")] { + for output in [ + McpResult(Err("MCP tool returned an error")), + McpResult(Err("MCP server disconnected")), + McpResult(Err("MCP request timed out")), + McpResult(Ok("{invalid json")), + McpResult(Ok(r#"{"continue":false}"#)), + McpResult(Ok("{}")), + McpResult(Ok("")), + McpResult(Ok("hook finished")), + ] { + if output.0 == Ok(r#"{"continue":false}"#) + && !matches!( + event, + HookEventName::PreToolUse | HookEventName::PermissionRequest + ) + { + continue; + } + let mut handler = json!({"type": "mcp_tool", "server": "scanner", "tool": "check"}); + if let Some(policy) = policy { + handler["onFailure"] = json!(policy); + } + let engine = engine(event, vec![handler], output); + assert!(engine.required_load_errors().is_empty()); + let (blocked, events) = run(&engine, event).await; + let failed = match output.0 { + Ok("{}" | "") => false, + Ok("hook finished") => matches!( + event, + HookEventName::Stop + | HookEventName::SubagentStop + | HookEventName::Interrupt + ), + _ => true, + }; + let expected_block = failed && policy == Some("block"); + assert_eq!( + blocked, expected_block, + "{event:?} {policy:?} {:?}", + output.0 + ); + assert_eq!(events.len(), 1); + assert_eq!( + events[0].run.status, + if expected_block { + HookRunStatus::Blocked + } else if failed { + HookRunStatus::Failed + } else { + HookRunStatus::Completed + } + ); + assert_eq!( + events[0] + .run + .entries + .iter() + .any(|entry| entry.kind == HookOutputEntryKind::Error), + failed + ); + } + } + } +} + +#[tokio::test] +async fn command_start_failure_obeys_policy() { + for event in MCP_EVENTS { + for policy in ["continue", "block"] { + let engine = engine( + event, + vec![json!({ + "type": "command", "command": "echo hello", "onFailure": policy, + })], + McpResult(Ok("{}")), + ); + assert!(engine.required_load_errors().is_empty()); + let (blocked, events) = run(&engine, event).await; + assert_eq!(blocked, policy == "block"); + assert!( + events[0] + .run + .entries + .iter() + .any(|entry| entry.kind == HookOutputEntryKind::Error) + ); + } + } +} + +#[cfg(unix)] +#[tokio::test] +async fn command_exit_timeout_and_invalid_output_obey_policy() { + for event in MCP_EVENTS { + for policy in ["continue", "block"] { + for (command, failed) in [ + ("exit 1", true), + ("exit 2", true), + ("printf '{invalid'", true), + ("sleep 10", true), + ("exit 0", false), + ] { + let mut engine = engine( + event, + vec![json!({ + "type": "command", "command": command, "onFailure": policy, "timeout": 1, + })], + McpResult(Ok("{}")), + ); + engine.command_runtime = command_runtime(CommandShell { + program: "sh".to_string(), + args: vec!["-c".to_string()], + }); + let (blocked, events) = run(&engine, event).await; + assert_eq!( + blocked, + failed && policy == "block", + "{event:?} {policy} {command}" + ); + assert_eq!( + events[0] + .run + .entries + .iter() + .any(|entry| entry.kind == HookOutputEntryKind::Error), + failed + ); + } + } + } +} + +#[tokio::test] +async fn failure_block_cannot_be_overridden_by_a_successful_hook() { + for event in MCP_EVENTS { + let engine = engine( + event, + vec![ + json!({ "type": "command", "command": "echo hello", "onFailure": "block" }), + json!({ "type": "mcp_tool", "server": "scanner", "tool": "check" }), + ], + McpResult(Ok(if event == HookEventName::PermissionRequest { + r#"{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}"# + } else if event == HookEventName::PreToolUse { + r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"echo rewritten"}}}"# + } else { + "{}" + })), + ); + let (blocked, events) = run(&engine, event).await; + assert!(blocked); + assert_eq!(events.len(), 2); + assert_eq!(events[1].run.status, HookRunStatus::Completed); + } +} + +#[test] +fn managed_hooks_reject_failure_blocking_that_cannot_be_enforced() { + for (event, mut handler) in MCP_EVENTS + .into_iter() + .map(|event| { + ( + event, + json!({"type": "command", "command": "echo hello", "async": true}), + ) + }) + .chain([ + ( + HookEventName::SessionEnd, + json!({"type": "command", "command": "echo hello"}), + ), + ( + HookEventName::SessionEnd, + json!({"type": "mcp_tool", "server": "scanner", "tool": "check"}), + ), + ]) + .chain( + [ + HookEventName::PreModelRequest, + HookEventName::PostModelRequest, + ] + .into_iter() + .flat_map(|event| { + [ + json!({"type": "command", "command": "echo hello"}), + json!({"type": "mcp_tool", "server": "scanner", "tool": "check"}), + ] + .map(|handler| (event, handler)) + }), + ) + { + handler["onFailure"] = json!("block"); + let engine = engine(event, vec![handler], McpResult(Ok("{}"))); + assert!(engine.handlers.is_empty()); + assert_eq!(engine.required_load_errors().len(), 1); + assert!( + engine.required_load_errors()[0].contains("onFailure:block requires a synchronous") + ); + } +} diff --git a/codex-rs/hooks/src/engine/mcp_runner_tests.rs b/codex-rs/hooks/src/engine/mcp_runner_tests.rs index 1830ab6ac4..19a1eae40b 100644 --- a/codex-rs/hooks/src/engine/mcp_runner_tests.rs +++ b/codex-rs/hooks/src/engine/mcp_runner_tests.rs @@ -102,6 +102,7 @@ async fn mcp_tool_results_use_command_hook_output_contract() { matcher: None, timeout_sec: 30, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: HookSource::User, diff --git a/codex-rs/hooks/src/engine/mod.rs b/codex-rs/hooks/src/engine/mod.rs index 73f2b4df64..8598f79b29 100644 --- a/codex-rs/hooks/src/engine/mod.rs +++ b/codex-rs/hooks/src/engine/mod.rs @@ -33,6 +33,7 @@ use crate::events::user_prompt_submit::UserPromptSubmitRequest; use crate::mcp::HookMcpExecutor; use crate::output_spill::AdditionalContextLimit; use codex_config::ConfigLayerStack; +use codex_config::HookFailurePolicy; use codex_config::HookHandlerConfig; use codex_plugin::ExecutorPluginHookSource; use codex_plugin::PluginHookSource; @@ -70,6 +71,7 @@ pub(crate) struct ConfiguredHandler { pub matcher: Option, pub timeout_sec: u64, pub status_message: Option, + pub on_failure: HookFailurePolicy, pub additional_context_limit: AdditionalContextLimit, pub source_path: HandlerSourcePath, pub source: HookSource, @@ -210,6 +212,18 @@ impl ConfiguredHandler { self.execution_mode() == HookExecutionMode::Sync } + pub(crate) fn failure_block_reason(&self) -> Option { + (self.on_failure == HookFailurePolicy::Block + && self.can_apply_control_effects() + && self.event_name != HookEventName::SessionEnd) + .then(|| { + format!( + "{:?} hook failed. This hook is configured to block continuation on failure.", + self.event_name + ) + }) + } + pub fn run_id(&self) -> String { format!( "{}:{}:{}", @@ -377,11 +391,27 @@ impl ClaudeHooksEngine { input, timeout_sec, status_message, + on_failure, } = handler else { unreachable!("allowlisted executor handler must be an MCP tool"); }; + let on_failure = match on_failure.unwrap_or_default() { + HookFailurePolicy::Continue => HookFailurePolicy::Continue, + HookFailurePolicy::Block => { + tracing::warn!( + plugin_id = %source.plugin_id.as_key(), + environment_id = %source.environment_id, + manifest_path = %source.manifest_path, + source_relative_path = %source.source_relative_path, + ?event_name, + "executor-scoped hooks always run asynchronously; ignoring unsupported onFailure:block and running cleanup with onFailure:continue" + ); + HookFailurePolicy::Continue + } + }; + // Bundled plugins can share a cleanup target; run it once per event // and MCP environment. let target = ( @@ -404,6 +434,7 @@ impl ClaudeHooksEngine { matcher: None, timeout_sec: timeout_sec.unwrap_or(5).max(1), status_message, + on_failure, additional_context_limit: Default::default(), source_path: HandlerSourcePath::ExecutorScoped { plugin_id: source.plugin_id.clone(), diff --git a/codex-rs/hooks/src/engine/mod_tests.rs b/codex-rs/hooks/src/engine/mod_tests.rs index 1b606f5753..23c48d15c3 100644 --- a/codex-rs/hooks/src/engine/mod_tests.rs +++ b/codex-rs/hooks/src/engine/mod_tests.rs @@ -56,6 +56,9 @@ use crate::mcp::HookMcpCall; use crate::mcp::HookMcpExecutor; use crate::mcp::HookMcpOutput; +#[path = "failure_policy_tests.rs"] +mod failure_policy; + fn cwd() -> AbsolutePathBuf { AbsolutePathBuf::current_dir().expect("current dir") } @@ -100,6 +103,7 @@ fn permission_request_timeout_only_counts_synchronous_handlers() { matcher: None, timeout_sec: 5, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: cwd().join("hooks.json").into(), source: HookSource::User, @@ -160,6 +164,7 @@ fn pre_tool_use_hook_events(command: impl Into) -> HookEventsToml { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -410,6 +415,7 @@ fn required_managed_mcp_hooks_reject_empty_targets() { input: Default::default(), timeout_sec: None, status_message: None, + on_failure: None, }], }], ..Default::default() @@ -450,6 +456,7 @@ fn required_managed_session_end_mcp_hooks_reject_startup() { input: Default::default(), timeout_sec: None, status_message: None, + on_failure: None, }], }], ..Default::default() @@ -588,6 +595,7 @@ with Path(r"{log_path}").open("a", encoding="utf-8") as handle: timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -701,6 +709,7 @@ async fn requirements_managed_hooks_execute_windows_command_override() { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -783,6 +792,7 @@ fn unknown_requirement_source_hooks_stay_managed() { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -854,6 +864,7 @@ fn user_disablement_filters_non_managed_hooks_but_not_managed_hooks() { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -1103,6 +1114,7 @@ fn requirements_managed_hooks_load_when_managed_dir_is_missing() { timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], @@ -1885,6 +1897,7 @@ fn bundled_cleanup_trust_does_not_extend_to_other_handlers() { input: Default::default(), timeout_sec: None, status_message: None, + on_failure: None, }, HookHandlerConfig::McpTool { server: "other_server".to_string(), @@ -1892,6 +1905,7 @@ fn bundled_cleanup_trust_does_not_extend_to_other_handlers() { input: Default::default(), timeout_sec: None, status_message: None, + on_failure: None, }, HookHandlerConfig::Command { command: "echo cleanup".to_string(), @@ -1899,6 +1913,7 @@ fn bundled_cleanup_trust_does_not_extend_to_other_handlers() { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }, ]); @@ -1976,6 +1991,7 @@ fn local_hosted_app_cleanup_hooks_require_saved_trust() { input: Default::default(), timeout_sec: None, status_message: None, + on_failure: None, }; let discovered = super::discovery::discover_handlers( /*config_layer_stack*/ None, @@ -2074,6 +2090,7 @@ fn disabled_hooks_feature_keeps_builtin_cleanup_but_not_trusted_plugin_hooks() { timeout_sec: None, r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }); let stack = trusted_plugin_hook_stack(cwd().join("config.toml"), &[source.clone()]); @@ -2143,6 +2160,7 @@ print(json.dumps({ timeout_sec: Some(10), r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -2270,6 +2288,7 @@ fn plugin_hook_sources_expand_plugin_placeholders() { timeout_sec: Some(5), r#async: false, status_message: None, + on_failure: None, additional_context_limit: None, }], }], @@ -2418,6 +2437,7 @@ fn executor_stop_hook_fixture() -> ( .expect("executor hook input"), timeout_sec: None, status_message: None, + on_failure: None, }], }], ..Default::default() @@ -2433,6 +2453,7 @@ fn executor_stop_hook_fixture() -> ( matcher: None, timeout_sec: 5, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: HandlerSourcePath::ExecutorScoped { plugin_id: PluginId::parse("computer-use@openai-bundled").expect("valid plugin ID"), @@ -2504,6 +2525,43 @@ async fn wait_for_mcp_calls(calls: &Arc>>, count: usize) .expect("executor hook should complete in the background"); } +#[tokio::test] +async fn executor_stop_hooks_normalize_blocking_policy_without_dropping_cleanup() { + let (_, _, _, _, source) = executor_stop_hook_fixture(); + let valid_group = source.hooks.stop[0].clone(); + let mut blocking_group = valid_group.clone(); + let HookHandlerConfig::McpTool { on_failure, .. } = &mut blocking_group.hooks[0] else { + panic!("expected an MCP tool hook"); + }; + *on_failure = Some(super::HookFailurePolicy::Block); + assert!(codex_plugin::is_allowlisted_bundled_cleanup_hook( + &source.plugin_id.as_key(), + HookEventName::Stop, + /*matcher*/ None, + &blocking_group.hooks[0], + /*app_connector_id*/ None, + )); + + let mut mixed_group = blocking_group.clone(); + mixed_group.hooks.extend(valid_group.hooks.clone()); + for groups in [ + vec![blocking_group.clone()], + vec![mixed_group], + vec![blocking_group, valid_group], + ] { + let (mut engine, calls, request, expected_call, mut source) = executor_stop_hook_fixture(); + let expected_handlers = Arc::clone(&engine.handlers); + source.hooks.stop = groups; + engine.set_executor_hooks(vec![source]); + assert_eq!(engine.handlers, expected_handlers); + + let outcome = engine.run_stop(request).await; + assert!(!outcome.should_block); + wait_for_mcp_calls(&calls, /*count*/ 1).await; + assert_eq!(*calls.lock().expect("lock MCP calls"), vec![expected_call]); + } +} + #[tokio::test] async fn subagent_stop_paths_are_scoped_to_each_hook() { let (mut engine, calls, mut request, _, _) = executor_stop_hook_fixture(); @@ -2599,6 +2657,7 @@ async fn executor_stop_hooks_run_unless_regular_hooks_block_without_stopping() { matcher: None, timeout_sec: 30, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: cwd().join("hooks.json").into(), source: HookSource::User, @@ -2638,6 +2697,7 @@ async fn executor_stop_hooks_run_unless_regular_hooks_block_without_stopping() { matcher: None, timeout_sec: 30, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: cwd().join("hooks.json").into(), source: HookSource::User, diff --git a/codex-rs/hooks/src/events/common.rs b/codex-rs/hooks/src/events/common.rs index 1d1bcb6692..9c5761bf8d 100644 --- a/codex-rs/hooks/src/events/common.rs +++ b/codex-rs/hooks/src/events/common.rs @@ -71,6 +71,33 @@ pub(crate) fn flatten_additional_contexts<'a>( additional_contexts.into_iter().flatten().cloned().collect() } +/// Preserve failure diagnostics while applying the handler's opt-in blocking policy. +pub(crate) fn apply_failure_policy( + handler: &ConfiguredHandler, + status: &mut HookRunStatus, + entries: &mut Vec, +) -> Option { + if *status != HookRunStatus::Failed { + return None; + } + let reason = handler.failure_block_reason()?; + *status = HookRunStatus::Blocked; + entries.push(HookOutputEntry { + kind: HookOutputEntryKind::Feedback, + text: reason.clone(), + }); + Some(reason) +} + +pub(crate) fn failure_block_reason(hook_events: &[HookCompletedEvent]) -> Option { + hook_events + .iter() + .filter(|event| event.run.status == HookRunStatus::Blocked) + .flat_map(|event| &event.run.entries) + .find(|entry| entry.kind == HookOutputEntryKind::Feedback) + .map(|entry| entry.text.clone()) +} + pub(crate) fn serialization_failure_hook_events( handlers: Vec, turn_id: Option, @@ -93,6 +120,7 @@ pub(crate) fn serialization_failure_hook_events( kind: HookOutputEntryKind::Error, text: error_message.clone(), }]; + apply_failure_policy(&handler, &mut run.status, &mut run.entries); HookCompletedEvent { turn_id: turn_id.clone(), run, diff --git a/codex-rs/hooks/src/events/compact.rs b/codex-rs/hooks/src/events/compact.rs index f07c4928e8..b090ecb704 100644 --- a/codex-rs/hooks/src/events/compact.rs +++ b/codex-rs/hooks/src/events/compact.rs @@ -90,14 +90,16 @@ pub(crate) async fn run_pre( let input = match pre_command_input(&request) { Ok(input) => input, Err(error) => { + let hook_events = common::serialization_failure_hook_events( + matched, + Some(request.turn_id), + format!("failed to serialize pre compact hook input: {error}"), + ); + let stop_reason = common::failure_block_reason(&hook_events); return PreCompactOutcome { - hook_events: common::serialization_failure_hook_events( - matched, - Some(request.turn_id), - format!("failed to serialize pre compact hook input: {error}"), - ), - should_stop: false, - stop_reason: None, + hook_events, + should_stop: stop_reason.is_some(), + stop_reason, }; } }; @@ -171,14 +173,16 @@ pub(crate) async fn run_post( let input = match post_command_input(&request) { Ok(input) => input, Err(error) => { + let hook_events = common::serialization_failure_hook_events( + matched, + Some(request.turn_id), + format!("failed to serialize post compact hook input: {error}"), + ); + let stop_reason = common::failure_block_reason(&hook_events); return StatelessHookOutcome { - hook_events: common::serialization_failure_hook_events( - matched, - Some(request.turn_id), - format!("failed to serialize post compact hook input: {error}"), - ), - should_stop: false, - stop_reason: None, + hook_events, + should_stop: stop_reason.is_some(), + stop_reason, }; } }; @@ -329,6 +333,11 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_stop = true; + stop_reason = Some(reason); + } + dispatcher::ParsedHandler { completed: HookCompletedEvent { turn_id, @@ -526,6 +535,7 @@ mod tests { matcher: None, timeout_sec: 5, status_message: Some("running compact hook".to_string()), + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/interrupt.rs b/codex-rs/hooks/src/events/interrupt.rs index 9d5817884d..84b039d156 100644 --- a/codex-rs/hooks/src/events/interrupt.rs +++ b/codex-rs/hooks/src/events/interrupt.rs @@ -171,6 +171,9 @@ fn parse_completed( }, } + // The turn is already interrupted; report the failure without resuming or undoing it. + common::apply_failure_policy(handler, &mut status, &mut entries); + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), diff --git a/codex-rs/hooks/src/events/interrupt_tests.rs b/codex-rs/hooks/src/events/interrupt_tests.rs index 7a54bf851f..3da9fa7bbb 100644 --- a/codex-rs/hooks/src/events/interrupt_tests.rs +++ b/codex-rs/hooks/src/events/interrupt_tests.rs @@ -104,6 +104,7 @@ fn handler() -> ConfiguredHandler { matcher: None, timeout_sec: 600, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/permission_request.rs b/codex-rs/hooks/src/events/permission_request.rs index e6e3c81032..f7e6d96c71 100644 --- a/codex-rs/hooks/src/events/permission_request.rs +++ b/codex-rs/hooks/src/events/permission_request.rs @@ -108,6 +108,10 @@ pub(crate) async fn run( let input = match serde_json::to_value(build_command_input(&request)) { Ok(input) => input, Err(error) => { + let decision = matched + .iter() + .find_map(ConfiguredHandler::failure_block_reason) + .map(|message| PermissionRequestDecision::Deny { message }); let hook_events = common::serialization_failure_hook_events_for_tool_use( matched, Some(request.turn_id.clone()), @@ -116,7 +120,7 @@ pub(crate) async fn run( ); return PermissionRequestOutcome { hook_events, - decision: None, + decision, }; } }; @@ -289,6 +293,10 @@ fn parse_completed( }, } + if let Some(message) = common::apply_failure_policy(handler, &mut status, &mut entries) { + decision = Some(PermissionRequestDecision::Deny { message }); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), diff --git a/codex-rs/hooks/src/events/post_tool_use.rs b/codex-rs/hooks/src/events/post_tool_use.rs index 32b501d71d..144d87611d 100644 --- a/codex-rs/hooks/src/events/post_tool_use.rs +++ b/codex-rs/hooks/src/events/post_tool_use.rs @@ -295,6 +295,11 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_block = true; + feedback_messages_for_model.push(reason); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), @@ -312,11 +317,12 @@ fn parse_completed( } fn serialization_failure_outcome(hook_events: Vec) -> PostToolUseOutcome { + let feedback_message = common::failure_block_reason(&hook_events); PostToolUseOutcome { hook_events, - should_block: false, + should_block: feedback_message.is_some(), additional_contexts: Vec::new(), - feedback_message: None, + feedback_message, } } @@ -616,6 +622,7 @@ mod tests { matcher: Some(crate::engine::HookMatcher::new("^Bash$").expect("valid matcher")), timeout_sec: 5, status_message: Some("running post tool use hook".to_string()), + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/pre_tool_use.rs b/codex-rs/hooks/src/events/pre_tool_use.rs index a07f0a60ff..2d8ad6aa7b 100644 --- a/codex-rs/hooks/src/events/pre_tool_use.rs +++ b/codex-rs/hooks/src/events/pre_tool_use.rs @@ -299,6 +299,11 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_block = true; + block_reason = Some(reason); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), @@ -317,10 +322,11 @@ fn parse_completed( } fn serialization_failure_outcome(hook_events: Vec) -> PreToolUseOutcome { + let block_reason = common::failure_block_reason(&hook_events); PreToolUseOutcome { hook_events, - should_block: false, - block_reason: None, + should_block: block_reason.is_some(), + block_reason, additional_contexts: Vec::new(), updated_input: None, } @@ -786,6 +792,25 @@ mod tests { assert_eq!(completed.len(), 1); assert_eq!(completed[0].run.id, runs[0].id); + + let mut handler = handler(); + handler.on_failure = codex_config::HookFailurePolicy::Block; + let completed = common::serialization_failure_hook_events_for_tool_use( + vec![handler], + Some(request.turn_id.clone()), + "serialize failed".into(), + &request.tool_use_id, + ); + let outcome = super::serialization_failure_outcome(completed); + assert!(outcome.should_block); + assert_eq!( + outcome.block_reason, + Some( + "PreToolUse hook failed. This hook is configured to block continuation on failure." + .to_string() + ) + ); + assert_eq!(outcome.hook_events[0].run.status, HookRunStatus::Blocked); } fn handler() -> ConfiguredHandler { @@ -800,6 +825,7 @@ mod tests { matcher: Some(crate::engine::HookMatcher::new("^Bash$").expect("valid matcher")), timeout_sec: 5, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/session_end_tests.rs b/codex-rs/hooks/src/events/session_end_tests.rs index fd63ccf8bf..d3fbab02ea 100644 --- a/codex-rs/hooks/src/events/session_end_tests.rs +++ b/codex-rs/hooks/src/events/session_end_tests.rs @@ -69,6 +69,7 @@ fn handler(matcher: Option<&str>) -> ConfiguredHandler { .map(|pattern| crate::engine::HookMatcher::new(pattern).expect("valid matcher")), timeout_sec: 2, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: HookSource::User, diff --git a/codex-rs/hooks/src/events/session_start.rs b/codex-rs/hooks/src/events/session_start.rs index 1c5cab9ce9..de026341fb 100644 --- a/codex-rs/hooks/src/events/session_start.rs +++ b/codex-rs/hooks/src/events/session_start.rs @@ -330,6 +330,11 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_stop = true; + stop_reason = Some(reason); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), @@ -347,10 +352,11 @@ fn parse_completed( } fn serialization_failure_outcome(hook_events: Vec) -> SessionStartOutcome { + let stop_reason = common::failure_block_reason(&hook_events); SessionStartOutcome { hook_events, - should_stop: false, - stop_reason: None, + should_stop: stop_reason.is_some(), + stop_reason, additional_contexts: Vec::new(), } } @@ -550,6 +556,7 @@ mod tests { matcher: None, timeout_sec: 600, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/stop.rs b/codex-rs/hooks/src/events/stop.rs index 78bdd3c76d..f43f902351 100644 --- a/codex-rs/hooks/src/events/stop.rs +++ b/codex-rs/hooks/src/events/stop.rs @@ -371,6 +371,12 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_block = true; + block_reason = Some(reason.clone()); + continuation_prompt = Some(reason); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), @@ -435,13 +441,26 @@ fn aggregate_results<'a>( } fn serialization_failure_outcome(hook_events: Vec) -> StopOutcome { + let block_reason = common::failure_block_reason(&hook_events); + let continuation_fragments = hook_events + .iter() + .filter(|event| event.run.status == HookRunStatus::Blocked) + .map(|event| HookPromptFragment { + text: format!( + "{:?} hook failed. This hook is configured to block continuation on failure.", + event.run.event_name + ), + hook_run_id: event.run.id.clone(), + metadata: codex_protocol::models::ContentItemMetadata::harness(), + }) + .collect(); StopOutcome { hook_events, should_stop: false, stop_reason: None, - should_block: false, - block_reason: None, - continuation_fragments: Vec::new(), + should_block: block_reason.is_some(), + block_reason, + continuation_fragments, } } @@ -688,6 +707,7 @@ mod tests { matcher: None, timeout_sec: 600, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/hooks/src/events/user_prompt_submit.rs b/codex-rs/hooks/src/events/user_prompt_submit.rs index 476b5953ae..934d00a875 100644 --- a/codex-rs/hooks/src/events/user_prompt_submit.rs +++ b/codex-rs/hooks/src/events/user_prompt_submit.rs @@ -260,6 +260,11 @@ fn parse_completed( }, } + if let Some(reason) = common::apply_failure_policy(handler, &mut status, &mut entries) { + should_stop = true; + stop_reason = Some(reason); + } + let completed = HookCompletedEvent { turn_id, run: dispatcher::completed_summary(handler, &run_result, status, entries), @@ -277,10 +282,11 @@ fn parse_completed( } fn serialization_failure_outcome(hook_events: Vec) -> UserPromptSubmitOutcome { + let stop_reason = common::failure_block_reason(&hook_events); UserPromptSubmitOutcome { hook_events, - should_stop: false, - stop_reason: None, + should_stop: stop_reason.is_some(), + stop_reason, additional_contexts: Vec::new(), } } @@ -469,6 +475,7 @@ mod tests { matcher: None, timeout_sec: 5, status_message: None, + on_failure: Default::default(), additional_context_limit: Default::default(), source_path: test_path_buf("/tmp/hooks.json").abs().into(), source: codex_protocol::protocol::HookSource::User, diff --git a/codex-rs/protocol/src/hooks.rs b/codex-rs/protocol/src/hooks.rs index 20bd7910d1..4a5e33487a 100644 --- a/codex-rs/protocol/src/hooks.rs +++ b/codex-rs/protocol/src/hooks.rs @@ -159,6 +159,10 @@ pub enum HookHandlerConfig { r#async: bool, #[serde(default, rename = "statusMessage")] status_message: Option, + /// Failure policy for synchronous hooks that support blocking. + /// Defaults to continue; block applies the event's blocking behavior on failure. + #[serde(default, rename = "onFailure", skip_serializing_if = "Option::is_none")] + on_failure: Option, /// Approximate token threshold for spilling this hook's `additionalContext` to disk. /// Unset uses 2,500 tokens; `0` disables spilling for this hook. The threshold is /// evaluated against the original context; a spilled preview also includes recovery @@ -180,6 +184,10 @@ pub enum HookHandlerConfig { timeout_sec: Option, #[serde(default, rename = "statusMessage")] status_message: Option, + /// Failure policy for MCP hooks that support blocking. + /// Defaults to continue; block applies the event's blocking behavior on failure. + #[serde(default, rename = "onFailure", skip_serializing_if = "Option::is_none")] + on_failure: Option, }, #[serde(rename = "prompt")] Prompt {}, @@ -187,6 +195,14 @@ pub enum HookHandlerConfig { Agent {}, } +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "camelCase")] +pub enum HookFailurePolicy { + #[default] + Continue, + Block, +} + // Reject values such as null that cannot be represented in TOML for trust hashing. fn deserialize_mcp_tool_input<'de, D>( deserializer: D, diff --git a/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hook_blocked_failed_feedback_history_snapshot.snap b/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hook_blocked_failed_feedback_history_snapshot.snap index 17a3b42f38..e6ce5b46ae 100644 --- a/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hook_blocked_failed_feedback_history_snapshot.snap +++ b/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hook_blocked_failed_feedback_history_snapshot.snap @@ -7,3 +7,7 @@ expression: rendered • Hook failed └ hook exited with code 7 + +• Blocked by hook + └ hook exited with code 7 + └ PreToolUse hook failed. This hook is configured to block continuation on failure. diff --git a/codex-rs/tui/src/chatwidget/tests/status_and_layout.rs b/codex-rs/tui/src/chatwidget/tests/status_and_layout.rs index fdc8c4758b..dd4545ed08 100644 --- a/codex-rs/tui/src/chatwidget/tests/status_and_layout.rs +++ b/codex-rs/tui/src/chatwidget/tests/status_and_layout.rs @@ -5536,6 +5536,25 @@ async fn blocked_and_failed_hooks_render_feedback_and_errors() { ), ); + handle_hook_completed( + &mut chat, + hook_completed_run( + "pre-tool-use:2:/tmp/hooks.json", + codex_app_server_protocol::HookEventName::PreToolUse, + codex_app_server_protocol::HookRunStatus::Blocked, + vec![ + codex_app_server_protocol::HookOutputEntry { + kind: codex_app_server_protocol::HookOutputEntryKind::Error, + text: "hook exited with code 7".to_string(), + }, + codex_app_server_protocol::HookOutputEntry { + kind: codex_app_server_protocol::HookOutputEntryKind::Feedback, + text: "PreToolUse hook failed. This hook is configured to block continuation on failure.".to_string(), + }, + ], + ), + ); + let rendered = drain_insert_history(&mut rx) .iter() .map(|lines| lines_to_single_string(lines)) diff --git a/codex-rs/tui/src/debug_config.rs b/codex-rs/tui/src/debug_config.rs index de13958ec8..a7e285bd45 100644 --- a/codex-rs/tui/src/debug_config.rs +++ b/codex-rs/tui/src/debug_config.rs @@ -1417,6 +1417,7 @@ approval_policy = "never" timeout_sec: Some(10), r#async: false, status_message: Some("checking".to_string()), + on_failure: None, additional_context_limit: None, }], }], diff --git a/sdk/python/src/openai_codex/generated/v2_all.py b/sdk/python/src/openai_codex/generated/v2_all.py index 47aca3f14a..7e7e400f71 100644 --- a/sdk/python/src/openai_codex/generated/v2_all.py +++ b/sdk/python/src/openai_codex/generated/v2_all.py @@ -1032,6 +1032,11 @@ class ConfigReadParams(BaseModel): include_layers: Annotated[bool | None, Field(alias="includeLayers")] = None +class ConfiguredHookFailurePolicy(Enum): + continue_ = "continue" + block = "block" + + class CommandConfiguredHookHandler(BaseModel): model_config = ConfigDict( populate_by_name=True, @@ -1047,6 +1052,7 @@ class CommandConfiguredHookHandler(BaseModel): async_: Annotated[bool, Field(alias="async")] command: str command_windows: Annotated[str | None, Field(alias="commandWindows")] = None + on_failure: Annotated[ConfiguredHookFailurePolicy | None, Field(alias="onFailure")] = None status_message: Annotated[str | None, Field(alias="statusMessage")] = None timeout_sec: Annotated[int | None, Field(alias="timeoutSec", ge=0)] = None type: Annotated[Literal["command"], Field(title="CommandConfiguredHookHandlerType")] @@ -1057,6 +1063,7 @@ class McpToolConfiguredHookHandler(BaseModel): populate_by_name=True, ) input: dict[str, Any] + on_failure: Annotated[ConfiguredHookFailurePolicy | None, Field(alias="onFailure")] = None server: str status_message: Annotated[str | None, Field(alias="statusMessage")] = None timeout_sec: Annotated[int | None, Field(alias="timeoutSec", ge=0)] = None