atman_runtime/tools/

term.rs

#![allow(dead_code)]

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use std::time::Instant;

use tokio::sync::broadcast;
use tokio::task::JoinHandle;

use crate::error::RuntimeError;

pub const DEFAULT_ROWS: u16 = 24;
pub const DEFAULT_COLS: u16 = 80;
const STREAM_CHANNEL_CAPACITY: usize = 256;

#[derive(Debug, Clone, Hash, PartialEq, Eq)]
pub struct TermHandle {
    pub session_id: String,
    pub local_id: u64,
}

impl TermHandle {
    pub fn parse(s: &str) -> Option<Self> {
        let rest = s.strip_prefix("term_")?;
        let idx = rest.rfind('_')?;
        let session_id = rest[..idx].to_string();
        let local_id = rest[idx + 1..].parse().ok()?;
        Some(Self {
            session_id,
            local_id,
        })
    }
}

impl std::fmt::Display for TermHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "term_{}_{}", self.session_id, self.local_id)
    }
}

#[derive(Debug, Clone)]
pub enum TermState {
    Running {
        pid: u32,
        started_at: u64,
    },
    Exited {
        exit_code: Option<i32>,
        ended_at: u64,
    },
    Failed {
        error: String,
        ended_at: u64,
    },
    Killed {
        ended_at: u64,
    },
}

impl TermState {
    pub fn is_running(&self) -> bool {
        matches!(self, TermState::Running { .. })
    }

    pub fn to_snapshot(&self) -> TermStateSnapshot {
        match self {
            TermState::Running { .. } => TermStateSnapshot::Running,
            TermState::Exited { exit_code, .. } => TermStateSnapshot::Exited {
                exit_code: *exit_code,
            },
            TermState::Failed { error, .. } => TermStateSnapshot::Failed {
                error: error.clone(),
            },
            TermState::Killed { .. } => TermStateSnapshot::Killed,
        }
    }
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind")]
pub enum TermStateSnapshot {
    Running,
    Exited { exit_code: Option<i32> },
    Failed { error: String },
    Killed,
}

#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct TerminalScreen {
    pub rows: u16,
    pub cols: u16,
    pub cells: Vec<TerminalCell>,
    pub cursor: Option<(u16, u16)>,
    pub alt_screen: bool,
}

#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct TerminalCell {
    pub chars: String,
    pub fg: TerminalColor,
    pub bg: TerminalColor,
    pub bold: bool,
    pub italic: bool,
    pub underline: bool,
    pub inverse: bool,
    pub dim: bool,
    pub wide: bool,
    #[serde(default)]
    pub wide_continuation: bool,
}

impl Default for TerminalCell {
    fn default() -> Self {
        Self {
            chars: String::new(),
            fg: TerminalColor::Default,
            bg: TerminalColor::Default,
            bold: false,
            italic: false,
            underline: false,
            inverse: false,
            dim: false,
            wide: false,
            wide_continuation: false,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum TerminalColor {
    Default,
    Idx(u8),
    Rgb(u8, u8, u8),
}

impl From<vt100::Color> for TerminalColor {
    fn from(c: vt100::Color) -> Self {
        match c {
            vt100::Color::Default => TerminalColor::Default,
            vt100::Color::Idx(i) => TerminalColor::Idx(i),
            vt100::Color::Rgb(r, g, b) => TerminalColor::Rgb(r, g, b),
        }
    }
}

pub fn snapshot_screen(parser: &vt100::Parser) -> TerminalScreen {
    let screen = parser.screen();
    let (rows, cols) = screen.size();
    let mut cells = Vec::with_capacity(rows as usize * cols as usize);
    for row in 0..rows {
        for col in 0..cols {
            if let Some(c) = screen.cell(row, col) {
                cells.push(TerminalCell {
                    chars: c.contents().to_string(),
                    fg: c.fgcolor().into(),
                    bg: c.bgcolor().into(),
                    bold: c.bold(),
                    italic: c.italic(),
                    underline: c.underline(),
                    inverse: c.inverse(),
                    dim: c.dim(),
                    wide: c.is_wide(),
                    wide_continuation: c.is_wide_continuation(),
                });
            } else {
                cells.push(TerminalCell::default());
            }
        }
    }
    let cursor = if screen.hide_cursor() {
        None
    } else {
        Some(screen.cursor_position())
    };
    TerminalScreen {
        rows,
        cols,
        cells,
        cursor,
        alt_screen: screen.alternate_screen(),
    }
}

/// Parse a string containing ANSI escape sequences into a [TerminalScreen].
///
/// Used by the TUI to render ` ```ansi ` code blocks with real colors.
/// cols is sized to the widest line (clamped 80..=256) so nothing wraps.
///
/// `\n` is upgraded to `\r\n` because vt100 treats bare LF as "line feed"
/// (move down, keep column) — most ANSI output expects carriage return too.
/// Trailing newlines are stripped so they don't trigger a scroll that
/// pushes the first line off the visible screen.
pub fn parse_ansi_to_screen(body: &str) -> TerminalScreen {
    let body = body.strip_suffix('\n').unwrap_or(body);
    let lines: Vec<&str> = body.split('\n').collect();
    let rows = lines.len().max(1) as u16;
    let cols = lines
        .iter()
        .map(|l| l.chars().count())
        .max()
        .unwrap_or(0)
        .clamp(80, 256) as u16;
    let mut parser = vt100::Parser::new(rows, cols, 0);
    for (i, line) in lines.iter().enumerate() {
        if i > 0 {
            parser.process(b"\r\n");
        }
        parser.process(line.as_bytes());
    }
    snapshot_screen(&parser)
}

#[derive(Debug, Clone)]
pub enum TermStreamEvent {
    Chunk {
        bytes: Vec<u8>,
        screen: TerminalScreen,
        state: TermState,
    },
    Exited {
        exit_code: Option<i32>,
    },
}

pub struct TermEntry {
    pub handle: TermHandle,
    pub session_id: String,
    pub pty_size: portable_pty::PtySize,
    pub parser: Arc<Mutex<vt100::Parser>>,
    pub writer: Mutex<Box<dyn std::io::Write + Send>>,
    pub state: Arc<Mutex<TermState>>,
    pub stream_tx: broadcast::Sender<TermStreamEvent>,
    pub log_path: PathBuf,
    pub reader_task: Mutex<Option<JoinHandle<()>>>,
    pub child: Mutex<Option<Box<dyn portable_pty::Child + Send + Sync>>>,
    pub master: Mutex<Option<Box<dyn portable_pty::MasterPty + Send>>>,
    profile: Arc<Mutex<Option<crate::sandbox::TempProfile>>>,
    pub started_at: Instant,
    pub task_id: Mutex<Option<crate::task_registry::TaskId>>,
}

impl TermEntry {
    pub fn snapshot(&self) -> TerminalScreen {
        let parser = self.parser.lock().expect("parser poisoned");
        snapshot_screen(&parser)
    }

    pub fn current_state(&self) -> TermState {
        self.state.lock().expect("state poisoned").clone()
    }

    pub fn resize(&self, rows: u16, cols: u16) -> Result<(), RuntimeError> {
        {
            let mut parser = self.parser.lock().expect("parser poisoned");
            parser.screen_mut().set_size(rows, cols);
        }
        let master = self.master.lock().expect("master poisoned");
        if let Some(master) = master.as_ref() {
            master
                .resize(portable_pty::PtySize {
                    rows,
                    cols,
                    pixel_width: 0,
                    pixel_height: 0,
                })
                .map_err(|e| RuntimeError::ToolFailed(format!("term resize: pty resize: {e}")))?;
        }
        Ok(())
    }
}

#[derive(Default)]
pub struct TermRegistry {
    entries: Mutex<HashMap<String, Arc<TermEntry>>>,
    task_registry: Option<crate::task_registry::TaskRegistry>,
}

impl TermRegistry {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_task_registry(mut self, tr: crate::task_registry::TaskRegistry) -> Self {
        self.task_registry = Some(tr);
        self
    }

    pub fn next_handle(&self, session_id: &str) -> TermHandle {
        let local_id = uuid::Uuid::now_v7().as_u64_pair().0;
        TermHandle {
            session_id: session_id.to_string(),
            local_id,
        }
    }

    pub fn insert(&self, entry: Arc<TermEntry>) {
        let key = entry.handle.to_string();
        self.entries
            .lock()
            .expect("entries poisoned")
            .insert(key, entry);
    }

    pub fn get(&self, handle_str: &str) -> Option<Arc<TermEntry>> {
        self.entries
            .lock()
            .expect("entries poisoned")
            .get(handle_str)
            .cloned()
    }

    pub fn kill_all(&self) {
        let entries = self.entries.lock().expect("entries poisoned");
        for (_, entry) in entries.iter() {
            let mut child = entry.child.lock().expect("child poisoned");
            if let Some(child) = child.as_mut() {
                let _ = child.kill();
            }
            entry.profile.lock().expect("profile poisoned").take();
        }
    }

    pub fn lookup(
        &self,
        handle_str: &str,
        session_id: &str,
    ) -> Result<Arc<TermEntry>, RuntimeError> {
        let handle = TermHandle::parse(handle_str).ok_or_else(|| {
            RuntimeError::ToolFailed(format!("term: invalid handle: {handle_str}"))
        })?;
        if handle.session_id != session_id {
            return Err(RuntimeError::ToolFailed(format!(
                "term: handle {handle_str} does not belong to session {session_id}"
            )));
        }
        self.get(handle_str).ok_or_else(|| {
            RuntimeError::ToolFailed(format!("term: handle not found: {handle_str}"))
        })
    }

    pub fn list(&self, session_id: &str) -> Vec<(String, TermState)> {
        self.entries
            .lock()
            .expect("entries poisoned")
            .iter()
            .filter(|(_, e)| e.session_id == session_id)
            .map(|(k, e)| (k.clone(), e.current_state()))
            .collect()
    }
}

fn now_ms() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
}

const READ_BUF_SIZE: usize = 4096;

fn open_term_log(path: &Path) -> std::io::Result<std::fs::File> {
    std::fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(path)
}

impl TermRegistry {
    #[allow(clippy::too_many_arguments)]
    pub fn spawn_entry(
        self: &Arc<Self>,
        rows: u16,
        cols: u16,
        session_id: String,
        session_dir: PathBuf,
        pty_result: crate::sandbox::PtySpawnResult,
        tui_stream_tx: Option<tokio::sync::broadcast::Sender<crate::stream::StreamFrame>>,
        label: String,
        command: String,
        call_intent: Option<crate::message::ToolCallIntent>,
        cancel: tokio_util::sync::CancellationToken,
        events: Option<crate::event::EventSink>,
        flow_run_id: Option<String>,
    ) -> Result<(TermHandle, Arc<TermEntry>), RuntimeError> {
        self.spawn_entry_with_log_opener(
            rows,
            cols,
            session_id,
            session_dir,
            pty_result,
            tui_stream_tx,
            label,
            command,
            call_intent,
            cancel,
            events,
            flow_run_id,
            open_term_log,
        )
    }

    #[allow(clippy::too_many_arguments)]
    fn spawn_entry_with_log_opener<F>(
        self: &Arc<Self>,
        rows: u16,
        cols: u16,
        session_id: String,
        session_dir: PathBuf,
        pty_result: crate::sandbox::PtySpawnResult,
        tui_stream_tx: Option<tokio::sync::broadcast::Sender<crate::stream::StreamFrame>>,
        label: String,
        command: String,
        call_intent: Option<crate::message::ToolCallIntent>,
        cancel: tokio_util::sync::CancellationToken,
        events: Option<crate::event::EventSink>,
        flow_run_id: Option<String>,
        open_log: F,
    ) -> Result<(TermHandle, Arc<TermEntry>), RuntimeError>
    where
        F: FnOnce(&Path) -> std::io::Result<std::fs::File>,
    {
        let handle = self.next_handle(&session_id);
        let handle_str = handle.to_string();

        let crate::sandbox::PtySpawnResult {
            mut child,
            reader,
            writer,
            master,
            profile,
        } = pty_result;

        if let Err(error) = std::fs::create_dir_all(&session_dir) {
            crate::sandbox::terminate_pty_child(child.as_mut());
            return Err(RuntimeError::ToolFailed(format!(
                "term.spawn: create session_dir: {error}"
            )));
        }
        let log_path = session_dir.join(format!("term_{}.log", handle_str));

        let parser = vt100::Parser::new(rows, cols, 0);
        let parser = Arc::new(Mutex::new(parser));
        let state = Arc::new(Mutex::new(TermState::Running {
            pid: 0,
            started_at: now_ms(),
        }));
        let (stream_tx, _stream_rx) = broadcast::channel(STREAM_CHANNEL_CAPACITY);
        let log_file = match open_log(&log_path) {
            Ok(file) => file,
            Err(error) => {
                crate::sandbox::terminate_pty_child(child.as_mut());
                return Err(RuntimeError::ToolFailed(format!(
                    "term.spawn: open log: {error}"
                )));
            }
        };

        let profile = Arc::new(Mutex::new(profile));
        let entry = Arc::new(TermEntry {
            handle: handle.clone(),
            session_id: session_id.clone(),
            pty_size: portable_pty::PtySize {
                rows,
                cols,
                pixel_width: 0,
                pixel_height: 0,
            },
            parser: parser.clone(),
            writer: Mutex::new(writer),
            state: state.clone(),
            stream_tx: stream_tx.clone(),
            log_path: log_path.clone(),
            reader_task: Mutex::new(None),
            child: Mutex::new(Some(child)),
            master: Mutex::new(Some(master)),
            profile: profile.clone(),
            started_at: Instant::now(),
            task_id: Mutex::new(None),
        });

        let kill_entry = entry.clone();
        let task_id = self.task_registry.as_ref().map(|tr| {
            let hook: std::sync::Arc<dyn Fn() + Send + Sync> = std::sync::Arc::new(move || {
                let mut child = kill_entry.child.lock().expect("child poisoned");
                if let Some(child) = child.as_mut() {
                    let _ = child.kill();
                }
                kill_entry.profile.lock().expect("profile poisoned").take();
            });
            tr.register_with_kill_hook(
                crate::task_registry::TaskKind::Terminal,
                crate::task_registry::TaskDisplay {
                    label,
                    command: Some(command),
                },
                handle_str.clone(),
                session_id.clone(),
                cancel,
                Some(hook),
            )
        });
        *entry.task_id.lock().unwrap() = task_id.clone();

        let handle_for_loop = handle_str.clone();
        let task_registry = self.task_registry.clone();
        let join = tokio::task::spawn_blocking(move || {
            run_reader_loop(
                reader,
                parser,
                state,
                stream_tx,
                log_file,
                tui_stream_tx,
                handle_for_loop,
                task_registry,
                task_id,
                events,
                flow_run_id,
                call_intent,
                profile,
            );
        });
        *entry.reader_task.lock().expect("reader_task poisoned") = Some(join);

        self.insert(entry.clone());
        Ok((handle, entry))
    }
}

impl Drop for TermRegistry {
    fn drop(&mut self) {
        self.kill_all();
    }
}

#[allow(clippy::too_many_arguments)]
fn run_reader_loop(
    mut reader: Box<dyn std::io::Read + Send>,
    parser: Arc<Mutex<vt100::Parser>>,
    state: Arc<Mutex<TermState>>,
    stream_tx: broadcast::Sender<TermStreamEvent>,
    mut log_file: std::fs::File,
    tui_stream_tx: Option<tokio::sync::broadcast::Sender<crate::stream::StreamFrame>>,
    handle: String,
    task_registry: Option<crate::task_registry::TaskRegistry>,
    task_id: Option<crate::task_registry::TaskId>,
    events_sink: Option<crate::event::EventSink>,
    flow_run_id: Option<String>,
    call_intent: Option<crate::message::ToolCallIntent>,
    profile: Arc<Mutex<Option<crate::sandbox::TempProfile>>>,
) {
    let mut buf = [0u8; READ_BUF_SIZE];
    let mut last_screen: Option<TerminalScreen> = None;
    loop {
        match reader.read(&mut buf) {
            Ok(0) => break,
            Ok(n) => {
                let chunk = &buf[..n];
                let _ = log_file.write_all(chunk);
                let screen = {
                    let mut p = parser.lock().expect("parser poisoned");
                    p.process(chunk);
                    snapshot_screen(&p)
                };
                let screen_changed = last_screen.as_ref() != Some(&screen);
                let st = state.lock().expect("state poisoned").clone();
                let _ = stream_tx.send(TermStreamEvent::Chunk {
                    bytes: chunk.to_vec(),
                    screen: screen.clone(),
                    state: st.clone(),
                });
                if let Some(tx) = &tui_stream_tx {
                    let tui_screen = if screen_changed {
                        last_screen = Some(screen.clone());
                        Some(screen)
                    } else {
                        None
                    };
                    let _ = tx.send(crate::stream::StreamFrame::TerminalChunk {
                        handle: handle.clone(),
                        bytes: chunk.to_vec(),
                        screen: tui_screen,
                        state: st.to_snapshot(),
                        call_intent: call_intent.clone(),
                        run_id: flow_run_id.clone(),
                    });
                }
            }
            Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
            Err(_) => break,
        }
    }

    let exit_code = None;
    {
        let mut s = state.lock().expect("state poisoned");
        // Only transition to Exited if not already Killed — term.kill sets
        // Killed before the reader loop observes the closed PTY.
        if matches!(*s, TermState::Running { .. }) {
            *s = TermState::Exited {
                exit_code,
                ended_at: now_ms(),
            };
        }
    }

    // Persist the last screen state before notifying exit — restore reads this
    // to recover the full cell grid (with colors) that stream frames never wrote.
    if let Some(sink) = &events_sink {
        let (final_screen, final_state) = {
            let p = parser.lock().expect("parser poisoned");
            let screen = snapshot_screen(&p);
            let st = state.lock().expect("state poisoned").to_snapshot();
            (screen, st)
        };
        sink.emit(crate::event::Event::TerminalFinalState {
            handle: handle.clone(),
            screen: final_screen,
            state: final_state,
        });
    }

    let _ = stream_tx.send(TermStreamEvent::Exited { exit_code });
    if let Some(tx) = &tui_stream_tx {
        let _ = tx.send(crate::stream::StreamFrame::TerminalExited {
            handle,
            exit_code,
            call_intent,
            run_id: flow_run_id,
        });
    }

    profile.lock().expect("profile poisoned").take();
    if let (Some(tr), Some(tid)) = (task_registry, task_id) {
        tr.finish(&tid, crate::task_registry::TaskStatus::Ok);
    }
}

use std::io::Write;

use std::path::Path;

use crate::sandbox::PtySpawnResult;
use crate::tool::{Tier, Tool};
use crate::value::Value;

fn extract_string(
    args: &crate::tool::ToolArgs,
    name: &str,
    pos: usize,
) -> Result<String, RuntimeError> {
    if let Some(v) = args.named(name) {
        if let Value::Str(s) = v {
            return Ok(s.clone());
        }
        return Err(RuntimeError::ToolFailed(format!(
            "term: arg {name} must be string"
        )));
    }
    if let Ok(Value::Str(s)) = args.positional(pos) {
        return Ok(s.clone());
    }
    Err(RuntimeError::MissingArg(format!("term: {name}")))
}

fn extract_optional_string(args: &crate::tool::ToolArgs, name: &str) -> Option<String> {
    args.named(name).and_then(|v| {
        if let Value::Str(s) = v {
            Some(s.clone())
        } else {
            None
        }
    })
}

fn extract_optional_int(args: &crate::tool::ToolArgs, name: &str) -> Option<i64> {
    args.named(name).and_then(|v| {
        if let Value::Int(i) = v {
            Some(*i)
        } else {
            None
        }
    })
}

pub struct TermSpawn;

impl Tool for TermSpawn {
    fn name(&self) -> &str {
        "term.spawn"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some(
            "Spawn a PTY-backed interactive terminal. Supports TUI apps (vim, top, ssh, codex).\nReturns handle + state + dimensions. Does NOT return screen content — use\nterm.capture to read the screen.\n\nTypical flow:\n1. term.spawn(cmd: \"your command\", rows: 24, cols: 80)\n2. term.input(handle: \"...\", text: \"ls -la\") or key: \"enter\"\n3. term.capture(handle: \"...\") — returns screen as text by default\n4. Repeat 2-3 as needed\n5. term.kill(handle: \"...\")",
        )
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "cmd": {"type": "string"},
                "rows": {"type": "integer", "default": 24},
                "cols": {"type": "integer", "default": 80},
                "cwd": {"type": "string"},
                "env": {"type": "object"}
            }
        })
    }
    fn invocation_provenance(
        &self,
        args: &crate::tool::ToolArgs,
        ctx: &crate::tool::ToolCtx,
    ) -> Result<crate::permission::ResourceProvenance, RuntimeError> {
        let explicit = extract_optional_string(args, "cwd").map(std::path::PathBuf::from);
        Ok(crate::permission::ResourceProvenance::for_ctx(ctx)
            .with_cwd(ctx, explicit.as_deref())?
            .with_risk(crate::trust::RiskKind::ProcessSpawn))
    }

    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move { spawn_impl(args, ctx).await })
    }
}

async fn spawn_impl(
    args: crate::tool::ToolArgs,
    ctx: &crate::tool::ToolCtx,
) -> crate::tool::ToolResult {
    let cmd_str = extract_optional_string(&args, "cmd");
    let rows = extract_optional_int(&args, "rows")
        .map(|v| v as u16)
        .unwrap_or(DEFAULT_ROWS)
        .max(1);
    let cols = extract_optional_int(&args, "cols")
        .map(|v| v as u16)
        .unwrap_or(DEFAULT_COLS)
        .max(2);
    let explicit_cwd = extract_optional_string(&args, "cwd").map(std::path::PathBuf::from);
    let cwd = ctx.resolve_cwd(explicit_cwd.as_deref())?;
    let env: Vec<(String, String)> = if let Some(Value::Struct(fields)) = args.named("env") {
        fields
            .iter()
            .filter_map(|(k, v)| {
                if let Value::Str(s) = v {
                    Some((k.clone(), s.clone()))
                } else {
                    None
                }
            })
            .collect()
    } else {
        Vec::new()
    };

    let registry = ctx
        .term_registry
        .clone()
        .ok_or_else(|| RuntimeError::ToolFailed("term.spawn: registry not available".into()))?;
    let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
    let session_dir = ctx
        .session_dir
        .clone()
        .ok_or_else(|| RuntimeError::ToolFailed("term.spawn: session_dir not available".into()))?;

    let pty_size = portable_pty::PtySize {
        rows,
        cols,
        pixel_width: 0,
        pixel_height: 0,
    };
    let default_shell = std::env::var("SHELL").unwrap_or_else(|_| "sh".into());
    let command = cmd_str.clone().unwrap_or_else(|| default_shell.clone());
    let cmd_args: Vec<&str> = if let Some(ref c) = cmd_str {
        vec!["sh", "-c", c.as_str()]
    } else {
        vec![default_shell.as_str()]
    };
    let env_refs: Vec<(String, String)> = env.clone();

    let authorization = ctx.invocation_authorization_for("term.spawn")?;
    let pty_result = match authorization.execution_boundary() {
        crate::permission::ExecutionBoundary::Sandboxed => {
            let sandbox = ctx.sandbox.as_ref().ok_or_else(|| {
                RuntimeError::ToolFailed(
                    "term.spawn: sandbox unavailable for controlled execution".into(),
                )
            })?;
            sandbox
                .spawn_pty(&cmd_args, &env_refs, &cwd, pty_size, authorization)
                .await
                .map_err(|error| error.into_runtime("term.spawn"))?
        }
        crate::permission::ExecutionBoundary::Direct => {
            spawn_pty_direct(&cmd_args, &env_refs, &cwd, pty_size)?
        }
    };

    let (handle, entry) = registry.spawn_entry(
        rows,
        cols,
        session_id,
        session_dir,
        pty_result,
        ctx.stream_tx.clone(),
        ctx.call_intent
            .as_ref()
            .map(|intent| intent.as_str().to_owned())
            .or(cmd_str)
            .unwrap_or_else(|| "terminal".into()),
        command,
        ctx.call_intent.clone(),
        {
            let tc = ctx.cancel.clone();
            tc.child_token()
        },
        ctx.events.clone(),
        ctx.flow_run_id.as_ref().map(|r| r.0.to_string()),
    )?;

    let state = entry.current_state();
    let text = {
        let parser = entry.parser.lock().expect("parser poisoned");
        parser.screen().contents()
    };
    Ok(Value::Struct(vec![
        ("handle".into(), Value::Str(handle.to_string())),
        ("state".into(), state_to_value(&state)),
        ("rows".into(), Value::Int(rows as i64)),
        ("cols".into(), Value::Int(cols as i64)),
        ("text".into(), Value::Str(text)),
    ]))
}

fn spawn_pty_direct(
    cmd: &[&str],
    env: &[(String, String)],
    cwd: &Path,
    pty_size: portable_pty::PtySize,
) -> Result<PtySpawnResult, RuntimeError> {
    let pty_system = portable_pty::native_pty_system();
    let pair = pty_system
        .openpty(pty_size)
        .map_err(|e| RuntimeError::ToolFailed(format!("openpty: {e}")))?;
    let mut builder = portable_pty::CommandBuilder::new(cmd[0]);
    for arg in &cmd[1..] {
        builder.arg(arg);
    }
    builder.cwd(cwd);
    for (k, v) in env {
        builder.env(k, v);
    }
    let child = pair
        .slave
        .spawn_command(builder)
        .map_err(|e| RuntimeError::ToolFailed(format!("pty spawn: {e}")))?;
    crate::sandbox::complete_pty_spawn(child, pair.master, None)
}

fn cell_text(screen: &TerminalScreen, row: u16, col: u16) -> String {
    let idx = (row as usize) * (screen.cols as usize) + (col as usize);
    match screen.cells.get(idx) {
        Some(cell) if cell.wide_continuation => String::new(),
        Some(cell) if cell.chars.is_empty() => " ".to_string(),
        Some(cell) => cell.chars.clone(),
        None => " ".to_string(),
    }
}

fn find_pattern_on_screen(screen: &TerminalScreen, pattern: &str) -> Option<(u16, u16)> {
    for r in 0..screen.rows {
        let row_text: String = (0..screen.cols)
            .map(|c| cell_text(screen, r, c))
            .collect::<String>()
            .trim_end()
            .to_string();
        if let Some(pos) = row_text.find(pattern) {
            return Some((r, pos as u16));
        }
    }
    None
}

impl crate::watch::Watchable for TermEntry {
    fn watch_output(
        self: std::sync::Arc<Self>,
        pattern: String,
        cancel: tokio_util::sync::CancellationToken,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = crate::watch::WatchResult> + Send>>
    {
        let stream_tx = self.stream_tx.clone();
        let state = self.state.clone();
        let parser = self.parser.clone();
        Box::pin(async move {
            // Subscribe BEFORE checking state — closes the TOCTOU window where
            // the terminal exits between the check and subscribe().
            let mut rx = stream_tx.subscribe();
            {
                let st = state.lock().unwrap().clone();
                if !st.is_running() {
                    let p = parser.lock().unwrap();
                    let screen = snapshot_screen(&p);
                    if let Some((r, c)) = find_pattern_on_screen(&screen, &pattern) {
                        return crate::watch::WatchResult::Matched {
                            row: Some(r),
                            col: Some(c),
                            text: pattern,
                        };
                    }
                    return crate::watch::WatchResult::SourceExited;
                }
            }
            loop {
                tokio::select! {
                    _ = cancel.cancelled() => return crate::watch::WatchResult::Cancelled,
                    result = rx.recv() => match result {
                        Ok(crate::tools::term::TermStreamEvent::Chunk { screen, .. }) => {
                            if let Some((r, c)) = find_pattern_on_screen(&screen, &pattern) {
                                return crate::watch::WatchResult::Matched {
                                    row: Some(r),
                                    col: Some(c),
                                    text: pattern,
                                };
                            }
                        }
                        _ => return crate::watch::WatchResult::SourceExited,
                    }
                }
            }
        })
    }
}

fn screen_to_value(screen: &TerminalScreen) -> Value {
    let cells: Vec<Value> = screen
        .cells
        .iter()
        .map(|c| {
            Value::Struct(vec![
                ("chars".into(), Value::Str(c.chars.clone())),
                ("fg".into(), color_to_value(c.fg)),
                ("bg".into(), color_to_value(c.bg)),
                ("bold".into(), Value::Bool(c.bold)),
                ("italic".into(), Value::Bool(c.italic)),
                ("underline".into(), Value::Bool(c.underline)),
                ("inverse".into(), Value::Bool(c.inverse)),
                ("dim".into(), Value::Bool(c.dim)),
                ("wide".into(), Value::Bool(c.wide)),
                ("wide_continuation".into(), Value::Bool(c.wide_continuation)),
            ])
        })
        .collect();
    Value::Struct(vec![
        ("rows".into(), Value::Int(screen.rows as i64)),
        ("cols".into(), Value::Int(screen.cols as i64)),
        ("cells".into(), Value::List(cells)),
        (
            "cursor".into(),
            match screen.cursor {
                Some((r, c)) => Value::Struct(vec![
                    ("row".into(), Value::Int(r as i64)),
                    ("col".into(), Value::Int(c as i64)),
                ]),
                None => Value::Unit,
            },
        ),
        ("alt_screen".into(), Value::Bool(screen.alt_screen)),
    ])
}

fn color_to_value(c: TerminalColor) -> Value {
    match c {
        TerminalColor::Default => Value::Str("default".into()),
        TerminalColor::Idx(i) => Value::Int(i as i64),
        TerminalColor::Rgb(r, g, b) => Value::Struct(vec![
            ("r".into(), Value::Int(r as i64)),
            ("g".into(), Value::Int(g as i64)),
            ("b".into(), Value::Int(b as i64)),
        ]),
    }
}

fn state_to_value(state: &TermState) -> Value {
    match state {
        TermState::Running { pid, started_at } => Value::Struct(vec![
            ("kind".into(), Value::Str("running".into())),
            ("pid".into(), Value::Int(*pid as i64)),
            ("started_at".into(), Value::Int(*started_at as i64)),
        ]),
        TermState::Exited {
            exit_code,
            ended_at,
        } => Value::Struct(vec![
            ("kind".into(), Value::Str("exited".into())),
            (
                "exit_code".into(),
                exit_code
                    .map(|c| Value::Int(c as i64))
                    .unwrap_or(Value::Unit),
            ),
            ("ended_at".into(), Value::Int(*ended_at as i64)),
        ]),
        TermState::Failed { error, ended_at } => Value::Struct(vec![
            ("kind".into(), Value::Str("failed".into())),
            ("error".into(), Value::Str(error.clone())),
            ("ended_at".into(), Value::Int(*ended_at as i64)),
        ]),
        TermState::Killed { ended_at } => Value::Struct(vec![
            ("kind".into(), Value::Str("killed".into())),
            ("ended_at".into(), Value::Int(*ended_at as i64)),
        ]),
    }
}

pub struct TermInput;
impl Tool for TermInput {
    fn name(&self) -> &str {
        "term.input"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some(
            "Send input to a terminal's PTY. Use `text` for literal text, `key` for\nspecial keys (enter, tab, esc, backspace, up, down, left, right, ctrl+c,\nctrl+d, ctrl+z), or `mouse` for mouse events. Use key: \"enter\" to\nsubmit a command, not text: \"\\r\". Mouse actions: click, double_click,\nlong_press, drag, press, release, move, scroll_up, scroll_down.\nUse term.find to locate text on screen before clicking.",
        )
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "handle": {"type": "string"},
                "text": {"type": "string", "description": "Literal text to write. Do NOT use \\r or \\n here — use key:\"enter\" instead."},
                "key": {"type": "string", "enum": ["enter", "tab", "esc", "backspace", "up", "down", "left", "right", "ctrl+c", "ctrl+d", "ctrl+z"]},
                "mouse": {
                    "type": "object",
                    "properties": {
                        "action": {
                            "type": "string",
                            "enum": ["click", "double_click", "long_press", "drag", "press", "release", "move", "scroll_up", "scroll_down"],
                            "description": "click=press+release, double_click=two clicks, long_press=press+500ms+release, drag=press+move+release (needs x2,y2), move=hover, scroll_up/down=wheel"
                        },
                        "button": {"type": "string", "enum": ["left", "right", "middle"], "default": "left"},
                        "x": {"type": "integer", "description": "Column (0-indexed, same as term.find col)"},
                        "y": {"type": "integer", "description": "Row (0-indexed, same as term.find row)"},
                        "x2": {"type": "integer", "description": "End column for drag"},
                        "y2": {"type": "integer", "description": "End row for drag"}
                    },
                    "required": ["action", "x", "y"],
                    "description": "Mouse event. Coordinates are 0-indexed — pass term.find (col,row) directly."
                }
            },
            "required": ["handle"]
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let handle = extract_string(&args, "handle", 0)?;
            let text = extract_optional_string(&args, "text").unwrap_or_default();
            let key = extract_optional_string(&args, "key");
            let mouse = args.named("mouse");
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.input: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let entry = registry.lookup(&handle, &session_id)?;

            // Build steps: (bytes, delay_after).
            let mut steps: Vec<(Vec<u8>, std::time::Duration)> = Vec::new();
            let mut first = text.into_bytes();
            if let Some(k) = &key {
                first.extend_from_slice(&key_to_bytes(k));
            }
            if !first.is_empty() {
                steps.push((first, std::time::Duration::ZERO));
            }
            if let Some(m) = &mouse {
                steps.extend(mouse_to_steps(m)?);
            }
            if steps.is_empty() {
                return Err(RuntimeError::ToolFailed(
                    "term.input: provide at least one of `text`, `key`, or `mouse`".into(),
                ));
            }

            let mut total = 0usize;
            for (payload, delay) in steps {
                if !payload.is_empty() {
                    let mut w = entry.writer.lock().expect("writer poisoned");
                    w.write_all(&payload)
                        .map_err(|e| RuntimeError::ToolFailed(format!("term.input write: {e}")))?;
                    total += payload.len();
                    drop(w);
                }
                if !delay.is_zero() {
                    tokio::time::sleep(delay).await;
                }
            }
            Ok(Value::Struct(vec![
                ("ok".into(), Value::Bool(true)),
                ("bytes_written".into(), Value::Int(total as i64)),
            ]))
        })
    }
}

fn key_to_bytes(key: &str) -> Vec<u8> {
    match key {
        "enter" => vec![b'\r'],
        "tab" => vec![b'\t'],
        "esc" => vec![0x1b],
        "backspace" => vec![0x7f],
        "up" => vec![0x1b, b'[', b'A'],
        "down" => vec![0x1b, b'[', b'B'],
        "right" => vec![0x1b, b'[', b'C'],
        "left" => vec![0x1b, b'[', b'D'],
        "ctrl+c" => vec![0x03],
        "ctrl+d" => vec![0x04],
        "ctrl+z" => vec![0x1a],
        _ => Vec::new(),
    }
}

/// SGR mouse bytes. Input coords are 0-indexed (term.find convention);
/// SGR protocol is 1-indexed so we +1 internally.
fn sgr(btn: u32, action: &str, col0: i64, row0: i64) -> Vec<u8> {
    let x = col0 + 1;
    let y = row0 + 1;
    match action {
        "press" => format!("\x1b[<{btn};{x};{y}M").into_bytes(),
        "release" => format!("\x1b[<{btn};{x};{y}m").into_bytes(),
        "move" => format!("\x1b[<{btn};{x};{y}M", btn = btn + 32).into_bytes(),
        _ => Vec::new(),
    }
}

/// Build (bytes, delay) steps from a mouse parameter.
/// Coords are 0-indexed — pass term.find (col, row) directly as (x, y).
fn mouse_to_steps(val: &Value) -> Result<Vec<(Vec<u8>, std::time::Duration)>, RuntimeError> {
    let fields = match val {
        Value::Struct(f) => f,
        _ => {
            return Err(RuntimeError::ToolFailed(
                "term.input: mouse must be an object".into(),
            ));
        }
    };
    let get_str = |name: &str| -> Result<&str, RuntimeError> {
        fields
            .iter()
            .find(|(k, _)| k == name)
            .and_then(|(_, v)| {
                if let Value::Str(s) = v {
                    Some(s.as_str())
                } else {
                    None
                }
            })
            .ok_or_else(|| RuntimeError::ToolFailed(format!("term.input: mouse.{name} missing")))
    };
    let get_int = |name: &str| -> Result<i64, RuntimeError> {
        fields
            .iter()
            .find(|(k, _)| k == name)
            .and_then(|(_, v)| {
                if let Value::Int(i) = v {
                    Some(*i)
                } else {
                    None
                }
            })
            .ok_or_else(|| RuntimeError::ToolFailed(format!("term.input: mouse.{name} missing")))
    };
    let get_opt_int = |name: &str| -> Option<i64> {
        fields.iter().find(|(k, _)| k == name).and_then(|(_, v)| {
            if let Value::Int(i) = v {
                Some(*i)
            } else {
                None
            }
        })
    };

    let action = get_str("action")?;
    let button_str = get_opt_str(fields, "button").unwrap_or("left");
    let x = get_int("x")?;
    let y = get_int("y")?;
    let btn: u32 = match button_str {
        "left" => 0,
        "middle" => 1,
        "right" => 2,
        _ => {
            return Err(RuntimeError::ToolFailed(format!(
                "term.input: mouse.button must be left/right/middle, got {button_str}"
            )));
        }
    };

    let z = std::time::Duration::ZERO;
    let gap = std::time::Duration::from_millis(50);
    let long = std::time::Duration::from_millis(500);

    match action {
        "press" => Ok(vec![(sgr(btn, "press", x, y), z)]),
        "release" => Ok(vec![(sgr(btn, "release", x, y), z)]),
        "click" => Ok(vec![
            (sgr(btn, "press", x, y), z),
            (sgr(btn, "release", x, y), z),
        ]),
        "double_click" => Ok(vec![
            (sgr(btn, "press", x, y), z),
            (sgr(btn, "release", x, y), gap),
            (sgr(btn, "press", x, y), z),
            (sgr(btn, "release", x, y), z),
        ]),
        "long_press" => Ok(vec![
            (sgr(btn, "press", x, y), long),
            (sgr(btn, "release", x, y), z),
        ]),
        "drag" => {
            let x2 = get_opt_int("x2").ok_or_else(|| {
                RuntimeError::ToolFailed("term.input: mouse.drag requires x2".into())
            })?;
            let y2 = get_opt_int("y2").ok_or_else(|| {
                RuntimeError::ToolFailed("term.input: mouse.drag requires y2".into())
            })?;
            let mut steps = vec![(sgr(btn, "press", x, y), z)];
            let dx = x2 - x;
            let dy = y2 - y;
            let n = dx.unsigned_abs().max(dy.unsigned_abs());
            for i in 1..=n {
                let cx = x + dx * i as i64 / n as i64;
                let cy = y + dy * i as i64 / n as i64;
                steps.push((sgr(btn, "move", cx, cy), z));
            }
            steps.push((sgr(btn, "release", x2, y2), z));
            Ok(steps)
        }
        "move" => Ok(vec![(sgr(0, "move", x, y), z)]),
        "scroll_up" => Ok(vec![(
            format!("\x1b[<64;{};{}M", x + 1, y + 1).into_bytes(),
            z,
        )]),
        "scroll_down" => Ok(vec![(
            format!("\x1b[<65;{};{}M", x + 1, y + 1).into_bytes(),
            z,
        )]),
        _ => Err(RuntimeError::ToolFailed(format!(
            "term.input: mouse.action must be click/double_click/long_press/drag/press/release/move/scroll_up/scroll_down, got {action}"
        ))),
    }
}

fn get_opt_str<'a>(fields: &'a [(String, Value)], name: &'a str) -> Option<&'a str> {
    fields.iter().find(|(k, _)| k == name).and_then(|(_, v)| {
        if let Value::Str(s) = v {
            Some(s.as_str())
        } else {
            None
        }
    })
}

pub struct TermCapture;
impl Tool for TermCapture {
    fn name(&self) -> &str {
        "term.capture"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some(
            "Read the terminal screen. Default returns plain text (format: \"text\").\n\
             Use start_row/end_row and start_col/end_col to read a rectangular region.\n\n\
             Best practices:\n\
             - After sending a command, capture to see the result.\n\
             - Use start_row/end_row to read only the relevant part (e.g. last 10 rows).\n\
             - Use start_col/end_col to read a column range (e.g. skip line numbers).\n\
             - format: \"screen\" returns full cell data with colors/styles.\n\
             - Default format: \"text\" is sufficient for most cases.",
        )
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "handle": {"type": "string"},
                "format": {"type": "string", "enum": ["text", "screen"], "default": "text"},
                "start_row": {"type": "integer", "default": 0, "description": "Start row (0-based). Default 0."},
                "end_row": {"type": "integer", "description": "End row (exclusive). Default: full height."},
                "start_col": {"type": "integer", "default": 0, "description": "Start column (0-based). Default 0."},
                "end_col": {"type": "integer", "description": "End column (exclusive). Default: full width."}
            },
            "required": ["handle"]
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let handle = extract_string(&args, "handle", 0)?;
            let format = extract_optional_string(&args, "format").unwrap_or_else(|| "text".into());
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.capture: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let entry = registry.lookup(&handle, &session_id)?;
            let screen = entry.snapshot();
            let start_row = extract_optional_int(&args, "start_row")
                .unwrap_or(0)
                .clamp(0, screen.rows as i64) as u16;
            let requested_end_row = extract_optional_int(&args, "end_row")
                .unwrap_or(screen.rows as i64)
                .clamp(start_row as i64, screen.rows as i64)
                as u16;
            let start_col = extract_optional_int(&args, "start_col")
                .unwrap_or(0)
                .clamp(0, screen.cols as i64) as u16;
            let end_col = extract_optional_int(&args, "end_col")
                .unwrap_or(screen.cols as i64)
                .clamp(start_col as i64, screen.cols as i64) as u16;
            let width = usize::from(end_col.saturating_sub(start_col));
            let max_rows_by_bytes = ctx
                .tool_output_budget
                .max_bytes
                .checked_div(width)
                .unwrap_or(ctx.tool_output_budget.max_lines);
            let max_rows = ctx
                .tool_output_budget
                .max_lines
                .min(max_rows_by_bytes.max(1))
                .min(u16::MAX as usize) as u16;
            let end_row = if format == "screen" {
                requested_end_row.min(start_row.saturating_add(max_rows))
            } else {
                requested_end_row
            };
            let state = entry.current_state();
            let mut fields = vec![
                ("handle".into(), Value::Str(handle.clone())),
                ("state".into(), state_to_value(&state)),
                ("rows".into(), Value::Int((end_row - start_row) as i64)),
                ("cols".into(), Value::Int((end_col - start_col) as i64)),
            ];
            if format == "screen" {
                fields.push((
                    "continuation".into(),
                    Value::Struct(vec![
                        ("type".into(), Value::Str("TerminalArea".into())),
                        ("next_row".into(), Value::Int(end_row as i64)),
                        ("start_col".into(), Value::Int(start_col as i64)),
                        ("end_col".into(), Value::Int(end_col as i64)),
                        ("has_more".into(), Value::Bool(end_row < screen.rows)),
                    ]),
                ));
                let sub_rows = end_row - start_row;
                let sub_cols = end_col - start_col;
                let sub_cells: Vec<TerminalCell> = (start_row..end_row)
                    .flat_map(|r| {
                        (start_col..end_col)
                            .map(|c| {
                                screen
                                    .cells
                                    .get((r as usize) * (screen.cols as usize) + (c as usize))
                                    .cloned()
                                    .unwrap_or_default()
                            })
                            .collect::<Vec<_>>()
                    })
                    .collect();
                let cursor = screen.cursor.and_then(|(row, col)| {
                    if (start_row..end_row).contains(&row) && (start_col..end_col).contains(&col) {
                        Some((row - start_row, col - start_col))
                    } else {
                        None
                    }
                });
                let partial_screen = TerminalScreen {
                    rows: sub_rows,
                    cols: sub_cols,
                    cells: sub_cells,
                    cursor,
                    alt_screen: screen.alt_screen,
                };
                fields.push(("screen".into(), screen_to_value(&partial_screen)));
            } else {
                let text = (start_row..end_row)
                    .map(|r| {
                        let row_text: String = (start_col..end_col)
                            .map(|c| cell_text(&screen, r, c))
                            .collect();
                        row_text.trim_end().to_string()
                    })
                    .collect::<Vec<_>>()
                    .join("\n");
                let cut =
                    crate::tools::tool_output::bounded_text_prefix(&text, ctx.tool_output_budget);
                if cut == text.len() {
                    fields.push(("text".into(), Value::Str(text)));
                } else {
                    let output_id = ctx
                        .output_store
                        .as_deref()
                        .and_then(|store| store.register("term_capture", &text))
                        .ok_or_else(|| {
                            RuntimeError::ToolFailed(
                                "term.capture: output exceeded budget, but no output_id is available for output.read".into(),
                            )
                        })?;
                    let total_lines = text.split_inclusive('\n').count();
                    fields.push(("content".into(), Value::Str(text[..cut].to_string())));
                    fields.push(("output_id".into(), Value::Str(output_id)));
                    fields.push(("total_lines".into(), Value::Int(total_lines as i64)));
                    fields.push(("total_bytes".into(), Value::Int(text.len() as i64)));
                    fields.push((
                        "next".into(),
                        Value::Struct(vec![
                            ("mode".into(), Value::Str("bytes".into())),
                            ("offset".into(), Value::Int(cut as i64)),
                            ("has_more".into(), Value::Bool(cut < text.len())),
                        ]),
                    ));
                }
            }
            Ok(Value::Struct(fields))
        })
    }
}

pub struct TermFind;
impl Tool for TermFind {
    fn name(&self) -> &str {
        "term.find"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some(
            "Search terminal screen for text and/or style. Returns list of matches.\n\n\
             - pattern: substring to search for (case-sensitive). Omit for style-only search.\n\
             - style: optional filter. Only cells matching ALL specified style fields count.\n\
             - Combine both: find red 'error' text, bold prompts, etc.\n\n\
             Style fields: bold, italic, underline, inverse, dim, fg, bg.\n\
             Colors: name (\"red\") or {r,g,b} struct (discover via term.capture format=\"screen\").\n\n\
             Returns: { matches: [{row, col, text}], count: N }",
        )
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "handle": {"type": "string"},
                "pattern": {"type": "string", "description": "Substring to search for. Omit for style-only search."},
                "style": {
                    "type": "object",
                    "properties": {
                        "bold": {"type": "boolean"},
                        "italic": {"type": "boolean"},
                        "underline": {"type": "boolean"},
                        "inverse": {"type": "boolean"},
                        "dim": {"type": "boolean"},
                        "fg": {"type": "string", "description": "Color name or {r,g,b} struct"},
                        "bg": {"type": "string", "description": "Color name or {r,g,b} struct"}
                    },
                    "description": "Optional style filter. All specified fields must match."
                },
                "start_row": {"type": "integer", "default": 0},
                "end_row": {"type": "integer", "description": "Exclusive. Default: full height."}
            },
            "required": ["handle"]
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let handle = extract_string(&args, "handle", 0)?;
            let pattern = extract_optional_string(&args, "pattern");
            let style_filter = parse_style_filter(&args)?;
            if pattern.is_none() && style_filter.is_none() {
                return Err(RuntimeError::ToolFailed(
                    "term.find: provide at least pattern or style".into(),
                ));
            }
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.find: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let entry = registry.lookup(&handle, &session_id)?;
            let screen = entry.snapshot();
            let start_row = extract_optional_int(&args, "start_row")
                .unwrap_or(0)
                .clamp(0, screen.rows as i64) as u16;
            let end_row = extract_optional_int(&args, "end_row")
                .unwrap_or(screen.rows as i64)
                .clamp(start_row as i64, screen.rows as i64) as u16;

            let mut matches = Vec::new();
            for r in start_row..end_row {
                let row_cells: Vec<&TerminalCell> =
                    (0..screen.cols).map(|c| cell_ref(&screen, r, c)).collect();
                let row_text: String = row_cells
                    .iter()
                    .map(|c| {
                        if c.wide_continuation {
                            ""
                        } else {
                            c.chars.as_str()
                        }
                    })
                    .collect::<String>();
                let row_text_trimmed = row_text.trim_end();

                if let Some(ref pat) = pattern {
                    let mut start = 0;
                    while let Some(pos) = row_text_trimmed[start..].find(pat) {
                        let abs_col = start + pos;
                        let style_ok = style_filter
                            .as_ref()
                            .map(|sf| sf.matches(row_cells.get(abs_col).copied()))
                            .unwrap_or(true);
                        if style_ok {
                            let matched_text = pat.clone();
                            matches.push(Value::Struct(vec![
                                ("row".into(), Value::Int(r as i64)),
                                ("col".into(), Value::Int(abs_col as i64)),
                                ("text".into(), Value::Str(matched_text)),
                            ]));
                        }
                        start += pos + pat.len();
                        if start >= row_text_trimmed.len() {
                            break;
                        }
                    }
                } else if let Some(ref sf) = style_filter {
                    let mut col = 0usize;
                    while col < screen.cols as usize {
                        if sf.matches(row_cells.get(col).copied())
                            && !row_cells[col].chars.is_empty()
                        {
                            let start_col = col;
                            let mut text = String::new();
                            while col < screen.cols as usize
                                && sf.matches(row_cells.get(col).copied())
                                && !row_cells[col].wide_continuation
                            {
                                text.push_str(&row_cells[col].chars);
                                col += 1;
                            }
                            if !text.trim().is_empty() {
                                matches.push(Value::Struct(vec![
                                    ("row".into(), Value::Int(r as i64)),
                                    ("col".into(), Value::Int(start_col as i64)),
                                    ("text".into(), Value::Str(text)),
                                ]));
                            }
                        } else {
                            col += 1;
                        }
                    }
                }
            }
            let count = matches.len() as i64;
            Ok(Value::Struct(vec![
                ("matches".into(), Value::List(matches)),
                ("count".into(), Value::Int(count)),
            ]))
        })
    }
}

fn cell_ref(screen: &TerminalScreen, row: u16, col: u16) -> &TerminalCell {
    let idx = (row as usize) * (screen.cols as usize) + (col as usize);
    screen.cells.get(idx).unwrap_or(&DEFAULT_CELL)
}

static DEFAULT_CELL: TerminalCell = TerminalCell {
    chars: String::new(),
    fg: TerminalColor::Default,
    bg: TerminalColor::Default,
    bold: false,
    italic: false,
    underline: false,
    inverse: false,
    dim: false,
    wide: false,
    wide_continuation: false,
};

struct StyleFilter {
    bold: Option<bool>,
    italic: Option<bool>,
    underline: Option<bool>,
    inverse: Option<bool>,
    dim: Option<bool>,
    fg: Option<TerminalColor>,
    bg: Option<TerminalColor>,
}

impl StyleFilter {
    fn matches(&self, cell: Option<&TerminalCell>) -> bool {
        let Some(cell) = cell else {
            return false;
        };
        if self.bold == Some(true) && !cell.bold {
            return false;
        }
        if self.bold == Some(false) && cell.bold {
            return false;
        }
        if self.italic == Some(true) && !cell.italic {
            return false;
        }
        if self.italic == Some(false) && cell.italic {
            return false;
        }
        if self.underline == Some(true) && !cell.underline {
            return false;
        }
        if self.underline == Some(false) && cell.underline {
            return false;
        }
        if self.inverse == Some(true) && !cell.inverse {
            return false;
        }
        if self.inverse == Some(false) && cell.inverse {
            return false;
        }
        if self.dim == Some(true) && !cell.dim {
            return false;
        }
        if self.dim == Some(false) && cell.dim {
            return false;
        }
        if let Some(fg) = &self.fg {
            if !color_matches(fg, &cell.fg) {
                return false;
            }
        }
        if let Some(bg) = &self.bg {
            if !color_matches(bg, &cell.bg) {
                return false;
            }
        }
        true
    }
}

fn parse_style_filter(args: &crate::tool::ToolArgs) -> Result<Option<StyleFilter>, RuntimeError> {
    let style = match args.named("style") {
        Some(v) => v,
        None => return Ok(None),
    };
    Ok(Some(StyleFilter {
        bold: get_optional_bool(style, "bold"),
        italic: get_optional_bool(style, "italic"),
        underline: get_optional_bool(style, "underline"),
        inverse: get_optional_bool(style, "inverse"),
        dim: get_optional_bool(style, "dim"),
        fg: get_optional_color(style, "fg")?,
        bg: get_optional_color(style, "bg")?,
    }))
}

fn get_optional_bool(style: &Value, field: &str) -> Option<bool> {
    match style.field(field) {
        Some(Value::Bool(b)) => Some(*b),
        _ => None,
    }
}

fn get_optional_color(style: &Value, field: &str) -> Result<Option<TerminalColor>, RuntimeError> {
    match style.field(field) {
        Some(v) => parse_color(v).map(Some).ok_or_else(|| {
            RuntimeError::ToolFailed(format!(
                "term.find: invalid color for '{field}' — use name (\"red\") or {{r,g,b}} struct"
            ))
        }),
        None => Ok(None),
    }
}

fn parse_color(val: &Value) -> Option<TerminalColor> {
    match val {
        Value::Str(name) => color_name_to_terminal(name),
        Value::Struct(fields) => {
            let r = fields
                .iter()
                .find(|(k, _)| k == "r")
                .and_then(|(_, v)| match v {
                    Value::Int(n) => Some(*n),
                    _ => None,
                })?;
            let g = fields
                .iter()
                .find(|(k, _)| k == "g")
                .and_then(|(_, v)| match v {
                    Value::Int(n) => Some(*n),
                    _ => None,
                })?;
            let b = fields
                .iter()
                .find(|(k, _)| k == "b")
                .and_then(|(_, v)| match v {
                    Value::Int(n) => Some(*n),
                    _ => None,
                })?;
            Some(TerminalColor::Rgb(r as u8, g as u8, b as u8))
        }
        _ => None,
    }
}

fn color_name_to_terminal(name: &str) -> Option<TerminalColor> {
    let idx = match name {
        "default" => return Some(TerminalColor::Default),
        "black" => 0,
        "red" => 1,
        "green" => 2,
        "yellow" => 3,
        "blue" => 4,
        "magenta" => 5,
        "cyan" => 6,
        "white" => 7,
        _ => return None,
    };
    Some(TerminalColor::Idx(idx))
}

fn color_matches(desired: &TerminalColor, actual: &TerminalColor) -> bool {
    match (desired, actual) {
        (TerminalColor::Default, TerminalColor::Default) => true,
        (TerminalColor::Idx(d), TerminalColor::Idx(a)) => *d == *a || (*d < 8 && *a == *d + 8),
        (TerminalColor::Rgb(dr, dg, db), TerminalColor::Rgb(ar, ag, ab)) => {
            dr == ar && dg == ag && db == ab
        }
        _ => false,
    }
}

pub struct TermResize;
impl Tool for TermResize {
    fn name(&self) -> &str {
        "term.resize"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some("Resize a terminal's PTY dimensions. Sends SIGWINCH to the child process.")
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "handle": {"type": "string"},
                "rows": {"type": "integer"},
                "cols": {"type": "integer"}
            },
            "required": ["handle", "rows", "cols"]
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let handle = extract_string(&args, "handle", 0)?;
            let rows = extract_optional_int(&args, "rows")
                .ok_or_else(|| RuntimeError::MissingArg("rows".into()))?
                as u16;
            let cols = extract_optional_int(&args, "cols")
                .ok_or_else(|| RuntimeError::MissingArg("cols".into()))?
                as u16;
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.resize: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let entry = registry.lookup(&handle, &session_id)?;
            entry.resize(rows, cols)?;
            Ok(Value::Struct(vec![
                ("ok".into(), Value::Bool(true)),
                ("rows".into(), Value::Int(rows as i64)),
                ("cols".into(), Value::Int(cols as i64)),
            ]))
        })
    }
}

pub struct TermKill;
impl Tool for TermKill {
    fn name(&self) -> &str {
        "term.kill"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some("Kill a terminal process. The terminal handle remains in the registry for history.")
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {"handle": {"type": "string"}},
            "required": ["handle"]
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let handle = extract_string(&args, "handle", 0)?;
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.kill: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let entry = registry.lookup(&handle, &session_id)?;
            {
                let mut child = entry.child.lock().expect("child poisoned");
                if let Some(child) = child.as_mut() {
                    let _ = child.kill();
                }
            }
            entry.profile.lock().expect("profile poisoned").take();
            {
                let mut state = entry.state.lock().expect("state poisoned");
                *state = TermState::Killed { ended_at: now_ms() };
            }
            Ok(Value::Struct(vec![
                ("ok".into(), Value::Bool(true)),
                ("state".into(), Value::Str("killed".into())),
            ]))
        })
    }
}

pub struct TermList;
impl Tool for TermList {
    fn name(&self) -> &str {
        "term.list"
    }
    fn tier(&self) -> Tier {
        Tier::Four
    }
    fn description(&self) -> Option<&str> {
        Some("List all terminal handles in the current session.")
    }
    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {"all": {"type": "boolean", "default": false}}
        })
    }
    fn call<'a>(
        &'a self,
        args: crate::tool::ToolArgs,
        ctx: &'a crate::tool::ToolCtx,
    ) -> crate::tool::BoxFut<'a, crate::tool::ToolResult> {
        Box::pin(async move {
            let all = args
                .named("all")
                .and_then(|v| {
                    if let Value::Bool(b) = v {
                        Some(*b)
                    } else {
                        None
                    }
                })
                .unwrap_or(false);
            let registry = ctx.term_registry.clone().ok_or_else(|| {
                RuntimeError::ToolFailed("term.list: registry not available".into())
            })?;
            let session_id = ctx.session_id.clone().unwrap_or_else(|| "anon".into());
            let _ = all;
            let list = registry.list(&session_id);
            let entries: Vec<Value> = list
                .iter()
                .map(|(h, st)| {
                    Value::Struct(vec![
                        ("handle".into(), Value::Str(h.clone())),
                        ("state".into(), state_to_value(st)),
                    ])
                })
                .collect();
            Ok(Value::Struct(vec![(
                "terminals".into(),
                Value::List(entries),
            )]))
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::tool::{ToolArgs, ToolCtx};
    use std::sync::atomic::{AtomicUsize, Ordering};

    #[derive(Debug)]
    struct RecordingChild {
        kill_calls: Arc<AtomicUsize>,
        wait_calls: Arc<AtomicUsize>,
    }

    #[derive(Debug)]
    struct RecordingKiller(Arc<AtomicUsize>);

    impl portable_pty::ChildKiller for RecordingKiller {
        fn kill(&mut self) -> std::io::Result<()> {
            self.0.fetch_add(1, Ordering::SeqCst);
            Ok(())
        }

        fn clone_killer(&self) -> Box<dyn portable_pty::ChildKiller + Send + Sync> {
            Box::new(Self(self.0.clone()))
        }
    }

    impl portable_pty::ChildKiller for RecordingChild {
        fn kill(&mut self) -> std::io::Result<()> {
            self.kill_calls.fetch_add(1, Ordering::SeqCst);
            Ok(())
        }

        fn clone_killer(&self) -> Box<dyn portable_pty::ChildKiller + Send + Sync> {
            Box::new(RecordingKiller(self.kill_calls.clone()))
        }
    }

    impl portable_pty::Child for RecordingChild {
        fn try_wait(&mut self) -> std::io::Result<Option<portable_pty::ExitStatus>> {
            Ok(None)
        }

        fn wait(&mut self) -> std::io::Result<portable_pty::ExitStatus> {
            self.wait_calls.fetch_add(1, Ordering::SeqCst);
            Ok(portable_pty::ExitStatus::with_exit_code(0))
        }

        fn process_id(&self) -> Option<u32> {
            Some(42)
        }
    }

    #[derive(Clone, Copy)]
    enum PtyIoFailure {
        Reader,
        Writer,
        Never,
    }

    struct FailingMaster(PtyIoFailure);

    impl portable_pty::MasterPty for FailingMaster {
        fn resize(&self, _size: portable_pty::PtySize) -> anyhow::Result<()> {
            Ok(())
        }

        fn get_size(&self) -> anyhow::Result<portable_pty::PtySize> {
            Ok(portable_pty::PtySize::default())
        }

        fn try_clone_reader(&self) -> anyhow::Result<Box<dyn std::io::Read + Send>> {
            if matches!(self.0, PtyIoFailure::Reader) {
                anyhow::bail!("reader sentinel")
            }
            Ok(Box::new(std::io::empty()))
        }

        fn take_writer(&self) -> anyhow::Result<Box<dyn std::io::Write + Send>> {
            if matches!(self.0, PtyIoFailure::Writer) {
                anyhow::bail!("writer sentinel")
            }
            Ok(Box::new(std::io::sink()))
        }

        #[cfg(unix)]
        fn process_group_leader(&self) -> Option<i32> {
            None
        }

        #[cfg(unix)]
        fn as_raw_fd(&self) -> Option<std::os::fd::RawFd> {
            None
        }

        #[cfg(unix)]
        fn tty_name(&self) -> Option<PathBuf> {
            None
        }
    }

    fn recording_child() -> (RecordingChild, Arc<AtomicUsize>, Arc<AtomicUsize>) {
        let kill_calls = Arc::new(AtomicUsize::new(0));
        let wait_calls = Arc::new(AtomicUsize::new(0));
        (
            RecordingChild {
                kill_calls: kill_calls.clone(),
                wait_calls: wait_calls.clone(),
            },
            kill_calls,
            wait_calls,
        )
    }

    struct ChannelReader {
        chunks: std::sync::mpsc::Receiver<Vec<u8>>,
        pending: std::io::Cursor<Vec<u8>>,
    }

    impl std::io::Read for ChannelReader {
        fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
            if self.pending.position() < self.pending.get_ref().len() as u64 {
                return self.pending.read(buf);
            }
            match self.chunks.recv() {
                Ok(chunk) => {
                    self.pending = std::io::Cursor::new(chunk);
                    self.pending.read(buf)
                }
                Err(_) => Ok(0),
            }
        }
    }

    fn recording_pty_result(
        profile: crate::sandbox::TempProfile,
    ) -> (PtySpawnResult, Arc<AtomicUsize>, Arc<AtomicUsize>, PathBuf) {
        let profile_path = profile.path().to_path_buf();
        let (child, kill_calls, wait_calls) = recording_child();
        (
            PtySpawnResult {
                child: Box::new(child),
                reader: Box::new(std::io::empty()),
                writer: Box::new(std::io::sink()),
                master: Box::new(FailingMaster(PtyIoFailure::Never)),
                profile: Some(profile),
            },
            kill_calls,
            wait_calls,
            profile_path,
        )
    }

    #[tokio::test]
    async fn successful_pty_releases_profile_after_exit_and_preserves_history() {
        let root = tempfile::tempdir().unwrap();
        let profile = crate::sandbox::TempProfile::create("live profile").unwrap();
        let profile_path = profile.path().to_path_buf();
        let (child, _, _) = recording_child();
        let (chunks_tx, chunks_rx) = std::sync::mpsc::channel();
        let pty_result = PtySpawnResult {
            child: Box::new(child),
            reader: Box::new(ChannelReader {
                chunks: chunks_rx,
                pending: std::io::Cursor::new(Vec::new()),
            }),
            writer: Box::new(std::io::sink()),
            master: Box::new(FailingMaster(PtyIoFailure::Never)),
            profile: Some(profile),
        };
        let registry = Arc::new(TermRegistry::new());
        let (handle, entry) = registry
            .spawn_entry(
                24,
                80,
                "success".into(),
                root.path().to_path_buf(),
                pty_result,
                None,
                "success".into(),
                "printf success".into(),
                None,
                tokio_util::sync::CancellationToken::new(),
                None,
                None,
            )
            .unwrap();

        assert!(profile_path.exists());
        chunks_tx.send(b"completed output".to_vec()).unwrap();
        drop(chunks_tx);
        let reader_task = entry
            .reader_task
            .lock()
            .expect("reader_task poisoned")
            .take()
            .unwrap();
        reader_task.await.unwrap();

        assert!(!profile_path.exists());
        assert!(matches!(entry.current_state(), TermState::Exited { .. }));
        let historical = registry.lookup(&handle.to_string(), "success").unwrap();
        let screen = historical.snapshot();
        let first_row = screen.cells[..usize::from(screen.cols)]
            .iter()
            .map(|cell| cell.chars.as_str())
            .collect::<String>();
        assert!(first_row.contains("completed output"));
    }

    #[test]
    fn pty_reader_failure_terminates_child_and_drops_profile() {
        let profile = crate::sandbox::TempProfile::create("reader profile").unwrap();
        let profile_path = profile.path().to_path_buf();
        let (child, kill_calls, wait_calls) = recording_child();
        let error = crate::sandbox::complete_pty_spawn(
            Box::new(child),
            Box::new(FailingMaster(PtyIoFailure::Reader)),
            Some(profile),
        )
        .err()
        .expect("reader acquisition must fail");
        assert!(error.to_string().contains("reader sentinel"));
        assert_eq!(kill_calls.load(Ordering::SeqCst), 1);
        assert_eq!(wait_calls.load(Ordering::SeqCst), 1);
        assert!(!profile_path.exists());
    }

    #[test]
    fn pty_writer_failure_terminates_child_and_drops_profile() {
        let profile = crate::sandbox::TempProfile::create("writer profile").unwrap();
        let profile_path = profile.path().to_path_buf();
        let (child, kill_calls, wait_calls) = recording_child();
        let error = crate::sandbox::complete_pty_spawn(
            Box::new(child),
            Box::new(FailingMaster(PtyIoFailure::Writer)),
            Some(profile),
        )
        .err()
        .expect("writer acquisition must fail");
        assert!(error.to_string().contains("writer sentinel"));
        assert_eq!(kill_calls.load(Ordering::SeqCst), 1);
        assert_eq!(wait_calls.load(Ordering::SeqCst), 1);
        assert!(!profile_path.exists());
    }

    #[test]
    fn session_directory_failure_leaves_no_terminal_resources() {
        let root = tempfile::tempdir().unwrap();
        let blocker = root.path().join("not-a-directory");
        let session_dir = blocker.join("session");
        std::fs::write(&blocker, "block directory creation").unwrap();
        let profile = crate::sandbox::TempProfile::create("directory profile").unwrap();
        let (pty_result, kill_calls, wait_calls, profile_path) = recording_pty_result(profile);
        let tasks = crate::task_registry::TaskRegistry::new();
        let registry = Arc::new(TermRegistry::new().with_task_registry(tasks.clone()));
        let error = registry
            .spawn_entry(
                24,
                80,
                "dir-failure".into(),
                session_dir.clone(),
                pty_result,
                None,
                "terminal".into(),
                "sh".into(),
                None,
                tokio_util::sync::CancellationToken::new(),
                None,
                None,
            )
            .err()
            .expect("session directory creation must fail");
        assert!(error.to_string().contains("create session_dir"));
        assert_eq!(kill_calls.load(Ordering::SeqCst), 1);
        assert_eq!(wait_calls.load(Ordering::SeqCst), 1);
        assert!(!profile_path.exists());
        assert!(registry.list("dir-failure").is_empty());
        assert!(
            tasks
                .list(&crate::task_registry::TaskFilter::all())
                .is_empty()
        );
        assert!(!session_dir.exists());
    }

    #[test]
    fn log_open_failure_after_directory_creation_leaves_no_terminal_resources() {
        let root = tempfile::tempdir().unwrap();
        let session_dir = root.path().join("session");
        let profile = crate::sandbox::TempProfile::create("log profile").unwrap();
        let (pty_result, kill_calls, wait_calls, profile_path) = recording_pty_result(profile);
        let tasks = crate::task_registry::TaskRegistry::new();
        let registry = Arc::new(TermRegistry::new().with_task_registry(tasks.clone()));
        let opener_calls = AtomicUsize::new(0);
        let error = registry
            .spawn_entry_with_log_opener(
                24,
                80,
                "log-failure".into(),
                session_dir.clone(),
                pty_result,
                None,
                "terminal".into(),
                "sh".into(),
                None,
                tokio_util::sync::CancellationToken::new(),
                None,
                None,
                |path| {
                    opener_calls.fetch_add(1, Ordering::SeqCst);
                    assert!(session_dir.is_dir());
                    assert!(path.starts_with(&session_dir));
                    Err(std::io::Error::other("log sentinel"))
                },
            )
            .err()
            .expect("log opening must fail");
        assert!(error.to_string().contains("log sentinel"));
        assert_eq!(opener_calls.load(Ordering::SeqCst), 1);
        assert_eq!(kill_calls.load(Ordering::SeqCst), 1);
        assert_eq!(wait_calls.load(Ordering::SeqCst), 1);
        assert!(!profile_path.exists());
        assert!(registry.list("log-failure").is_empty());
        assert!(
            tasks
                .list(&crate::task_registry::TaskFilter::all())
                .is_empty()
        );
        assert!(std::fs::read_dir(&session_dir).unwrap().next().is_none());
    }

    #[test]
    fn spawn_provenance_uses_cwd_not_cmd() {
        let dir = tempfile::tempdir().unwrap();
        let ctx = ToolCtx::default();
        let args = ToolArgs {
            named: vec![
                ("cmd".into(), Value::Str("/bin/echo hi".into())),
                ("cwd".into(), Value::Str(dir.path().display().to_string())),
            ],
            ..ToolArgs::default()
        };
        let provenance = TermSpawn.invocation_provenance(&args, &ctx).unwrap();
        let cwd = provenance.cwd.expect("cwd recorded");
        assert_eq!(
            std::fs::canonicalize(&cwd).unwrap(),
            std::fs::canonicalize(dir.path()).unwrap()
        );
        assert_eq!(provenance.path, None);
        assert!(
            provenance
                .risks
                .contains(&crate::trust::RiskKind::ProcessSpawn)
        );
    }

    struct StrictRecordingSandbox {
        pty_calls: AtomicUsize,
    }

    struct DenyingSandbox {
        strict_calls: AtomicUsize,
    }

    impl crate::sandbox::Sandbox for DenyingSandbox {
        fn spawn<'a>(
            &'a self,
            _cmd: &'a [&'a str],
            _env: &'a [(String, String)],
            _cwd: &'a Path,
            _authorization: &'a crate::permission::InvocationAuthorization,
        ) -> crate::tool::BoxFut<'a, Result<std::process::Output, RuntimeError>> {
            Box::pin(async { Err(RuntimeError::ToolFailed("Operation not permitted".into())) })
        }

        fn prepare_background(
            &self,
            _cmd: &[&str],
            _env: &[(String, String)],
            _cwd: &Path,
            _authorization: &crate::permission::InvocationAuthorization,
        ) -> Result<Box<dyn crate::sandbox::BackgroundLauncher>, crate::sandbox::SandboxLaunchError>
        {
            Err(crate::sandbox::SandboxLaunchError::Runtime(
                RuntimeError::ToolFailed("background unsupported".into()),
            ))
        }

        fn spawn_pty<'a>(
            &'a self,
            _cmd: &'a [&'a str],
            _env: &'a [(String, String)],
            _cwd: &'a Path,
            _pty_size: portable_pty::PtySize,
            authorization: &'a crate::permission::InvocationAuthorization,
        ) -> crate::tool::BoxFut<'a, Result<PtySpawnResult, crate::sandbox::SandboxLaunchError>>
        {
            self.strict_calls.fetch_add(1, Ordering::SeqCst);
            Box::pin(async move {
                Err(crate::sandbox::SandboxLaunchError::Denied(Box::new(
                    crate::sandbox::SandboxDenial {
                        operation: crate::sandbox::SandboxOperation::PtySpawn,
                        reason: "Operation not permitted".into(),
                        provenance: authorization.provenance().clone(),
                    },
                )))
            })
        }

        fn is_available(&self) -> bool {
            true
        }

        fn kind(&self) -> &'static str {
            "test-denial"
        }
    }

    impl crate::sandbox::Sandbox for StrictRecordingSandbox {
        fn spawn<'a>(
            &'a self,
            _cmd: &'a [&'a str],
            _env: &'a [(String, String)],
            _cwd: &'a Path,
            _authorization: &'a crate::permission::InvocationAuthorization,
        ) -> crate::tool::BoxFut<'a, Result<std::process::Output, RuntimeError>> {
            Box::pin(async { Err(RuntimeError::ToolFailed("strict sentinel".into())) })
        }

        fn prepare_background(
            &self,
            _cmd: &[&str],
            _env: &[(String, String)],
            _cwd: &Path,
            _authorization: &crate::permission::InvocationAuthorization,
        ) -> Result<Box<dyn crate::sandbox::BackgroundLauncher>, crate::sandbox::SandboxLaunchError>
        {
            Err(crate::sandbox::SandboxLaunchError::Runtime(
                RuntimeError::ToolFailed("background unsupported".into()),
            ))
        }

        fn spawn_pty<'a>(
            &'a self,
            _cmd: &'a [&'a str],
            _env: &'a [(String, String)],
            _cwd: &'a Path,
            _pty_size: portable_pty::PtySize,
            _authorization: &'a crate::permission::InvocationAuthorization,
        ) -> crate::tool::BoxFut<'a, Result<PtySpawnResult, crate::sandbox::SandboxLaunchError>>
        {
            self.pty_calls.fetch_add(1, Ordering::SeqCst);
            Box::pin(async {
                Err(crate::sandbox::SandboxLaunchError::Runtime(
                    RuntimeError::ToolFailed("strict sentinel".into()),
                ))
            })
        }

        fn is_available(&self) -> bool {
            true
        }
        fn kind(&self) -> &'static str {
            "test"
        }
    }

    fn managed_term_ctx(
        workspace: &Path,
        registry: Arc<TermRegistry>,
        session_dir: &Path,
    ) -> ToolCtx {
        let mut ctx = ToolCtx::new()
            .with_trust(crate::trust::TrustConfig {
                mode: crate::trust::TrustMode::Reckless,
                ..crate::trust::TrustConfig::default()
            })
            .with_term_registry(registry)
            .with_session_dir(session_dir.to_path_buf())
            .with_fs_access(crate::fs_access::FsAccessPolicy::workspace_write(
                workspace.to_path_buf(),
            ))
            .with_workspace(crate::git_workspace::WorkspaceBinding {
                workspace_id: "test".into(),
                repository_root: workspace.to_path_buf(),
                path: workspace.to_path_buf(),
                branch: None,
            });
        ctx.session_id = Some("r4".into());
        ctx.for_tool_invocation(crate::tool::Tier::Four)
            .authorized_for(crate::permission::InvocationAuthorization::new(
                crate::permission::PermissionRequestId::now(),
                "test-call",
                "term.spawn",
                crate::permission::ResourceProvenance::none(),
                crate::permission::ExecutionBoundary::Direct,
            ))
    }

    fn term_args(cwd: &Path) -> ToolArgs {
        ToolArgs {
            positional: vec![],
            named: vec![
                ("cmd".into(), Value::Str("exit 0".into())),
                ("cwd".into(), Value::Str(cwd.to_string_lossy().into())),
            ],
        }
    }

    fn brokered_term_ctx(
        workspace: &Path,
        registry: Arc<TermRegistry>,
        session_dir: &Path,
        trust: crate::trust::TrustConfig,
    ) -> ToolCtx {
        let flows = Arc::new(crate::tools::agent_ctrl::FlowRegistry::default());
        let identity = flows
            .register_root(
                "r4".into(),
                crate::event::FlowRunId::now(),
                crate::flow_authority::EffectiveAuthority::root(&trust, true, None),
            )
            .unwrap();
        let broker = crate::permission::PermissionBroker::shared(Arc::clone(&flows));
        let mut ctx = managed_term_ctx(workspace, registry, session_dir)
            .with_flow_registry(flows)
            .with_permission_broker(broker)
            .with_trust(trust)
            .with_approval(Arc::new(crate::session::ApprovalRegistry::new()))
            .with_anchors(None, Some(identity.run_id.clone()), None);
        ctx.flow_identity = Some(identity);
        ctx.for_tool_invocation(crate::tool::Tier::Four)
    }

    #[tokio::test]
    async fn sandbox_strict_path_receives_external_cwd_before_fs_policy() {
        let workspace = tempfile::tempdir().unwrap();
        let session_dir = tempfile::tempdir().unwrap();
        let registry = Arc::new(TermRegistry::new());
        let sandbox = Arc::new(StrictRecordingSandbox {
            pty_calls: AtomicUsize::new(0),
        });
        let args = term_args(Path::new(env!("CARGO_MANIFEST_DIR")));
        let mut trust = eager_spawn_policy();
        trust.risks.eager.outside_workspace = Some(crate::trust::PolicyAction::Auto);
        let ctx = brokered_term_ctx(workspace.path(), registry, session_dir.path(), trust)
            .with_sandbox(sandbox.clone());
        let ctx = authorize_term_spawn(ctx, &args).await;
        let error = spawn_impl(args, &ctx).await.unwrap_err();
        assert!(error.to_string().contains("strict sentinel"));
        assert_eq!(sandbox.pty_calls.load(Ordering::SeqCst), 1);
    }

    #[tokio::test]
    async fn direct_authorization_skips_available_sandbox() {
        let workspace = tempfile::tempdir().unwrap();
        let session_dir = tempfile::tempdir().unwrap();
        let registry = Arc::new(TermRegistry::new());
        let sandbox = Arc::new(StrictRecordingSandbox {
            pty_calls: AtomicUsize::new(0),
        });
        let ctx = managed_term_ctx(workspace.path(), Arc::clone(&registry), session_dir.path())
            .with_sandbox(sandbox.clone());

        spawn_impl(term_args(workspace.path()), &ctx).await.unwrap();

        assert_eq!(sandbox.pty_calls.load(Ordering::SeqCst), 0);
        registry.kill_all();
    }

    async fn authorize_term_spawn(ctx: ToolCtx, args: &ToolArgs) -> ToolCtx {
        match crate::approval::request_approval(
            &ctx,
            "term.spawn",
            "term.spawn",
            args,
            crate::tool::ApprovalLevel::Dangerous,
            Some(&TermSpawn),
        )
        .await
        {
            crate::approval::ApprovalOutcome::Approve { authorization } => {
                ctx.authorized_for(*authorization)
            }
            crate::approval::ApprovalOutcome::Deny { reason } => {
                panic!("strict term spawn authorization denied: {reason}")
            }
        }
    }

    fn eager_spawn_policy() -> crate::trust::TrustConfig {
        crate::trust::TrustConfig {
            mode: crate::trust::TrustMode::Eager,
            escalation: crate::trust::EscalationPolicy::Deny,
            ..crate::trust::TrustConfig::default()
        }
    }

    #[tokio::test]
    async fn sandbox_denial_never_relaunches_or_registers_resources() {
        let workspace = tempfile::tempdir().unwrap();
        let session_dir = tempfile::tempdir().unwrap();
        let tasks = crate::task_registry::TaskRegistry::new();
        let registry = Arc::new(TermRegistry::new().with_task_registry(tasks.clone()));
        let sandbox = Arc::new(DenyingSandbox {
            strict_calls: AtomicUsize::new(0),
        });
        let ctx = brokered_term_ctx(
            workspace.path(),
            registry.clone(),
            session_dir.path(),
            eager_spawn_policy(),
        )
        .with_sandbox(sandbox.clone())
        .with_task_registry(tasks.clone());
        let args = term_args(workspace.path());
        let ctx = authorize_term_spawn(ctx, &args).await;

        let error = spawn_impl(args, &ctx).await.unwrap_err();

        assert!(error.to_string().contains("Operation not permitted"));
        assert_eq!(sandbox.strict_calls.load(Ordering::SeqCst), 1);
        assert!(registry.list("r4").is_empty());
        assert!(
            tasks
                .list(&crate::task_registry::TaskFilter::all())
                .is_empty()
        );
    }

    #[tokio::test]
    async fn direct_spawn_allows_external_temp_cwd() {
        let workspace = tempfile::tempdir().unwrap();
        let external = tempfile::tempdir().unwrap();
        let session_dir = tempfile::tempdir().unwrap();
        let registry = Arc::new(TermRegistry::new());
        let ctx = managed_term_ctx(workspace.path(), registry.clone(), session_dir.path());
        spawn_impl(term_args(external.path()), &ctx).await.unwrap();
        assert_eq!(registry.list("r4").len(), 1);
        registry.kill_all();
    }

    #[tokio::test]
    async fn direct_spawn_allows_external_cwd_under_full_access() {
        let workspace = tempfile::tempdir().unwrap();
        let session_dir = tempfile::tempdir().unwrap();
        let registry = Arc::new(TermRegistry::new());
        let ctx = managed_term_ctx(workspace.path(), registry.clone(), session_dir.path())
            .with_fs_access(crate::fs_access::FsAccessPolicy::danger_full_access());
        spawn_impl(term_args(Path::new(env!("CARGO_MANIFEST_DIR"))), &ctx)
            .await
            .unwrap();
        assert_eq!(registry.list("r4").len(), 1);
        registry.kill_all();
    }

    #[test]
    fn handle_parse_roundtrip() {
        let h = TermHandle {
            session_id: "abc".into(),
            local_id: 7,
        };
        assert_eq!(h.to_string(), "term_abc_7");
        let back = TermHandle::parse("term_abc_7").unwrap();
        assert_eq!(back, h);
    }

    #[test]
    fn handle_parse_rejects_bad_format() {
        assert!(TermHandle::parse("not_term").is_none());
        assert!(TermHandle::parse("term_nosuffix").is_none());
        assert!(TermHandle::parse("term_x_notnum").is_none());
    }

    #[test]
    fn snapshot_screen_captures_text() {
        let mut parser = vt100::Parser::new(3, 5, 0);
        parser.process(b"hello");
        let screen = snapshot_screen(&parser);
        assert_eq!(screen.rows, 3);
        assert_eq!(screen.cols, 5);
        assert_eq!(screen.cells.len(), 15);
        assert_eq!(screen.cells[0].chars, "h");
        assert_eq!(screen.cells[4].chars, "o");
    }

    #[tokio::test]
    async fn capture_spills_text_to_output_store_with_byte_continuation() {
        const ROWS: u16 = 4096;
        const COLS: u16 = 256;
        const CONTENT_COLS: usize = 255;
        const EXPECTED_TEXT_BYTES: usize = ROWS as usize * CONTENT_COLS + (ROWS as usize - 1);

        let registry = Arc::new(TermRegistry::new());
        let handle = registry.next_handle("session_a");
        let row = "a".repeat(CONTENT_COLS);
        let expected_text = vec![row.as_str(); ROWS as usize].join("\n");
        assert_eq!(expected_text.len(), EXPECTED_TEXT_BYTES);
        assert_eq!(EXPECTED_TEXT_BYTES, 1_048_575);
        let terminal_input = expected_text.replace('\n', "\r\n");
        let mut parser = vt100::Parser::new(ROWS, COLS, 0);
        parser.process(terminal_input.as_bytes());
        let entry = Arc::new(TermEntry {
            handle: handle.clone(),
            session_id: "session_a".into(),
            pty_size: portable_pty::PtySize {
                rows: ROWS,
                cols: COLS,
                pixel_width: 0,
                pixel_height: 0,
            },
            parser: Arc::new(Mutex::new(parser)),
            writer: Mutex::new(Box::new(std::io::sink())),
            state: Arc::new(Mutex::new(TermState::Running {
                pid: 0,
                started_at: 0,
            })),
            stream_tx: broadcast::channel(STREAM_CHANNEL_CAPACITY).0,
            log_path: std::env::temp_dir().join("term_capture_budget.log"),
            reader_task: Mutex::new(None),
            child: Mutex::new(None),
            master: Mutex::new(None),
            profile: Arc::new(Mutex::new(None)),
            started_at: Instant::now(),
            task_id: Mutex::new(None),
        });
        registry.insert(entry);
        let output_dir = tempfile::tempdir().unwrap();
        let mut ctx = crate::tool::ToolCtx::new()
            .with_term_registry(registry)
            .with_session_dir(output_dir.path().to_path_buf());
        ctx.session_id = Some("session_a".into());
        ctx.tool_output_budget = crate::tools::tool_output::ToolOutputBudget {
            max_lines: 32,
            max_bytes: 64 * 1024,
            max_line_bytes: 64 * 1024,
        };

        let first = TermCapture
            .call(
                crate::tool::ToolArgs {
                    positional: Vec::new(),
                    named: vec![("handle".into(), Value::Str(handle.to_string()))],
                },
                &ctx,
            )
            .await
            .unwrap();
        let Value::Struct(fields) = first else {
            panic!("expected capture fields");
        };
        assert!(matches!(
            fields.iter().find(|(name, _)| name == "rows"),
            Some((_, Value::Int(rows))) if *rows == i64::from(ROWS)
        ));
        assert!(matches!(
            fields.iter().find(|(name, _)| name == "total_lines"),
            Some((_, Value::Int(lines))) if *lines == i64::from(ROWS)
        ));
        assert!(matches!(
            fields.iter().find(|(name, _)| name == "total_bytes"),
            Some((_, Value::Int(bytes))) if *bytes == EXPECTED_TEXT_BYTES as i64
        ));
        assert!(!fields.iter().any(|(name, _)| name == "continuation"));
        assert!(!fields.iter().any(|(name, _)| name == "TerminalArea"));
        assert!(!fields.iter().any(|(name, _)| name == "next_row"));
        assert!(!fields.iter().any(|(name, _)| name == "next_col"));
        assert!(!fields.iter().any(|(name, _)| name == "text"));
        let content = fields.iter().find_map(|(name, value)| {
            (name == "content").then(|| match value {
                Value::Str(text) => text.as_str(),
                _ => panic!("expected content string"),
            })
        });
        let Value::Str(output_id) = fields
            .iter()
            .find(|(name, _)| name == "output_id")
            .map(|(_, value)| value)
            .unwrap()
        else {
            panic!("expected output_id");
        };
        let Value::Struct(next) = fields
            .iter()
            .find(|(name, _)| name == "next")
            .map(|(_, value)| value)
            .unwrap()
        else {
            panic!("expected byte continuation");
        };
        let offset = next
            .iter()
            .find_map(|(name, value)| (name == "offset").then_some(value))
            .and_then(|value| match value {
                Value::Int(offset) => Some(*offset as usize),
                _ => None,
            })
            .unwrap();
        assert!(matches!(
            next.iter().find(|(name, _)| name == "mode"),
            Some((_, Value::Str(mode))) if mode == "bytes"
        ));
        let store = ctx.output_store.as_deref().unwrap();
        let mut reconstructed = content.unwrap().to_string();
        let mut page_offset = offset;
        loop {
            let page = store
                .read_bytes(output_id, page_offset, usize::MAX, ctx.tool_output_budget)
                .unwrap();
            assert_eq!(page.offset, page_offset);
            reconstructed.push_str(&page.content);
            if !page.has_more {
                break;
            }
            assert!(page.next_offset > page_offset);
            page_offset = page.next_offset;
        }
        assert_eq!(reconstructed.len(), EXPECTED_TEXT_BYTES);
        assert_eq!(reconstructed, expected_text);

        let untruncated = TermCapture
            .call(
                crate::tool::ToolArgs {
                    positional: Vec::new(),
                    named: vec![
                        ("handle".into(), Value::Str(handle.to_string())),
                        ("end_row".into(), Value::Int(1)),
                    ],
                },
                &ctx,
            )
            .await
            .unwrap();
        let Value::Struct(fields) = untruncated else {
            panic!("expected capture fields");
        };
        assert!(matches!(
            fields.iter().find(|(name, _)| name == "text"),
            Some((_, Value::Str(text))) if text == &row
        ));
        assert!(!fields.iter().any(|(name, _)| name == "continuation"));
        assert!(!fields.iter().any(|(name, _)| name == "output_id"));
        assert!(!fields.iter().any(|(name, _)| name == "next"));

        let screen_capture = TermCapture
            .call(
                crate::tool::ToolArgs {
                    positional: Vec::new(),
                    named: vec![
                        ("handle".into(), Value::Str(handle.to_string())),
                        ("format".into(), Value::Str("screen".into())),
                    ],
                },
                &ctx,
            )
            .await
            .unwrap();
        let Value::Struct(fields) = screen_capture else {
            panic!("expected capture fields");
        };
        let Value::Struct(continuation) = fields
            .iter()
            .find(|(name, _)| name == "continuation")
            .map(|(_, value)| value)
            .unwrap()
        else {
            panic!("expected screen continuation");
        };
        assert!(matches!(
            continuation.iter().find(|(name, _)| name == "type"),
            Some((_, Value::Str(kind))) if kind == "TerminalArea"
        ));
        assert!(continuation.iter().any(|(name, _)| name == "next_row"));
        assert!(fields.iter().any(|(name, _)| name == "screen"));
    }

    #[test]
    fn registry_lookup_rejects_cross_session() {
        let registry = Arc::new(TermRegistry::new());
        let h = registry.next_handle("session_a");
        let entry = Arc::new(TermEntry {
            handle: h.clone(),
            session_id: "session_a".into(),
            pty_size: portable_pty::PtySize {
                rows: 24,
                cols: 80,
                pixel_width: 0,
                pixel_height: 0,
            },
            parser: Arc::new(Mutex::new(vt100::Parser::new(24, 80, 0))),
            writer: Mutex::new(Box::new(std::io::sink())),
            state: Arc::new(Mutex::new(TermState::Running {
                pid: 0,
                started_at: 0,
            })),
            stream_tx: broadcast::channel(STREAM_CHANNEL_CAPACITY).0,
            log_path: std::env::temp_dir().join("term_test_dummy.log"),
            reader_task: Mutex::new(None),
            child: Mutex::new(None),
            master: Mutex::new(None),
            profile: Arc::new(Mutex::new(None)),
            started_at: Instant::now(),
            task_id: Mutex::new(None),
        });
        registry.insert(entry);
        assert!(registry.lookup(&h.to_string(), "session_a").is_ok());
        assert!(registry.lookup(&h.to_string(), "session_b").is_err());
    }

    fn make_screen(rows: u16, cols: u16, text: &str) -> TerminalScreen {
        let mut parser = vt100::Parser::new(rows, cols, 0);
        parser.process(text.as_bytes());
        snapshot_screen(&parser)
    }

    #[test]
    fn cell_text_returns_chars_for_filled_cell() {
        let screen = make_screen(1, 5, "hello");
        assert_eq!(cell_text(&screen, 0, 0), "h");
        assert_eq!(cell_text(&screen, 0, 4), "o");
    }

    #[test]
    fn cell_text_returns_space_for_empty_cell() {
        let screen = make_screen(1, 5, "hi");
        assert_eq!(cell_text(&screen, 0, 2), " ");
    }

    #[test]
    fn find_pattern_returns_position() {
        let screen = make_screen(2, 10, "hello\r\nworld");
        let pos = find_pattern_on_screen(&screen, "world");
        assert_eq!(pos, Some((1, 0)));
    }

    #[test]
    fn find_pattern_returns_none_when_absent() {
        let screen = make_screen(1, 5, "hello");
        assert!(find_pattern_on_screen(&screen, "xyz").is_none());
    }

    #[test]
    fn color_name_maps_to_ansi_idx() {
        assert_eq!(color_name_to_terminal("red"), Some(TerminalColor::Idx(1)));
        assert_eq!(
            color_name_to_terminal("default"),
            Some(TerminalColor::Default)
        );
        assert_eq!(color_name_to_terminal("nonexistent"), None);
    }

    #[test]
    fn color_matches_bright_variant_to_base_name() {
        let desired = TerminalColor::Idx(1);
        let actual_bright = TerminalColor::Idx(9);
        assert!(color_matches(&desired, &actual_bright));
        let actual_normal = TerminalColor::Idx(1);
        assert!(color_matches(&desired, &actual_normal));
    }

    #[test]
    fn color_matches_rgb_exact() {
        let desired = TerminalColor::Rgb(255, 128, 0);
        let actual = TerminalColor::Rgb(255, 128, 0);
        assert!(color_matches(&desired, &actual));
        let wrong = TerminalColor::Rgb(255, 128, 1);
        assert!(!color_matches(&desired, &wrong));
    }

    #[test]
    fn parse_color_accepts_name_and_rgb() {
        assert_eq!(
            parse_color(&Value::Str("blue".into())),
            Some(TerminalColor::Idx(4))
        );
        let rgb = Value::Struct(vec![
            ("r".into(), Value::Int(10)),
            ("g".into(), Value::Int(20)),
            ("b".into(), Value::Int(30)),
        ]);
        assert_eq!(parse_color(&rgb), Some(TerminalColor::Rgb(10, 20, 30)));
    }
}