pub(crate) mod command_runner; pub(crate) mod discovery; pub(crate) mod dispatcher; mod matcher; pub(crate) mod mcp_runner; pub(crate) mod output_parser; mod plugin_fingerprint; mod plugin_trust; pub(crate) mod schema_loader; pub(crate) use matcher::HookMatcher; use crate::events::compact::PostCompactRequest; use crate::events::compact::PreCompactOutcome; use crate::events::compact::PreCompactRequest; use crate::events::compact::StatelessHookOutcome; use crate::events::interrupt::InterruptOutcome; use crate::events::interrupt::InterruptRequest; use crate::events::permission_request::PermissionRequestOutcome; use crate::events::permission_request::PermissionRequestRequest; use crate::events::post_tool_use::PostToolUseOutcome; use crate::events::post_tool_use::PostToolUseRequest; use crate::events::pre_tool_use::PreToolUseOutcome; use crate::events::pre_tool_use::PreToolUseRequest; use crate::events::session_end::SessionEndOutcome; use crate::events::session_end::SessionEndRequest; use crate::events::session_start::SessionStartOutcome; use crate::events::session_start::SessionStartRequest; use crate::events::stop::StopOutcome; use crate::events::stop::StopRequest; use crate::events::user_prompt_submit::UserPromptSubmitOutcome; 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; use codex_plugin::PluginId; use codex_protocol::protocol::HookEventName; use codex_protocol::protocol::HookExecutionMode; use codex_protocol::protocol::HookHandlerType; use codex_protocol::protocol::HookRunSummary; use codex_protocol::protocol::HookSource; use codex_protocol::protocol::HookTrustStatus; use codex_utils_absolute_path::AbsolutePathBuf; use codex_utils_path_uri::PathUri; use serde_json::Map; use serde_json::Value; use std::borrow::Cow; use std::collections::HashMap; use std::collections::HashSet; use std::sync::Arc; use std::time::Duration; use command_runner::CommandHookRuntime; #[derive(Debug, Clone)] pub(crate) struct CommandShell { pub program: String, pub args: Vec, } #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) struct ConfiguredHandler { /// Internally admitted bundled hook, enabled independently of per-hook state. pub builtin: bool, pub plugin_trust: Option, pub event_name: codex_protocol::protocol::HookEventName, 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, pub display_order: i64, pub kind: ConfiguredHandlerKind, } #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) enum HandlerSourcePath { Local(AbsolutePathBuf), Environment { environment_id: String, cwd: PathUri, source_path: PathUri, }, /// Executor-scoped handlers are currently excluded from user-visible hook reporting /// (events, summary, telemetry). Their handlers are always executed async. /// /// TODO: With CCA, all hooks will be executor-scoped, so user visibility /// (participation in lifecycle events and summaries) and execution behavior /// (non-blocking) will need to be determined independently. ExecutorScoped { plugin_id: PluginId, environment_id: String, mcp_environment_id: Option, mcp_metadata: Option>>, manifest_path: PathUri, source_relative_path: String, }, } impl HandlerSourcePath { /// Use the environment's working directory and withhold controller-owned transcript paths. fn event_input<'a>(&self, input: &'a Value) -> Cow<'a, Value> { match self { Self::Environment { cwd, .. } => { let mut input = input.clone(); input["cwd"] = Value::String(cwd.inferred_native_path_string()); input["transcript_path"] = Value::Null; if let Some(path) = input.get_mut("agent_transcript_path") { *path = Value::Null; } Cow::Owned(input) } Self::Local(_) | Self::ExecutorScoped { .. } => Cow::Borrowed(input), } } } impl From for HandlerSourcePath { fn from(path: AbsolutePathBuf) -> Self { Self::Local(path) } } impl std::fmt::Display for HandlerSourcePath { fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { Self::Local(path) => write!(formatter, "{}", path.display()), Self::Environment { source_path, .. } => { write!(formatter, "{}", source_path.inferred_native_path_string()) } Self::ExecutorScoped { environment_id, manifest_path, source_relative_path, .. } => write!( formatter, "{environment_id}:{manifest_path}:{source_relative_path}" ), } } } #[derive(Debug, Clone, PartialEq, Eq)] pub(crate) enum ConfiguredHandlerKind { Command { command: String, env: HashMap, r#async: bool, }, McpTool { expected_app_connector_id: Option<&'static str>, server: String, tool: String, input: serde_json::Map, }, } #[derive(Debug)] pub(crate) struct HandlerRunResult { pub structured_content: Option, pub context_metadata: codex_protocol::models::ContentItemMetadata, pub started_at: i64, pub completed_at: i64, pub duration_ms: i64, pub exit_code: Option, pub stdout: String, pub stderr: String, pub error: Option, } impl ConfiguredHandler { /// Internal memory work runs policy and executor hooks, not user or project hooks. pub(crate) fn runs_for_memory_consolidation(&self) -> bool { matches!(self.source_path, HandlerSourcePath::ExecutorScoped { .. }) || match self.source { HookSource::User | HookSource::Project | HookSource::SessionFlags | HookSource::Plugin => false, HookSource::System | HookSource::Mdm | HookSource::CloudRequirements | HookSource::CloudManagedConfig | HookSource::LegacyManagedConfigFile | HookSource::LegacyManagedConfigMdm // Required hooks can have unknown attribution; retain them fail-closed. | HookSource::Unknown => true, } } pub(crate) fn execution_mode(&self) -> HookExecutionMode { if matches!(self.source_path, HandlerSourcePath::ExecutorScoped { .. }) { return HookExecutionMode::Async; } match self.kind { ConfiguredHandlerKind::Command { r#async: true, .. } => HookExecutionMode::Async, ConfiguredHandlerKind::Command { r#async: false, .. } | ConfiguredHandlerKind::McpTool { .. } => HookExecutionMode::Sync, } } /// Only synchronous hooks can apply control effects. pub(crate) fn can_apply_control_effects(&self) -> bool { 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!( "{}:{}:{}", self.event_name_label(), self.display_order, self.source_path ) } fn event_name_label(&self) -> &'static str { match self.event_name { codex_protocol::protocol::HookEventName::PreToolUse => "pre-tool-use", codex_protocol::protocol::HookEventName::PermissionRequest => "permission-request", codex_protocol::protocol::HookEventName::PostToolUse => "post-tool-use", codex_protocol::protocol::HookEventName::PreCompact => "pre-compact", codex_protocol::protocol::HookEventName::PostCompact => "post-compact", codex_protocol::protocol::HookEventName::PreModelRequest => "pre-model-request", codex_protocol::protocol::HookEventName::PostModelRequest => "post-model-request", codex_protocol::protocol::HookEventName::SessionStart => "session-start", codex_protocol::protocol::HookEventName::SessionEnd => "session-end", codex_protocol::protocol::HookEventName::UserPromptSubmit => "user-prompt-submit", codex_protocol::protocol::HookEventName::SubagentStart => "subagent-start", codex_protocol::protocol::HookEventName::SubagentStop => "subagent-stop", codex_protocol::protocol::HookEventName::Stop => "stop", codex_protocol::protocol::HookEventName::Interrupt => "interrupt", } } fn handler_type(&self) -> HookHandlerType { match &self.kind { ConfiguredHandlerKind::Command { .. } => HookHandlerType::Command, ConfiguredHandlerKind::McpTool { .. } => HookHandlerType::McpTool, } } } #[derive(Debug, Clone, PartialEq, Eq)] pub enum HookListEntryHandler { Command { command: String, r#async: bool }, McpTool { server: String, tool: String }, } #[derive(Debug, Clone, PartialEq, Eq)] pub struct HookListEntry { /// Builtin hooks remain available internally but are omitted from the public hooks list. pub builtin: bool, pub key: String, pub event_name: HookEventName, pub handler: HookListEntryHandler, pub matcher: Option, pub timeout_sec: u64, pub status_message: Option, pub additional_context_limit: Option, pub source_path: AbsolutePathBuf, pub source: HookSource, pub plugin_id: Option, /// The owning execution environment, if this hook came from its requirements. pub environment_id: Option, pub display_order: i64, pub enabled: bool, pub is_managed: bool, pub current_hash: String, pub trust_status: HookTrustStatus, } #[derive(Clone)] pub(crate) struct ClaudeHooksEngine { pub(crate) enabled: bool, // Per-turn views share configuration; executor overlays copy handlers on mutation. pub(crate) handlers: Arc>, /// Retain the session inventory without copying it for every hook dispatch. pub(crate) hook_entries: Arc>, pub(crate) warnings: Arc<[String]>, required_load_errors: Arc<[String]>, pub(crate) command_runtime: CommandHookRuntime, pub(crate) mcp_executor: Arc, } impl ClaudeHooksEngine { pub(crate) fn new( enabled: bool, bypass_hook_trust: bool, config_layer_stack: Option<&ConfigLayerStack>, plugin_hook_sources: Vec, plugin_hook_load_warnings: Vec, command_runtime: CommandHookRuntime, mcp_executor: Arc, ) -> Self { if !enabled && plugin_hook_sources.is_empty() { return Self { enabled, handlers: Arc::default(), hook_entries: Arc::default(), warnings: Arc::default(), required_load_errors: Arc::default(), command_runtime, mcp_executor, }; } let _ = schema_loader::generated_hook_schemas(); let mut discovered = discovery::discover_handlers( config_layer_stack, plugin_hook_sources, plugin_hook_load_warnings, bypass_hook_trust, discovery::DiscoveryMode::Runtime, ); if !enabled { discovered.handlers.retain(|handler| handler.builtin); discovered.hook_entries.clear(); // Disabled ordinary hooks must not emit warnings or reject session startup. discovered.warnings.clear(); discovered.required_load_errors.clear(); } Self { enabled, handlers: Arc::new(discovered.handlers), hook_entries: Arc::new(discovered.hook_entries), warnings: discovered.warnings.into(), required_load_errors: discovered.required_load_errors.into(), command_runtime, mcp_executor, } } pub(crate) fn warnings(&self) -> &[String] { &self.warnings } pub(crate) fn set_executor_hooks(&mut self, executor_hooks: Vec) { if executor_hooks.is_empty() && !self.handlers.iter().any(|handler| { matches!( handler.source_path, HandlerSourcePath::ExecutorScoped { .. } ) }) { return; } let handlers = Arc::make_mut(&mut self.handlers); handlers.retain(|handler| { !matches!( handler.source_path, HandlerSourcePath::ExecutorScoped { .. } ) }); let mut display_order = handlers .iter() .map(|handler| handler.display_order) .max() .map_or(0, |display_order| display_order.saturating_add(1)); let mut seen_targets = HashSet::new(); for source in executor_hooks { for (event_name, groups) in source.hooks.into_matcher_groups() { let Some(handler) = groups.into_iter().flat_map(|group| group.hooks).next() else { continue; }; let HookHandlerConfig::McpTool { server, tool, 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 = ( std::mem::discriminant(&event_name), source .mcp_environment_id .as_ref() .unwrap_or(&source.environment_id) .clone(), server.clone(), tool.clone(), ); if !seen_targets.insert(target) { continue; } handlers.push(ConfiguredHandler { builtin: true, plugin_trust: None, event_name, 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(), environment_id: source.environment_id.clone(), mcp_environment_id: source.mcp_environment_id.clone(), mcp_metadata: source.mcp_metadata.clone().map(Box::new), manifest_path: source.manifest_path.clone(), source_relative_path: source.source_relative_path.clone(), }, source: HookSource::Plugin, display_order, kind: ConfiguredHandlerKind::McpTool { expected_app_connector_id: None, server, tool, input, }, }); display_order = display_order.saturating_add(1); } } } pub(crate) fn required_load_errors(&self) -> &[String] { &self.required_load_errors } pub(crate) fn preview_session_start( &self, request: &SessionStartRequest, ) -> Vec { crate::events::session_start::preview(&self.handlers, request) } pub(crate) fn preview_pre_tool_use(&self, request: &PreToolUseRequest) -> Vec { crate::events::pre_tool_use::preview(&self.handlers, request) } pub(crate) fn preview_permission_request( &self, request: &PermissionRequestRequest, ) -> Vec { crate::events::permission_request::preview(&self.handlers, request) } pub(crate) fn max_permission_request_timeout(&self) -> Duration { Duration::from_secs( self.handlers .iter() .filter(|handler| { handler.event_name == HookEventName::PermissionRequest && handler.can_apply_control_effects() }) .map(|handler| handler.timeout_sec) .max() .unwrap_or_default(), ) } pub(crate) fn preview_post_tool_use( &self, request: &PostToolUseRequest, ) -> Vec { crate::events::post_tool_use::preview(&self.handlers, request) } pub(crate) async fn run_session_start( &self, request: SessionStartRequest, turn_id: Option, ) -> SessionStartOutcome { crate::events::session_start::run(self, request, turn_id).await } pub(crate) async fn run_pre_tool_use(&self, request: PreToolUseRequest) -> PreToolUseOutcome { crate::events::pre_tool_use::run(self, request).await } pub(crate) async fn run_permission_request( &self, request: PermissionRequestRequest, ) -> PermissionRequestOutcome { crate::events::permission_request::run(self, request).await } pub(crate) async fn run_post_tool_use( &self, request: PostToolUseRequest, ) -> PostToolUseOutcome { let mut outcome = crate::events::post_tool_use::run(self, request).await; if let Some(feedback_message) = outcome.feedback_message.take() { outcome.feedback_message = Some( self.command_runtime .output_spiller() .maybe_spill_text(feedback_message) .await, ); } outcome } pub(crate) fn preview_pre_compact(&self, request: &PreCompactRequest) -> Vec { crate::events::compact::preview_pre(&self.handlers, request) } pub(crate) async fn run_pre_compact(&self, request: PreCompactRequest) -> PreCompactOutcome { crate::events::compact::run_pre(self, request).await } pub(crate) fn preview_post_compact(&self, request: &PostCompactRequest) -> Vec { crate::events::compact::preview_post(&self.handlers, request) } pub(crate) async fn run_post_compact( &self, request: PostCompactRequest, ) -> StatelessHookOutcome { crate::events::compact::run_post(self, request).await } pub(crate) fn preview_user_prompt_submit( &self, request: &UserPromptSubmitRequest, ) -> Vec { crate::events::user_prompt_submit::preview(&self.handlers, request) } pub(crate) async fn run_user_prompt_submit( &self, request: UserPromptSubmitRequest, ) -> UserPromptSubmitOutcome { crate::events::user_prompt_submit::run(self, request).await } pub(crate) fn preview_stop(&self, request: &StopRequest) -> Vec { crate::events::stop::preview(&self.handlers, request) } pub(crate) fn preview_session_end(&self) -> Vec { crate::events::session_end::preview(&self.handlers) } pub(crate) async fn run_session_end(&self, request: SessionEndRequest) -> SessionEndOutcome { crate::events::session_end::run(self, request).await } pub(crate) async fn run_stop(&self, request: StopRequest) -> StopOutcome { let mut outcome = crate::events::stop::run(self, request).await; outcome.continuation_fragments = self .command_runtime .output_spiller() .maybe_spill_prompt_fragments(outcome.continuation_fragments) .await; outcome } pub(crate) fn preview_interrupt(&self) -> Vec { crate::events::interrupt::preview(&self.handlers) } pub(crate) async fn run_interrupt(&self, request: InterruptRequest) -> InterruptOutcome { crate::events::interrupt::run(self, request).await } } #[cfg(test)] #[path = "mod_tests.rs"] mod tests;