enact_runner/

approval.rs

//! Human-in-the-loop approval — check before tool execution.
//!
//! When set, the runner calls the checker before each tool execution.
//! Return true to allow, false to block (tool result will indicate "blocked by approval policy").
//!
//! ## Policies
//!
//! - `AlwaysApprove` - Allow all tool calls without prompting
//! - `AlwaysDeny` - Block all tool calls
//! - `AskApprovalChecker` - Prompt user for every tool call
//! - `AskOnceApprovalChecker` - Prompt once per tool, remember decisions
//! - `PatternApprovalChecker` - Only prompt for tools matching patterns
//! - `PolicyWithOverrides` - Per-tool policy overrides

use async_trait::async_trait;
use regex::Regex;
use serde_json::Value;
use std::collections::HashMap;
use std::io::{self, BufRead, Write};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::RwLock;
use tokio::time::timeout;

/// Checker invoked before each tool execution (PreToolUse). Return true to allow, false to block.
#[async_trait]
pub trait ApprovalChecker: Send + Sync {
    async fn allow_tool(&self, tool_name: &str, args: &Value) -> bool;
}

/// Trait for prompting the user for approval decisions.
///
/// Implement this trait to customize how approval prompts are presented
/// (CLI stdin, API callback, GUI dialog, etc.).
#[async_trait]
pub trait ApprovalPrompter: Send + Sync {
    /// Prompt the user to approve a tool call.
    ///
    /// Returns `true` if approved, `false` if denied.
    async fn prompt(&self, tool_name: &str, args: &Value) -> io::Result<bool>;
}

/// Always allow all tool calls (default when no approval config).
pub struct AlwaysApprove;

#[async_trait]
impl ApprovalChecker for AlwaysApprove {
    async fn allow_tool(&self, _tool_name: &str, _args: &Value) -> bool {
        true
    }
}

/// Always deny all tool calls.
pub struct AlwaysDeny;

#[async_trait]
impl ApprovalChecker for AlwaysDeny {
    async fn allow_tool(&self, _tool_name: &str, _args: &Value) -> bool {
        false
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// CLI Prompter
// ─────────────────────────────────────────────────────────────────────────────

/// CLI-based prompter that reads from stdin.
///
/// Displays tool name and arguments, asks user to approve [y/n].
pub struct CliPrompter;

impl CliPrompter {
    pub fn new() -> Self {
        Self
    }
}

impl Default for CliPrompter {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl ApprovalPrompter for CliPrompter {
    async fn prompt(&self, tool_name: &str, args: &Value) -> io::Result<bool> {
        // Format arguments for display (truncate if too long)
        let args_str = serde_json::to_string_pretty(args).unwrap_or_else(|_| args.to_string());
        let args_display = if args_str.len() > 500 {
            format!("{}...", &args_str[..500])
        } else {
            args_str
        };

        // Print prompt
        let mut stdout = io::stdout();
        writeln!(stdout)?;
        writeln!(
            stdout,
            "╭─────────────────────────────────────────────────────╮"
        )?;
        writeln!(
            stdout,
            "│  Tool Approval Required                             │"
        )?;
        writeln!(
            stdout,
            "╰─────────────────────────────────────────────────────╯"
        )?;
        writeln!(stdout)?;
        writeln!(stdout, "Tool: {}", tool_name)?;
        writeln!(stdout, "Arguments:")?;
        for line in args_display.lines() {
            writeln!(stdout, "  {}", line)?;
        }
        writeln!(stdout)?;
        write!(stdout, "Allow this tool call? [y/n]: ")?;
        stdout.flush()?;

        // Read response - use blocking I/O in spawn_blocking to avoid blocking async runtime
        let response = tokio::task::spawn_blocking(|| {
            let stdin = io::stdin();
            let mut line = String::new();
            stdin.lock().read_line(&mut line)?;
            Ok::<_, io::Error>(line)
        })
        .await
        .map_err(io::Error::other)??;

        let answer = response.trim().to_lowercase();
        Ok(answer == "y" || answer == "yes")
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Ask Policy (prompt every time)
// ─────────────────────────────────────────────────────────────────────────────

/// Ask policy — prompts the user for every tool call.
///
/// Use this for maximum control over what the agent can do.
pub struct AskApprovalChecker {
    prompter: Arc<dyn ApprovalPrompter>,
    timeout_duration: Duration,
}

impl AskApprovalChecker {
    /// Create a new AskApprovalChecker with the given prompter and timeout.
    pub fn new(prompter: Arc<dyn ApprovalPrompter>, timeout_seconds: u64) -> Self {
        Self {
            prompter,
            timeout_duration: Duration::from_secs(timeout_seconds),
        }
    }

    /// Create with CLI prompter and default 5-minute timeout.
    pub fn cli_default() -> Self {
        Self::new(Arc::new(CliPrompter::new()), 300)
    }
}

#[async_trait]
impl ApprovalChecker for AskApprovalChecker {
    async fn allow_tool(&self, tool_name: &str, args: &Value) -> bool {
        match timeout(self.timeout_duration, self.prompter.prompt(tool_name, args)).await {
            Ok(Ok(approved)) => approved,
            Ok(Err(e)) => {
                tracing::warn!(error = %e, tool = tool_name, "Approval prompt failed, denying");
                false
            }
            Err(_) => {
                tracing::warn!(tool = tool_name, "Approval prompt timed out, denying");
                false
            }
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// AskOnce Policy (remember decisions)
// ─────────────────────────────────────────────────────────────────────────────

/// AskOnce policy — prompts once per tool name, remembers decisions.
///
/// After approving/denying a tool once, subsequent calls to the same tool
/// use the cached decision without prompting again.
pub struct AskOnceApprovalChecker {
    prompter: Arc<dyn ApprovalPrompter>,
    decisions: RwLock<HashMap<String, bool>>,
    timeout_duration: Duration,
}

impl AskOnceApprovalChecker {
    /// Create a new AskOnceApprovalChecker with the given prompter and timeout.
    pub fn new(prompter: Arc<dyn ApprovalPrompter>, timeout_seconds: u64) -> Self {
        Self {
            prompter,
            decisions: RwLock::new(HashMap::new()),
            timeout_duration: Duration::from_secs(timeout_seconds),
        }
    }

    /// Create with CLI prompter and default 5-minute timeout.
    pub fn cli_default() -> Self {
        Self::new(Arc::new(CliPrompter::new()), 300)
    }

    /// Clear all cached decisions.
    pub async fn clear_decisions(&self) {
        self.decisions.write().await.clear();
    }

    /// Pre-approve a tool (useful for allowing known-safe tools).
    pub async fn pre_approve(&self, tool_name: &str) {
        self.decisions
            .write()
            .await
            .insert(tool_name.to_string(), true);
    }

    /// Pre-deny a tool (useful for blocking known-dangerous tools).
    pub async fn pre_deny(&self, tool_name: &str) {
        self.decisions
            .write()
            .await
            .insert(tool_name.to_string(), false);
    }
}

#[async_trait]
impl ApprovalChecker for AskOnceApprovalChecker {
    async fn allow_tool(&self, tool_name: &str, args: &Value) -> bool {
        // Check cached decision first
        {
            let decisions = self.decisions.read().await;
            if let Some(&cached) = decisions.get(tool_name) {
                tracing::debug!(tool = tool_name, cached, "Using cached approval decision");
                return cached;
            }
        }

        // No cached decision — prompt user
        let approved =
            match timeout(self.timeout_duration, self.prompter.prompt(tool_name, args)).await {
                Ok(Ok(approved)) => approved,
                Ok(Err(e)) => {
                    tracing::warn!(error = %e, tool = tool_name, "Approval prompt failed, denying");
                    false
                }
                Err(_) => {
                    tracing::warn!(tool = tool_name, "Approval prompt timed out, denying");
                    false
                }
            };

        // Cache the decision
        self.decisions
            .write()
            .await
            .insert(tool_name.to_string(), approved);

        approved
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Pattern Policy (only prompt for matching tools)
// ─────────────────────────────────────────────────────────────────────────────

/// Pattern policy — only prompts for tools matching specified patterns.
///
/// Tools that don't match any pattern are automatically approved.
/// Tools matching a pattern require user approval.
pub struct PatternApprovalChecker {
    prompter: Arc<dyn ApprovalPrompter>,
    patterns: Vec<Regex>,
    timeout_duration: Duration,
}

impl PatternApprovalChecker {
    /// Create a new PatternApprovalChecker with the given patterns.
    ///
    /// Patterns are regular expressions matched against tool names.
    pub fn new(
        prompter: Arc<dyn ApprovalPrompter>,
        patterns: Vec<String>,
        timeout_seconds: u64,
    ) -> Result<Self, regex::Error> {
        let compiled: Result<Vec<Regex>, _> = patterns.iter().map(|p| Regex::new(p)).collect();
        Ok(Self {
            prompter,
            patterns: compiled?,
            timeout_duration: Duration::from_secs(timeout_seconds),
        })
    }

    /// Create with CLI prompter and default timeout.
    pub fn cli_with_patterns(patterns: Vec<String>) -> Result<Self, regex::Error> {
        Self::new(Arc::new(CliPrompter::new()), patterns, 300)
    }

    /// Check if a tool name matches any pattern.
    fn matches_pattern(&self, tool_name: &str) -> bool {
        self.patterns.iter().any(|p| p.is_match(tool_name))
    }
}

#[async_trait]
impl ApprovalChecker for PatternApprovalChecker {
    async fn allow_tool(&self, tool_name: &str, args: &Value) -> bool {
        // If no pattern matches, auto-approve
        if !self.matches_pattern(tool_name) {
            tracing::debug!(
                tool = tool_name,
                "Tool doesn't match approval patterns, auto-approving"
            );
            return true;
        }

        // Pattern matched — prompt user
        tracing::debug!(tool = tool_name, "Tool matches approval pattern, prompting");
        match timeout(self.timeout_duration, self.prompter.prompt(tool_name, args)).await {
            Ok(Ok(approved)) => approved,
            Ok(Err(e)) => {
                tracing::warn!(error = %e, tool = tool_name, "Approval prompt failed, denying");
                false
            }
            Err(_) => {
                tracing::warn!(tool = tool_name, "Approval prompt timed out, denying");
                false
            }
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Policy with Per-Tool Overrides
// ─────────────────────────────────────────────────────────────────────────────

/// Policy with per-tool overrides.
///
/// Allows specifying different policies for specific tools while using
/// a default policy for everything else.
///
/// # Example
///
/// ```ignore
/// let policy = PolicyWithOverrides::new(Arc::new(AskApprovalChecker::cli_default()))
///     .with_override("Read", Arc::new(AlwaysApprove))  // Auto-approve Read
///     .with_override("Write", Arc::new(AlwaysDeny));   // Block Write
/// ```
pub struct PolicyWithOverrides {
    default: Arc<dyn ApprovalChecker>,
    overrides: HashMap<String, Arc<dyn ApprovalChecker>>,
}

impl PolicyWithOverrides {
    /// Create a new policy with the given default checker.
    pub fn new(default: Arc<dyn ApprovalChecker>) -> Self {
        Self {
            default,
            overrides: HashMap::new(),
        }
    }

    /// Add a per-tool override.
    pub fn with_override(mut self, tool_name: &str, checker: Arc<dyn ApprovalChecker>) -> Self {
        self.overrides.insert(tool_name.to_string(), checker);
        self
    }

    /// Add multiple overrides at once.
    pub fn with_overrides(mut self, overrides: HashMap<String, Arc<dyn ApprovalChecker>>) -> Self {
        self.overrides.extend(overrides);
        self
    }
}

#[async_trait]
impl ApprovalChecker for PolicyWithOverrides {
    async fn allow_tool(&self, tool_name: &str, args: &Value) -> bool {
        // Check for tool-specific override
        if let Some(checker) = self.overrides.get(tool_name) {
            return checker.allow_tool(tool_name, args).await;
        }

        // Fall back to default policy
        self.default.allow_tool(tool_name, args).await
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Factory function from config
// ─────────────────────────────────────────────────────────────────────────────

/// Create an approval checker from ApprovalConfig.
///
/// Maps policy strings to checker implementations:
/// - "always_approve" → AlwaysApprove
/// - "always_deny" → AlwaysDeny
/// - "ask" or "always_require" → AskApprovalChecker
/// - "ask_once" → AskOnceApprovalChecker
/// - "pattern" → PatternApprovalChecker (requires patterns in config)
pub fn checker_from_config(
    policy: &str,
    timeout_seconds: u64,
    patterns: Option<&[String]>,
) -> Result<Arc<dyn ApprovalChecker>, String> {
    match policy {
        "always_approve" => Ok(Arc::new(AlwaysApprove)),
        "always_deny" => Ok(Arc::new(AlwaysDeny)),
        "ask" | "always_require" => Ok(Arc::new(AskApprovalChecker::new(
            Arc::new(CliPrompter::new()),
            timeout_seconds,
        ))),
        "ask_once" => Ok(Arc::new(AskOnceApprovalChecker::new(
            Arc::new(CliPrompter::new()),
            timeout_seconds,
        ))),
        "pattern" => {
            let patterns = patterns
                .ok_or("Pattern policy requires 'require_patterns' in config")?
                .to_vec();
            PatternApprovalChecker::new(Arc::new(CliPrompter::new()), patterns, timeout_seconds)
                .map(|c| Arc::new(c) as Arc<dyn ApprovalChecker>)
                .map_err(|e| format!("Invalid pattern regex: {}", e))
        }
        other => Err(format!("Unknown approval policy: '{}'", other)),
    }
}

/// Create an approval checker from full ApprovalConfig, including tool overrides.
///
/// If `tool_overrides` is set, wraps the base checker in `PolicyWithOverrides`.
pub fn checker_from_approval_config(
    config: &enact_config::ApprovalConfig,
) -> Result<Arc<dyn ApprovalChecker>, String> {
    // Create base checker from policy
    let base = checker_from_config(
        &config.policy,
        config.timeout_seconds,
        config.require_patterns.as_deref(),
    )?;

    // Apply tool overrides if present
    if let Some(ref overrides) = config.tool_overrides {
        if overrides.is_empty() {
            return Ok(base);
        }

        let mut policy = PolicyWithOverrides::new(base);
        for (tool_name, tool_policy) in overrides {
            let override_checker = checker_from_config(tool_policy, config.timeout_seconds, None)?;
            policy = policy.with_override(tool_name, override_checker);
        }
        Ok(Arc::new(policy))
    } else {
        Ok(base)
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn always_approve_allows_all() {
        let checker = AlwaysApprove;
        assert!(checker.allow_tool("anything", &serde_json::json!({})).await);
        assert!(
            checker
                .allow_tool("dangerous_tool", &serde_json::json!({"rm": "-rf /"}))
                .await
        );
    }

    #[tokio::test]
    async fn always_deny_blocks_all() {
        let checker = AlwaysDeny;
        assert!(!checker.allow_tool("anything", &serde_json::json!({})).await);
        assert!(
            !checker
                .allow_tool("safe_tool", &serde_json::json!({}))
                .await
        );
    }

    /// Mock prompter for testing
    struct MockPrompter {
        response: bool,
    }

    impl MockPrompter {
        fn approving() -> Arc<Self> {
            Arc::new(Self { response: true })
        }

        fn denying() -> Arc<Self> {
            Arc::new(Self { response: false })
        }
    }

    #[async_trait]
    impl ApprovalPrompter for MockPrompter {
        async fn prompt(&self, _tool_name: &str, _args: &Value) -> io::Result<bool> {
            Ok(self.response)
        }
    }

    #[tokio::test]
    async fn ask_checker_uses_prompter() {
        let approving = AskApprovalChecker::new(MockPrompter::approving(), 60);
        assert!(approving.allow_tool("test", &serde_json::json!({})).await);

        let denying = AskApprovalChecker::new(MockPrompter::denying(), 60);
        assert!(!denying.allow_tool("test", &serde_json::json!({})).await);
    }

    #[tokio::test]
    async fn ask_once_caches_decisions() {
        let checker = AskOnceApprovalChecker::new(MockPrompter::approving(), 60);

        // First call prompts and caches
        assert!(
            checker
                .allow_tool("test_tool", &serde_json::json!({}))
                .await
        );

        // Second call uses cache (even if prompter would deny)
        // We can verify caching by checking the decision map
        {
            let decisions = checker.decisions.read().await;
            assert_eq!(decisions.get("test_tool"), Some(&true));
        }
    }

    #[tokio::test]
    async fn ask_once_pre_approve_works() {
        let checker = AskOnceApprovalChecker::new(MockPrompter::denying(), 60);

        // Pre-approve the tool
        checker.pre_approve("safe_tool").await;

        // Should be approved without prompting
        assert!(
            checker
                .allow_tool("safe_tool", &serde_json::json!({}))
                .await
        );
    }

    #[tokio::test]
    async fn ask_once_pre_deny_works() {
        let checker = AskOnceApprovalChecker::new(MockPrompter::approving(), 60);

        // Pre-deny the tool
        checker.pre_deny("dangerous_tool").await;

        // Should be denied without prompting
        assert!(
            !checker
                .allow_tool("dangerous_tool", &serde_json::json!({}))
                .await
        );
    }

    #[tokio::test]
    async fn pattern_checker_auto_approves_non_matching() {
        let checker =
            PatternApprovalChecker::new(MockPrompter::denying(), vec!["^Write".to_string()], 60)
                .unwrap();

        // Read doesn't match ^Write pattern, auto-approved
        assert!(checker.allow_tool("Read", &serde_json::json!({})).await);

        // Write matches, uses prompter (which denies)
        assert!(!checker.allow_tool("Write", &serde_json::json!({})).await);
    }

    #[tokio::test]
    async fn pattern_checker_prompts_for_matching() {
        let checker = PatternApprovalChecker::new(
            MockPrompter::approving(),
            vec!["Edit|Write|Bash".to_string()],
            60,
        )
        .unwrap();

        // These match the pattern
        assert!(checker.allow_tool("Edit", &serde_json::json!({})).await);
        assert!(checker.allow_tool("Write", &serde_json::json!({})).await);
        assert!(checker.allow_tool("Bash", &serde_json::json!({})).await);

        // This doesn't match
        assert!(checker.allow_tool("Read", &serde_json::json!({})).await);
    }

    #[tokio::test]
    async fn policy_with_overrides_uses_specific_policy() {
        let default = Arc::new(AlwaysDeny);
        let policy = PolicyWithOverrides::new(default)
            .with_override("Read", Arc::new(AlwaysApprove))
            .with_override("Glob", Arc::new(AlwaysApprove));

        // Read and Glob use override (AlwaysApprove)
        assert!(policy.allow_tool("Read", &serde_json::json!({})).await);
        assert!(policy.allow_tool("Glob", &serde_json::json!({})).await);

        // Others use default (AlwaysDeny)
        assert!(!policy.allow_tool("Write", &serde_json::json!({})).await);
        assert!(!policy.allow_tool("Edit", &serde_json::json!({})).await);
    }

    #[tokio::test]
    async fn checker_from_config_creates_correct_types() {
        // Test always_approve
        let checker = checker_from_config("always_approve", 60, None).unwrap();
        assert!(checker.allow_tool("test", &serde_json::json!({})).await);

        // Test always_deny
        let checker = checker_from_config("always_deny", 60, None).unwrap();
        assert!(!checker.allow_tool("test", &serde_json::json!({})).await);

        // Test pattern with valid regex
        let patterns = vec!["^Edit$".to_string()];
        let checker = checker_from_config("pattern", 60, Some(&patterns)).unwrap();
        // Non-matching tools should be auto-approved
        assert!(checker.allow_tool("Read", &serde_json::json!({})).await);

        // Test pattern without patterns should error
        let result = checker_from_config("pattern", 60, None);
        assert!(result.is_err());

        // Test unknown policy should error
        let result = checker_from_config("unknown_policy", 60, None);
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn checker_from_approval_config_with_overrides() {
        use std::collections::HashMap;

        // Create config with base policy=always_deny but override Read to always_approve
        let mut overrides = HashMap::new();
        overrides.insert("Read".to_string(), "always_approve".to_string());
        overrides.insert("Glob".to_string(), "always_approve".to_string());

        let config = enact_config::ApprovalConfig {
            enabled: true,
            policy: "always_deny".to_string(),
            max_steps: None,
            require_patterns: None,
            timeout_seconds: 60,
            tool_overrides: Some(overrides),
        };

        let checker = checker_from_approval_config(&config).unwrap();

        // Read and Glob should be approved (override)
        assert!(checker.allow_tool("Read", &serde_json::json!({})).await);
        assert!(checker.allow_tool("Glob", &serde_json::json!({})).await);

        // Other tools should be denied (base policy)
        assert!(!checker.allow_tool("Write", &serde_json::json!({})).await);
        assert!(!checker.allow_tool("Edit", &serde_json::json!({})).await);
    }

    #[tokio::test]
    async fn checker_from_approval_config_without_overrides() {
        let config = enact_config::ApprovalConfig {
            enabled: true,
            policy: "always_approve".to_string(),
            max_steps: None,
            require_patterns: None,
            timeout_seconds: 60,
            tool_overrides: None,
        };

        let checker = checker_from_approval_config(&config).unwrap();
        assert!(checker.allow_tool("anything", &serde_json::json!({})).await);
    }
}