codex_cli_sdk/

hooks.rs

//! Hook system for observing and reacting to SDK events.
//!
//! Hooks fire on stream events **after** the Codex CLI has already acted.
//! `Block`/`Abort` affect what the SDK consumer sees, not what the CLI executes.
//! Pre-execution gating requires [`ApprovalPolicy::OnRequest`](crate::ApprovalPolicy)
//! combined with an [`ApprovalCallback`](crate::ApprovalCallback).
//!
//! # Design
//!
//! - **First-match dispatch**: hooks are evaluated in order; the first matching hook handles the event.
//! - **Configurable timeout behavior**: if a hook callback exceeds its timeout, the behavior is
//!   controlled per-hook via [`HookTimeoutBehavior`]. Defaults to `FailOpen` (event passes through).
//!   Use `FailClosed` for security/gating hooks where a timeout must not silently allow the event.
//! - **Async callbacks**: hooks can perform I/O (logging, webhooks, etc.).
//!
//! # Processing order
//!
//! Hooks run **before** the [`EventCallback`](crate::callback::EventCallback).
//! For each event the pipeline is:
//!
//! 1. Hooks (async, semantically classified, first-match)
//! 2. `EventCallback` (sync, raw event, observe/filter/transform)
//!
//! If a hook returns [`HookDecision::Block`] or [`HookDecision::Abort`], the
//! `EventCallback` is **not** invoked for that event.
//!
//! # Example
//!
//! ```rust
//! use std::sync::Arc;
//! use std::time::Duration;
//! use codex_cli_sdk::hooks::{HookMatcher, HookEvent, HookDecision, HookOutput, HookTimeoutBehavior};
//!
//! let hook = HookMatcher {
//!     event: HookEvent::CommandStarted,
//!     command_filter: Some("rm".into()),
//!     callback: Arc::new(|input, _ctx| {
//!         Box::pin(async move {
//!             eprintln!("Blocked dangerous command: {:?}", input.command);
//!             HookOutput {
//!                 decision: HookDecision::Block,
//!                 reason: Some("dangerous command".into()),
//!                 replacement_event: None,
//!             }
//!         })
//!     }),
//!     timeout: Some(Duration::from_secs(5)),
//!     on_timeout: HookTimeoutBehavior::FailClosed, // block on timeout for security hooks
//! };
//! ```

use crate::types::events::ThreadEvent;
use crate::types::items::ThreadItem;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::time::Duration;

// ── Hook event classification ─────────────────────────────────

/// The semantic event type that hooks match against.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum HookEvent {
    /// A command execution item started (shell command about to run or running).
    CommandStarted,
    /// A command execution item completed successfully.
    CommandCompleted,
    /// A command execution item failed (non-zero exit or error status).
    CommandFailed,
    /// A file change item completed.
    FileChangeCompleted,
    /// An agent message item completed.
    AgentMessage,
    /// The turn completed successfully.
    TurnCompleted,
    /// The turn failed.
    TurnFailed,
}

// ── Hook callback types ───────────────────────────────────────

/// Input provided to a hook callback.
#[derive(Debug, Clone)]
pub struct HookInput {
    /// The classified hook event.
    pub hook_event: HookEvent,
    /// The shell command (if applicable).
    pub command: Option<String>,
    /// The exit code (if applicable).
    pub exit_code: Option<i32>,
    /// The message text (if applicable, e.g. agent message or error).
    pub message_text: Option<String>,
    /// The raw event that triggered this hook.
    pub raw_event: ThreadEvent,
}

/// Context provided alongside the hook input.
#[derive(Debug, Clone)]
pub struct HookContext {
    /// The current thread ID, if known.
    pub thread_id: Option<String>,
    /// Number of turns completed so far.
    pub turn_count: u32,
}

/// Output returned by a hook callback.
#[derive(Debug, Clone)]
pub struct HookOutput {
    /// The decision for how to handle the event.
    pub decision: HookDecision,
    /// Optional human-readable reason for the decision.
    pub reason: Option<String>,
    /// Replacement event (only used with `HookDecision::Modify`).
    pub replacement_event: Option<ThreadEvent>,
}

impl Default for HookOutput {
    fn default() -> Self {
        Self {
            decision: HookDecision::Allow,
            reason: None,
            replacement_event: None,
        }
    }
}

/// What happens when a hook callback exceeds its timeout.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum HookTimeoutBehavior {
    /// Let the event pass through unchanged (default).
    ///
    /// Safe for observability hooks (logging, metrics) where a slow hook
    /// should not block the event stream.
    #[default]
    FailOpen,

    /// Block (suppress) the event, as if the hook returned [`HookDecision::Block`].
    ///
    /// Use this for security or gating hooks where a timeout must not silently
    /// allow a potentially dangerous event through.
    FailClosed,
}

/// Decision made by a hook.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HookDecision {
    /// Allow the event to pass through unchanged.
    Allow,
    /// Block (suppress) the event — consumer won't see it.
    Block,
    /// Replace the event with `HookOutput::replacement_event`.
    Modify,
    /// Abort — terminate the stream entirely.
    Abort,
}

/// Async hook callback.
pub type HookCallback = Arc<
    dyn Fn(HookInput, HookContext) -> Pin<Box<dyn Future<Output = HookOutput> + Send>>
        + Send
        + Sync,
>;

// ── Hook matcher ──────────────────────────────────────────────

/// A hook registration: matches events and invokes a callback.
#[derive(Clone)]
pub struct HookMatcher {
    /// Which event type this hook matches.
    pub event: HookEvent,
    /// Optional command substring filter (only relevant for Command* events).
    pub command_filter: Option<String>,
    /// The async callback to invoke when matched.
    pub callback: HookCallback,
    /// Per-hook timeout override. Falls back to `ThreadOptions::default_hook_timeout`.
    pub timeout: Option<Duration>,
    /// What to do if the callback exceeds its timeout.
    ///
    /// Defaults to [`HookTimeoutBehavior::FailOpen`] (event passes through).
    /// Set to [`HookTimeoutBehavior::FailClosed`] for security/gating hooks.
    pub on_timeout: HookTimeoutBehavior,
}

impl std::fmt::Debug for HookMatcher {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HookMatcher")
            .field("event", &self.event)
            .field("command_filter", &self.command_filter)
            .field("timeout", &self.timeout)
            .field("on_timeout", &self.on_timeout)
            .finish()
    }
}

// ── Classification ────────────────────────────────────────────

/// Classify a `ThreadEvent` into a `HookEvent`, if applicable.
///
/// Returns `None` for events that don't map to any hook (e.g. `ThreadStarted`,
/// `TurnStarted`, approval requests, streaming deltas).
pub fn classify_hook_event(event: &ThreadEvent) -> Option<HookEvent> {
    use crate::types::items::CommandExecutionStatus;

    match event {
        ThreadEvent::ItemStarted {
            item: ThreadItem::CommandExecution { .. },
        } => Some(HookEvent::CommandStarted),

        ThreadEvent::ItemCompleted {
            item: ThreadItem::CommandExecution { status, .. },
        } => match status {
            CommandExecutionStatus::Completed => Some(HookEvent::CommandCompleted),
            CommandExecutionStatus::Failed => Some(HookEvent::CommandFailed),
            CommandExecutionStatus::InProgress => None,
        },

        ThreadEvent::ItemCompleted {
            item: ThreadItem::FileChange { .. },
        } => Some(HookEvent::FileChangeCompleted),

        ThreadEvent::ItemCompleted {
            item: ThreadItem::AgentMessage { .. },
        } => Some(HookEvent::AgentMessage),

        ThreadEvent::TurnCompleted { .. } => Some(HookEvent::TurnCompleted),
        ThreadEvent::TurnFailed { .. } => Some(HookEvent::TurnFailed),

        _ => None,
    }
}

/// Build a `HookInput` from a classified event.
pub fn build_hook_input(hook_event: HookEvent, event: &ThreadEvent) -> HookInput {
    let (command, exit_code, message_text) = match event {
        ThreadEvent::ItemStarted {
            item: ThreadItem::CommandExecution { command, .. },
        }
        | ThreadEvent::ItemCompleted {
            item: ThreadItem::CommandExecution { command, .. },
        } => {
            let exit_code = match event {
                ThreadEvent::ItemCompleted {
                    item: ThreadItem::CommandExecution { exit_code, .. },
                } => *exit_code,
                _ => None,
            };
            (Some(command.clone()), exit_code, None)
        }

        ThreadEvent::ItemCompleted {
            item: ThreadItem::AgentMessage { text, .. },
        } => (None, None, Some(text.clone())),

        ThreadEvent::TurnFailed { error } => (None, None, Some(error.message.clone())),

        _ => (None, None, None),
    };

    HookInput {
        hook_event,
        command,
        exit_code,
        message_text,
        raw_event: event.clone(),
    }
}

// ── Dispatch ──────────────────────────────────────────────────

/// Dispatch an event through the hook chain (first-match).
///
/// Returns the `HookOutput` from the first matching hook, or `None` if no hook matched.
/// On timeout, the hook is skipped (fail-open) and dispatch continues to the next hook.
pub async fn dispatch_hook(
    event: &ThreadEvent,
    hooks: &[HookMatcher],
    context: &HookContext,
    default_timeout: Duration,
) -> Option<HookOutput> {
    let hook_event = classify_hook_event(event)?;
    let input = build_hook_input(hook_event.clone(), event);

    for hook in hooks {
        if hook.event != hook_event {
            continue;
        }

        // Apply command filter if present.
        if let Some(ref filter) = hook.command_filter {
            match &input.command {
                Some(cmd) if cmd.contains(filter.as_str()) => {}
                _ => continue,
            }
        }

        let timeout = hook.timeout.unwrap_or(default_timeout);
        let future = (hook.callback)(input.clone(), context.clone());

        match tokio::time::timeout(timeout, future).await {
            Ok(output) => return Some(output),
            Err(_) => {
                tracing::warn!(
                    "Hook timed out after {:?} for {:?} — {:?}",
                    timeout,
                    hook.event,
                    hook.on_timeout,
                );
                match hook.on_timeout {
                    HookTimeoutBehavior::FailOpen => continue,
                    HookTimeoutBehavior::FailClosed => {
                        return Some(HookOutput {
                            decision: HookDecision::Block,
                            reason: Some(format!("hook timeout after {timeout:?} (fail-closed)")),
                            replacement_event: None,
                        });
                    }
                }
            }
        }
    }

    None
}

// ── Tests ─────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::events::Usage;

    fn make_command_started(cmd: &str) -> ThreadEvent {
        ThreadEvent::ItemStarted {
            item: ThreadItem::CommandExecution {
                id: "cmd-1".into(),
                command: cmd.into(),
                aggregated_output: String::new(),
                exit_code: None,
                status: crate::types::items::CommandExecutionStatus::InProgress,
            },
        }
    }

    fn make_command_completed(cmd: &str, code: i32) -> ThreadEvent {
        ThreadEvent::ItemCompleted {
            item: ThreadItem::CommandExecution {
                id: "cmd-1".into(),
                command: cmd.into(),
                aggregated_output: "output".into(),
                exit_code: Some(code),
                status: crate::types::items::CommandExecutionStatus::Completed,
            },
        }
    }

    fn make_turn_completed() -> ThreadEvent {
        ThreadEvent::TurnCompleted {
            usage: Usage {
                input_tokens: 100,
                cached_input_tokens: 0,
                output_tokens: 50,
            },
        }
    }

    fn make_context() -> HookContext {
        HookContext {
            thread_id: Some("thread-1".into()),
            turn_count: 0,
        }
    }

    #[test]
    fn classify_command_started() {
        let event = make_command_started("ls -la");
        assert_eq!(classify_hook_event(&event), Some(HookEvent::CommandStarted));
    }

    #[test]
    fn classify_command_completed() {
        let event = make_command_completed("ls", 0);
        assert_eq!(
            classify_hook_event(&event),
            Some(HookEvent::CommandCompleted)
        );
    }

    #[test]
    fn classify_turn_completed() {
        let event = make_turn_completed();
        assert_eq!(classify_hook_event(&event), Some(HookEvent::TurnCompleted));
    }

    #[test]
    fn classify_unmatched_returns_none() {
        let event = ThreadEvent::TurnStarted;
        assert_eq!(classify_hook_event(&event), None);
    }

    #[test]
    fn build_input_extracts_command() {
        let event = make_command_started("git status");
        let input = build_hook_input(HookEvent::CommandStarted, &event);
        assert_eq!(input.command, Some("git status".into()));
        assert_eq!(input.exit_code, None);
    }

    #[test]
    fn build_input_extracts_exit_code() {
        let event = make_command_completed("ls", 1);
        let input = build_hook_input(HookEvent::CommandCompleted, &event);
        assert_eq!(input.exit_code, Some(1));
    }

    #[tokio::test]
    async fn dispatch_first_match() {
        let hook = HookMatcher {
            event: HookEvent::CommandStarted,
            command_filter: None,
            callback: Arc::new(|_input, _ctx| {
                Box::pin(async {
                    HookOutput {
                        decision: HookDecision::Block,
                        reason: Some("blocked".into()),
                        replacement_event: None,
                    }
                })
            }),
            timeout: None,
            on_timeout: Default::default(),
        };

        let event = make_command_started("ls");
        let ctx = make_context();
        let result = dispatch_hook(&event, &[hook], &ctx, Duration::from_secs(5)).await;

        assert!(result.is_some());
        let output = result.unwrap();
        assert_eq!(output.decision, HookDecision::Block);
    }

    #[tokio::test]
    async fn dispatch_command_filter() {
        let hook = HookMatcher {
            event: HookEvent::CommandStarted,
            command_filter: Some("rm".into()),
            callback: Arc::new(|_input, _ctx| {
                Box::pin(async {
                    HookOutput {
                        decision: HookDecision::Block,
                        reason: None,
                        replacement_event: None,
                    }
                })
            }),
            timeout: None,
            on_timeout: Default::default(),
        };

        let ctx = make_context();

        // Should NOT match "ls"
        let ls_event = make_command_started("ls -la");
        let result = dispatch_hook(&ls_event, &[hook], &ctx, Duration::from_secs(5)).await;
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn dispatch_command_filter_matches() {
        let hook = HookMatcher {
            event: HookEvent::CommandStarted,
            command_filter: Some("rm".into()),
            callback: Arc::new(|_input, _ctx| {
                Box::pin(async {
                    HookOutput {
                        decision: HookDecision::Block,
                        reason: None,
                        replacement_event: None,
                    }
                })
            }),
            timeout: None,
            on_timeout: Default::default(),
        };

        let ctx = make_context();

        let rm_event = make_command_started("rm -rf /tmp/test");
        let result = dispatch_hook(&rm_event, &[hook], &ctx, Duration::from_secs(5)).await;
        assert!(result.is_some());
        assert_eq!(result.unwrap().decision, HookDecision::Block);
    }

    #[tokio::test]
    async fn dispatch_no_match_returns_none() {
        let hook = HookMatcher {
            event: HookEvent::TurnCompleted,
            command_filter: None,
            callback: Arc::new(|_input, _ctx| Box::pin(async { HookOutput::default() })),
            timeout: None,
            on_timeout: Default::default(),
        };

        let event = make_command_started("ls");
        let ctx = make_context();
        let result = dispatch_hook(&event, &[hook], &ctx, Duration::from_secs(5)).await;
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn dispatch_timeout_fails_open() {
        let hook = HookMatcher {
            event: HookEvent::CommandStarted,
            command_filter: None,
            callback: Arc::new(|_input, _ctx| {
                Box::pin(async {
                    // Simulate a slow hook
                    tokio::time::sleep(Duration::from_secs(10)).await;
                    HookOutput {
                        decision: HookDecision::Block,
                        reason: None,
                        replacement_event: None,
                    }
                })
            }),
            timeout: Some(Duration::from_millis(10)),
            on_timeout: HookTimeoutBehavior::FailOpen,
        };

        let event = make_command_started("ls");
        let ctx = make_context();
        let result = dispatch_hook(&event, &[hook], &ctx, Duration::from_secs(5)).await;

        // Timeout → fail-open → no match (since it's the only hook)
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn dispatch_timeout_fail_closed_blocks() {
        let hook = HookMatcher {
            event: HookEvent::CommandStarted,
            command_filter: None,
            callback: Arc::new(|_input, _ctx| {
                Box::pin(async {
                    tokio::time::sleep(Duration::from_secs(10)).await;
                    HookOutput::default()
                })
            }),
            timeout: Some(Duration::from_millis(10)),
            on_timeout: HookTimeoutBehavior::FailClosed,
        };

        let event = make_command_started("dangerous-cmd");
        let ctx = make_context();
        let result = dispatch_hook(&event, &[hook], &ctx, Duration::from_secs(5)).await;

        // Timeout + fail-closed → Block decision returned
        assert!(result.is_some());
        let output = result.unwrap();
        assert_eq!(output.decision, HookDecision::Block);
        assert!(output.reason.as_deref().unwrap_or("").contains("timeout"));
    }

    #[tokio::test]
    async fn dispatch_all_four_decisions() {
        for decision in [
            HookDecision::Allow,
            HookDecision::Block,
            HookDecision::Modify,
            HookDecision::Abort,
        ] {
            let d = decision.clone();
            let hook = HookMatcher {
                event: HookEvent::TurnCompleted,
                command_filter: None,
                callback: Arc::new(move |_input, _ctx| {
                    let d = d.clone();
                    Box::pin(async move {
                        HookOutput {
                            decision: d,
                            reason: None,
                            replacement_event: None,
                        }
                    })
                }),
                timeout: None,
                on_timeout: Default::default(),
            };

            let event = make_turn_completed();
            let ctx = make_context();
            let result = dispatch_hook(&event, &[hook], &ctx, Duration::from_secs(5)).await;
            assert!(result.is_some());
            assert_eq!(result.unwrap().decision, decision);
        }
    }
}