Let required hooks block continuation on failure (#62831)

## Why

A required hook check can fail to run or return a usable result. Continuing
after that failure can let an action proceed without a completed check.

## What changed

Add per-handler `onFailure` for command and MCP tool hooks. The default
`continue` preserves existing behavior. On supported synchronous hooks,
`block` applies the event's blocking behavior and reports the reason while
preserving failure diagnostics. For example, a failed `PreToolUse` check
prevents the tool from running, while a failed `PostToolUse` check withholds
the result of a tool that already ran.

Expose the policy in the app-server's `configRequirements/read` response.

## Testing

Add tests for command and MCP failures under both policies, and scenario
coverage for blocked tool execution, withheld results, and completion after
a `Stop` hook recovers.

GitOrigin-RevId: 20d6ebda0094382fe052bbf34338edb994cc7bd3
This commit is contained in:
Ryan Taylor
2026-11-20 20:24:34 +00:00
committed by copyberry
parent 0a0b1021f0
commit a1afa12273
49 changed files with 1377 additions and 52 deletions
@@ -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"
},
@@ -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"
},
@@ -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"
},
@@ -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";
@@ -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", };
@@ -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";
@@ -738,6 +738,14 @@ pub struct ConfiguredHookMatcherGroup {
pub hooks: Vec<ConfiguredHookHandler>,
}
#[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<String>,
#[serde(rename = "onFailure")]
#[ts(rename = "onFailure")]
on_failure: Option<ConfiguredHookFailurePolicy>,
/// 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<String>,
#[serde(rename = "onFailure")]
#[ts(rename = "onFailure")]
on_failure: Option<ConfiguredHookFailurePolicy>,
},
#[serde(rename = "prompt")]
#[ts(rename = "prompt")]
@@ -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<SandboxMode> {
match mode {
CoreSandboxModeRequirement::ReadOnly => Some(SandboxMode::ReadOnly),
@@ -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),
},
]
);
@@ -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,
}],
},
+1
View File
@@ -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;
+21 -1
View File
@@ -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::<HookHandlerConfig>(handler).is_err());
}
}
+1
View File
@@ -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;
@@ -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();
+23
View File
@@ -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"
},
+2
View File
@@ -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)
{
+1
View File
@@ -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,
}],
},
+16 -3
View File
@@ -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);
+159 -16
View File
@@ -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<Vec<core_test_support::responses::ResponsesRequest>> {
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(())
+89
View File
@@ -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::<Vec<_>>();
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(),
"<CODEX_HOME>",
))?;
}
let entries = bodies.iter().map(SnapshotEntry::body).collect::<Vec<_>>();
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(()));
@@ -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:
<MODEL_INSTRUCTIONS>
01:message/developer[2]:
[01] <PERMISSIONS_INSTRUCTIONS>
[02] <tools>
Deferred tool namespaces:
- multi_agent_v1: Tools for spawning and managing sub-agents.
</tools>
02:message/user:
<ENVIRONMENT_CONTEXT>
03:message/user:
write a draft
-- request 2 (request) --
04:message/assistant:
initial draft
05:message/user:
<hook_prompt hook_run_id="stop:0:<CODEX_HOME>/hooks.json">Stop hook failed. This hook is configured to block continuation on failure.</hook_prompt>
@@ -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:
<MODEL_INSTRUCTIONS>
01:message/developer[2]:
[01] <PERMISSIONS_INSTRUCTIONS>
[02] <tools>
Deferred tool namespaces:
- mcp__rmcp: Use these tools to exercise the rmcp test server.
- multi_agent_v1: Tools for spawning and managing sub-agents.
</tools>
02:message/user:
<ENVIRONMENT_CONTEXT>
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
@@ -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:
<MODEL_INSTRUCTIONS>
01:message/developer[2]:
[01] <PERMISSIONS_INSTRUCTIONS>
[02] <tools>
Deferred tool namespaces:
- mcp__rmcp: Use these tools to exercise the rmcp test server.
- multi_agent_v1: Tools for spawning and managing sub-agents.
</tools>
02:message/user:
<ENVIRONMENT_CONTEXT>
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.
+1
View File
@@ -69,6 +69,7 @@ mod tests {
timeout_sec: None,
r#async: false,
status_message: None,
on_failure: None,
additional_context_limit: None,
},
],
@@ -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")
+86
View File
@@ -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<_>>(),
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,
}],
}],
+1
View File
@@ -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,
@@ -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<HookMcpOutput>> {
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<Value>, 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<HookCompletedEvent>) {
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")
);
}
}
@@ -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,
+31
View File
@@ -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<HookMatcher>,
pub timeout_sec: u64,
pub status_message: Option<String>,
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<String> {
(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(),
+60
View File
@@ -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<String>) -> 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<Mutex<Vec<HookMcpCall>>>, 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,
+28
View File
@@ -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<HookOutputEntry>,
) -> Option<String> {
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<String> {
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<ConfiguredHandler>,
turn_id: Option<String>,
@@ -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,
+24 -14
View File
@@ -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,
+3
View File
@@ -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),
@@ -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,
@@ -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),
+9 -2
View File
@@ -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<HookCompletedEvent>) -> 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,
+28 -2
View File
@@ -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<HookCompletedEvent>) -> 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,
@@ -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,
+9 -2
View File
@@ -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<HookCompletedEvent>) -> 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,
+23 -3
View File
@@ -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<HookCompletedEvent>) -> 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,
@@ -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<HookCompletedEvent>) -> 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,
+16
View File
@@ -159,6 +159,10 @@ pub enum HookHandlerConfig {
r#async: bool,
#[serde(default, rename = "statusMessage")]
status_message: Option<String>,
/// 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<HookFailurePolicy>,
/// 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<u64>,
#[serde(default, rename = "statusMessage")]
status_message: Option<String>,
/// 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<HookFailurePolicy>,
},
#[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,
@@ -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.
@@ -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))
+1
View File
@@ -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,
}],
}],
@@ -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