pi-oxidized 0.1.1

package/crates/pi/src/core/tools/bash.rs

@@ -0,0 +1,1574 @@
+//! Bash tool: execute a shell command with streamed, tail-truncated output.
+//!
+//! Ports `.references/pi/packages/coding-agent/src/core/tools/bash.ts` plus the
+//! local process-tree kill path from `utils/shell.ts`. stdout and stderr are
+//! merged by arrival order into an [`OutputAccumulator`] with spill prefix
+//! `pi-bash`. Partial tool updates are throttled to 100 ms.
+
+use std::collections::HashMap;
+use std::fmt::Write as _;
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use futures::FutureExt as _;
+use futures::future::BoxFuture;
+use pi_agent::{AgentTool, AgentToolResult, ToolError, ToolUpdates};
+use pi_ai::ToolResultContent;
+use pi_ai::types::TextContent;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use tokio::io::{AsyncRead, AsyncReadExt, AsyncWriteExt};
+use tokio::process::{Child, Command};
+use tokio::sync::Mutex;
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::{
+    DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, OutputAccumulator, OutputAccumulatorError,
+    OutputAccumulatorOptions, OutputSnapshot, TruncatedBy, TruncationResult, format_size,
+};
+
+/// Maximum timeout duration in milliseconds (TypeScript `MAX_TIMEOUT_MS`).
+const MAX_TIMEOUT_MS: u64 = 2_147_483_647;
+
+/// Numeric form of the maximum timeout in seconds.
+const MAX_TIMEOUT_SECONDS: f64 = 2_147_483.647;
+
+/// Display form of the maximum timeout in seconds (`MAX_TIMEOUT_MS / 1000`).
+const MAX_TIMEOUT_SECONDS_DISPLAY: &str = "2147483.647";
+
+/// Throttle window for streaming tool updates.
+const BASH_UPDATE_THROTTLE: Duration = Duration::from_millis(100);
+
+/// Temp-file prefix for bash spill paths (`pi-bash-{16hex}.log`).
+const BASH_TEMP_FILE_PREFIX: &str = "pi-bash";
+
+/// TypeBox-compatible bash arguments (fixture `bash.json`).
+#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+pub struct BashToolInput {
+    /// Bash command to execute.
+    #[schemars(description = "Bash command to execute")]
+    pub command: String,
+    /// Timeout in seconds (optional, no default timeout).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(description = "Timeout in seconds (optional, no default timeout)")]
+    pub timeout: Option<f64>,
+}
+
+/// Structured details returned when bash output is truncated.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BashToolDetails {
+    /// Tail truncation metadata when the stream exceeded limits.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub truncation: Option<TruncationResult>,
+    /// Absolute path of the full-output spill file, when one was opened.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub full_output_path: Option<String>,
+}
+
+/// Pluggable command execution backend (TypeScript `BashOperations`).
+pub trait BashOperations: Send + Sync {
+    /// Execute `command` in `cwd`, streaming merged output chunks through
+    /// `on_data`. Returns the process exit code (`None` when killed without a
+    /// status). Failures use the TypeScript internal markers `"aborted"` and
+    /// `"timeout:{secs}"` so the tool wrapper can append status text.
+    fn exec(
+        &self,
+        command: String,
+        cwd: PathBuf,
+        on_data: Box<dyn FnMut(Vec<u8>) + Send>,
+        cancel: CancellationToken,
+        timeout: Option<f64>,
+        env: HashMap<String, String>,
+    ) -> BoxFuture<'static, Result<Option<i32>, ToolError>>;
+}
+
+/// Spawn rewrite hook context (TypeScript `BashSpawnContext`).
+#[derive(Clone, Debug)]
+pub struct BashSpawnContext {
+    /// Command string to execute.
+    pub command: String,
+    /// Working directory for the child process.
+    pub cwd: PathBuf,
+    /// Environment map for the child process.
+    pub env: HashMap<String, String>,
+}
+
+/// Optional rewrite applied before local spawn (TypeScript `BashSpawnHook`).
+pub type BashSpawnHook = Arc<dyn Fn(BashSpawnContext) -> BashSpawnContext + Send + Sync>;
+
+/// Options for [`BashTool`].
+#[derive(Clone)]
+pub struct BashToolOptions {
+    /// Working directory used when no spawn hook rewrites it.
+    pub cwd: PathBuf,
+    /// Optional absolute shell path (TypeScript `shellPath`).
+    pub shell_path: Option<PathBuf>,
+    /// Optional command prefix prepended as `{prefix}\n{command}`.
+    pub command_prefix: Option<String>,
+    /// Optional spawn rewrite hook.
+    pub spawn_hook: Option<BashSpawnHook>,
+    /// Custom operations; default is local shell execution.
+    pub operations: Option<Arc<dyn BashOperations>>,
+}
+
+impl std::fmt::Debug for BashToolOptions {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("BashToolOptions")
+            .field("cwd", &self.cwd)
+            .field("shell_path", &self.shell_path)
+            .field("command_prefix", &self.command_prefix)
+            .field("spawn_hook", &self.spawn_hook.as_ref().map(|_| "Some(..)"))
+            .field("operations", &self.operations.as_ref().map(|_| "Some(..)"))
+            .finish()
+    }
+}
+
+impl BashToolOptions {
+    /// Builds options for `cwd`.
+    #[must_use]
+    pub fn new(cwd: impl Into<PathBuf>) -> Self {
+        Self {
+            cwd: cwd.into(),
+            shell_path: None,
+            command_prefix: None,
+            spawn_hook: None,
+            operations: None,
+        }
+    }
+}
+
+/// Local shell backend matching TypeScript `createLocalBashOperations`.
+#[derive(Clone, Debug, Default)]
+pub struct LocalBashOperations {
+    shell_path: Option<PathBuf>,
+}
+
+impl LocalBashOperations {
+    /// Creates local operations with optional custom shell path.
+    #[must_use]
+    pub fn new(shell_path: Option<PathBuf>) -> Self {
+        Self { shell_path }
+    }
+}
+
+impl BashOperations for LocalBashOperations {
+    fn exec(
+        &self,
+        command: String,
+        cwd: PathBuf,
+        mut on_data: Box<dyn FnMut(Vec<u8>) + Send>,
+        cancel: CancellationToken,
+        timeout: Option<f64>,
+        env: HashMap<String, String>,
+    ) -> BoxFuture<'static, Result<Option<i32>, ToolError>> {
+        let shell_path = self.shell_path.clone();
+        async move {
+            let timeout_ms = resolve_timeout_ms(timeout)?;
+            if cancel.is_cancelled() {
+                return Err(ToolError::new("aborted"));
+            }
+            if !cwd.is_dir() {
+                return Err(ToolError::new(format!(
+                    "Working directory does not exist: {}\nCannot execute bash commands.",
+                    cwd.display()
+                )));
+            }
+
+            let shell = resolve_shell_config(shell_path.as_deref())?;
+            let mut child = spawn_shell_command(&shell, &command, &cwd, &env)?;
+            let pid = child.id();
+            let stdout = child.stdout.take();
+            let stderr = child.stderr.take();
+
+            let (chunk_tx, mut chunk_rx) = mpsc::unbounded_channel::<Vec<u8>>();
+            let readers = spawn_stream_readers(stdout, stderr, chunk_tx);
+
+            let outcome = run_child_loop(
+                &mut child,
+                pid,
+                &mut chunk_rx,
+                &mut on_data,
+                &cancel,
+                timeout_ms,
+            )
+            .await;
+
+            // Always reap and drain; cancellation wins over timeout/exit.
+            let exit_code = finalize_child(
+                &mut child,
+                pid,
+                &mut chunk_rx,
+                &mut on_data,
+                readers,
+                outcome,
+            )
+            .await?;
+
+            if cancel.is_cancelled() {
+                return Err(ToolError::new("aborted"));
+            }
+            if matches!(outcome, ChildLoopOutcome::TimedOut) {
+                return Err(ToolError::new(format!(
+                    "timeout:{}",
+                    timeout_seconds_label(timeout)
+                )));
+            }
+            Ok(exit_code)
+        }
+        .boxed()
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum ChildLoopOutcome {
+    Exited,
+    Cancelled,
+    TimedOut,
+    WaitFailed,
+}
+
+async fn run_child_loop(
+    child: &mut Child,
+    pid: Option<u32>,
+    chunk_rx: &mut mpsc::UnboundedReceiver<Vec<u8>>,
+    on_data: &mut (dyn FnMut(Vec<u8>) + Send),
+    cancel: &CancellationToken,
+    timeout_ms: Option<u64>,
+) -> ChildLoopOutcome {
+    let timeout_at = timeout_ms.map(|ms| Instant::now() + Duration::from_millis(ms));
+    let mut exited = false;
+
+    loop {
+        if cancel.is_cancelled() {
+            kill_process(pid);
+            return ChildLoopOutcome::Cancelled;
+        }
+        if timeout_at.is_some_and(|deadline| Instant::now() >= deadline) {
+            kill_process(pid);
+            return ChildLoopOutcome::TimedOut;
+        }
+
+        let wait_timeout = timeout_at.map(|deadline| {
+            deadline
+                .saturating_duration_since(Instant::now())
+                .max(Duration::from_millis(1))
+        });
+
+        tokio::select! {
+            biased;
+            () = cancel.cancelled() => {
+                kill_process(pid);
+                return ChildLoopOutcome::Cancelled;
+            }
+            () = tokio::time::sleep(wait_timeout.unwrap_or(Duration::from_hours(8760))),
+                if wait_timeout.is_some() =>
+            {
+                kill_process(pid);
+                return ChildLoopOutcome::TimedOut;
+            }
+            chunk = chunk_rx.recv() => {
+                if let Some(bytes) = chunk {
+                    on_data(bytes);
+                } else {
+                    // Both stream readers finished. Wait for process if needed.
+                    if !exited {
+                        return match child.wait().await {
+                            Ok(_) => ChildLoopOutcome::Exited,
+                            Err(_) => ChildLoopOutcome::WaitFailed,
+                        };
+                    }
+                    return ChildLoopOutcome::Exited;
+                }
+            }
+            status = child.wait(), if !exited => {
+                match status {
+                    Ok(_) => {
+                        exited = true;
+                        // Drain remaining pipe data until readers disconnect.
+                    }
+                    Err(_) => return ChildLoopOutcome::WaitFailed,
+                }
+            }
+        }
+
+        if exited {
+            return drain_exited_output(pid, chunk_rx, on_data, cancel).await;
+        }
+    }
+}
+
+async fn drain_exited_output(
+    pid: Option<u32>,
+    chunk_rx: &mut mpsc::UnboundedReceiver<Vec<u8>>,
+    on_data: &mut (dyn FnMut(Vec<u8>) + Send),
+    cancel: &CancellationToken,
+) -> ChildLoopOutcome {
+    let idle_deadline = Instant::now() + Duration::from_millis(100);
+    loop {
+        if cancel.is_cancelled() {
+            kill_process(pid);
+            return ChildLoopOutcome::Cancelled;
+        }
+        match chunk_rx.try_recv() {
+            Ok(bytes) => on_data(bytes),
+            Err(mpsc::error::TryRecvError::Empty) => {
+                if Instant::now() >= idle_deadline {
+                    return ChildLoopOutcome::Exited;
+                }
+                tokio::select! {
+                    () = cancel.cancelled() => {
+                        kill_process(pid);
+                        return ChildLoopOutcome::Cancelled;
+                    }
+                    chunk = chunk_rx.recv() => {
+                        match chunk {
+                            Some(bytes) => on_data(bytes),
+                            None => return ChildLoopOutcome::Exited,
+                        }
+                    }
+                    () = tokio::time::sleep(Duration::from_millis(5)) => {}
+                }
+            }
+            Err(mpsc::error::TryRecvError::Disconnected) => {
+                return ChildLoopOutcome::Exited;
+            }
+        }
+    }
+}
+
+fn kill_process(pid: Option<u32>) {
+    if let Some(pid) = pid {
+        kill_process_tree(pid);
+    }
+}
+
+async fn finalize_child(
+    child: &mut Child,
+    pid: Option<u32>,
+    chunk_rx: &mut mpsc::UnboundedReceiver<Vec<u8>>,
+    on_data: &mut (dyn FnMut(Vec<u8>) + Send),
+    readers: Vec<tokio::task::JoinHandle<()>>,
+    outcome: ChildLoopOutcome,
+) -> Result<Option<i32>, ToolError> {
+    if matches!(
+        outcome,
+        ChildLoopOutcome::Cancelled | ChildLoopOutcome::TimedOut
+    ) {
+        kill_process(pid);
+    }
+
+    // Drain any remaining output.
+    let drain_deadline = Instant::now() + Duration::from_millis(200);
+    while Instant::now() < drain_deadline {
+        match chunk_rx.try_recv() {
+            Ok(bytes) => on_data(bytes),
+            Err(mpsc::error::TryRecvError::Empty) => {
+                tokio::task::yield_now().await;
+            }
+            Err(mpsc::error::TryRecvError::Disconnected) => break,
+        }
+    }
+    while let Ok(bytes) = chunk_rx.try_recv() {
+        on_data(bytes);
+    }
+
+    for handle in readers {
+        let _ = handle.await;
+    }
+
+    match child.try_wait() {
+        Ok(Some(status)) => Ok(status.code()),
+        Ok(None) => {
+            if let Some(pid) = pid {
+                kill_process_tree(pid);
+            }
+            match child.wait().await {
+                Ok(status) => Ok(status.code()),
+                Err(error) => Err(ToolError::new(error.to_string())),
+            }
+        }
+        Err(error) => Err(ToolError::new(error.to_string())),
+    }
+}
+
+/// Agent tool that runs bash commands in a working directory.
+#[derive(Clone)]
+pub struct BashTool {
+    cwd: PathBuf,
+    command_prefix: Option<String>,
+    spawn_hook: Option<BashSpawnHook>,
+    operations: Arc<dyn BashOperations>,
+    parameters: Value,
+    description: String,
+}
+
+impl std::fmt::Debug for BashTool {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("BashTool")
+            .field("cwd", &self.cwd)
+            .field("command_prefix", &self.command_prefix)
+            .field("spawn_hook", &self.spawn_hook.as_ref().map(|_| "Some(..)"))
+            .field("operations", &"<dyn BashOperations>")
+            .field("parameters", &self.parameters)
+            .field("description", &self.description)
+            .finish()
+    }
+}
+
+impl BashTool {
+    /// Creates a bash tool rooted at `cwd`.
+    #[must_use]
+    pub fn new(cwd: impl Into<PathBuf>) -> Self {
+        Self::with_options(BashToolOptions::new(cwd))
+    }
+
+    /// Creates a bash tool from explicit options.
+    #[must_use]
+    pub fn with_options(options: BashToolOptions) -> Self {
+        let operations = options.operations.unwrap_or_else(|| {
+            Arc::new(LocalBashOperations::new(options.shell_path.clone()))
+                as Arc<dyn BashOperations>
+        });
+        Self {
+            cwd: options.cwd,
+            command_prefix: options.command_prefix,
+            spawn_hook: options.spawn_hook,
+            operations,
+            parameters: bash_parameters_schema(),
+            description: bash_description(),
+        }
+    }
+
+    /// Returns the JSON Schema for bash arguments (normalized `TypeBox` shape).
+    #[must_use]
+    pub fn parameters_schema() -> Value {
+        bash_parameters_schema()
+    }
+
+    /// Validates raw tool arguments into [`BashToolInput`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ToolError`] when required fields are missing or mistyped, or
+    /// when `timeout` fails TypeScript `resolveTimeoutMs` checks.
+    pub fn parse_input(args: &Map<String, Value>) -> Result<BashToolInput, ToolError> {
+        let input: BashToolInput = serde_json::from_value(Value::Object(args.clone()))
+            .map_err(|error| ToolError::new(format!("Bash tool input is invalid. {error}")))?;
+        let _ = resolve_timeout_ms(input.timeout)?;
+        Ok(input)
+    }
+}
+
+impl AgentTool for BashTool {
+    fn name(&self) -> &'static str {
+        "bash"
+    }
+
+    fn label(&self) -> &'static str {
+        "bash"
+    }
+
+    fn description(&self) -> &str {
+        &self.description
+    }
+
+    fn parameters(&self) -> &Value {
+        &self.parameters
+    }
+
+    fn validate_arguments(
+        &self,
+        args: &Map<String, Value>,
+    ) -> Result<Map<String, Value>, ToolError> {
+        let _ = Self::parse_input(args)?;
+        Ok(args.clone())
+    }
+
+    fn execute(
+        &self,
+        _tool_call_id: &str,
+        args: Map<String, Value>,
+        cancel: CancellationToken,
+        updates: ToolUpdates,
+    ) -> BoxFuture<'static, Result<AgentToolResult, ToolError>> {
+        let cwd = self.cwd.clone();
+        let command_prefix = self.command_prefix.clone();
+        let spawn_hook = self.spawn_hook.clone();
+        let operations = Arc::clone(&self.operations);
+
+        async move {
+            let input = BashTool::parse_input(&args)?;
+            let resolved_command = match command_prefix {
+                Some(prefix) => format!("{prefix}\n{}", input.command),
+                None => input.command,
+            };
+            let spawn_context = resolve_spawn_context(resolved_command, cwd, spawn_hook.as_ref());
+            let collected =
+                collect_command_output(operations, spawn_context, input.timeout, cancel, updates)
+                    .await?;
+            command_result(collected)
+        }
+        .boxed()
+    }
+}
+
+struct CollectedCommandOutput {
+    exec_result: Result<Option<i32>, ToolError>,
+    snapshot: OutputSnapshot,
+    last_line_bytes: usize,
+}
+
+async fn collect_command_output(
+    operations: Arc<dyn BashOperations>,
+    spawn_context: BashSpawnContext,
+    timeout: Option<f64>,
+    cancel: CancellationToken,
+    updates: ToolUpdates,
+) -> Result<CollectedCommandOutput, ToolError> {
+    updates.send(AgentToolResult {
+        content: Vec::new(),
+        details: Value::Null,
+        added_tool_names: None,
+        terminate: None,
+    });
+    let output = Arc::new(Mutex::new(OutputAccumulator::new(
+        OutputAccumulatorOptions {
+            max_lines: DEFAULT_MAX_LINES,
+            max_bytes: DEFAULT_MAX_BYTES,
+            temp_file_prefix: BASH_TEMP_FILE_PREFIX.to_owned(),
+        },
+    )));
+    let throttle = Arc::new(Mutex::new(UpdateThrottle::new()));
+    let (data_tx, mut data_rx) = mpsc::unbounded_channel::<Vec<u8>>();
+    let pump_output = Arc::clone(&output);
+    let pump_updates = updates.clone();
+    let pump_throttle = Arc::clone(&throttle);
+    let pump = tokio::spawn(async move {
+        while let Some(chunk) = data_rx.recv().await {
+            pump_output.lock().await.append(&chunk)?;
+            schedule_throttled_update(
+                pump_updates.clone(),
+                Arc::clone(&pump_output),
+                Arc::clone(&pump_throttle),
+            );
+        }
+        Ok::<(), OutputAccumulatorError>(())
+    });
+    let on_data = Box::new(move |bytes: Vec<u8>| {
+        let _ = data_tx.send(bytes);
+    });
+    let exec_result = operations
+        .exec(
+            spawn_context.command,
+            spawn_context.cwd,
+            on_data,
+            cancel,
+            timeout,
+            spawn_context.env,
+        )
+        .await;
+    finish_collected_output(exec_result, pump, output, throttle, updates).await
+}
+
+async fn finish_collected_output(
+    exec_result: Result<Option<i32>, ToolError>,
+    pump: tokio::task::JoinHandle<Result<(), OutputAccumulatorError>>,
+    output: Arc<Mutex<OutputAccumulator>>,
+    throttle: Arc<Mutex<UpdateThrottle>>,
+    updates: ToolUpdates,
+) -> Result<CollectedCommandOutput, ToolError> {
+    match pump.await {
+        Ok(Ok(())) => {}
+        Ok(Err(error)) => return Err(accumulator_error(&error)),
+        Err(error) => return Err(ToolError::new(format!("bash output pump failed: {error}"))),
+    }
+    for _ in 0..20 {
+        if !throttle.lock().await.timer_armed {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(10)).await;
+    }
+    let mut output_guard = output.lock().await;
+    output_guard
+        .finish()
+        .map_err(|error| accumulator_error(&error))?;
+    let snapshot = output_guard
+        .snapshot(true)
+        .map_err(|error| accumulator_error(&error))?;
+    updates.send(snapshot_to_partial(&snapshot));
+    let last_line_bytes = output_guard.last_line_bytes();
+    output_guard.close_temp_file();
+    drop(output_guard);
+    Ok(CollectedCommandOutput {
+        exec_result,
+        snapshot,
+        last_line_bytes,
+    })
+}
+
+fn command_result(collected: CollectedCommandOutput) -> Result<AgentToolResult, ToolError> {
+    let CollectedCommandOutput {
+        exec_result,
+        snapshot,
+        last_line_bytes,
+    } = collected;
+    match exec_result {
+        Ok(exit_code) => {
+            let (text, details) = format_output(&snapshot, last_line_bytes, "(no output)");
+            if let Some(code) = exit_code
+                && code != 0
+            {
+                return Err(ToolError::new(append_status(
+                    &text,
+                    &format!("Command exited with code {code}"),
+                )));
+            }
+            Ok(AgentToolResult {
+                content: vec![ToolResultContent::Text(TextContent::new(text))],
+                details: details_to_value(details),
+                added_tool_names: None,
+                terminate: None,
+            })
+        }
+        Err(error) => command_error_result(&error, &snapshot, last_line_bytes),
+    }
+}
+
+fn command_error_result(
+    error: &ToolError,
+    snapshot: &OutputSnapshot,
+    last_line_bytes: usize,
+) -> Result<AgentToolResult, ToolError> {
+    let message = error.message().to_owned();
+    let (text, _) = format_output(snapshot, last_line_bytes, "");
+    if message == "aborted" {
+        return Err(ToolError::new(append_status(&text, "Command aborted")));
+    }
+    if let Some(secs) = message.strip_prefix("timeout:") {
+        return Err(ToolError::new(append_status(
+            &text,
+            &format!("Command timed out after {secs} seconds"),
+        )));
+    }
+    Err(ToolError::new(message))
+}
+
+/// Builds an [`Arc<dyn AgentTool>`] bash tool for `cwd`.
+#[must_use]
+pub fn create_bash_tool(cwd: impl Into<PathBuf>) -> Arc<dyn AgentTool> {
+    Arc::new(BashTool::new(cwd))
+}
+
+fn bash_description() -> String {
+    format!(
+        "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {DEFAULT_MAX_LINES} lines or {}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.",
+        DEFAULT_MAX_BYTES / 1024
+    )
+}
+
+fn bash_parameters_schema() -> Value {
+    normalize_tool_schema(schemars::schema_for!(BashToolInput))
+}
+
+fn normalize_tool_schema(schema: schemars::Schema) -> Value {
+    let mut value = serde_json::to_value(schema).unwrap_or_else(|_| Value::Object(Map::new()));
+    if let Value::Object(map) = &mut value {
+        map.remove("$schema");
+        map.remove("title");
+        // TypeBox fixtures omit the root struct doc-comment description.
+        map.remove("description");
+        normalize_schema_node(map);
+    }
+    value
+}
+
+fn normalize_schema_node(map: &mut Map<String, Value>) {
+    map.remove("format");
+    // schemars represents `Option<number>` as `["number","null"]`; TypeBox uses
+    // a plain `"number"` with the key absent from `required`.
+    if let Some(Value::Array(types)) = map.get("type").cloned() {
+        let non_null: Vec<Value> = types
+            .into_iter()
+            .filter(|item| item.as_str() != Some("null"))
+            .collect();
+        if non_null.len() == 1 {
+            map.insert("type".to_owned(), non_null[0].clone());
+        }
+    }
+    let keys: Vec<String> = map.keys().cloned().collect();
+    for key in keys {
+        match map.get_mut(&key) {
+            Some(Value::Object(child)) => normalize_schema_node(child),
+            Some(Value::Array(items)) => {
+                for item in items {
+                    if let Value::Object(child) = item {
+                        normalize_schema_node(child);
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+/// TypeScript `resolveTimeoutMs`.
+fn resolve_timeout_ms(timeout: Option<f64>) -> Result<Option<u64>, ToolError> {
+    let Some(timeout) = timeout else {
+        return Ok(None);
+    };
+    if !timeout.is_finite() || timeout <= 0.0 {
+        return Err(ToolError::new(
+            "Invalid timeout: must be a finite number of seconds",
+        ));
+    }
+    if timeout > MAX_TIMEOUT_SECONDS {
+        return Err(ToolError::new(format!(
+            "Invalid timeout: maximum is {MAX_TIMEOUT_SECONDS_DISPLAY} seconds"
+        )));
+    }
+    let milliseconds = (timeout * 1000.0).floor();
+    Ok(Some(
+        bounded_integer_f64_to_u64(milliseconds).min(MAX_TIMEOUT_MS),
+    ))
+}
+
+fn bounded_integer_f64_to_u64(value: f64) -> u64 {
+    const FRACTION_BITS: u32 = 52;
+    const FRACTION_BITS_I32: i32 = 52;
+    const EXPONENT_BIAS: i32 = 1023;
+
+    if value == 0.0 {
+        return 0;
+    }
+    let bits = value.to_bits();
+    let exponent_bits = (bits >> FRACTION_BITS) & 0x7ff;
+    let fraction = bits & ((1_u64 << FRACTION_BITS) - 1);
+    let significand = fraction | (1_u64 << FRACTION_BITS);
+    let exponent = i32::try_from(exponent_bits).unwrap_or(0) - EXPONENT_BIAS;
+    let denominator_shift = u32::try_from(FRACTION_BITS_I32 - exponent).unwrap_or(FRACTION_BITS);
+    significand >> denominator_shift
+}
+
+fn timeout_seconds_label(timeout: Option<f64>) -> String {
+    timeout.map_or_else(|| "0".to_owned(), |value| value.to_string())
+}
+
+struct ShellConfig {
+    shell: PathBuf,
+    args: Vec<String>,
+    command_from_stdin: bool,
+}
+
+fn resolve_shell_config(custom: Option<&Path>) -> Result<ShellConfig, ToolError> {
+    if let Some(path) = custom {
+        if path.exists() {
+            return Ok(bash_shell_config(path.to_path_buf()));
+        }
+        return Err(ToolError::new(format!(
+            "Custom shell path not found: {}",
+            path.display()
+        )));
+    }
+
+    #[cfg(windows)]
+    {
+        let mut candidates = Vec::new();
+        if let Ok(program_files) = std::env::var("ProgramFiles") {
+            candidates.push(PathBuf::from(program_files).join(r"Git\bin\bash.exe"));
+        }
+        if let Ok(program_files_x86) = std::env::var("ProgramFiles(x86)") {
+            candidates.push(PathBuf::from(program_files_x86).join(r"Git\bin\bash.exe"));
+        }
+        for path in &candidates {
+            if path.exists() {
+                return Ok(bash_shell_config(path.clone()));
+            }
+        }
+        if let Some(path) = find_on_path("bash.exe") {
+            return Ok(bash_shell_config(path));
+        }
+        return Err(ToolError::new(
+            "No bash shell found. Options:\n  1. Install Git for Windows: https://git-scm.com/download/win\n  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\n  3. Set shellPath in settings.json".to_owned(),
+        ));
+    }
+
+    #[cfg(not(windows))]
+    {
+        if Path::new("/bin/bash").exists() {
+            return Ok(bash_shell_config(PathBuf::from("/bin/bash")));
+        }
+        if let Some(path) = find_on_path("bash") {
+            return Ok(bash_shell_config(path));
+        }
+        Ok(ShellConfig {
+            shell: PathBuf::from("sh"),
+            args: vec!["-c".to_owned()],
+            command_from_stdin: false,
+        })
+    }
+}
+
+fn bash_shell_config(shell: PathBuf) -> ShellConfig {
+    let legacy_wsl = shell
+        .to_string_lossy()
+        .replace('\\', "/")
+        .to_ascii_lowercase()
+        .contains("/windows/system32/bash.exe");
+    if legacy_wsl {
+        ShellConfig {
+            shell,
+            args: vec!["-s".to_owned()],
+            command_from_stdin: true,
+        }
+    } else {
+        ShellConfig {
+            shell,
+            args: vec!["-c".to_owned()],
+            command_from_stdin: false,
+        }
+    }
+}
+
+fn find_on_path(name: &str) -> Option<PathBuf> {
+    let path_var = std::env::var_os("PATH")?;
+    for dir in std::env::split_paths(&path_var) {
+        let candidate = dir.join(name);
+        if candidate.is_file() {
+            return Some(candidate);
+        }
+    }
+    None
+}
+
+fn current_env_map() -> HashMap<String, String> {
+    std::env::vars().collect()
+}
+
+fn resolve_spawn_context(
+    command: String,
+    cwd: PathBuf,
+    spawn_hook: Option<&BashSpawnHook>,
+) -> BashSpawnContext {
+    let base = BashSpawnContext {
+        command,
+        cwd,
+        env: current_env_map(),
+    };
+    match spawn_hook {
+        Some(hook) => hook(base),
+        None => base,
+    }
+}
+
+fn spawn_shell_command(
+    shell: &ShellConfig,
+    command: &str,
+    cwd: &Path,
+    env: &HashMap<String, String>,
+) -> Result<Child, ToolError> {
+    let mut cmd = Command::new(&shell.shell);
+    cmd.args(&shell.args);
+    if !shell.command_from_stdin {
+        cmd.arg(command);
+    }
+    cmd.current_dir(cwd)
+        .stdin(if shell.command_from_stdin {
+            Stdio::piped()
+        } else {
+            Stdio::null()
+        })
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true)
+        .envs(env.iter().map(|(k, v)| (k.as_str(), v.as_str())));
+
+    #[cfg(unix)]
+    {
+        // Detached process group so killpg reaps descendants (Node `detached`).
+        cmd.process_group(0);
+    }
+
+    #[cfg(windows)]
+    {
+        use std::os::windows::process::CommandExt as _;
+        const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+        cmd.creation_flags(CREATE_NO_WINDOW);
+    }
+
+    let mut child = cmd
+        .spawn()
+        .map_err(|error| ToolError::new(format!("Failed to spawn shell: {error}")))?;
+
+    if shell.command_from_stdin
+        && let Some(mut stdin) = child.stdin.take()
+    {
+        let payload = command.to_owned();
+        tokio::spawn(async move {
+            let _ = stdin.write_all(payload.as_bytes()).await;
+            let _ = stdin.shutdown().await;
+        });
+    }
+
+    Ok(child)
+}
+
+fn spawn_stream_readers(
+    stdout: Option<impl AsyncRead + Unpin + Send + 'static>,
+    stderr: Option<impl AsyncRead + Unpin + Send + 'static>,
+    tx: mpsc::UnboundedSender<Vec<u8>>,
+) -> Vec<tokio::task::JoinHandle<()>> {
+    let mut handles = Vec::new();
+    if let Some(stdout) = stdout {
+        let tx = tx.clone();
+        handles.push(tokio::spawn(async move {
+            pump_reader(stdout, tx).await;
+        }));
+    }
+    if let Some(stderr) = stderr {
+        handles.push(tokio::spawn(async move {
+            pump_reader(stderr, tx).await;
+        }));
+    }
+    handles
+}
+
+async fn pump_reader<R>(mut reader: R, tx: mpsc::UnboundedSender<Vec<u8>>)
+where
+    R: AsyncRead + Unpin,
+{
+    let mut buf = vec![0_u8; 8192];
+    loop {
+        match reader.read(&mut buf).await {
+            Ok(0) | Err(_) => break,
+            Ok(n) => {
+                if tx.send(buf[..n].to_vec()).is_err() {
+                    break;
+                }
+            }
+        }
+    }
+}
+
+fn kill_process_tree(pid: u32) {
+    #[cfg(unix)]
+    {
+        use nix::sys::signal::{Signal, kill, killpg};
+        use nix::unistd::Pid;
+
+        let Ok(raw) = i32::try_from(pid) else {
+            return;
+        };
+        let group = Pid::from_raw(raw);
+        // Node: process.kill(-pid, SIGKILL) then fallback process.kill(pid).
+        if killpg(group, Signal::SIGKILL).is_err() {
+            let _ = kill(group, Signal::SIGKILL);
+        }
+    }
+
+    #[cfg(windows)]
+    {
+        let _ = std::process::Command::new("taskkill")
+            .args(["/F", "/T", "/PID", &pid.to_string()])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .spawn();
+    }
+}
+
+struct UpdateThrottle {
+    last_update_at: Option<Instant>,
+    dirty: bool,
+    timer_armed: bool,
+}
+
+impl UpdateThrottle {
+    fn new() -> Self {
+        Self {
+            last_update_at: None,
+            dirty: false,
+            timer_armed: false,
+        }
+    }
+}
+
+fn schedule_throttled_update(
+    updates: ToolUpdates,
+    output: Arc<Mutex<OutputAccumulator>>,
+    state: Arc<Mutex<UpdateThrottle>>,
+) {
+    tokio::spawn(async move {
+        {
+            let mut guard = state.lock().await;
+            guard.dirty = true;
+            if guard.timer_armed {
+                return;
+            }
+            guard.timer_armed = true;
+        }
+
+        loop {
+            let delay = {
+                let guard = state.lock().await;
+                match guard.last_update_at {
+                    Some(last) => BASH_UPDATE_THROTTLE.saturating_sub(last.elapsed()),
+                    None => Duration::ZERO,
+                }
+            };
+            if !delay.is_zero() {
+                tokio::time::sleep(delay).await;
+            }
+
+            let should_emit = {
+                let mut guard = state.lock().await;
+                if guard.dirty {
+                    guard.dirty = false;
+                    guard.last_update_at = Some(Instant::now());
+                    true
+                } else {
+                    false
+                }
+            };
+            if should_emit {
+                let mut output_guard = output.lock().await;
+                if let Ok(snapshot) = output_guard.snapshot(true) {
+                    updates.send(snapshot_to_partial(&snapshot));
+                }
+            }
+
+            let mut guard = state.lock().await;
+            if guard.dirty {
+                continue;
+            }
+            guard.timer_armed = false;
+            break;
+        }
+    });
+}
+
+fn snapshot_to_partial(snapshot: &OutputSnapshot) -> AgentToolResult {
+    let mut details = Map::new();
+    if snapshot.truncation.truncated
+        && let Ok(value) = serde_json::to_value(&snapshot.truncation)
+    {
+        details.insert("truncation".to_owned(), value);
+    }
+    if let Some(path) = &snapshot.full_output_path {
+        details.insert(
+            "fullOutputPath".to_owned(),
+            Value::String(path.to_string_lossy().into_owned()),
+        );
+    }
+    AgentToolResult {
+        content: vec![ToolResultContent::Text(TextContent::new(
+            snapshot.content.clone(),
+        ))],
+        details: if details.is_empty() {
+            Value::Null
+        } else {
+            Value::Object(details)
+        },
+        added_tool_names: None,
+        terminate: None,
+    }
+}
+
+fn format_output(
+    snapshot: &OutputSnapshot,
+    last_line_bytes: usize,
+    empty_text: &str,
+) -> (String, Option<BashToolDetails>) {
+    let truncation = &snapshot.truncation;
+    let mut text = if snapshot.content.is_empty() {
+        empty_text.to_owned()
+    } else {
+        snapshot.content.clone()
+    };
+    let mut details = None;
+    if truncation.truncated {
+        let full_output_path = snapshot
+            .full_output_path
+            .as_ref()
+            .map(|path| path.to_string_lossy().into_owned());
+        details = Some(BashToolDetails {
+            truncation: Some(truncation.clone()),
+            full_output_path: full_output_path.clone(),
+        });
+        let start_line = truncation
+            .total_lines
+            .saturating_sub(truncation.output_lines)
+            + 1;
+        let end_line = truncation.total_lines;
+        let path_display = full_output_path.unwrap_or_default();
+        if truncation.last_line_partial {
+            let last_line_size = format_size(last_line_bytes as u64);
+            let _ = write!(
+                text,
+                "\n\n[Showing last {} of line {end_line} (line is {last_line_size}). Full output: {path_display}]",
+                format_size(truncation.output_bytes as u64)
+            );
+        } else if truncation.truncated_by == Some(TruncatedBy::Lines) {
+            let _ = write!(
+                text,
+                "\n\n[Showing lines {start_line}-{end_line} of {}. Full output: {path_display}]",
+                truncation.total_lines
+            );
+        } else {
+            let _ = write!(
+                text,
+                "\n\n[Showing lines {start_line}-{end_line} of {} ({} limit). Full output: {path_display}]",
+                truncation.total_lines,
+                format_size(DEFAULT_MAX_BYTES as u64)
+            );
+        }
+    }
+    (text, details)
+}
+
+fn append_status(text: &str, status: &str) -> String {
+    if text.is_empty() {
+        status.to_owned()
+    } else {
+        format!("{text}\n\n{status}")
+    }
+}
+
+fn details_to_value(details: Option<BashToolDetails>) -> Value {
+    match details {
+        Some(details) => serde_json::to_value(details).unwrap_or(Value::Null),
+        None => Value::Null,
+    }
+}
+
+fn accumulator_error(error: &OutputAccumulatorError) -> ToolError {
+    ToolError::new(error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    use serde_json::json;
+    use tempfile::tempdir;
+
+    fn fixture_schema() -> Result<Value, serde_json::Error> {
+        let text = include_str!("../../../tests/fixtures/tool-schemas/bash.json");
+        serde_json::from_str(text)
+    }
+
+    fn json_map(value: Value) -> Result<Map<String, Value>, Box<dyn std::error::Error>> {
+        match value {
+            Value::Object(map) => Ok(map),
+            _ => Err(io::Error::other("test arguments must be a JSON object").into()),
+        }
+    }
+
+    fn required<T>(
+        value: Option<T>,
+        message: &'static str,
+    ) -> Result<T, Box<dyn std::error::Error>> {
+        value.ok_or_else(|| io::Error::other(message).into())
+    }
+
+    fn expected_error<T>(
+        result: Result<T, ToolError>,
+        message: &'static str,
+    ) -> Result<ToolError, Box<dyn std::error::Error>> {
+        match result {
+            Err(error) => Ok(error),
+            Ok(_) => Err(io::Error::other(message).into()),
+        }
+    }
+
+    fn text_of(result: &AgentToolResult) -> String {
+        match result.content.first() {
+            Some(ToolResultContent::Text(text)) => text.text.to_string(),
+            _ => String::new(),
+        }
+    }
+
+    fn text_of_err(error: &ToolError) -> String {
+        error.message().to_owned()
+    }
+
+    #[test]
+    fn schema_matches_typebox_fixture() -> Result<(), Box<dyn std::error::Error>> {
+        let schema = BashTool::parameters_schema();
+        assert_eq!(schema, fixture_schema()?);
+        Ok(())
+    }
+
+    #[test]
+    fn timeout_validation_rejects_non_positive_and_too_large()
+    -> Result<(), Box<dyn std::error::Error>> {
+        assert_eq!(
+            expected_error(resolve_timeout_ms(Some(0.0)), "zero accepted")?.message(),
+            "Invalid timeout: must be a finite number of seconds"
+        );
+        assert_eq!(
+            expected_error(resolve_timeout_ms(Some(-1.0)), "negative accepted")?.message(),
+            "Invalid timeout: must be a finite number of seconds"
+        );
+        assert_eq!(
+            expected_error(resolve_timeout_ms(Some(f64::NAN)), "NaN accepted")?.message(),
+            "Invalid timeout: must be a finite number of seconds"
+        );
+        assert_eq!(
+            expected_error(resolve_timeout_ms(Some(f64::INFINITY)), "infinity accepted",)?
+                .message(),
+            "Invalid timeout: must be a finite number of seconds"
+        );
+        let too_large = MAX_TIMEOUT_SECONDS + 0.001;
+        assert_eq!(
+            expected_error(resolve_timeout_ms(Some(too_large)), "large accepted")?.message(),
+            format!("Invalid timeout: maximum is {MAX_TIMEOUT_SECONDS_DISPLAY} seconds")
+        );
+        assert_eq!(resolve_timeout_ms(Some(1.0))?, Some(1000));
+        assert_eq!(resolve_timeout_ms(Some(0.000_999))?, Some(0));
+        assert_eq!(resolve_timeout_ms(Some(0.001))?, Some(1));
+        assert_eq!(
+            resolve_timeout_ms(Some(MAX_TIMEOUT_SECONDS))?,
+            Some(MAX_TIMEOUT_MS)
+        );
+        assert!(resolve_timeout_ms(None)?.is_none());
+        Ok(())
+    }
+
+    #[test]
+    fn validate_arguments_rejects_bad_timeout() -> Result<(), Box<dyn std::error::Error>> {
+        let tool = BashTool::new("/tmp");
+        let err = expected_error(
+            tool.validate_arguments(&json_map(json!({"command": "true", "timeout": 0}))?),
+            "bad timeout accepted",
+        )?;
+        assert_eq!(
+            err.message(),
+            "Invalid timeout: must be a finite number of seconds"
+        );
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn empty_success_returns_no_output() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"command": "true"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        assert_eq!(text_of(&result), "(no output)");
+        assert!(result.details.is_null());
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn nonempty_success_returns_stdout() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"command": "printf 'hello\n'"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        assert_eq!(text_of(&result), "hello\n");
+        assert!(result.details.is_null());
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn nonzero_exit_appends_status() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let err = expected_error(
+            tool.execute(
+                "1",
+                json_map(json!({"command": "printf 'fail\n'; exit 7"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await,
+            "nonzero exit succeeded",
+        )?;
+        assert_eq!(text_of_err(&err), "fail\n\n\nCommand exited with code 7");
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn interleaves_stdout_and_stderr_by_arrival() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({
+                    "command": "printf 'out1\n'; sleep 0.05; printf 'err1\n' 1>&2; sleep 0.05; printf 'out2\n'"
+                }))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(text.contains("out1"));
+        assert!(text.contains("err1"));
+        assert!(text.contains("out2"));
+        let out1 = required(text.find("out1"), "out1 missing")?;
+        let err1 = required(text.find("err1"), "err1 missing")?;
+        let out2 = required(text.find("out2"), "out2 missing")?;
+        assert!(out1 < err1 && err1 < out2, "text={text:?}");
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn timeout_kills_descendants() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let marker = dir.path().join("child.pid");
+        let marker_str = marker.display().to_string();
+        let tool = BashTool::new(dir.path());
+        let command = format!("sleep 60 & echo $! > '{marker_str}'; wait");
+        let err = expected_error(
+            tool.execute(
+                "1",
+                json_map(json!({"command": command, "timeout": 0.3}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await,
+            "timed command succeeded",
+        )?;
+        assert!(
+            text_of_err(&err).contains("Command timed out after 0.3 seconds"),
+            "{}",
+            text_of_err(&err)
+        );
+
+        let mut child_pid = None;
+        for _ in 0..50 {
+            if marker.exists() {
+                let raw = tokio::fs::read_to_string(&marker).await?;
+                child_pid = raw.trim().parse::<u32>().ok();
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        if let Some(pid) = child_pid {
+            for _ in 0..50 {
+                if !process_alive(pid) {
+                    break;
+                }
+                tokio::time::sleep(Duration::from_millis(20)).await;
+            }
+            assert!(!process_alive(pid), "descendant {pid} still alive");
+        }
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn cancel_kills_descendants_and_wins_race() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let marker = dir.path().join("cancel.pid");
+        let marker_str = marker.display().to_string();
+        let tool = BashTool::new(dir.path());
+        let cancel = CancellationToken::new();
+        let cancel_task = cancel.clone();
+        let command = format!("sleep 60 & echo $! > '{marker_str}'; wait");
+
+        let cancel_args = json_map(json!({"command": command, "timeout": 30.0}))?;
+        let join = tokio::spawn(async move {
+            tool.execute("1", cancel_args, cancel_task, ToolUpdates::noop())
+                .await
+        });
+
+        let mut child_pid = None;
+        for _ in 0..100 {
+            if marker.exists() {
+                let raw = tokio::fs::read_to_string(&marker).await?;
+                child_pid = raw.trim().parse::<u32>().ok();
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+        cancel.cancel();
+        let err = expected_error(join.await?, "cancelled command succeeded")?;
+        assert!(
+            text_of_err(&err).contains("Command aborted"),
+            "{}",
+            text_of_err(&err)
+        );
+        if let Some(pid) = child_pid {
+            for _ in 0..50 {
+                if !process_alive(pid) {
+                    break;
+                }
+                tokio::time::sleep(Duration::from_millis(20)).await;
+            }
+            assert!(!process_alive(pid), "descendant {pid} still alive");
+        }
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn partial_updates_are_throttled() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let seen = Arc::new(AtomicUsize::new(0));
+        let seen_c = Arc::clone(&seen);
+        let updates = ToolUpdates::new(move |_partial| {
+            seen_c.fetch_add(1, Ordering::SeqCst);
+        });
+        let _ = tool
+            .execute(
+                "1",
+                json_map(json!({
+                    "command": "python3 - <<'PY'\nimport sys,time\nfor i in range(20):\n    sys.stdout.write(f'line-{i}\\n')\n    sys.stdout.flush()\n    time.sleep(0.02)\nPY"
+                }))?,
+                CancellationToken::new(),
+                updates,
+            )
+            .await?;
+        let count = seen.load(Ordering::SeqCst);
+        assert!(count >= 2, "expected streaming updates, got {count}");
+        assert!(count < 20, "updates were not throttled: {count}");
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn line_truncation_notice_and_spill() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({
+                    "command": "python3 - <<'PY'\nfor i in range(2100):\n    print(f'L{i}')\nPY"
+                }))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("Showing lines ") && text.contains("Full output: "),
+            "{text}"
+        );
+        let details = required(result.details.as_object(), "details object missing")?;
+        let path = required(
+            details.get("fullOutputPath").and_then(Value::as_str),
+            "spill path missing",
+        )?;
+        assert!(
+            Path::new(path)
+                .file_name()
+                .and_then(|name| name.to_str())
+                .is_some_and(|name| {
+                    name.starts_with("pi-bash-")
+                        && Path::new(name)
+                            .extension()
+                            .is_some_and(|extension| extension.eq_ignore_ascii_case("log"))
+                }),
+            "path={path}"
+        );
+        assert!(Path::new(path).is_file(), "spill missing: {path}");
+        let full = tokio::fs::read_to_string(path).await?;
+        assert!(full.lines().count() >= 2100);
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn byte_truncation_notice_and_spill() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({
+                    "command": format!(
+                        "python3 - <<'PY'\nprint('x'*{})\nPY",
+                        DEFAULT_MAX_BYTES + 100
+                    )
+                }))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("limit). Full output: ") || text.contains("of line "),
+            "{text}"
+        );
+        let details = required(result.details.as_object(), "details object missing")?;
+        let path = required(
+            details.get("fullOutputPath").and_then(Value::as_str),
+            "spill path missing",
+        )?;
+        assert!(Path::new(path).is_file());
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn untruncated_has_no_spill() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = BashTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"command": "printf 'small\n'"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        assert_eq!(text_of(&result), "small\n");
+        assert!(result.details.is_null());
+        Ok(())
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn missing_cwd_errors() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let missing = dir.path().join("nope");
+        let tool = BashTool::new(&missing);
+        let err = expected_error(
+            tool.execute(
+                "1",
+                json_map(json!({"command": "true"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await,
+            "missing cwd accepted",
+        )?;
+        assert!(
+            text_of_err(&err).contains("Working directory does not exist:"),
+            "{}",
+            text_of_err(&err)
+        );
+        Ok(())
+    }
+
+    fn process_alive(pid: u32) -> bool {
+        #[cfg(unix)]
+        {
+            use nix::sys::signal::kill;
+            use nix::unistd::Pid;
+            i32::try_from(pid).is_ok_and(|raw| kill(Pid::from_raw(raw), None).is_ok())
+        }
+        #[cfg(not(unix))]
+        {
+            let _ = pid;
+            false
+        }
+    }
+}