enact_runner/

loop_driver.rs

//! Core agent loop driver
//!
//! `AgentRunner` is the "missing middle" — the robust loop that sits between
//! the apps (CLI, API) and the `enact-core` kernel. It implements:
//!
//! - Multi-iteration tool call loop (ported from zeroclaw's `run_tool_call_loop`)
//! - Multi-format tool call parsing (JSON, XML, Markdown)
//! - Auto context compaction when history grows too large
//! - Retry with exponential backoff for transient errors
//! - Checkpoint saving at configured intervals
//! - Stream event emission throughout
//! - LLM call tracing and token/cost accounting (observability)
//!
//! This fulfills the mandate from `28-TS-RUST-INTEGRATION.md`:
//! "Rust handles retries/fallbacks" and `27-LONG-RUNNING-EXECUTIONS.md`:
//! "Unified long-running agentic loop".

use crate::approval::ApprovalChecker;
use crate::commands::{
    dispatch as dispatch_command, load_commands_for_run, parse_slash_invocation,
};
use crate::compaction::{self, HistoryMessage};
use crate::config::RunnerConfig;
use crate::hooks::HookRegistry;
use crate::parser;
use crate::retry::RetryHandler;

use enact_config::{HookDecision, HookEvent, HookHandler};
use enact_core::callable::Callable;
use enact_core::graph::CheckpointStore;
use enact_core::kernel::cost::{
    CostCalculator, ModelPricing, TokenUsage as LlmTokenUsage, UsageAccumulator,
};
use enact_core::kernel::{ExecutionError, StepId, StepType};
use enact_core::runner::Runner;
use enact_core::streaming::StreamEvent;
use enact_core::tool::Tool;
use enact_skills::{
    find_matching_skills, find_skill_by_name, load_skill_body, load_skill_metas,
    load_skill_resources, SkillResourceLimits,
};

use std::path::Path;
use std::sync::Arc;
use std::time::Instant;

/// Outcome of a runner loop execution.
#[derive(Debug)]
pub enum LoopOutcome {
    /// The agent produced a final response (no more tool calls).
    Completed(String),
    /// The loop hit the maximum iteration limit.
    MaxIterationsReached {
        last_output: String,
        iterations: usize,
    },
    /// The execution was cancelled externally.
    Cancelled,
    /// The execution exceeded the configured timeout.
    TimedOut { elapsed_secs: u64 },
}

impl LoopOutcome {
    /// Whether the outcome represents a successful completion.
    pub fn is_completed(&self) -> bool {
        matches!(self, LoopOutcome::Completed(_))
    }

    /// Get the final output text, if any.
    pub fn output(&self) -> Option<&str> {
        match self {
            LoopOutcome::Completed(s) => Some(s),
            LoopOutcome::MaxIterationsReached { last_output, .. } => Some(last_output),
            _ => None,
        }
    }
}

/// The robust agent runner — drives the tool call loop with retries,
/// compaction, and multi-format parsing.
pub struct AgentRunner<S: CheckpointStore> {
    /// The underlying enact-core runner (provides cancel/pause/checkpoint/events)
    runner: Runner<S>,
    /// Configuration for iteration limits, compaction, retries
    config: RunnerConfig,
    /// Registered tools available to the agent
    tools: Vec<Arc<dyn Tool>>,
    /// Cumulative token usage and cost tracking
    usage_accumulator: UsageAccumulator,
    /// Optional approval checker (PreToolUse); if returns false, tool is blocked
    approval_checker: Option<Arc<dyn ApprovalChecker>>,
    /// Optional hook registry (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd)
    hook_registry: Option<Arc<HookRegistry>>,
}

impl<S: CheckpointStore> AgentRunner<S> {
    /// Create a new `AgentRunner` wrapping an existing `Runner`.
    pub fn new(runner: Runner<S>, config: RunnerConfig) -> Self {
        Self {
            runner,
            config,
            tools: Vec::new(),
            usage_accumulator: UsageAccumulator::new(),
            approval_checker: None,
            hook_registry: None,
        }
    }

    /// Set the hook registry for lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd).
    pub fn with_hook_registry(mut self, registry: Arc<HookRegistry>) -> Self {
        self.hook_registry = Some(registry);
        self
    }

    /// Set an approval checker (PreToolUse). When set, each tool call is checked; if false, the tool is blocked.
    pub fn with_approval_checker(mut self, checker: Arc<dyn ApprovalChecker>) -> Self {
        self.approval_checker = Some(checker);
        self
    }

    /// Get the cumulative usage statistics
    pub fn usage(&self) -> &UsageAccumulator {
        &self.usage_accumulator
    }

    /// Register a tool for use in the loop.
    pub fn add_tool(mut self, tool: impl Tool + 'static) -> Self {
        self.tools.push(Arc::new(tool));
        self
    }

    /// Register multiple tools at once.
    pub fn add_tools(mut self, tools: Vec<Arc<dyn Tool>>) -> Self {
        self.tools.extend(tools);
        self
    }

    /// Access the underlying runner.
    pub fn inner(&self) -> &Runner<S> {
        &self.runner
    }

    /// Access the underlying runner mutably.
    pub fn inner_mut(&mut self) -> &mut Runner<S> {
        &mut self.runner
    }

    /// Run the robust agent loop.
    ///
    /// This is the core method — it replaces both `AgenticLoop::run` (which was
    /// a skeleton) and `LlmCallable::run` (which had a basic loop but no
    /// retries, compaction, or multi-format parsing).
    ///
    /// # Flow
    ///
    /// 1. Call the callable with current input
    /// 2. Parse the response for tool calls (JSON → XML → Markdown)
    /// 3. If tool calls found: execute them, append results to history, loop
    /// 4. If no tool calls: return the final response
    /// 5. Throughout: check limits, retry on errors, compact history, checkpoint
    pub async fn run(
        &mut self,
        callable: &dyn Callable,
        input: &str,
        project_dir: Option<&Path>,
    ) -> anyhow::Result<LoopOutcome> {
        let start_time = Instant::now();
        let mut retry_handler = RetryHandler::new(self.config.retry.clone());

        self.load_mcp_tools_at_session_start().await;

        // ── Hooks: SessionStart ──
        if let Some(ref reg) = self.hook_registry {
            let mut ctx = serde_json::json!({
                "event": "SessionStart",
                "execution_id": self.runner.execution_id().as_str(),
                "callable": callable.name(),
            });
            self.execute_hooks(reg, HookEvent::SessionStart, None, &mut ctx, callable)
                .await;
        }

        // ── Slash command dispatch: expand /command args into content (global + project + plugin commands) ──
        let commands = load_commands_for_run(project_dir);
        let command_expanded = dispatch_command(input, &commands);
        let effective_input = command_expanded
            .clone()
            .unwrap_or_else(|| input.to_string());

        // ── Manual skill invocation: /skill-name or /plugin:skill-name (command precedence) ──
        let first_user_content = if command_expanded.is_none() {
            if let Some(invoked) = build_manual_skill_input(project_dir, input) {
                invoked
            } else {
                let skill_context = build_skill_context(project_dir, &effective_input);
                if skill_context.is_empty() {
                    effective_input.clone()
                } else {
                    format!("{}\n\n{}", skill_context, effective_input)
                }
            }
        } else {
            let skill_context = build_skill_context(project_dir, &effective_input);
            if skill_context.is_empty() {
                effective_input.clone()
            } else {
                format!("{}\n\n{}", skill_context, effective_input)
            }
        };

        // Build initial history
        let mut history = vec![HistoryMessage::user(&first_user_content)];

        // ── Hooks: UserPromptSubmit ──
        if let Some(ref reg) = self.hook_registry {
            let mut ctx = serde_json::json!({
                "event": "UserPromptSubmit",
                "execution_id": self.runner.execution_id().as_str(),
                "prompt": effective_input,
            });
            self.execute_hooks(reg, HookEvent::UserPromptSubmit, None, &mut ctx, callable)
                .await;
        }

        // Emit execution start
        if self.config.emit_events {
            self.runner
                .emitter()
                .emit(StreamEvent::execution_start(self.runner.execution_id()));
        }

        tracing::info!(
            execution_id = %self.runner.execution_id(),
            callable = callable.name(),
            max_iterations = self.config.max_iterations,
            "Starting robust agent loop"
        );

        let mut last_output = String::new();

        for iteration in 0..self.config.max_iterations {
            // ── Check cancellation ──
            if self.runner.is_cancelled() {
                tracing::info!("Execution cancelled");
                if let Some(ref reg) = self.hook_registry {
                    let mut ctx = serde_json::json!({
                        "event": "SessionEnd",
                        "execution_id": self.runner.execution_id().as_str(),
                        "outcome": "cancelled",
                    });
                    self.execute_hooks(reg, HookEvent::SessionEnd, None, &mut ctx, callable)
                        .await;
                }
                return Ok(LoopOutcome::Cancelled);
            }

            // ── Check timeout ──
            let elapsed = start_time.elapsed();
            if elapsed > self.config.max_duration {
                tracing::warn!(elapsed_secs = elapsed.as_secs(), "Execution timed out");
                if let Some(ref reg) = self.hook_registry {
                    let mut ctx = serde_json::json!({
                        "event": "SessionEnd",
                        "execution_id": self.runner.execution_id().as_str(),
                        "outcome": "timed_out",
                        "elapsed_secs": elapsed.as_secs(),
                    });
                    self.execute_hooks(reg, HookEvent::SessionEnd, None, &mut ctx, callable)
                        .await;
                }
                return Ok(LoopOutcome::TimedOut {
                    elapsed_secs: elapsed.as_secs(),
                });
            }

            // ── Wait if paused ──
            while self.runner.is_paused() {
                tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
                if self.runner.is_cancelled() {
                    return Ok(LoopOutcome::Cancelled);
                }
            }

            // ── Build input for this iteration ──
            let current_input = self.build_iteration_input(&history);
            let step_id = StepId::new();
            let step_start = Instant::now();

            if self.config.emit_events {
                self.runner.emitter().emit(StreamEvent::step_start(
                    self.runner.execution_id(),
                    &step_id,
                    StepType::LlmNode,
                    format!("iteration_{}", iteration),
                ));
            }

            tracing::debug!(iteration, "Running callable");

            // ── Emit LLM call start event (observability) ──
            if self.config.emit_events && self.config.observability.trace_llm_calls {
                self.runner.emitter().emit(StreamEvent::llm_call_start(
                    self.runner.execution_id(),
                    Some(&step_id),
                    callable.name(),
                    self.config.observability.model_name.clone(),
                    history.len(),
                ));
            }

            let llm_call_start = Instant::now();

            // ── Call the LLM ──
            let response = match callable.run(&current_input).await {
                Ok(output) => {
                    retry_handler.reset();

                    // ── Emit LLM call end event (observability) ──
                    let llm_call_duration_ms = llm_call_start.elapsed().as_millis() as u64;
                    if self.config.emit_events && self.config.observability.trace_llm_calls {
                        let (prompt_tokens, completion_tokens) = match callable.last_usage() {
                            Some(u) if !u.is_empty() => (u.prompt_tokens, u.completion_tokens),
                            _ => {
                                let prompt_len = current_input.len();
                                let estimated_prompt_tokens = (prompt_len / 4) as u32;
                                let estimated_tokens = (output.len() / 4) as u32;
                                (estimated_prompt_tokens, estimated_tokens)
                            }
                        };
                        let total_tokens = prompt_tokens + completion_tokens;

                        self.runner.emitter().emit(StreamEvent::llm_call_end(
                            self.runner.execution_id(),
                            Some(&step_id),
                            llm_call_duration_ms,
                            Some(prompt_tokens),
                            Some(completion_tokens),
                            Some(total_tokens),
                        ));

                        // Track cumulative usage
                        if self.config.observability.track_token_usage {
                            let usage = LlmTokenUsage::new(prompt_tokens, completion_tokens);

                            // Use pricing from config if available, otherwise fall back to model name
                            let pricing = if let (Some(input_cost), Some(output_cost)) = (
                                self.config.observability.cost_per_1m_input,
                                self.config.observability.cost_per_1m_output,
                            ) {
                                ModelPricing::new(input_cost, output_cost)
                            } else {
                                let model = self
                                    .config
                                    .observability
                                    .model_name
                                    .as_deref()
                                    .unwrap_or("default");
                                CostCalculator::pricing_for_model(model)
                            };
                            let cost = CostCalculator::calculate_cost(&usage, &pricing);

                            self.usage_accumulator.add(&usage, cost);

                            // Emit token usage event
                            self.runner
                                .emitter()
                                .emit(StreamEvent::token_usage_recorded(
                                    self.runner.execution_id(),
                                    Some(&step_id),
                                    prompt_tokens,
                                    completion_tokens,
                                    self.usage_accumulator.total_tokens,
                                    Some(cost),
                                    Some(self.usage_accumulator.total_cost_usd),
                                ));
                        }
                    }

                    output
                }
                Err(e) => {
                    let err_msg = e.to_string();
                    let llm_call_duration_ms = llm_call_start.elapsed().as_millis() as u64;
                    tracing::warn!(iteration, error = %err_msg, "Callable error");

                    // ── Emit LLM call failed event (observability) ──
                    if self.config.emit_events && self.config.observability.trace_llm_calls {
                        self.runner.emitter().emit(StreamEvent::llm_call_failed(
                            self.runner.execution_id(),
                            Some(&step_id),
                            &err_msg,
                            Some(llm_call_duration_ms),
                        ));
                    }

                    // Check if we should retry
                    if let Some(delay) = retry_handler.should_retry(&err_msg) {
                        if self.config.emit_events {
                            self.runner.emitter().emit(StreamEvent::step_end(
                                self.runner.execution_id(),
                                &step_id,
                                Some(format!("Retrying after error: {}", err_msg)),
                                step_start.elapsed().as_millis() as u64,
                            ));
                        }
                        tokio::time::sleep(delay).await;
                        continue; // Retry this iteration
                    }

                    // Non-retryable or max retries exceeded
                    let exec_error = ExecutionError::kernel_internal(err_msg);
                    if self.config.emit_events {
                        self.runner.emitter().emit(StreamEvent::execution_failed(
                            self.runner.execution_id(),
                            exec_error,
                        ));
                    }
                    return Err(e);
                }
            };

            // ── Parse for tool calls ──
            let mut parse_result = parser::parse(&response);

            if parse_result.tool_calls.is_empty() {
                // No tool calls — this is the final response
                last_output = if parse_result.text.is_empty() {
                    response.clone()
                } else {
                    parse_result.text.clone()
                };

                let step_duration = step_start.elapsed().as_millis() as u64;
                if self.config.emit_events {
                    self.runner.emitter().emit(StreamEvent::step_end(
                        self.runner.execution_id(),
                        &step_id,
                        Some(last_output.clone()),
                        step_duration,
                    ));
                    let total_duration = start_time.elapsed().as_millis() as u64;
                    self.runner.emitter().emit(StreamEvent::execution_end(
                        self.runner.execution_id(),
                        Some(last_output.clone()),
                        total_duration,
                    ));
                }

                tracing::info!(
                    iteration,
                    output_len = last_output.len(),
                    "Agent loop completed with final response"
                );

                // Hooks: SessionEnd / Stop on normal completion
                if let Some(ref reg) = self.hook_registry {
                    let mut ctx = serde_json::json!({
                        "event": "SessionEnd",
                        "execution_id": self.runner.execution_id().as_str(),
                        "outcome": "completed",
                        "output": last_output,
                    });
                    self.execute_hooks(reg, HookEvent::SessionEnd, None, &mut ctx, callable)
                        .await;
                    self.execute_hooks(reg, HookEvent::Stop, None, &mut ctx, callable)
                        .await;
                }

                return Ok(LoopOutcome::Completed(last_output));
            }

            // ── Execute tool calls ──
            history.push(HistoryMessage::assistant(&response));

            for (tool_idx, tool_call) in parse_result.tool_calls.iter_mut().enumerate() {
                let tool_call_id = format!("{}-tool-{}", step_id, tool_idx);

                tracing::debug!(
                    tool = %tool_call.name,
                    format = ?tool_call.format,
                    "Executing tool call"
                );

                // PreToolUse: hooks (allow/block/mutate)
                if let Some(ref reg) = self.hook_registry {
                    let ctx = serde_json::json!({
                        "event": "PreToolUse",
                        "execution_id": self.runner.execution_id().as_str(),
                        "tool_name": tool_call.name,
                        "arguments": tool_call.arguments,
                    });
                    match self
                        .execute_pre_tool_hooks(reg, Some(&tool_call.name), &ctx, callable)
                        .await
                    {
                        HookDecision::Allow => {}
                        HookDecision::Mutate { arguments, reason } => {
                            if let Some(reason) = reason {
                                tracing::debug!(
                                    tool = %tool_call.name,
                                    reason = %reason,
                                    "PreToolUse hook mutated tool arguments"
                                );
                            }
                            tool_call.arguments = arguments;
                        }
                        HookDecision::Block { reason } => {
                            let blocked_msg = match reason {
                                Some(reason) if !reason.is_empty() => format!(
                                    "Tool '{}' was blocked by a PreToolUse hook: {}",
                                    tool_call.name, reason
                                ),
                                _ => {
                                    format!(
                                        "Tool '{}' was blocked by a PreToolUse hook.",
                                        tool_call.name
                                    )
                                }
                            };
                            history
                                .push(HistoryMessage::tool_result(&tool_call.name, &blocked_msg));
                            continue;
                        }
                    }
                }

                // PreToolUse: approval check (human-in-the-loop)
                if let Some(ref checker) = self.approval_checker {
                    if self.config.emit_events {
                        self.runner.emitter().emit(StreamEvent::permission_request(
                            self.runner.execution_id(),
                            &tool_call.name,
                            tool_call.arguments.clone(),
                            "approval_policy",
                        ));
                    }
                    if !checker
                        .allow_tool(&tool_call.name, &tool_call.arguments)
                        .await
                    {
                        let blocked_msg = format!(
                            "Tool '{}' was blocked by approval policy (user denied or policy=always_deny).",
                            tool_call.name
                        );
                        history.push(HistoryMessage::tool_result(&tool_call.name, &blocked_msg));
                        continue;
                    }
                }

                // Emit tool input event
                if self.config.emit_events {
                    self.runner.emitter().emit(StreamEvent::ToolInputAvailable {
                        tool_call_id: tool_call_id.clone(),
                        tool_name: tool_call.name.clone(),
                        input: tool_call.arguments.clone(),
                    });
                }

                let tool_start = std::time::Instant::now();

                // Find the tool in our registry
                let tool = self.tools.iter().find(|t| t.name() == tool_call.name);

                let tool_result = match tool {
                    Some(t) => match t.execute(tool_call.arguments.clone()).await {
                        Ok(result) => serde_json::to_string(&result)
                            .unwrap_or_else(|_| format!("{:?}", result)),
                        Err(e) => format!("Tool error: {}", e),
                    },
                    None => {
                        format!(
                            "Error: Tool '{}' not found. Available tools: {:?}",
                            tool_call.name,
                            self.tools.iter().map(|t| t.name()).collect::<Vec<_>>()
                        )
                    }
                };

                let tool_duration_ms = tool_start.elapsed().as_millis() as u64;

                // Emit tool output event
                if self.config.emit_events {
                    self.runner
                        .emitter()
                        .emit(StreamEvent::ToolOutputAvailable {
                            tool_call_id: tool_call_id.clone(),
                            output: serde_json::json!({
                                "result": tool_result.clone(),
                                "duration_ms": tool_duration_ms,
                            }),
                        });
                }

                history.push(HistoryMessage::tool_result(&tool_call.name, &tool_result));

                // PostToolUse: hooks
                if let Some(ref reg) = self.hook_registry {
                    let mut ctx = serde_json::json!({
                        "event": "PostToolUse",
                        "execution_id": self.runner.execution_id().as_str(),
                        "tool_name": tool_call.name,
                        "arguments": tool_call.arguments,
                        "result": tool_result,
                    });
                    self.execute_hooks(
                        reg,
                        HookEvent::PostToolUse,
                        Some(&tool_call.name),
                        &mut ctx,
                        callable,
                    )
                    .await;
                }
            }

            let step_duration = step_start.elapsed().as_millis() as u64;
            if self.config.emit_events {
                self.runner.emitter().emit(StreamEvent::step_end(
                    self.runner.execution_id(),
                    &step_id,
                    Some(format!(
                        "Executed {} tool(s)",
                        parse_result.tool_calls.len()
                    )),
                    step_duration,
                ));
            }

            last_output = response;

            // ── Auto-compact history if needed ──
            if compaction::needs_compaction(&history, self.config.compaction_threshold) {
                tracing::info!(
                    history_len = history.len(),
                    threshold = self.config.compaction_threshold,
                    "Triggering auto-compaction"
                );

                match compaction::compact_history(
                    &mut history,
                    callable,
                    self.config.compaction_keep_recent,
                )
                .await
                {
                    Ok(true) => {
                        tracing::info!(new_len = history.len(), "History compacted successfully");
                    }
                    Ok(false) => {
                        tracing::debug!("Compaction skipped (not enough messages)");
                    }
                    Err(e) => {
                        // Compaction failure is non-fatal — log and continue
                        tracing::warn!(error = %e, "History compaction failed, continuing");
                    }
                }
            }

            // ── Checkpoint at intervals ──
            if let Some(interval) = self.config.checkpoint_interval {
                if (iteration + 1) % interval == 0 {
                    let state = enact_core::graph::NodeState::from_string(&last_output);
                    if let Err(e) = self
                        .runner
                        .save_checkpoint(state, Some(callable.name()), Some(callable.name()))
                        .await
                    {
                        tracing::warn!(error = %e, "Failed to save checkpoint, continuing");
                    } else {
                        tracing::debug!(iteration, "Checkpoint saved");
                    }
                }
            }
        }

        // Max iterations reached
        tracing::warn!(max = self.config.max_iterations, "Max iterations reached");

        // Hooks: SessionEnd / Stop
        if let Some(ref reg) = self.hook_registry {
            let mut ctx = serde_json::json!({
                "event": "SessionEnd",
                "execution_id": self.runner.execution_id().as_str(),
                "outcome": "max_iterations",
                "output": last_output,
            });
            self.execute_hooks(reg, HookEvent::SessionEnd, None, &mut ctx, callable)
                .await;
            self.execute_hooks(reg, HookEvent::Stop, None, &mut ctx, callable)
                .await;
        }

        if self.config.emit_events {
            let duration = start_time.elapsed().as_millis() as u64;
            self.runner.emitter().emit(StreamEvent::execution_end(
                self.runner.execution_id(),
                Some(last_output.clone()),
                duration,
            ));
        }

        Ok(LoopOutcome::MaxIterationsReached {
            last_output,
            iterations: self.config.max_iterations,
        })
    }

    /// Build the input string for a given iteration from history.
    ///
    /// Concatenates all history messages into a single prompt string.
    fn build_iteration_input(&self, history: &[HistoryMessage]) -> String {
        history
            .iter()
            .map(|m| format!("{}: {}", m.role, m.content))
            .collect::<Vec<_>>()
            .join("\n\n")
    }

    async fn load_mcp_tools_at_session_start(&mut self) {
        match enact_mcp::discover_mcp_tools().await {
            Ok(mcp_tools) if !mcp_tools.is_empty() => {
                let existing: std::collections::HashSet<String> =
                    self.tools.iter().map(|t| t.name().to_string()).collect();
                let mut added = 0usize;
                for tool in mcp_tools {
                    if !existing.contains(tool.name()) {
                        self.tools.push(tool);
                        added += 1;
                    }
                }
                if added > 0 {
                    tracing::debug!("Added {} MCP tool(s) at session start", added);
                }
            }
            Ok(_) => {}
            Err(e) => tracing::warn!("MCP discovery at session start failed: {}", e),
        }
    }

    async fn execute_hooks(
        &self,
        reg: &HookRegistry,
        event: HookEvent,
        tool_name: Option<&str>,
        ctx: &mut serde_json::Value,
        callable: &dyn Callable,
    ) {
        for hook in reg.hooks_for_event(event, tool_name) {
            if hook.async_mode {
                // async_mode is fire-and-forget for non-blocking lifecycle events.
                if let HookHandler::Command { script } = &hook.handler {
                    let script = script.clone();
                    let context = ctx.clone();
                    let registry = reg.clone();
                    tokio::spawn(async move {
                        let _ = registry.run_command_handler(&script, &context).await;
                    });
                    continue;
                }
            }
            let _ = self.execute_single_hook(reg, hook, ctx, callable).await;
        }
    }

    async fn execute_pre_tool_hooks(
        &self,
        reg: &HookRegistry,
        tool_name: Option<&str>,
        ctx: &serde_json::Value,
        callable: &dyn Callable,
    ) -> HookDecision {
        let mut latest_mutation: Option<HookDecision> = None;
        for hook in reg.hooks_for_event(HookEvent::PreToolUse, tool_name) {
            if hook.async_mode {
                // PreToolUse async hooks cannot authoritatively block/mutate.
                if let HookHandler::Command { script } = &hook.handler {
                    let script = script.clone();
                    let context = ctx.clone();
                    let registry = reg.clone();
                    tokio::spawn(async move {
                        let _ = registry.run_command_handler(&script, &context).await;
                    });
                }
                continue;
            }
            match self
                .execute_single_pre_tool_hook(reg, hook, ctx, callable)
                .await
            {
                HookDecision::Allow => {}
                HookDecision::Block { reason } => return HookDecision::Block { reason },
                HookDecision::Mutate { arguments, reason } => {
                    latest_mutation = Some(HookDecision::Mutate { arguments, reason });
                }
            }
        }
        latest_mutation.unwrap_or(HookDecision::Allow)
    }

    async fn execute_single_hook(
        &self,
        reg: &HookRegistry,
        hook: &enact_config::HookConfig,
        ctx: &serde_json::Value,
        callable: &dyn Callable,
    ) -> bool {
        match &hook.handler {
            HookHandler::Command { script } => reg
                .run_command_handler(script, ctx)
                .await
                .map(|r| r.success)
                .unwrap_or(true),
            HookHandler::Prompt { template } => {
                let rendered = render_template(template, ctx);
                callable.run(&rendered).await.is_ok()
            }
            HookHandler::Agent { agent_name } => {
                let prompt = format!("Hook agent '{}' validation context: {}", agent_name, ctx);
                callable.run(&prompt).await.is_ok()
            }
        }
    }

    async fn execute_single_pre_tool_hook(
        &self,
        reg: &HookRegistry,
        hook: &enact_config::HookConfig,
        ctx: &serde_json::Value,
        callable: &dyn Callable,
    ) -> HookDecision {
        match &hook.handler {
            HookHandler::Command { script } => {
                let Ok(result) = reg.run_command_handler(script, ctx).await else {
                    return HookDecision::Allow;
                };
                parse_command_hook_decision(&result.stdout, result.success)
            }
            HookHandler::Prompt { template } => {
                let rendered = render_template(template, ctx);
                let Ok(output) = callable.run(&rendered).await else {
                    return HookDecision::Allow;
                };
                parse_model_hook_decision(&output)
            }
            HookHandler::Agent { agent_name } => {
                let prompt = format!(
                    "Return ONLY JSON hook decision for this context. Agent '{}': {}",
                    agent_name, ctx
                );
                let Ok(output) = callable.run(&prompt).await else {
                    return HookDecision::Allow;
                };
                parse_model_hook_decision(&output)
            }
        }
    }
}

/// Build context string from skills that match the user prompt (progressive Level 2).
/// Returns concatenated skill bodies to prepend to the first user message.
fn build_skill_context(project_dir: Option<&Path>, prompt: &str) -> String {
    let metas = load_skill_metas(project_dir);
    if metas.is_empty() {
        return String::new();
    }
    let matched = find_matching_skills(prompt, &metas);
    let mut parts = Vec::new();
    for meta in matched {
        if let Ok(body) = load_skill_body(&meta) {
            let mut section = format!("## Skill: {}\n\n{}", meta.name, body);
            let resources =
                load_skill_resources(&meta, &body, project_dir, SkillResourceLimits::default());
            if !resources.is_empty() {
                section.push_str("\n\n### Skill Resources\n");
                for resource in resources {
                    section.push_str(&format!(
                        "\n#### {}\n\n```\n{}\n```\n",
                        resource.path.display(),
                        resource.content
                    ));
                }
            }
            parts.push(section);
        }
    }
    if parts.is_empty() {
        return String::new();
    }
    format!(
        "<!-- Matched skills for this request -->\n\n{}\n\n---\n\n",
        parts.join("\n\n---\n\n")
    )
}

fn build_manual_skill_input(project_dir: Option<&Path>, raw_input: &str) -> Option<String> {
    let (name, args) = parse_slash_invocation(raw_input)?;
    let meta = find_skill_by_name(project_dir, &name)?;
    let body = load_skill_body(&meta).ok()?;
    let mut section = format!("## Skill: {}\n\n{}", meta.name, body);
    let resources = load_skill_resources(&meta, &body, project_dir, SkillResourceLimits::default());
    if !resources.is_empty() {
        section.push_str("\n\n### Skill Resources\n");
        for resource in resources {
            section.push_str(&format!(
                "\n#### {}\n\n```\n{}\n```\n",
                resource.path.display(),
                resource.content
            ));
        }
    }
    let user_request = if args.trim().is_empty() {
        "Follow this skill for the current task.".to_string()
    } else {
        args
    };
    Some(format!(
        "<!-- Manually invoked skill -->\n\n{}\n\n---\n\n{}",
        section, user_request
    ))
}

fn parse_command_hook_decision(stdout: &str, success: bool) -> HookDecision {
    if let Some(parsed) = parse_hook_decision(stdout) {
        return parsed;
    }
    if success {
        HookDecision::Allow
    } else {
        HookDecision::Block { reason: None }
    }
}

fn parse_model_hook_decision(output: &str) -> HookDecision {
    parse_hook_decision(output).unwrap_or(HookDecision::Allow)
}

fn parse_hook_decision(raw: &str) -> Option<HookDecision> {
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return None;
    }
    if let Ok(d) = serde_json::from_str::<HookDecision>(trimmed) {
        return Some(d);
    }
    extract_json_object(trimmed).and_then(|s| serde_json::from_str::<HookDecision>(&s).ok())
}

fn extract_json_object(s: &str) -> Option<String> {
    let start = s.find('{')?;
    let end = s.rfind('}')?;
    if end <= start {
        return None;
    }
    Some(s[start..=end].to_string())
}

fn render_template(template: &str, ctx: &serde_json::Value) -> String {
    let mut out = template.to_string();
    if let Some(obj) = ctx.as_object() {
        for (k, v) in obj {
            let replacement = if v.is_string() {
                v.as_str().unwrap_or_default().to_string()
            } else {
                v.to_string()
            };
            out = out.replace(&format!("{{{{{}}}}}", k), &replacement);
        }
    }
    out
}

/// Convenience: create an `AgentRunner` with default in-memory checkpoint store.
pub type DefaultAgentRunner = AgentRunner<enact_core::graph::InMemoryCheckpointStore>;

impl DefaultAgentRunner {
    /// Create a new `AgentRunner` with default in-memory store and default config.
    pub fn default_new() -> Self {
        Self::new(
            enact_core::runner::DefaultRunner::default_new(),
            RunnerConfig::default(),
        )
    }

    /// Create with a specific config.
    pub fn with_config(config: RunnerConfig) -> Self {
        Self::new(enact_core::runner::DefaultRunner::default_new(), config)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use async_trait::async_trait;
    use enact_core::callable::Callable;
    use enact_core::tool::Tool;
    use serde_json::json;
    use std::fs;
    use std::sync::{
        atomic::{AtomicUsize, Ordering},
        Arc,
    };
    use tokio::sync::Mutex;

    #[test]
    fn parse_command_hook_decision_falls_back_to_exit_status() {
        let allow = parse_command_hook_decision("", true);
        assert!(matches!(allow, HookDecision::Allow));

        let block = parse_command_hook_decision("", false);
        assert!(matches!(block, HookDecision::Block { .. }));
    }

    #[test]
    fn parse_model_hook_decision_handles_json_block() {
        let decision =
            parse_model_hook_decision(r#"{"decision":"block","reason":"unsafe operation"}"#);
        assert!(matches!(
            decision,
            HookDecision::Block {
                reason: Some(ref r)
            } if r == "unsafe operation"
        ));
    }

    #[test]
    fn build_manual_skill_input_loads_skill_body() {
        let project = tempfile::tempdir().unwrap();
        let skill_dir = project.path().join(".enact").join("skills").join("review");
        fs::create_dir_all(&skill_dir).unwrap();
        fs::write(
            skill_dir.join("SKILL.md"),
            "---\nname: review\ndescription: Review code\nversion: 0.1.0\n---\nAlways list findings.\n",
        )
        .unwrap();

        let injected =
            build_manual_skill_input(Some(project.path()), "/review inspect this").unwrap();
        assert!(injected.contains("Skill: review"));
        assert!(injected.contains("inspect this"));
    }

    struct MockCallable {
        calls: AtomicUsize,
        first: String,
        rest: String,
    }

    #[async_trait]
    impl Callable for MockCallable {
        fn name(&self) -> &str {
            "mock"
        }

        async fn run(&self, _input: &str) -> anyhow::Result<String> {
            let idx = self.calls.fetch_add(1, Ordering::SeqCst);
            if idx == 0 {
                Ok(self.first.clone())
            } else {
                Ok(self.rest.clone())
            }
        }
    }

    struct CaptureTool {
        seen: Arc<Mutex<Option<serde_json::Value>>>,
    }

    #[async_trait]
    impl Tool for CaptureTool {
        fn name(&self) -> &str {
            "capture_tool"
        }

        fn description(&self) -> &str {
            "capture"
        }

        fn parameters_schema(&self) -> serde_json::Value {
            json!({"type":"object"})
        }

        async fn execute(&self, args: serde_json::Value) -> anyhow::Result<serde_json::Value> {
            *self.seen.lock().await = Some(args);
            Ok(json!({"ok": true}))
        }
    }

    #[tokio::test]
    async fn pre_tool_mutation_updates_tool_arguments() {
        let temp = tempfile::tempdir().unwrap();
        let hooks_path = temp.path().join("hooks.yaml");
        fs::write(
            &hooks_path,
            r#"hooks:
  - event: PreToolUse
    matcher: "capture_tool"
    handler:
      type: command
      script: "echo '{\"decision\":\"mutate\",\"arguments\":{\"value\":\"mutated\"}}'"
"#,
        )
        .unwrap();
        std::env::set_var(
            "ENACT_HOOKS_CONFIG_PATH",
            hooks_path.to_string_lossy().as_ref(),
        );

        let seen = Arc::new(Mutex::new(None));
        let tool = CaptureTool {
            seen: Arc::clone(&seen),
        };
        let callable = MockCallable {
            calls: AtomicUsize::new(0),
            first: r#"{"tool_call":{"name":"capture_tool","arguments":{"value":"original"}}}"#
                .to_string(),
            rest: "done".to_string(),
        };

        let mut runner = DefaultAgentRunner::default_new()
            .add_tool(tool)
            .with_hook_registry(Arc::new(HookRegistry::load_global_and_agent(None, None)));
        let result = runner.run(&callable, "test", None).await.unwrap();
        std::env::remove_var("ENACT_HOOKS_CONFIG_PATH");

        assert!(matches!(result, LoopOutcome::Completed(_)));
        let captured = seen.lock().await.clone().unwrap();
        assert_eq!(captured, json!({"value":"mutated"}));
    }

    #[tokio::test]
    async fn prompt_and_agent_hooks_dispatch_callable() {
        let reg = HookRegistry::new();
        let runner = DefaultAgentRunner::default_new();
        let callable = MockCallable {
            calls: AtomicUsize::new(0),
            first: r#"{"decision":"allow"}"#.to_string(),
            rest: r#"{"decision":"allow"}"#.to_string(),
        };
        let ctx = json!({"tool_name":"capture_tool","arguments":{"v":1}});

        let prompt = enact_config::HookConfig {
            event: HookEvent::PreToolUse,
            matcher: None,
            handler: HookHandler::Prompt {
                template: "Decide for {{tool_name}}".to_string(),
            },
            async_mode: false,
        };
        let agent = enact_config::HookConfig {
            event: HookEvent::PreToolUse,
            matcher: None,
            handler: HookHandler::Agent {
                agent_name: "reviewer".to_string(),
            },
            async_mode: false,
        };

        let p = runner
            .execute_single_pre_tool_hook(&reg, &prompt, &ctx, &callable)
            .await;
        let a = runner
            .execute_single_pre_tool_hook(&reg, &agent, &ctx, &callable)
            .await;

        assert!(matches!(p, HookDecision::Allow));
        assert!(matches!(a, HookDecision::Allow));
        assert_eq!(callable.calls.load(Ordering::SeqCst), 2);
    }
}