supercode_harness/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::convert::{is_notebook_path, is_pdf_path, notebook_markdown, pdf_markdown};
use crate::tools::{
    image_mime_for, is_image_path, network_checked_redirect_policy, Tool, ToolContext,
    MULTIMODAL_IMAGE_MARKER, NOTEBOOK_EXTENSION,
};

/// `read_file` truncates (never errors) at this many bytes; the agent
/// additionally caps every tool result at `Config::max_tool_output_bytes`
/// (default 100 KB), so the model receives `min` of the two — see
/// `Agent::cap_tool_output`.
pub(crate) const MAX_READ_BYTES: usize = 400_000;
const DEFAULT_BASH_TIMEOUT_MS: u64 = 120_000;

pub(crate) 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()
}

/// P4c (S1.2 `core.tools.read_file.multimodal` / `view_image`): hand-rolled
/// standard base64 (no external dependency — same "small parser over a
/// crate" precedent as `config::glob_match`/`tools::url_host`). Used ONLY
/// to build a `data:` URL for an image tool result.
pub(crate) fn base64_encode(bytes: &[u8]) -> String {
    const ALPHABET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    let mut out = String::with_capacity(bytes.len().div_ceil(3) * 4);
    for chunk in bytes.chunks(3) {
        let b0 = chunk[0];
        let b1 = chunk.get(1).copied();
        let b2 = chunk.get(2).copied();
        out.push(ALPHABET[(b0 >> 2) as usize] as char);
        out.push(ALPHABET[(((b0 & 0x03) << 4) | (b1.unwrap_or(0) >> 4)) as usize] as char);
        match b1 {
            Some(b1) => {
                out.push(ALPHABET[(((b1 & 0x0f) << 2) | (b2.unwrap_or(0) >> 6)) as usize] as char)
            }
            None => out.push('='),
        }
        match b2 {
            Some(b2) => out.push(ALPHABET[(b2 & 0x3f) as usize] as char),
            None => out.push('='),
        }
    }
    out
}

/// BP-2 (catalog:27): the PDF half of the multimodal read — a PDF's text
/// layer, extracted page by page, or an honest structured summary when the
/// document has none (see `tools::convert::pdf_markdown`).
fn pdf_tool_result(path: &Path, bytes: &[u8]) -> String {
    pdf_markdown(
        &path.file_name().unwrap_or_default().to_string_lossy(),
        bytes,
    )
}

/// BP-2: the `.ipynb` half of the same row — cells rendered with outputs.
fn notebook_tool_result(path: &Path, bytes: &[u8]) -> String {
    notebook_markdown(
        &path.file_name().unwrap_or_default().to_string_lossy(),
        bytes,
    )
}

/// P4c: build the `MULTIMODAL_IMAGE_MARKER`-prefixed tool result for a
/// successfully-read image file — `Agent::run_loop` detects this prefix and
/// turns it into a `content_parts` image block instead of plain text.
fn image_tool_result(path: &Path, bytes: &[u8]) -> String {
    let mime = image_mime_for(path);
    let b64 = base64_encode(bytes);
    format!("{MULTIMODAL_IMAGE_MARKER}data:{mime};base64,{b64}")
}

/// P4c (S1.4 `core.nested_instructions`, deferred from P4b): if
/// [`ToolContext::nested_instructions`] is on and `touched` lives in a
/// subdirectory (other than `ctx.cwd` itself, already loaded at session
/// start) that carries its own `CLAUDE.md`/`AGENTS.md` and hasn't been
/// injected yet this conversation, return a banner to append to the calling
/// tool's result. Reuses `agent::import_target_is_contained` — the SAME
/// canonicalize+containment check P4b's `@`-import expansion uses — so a
/// symlinked subdirectory cannot walk the injection outside `ctx.cwd`.
fn nested_instructions_notice(ctx: &ToolContext, touched: &Path) -> Option<String> {
    if !ctx.nested_instructions {
        return None;
    }
    let dir = if touched.is_dir() {
        touched.to_path_buf()
    } else {
        touched.parent()?.to_path_buf()
    };
    if !crate::agent::import_target_is_contained(&dir, &ctx.cwd) {
        return None;
    }
    let root = std::fs::canonicalize(&ctx.cwd).unwrap_or_else(|_| ctx.cwd.clone());
    let real_dir = std::fs::canonicalize(&dir).ok()?;
    if real_dir == root {
        // Already loaded globally at session start by `load_project_context`.
        return None;
    }
    let mut found: Option<(PathBuf, String)> = None;
    for name in ["CLAUDE.md", "AGENTS.md"] {
        let candidate = dir.join(name);
        if let Ok(content) = std::fs::read_to_string(&candidate) {
            found = Some((candidate, content));
            break;
        }
    }
    let (candidate, content) = found?;
    {
        let mut seen = ctx.injected_instruction_dirs.lock().ok()?;
        if !seen.insert(real_dir) {
            // Already injected this conversation — deduped (catalog:84).
            return None;
        }
    }
    let shown = rel(ctx, &candidate);
    Some(format!(
        "\n\n[nested instructions from {shown}]\n{}",
        content.trim()
    ))
}

/// BP-5 (catalog D2 "Path-scoped rules": *rule files activated only when
/// matching files are touched*; cc§2 "`paths:` frontmatter scopes a rule to
/// file globs so it loads only when Claude touches matching files"): every
/// `paths:`-scoped rule whose selector matches `touched` and that has not
/// already been injected this conversation, as a banner to append to the
/// calling tool's result.
///
/// The SAME door [`nested_instructions_notice`] uses — a tool result is
/// where "you just touched a file this instruction is about" can be said —
/// with the selector swapped from the touched file's own directory to the
/// rule's declared globs. Empty (and free of any work) when
/// `[core.path_rules]` is off, because the list is then empty.
fn path_rules_notice(ctx: &ToolContext, touched: &Path) -> Option<String> {
    if ctx.path_rules.is_empty() {
        return None;
    }
    let mut out = String::new();
    for rule in ctx.path_rules.iter().filter(|r| r.is_scoped()) {
        if !rule.matches(touched, &ctx.cwd) {
            continue;
        }
        {
            let mut seen = ctx.injected_rule_files.lock().ok()?;
            if !seen.insert(rule.path.clone()) {
                continue;
            }
        }
        out.push_str("\n\n");
        out.push_str(&rule.render());
    }
    (!out.is_empty()).then_some(out)
}

/// BP-2 (§1.2 `core.tools.read_file.line_numbers`, catalog:26 "Dedicated
/// read with offset/limit, `cat -n` style output"): render one slice of a
/// file for the model. With the knob off this is the raw slice, exactly as
/// before; with it on, every line carries its REAL file line number
/// (`first_line` is the 1-based number of `slice`'s first line, so an
/// `offset` read numbers from the offset, not from 1) in a right-aligned
/// six-column gutter followed by a tab — the gutter Claude Code's Read
/// emits and its models cite line numbers from.
fn render_read_slice(ctx: &ToolContext, slice: &str, first_line: usize) -> String {
    if !ctx.read_line_numbers {
        return slice.to_string();
    }
    number_lines(slice, first_line)
}

/// `cat -n` gutter over `text`, numbering from `first_line`.
pub(crate) fn number_lines(text: &str, first_line: usize) -> String {
    if text.is_empty() {
        return String::new();
    }
    let trailing_newline = text.ends_with('\n');
    let mut out = String::with_capacity(text.len() + 8);
    for (offset, line) in text.lines().enumerate() {
        out.push_str(&format!("{:>6}\t{line}\n", first_line + offset));
    }
    if !trailing_newline {
        out.pop();
    }
    out
}

// ---- 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. Output may be line-numbered `cat -n` style (a right-aligned number and a tab before each line, numbered from `offset`); the numbers are the gutter, not file content. Large files are returned truncated from the start (with a notice stating the true size); pass `offset` (1-based start line) and/or `limit` (number of lines) to read further slices. PDFs come back as extracted text and Jupyter notebooks as their cells with outputs."
    }
    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())))?;
        // P4c (S1.2 `core.tools.read_file.multimodal`): a recognized image
        // file, with the knob on, returns as a model-visible image content
        // block instead of being lossy-decoded as UTF-8 text. Read-tracking
        // (below) still applies; nested-instructions injection is skipped
        // for this branch (the whole result is a machine-parsed marker, not
        // a place to append prose — see `nested_instructions_notice`'s
        // caller below).
        if ctx.multimodal_read && is_image_path(&path) {
            ctx.mark_read_bytes(&path, &bytes);
            return Ok(image_tool_result(&path, &bytes));
        }
        // BP-2 (§1.2 `core.tools.read_file.multimodal`, catalog:27): with
        // the same knob on, a PDF comes back as extracted text pages and a
        // Jupyter notebook as its cells rendered WITH their outputs, rather
        // than as the UTF-8-lossy binary/JSON soup a raw decode produces.
        // Both branches still mark the path read and are still capped by
        // the agent's own `max_tool_output_bytes`.
        if ctx.multimodal_read && is_pdf_path(&path) {
            ctx.mark_read_bytes(&path, &bytes);
            return Ok(pdf_tool_result(&path, &bytes));
        }
        if ctx.multimodal_read && is_notebook_path(&path) {
            ctx.mark_read_bytes(&path, &bytes);
            return Ok(notebook_tool_result(&path, &bytes));
        }
        let text = String::from_utf8_lossy(&bytes);
        let result = if a.offset.is_none() && a.limit.is_none() {
            if bytes.len() > MAX_READ_BYTES {
                let total = bytes.len();
                // Find the largest char boundary <= MAX_READ_BYTES.
                let mut end = MAX_READ_BYTES.min(text.len());
                while end > 0 && !text.is_char_boundary(end) {
                    end -= 1;
                }
                // Prefer to back off further to the previous newline, so the
                // cut lands on a whole line, as long as one exists in the head.
                if let Some(nl) = text[..end].rfind('\n') {
                    end = nl + 1;
                }
                let shown = end;
                let lines = text[..end].matches('\n').count();
                let notice = format!(
                    "[read_file: file is {total} bytes; showing first {shown} bytes ({lines} lines). Pass offset/limit to read more.]\n"
                );
                notice + &render_read_slice(ctx, &text[..end], 1)
            } else {
                render_read_slice(ctx, &text, 1)
            }
        } else {
            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();
            render_read_slice(ctx, &sliced.join("\n"), start + 1)
        };
        // P4c (S1.2 `core.tools.edit_file.require_read_before_edit`): record
        // this read unconditionally (cheap; only ever CONSULTED when the
        // knob is on — see `ToolContext::mark_read`'s doc comment). BP-2:
        // stamped with the bytes just read, so the staleness check compares
        // against exactly what the model was shown.
        ctx.mark_read_bytes(&path, &bytes);
        let mut result = result;
        // P4c (S1.4 `core.nested_instructions`).
        if let Some(notice) = nested_instructions_notice(ctx, &path) {
            result.push_str(&notice);
        }
        // BP-5 (catalog D2 "Path-scoped rules").
        if let Some(notice) = path_rules_notice(ctx, &path) {
            result.push_str(&notice);
        }
        Ok(result)
    }
}

// ---- view_image -------------------------------------------------------------

/// P4c (S1.2 `view_image`, SPLIT CX row `view_image`, catalog:28): a
/// dedicated image-input tool, distinct from `read_file`'s `multimodal`
/// mode — needed as an image pathway when `read_file` itself is disabled
/// (cx-parity, S12). NOT registered by default; only reachable as the
/// optional fifth name in `[core.tools] enabled` (see
/// `ToolRegistry::from_config`).
pub struct ViewImageTool;

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

#[async_trait]
impl Tool for ViewImageTool {
    fn name(&self) -> &str {
        "view_image"
    }
    fn description(&self) -> &str {
        "Read a local image file and return it as a model-visible image content block."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Image file path, absolute or relative to the working directory."}
            },
            "required": ["path"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: ViewImageArgs = parse_args(self.name(), args)?;
        let path = ctx.resolve(&a.path);
        if !is_image_path(&path) {
            return Err(Error::tool(
                self.name(),
                format!(
                    "{} is not a recognized image file (expected one of: png, jpg, jpeg, gif, webp, bmp)",
                    path.display()
                ),
            ));
        }
        let bytes = tokio::fs::read(&path)
            .await
            .map_err(|e| Error::tool(self.name(), format!("{}: {e}", path.display())))?;
        ctx.mark_read(&path);
        Ok(image_tool_result(&path, &bytes))
    }
}

// ---- 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)?;
        // P5-9 (D-5 write-path interception seam): pre-image capture
        // BEFORE the mutation — see `ToolContext::write_observer`'s doc
        // comment. `None` (checkpoint off, the default) is a no-op.
        if let Some(obs) = &ctx.write_observer {
            obs.before_write(&path).await;
        }
        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())))?;
        // P5-11 (§2 modules 28/29, C10): the observer chain's `after_write`
        // may hand back an annotation (a formatter's diff-back, LSP
        // diagnostics, or both) — appended to the result text the model
        // sees, never silently dropped. `None` (both modules off, the
        // default) leaves this byte-identical to pre-P5-11 behavior.
        let mut annotation = String::new();
        if let Some(obs) = &ctx.write_observer {
            if let Some(note) = obs.after_write(&path).await {
                annotation = format!("\n\n{note}");
            }
        }
        Ok(format!(
            "Wrote {} bytes to {}{}",
            a.content.len(),
            rel(ctx, &path),
            annotation
        ))
    }
}

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

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

#[derive(Deserialize)]
struct EditArgs {
    path: String,
    #[serde(default)]
    old_string: String,
    #[serde(default)]
    new_string: String,
    #[serde(default)]
    replace_all: bool,
    /// P4c (S1.2 `core.tools.edit_file.notebook_aware`): 0-based Jupyter
    /// cell index. Presence (with `cell_op`) switches this call into the
    /// notebook cell-surgery branch instead of exact-string replace.
    #[serde(default)]
    cell_index: Option<usize>,
    /// P4c: `"replace"` | `"insert"` | `"delete"`.
    #[serde(default)]
    cell_op: Option<String>,
    /// P4c: the cell's new source text (required for `replace`/`insert`).
    #[serde(default)]
    cell_source: Option<String>,
    /// P4c: cell type for `insert` — `"code"` (default) or `"markdown"`.
    #[serde(default)]
    cell_type: Option<String>,
}

#[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. When notebook-aware editing is enabled, pass `cell_index`/`cell_op` (`replace`|`insert`|`delete`) instead to edit a Jupyter `.ipynb` cell."
    }
    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."},
                "cell_index": {"type": "integer", "description": "0-based Jupyter cell index (notebook-aware mode only)."},
                "cell_op": {"type": "string", "enum": ["replace", "insert", "delete"], "description": "Notebook cell operation (notebook-aware mode only)."},
                "cell_source": {"type": "string", "description": "New cell source text (notebook-aware `replace`/`insert`)."},
                "cell_type": {"type": "string", "enum": ["code", "markdown"], "description": "Cell type for notebook-aware `insert` (default `code`)."}
            },
            "required": ["path"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: EditArgs = parse_args(self.name(), args)?;
        let path = ctx.resolve(&a.path);
        ctx.check_write(&path)?;
        // P5-9 (D-5 write-path interception seam): one capture point ahead
        // of BOTH branches below (notebook cell-surgery and plain-text
        // replace) — whichever this call takes, the pre-image is captured
        // exactly once, before either mutates anything.
        if let Some(obs) = &ctx.write_observer {
            obs.before_write(&path).await;
        }

        // P4c (S1.2 `core.tools.edit_file.require_read_before_edit`, UNIQUE
        // CC row): refuse unless `read_file` has already read this exact
        // path this conversation. `false` (the default) never consults
        // `ToolContext::read_state` at all — byte-identical to today.
        //
        // BP-2 (catalog:32, the "AND UNCHANGED" half): a path read earlier
        // and then modified on disk is refused too. Editing against a view
        // the file no longer has is how an exact-string replace silently
        // clobbers someone else's write — CC refuses it, and so must this.
        if ctx.require_read_before_edit {
            match ctx.read_state(&path) {
                crate::tools::ReadState::Fresh => {}
                crate::tools::ReadState::NeverRead => {
                    return Err(Error::tool(
                        self.name(),
                        format!(
                            "{} must be read with `read_file` before it can be edited this conversation",
                            path.display()
                        ),
                    ))
                }
                crate::tools::ReadState::Stale => {
                    return Err(Error::tool(
                        self.name(),
                        format!(
                            "{} has changed on disk since it was read; read it again before editing",
                            path.display()
                        ),
                    ))
                }
            }
        }

        // P4c (S1.2 `core.tools.edit_file.notebook_aware`): a Jupyter
        // cell-surgery call is routed here BEFORE the exact-string-replace
        // path — `false` (the default), or a `.ipynb` path with no
        // `cell_op`, falls straight through unchanged.
        if ctx.notebook_aware
            && a.cell_op.is_some()
            && path.extension().and_then(|e| e.to_str()) == Some(NOTEBOOK_EXTENSION)
        {
            let result = edit_notebook_cell(self.name(), ctx, &path, &a).await?;
            // BP-2: same re-stamp as the exact-string branch below.
            ctx.mark_read(&path);
            let mut annotation = String::new();
            if let Some(obs) = &ctx.write_observer {
                if let Some(note) = obs.after_write(&path).await {
                    annotation = format!("\n\n{note}");
                }
            }
            return Ok(format!("{result}{annotation}"));
        }

        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 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())))?;
        // BP-2: the model's view of this file is now the bytes IT just
        // wrote, so re-stamp the read record — otherwise the staleness
        // check above would refuse the model's own next edit of the same
        // file (CC's rule is "unchanged BY SOMEONE ELSE", not "never
        // written"). A write observer's diff-back (formatters, module 28)
        // lands after this, which is exactly the C10 case CC re-reads for:
        // it is a real change to the model's view and stays detected.
        ctx.mark_read_bytes(&path, updated.as_bytes());
        let mut result = format!(
            "Replaced {} occurrence(s) in {}",
            if a.replace_all { count } else { 1 },
            rel(ctx, &path)
        );
        // P5-11: see `WriteFileTool::execute`'s matching comment above.
        if let Some(obs) = &ctx.write_observer {
            if let Some(note) = obs.after_write(&path).await {
                result.push_str("\n\n");
                result.push_str(&note);
            }
        }
        if let Some(notice) = nested_instructions_notice(ctx, &path) {
            result.push_str(&notice);
        }
        // BP-5 (catalog D2 "Path-scoped rules").
        if let Some(notice) = path_rules_notice(ctx, &path) {
            result.push_str(&notice);
        }
        Ok(result)
    }
}

/// P4c (S1.2 `core.tools.edit_file.notebook_aware`): Jupyter cell
/// replace/insert/delete over the notebook's `cells` array. The notebook is
/// parsed/re-serialized as generic JSON (`serde_json::Value`) rather than a
/// typed nbformat model — the smallest form that satisfies "cell surgery",
/// matching the catalog's S-sized classification for this row (not a full
/// nbformat crate/schema).
async fn edit_notebook_cell(
    tool_name: &str,
    ctx: &ToolContext,
    path: &Path,
    a: &EditArgs,
) -> Result<String> {
    let text = tokio::fs::read_to_string(path)
        .await
        .map_err(|e| Error::tool(tool_name, format!("{}: {e}", path.display())))?;
    let mut doc: Value = serde_json::from_str(&text).map_err(|e| {
        Error::tool(
            tool_name,
            format!("{}: not valid notebook JSON: {e}", path.display()),
        )
    })?;
    let cells = doc
        .get_mut("cells")
        .and_then(|c| c.as_array_mut())
        .ok_or_else(|| Error::tool(tool_name, format!("{}: no `cells` array", path.display())))?;
    let index = a
        .cell_index
        .ok_or_else(|| Error::tool(tool_name, "cell_index is required for notebook cell edits"))?;
    let op = a.cell_op.as_deref().unwrap_or("replace");
    let summary = match op {
        "delete" => {
            if index >= cells.len() {
                return Err(Error::tool(
                    tool_name,
                    format!("cell_index {index} out of range (0..{})", cells.len()),
                ));
            }
            cells.remove(index);
            format!("Deleted cell {index}")
        }
        "insert" => {
            let source = a
                .cell_source
                .clone()
                .ok_or_else(|| Error::tool(tool_name, "cell_source is required for insert"))?;
            let cell_type = a.cell_type.as_deref().unwrap_or("code");
            let new_cell = json!({
                "cell_type": cell_type,
                "metadata": {},
                "source": [source],
                "outputs": if cell_type == "code" { json!([]) } else { json!(null) },
                "execution_count": json!(null),
            });
            if index > cells.len() {
                return Err(Error::tool(
                    tool_name,
                    format!("cell_index {index} out of range (0..={})", cells.len()),
                ));
            }
            cells.insert(index, new_cell);
            format!("Inserted a {cell_type} cell at {index}")
        }
        "replace" => {
            let source = a
                .cell_source
                .clone()
                .ok_or_else(|| Error::tool(tool_name, "cell_source is required for replace"))?;
            let len = cells.len();
            let cell = cells.get_mut(index).ok_or_else(|| {
                Error::tool(
                    tool_name,
                    format!("cell_index {index} out of range (0..{len})"),
                )
            })?;
            cell["source"] = json!([source]);
            format!("Replaced source of cell {index}")
        }
        other => {
            return Err(Error::tool(
                tool_name,
                format!("unknown cell_op `{other}` (expected replace|insert|delete)"),
            ))
        }
    };
    let rendered =
        serde_json::to_string_pretty(&doc).map_err(|e| Error::tool(tool_name, e.to_string()))?;
    tokio::fs::write(path, rendered.as_bytes())
        .await
        .map_err(|e| Error::tool(tool_name, format!("{}: {e}", path.display())))?;
    Ok(format!("{summary} in {}", 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,
}

/// Owns the process group created for one [`BashTool`] invocation.
///
/// The explicit calls clean up before we await pipe readers or reap the direct
/// child. The `Drop` backstop also covers cancellation of the tool future: a
/// cancelled request must not detach the shell's workers from Supercode.
#[cfg(unix)]
struct BashProcessTreeGuard(Option<u32>);

#[cfg(windows)]
struct BashProcessTreeGuard(Option<usize>);

#[cfg(not(any(unix, windows)))]
struct BashProcessTreeGuard;

impl BashProcessTreeGuard {
    #[cfg(unix)]
    fn prepare() -> std::io::Result<Self> {
        Ok(Self(None))
    }

    #[cfg(windows)]
    fn prepare() -> std::io::Result<Self> {
        use windows_sys::Win32::Foundation::CloseHandle;
        use windows_sys::Win32::System::JobObjects::{
            CreateJobObjectW, JobObjectExtendedLimitInformation, SetInformationJobObject,
            JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
        };

        // A Job Object is Windows' process-tree ownership primitive. Closing
        // this handle terminates every assigned descendant, including on an
        // async future cancellation where no explicit timeout arm runs.
        let job = unsafe { CreateJobObjectW(std::ptr::null(), std::ptr::null()) };
        if job.is_null() {
            return Err(std::io::Error::last_os_error());
        }
        let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() };
        limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
        let configured = unsafe {
            SetInformationJobObject(
                job,
                JobObjectExtendedLimitInformation,
                std::ptr::addr_of!(limits).cast(),
                std::mem::size_of_val(&limits) as u32,
            )
        };
        if configured == 0 {
            let error = std::io::Error::last_os_error();
            unsafe {
                CloseHandle(job);
            }
            return Err(error);
        }
        Ok(Self(Some(job as usize)))
    }

    #[cfg(not(any(unix, windows)))]
    fn prepare() -> std::io::Result<Self> {
        Ok(Self)
    }

    fn configure_command(&self, command: &mut tokio::process::Command) {
        #[cfg(unix)]
        command.process_group(0);
        #[cfg(windows)]
        command.creation_flags(windows_sys::Win32::System::Threading::CREATE_SUSPENDED);
    }

    #[cfg(unix)]
    fn attach_and_start(&mut self, child: &tokio::process::Child) -> std::io::Result<()> {
        self.0 = child.id();
        Ok(())
    }

    #[cfg(windows)]
    fn attach_and_start(&mut self, child: &tokio::process::Child) -> std::io::Result<()> {
        use windows_sys::Win32::System::JobObjects::AssignProcessToJobObject;

        let job = self.0.ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::BrokenPipe,
                "command Job Object is closed",
            )
        })? as windows_sys::Win32::Foundation::HANDLE;
        let process = child.raw_handle().ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::BrokenPipe,
                "suspended command has no process handle",
            )
        })?;
        if unsafe { AssignProcessToJobObject(job, process.cast()) } == 0 {
            return Err(std::io::Error::last_os_error());
        }
        Self::resume_primary_thread(child.id().ok_or_else(|| {
            std::io::Error::new(
                std::io::ErrorKind::BrokenPipe,
                "suspended command has no process id",
            )
        })?)
    }

    #[cfg(windows)]
    fn resume_primary_thread(process_id: u32) -> std::io::Result<()> {
        use windows_sys::Win32::Foundation::{CloseHandle, INVALID_HANDLE_VALUE};
        use windows_sys::Win32::System::Diagnostics::ToolHelp::{
            CreateToolhelp32Snapshot, Thread32First, Thread32Next, TH32CS_SNAPTHREAD, THREADENTRY32,
        };
        use windows_sys::Win32::System::Threading::{
            OpenThread, ResumeThread, THREAD_SUSPEND_RESUME,
        };

        let snapshot = unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPTHREAD, 0) };
        if snapshot == INVALID_HANDLE_VALUE {
            return Err(std::io::Error::last_os_error());
        }
        let result = (|| {
            let mut entry: THREADENTRY32 = unsafe { std::mem::zeroed() };
            entry.dwSize = std::mem::size_of::<THREADENTRY32>() as u32;
            let mut has_entry = unsafe { Thread32First(snapshot, &mut entry) } != 0;
            while has_entry {
                if entry.th32OwnerProcessID == process_id {
                    let thread =
                        unsafe { OpenThread(THREAD_SUSPEND_RESUME, 0, entry.th32ThreadID) };
                    if thread.is_null() {
                        return Err(std::io::Error::last_os_error());
                    }
                    let resumed = unsafe { ResumeThread(thread) };
                    unsafe {
                        CloseHandle(thread);
                    }
                    if resumed == u32::MAX {
                        return Err(std::io::Error::last_os_error());
                    }
                    return Ok(());
                }
                has_entry = unsafe { Thread32Next(snapshot, &mut entry) } != 0;
            }
            Err(std::io::Error::new(
                std::io::ErrorKind::NotFound,
                "suspended command's primary thread was not found",
            ))
        })();
        unsafe {
            CloseHandle(snapshot);
        }
        result
    }

    #[cfg(not(any(unix, windows)))]
    fn attach_and_start(&mut self, _child: &tokio::process::Child) -> std::io::Result<()> {
        Ok(())
    }

    fn kill(&mut self) {
        #[cfg(unix)]
        if let Some(pid) = self.0.take() {
            crate::lsp::kill_process_group(pid);
        }
        #[cfg(windows)]
        if let Some(job) = self.0.take() {
            use windows_sys::Win32::Foundation::CloseHandle;
            use windows_sys::Win32::System::JobObjects::TerminateJobObject;
            let job = job as windows_sys::Win32::Foundation::HANDLE;
            unsafe {
                TerminateJobObject(job, 1);
                CloseHandle(job);
            }
        }
    }
}

impl Drop for BashProcessTreeGuard {
    fn drop(&mut self) {
        self.kill();
    }
}

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>,
    /// BP-10 (catalog row "Sandbox-escalation path", cx§4's own spelling):
    /// the model's request to run this ONE command outside the sandbox,
    /// after a confined attempt failed. See
    /// [`escalation_requested`] for how it is adjudicated — the request is
    /// not the grant.
    #[serde(default)]
    with_escalated_permissions: Option<bool>,
    /// BP-10: why the escalation is needed, in the model's own words —
    /// what the approval door shows the user (cx§4
    /// `sandbox_permissions: "require_escalated"` + justification).
    #[serde(default)]
    /// Read by the permissions gate from the RAW args (see `escalation_requested`);
    /// declared here so the schema and the parse agree on the field.
    #[allow(dead_code)]
    justification: Option<String>,
}

/// BP-10 (catalog row "Sandbox-escalation path"): the ONE place that turns
/// a model-issued `with_escalated_permissions` argument into "run this
/// spawn unconfined", for every shell-family tool.
///
/// **The request is not the grant.** A call carrying this flag was already
/// forced to the permissions engine's `Ask` tier by
/// `crate::agent::Agent::permissions_gate_denial_impl` (which sees the same
/// argument, and hands the approval door the `justification` in the raw
/// args) — so if the tool is executing AT ALL, the escalation was approved
/// by the door, or refused and the tool never ran. That is why this
/// function does not prompt a second time: there is ONE gate, and it has
/// already spoken.
///
/// **Only where that gate exists.** When the permissions engine is off
/// (`capabilities.permissions.enabled = false`), no gate adjudicated the
/// flag, so honoring it would be an unapproved un-sandboxing — a model
/// argument silently switching the sandbox off. In that configuration the
/// flag is refused, loudly, rather than obeyed.
fn escalation_requested(tool: &str, requested: Option<bool>, ctx: &ToolContext) -> Result<bool> {
    if requested != Some(true) {
        return Ok(false);
    }
    if !ctx.permissions_engine_active() {
        return Err(Error::tool(
            tool,
            "with_escalated_permissions requires the permissions engine              (capabilities.permissions.enabled) — there is no approval door to grant it, and              an unadjudicated escalation would switch the sandbox off on the model's say-so",
        ));
    }
    Ok(true)
}

/// BP-10 (catalog row "Sandbox-escalation path", the "fail in sandbox"
/// half): does this finished command look like it failed BECAUSE it was
/// confined? A heuristic over the combined output, consulted only for a
/// non-zero exit of a call that actually ran confined — so a false
/// positive costs one extra sentence of advice, never a behavior change.
///
/// The strings are the ones the two real backstops produce: macOS
/// seatbelt denies with `Operation not permitted` (and names itself in
/// `sandbox-exec` failures), Linux Landlock/`unshare` denies with the same
/// `EPERM` text, and a network cut-off surfaces as a resolver/connect
/// failure.
fn looks_sandbox_denied(output: &str) -> bool {
    const MARKERS: &[&str] = &[
        "operation not permitted",
        "permission denied",
        "read-only file system",
        "sandbox-exec",
        "eperm",
        "could not resolve host",
        "temporary failure in name resolution",
        "network is unreachable",
        "connection refused",
    ];
    let lower = output.to_ascii_lowercase();
    MARKERS.iter().any(|m| lower.contains(m))
}

/// BP-10: the advice appended to a confined command's failed output — the
/// model's CHANNEL to ask for an unsandboxed rerun. Naming the exact
/// argument names is the point: without this line the model has no way to
/// discover that an escalation path exists at all, which is precisely the
/// half of the row that was missing.
fn escalation_hint(tool: &str) -> String {
    format!(
        "\n[{tool}: this command ran inside the sandbox and failed with an error that looks          like a sandbox denial. If it genuinely has to run outside the sandbox, call {tool}          again with `with_escalated_permissions: true` and a `justification` explaining why;          the user is asked before the unsandboxed rerun happens.]"
    )
}

/// BP-2 (catalog:32 footnote "+Bash-view exemptions"): the single file a
/// bash command plainly SHOWED the model, or `None`.
///
/// Deliberately narrow, exactly as the Claude Code inventory states the
/// rule (`cat`/`head`/`tail`/`sed -n`/`grep`/`egrep`/`fgrep`, no pipes or
/// redirects): a shell composition can transform, filter or truncate what
/// the model saw, and an exemption granted on a partial view is how a
/// clobbering edit gets waved through. Anything with shell metacharacters,
/// anything but one existing-file argument, or a `sed` without `-n` is not
/// an exemption.
pub(crate) fn bash_view_target(command: &str) -> Option<String> {
    if command
        .chars()
        .any(|c| matches!(c, '|' | '>' | '<' | ';' | '&' | '`' | '\n'))
        || command.contains("$(")
    {
        return None;
    }
    let tokens: Vec<&str> = command.split_whitespace().collect();
    let (first, rest) = tokens.split_first()?;
    // Accept an absolute path to the same viewer (`/bin/cat`).
    let program = first.rsplit('/').next().unwrap_or(first);
    // Per program: whether the first operand is a PATTERN/script rather
    // than a path, and which flags consume the next token as their value
    // (`head -n 20 file`). Per-program because `sed -n` is a boolean flag
    // while `head -n` takes a count.
    let (takes_pattern, value_flags): (bool, &[&str]) = match program {
        "cat" => (false, &[]),
        "head" | "tail" => (false, &["-n", "-c"]),
        "sed" => (true, &["-e", "-f", "-i"]),
        "grep" | "egrep" | "fgrep" => (true, &["-e", "-f", "-m", "-A", "-B", "-C"]),
        _ => return None,
    };
    if program == "sed" && !rest.iter().any(|t| *t == "-n" || *t == "--quiet") {
        // Without `-n`, `sed` prints its own EDITED stream, not the file.
        return None;
    }
    // Every argument that is neither a flag nor a flag's value; what is
    // left after the pattern must be exactly ONE path, or this is a
    // multi-file view, which CC does not exempt either.
    let mut operands: Vec<String> = Vec::new();
    let mut skip_next = false;
    for token in rest {
        if skip_next {
            skip_next = false;
            continue;
        }
        if token.starts_with('-') {
            skip_next = value_flags.contains(token);
            continue;
        }
        let unquoted = token.trim_matches(|c| c == '\'' || c == '"');
        if unquoted.is_empty() {
            continue;
        }
        operands.push(unquoted.to_string());
    }
    if takes_pattern && !operands.is_empty() {
        operands.remove(0);
    }
    match operands.len() {
        1 => operands.pop(),
        _ => None,
    }
}

#[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)."},
                "with_escalated_permissions": {"type": "boolean", "description": "Run this one command OUTSIDE the sandbox. Only use it after a sandboxed attempt failed for a sandbox reason; the user is asked first, and must supply a justification."},
                "justification": {"type": "string", "description": "Why this command needs to run outside the sandbox. Shown to the user with the approval request."}
            },
            "required": ["command"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: BashArgs = parse_args(self.name(), args)?;
        // BP-10 (catalog row "Sandbox-escalation path"): an APPROVED
        // escalation runs this one command unconfined — see
        // `escalation_requested`'s doc comment for why the approval has
        // already happened by the time we are here.
        let escalated = escalation_requested(self.name(), a.with_escalated_permissions, ctx)?;
        // P4e (S3.1 `core.tools.bash.timeout_secs`, S14): a model-issued
        // `timeout_ms` argument always wins (unchanged); absent that, a
        // configured `ctx.bash_timeout_secs` REPLACES the built-in
        // `self.default_timeout_ms` fallback instead of stacking with it.
        // `ctx.bash_timeout_secs == None` (the default) makes this
        // byte-identical to the pre-P4e single-source fallback.
        let effective_default_ms = ctx
            .bash_timeout_secs
            .map(|s| s.saturating_mul(1000))
            .unwrap_or(self.default_timeout_ms);
        let timeout = Duration::from_millis(a.timeout_ms.unwrap_or(effective_default_ms));
        let deadline = tokio::time::Instant::now() + timeout;

        // P4c (S1.2 `core.shell_env_snapshot`)/P5-10 (`env_policy`):
        // `build_sandboxed_sh` folds `ctx.shell_env` in via
        // `apply_sandbox_env_policy` (its own last step) — a no-op (byte-
        // identical spawn) when `ctx.shell_env` is `None` AND
        // `ctx.sandbox_env_policy` is `Inherit` (both defaults).
        let mut cmd = if escalated {
            build_unsandboxed_sh(&a.command, ctx)
        } else {
            build_sandboxed_sh(&a.command, ctx)?
        };
        cmd.current_dir(&ctx.cwd)
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .kill_on_drop(true);
        // Own the tree before it can execute: Unix creates a new process
        // group at spawn; Windows starts suspended, enters a preconfigured
        // kill-on-close Job Object, and only then resumes its primary thread.
        let mut process_tree = BashProcessTreeGuard::prepare()
            .map_err(|error| Error::tool(self.name(), error.to_string()))?;
        process_tree.configure_command(&mut cmd);
        let mut child = cmd
            .spawn()
            .map_err(|error| Error::tool(self.name(), error.to_string()))?;
        process_tree
            .attach_and_start(&child)
            .map_err(|error| Error::tool(self.name(), error.to_string()))?;
        let mut stdout = child
            .stdout
            .take()
            .ok_or_else(|| Error::tool(self.name(), "spawned command has no stdout"))?;
        let mut stderr = child
            .stderr
            .take()
            .ok_or_else(|| Error::tool(self.name(), "spawned command has no stderr"))?;
        let mut stdout_task = tokio::spawn(async move {
            let mut bytes = Vec::new();
            let result = stdout.read_to_end(&mut bytes).await;
            (result, bytes)
        });
        let mut stderr_task = tokio::spawn(async move {
            let mut bytes = Vec::new();
            let result = stderr.read_to_end(&mut bytes).await;
            (result, bytes)
        });

        let status = match tokio::time::timeout_at(deadline, child.wait()).await {
            Ok(Ok(status)) => status,
            Ok(Err(error)) => {
                process_tree.kill();
                let _ = child.start_kill();
                let _ = tokio::time::timeout(Duration::from_secs(1), child.wait()).await;
                stdout_task.abort();
                stderr_task.abort();
                return Err(Error::tool(self.name(), error.to_string()));
            }
            Err(_) => {
                process_tree.kill();
                let _ = child.start_kill();
                let _ = tokio::time::timeout(Duration::from_secs(1), child.wait()).await;
                stdout_task.abort();
                stderr_task.abort();
                return Err(Error::tool(
                    self.name(),
                    format!("command timed out after {timeout:?}"),
                ));
            }
        };
        // A shell can exit successfully after backgrounding a worker. Bash
        // is the bounded foreground tool; durable work belongs in the
        // background tool. Reap any remaining member before reading EOF.
        process_tree.kill();
        let pipe_output = tokio::time::timeout_at(deadline, async {
            let (stdout_result, stdout) = (&mut stdout_task)
                .await
                .map_err(|error| Error::tool(self.name(), error.to_string()))?;
            stdout_result.map_err(|error| Error::tool(self.name(), error.to_string()))?;
            let (stderr_result, stderr) = (&mut stderr_task)
                .await
                .map_err(|error| Error::tool(self.name(), error.to_string()))?;
            stderr_result.map_err(|error| Error::tool(self.name(), error.to_string()))?;
            Ok::<_, Error>((stdout, stderr))
        })
        .await;
        let (stdout, stderr) = match pipe_output {
            Ok(result) => result?,
            Err(_) => {
                stdout_task.abort();
                stderr_task.abort();
                return Err(Error::tool(
                    self.name(),
                    format!("command timed out after {timeout:?}"),
                ));
            }
        };

        let mut buf = String::new();
        let stdout = String::from_utf8_lossy(&stdout);
        let stderr = String::from_utf8_lossy(&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 = status.code().unwrap_or(-1);
        // BP-2 (catalog:32 fn "+Bash-view exemptions", cc§1 Edit): CC
        // accepts a single-file `cat`/`head`/`tail`/`sed -n`/`grep` view as
        // satisfying read-before-edit, because the model HAS seen the file.
        // Only consulted when the enforcement knob is on, and only for a
        // command that succeeded — a failed view showed the model nothing.
        if ctx.require_read_before_edit && code == 0 {
            if let Some(target) = bash_view_target(&a.command) {
                let resolved = ctx.resolve(&target);
                if resolved.is_file() {
                    ctx.mark_read(&resolved);
                }
            }
        }
        if buf.is_empty() {
            buf.push_str("(no output)");
        }
        // BP-10: the "fail in sandbox → model justifies" half. Only for a
        // call that actually ran confined (an already-escalated rerun, or
        // an unconfined tier, has nothing to escalate to) and only on a
        // failure that looks like a confinement denial.
        if !escalated && code != 0 && ctx.os_sandbox_active() && looks_sandbox_denied(&buf) {
            buf.push_str(&escalation_hint(self.name()));
        }
        Ok(format!("exit code: {code}\n{buf}"))
    }
}

/// P5-10 (§2 module 12): the resolved, platform-agnostic decision
/// [`build_sandboxed_sh`]/[`build_sandboxed_interactive_sh`] act on —
/// computed ONCE by [`resolve_sandbox_plan`] so both callers (and
/// `crate::agent::Agent::background_exec`, via the same shared function)
/// apply the identical fs/net posture, never two independently-computed
/// ones that could drift.
struct SandboxPlan {
    /// Apply real OS fs confinement (seatbelt on macOS, Landlock on
    /// Linux) for this call.
    confine_fs: bool,
    /// `true` for `WorkspaceWrite` (writes allowed under `cwd` + temp),
    /// `false` for `ReadOnly` (no writes at all). Only consulted when
    /// `confine_fs` is `true`.
    #[cfg_attr(not(target_os = "linux"), allow(dead_code))]
    fs_allow_writes: bool,
    /// Apply a real coarse network cut-off (Linux network-namespace
    /// isolation) for this call.
    #[cfg_attr(not(target_os = "linux"), allow(dead_code))]
    confine_net: bool,
}

/// P5-10 (§2 module 12, cardinal rule "no silent-unsandboxed"): resolve
/// what [`build_sandboxed_sh`]/[`build_sandboxed_interactive_sh`] should
/// actually DO for one subprocess spawn — real availability probes
/// ([`crate::sandbox::landlock_available`]/[`crate::sandbox::
/// netns_available`], macOS's seatbelt treated as always-available,
/// matching its pre-P5-10 unconditional trigger) feed the PURE
/// `crate::sandbox::decide_fs`/`decide_net` functions, whose `Refuse`
/// outcome surfaces here as a real `Err` (the tool call fails — "refuse to
/// run the sandboxed subprocess") and whose `RunUnconfinedWithWarning`/
/// `GapWarn` outcomes print the loud one-time warning
/// (`crate::sandbox::warn_once`) and fall through to an UNCONFINED spawn
/// for that axis, rather than ever silently claiming confinement this
/// platform/kernel can't actually provide.
fn resolve_sandbox_plan(ctx: &ToolContext, subject: &str) -> Result<SandboxPlan> {
    use crate::sandbox::{decide_fs, decide_net, warn_once, FsDecision, NetDecision};

    let fs_available = cfg!(target_os = "macos") || crate::sandbox::landlock_available();
    let approval = ctx.sandbox_approval_handler.as_deref();
    let fs_decision = decide_fs(
        ctx.sandbox,
        ctx.sandbox_os_enabled,
        fs_available,
        ctx.sandbox_escalation,
        approval,
        subject,
    );
    let confine_fs = match fs_decision {
        FsDecision::NotRequested => false,
        FsDecision::Confine => true,
        FsDecision::RunUnconfinedWithWarning { reason } => {
            warn_once(&reason);
            false
        }
        FsDecision::Refuse { reason } => return Err(Error::tool("sandbox", reason)),
    };

    let network_enabled = ctx
        .network_policy
        .as_ref()
        .map(|p| p.enabled)
        .unwrap_or(false);
    let has_domain_rules = ctx
        .network_policy
        .as_ref()
        .map(|p| !p.allow_domains.is_empty() || !p.deny_domains.is_empty())
        .unwrap_or(false);
    // BP-10 (catalog row "Network sandbox / domain rules"): macOS has a
    // REAL coarse network primitive of its own — seatbelt's `(deny
    // network*)`, applied by `seatbelt_profile` below — so a coarse
    // cut-off is available here too, not only on a Linux kernel with
    // unprivileged network namespaces. Domain-level filtering is a
    // separate question `decide_net` still answers with `GapWarn` on both
    // platforms (see its own doc comment).
    let net_available = cfg!(target_os = "macos")
        || (cfg!(target_os = "linux") && crate::sandbox::netns_available());
    let net_decision = decide_net(network_enabled, has_domain_rules, net_available);
    let confine_net = match net_decision {
        NetDecision::NotRequested => false,
        NetDecision::Confine => true,
        NetDecision::GapWarn { reason } => {
            warn_once(&reason);
            false
        }
    };

    Ok(SandboxPlan {
        confine_fs,
        fs_allow_writes: ctx.sandbox == crate::tools::SandboxPolicy::WorkspaceWrite,
        confine_net,
    })
}

/// P5-10: apply [`SandboxPlan::confine_net`]/`.confine_fs` to `cmd` via a
/// real `pre_exec` closure — Linux only (see
/// [`crate::sandbox::apply_linux_confinement`]'s own doc comment for the
/// full real-enforcement story: runs in the FORKED CHILD, never touches
/// supercode itself). `cwd`/the system temp dir are resolved through
/// [`crate::safe_path::resolve_real`] (not a bare `std::fs::canonicalize`)
/// — the same dual lexical+resolved discipline every other containment
/// check in this crate uses, so a symlink'd working directory grants the
/// REAL target, not its lexical location. A no-op on non-Linux platforms
/// (macOS's confinement is the separate `seatbelt_profile` wrapper below;
/// every other platform has no primitive at all, which is exactly why
/// `resolve_sandbox_plan` never sets `confine_fs`/`confine_net` there).
#[cfg(target_os = "linux")]
fn apply_linux_plan(cmd: &mut tokio::process::Command, ctx: &ToolContext, plan: &SandboxPlan) {
    if !plan.confine_fs && !plan.confine_net {
        return;
    }
    let cwd = crate::safe_path::resolve_real(&ctx.cwd).unwrap_or_else(|| ctx.cwd.clone());
    let tmp_dir = std::env::temp_dir();
    let tmp = crate::safe_path::resolve_real(&tmp_dir).unwrap_or(tmp_dir);
    // BP-10: every granted `--add-dir` root joins the writable set, so the
    // kernel-level confinement agrees with `ToolContext::check_write`.
    let mut extra = vec![tmp];
    for root in &ctx.extra_roots {
        extra.push(crate::safe_path::resolve_real(root).unwrap_or_else(|| root.clone()));
    }
    crate::sandbox::apply_linux_confinement(
        cmd,
        plan.confine_fs,
        plan.fs_allow_writes,
        cwd,
        extra,
        plan.confine_net,
    );
}

#[cfg(not(target_os = "linux"))]
fn apply_linux_plan(_cmd: &mut tokio::process::Command, _ctx: &ToolContext, _plan: &SandboxPlan) {}

/// P5-10: env-policy pass — the LAST env-related step
/// [`BashTool::execute`]/`PersistentShellTool::execute`/`Agent::
/// background_exec` all apply, AFTER any `ctx.shell_env` snapshot has
/// already been folded in by the caller, so a `Filtered`/`None` policy
/// also strips a secret that arrived via the snapshot (not just the
/// process's own inherited environment) — computing the SAME effective
/// base independently here (rather than trying to introspect what a prior
/// `cmd.envs(...)` call already staged) and then `env_clear` + re-`envs`
/// the filtered result means call order never matters. `Inherit` (the
/// default) is a true no-op: `cmd` is never touched, so the spawn stays
/// byte-identical to pre-P5-10 behavior.
///
/// ALSO folds in `ctx.shell_env` (the `core.shell_env_snapshot` capture)
/// itself, for EVERY policy including `Inherit` — this is now the ONE place
/// that applies the snapshot, so callers must not separately call
/// `cmd.envs(ctx.shell_env...)` beforehand (that would let a secret from
/// the snapshot survive a `Filtered`/`None` policy by re-adding it after
/// this function's `env_clear()`, which is exactly the leak this
/// consolidation closes — see the git history for the P5-10 build's own
/// caught-in-review instance of that bug).
fn apply_sandbox_env_policy(cmd: &mut tokio::process::Command, ctx: &ToolContext) {
    if ctx.sandbox_env_policy == crate::sandbox::SandboxEnvPolicy::Inherit {
        // Byte-identical to pre-P5-10 behavior: don't touch the inherited
        // environment at all, just fold the snapshot on top if configured.
        if let Some(snapshot) = &ctx.shell_env {
            cmd.envs(snapshot.iter().map(|(k, v)| (k.as_str(), v.as_str())));
        }
        return;
    }
    let mut base: Vec<(String, String)> = std::env::vars().collect();
    if let Some(snapshot) = &ctx.shell_env {
        for (k, v) in snapshot.iter() {
            match base.iter_mut().find(|(bk, _)| bk == k) {
                Some(entry) => entry.1 = v.clone(),
                None => base.push((k.clone(), v.clone())),
            }
        }
    }
    let filtered = crate::sandbox::apply_env_policy(ctx.sandbox_env_policy, base);
    cmd.env_clear();
    cmd.envs(filtered);
}

/// Build the `sh -c <command>` invocation, wrapped in real OS process
/// confinement when [`resolve_sandbox_plan`] says to (seatbelt on macOS,
/// Landlock + optional network-namespace isolation on Linux via
/// [`apply_linux_plan`]).
///
/// On macOS this uses `sandbox-exec` (seatbelt): `ReadOnly` denies all file
/// writes; `WorkspaceWrite` denies writes outside the working directory. On
/// Linux, Landlock gives the same real subprocess isolation (a `bash`
/// command cannot escape the policy via the kernel's own enforcement, not
/// just the file-tool confinement) — see `crate::sandbox`'s module doc
/// comment for the full fail-closed/escalation/gap-honesty story. Returns
/// `Err` when a confining tier was requested, this platform/kernel can't
/// provide it, and `escalation` says to refuse (the default) — "refuse to
/// run the sandboxed subprocess" rather than ever silently running
/// unconfined.
///
/// `pub(crate)` (P5-6, §2 module 4 `tools.background`, build brief "reuse
/// the bash tool's execution + sandbox path"): `crate::agent::Agent`'s
/// `background_exec` intrinsic calls this SAME function (re-exported via
/// `crate::tools::build_sandboxed_sh`) rather than reimplementing its own
/// spawn path, so a background command gets byte-identical sandboxing to a
/// foreground `bash` call — one enforcement point, not two that could
/// silently drift apart.
/// BP-10 (catalog row "Sandbox-escalation path"): the APPROVED unsandboxed
/// rerun — the same spawn `build_sandboxed_sh` builds, minus the
/// confinement wrapper. Deliberately a separate, named function rather than
/// a boolean threaded through `build_sandboxed_sh`: an unsandboxed spawn
/// should be greppable and should read as the exception it is. The env
/// policy still applies (an escalated command is unconfined, not
/// un-sanitized — a user who approved "run outside the sandbox" did not
/// thereby hand over their API keys).
pub(crate) fn build_unsandboxed_sh(command: &str, ctx: &ToolContext) -> tokio::process::Command {
    crate::sandbox::warn_once(&format!(
        "sandbox: running an APPROVED escalated command OUTSIDE the sandbox: {command}"
    ));
    let mut cmd = tokio::process::Command::new("sh");
    cmd.arg("-c").arg(command);
    apply_sandbox_env_policy(&mut cmd, ctx);
    cmd
}

pub(crate) fn build_sandboxed_sh(
    command: &str,
    ctx: &ToolContext,
) -> Result<tokio::process::Command> {
    let plan = resolve_sandbox_plan(ctx, command)?;
    #[cfg(target_os = "macos")]
    {
        if plan.confine_fs || plan.confine_net {
            if let Some(profile) = seatbelt_profile(ctx, &plan) {
                let mut cmd = tokio::process::Command::new("sandbox-exec");
                cmd.arg("-p").arg(profile).arg("sh").arg("-c").arg(command);
                apply_sandbox_env_policy(&mut cmd, ctx);
                return Ok(cmd);
            }
        }
    }
    let mut cmd = tokio::process::Command::new("sh");
    cmd.arg("-c").arg(command);
    apply_linux_plan(&mut cmd, ctx, &plan);
    apply_sandbox_env_policy(&mut cmd, ctx);
    Ok(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) -> Result<tokio::process::Command> {
    let plan = resolve_sandbox_plan(ctx, "<persistent shell>")?;
    #[cfg(target_os = "macos")]
    {
        if plan.confine_fs || plan.confine_net {
            if let Some(profile) = seatbelt_profile(ctx, &plan) {
                let mut cmd = tokio::process::Command::new("sandbox-exec");
                cmd.arg("-p").arg(profile).arg("sh");
                apply_sandbox_env_policy(&mut cmd, ctx);
                return Ok(cmd);
            }
        }
    }
    let mut cmd = tokio::process::Command::new("sh");
    apply_linux_plan(&mut cmd, ctx, &plan);
    apply_sandbox_env_policy(&mut cmd, ctx);
    Ok(cmd)
}

/// A seatbelt profile string for the current sandbox plan, or `None` when
/// there is nothing at all to confine.
///
/// BP-10: the profile now carries BOTH axes of [`SandboxPlan`], not the fs
/// tier alone — `confine_net` contributes `(deny network*)`, macOS's real
/// coarse network cut-off (the analogue of the Linux network namespace
/// `crate::sandbox::apply_linux_confinement` uses), so
/// `capabilities.permissions.sandbox.network.enabled` is genuinely
/// enforced on this platform instead of degrading to a `GapWarn`. It also
/// grants every [`ToolContext::write_roots`] entry, so an `--add-dir` root
/// is writable inside the sandbox exactly as `ToolContext::check_write`
/// says it is.
#[cfg(target_os = "macos")]
fn seatbelt_profile(ctx: &ToolContext, plan: &SandboxPlan) -> Option<String> {
    use crate::tools::SandboxPolicy;
    if !plan.confine_fs && !plan.confine_net {
        return None;
    }
    let net = if plan.confine_net {
        "(deny network*)"
    } else {
        ""
    };
    let fs = if !plan.confine_fs {
        String::new()
    } else {
        match ctx.sandbox {
            SandboxPolicy::DangerFullAccess => String::new(),
            SandboxPolicy::ReadOnly => "(deny file-write*)".to_string(),
            SandboxPolicy::WorkspaceWrite => {
                // Allow writes only under the (real) working directory and
                // each granted extra root, plus the usual harmless
                // devices/temp. P5-10: reuses
                // `crate::safe_path::resolve_real` (the shared dual
                // lexical+resolved path primitive every other containment
                // check in this crate now goes through) instead of a bare
                // `std::fs::canonicalize` call, so a symlink'd root
                // resolves identically here and in the Linux Landlock path.
                let mut out = "(deny file-write*)".to_string();
                for root in ctx.write_roots() {
                    let real = crate::safe_path::resolve_real(&root).unwrap_or(root);
                    let dir = real.to_string_lossy().replace('"', "");
                    out.push_str(&format!("(allow file-write* (subpath \"{dir}\"))"));
                }
                out.push_str(
                    "(allow file-write* (literal \"/dev/null\") \
                     (literal \"/dev/dtracehelper\") (literal \"/dev/tty\"))",
                );
                out
            }
        }
    };
    if fs.is_empty() && net.is_empty() {
        return None;
    }
    Some(format!("(version 1)(allow default){fs}{net}"))
}

// ---- 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'"))
}

/// P5-1 F4 (Fable-5 adversarial review): every file path an `apply_patch`
/// envelope's operations target — an `Add`/`Delete`/`Update` op's own
/// `path`, plus an `Update`'s `*** Move to:` destination when present.
/// `crate::agent`'s permissions gate uses this to check a patch's write
/// surface against `protected_paths` rules BEFORE the patch is applied —
/// module 13's protection previously only ever reached `read()`/`write()`
/// pseudo-tool calls, never an `apply_patch` envelope (whose args carry a
/// patch BODY, not a path, so the gate's ordinary `args.get("path")` lookup
/// never fires for it). Reuses [`parse_patch`] rather than re-deriving the
/// envelope grammar — one parser, one source of truth. `Err` propagates a
/// malformed envelope so the gate can fail closed on it too (never silently
/// skip the check just because the patch didn't parse).
pub(crate) fn patch_target_paths(patch: &str) -> Result<Vec<String>> {
    let ops = parse_patch(patch)?;
    let mut paths = Vec::with_capacity(ops.len());
    for op in ops {
        match op {
            PatchOp::Add { path, .. } | PatchOp::Delete { path } => paths.push(path),
            PatchOp::Update { path, move_to, .. } => {
                paths.push(path);
                if let Some(m) = move_to {
                    paths.push(m);
                }
            }
        }
    }
    Ok(paths)
}

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");
        let region = &text[from..];
        let count = region.matches(&old_block).count();
        match count {
            0 => {
                return Err(Error::tool(
                    tool,
                    format!("hunk did not match file contents:\n{old_block}"),
                ))
            }
            1 => {
                let rel = region.find(&old_block).unwrap();
                let start = from + rel;
                text.replace_range(start..start + old_block.len(), &new_block);
            }
            _ => {
                return Err(Error::tool(
                    tool,
                    format!(
                        "hunk matches file contents {count} times; add more context lines or a more specific @@ anchor to disambiguate:\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();
        // P5-11 (§2 modules 28/29, C10): `apply_patch` is multi-file, so
        // annotations from every op's `after_write` are collected here and
        // appended once at the end (rather than interleaved into `summary`)
        // — keeps the per-op summary lines a clean, stable format while
        // still surfacing every formatter diff-back / LSP diagnostics block
        // the model needs to see.
        let mut annotations: Vec<String> = Vec::new();
        for op in ops {
            match op {
                PatchOp::Add { path, body } => {
                    let full = ctx.resolve(&path);
                    ctx.check_write(&full)?;
                    // P5-9 (D-5 seam): capture BEFORE each op's own mutation
                    // — `apply_patch` is multi-file, so this fires once per
                    // path actually touched, not once for the whole call.
                    if let Some(obs) = &ctx.write_observer {
                        obs.before_write(&full).await;
                    }
                    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()))
                        })?;
                    if let Some(obs) = &ctx.write_observer {
                        if let Some(note) = obs.after_write(&full).await {
                            annotations.push(note);
                        }
                    }
                    summary.push(format!("A {}", rel(ctx, &full)));
                }
                PatchOp::Delete { path } => {
                    let full = ctx.resolve(&path);
                    ctx.check_write(&full)?;
                    if let Some(obs) = &ctx.write_observer {
                        obs.before_write(&full).await;
                    }
                    tokio::fs::remove_file(&full).await.map_err(|e| {
                        Error::tool(self.name(), format!("{}: {e}", full.display()))
                    })?;
                    if let Some(obs) = &ctx.write_observer {
                        // A deleted file has nothing to format/diagnose —
                        // still call the hook (some future observer might
                        // care about deletions) but a formatter/lsp
                        // observer's `after_write` is a no-op on a path
                        // that no longer exists, so this is never expected
                        // to produce an annotation in practice.
                        if let Some(note) = obs.after_write(&full).await {
                            annotations.push(note);
                        }
                    }
                    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)?;
                    // Capture BOTH the source (`full` — read then possibly
                    // deleted on a move) and, when a move targets a
                    // DIFFERENT path, the destination's own pre-image too
                    // (it may already exist and be about to be overwritten).
                    if let Some(obs) = &ctx.write_observer {
                        obs.before_write(&full).await;
                        if dest_for_check != full {
                            obs.before_write(&dest_for_check).await;
                        }
                    }
                    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();
                        if let Some(obs) = &ctx.write_observer {
                            if let Some(note) = obs.after_write(&dest).await {
                                annotations.push(note);
                            }
                        }
                        summary.push(format!("M {} -> {}", rel(ctx, &full), rel(ctx, &dest)));
                    } else {
                        if let Some(obs) = &ctx.write_observer {
                            if let Some(note) = obs.after_write(&full).await {
                                annotations.push(note);
                            }
                        }
                        summary.push(format!("U {}", rel(ctx, &full)));
                    }
                }
            }
        }
        let annotation = if annotations.is_empty() {
            String::new()
        } else {
            format!("\n\n{}", annotations.join("\n\n"))
        };
        if summary.is_empty() {
            Ok("(empty patch)".to_string())
        } else {
            Ok(format!(
                "Applied patch:\n{}{annotation}",
                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.
///
/// Known limitation (documented, not fixed — see UX-29.md "Known
/// limitations"): if a REPL turn is hard-cancelled (`race_ctrl_c` in
/// `crates/cli/src/main.rs`) while `execute()` below is mid-`.await` waiting
/// for the completion sentinel, only that `.await` is dropped — the `child`
/// held in `ShellState` is untouched (by design: it must survive to serve
/// the NEXT call in this REPL session) and keeps running the in-flight
/// command to completion on its own schedule. The cancelled command's
/// eventual output (and sentinel line) still lands in the shared stdout
/// pipe, so the next `shell` call in the same session can either block
/// behind the stale command finishing or read a garbage prefix ahead of its
/// own sentinel. This is no worse than the pre-existing hard-kill behavior
/// this ticket replaced (which would have torn down the whole process), and
/// the on-disk session file itself is unaffected — only the persistent
/// shell's own child-process state can go stale.
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__";

use std::sync::atomic::{AtomicU64, Ordering};

static SHELL_SENTINEL_SEQ: AtomicU64 = AtomicU64::new(0);

/// Per-invocation completion sentinel: base string + unguessable hex token.
/// RandomState is seeded from OS entropy once per process; hashing
/// (pid, per-call counter, wall-clock nanos) through it yields a token a
/// user command cannot predict, with no new dependencies.
fn shell_sentinel() -> String {
    use std::hash::BuildHasher;
    let seq = SHELL_SENTINEL_SEQ.fetch_add(1, Ordering::Relaxed);
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_nanos())
        .unwrap_or(0);
    let hash =
        std::collections::hash_map::RandomState::new().hash_one((std::process::id(), seq, nanos));
    format!("{SHELL_SENTINEL}_{hash:016x}{seq:04x}")
}

#[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. The sentinel is unguessable per-call so a
        // command that echoes the base string can't spoof completion.
        let sentinel = shell_sentinel();
        let wrapped = format!("{{ {command}\n}} 2>&1\nprintf '%s %d\\n' '{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(&sentinel) {
                    let after = &acc[pos + 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).
///
/// BP-8 (catalog:156 "Todos/plan persisted per session"): the plan itself
/// lives on [`ToolContext::plan`], not in this tool. A tool-local mutex was
/// unreadable by the agent, so `[capabilities.todos] persist = true` had
/// nothing to persist and a plan died with the process; on the shared
/// context, the agent journals every change and a resume restores it.
#[derive(Default)]
pub struct UpdatePlanTool;

#[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>,
}

#[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)?;
        ctx.set_plan(
            a.plan
                .iter()
                .map(|s| crate::session_journal::PlanEntry {
                    step: s.step.clone(),
                    status: s.status.clone(),
                })
                .collect(),
        );
        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}")
        })
    }
}

/// P4c-review (LOW follow-up): render a `reqwest::Error` together with its
/// full `source()` chain. `reqwest::Error`'s own `Display` for a redirect
/// blocked by [`network_checked_redirect_policy`] shows only "error
/// following redirect for url (...)" — the actually useful reason (this
/// crate's own "host `x` is denied by the active network policy" message)
/// lives one level down the `source()` chain and would otherwise be
/// silently dropped, leaving a vague tool error for the model to act on.
fn describe_reqwest_error(e: &reqwest::Error) -> String {
    let mut out = e.to_string();
    let mut source = std::error::Error::source(e);
    while let Some(s) = source {
        out.push_str(": ");
        out.push_str(&s.to_string());
        source = s.source();
    }
    out
}

// ---- web_fetch / web_search (S2 module 5 `tools.web`) --------------------

/// P4c (S2 module 5 `tools.web`, S4a "trivially addable... single tool
/// each, no loop changes"): fetch a URL and return it AS MARKDOWN (BP-2,
/// catalog:44 "Fetch a URL, convert to markdown, return to model"), served
/// from an on-disk cache within [`WEB_FETCH_TTL_SECS`] of the last fetch —
/// CC's WebFetch is markdown-converting and cached, and a model that
/// re-fetches the same page mid-task should not pay for it twice. NOT
/// registered by default — only reached via `[capabilities.tools_web]`
/// (module 5), off by default (§3.1). SECURITY (S2.1 S17): honors
/// `ToolContext::network_policy` when one is configured (see
/// `ToolContext::check_network`) — a caller (SDK embedder) that has set up
/// a sandbox/network policy on the context gets it enforced here too; with
/// no policy configured (today's honest default), the fetch is
/// unrestricted, same posture as every other network-capable path in this
/// crate today (C3).
pub struct WebFetchTool;

/// Cap the fetched body at this many bytes before returning it to the model
/// — the same order of magnitude as `MAX_READ_BYTES`.
const MAX_FETCH_BYTES: usize = 200_000;

/// BP-2: how long a cached fetch stays servable. CC's WebFetch keeps a
/// self-cleaning 15-minute cache; same window.
pub(crate) const WEB_FETCH_TTL_SECS: u64 = 900;

/// BP-2: directory override for the fetch cache (tests, and an operator who
/// wants it somewhere specific).
pub const WEB_CACHE_DIR_ENV: &str = "SUPERCODE_WEB_CACHE_DIR";

/// BP-2: where cached fetches live — `$SUPERCODE_WEB_CACHE_DIR`, else
/// `$SUPERCODE_HOME`/`~/.supercode/web-cache`, else a temp dir. Same
/// resolution ladder as `runtime::supercode_runtime_root`.
pub(crate) fn web_cache_root() -> PathBuf {
    if let Some(dir) = std::env::var_os(WEB_CACHE_DIR_ENV) {
        return PathBuf::from(dir);
    }
    std::env::var_os("SUPERCODE_HOME")
        .map(PathBuf::from)
        .or_else(|| {
            std::env::var_os("HOME")
                .map(PathBuf::from)
                .map(|home| home.join(".supercode"))
        })
        .unwrap_or_else(|| std::env::temp_dir().join("supercode"))
        .join("web-cache")
}

fn web_cache_path(url: &str) -> PathBuf {
    web_cache_root().join(format!("{}.md", blake3::hash(url.as_bytes()).to_hex()))
}

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

/// BP-2: a still-fresh cached body for `url`, with its age in seconds.
///
/// The entry's first line is `<unix-secs> <url>`; the url is stored so a
/// hash collision (or a hand-edited cache dir) can never serve one page's
/// content under another's name.
pub(crate) fn web_cache_get(url: &str) -> Option<(String, u64)> {
    let text = std::fs::read_to_string(web_cache_path(url)).ok()?;
    let (header, body) = text.split_once('\n')?;
    let (stamp, cached_url) = header.split_once(' ')?;
    if cached_url != url {
        return None;
    }
    let stamped: u64 = stamp.parse().ok()?;
    let age = unix_secs().saturating_sub(stamped);
    if age > WEB_FETCH_TTL_SECS {
        return None;
    }
    Some((body.to_string(), age))
}

/// BP-2: record `body` as `url`'s cached rendering. Best-effort — a cache
/// that cannot be written must never fail the fetch.
pub(crate) fn web_cache_put(url: &str, body: &str) {
    let path = web_cache_path(url);
    if let Some(parent) = path.parent() {
        let _ = std::fs::create_dir_all(parent);
    }
    let _ = std::fs::write(path, format!("{} {url}\n{body}", unix_secs()));
}

/// BP-2: does this response look like HTML (so it should be converted)?
fn is_html_response(content_type: Option<&str>, body: &str) -> bool {
    if let Some(ct) = content_type {
        let ct = ct.to_ascii_lowercase();
        if ct.contains("html") {
            return true;
        }
        if ct.contains("json") || ct.contains("text/plain") || ct.contains("markdown") {
            return false;
        }
    }
    let head = body.trim_start();
    let head = &head[..head.len().min(512)].to_ascii_lowercase();
    head.starts_with("<!doctype html") || head.starts_with("<html") || head.contains("<body")
}

/// BP-2: cut `text` to at most `MAX_FETCH_BYTES` on a char boundary.
fn cap_fetch_body(text: &str) -> (&str, bool) {
    let mut end = MAX_FETCH_BYTES.min(text.len());
    while end > 0 && !text.is_char_boundary(end) {
        end -= 1;
    }
    (&text[..end], text.len() > MAX_FETCH_BYTES)
}

#[derive(Deserialize)]
struct WebFetchArgs {
    url: String,
}

#[async_trait]
impl Tool for WebFetchTool {
    fn name(&self) -> &str {
        "web_fetch"
    }
    fn description(&self) -> &str {
        "Fetch a URL over HTTP(S) and return its content as markdown (HTML is converted; other content types are returned as text, truncated if large). Recent fetches of the same URL are served from a local cache."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "url": {"type": "string", "description": "The http:// or https:// URL to fetch."}
            },
            "required": ["url"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: WebFetchArgs = parse_args(self.name(), args)?;
        ctx.check_network(&a.url)?;
        if !a.url.starts_with("http://") && !a.url.starts_with("https://") {
            return Err(Error::tool(self.name(), "url must be http:// or https://"));
        }
        // BP-2 (catalog:44 "cached"): a repeat fetch inside the TTL is
        // served from disk. The notice says so, so the model can tell a
        // cached page from a live one.
        if let Some((body, age)) = web_cache_get(&a.url) {
            return Ok(format!("[web_fetch: cached {age}s ago]\n{body}"));
        }
        // P4c-review (MEDIUM/LOW follow-up): re-run the same host check on
        // every redirect hop, not just this initial url — closes the SSRF
        // gap where a denied host reachable only via an allowed host's HTTP
        // redirect would otherwise slip past `check_network` above (see
        // `network_checked_redirect_policy`'s doc comment).
        let client = reqwest::Client::builder()
            .timeout(Duration::from_secs(30))
            .redirect(network_checked_redirect_policy(
                ctx.network_policy.clone(),
                ctx.permission_rules.clone(),
            ))
            .build()
            .map_err(|e| Error::tool(self.name(), e.to_string()))?;
        let resp = client.get(&a.url).send().await.map_err(|e| {
            Error::tool(
                self.name(),
                format!("fetch failed: {}", describe_reqwest_error(&e)),
            )
        })?;
        let status = resp.status();
        let content_type = resp
            .headers()
            .get(reqwest::header::CONTENT_TYPE)
            .and_then(|v| v.to_str().ok())
            .map(|v| v.to_string());
        let body = resp
            .text()
            .await
            .map_err(|e| Error::tool(self.name(), format!("failed to read response body: {e}")))?;
        // BP-2: HTML becomes markdown; anything else is returned as-is —
        // converting JSON or plain text would destroy it.
        let (rendered, converted) = if is_html_response(content_type.as_deref(), &body) {
            (crate::tools::convert::html_to_markdown(&body), true)
        } else {
            (body, false)
        };
        let (shown, truncated) = cap_fetch_body(&rendered);
        if status.is_success() {
            web_cache_put(&a.url, shown);
        }
        let form = if converted { "markdown" } else { "text" };
        Ok(if truncated {
            format!(
                "[web_fetch: HTTP {status}; {form}, {} bytes, showing first {}]\n{shown}",
                rendered.len(),
                shown.len()
            )
        } else {
            format!("[web_fetch: HTTP {status}; {form}]\n{shown}")
        })
    }
}

/// P4c (S2 module 5 `tools.web`): perform a web search.
///
/// BP-2 (catalog:45, "supercode bundles no search backend" closed): the
/// tool works out of the box against DuckDuckGo's public HTML endpoint
/// ([`DEFAULT_WEB_SEARCH_URL`]) — the same "no key, no account" surface a
/// browser gets — and an operator can point it anywhere else with
/// [`WEB_SEARCH_URL_ENV`], which keeps its existing `<url>?q=<query>`
/// contract. Results are extracted into a numbered title/url/snippet list;
/// a page whose markup this does not recognize falls back to the page as
/// markdown rather than to a claim of zero hits. A backend that cannot be
/// reached says so, naming the endpoint it tried and the override.
pub struct WebSearchTool;

/// Environment variable naming the search endpoint `WebSearchTool` queries.
pub const WEB_SEARCH_URL_ENV: &str = "SUPERCODE_WEB_SEARCH_URL";

/// BP-2: the backend used when no operator endpoint is configured.
pub const DEFAULT_WEB_SEARCH_URL: &str = "https://html.duckduckgo.com/html/";

/// BP-2: the endpoint this call will query, and whether it is the built-in
/// default (as opposed to an operator's override).
pub(crate) fn web_search_endpoint() -> (String, bool) {
    match std::env::var(WEB_SEARCH_URL_ENV) {
        Ok(url) if !url.trim().is_empty() => (url, false),
        _ => (DEFAULT_WEB_SEARCH_URL.to_string(), true),
    }
}

/// BP-2: HTML endpoints reject an unidentified client; identify honestly.
const WEB_SEARCH_USER_AGENT: &str = concat!("supercode/", env!("CARGO_PKG_VERSION"));

#[derive(Deserialize)]
struct WebSearchArgs {
    query: String,
}

#[async_trait]
impl Tool for WebSearchTool {
    fn name(&self) -> &str {
        "web_search"
    }
    fn description(&self) -> &str {
        "Search the web and return the top results as a numbered list of titles, URLs and snippets."
    }
    fn parameters(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query."}
            },
            "required": ["query"],
            "additionalProperties": false
        })
    }
    async fn execute(&self, args: Value, ctx: &ToolContext) -> Result<String> {
        let a: WebSearchArgs = parse_args(self.name(), args)?;
        let (endpoint, is_default) = web_search_endpoint();
        ctx.check_network(&endpoint)?;
        // P4c-review: same redirect-hop re-check as `WebFetchTool` — see
        // `network_checked_redirect_policy`'s doc comment.
        let client = reqwest::Client::builder()
            .timeout(Duration::from_secs(30))
            .redirect(network_checked_redirect_policy(
                ctx.network_policy.clone(),
                ctx.permission_rules.clone(),
            ))
            .build()
            .map_err(|e| Error::tool(self.name(), e.to_string()))?;
        let resp = client
            .get(&endpoint)
            .header(reqwest::header::USER_AGENT, WEB_SEARCH_USER_AGENT)
            .query(&[("q", &a.query)])
            .send()
            .await
            .map_err(|e| {
                let source = if is_default {
                    format!(
                        "the built-in search backend ({endpoint}) is unreachable: {}. Set {WEB_SEARCH_URL_ENV} to use a different search endpoint.",
                        describe_reqwest_error(&e)
                    )
                } else {
                    format!(
                        "the configured search endpoint ({endpoint}, from {WEB_SEARCH_URL_ENV}) is unreachable: {}",
                        describe_reqwest_error(&e)
                    )
                };
                Error::tool(self.name(), format!("search failed: {source}"))
            })?;
        let status = resp.status();
        let body = resp
            .text()
            .await
            .map_err(|e| Error::tool(self.name(), format!("failed to read response body: {e}")))?;
        let results = crate::tools::convert::parse_html_search_results(&body);
        if !results.is_empty() {
            return Ok(crate::tools::convert::render_search_results(
                &a.query, &results,
            ));
        }
        // Nothing recognizable: hand back what the endpoint actually said,
        // as markdown when it is a page, rather than claiming zero hits.
        let rendered = if is_html_response(None, &body) {
            crate::tools::convert::html_to_markdown(&body)
        } else {
            body
        };
        let (shown, _) = cap_fetch_body(&rendered);
        Ok(format!(
            "[web_search: HTTP {status} from {endpoint}; no recognizable result list — the raw response follows]\n{shown}"
        ))
    }
}