supercode/tools/

builtins.rs

//! Built-in tools: file read/write/edit, directory listing, glob, content
//! search, and shell execution.

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

use async_trait::async_trait;
use serde::de::DeserializeOwned;
use serde::Deserialize;
use serde_json::{json, Value};

use crate::error::{Error, Result};
use crate::tools::{Tool, ToolContext};

const MAX_READ_BYTES: usize = 400_000;
const DEFAULT_BASH_TIMEOUT_MS: u64 = 120_000;

fn parse_args<T: DeserializeOwned>(tool: &str, args: Value) -> Result<T> {
    serde_json::from_value(args).map_err(|e| Error::InvalidArguments {
        tool: tool.to_string(),
        message: e.to_string(),
    })
}

fn rel(ctx: &ToolContext, p: &Path) -> String {
    p.strip_prefix(&ctx.cwd)
        .unwrap_or(p)
        .to_string_lossy()
        .into_owned()
}

// ---- read -----------------------------------------------------------------

/// Read a UTF-8 text file.
pub struct ReadFileTool;

#[derive(Deserialize)]
struct ReadArgs {
    path: String,
    #[serde(default)]
    offset: Option<usize>,
    #[serde(default)]
    limit: Option<usize>,
}

#[async_trait]
impl Tool for ReadFileTool {
    fn name(&self) -> &str {
        "read_file"
    }
    fn description(&self) -> &str {
        "Read the contents of a UTF-8 text file. Optionally pass `offset` (1-based start line) and `limit` (number of lines) to read a slice of a large file."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path, absolute or relative to the working directory."},
                "offset": {"type": "integer", "description": "1-based line to start at."},
                "limit": {"type": "integer", "description": "Maximum number of lines to return."}
            },
            "required": ["path"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: ReadArgs = parse_args(self.name(), args)?;
        let path = ctx.resolve(&a.path);
        let bytes = tokio::fs::read(&path)
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", path.display())))?;
        if bytes.len() > MAX_READ_BYTES && a.offset.is_none() && a.limit.is_none() {
            return Err(Error::tool(
                self.name(),
                format!(
                    "file is {} bytes (> {MAX_READ_BYTES}); pass offset/limit to read a slice",
                    bytes.len()
                ),
            ));
        }
        let text = String::from_utf8_lossy(&bytes);
        if a.offset.is_none() && a.limit.is_none() {
            return Ok(text.into_owned());
        }
        let start = a.offset.unwrap_or(1).saturating_sub(1);
        let limit = a.limit.unwrap_or(usize::MAX);
        let sliced: Vec<&str> = text.lines().skip(start).take(limit).collect();
        Ok(sliced.join("\n"))
    }
}

// ---- write ----------------------------------------------------------------

/// Create or overwrite a file.
pub struct WriteFileTool;

#[derive(Deserialize)]
struct WriteArgs {
    path: String,
    content: String,
}

#[async_trait]
impl Tool for WriteFileTool {
    fn name(&self) -> &str {
        "write_file"
    }
    fn description(&self) -> &str {
        "Create or overwrite a file with the given contents. Parent directories are created as needed."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to write."},
                "content": {"type": "string", "description": "Full file contents."}
            },
            "required": ["path", "content"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: WriteArgs = parse_args(self.name(), args)?;
        let path = ctx.resolve(&a.path);
        ctx.check_write(&path)?;
        if let Some(parent) = path.parent() {
            tokio::fs::create_dir_all(parent).await.ok();
        }
        tokio::fs::write(&path, a.content.as_bytes())
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", path.display())))?;
        Ok(format!(
            "Wrote {} bytes to {}",
            a.content.len(),
            rel(ctx, &path)
        ))
    }
}

// ---- edit -----------------------------------------------------------------

/// Replace an exact substring in a file.
pub struct EditFileTool;

#[derive(Deserialize)]
struct EditArgs {
    path: String,
    old_string: String,
    new_string: String,
    #[serde(default)]
    replace_all: bool,
}

#[async_trait]
impl Tool for EditFileTool {
    fn name(&self) -> &str {
        "edit_file"
    }
    fn description(&self) -> &str {
        "Replace an exact substring in a file. By default `old_string` must occur exactly once; set `replace_all` to replace every occurrence."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "old_string": {"type": "string", "description": "Exact text to replace."},
                "new_string": {"type": "string", "description": "Replacement text."},
                "replace_all": {"type": "boolean", "description": "Replace every occurrence instead of requiring uniqueness."}
            },
            "required": ["path", "old_string", "new_string"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: EditArgs = parse_args(self.name(), args)?;
        if a.old_string.is_empty() {
            // An empty needle matches at every char boundary; with replace_all
            // that would interleave new_string through the whole file.
            return Err(Error::tool(self.name(), "old_string must not be empty"));
        }
        let path = ctx.resolve(&a.path);
        ctx.check_write(&path)?;
        let original = tokio::fs::read_to_string(&path)
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", path.display())))?;
        let count = original.matches(&a.old_string).count();
        if count == 0 {
            return Err(Error::tool(self.name(), "old_string not found in file"));
        }
        if count > 1 && !a.replace_all {
            return Err(Error::tool(
                self.name(),
                format!("old_string occurs {count} times; pass replace_all or add more context"),
            ));
        }
        let updated = if a.replace_all {
            original.replace(&a.old_string, &a.new_string)
        } else {
            original.replacen(&a.old_string, &a.new_string, 1)
        };
        tokio::fs::write(&path, updated.as_bytes())
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", path.display())))?;
        Ok(format!(
            "Replaced {} occurrence(s) in {}",
            if a.replace_all { count } else { 1 },
            rel(ctx, &path)
        ))
    }
}

// ---- list -----------------------------------------------------------------

/// List directory entries.
pub struct ListDirTool;

#[derive(Deserialize)]
struct ListArgs {
    #[serde(default)]
    path: Option<String>,
}

#[async_trait]
impl Tool for ListDirTool {
    fn name(&self) -> &str {
        "list_dir"
    }
    fn description(&self) -> &str {
        "List the entries of a directory (defaults to the working directory). Directories are suffixed with `/`."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Directory to list. Defaults to the working directory."}
            },
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: ListArgs = parse_args(self.name(), args)?;
        let dir = match a.path {
            Some(p) => ctx.resolve(&p),
            None => ctx.cwd.clone(),
        };
        let mut rd = tokio::fs::read_dir(&dir)
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", dir.display())))?;
        let mut entries = Vec::new();
        while let Some(e) = rd
            .next_entry()
            .await
            .map_err(|e| Error::tool(self.name(), e.to_string()))?
        {
            let name = e.file_name().to_string_lossy().into_owned();
            let is_dir = e.file_type().await.map(|t| t.is_dir()).unwrap_or(false);
            entries.push(if is_dir { format!("{name}/") } else { name });
        }
        entries.sort();
        if entries.is_empty() {
            Ok("(empty directory)".to_string())
        } else {
            Ok(entries.join("\n"))
        }
    }
}

// ---- glob -----------------------------------------------------------------

/// Match files by glob pattern.
pub struct GlobTool;

#[derive(Deserialize)]
struct GlobArgs {
    pattern: String,
}

#[async_trait]
impl Tool for GlobTool {
    fn name(&self) -> &str {
        "glob"
    }
    fn description(&self) -> &str {
        "Find files matching a glob pattern (e.g. `src/**/*.rs`), relative to the working directory."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "pattern": {"type": "string", "description": "Glob pattern, e.g. **/*.rs"}
            },
            "required": ["pattern"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: GlobArgs = parse_args(self.name(), args)?;
        let cwd = ctx.cwd.clone();
        let full = if PathBuf::from(&a.pattern).is_absolute() {
            a.pattern.clone()
        } else {
            cwd.join(&a.pattern).to_string_lossy().into_owned()
        };
        let cwd2 = cwd.clone();
        let matches = tokio::task::spawn_blocking(move || {
            let mut out = Vec::new();
            if let Ok(paths) = glob::glob(&full) {
                for p in paths.flatten() {
                    let display = p
                        .strip_prefix(&cwd2)
                        .unwrap_or(&p)
                        .to_string_lossy()
                        .into_owned();
                    out.push(display);
                }
            }
            out
        })
        .await
        .map_err(|e| Error::tool("glob", e.to_string()))?;
        if matches.is_empty() {
            Ok("(no matches)".to_string())
        } else {
            Ok(matches.join("\n"))
        }
    }
}

// ---- search ---------------------------------------------------------------

/// Regex search file contents (respecting .gitignore).
pub struct SearchTool;

#[derive(Deserialize)]
struct SearchArgs {
    pattern: String,
    #[serde(default)]
    path: Option<String>,
    #[serde(default)]
    max_results: Option<usize>,
}

#[async_trait]
impl Tool for SearchTool {
    fn name(&self) -> &str {
        "search"
    }
    fn description(&self) -> &str {
        "Search file contents with a regular expression, respecting .gitignore. Returns `path:line: text` matches."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "pattern": {"type": "string", "description": "Regular expression to search for."},
                "path": {"type": "string", "description": "Directory or file to search. Defaults to the working directory."},
                "max_results": {"type": "integer", "description": "Cap on the number of matches (default 200)."}
            },
            "required": ["pattern"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: SearchArgs = parse_args(self.name(), args)?;
        let re = regex::Regex::new(&a.pattern)
            .map_err(|e| Error::tool(self.name(), format!("invalid regex: {e}")))?;
        let root = match a.path {
            Some(p) => ctx.resolve(&p),
            None => ctx.cwd.clone(),
        };
        let cwd = ctx.cwd.clone();
        let cap = a.max_results.unwrap_or(200);
        let results = tokio::task::spawn_blocking(move || {
            let mut out: Vec<String> = Vec::new();
            let walker = ignore::WalkBuilder::new(&root).build();
            'outer: for entry in walker.flatten() {
                if !entry.file_type().map(|t| t.is_file()).unwrap_or(false) {
                    continue;
                }
                let path = entry.path();
                let Ok(content) = std::fs::read_to_string(path) else {
                    continue; // skip binary / unreadable
                };
                for (i, line) in content.lines().enumerate() {
                    if re.is_match(line) {
                        let rel = path.strip_prefix(&cwd).unwrap_or(path);
                        out.push(format!("{}:{}: {}", rel.display(), i + 1, line.trim_end()));
                        if out.len() >= cap {
                            break 'outer;
                        }
                    }
                }
            }
            out
        })
        .await
        .map_err(|e| Error::tool("search", e.to_string()))?;
        if results.is_empty() {
            Ok("(no matches)".to_string())
        } else {
            Ok(results.join("\n"))
        }
    }
}

// ---- bash -----------------------------------------------------------------

/// Run a shell command via `sh -c`.
pub struct BashTool {
    default_timeout_ms: u64,
}

impl Default for BashTool {
    fn default() -> Self {
        BashTool {
            default_timeout_ms: DEFAULT_BASH_TIMEOUT_MS,
        }
    }
}

#[derive(Deserialize)]
struct BashArgs {
    command: String,
    #[serde(default)]
    timeout_ms: Option<u64>,
}

#[async_trait]
impl Tool for BashTool {
    fn name(&self) -> &str {
        "bash"
    }
    fn description(&self) -> &str {
        "Execute a shell command via `sh -c` in the working directory and return its combined stdout/stderr and exit code."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "Shell command to run."},
                "timeout_ms": {"type": "integer", "description": "Timeout in milliseconds (default 120000)."}
            },
            "required": ["command"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: BashArgs = parse_args(self.name(), args)?;
        let timeout = Duration::from_millis(a.timeout_ms.unwrap_or(self.default_timeout_ms));

        let mut cmd = build_sandboxed_sh(&a.command, ctx);
        cmd.current_dir(&ctx.cwd).stdin(std::process::Stdio::null());

        let fut = cmd.output();
        let output = match tokio::time::timeout(timeout, fut).await {
            Ok(Ok(o)) => o,
            Ok(Err(e)) => return Err(Error::tool(self.name(), e.to_string())),
            Err(_) => {
                return Err(Error::tool(
                    self.name(),
                    format!("command timed out after {timeout:?}"),
                ))
            }
        };

        let mut buf = String::new();
        let stdout = String::from_utf8_lossy(&output.stdout);
        let stderr = String::from_utf8_lossy(&output.stderr);
        if !stdout.is_empty() {
            buf.push_str(&stdout);
        }
        if !stderr.is_empty() {
            if !buf.is_empty() && !buf.ends_with('\n') {
                buf.push('\n');
            }
            buf.push_str(&stderr);
        }
        let code = output.status.code().unwrap_or(-1);
        if buf.is_empty() {
            buf.push_str("(no output)");
        }
        Ok(format!("exit code: {code}\n{buf}"))
    }
}

/// Build the `sh -c <command>` invocation, wrapped in an OS process sandbox
/// when the policy requires it and the platform supports it.
///
/// On macOS this uses `sandbox-exec` (seatbelt): `ReadOnly` denies all file
/// writes; `WorkspaceWrite` denies writes outside the working directory. This
/// gives real subprocess isolation (a `bash` command cannot escape the policy),
/// not just the file-tool confinement. On other platforms (no portable
/// primitive wired up yet) the command runs unsandboxed — callers needing
/// hard isolation there should run supercode inside a container.
fn build_sandboxed_sh(command: &str, ctx: &ToolContext) -> tokio::process::Command {
    #[cfg(target_os = "macos")]
    {
        use crate::tools::SandboxPolicy;
        if ctx.sandbox != SandboxPolicy::DangerFullAccess {
            if let Some(profile) = seatbelt_profile(ctx) {
                let mut cmd = tokio::process::Command::new("sandbox-exec");
                cmd.arg("-p").arg(profile).arg("sh").arg("-c").arg(command);
                return cmd;
            }
        }
    }
    let _ = ctx;
    let mut cmd = tokio::process::Command::new("sh");
    cmd.arg("-c").arg(command);
    cmd
}

/// Like [`build_sandboxed_sh`] but for the *persistent* shell: an interactive
/// `sh` reading commands from its stdin (no `-c`). Without this the `shell`
/// tool would be an unsandboxed escape hatch around the policy that `bash`
/// honors.
fn build_sandboxed_interactive_sh(ctx: &ToolContext) -> tokio::process::Command {
    #[cfg(target_os = "macos")]
    {
        use crate::tools::SandboxPolicy;
        if ctx.sandbox != SandboxPolicy::DangerFullAccess {
            if let Some(profile) = seatbelt_profile(ctx) {
                let mut cmd = tokio::process::Command::new("sandbox-exec");
                cmd.arg("-p").arg(profile).arg("sh");
                return cmd;
            }
        }
    }
    let _ = ctx;
    tokio::process::Command::new("sh")
}

/// A seatbelt profile string for the current sandbox policy, or `None` for
/// full access.
#[cfg(target_os = "macos")]
fn seatbelt_profile(ctx: &ToolContext) -> Option<String> {
    use crate::tools::SandboxPolicy;
    match ctx.sandbox {
        SandboxPolicy::DangerFullAccess => None,
        SandboxPolicy::ReadOnly => Some("(version 1)(allow default)(deny file-write*)".to_string()),
        SandboxPolicy::WorkspaceWrite => {
            // Allow writes only under the (real) working directory, plus the
            // usual harmless devices/temp.
            let real = std::fs::canonicalize(&ctx.cwd).unwrap_or_else(|_| ctx.cwd.clone());
            let dir = real.to_string_lossy().replace('"', "");
            Some(format!(
                "(version 1)(allow default)(deny file-write*)\
(allow file-write* (subpath \"{dir}\"))\
(allow file-write* (literal \"/dev/null\") (literal \"/dev/dtracehelper\") (literal \"/dev/tty\"))"
            ))
        }
    }
}

// ---- apply_patch ----------------------------------------------------------

/// Apply a Codex-style `apply_patch` envelope — Codex's primary edit
/// mechanism, richer than `edit_file`'s single string replace. Supports
/// `Add File`, `Delete File`, and `Update File` (with `-`/`+`/context hunks and
/// an optional `*** Move to:` rename) in one atomic-ish call.
pub struct ApplyPatchTool;

#[derive(Deserialize)]
struct ApplyPatchArgs {
    /// The full `*** Begin Patch … *** End Patch` text.
    patch: String,
}

/// One file operation parsed from a patch.
enum PatchOp {
    Add {
        path: String,
        body: String,
    },
    Delete {
        path: String,
    },
    Update {
        path: String,
        move_to: Option<String>,
        hunks: Vec<Hunk>,
    },
}

/// A single update hunk: lines to match (context + removed) and the replacement
/// (context + added), in order. `anchor` is the optional text after the `@@`
/// header — it scopes where the hunk applies (and where a pure insertion goes).
#[derive(Default)]
struct Hunk {
    old: Vec<String>,
    new: Vec<String>,
    anchor: Option<String>,
}

fn parse_patch(patch: &str) -> Result<Vec<PatchOp>> {
    let err = |m: &str| Error::tool("apply_patch", m.to_string());
    let lines: Vec<&str> = patch.lines().collect();
    let mut i = 0;
    // Skip to Begin Patch.
    while i < lines.len() && lines[i].trim() != "*** Begin Patch" {
        i += 1;
    }
    if i == lines.len() {
        return Err(err("missing '*** Begin Patch'"));
    }
    i += 1;

    let mut ops = Vec::new();
    while i < lines.len() {
        let line = lines[i];
        let t = line.trim_end();
        if t == "*** End Patch" {
            return Ok(ops);
        } else if let Some(p) = t.strip_prefix("*** Add File: ") {
            i += 1;
            let mut body = Vec::new();
            while i < lines.len() && lines[i].starts_with('+') {
                body.push(&lines[i][1..]);
                i += 1;
            }
            ops.push(PatchOp::Add {
                path: p.to_string(),
                body: body.join("\n"),
            });
        } else if let Some(p) = t.strip_prefix("*** Delete File: ") {
            ops.push(PatchOp::Delete {
                path: p.to_string(),
            });
            i += 1;
        } else if let Some(p) = t.strip_prefix("*** Update File: ") {
            i += 1;
            let mut move_to = None;
            if i < lines.len() {
                if let Some(m) = lines[i].trim_end().strip_prefix("*** Move to: ") {
                    move_to = Some(m.to_string());
                    i += 1;
                }
            }
            let mut hunks = Vec::new();
            let mut cur = Hunk::default();
            let mut started = false;
            while i < lines.len() {
                let l = lines[i];
                let lt = l.trim_end();
                if lt.starts_with("*** ") {
                    break; // next section
                }
                if let Some(anchor) = lt.strip_prefix("@@") {
                    if started && (!cur.old.is_empty() || !cur.new.is_empty()) {
                        hunks.push(std::mem::take(&mut cur));
                    }
                    // The text after `@@` (e.g. `@@ def foo():`) anchors the hunk.
                    let anchor = anchor.trim();
                    cur.anchor = (!anchor.is_empty()).then(|| anchor.to_string());
                    started = true;
                    i += 1;
                    continue;
                }
                started = true;
                if let Some(rest) = l.strip_prefix('+') {
                    cur.new.push(rest.to_string());
                } else if let Some(rest) = l.strip_prefix('-') {
                    cur.old.push(rest.to_string());
                } else {
                    // context line (leading space, or bare)
                    let ctx = l.strip_prefix(' ').unwrap_or(l).to_string();
                    cur.old.push(ctx.clone());
                    cur.new.push(ctx);
                }
                i += 1;
            }
            if !cur.old.is_empty() || !cur.new.is_empty() {
                hunks.push(cur);
            }
            ops.push(PatchOp::Update {
                path: p.to_string(),
                move_to,
                hunks,
            });
        } else {
            // Stray line between sections — skip.
            i += 1;
        }
    }
    Err(err("missing '*** End Patch'"))
}

fn apply_update(original: &str, hunks: &[Hunk], tool: &str) -> Result<String> {
    let mut text = original.to_string();
    for h in hunks {
        // Resolve the `@@` anchor (if any) to a byte offset to search from, so
        // the hunk applies at the right place and an ambiguous old-block isn't
        // matched at the wrong (first) occurrence.
        let from = match &h.anchor {
            Some(a) => {
                let Some(pos) = text.find(a.as_str()) else {
                    return Err(Error::tool(tool, format!("@@ anchor not found: {a}")));
                };
                // Start just past the end of the anchor's line.
                text[pos..]
                    .find('\n')
                    .map(|nl| pos + nl + 1)
                    .unwrap_or(text.len())
            }
            None => 0,
        };

        let new_block = h.new.join("\n");

        if h.old.is_empty() {
            // Pure insertion. With an anchor, insert right after it; otherwise
            // append at EOF (the only sensible place with no location info).
            if h.anchor.is_some() {
                let needs_lead_nl = from > 0 && text.as_bytes()[from - 1] != b'\n';
                let payload = if needs_lead_nl {
                    format!("\n{new_block}\n")
                } else {
                    format!("{new_block}\n")
                };
                text.insert_str(from, &payload);
            } else {
                if !text.is_empty() && !text.ends_with('\n') {
                    text.push('\n');
                }
                text.push_str(&new_block);
            }
            continue;
        }

        let old_block = h.old.join("\n");
        match text[from..].find(&old_block) {
            Some(rel) => {
                let start = from + rel;
                text.replace_range(start..start + old_block.len(), &new_block);
            }
            None => {
                return Err(Error::tool(
                    tool,
                    format!("hunk did not match file contents:\n{old_block}"),
                ))
            }
        }
    }
    Ok(text)
}

#[async_trait]
impl Tool for ApplyPatchTool {
    fn name(&self) -> &str {
        "apply_patch"
    }
    fn description(&self) -> &str {
        "Apply a patch in the apply_patch envelope format (*** Begin Patch / *** End Patch) with Add File, Delete File, and Update File operations. Update hunks use leading '+'/'-'/' ' on each line and may include '@@' context headers and an optional '*** Move to:' rename."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "patch": {"type": "string", "description": "The full *** Begin Patch … *** End Patch text."}
            },
            "required": ["patch"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: ApplyPatchArgs = parse_args(self.name(), args)?;
        let ops = parse_patch(&a.patch)?;
        let mut summary = Vec::new();
        for op in ops {
            match op {
                PatchOp::Add { path, body } => {
                    let full = ctx.resolve(&path);
                    ctx.check_write(&full)?;
                    if let Some(parent) = full.parent() {
                        tokio::fs::create_dir_all(parent).await.ok();
                    }
                    tokio::fs::write(&full, body.as_bytes())
                        .await
                        .map_err(|e| {
                            Error::tool(self.name(), format!("{}: {e}", full.display()))
                        })?;
                    summary.push(format!("A {}", rel(ctx, &full)));
                }
                PatchOp::Delete { path } => {
                    let full = ctx.resolve(&path);
                    ctx.check_write(&full)?;
                    tokio::fs::remove_file(&full).await.map_err(|e| {
                        Error::tool(self.name(), format!("{}: {e}", full.display()))
                    })?;
                    summary.push(format!("D {}", rel(ctx, &full)));
                }
                PatchOp::Update {
                    path,
                    move_to,
                    hunks,
                } => {
                    let full = ctx.resolve(&path);
                    let dest_for_check = move_to
                        .as_ref()
                        .map(|m| ctx.resolve(m))
                        .unwrap_or_else(|| full.clone());
                    ctx.check_write(&dest_for_check)?;
                    let original = tokio::fs::read_to_string(&full).await.map_err(|e| {
                        Error::tool(self.name(), format!("{}: {e}", full.display()))
                    })?;
                    let updated = apply_update(&original, &hunks, self.name())?;
                    let dest = match &move_to {
                        Some(m) => ctx.resolve(m),
                        None => full.clone(),
                    };
                    if let Some(parent) = dest.parent() {
                        tokio::fs::create_dir_all(parent).await.ok();
                    }
                    tokio::fs::write(&dest, updated.as_bytes())
                        .await
                        .map_err(|e| {
                            Error::tool(self.name(), format!("{}: {e}", dest.display()))
                        })?;
                    if move_to.is_some() && dest != full {
                        tokio::fs::remove_file(&full).await.ok();
                        summary.push(format!("M {} -> {}", rel(ctx, &full), rel(ctx, &dest)));
                    } else {
                        summary.push(format!("U {}", rel(ctx, &full)));
                    }
                }
            }
        }
        if summary.is_empty() {
            Ok("(empty patch)".to_string())
        } else {
            Ok(format!("Applied patch:\n{}", summary.join("\n")))
        }
    }
}

// ---- persistent shell -----------------------------------------------------

use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::sync::Mutex as AsyncMutex;

/// A long-lived shell whose state (working directory, environment variables,
/// shell functions) persists across calls — unlike the one-shot [`BashTool`].
/// Also supports `write_stdin` to feed raw input to the shell, for driving
/// interactive programs. This is the analog of Codex's persistent exec session.
pub struct PersistentShellTool {
    state: AsyncMutex<Option<ShellState>>,
    default_timeout_ms: u64,
}

impl Default for PersistentShellTool {
    fn default() -> Self {
        PersistentShellTool {
            state: AsyncMutex::new(None),
            default_timeout_ms: DEFAULT_BASH_TIMEOUT_MS,
        }
    }
}

struct ShellState {
    // Held to keep the shell process alive for the tool's lifetime; dropping it
    // would terminate the persistent shell.
    #[allow(dead_code)]
    child: tokio::process::Child,
    stdin: tokio::process::ChildStdin,
    stdout: tokio::io::BufReader<tokio::process::ChildStdout>,
}

const SHELL_SENTINEL: &str = "__SC_SHELL_DONE__";

#[derive(Deserialize)]
struct ShellArgs {
    #[serde(default)]
    command: Option<String>,
    #[serde(default)]
    write_stdin: Option<String>,
    #[serde(default)]
    timeout_ms: Option<u64>,
}

impl PersistentShellTool {
    async fn ensure_started(
        &self,
        state: &mut Option<ShellState>,
        ctx: &ToolContext,
    ) -> Result<()> {
        if state.is_some() {
            return Ok(());
        }
        let mut child = build_sandboxed_interactive_sh(ctx)
            .current_dir(&ctx.cwd)
            .stdin(std::process::Stdio::piped())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            // Don't leave the shell (or its sandbox-exec wrapper) running if the
            // tool is dropped without an explicit shutdown.
            .kill_on_drop(true)
            .spawn()
            .map_err(|e| Error::tool("shell", format!("spawn sh: {e}")))?;
        let stdin = child
            .stdin
            .take()
            .ok_or_else(|| Error::tool("shell", "no stdin"))?;
        let stdout = tokio::io::BufReader::new(
            child
                .stdout
                .take()
                .ok_or_else(|| Error::tool("shell", "no stdout"))?,
        );
        *state = Some(ShellState {
            child,
            stdin,
            stdout,
        });
        Ok(())
    }
}

#[async_trait]
impl Tool for PersistentShellTool {
    fn name(&self) -> &str {
        "shell"
    }
    fn description(&self) -> &str {
        "Run a command in a PERSISTENT shell whose working directory, environment, and shell functions survive across calls (unlike one-shot bash). Pass `command` to run to completion (returns exit code), or `write_stdin` to feed raw input to the shell (for interactive programs)."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "Command to run in the persistent shell."},
                "write_stdin": {"type": "string", "description": "Raw text to write to the shell's stdin instead of running a command."},
                "timeout_ms": {"type": "integer", "description": "Timeout in milliseconds (default 120000)."}
            },
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: ShellArgs = parse_args(self.name(), args)?;
        let timeout = Duration::from_millis(a.timeout_ms.unwrap_or(self.default_timeout_ms));
        let mut guard = self.state.lock().await;
        self.ensure_started(&mut guard, ctx).await?;
        let st = guard.as_mut().expect("started");

        if let Some(input) = a.write_stdin {
            st.stdin
                .write_all(input.as_bytes())
                .await
                .map_err(|e| Error::tool(self.name(), format!("write_stdin: {e}")))?;
            st.stdin.flush().await.ok();
            // Best-effort: read whatever output arrives within a short window.
            let out = read_available(&mut st.stdout, Duration::from_millis(800)).await;
            return Ok(if out.is_empty() {
                "(no output)".into()
            } else {
                out
            });
        }

        let command = a
            .command
            .ok_or_else(|| Error::tool(self.name(), "provide `command` or `write_stdin`"))?;
        // Wrap so the command's stderr merges into stdout, then emit a sentinel
        // line carrying the exit code.
        let wrapped =
            format!("{{ {command}\n}} 2>&1\nprintf '%s %d\\n' '{SHELL_SENTINEL}' \"$?\"\n");
        st.stdin
            .write_all(wrapped.as_bytes())
            .await
            .map_err(|e| Error::tool(self.name(), format!("write: {e}")))?;
        st.stdin.flush().await.ok();

        // Accumulate bytes until the sentinel line appears. Byte-based (not
        // line-based) so a flush that splits mid-line can't stall us.
        let mut acc = String::new();
        let mut code = -1;
        let read_fut = async {
            let mut chunk = [0u8; 4096];
            loop {
                let n = st.stdout.read(&mut chunk).await.unwrap_or(0);
                if n == 0 {
                    break; // EOF
                }
                acc.push_str(&String::from_utf8_lossy(&chunk[..n]));
                if let Some(pos) = acc.find(SHELL_SENTINEL) {
                    let after = &acc[pos + SHELL_SENTINEL.len()..];
                    if let Some(nl) = after.find('\n') {
                        code = after[..nl].trim().parse().unwrap_or(-1);
                        acc.truncate(pos);
                        break;
                    }
                }
            }
        };
        if tokio::time::timeout(timeout, read_fut).await.is_err() {
            return Err(Error::tool(
                self.name(),
                format!("command timed out after {timeout:?}"),
            ));
        }
        let output = if acc.trim().is_empty() {
            "(no output)".to_string()
        } else {
            acc.trim_end().to_string()
        };
        Ok(format!("exit code: {code}\n{output}"))
    }
}

/// Read whatever bytes are available on a reader within `window`, returning the
/// decoded text. Used by `write_stdin` where there is no completion sentinel.
async fn read_available<R: AsyncReadExt + Unpin>(reader: &mut R, window: Duration) -> String {
    let mut buf = Vec::new();
    let mut chunk = [0u8; 4096];
    loop {
        match tokio::time::timeout(window, reader.read(&mut chunk)).await {
            Ok(Ok(0)) => break, // EOF
            Ok(Ok(n)) => buf.extend_from_slice(&chunk[..n]),
            Ok(Err(_)) => break,
            Err(_) => break, // window elapsed
        }
    }
    String::from_utf8_lossy(&buf).into_owned()
}

// ---- update_plan ----------------------------------------------------------

/// A simple plan / task tracker. The model calls it to record or update a
/// checklist of steps (the analog of Codex `update_plan` / Claude's plan mode).
/// The plan is held in the tool so it persists across calls within a session.
pub struct UpdatePlanTool {
    plan: std::sync::Mutex<Vec<PlanStep>>,
}

impl Default for UpdatePlanTool {
    fn default() -> Self {
        UpdatePlanTool {
            plan: std::sync::Mutex::new(Vec::new()),
        }
    }
}

#[derive(Deserialize, Clone)]
struct PlanStep {
    step: String,
    #[serde(default = "default_status")]
    status: String,
}
fn default_status() -> String {
    "pending".to_string()
}

#[derive(Deserialize)]
struct PlanArgs {
    plan: Vec<PlanStep>,
}

impl UpdatePlanTool {
    /// The current plan as `(step, status)` pairs.
    pub fn current(&self) -> Vec<(String, String)> {
        self.plan
            .lock()
            .unwrap()
            .iter()
            .map(|s| (s.step.clone(), s.status.clone()))
            .collect()
    }
}

#[async_trait]
impl Tool for UpdatePlanTool {
    fn name(&self) -> &str {
        "update_plan"
    }
    fn description(&self) -> &str {
        "Record or update the task plan: a checklist of steps with statuses (pending/in_progress/completed). Replaces the current plan. Use it to track multi-step work."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "plan": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "step": {"type": "string"},
                            "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}
                        },
                        "required": ["step"]
                    }
                }
            },
            "required": ["plan"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, _ctx: &ToolContext) -> Result<String> {
        let a: PlanArgs = parse_args(self.name(), args)?;
        *self.plan.lock().unwrap() = a.plan.clone();
        let rendered = a
            .plan
            .iter()
            .map(|s| {
                let mark = match s.status.as_str() {
                    "completed" => "[x]",
                    "in_progress" => "[~]",
                    _ => "[ ]",
                };
                format!("{mark} {}", s.step)
            })
            .collect::<Vec<_>>()
            .join("\n");
        Ok(if rendered.is_empty() {
            "(empty plan)".into()
        } else {
            format!("Plan updated:\n{rendered}")
        })
    }
}