car_engine/

agent_basics.rs

use crate::registry::{ToolEntry, ToolPermission};
use crate::substrate::Substrate;
use regex::Regex;
use serde_json::{json, Value};
use std::collections::HashMap;
use std::hash::{Hash, Hasher};
use std::path::{Component, Path, PathBuf};
use std::sync::{Arc, Mutex};

const MAX_FILE_BYTES: usize = 512 * 1024;

/// How a path stands relative to what an agent session has already observed —
/// the input to the read-before-edit / staleness guard (H1/F4-remainder,
/// audit 2026-07-06).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadState {
    /// The session has never read or written this path.
    Unread,
    /// The session recorded this path, but the current on-disk content differs
    /// from what it recorded — the file changed since it was last seen.
    Stale,
    /// The recorded content hash matches, but the agent observed only a slice.
    FreshPartial,
    /// The recorded content hash matches and the agent observed the full file.
    FreshFull,
}

#[derive(Debug, Clone, Copy)]
struct ReadRecord {
    hash: u64,
    full_read: bool,
}

/// Per-session record of which paths an agent has read (or written), keyed by
/// the path string as the model passed it (lexical `.` components are normalized
/// away — see [`ReadLedger::normalize_key`]) and valued by a content hash of the
/// FULL file text plus whether the agent actually observed that full text. It
/// backs the read-before-edit / staleness guard on the
/// built-in `edit_file`/`write_file` tools: an edit (or an overwrite/append onto
/// an existing file) is licensed only once the session has observed that path's
/// current content, so the model can't blind-edit a file it never read or clobber
/// one that changed underneath it.
///
/// Interior mutability is a plain `std::sync::Mutex` (never held across an
/// `.await`), so a `&ReadLedger` can live behind a shared `Arc<dyn ToolExecutor>`.
#[derive(Debug, Default)]
pub struct ReadLedger {
    seen: Mutex<HashMap<String, ReadRecord>>,
    mutation_locks: Arc<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>>,
}

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

    fn with_mutation_locks(
        mutation_locks: Arc<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>>,
    ) -> Self {
        Self {
            seen: Mutex::new(HashMap::new()),
            mutation_locks,
        }
    }

    /// Content hash of the FULL file text. `std::hash::DefaultHasher` is used
    /// deliberately: the ledger only needs same-process change detection, not a
    /// cryptographic digest.
    fn hash(content: &str) -> u64 {
        let mut hasher = std::collections::hash_map::DefaultHasher::new();
        content.hash(&mut hasher);
        hasher.finish()
    }

    /// Normalize a path into its ledger key. Lexical `.` components are removed
    /// so clamped `root/./src/x.rs` and `root/src/x.rs` share an observation.
    /// Parent components remain intact: the substrate owns actual path
    /// resolution and authorization.
    fn normalize_key(path: &str) -> String {
        let mut normalized = PathBuf::new();
        for component in Path::new(path).components() {
            if !matches!(component, Component::CurDir) {
                normalized.push(component.as_os_str());
            }
        }
        if normalized.as_os_str().is_empty() {
            ".".to_string()
        } else {
            normalized.to_string_lossy().into_owned()
        }
    }

    /// Record that `path` currently holds `content` (its FULL text). Called on a
    /// successful read and after a successful write/edit, so a later edit is
    /// licensed and staleness compares against this snapshot. `full_read` says
    /// whether the agent observed all of `content`, which whole-file writes and
    /// replace-all edits require.
    pub fn record(&self, path: &str, content: &str, full_read: bool) {
        let record = ReadRecord {
            hash: Self::hash(content),
            full_read,
        };
        self.seen
            .lock()
            .expect("read ledger mutex poisoned")
            .insert(Self::normalize_key(path), record);
    }

    /// Classify `path` against `content` (its current FULL text).
    pub fn check(&self, path: &str, content: &str) -> ReadState {
        let guard = self.seen.lock().expect("read ledger mutex poisoned");
        match guard.get(&Self::normalize_key(path)) {
            None => ReadState::Unread,
            Some(recorded) if recorded.hash == Self::hash(content) && recorded.full_read => {
                ReadState::FreshFull
            }
            Some(recorded) if recorded.hash == Self::hash(content) => ReadState::FreshPartial,
            Some(_) => ReadState::Stale,
        }
    }

    /// Serialize guarded mutations of one lexical path. The guard spans the
    /// read/check/write/record sequence so two same-session edits cannot both
    /// pass the stale check against one snapshot and lose one update.
    pub fn mutation_lock(&self, path: &str) -> Arc<tokio::sync::Mutex<()>> {
        let key = Self::normalize_key(path);
        let mut locks = self
            .mutation_locks
            .lock()
            .expect("read ledger mutation-lock mutex poisoned");
        locks
            .entry(key)
            .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(())))
            .clone()
    }

    pub fn clear(&self) {
        self.seen
            .lock()
            .expect("read ledger mutex poisoned")
            .clear();
    }
}

/// A default ledger plus lazily-created ledgers keyed by execution session.
/// Executors use this so a shared executor never lets one conversation's read
/// authorize another conversation's edit.
#[derive(Debug)]
pub struct SessionReadLedgers {
    default: Arc<ReadLedger>,
    sessions: Mutex<HashMap<String, Arc<ReadLedger>>>,
    mutation_locks: Arc<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>>,
}

impl Default for SessionReadLedgers {
    fn default() -> Self {
        Self::new()
    }
}

impl SessionReadLedgers {
    pub fn new() -> Self {
        let mutation_locks = Arc::new(Mutex::new(HashMap::new()));
        Self {
            default: Arc::new(ReadLedger::with_mutation_locks(mutation_locks.clone())),
            sessions: Mutex::new(HashMap::new()),
            mutation_locks,
        }
    }

    pub fn ledger_for(&self, session_id: Option<&str>) -> Arc<ReadLedger> {
        let Some(session_id) = session_id else {
            return self.default.clone();
        };
        let mut sessions = self
            .sessions
            .lock()
            .expect("session read-ledger mutex poisoned");
        sessions
            .entry(session_id.to_string())
            .or_insert_with(|| {
                Arc::new(ReadLedger::with_mutation_locks(self.mutation_locks.clone()))
            })
            .clone()
    }

    pub fn remove(&self, session_id: &str) {
        self.sessions
            .lock()
            .expect("session read-ledger mutex poisoned")
            .remove(session_id);
    }

    pub fn clear(&self) {
        self.default.clear();
        let ledgers: Vec<Arc<ReadLedger>> = self
            .sessions
            .lock()
            .expect("session read-ledger mutex poisoned")
            .values()
            .cloned()
            .collect();
        for ledger in ledgers {
            ledger.clear();
        }
    }
}

/// Prescriptive "read the file before you modify it" error the staleness guard
/// returns for an unread path.
fn read_first_error(display_path: &str, verb: &str) -> String {
    format!("you must read '{display_path}' before {verb} it — call read_file first")
}

/// Prescriptive "the file changed under you" error for a stale edit.
fn stale_error(display_path: &str) -> String {
    format!("'{display_path}' changed since you last read it — re-read it and retry")
}

fn full_read_error(display_path: &str, verb: &str) -> String {
    format!(
        "you must read the full current content of '{display_path}' before {verb} it — call read_file without offset or limit first"
    )
}

/// True when `old_text` is shaped like read_file's line-number prefix — leading
/// spaces, then one or more digits, then a tab (`^\s*\d+\t`). Pasting that prefix
/// into `old_text` is a common mistake that guarantees a no-match, so the
/// no-match error can point the model straight at it. (H1/F4-remainder review.)
fn looks_like_pasted_line_number(old_text: &str) -> bool {
    let after_spaces = old_text.trim_start_matches(' ');
    let digits = after_spaces
        .bytes()
        .take_while(|b| b.is_ascii_digit())
        .count();
    digits > 0 && after_spaces.as_bytes().get(digits) == Some(&b'\t')
}

pub fn entries() -> Vec<ToolEntry> {
    vec![
        ToolEntry::builtin(car_ir::builtins::read_file()).with_category("filesystem"),
        ToolEntry::builtin(car_ir::builtins::list_dir()).with_category("filesystem"),
        ToolEntry::builtin(car_ir::builtins::find_files()).with_category("filesystem"),
        ToolEntry::builtin(car_ir::builtins::grep_files()).with_category("filesystem"),
        ToolEntry::builtin(car_ir::builtins::calculate()).with_category("utility"),
        ToolEntry::builtin(car_ir::builtins::write_file())
            .with_permission(ToolPermission::AskUser)
            .with_side_effects(true)
            .with_category("filesystem"),
        ToolEntry::builtin(car_ir::builtins::edit_file())
            .with_permission(ToolPermission::AskUser)
            .with_side_effects(true)
            .with_category("filesystem"),
    ]
}

/// Execute a built-in commodity tool against the runtime's bound `substrate`.
///
/// The side-effecting file tools (`read_file`/`write_file`/`edit_file`/
/// `list_dir`/`find_files`/`grep_files`) resolve and act against `substrate`,
/// so the agent acts within **one** environment. `calculate` is pure — it
/// never consults the substrate. Returns `None` for unknown tools (so the
/// caller can fall through), `Some(result)` otherwise.
///
/// This entrypoint runs with the read-before-edit / staleness guard **disabled**
/// (no session ledger). It keeps its historic signature and behavior because it
/// is published crates.io API; new callers that want the guard use
/// [`execute_with_ledger`]. In particular, its `read_file` output remains raw
/// file text for existing callers; the guarded agent path returns numbered
/// display text.
pub async fn execute(
    substrate: &Arc<dyn Substrate>,
    tool: &str,
    params: &Value,
) -> Option<Result<Value, String>> {
    execute_inner(substrate, None, tool, params).await
}

/// Like [`execute`], but threads a per-session [`ReadLedger`] so the built-in
/// file tools enforce read-before-edit and content staleness: `edit_file` (and
/// `write_file` over an existing file) require the session to have read the path
/// first, and a successful read/write/edit records the current content so the
/// next edit is licensed. Opt-in — every in-repo executor call site uses this so
/// its agent gets the guard; the plain [`execute`] stays ungated for external
/// consumers of the stable API.
pub async fn execute_with_ledger(
    substrate: &Arc<dyn Substrate>,
    ledger: &ReadLedger,
    tool: &str,
    params: &Value,
) -> Option<Result<Value, String>> {
    execute_inner(substrate, Some(ledger), tool, params).await
}

async fn execute_inner(
    substrate: &Arc<dyn Substrate>,
    ledger: Option<&ReadLedger>,
    tool: &str,
    params: &Value,
) -> Option<Result<Value, String>> {
    let result = match tool {
        "read_file" => exec_read_file(substrate, ledger, params).await,
        "write_file" => exec_write_file(substrate, ledger, params).await,
        "edit_file" => exec_edit_file(substrate, ledger, params).await,
        "list_dir" => exec_list_dir(substrate, params).await,
        "find_files" => exec_find_files(substrate, params).await,
        "grep_files" => exec_grep_files(substrate, params).await,
        "calculate" => exec_calculate(params),
        _ => return None,
    };
    Some(result)
}

async fn exec_read_file(
    substrate: &Arc<dyn Substrate>,
    ledger: Option<&ReadLedger>,
    params: &Value,
) -> Result<Value, String> {
    let path = params
        .get("path")
        .and_then(|v| v.as_str())
        .ok_or("missing 'path' parameter")?;
    let offset = params.get("offset").and_then(|v| v.as_u64()).unwrap_or(0) as usize;
    let limit = params
        .get("limit")
        .and_then(|v| v.as_u64())
        .map(|v| v as usize);

    let content = substrate.read_text(path).await?;
    let size_bytes = content.len();
    let total_lines = content.lines().count();

    // Number each returned line `cat -n` style so the model can cite exact line
    // numbers (matching grep_files' `line`). Numbering is 1-based and starts at
    // `offset + 1` when a slice is requested. The prefixes are display-only —
    // the tool descriptions warn the model to strip them before reusing text.
    //
    // Split on '\n' ONLY — never `str::lines()`, which strips a trailing `\r`.
    // On a CRLF file that would render an LF-only view, so any multi-line
    // `old_text` the model builds from read output could never match the
    // on-disk bytes and every multi-line edit would fail as "not found".
    // Keeping `\r` in the displayed line (like real `cat -n`) means text
    // copied across lines round-trips byte-exact. A single trailing empty
    // segment (file ending in '\n') is dropped, matching `cat -n`.
    let mut lines: Vec<&str> = content.split('\n').collect();
    if lines.last() == Some(&"") {
        lines.pop();
    }
    let start = offset.min(lines.len());
    let end = limit
        .map(|line_count| (start + line_count).min(lines.len()))
        .unwrap_or(lines.len());
    let full_read = start == 0 && end == lines.len();

    // Record a hash of the full current file for staleness detection, but keep
    // whether the agent actually saw every line. A slice can license a narrow,
    // unique edit; it cannot license a whole-file overwrite, append, or
    // replace-all that would change unseen content.
    if let Some(ledger) = ledger {
        ledger.record(path, &content, full_read);
    }

    let returned = if ledger.is_some() {
        lines[start..end]
            .iter()
            .enumerate()
            .map(|(i, line)| format!("{:>6}\t{}", start + i + 1, line))
            .collect::<Vec<_>>()
            .join("\n")
    } else if offset > 0 || limit.is_some() {
        lines[start..end].join("\n")
    } else {
        content.clone()
    };

    Ok(json!({
        "path": substrate.display_path(path),
        "content": returned,
        "size_bytes": size_bytes,
        "total_lines": total_lines,
    }))
}

async fn exec_write_file(
    substrate: &Arc<dyn Substrate>,
    ledger: Option<&ReadLedger>,
    params: &Value,
) -> Result<Value, String> {
    let path = params
        .get("path")
        .and_then(|v| v.as_str())
        .ok_or("missing 'path' parameter")?;
    let content = params
        .get("content")
        .and_then(|v| v.as_str())
        .ok_or("missing 'content' parameter")?;
    let append = params
        .get("append")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);

    let _mutation_guard = match ledger {
        Some(ledger) => Some(ledger.mutation_lock(path).lock_owned().await),
        None => None,
    };

    let existing = if ledger.is_some() {
        match substrate.read_text(path).await {
            Ok(content) => Some(content),
            Err(read_error) => match substrate.path_state(path).await {
                crate::substrate::PathState::Missing => None,
                crate::substrate::PathState::Exists => {
                    return Err(format!(
                        "cannot modify existing file '{}' because it cannot be read as UTF-8: {read_error}",
                        substrate.display_path(path)
                    ));
                }
                crate::substrate::PathState::Unknown(reason) => {
                    return Err(format!(
                        "cannot determine whether '{}' is safe to create: {reason}",
                        substrate.display_path(path)
                    ));
                }
            },
        }
    } else {
        None
    };

    let combined = if append {
        // Compose append on top of the substrate's read/write primitives so
        // behavior is environment-agnostic. A missing file starts empty,
        // matching the historic OpenOptions(create=true, append=true).
        let existed = existing.is_some();
        let existing = match existing {
            Some(existing) => existing,
            None if ledger.is_some() => String::new(),
            None => substrate.read_text(path).await.unwrap_or_default(),
        };
        // Read-before-edit + staleness guard: an append that lands on an
        // existing file the session never read is refused, same as a plain
        // overwrite — and an append onto content that changed since the last
        // read is refused as stale (the new bytes would land after content the
        // session has never seen). A missing file (empty existing) is a
        // creation and stays ungated.
        if let Some(ledger) = ledger.filter(|_| existed) {
            match ledger.check(path, &existing) {
                ReadState::Unread => {
                    return Err(read_first_error(
                        &substrate.display_path(path),
                        "overwriting",
                    ));
                }
                ReadState::Stale => {
                    return Err(stale_error(&substrate.display_path(path)));
                }
                ReadState::FreshPartial => {
                    return Err(full_read_error(
                        &substrate.display_path(path),
                        "appending to",
                    ));
                }
                ReadState::FreshFull => {}
            }
        }
        let mut combined = existing;
        combined.push_str(content);
        substrate.write_text(path, &combined).await?;
        combined
    } else {
        // Read-before-edit + staleness guard: overwriting a file that already
        // exists but was never read this session is refused (a blind clobber),
        // and overwriting one that CHANGED since the last read is refused as
        // stale — the session would silently destroy content it has never
        // observed (e.g. a change made by its own shell command or an external
        // process). Re-reading shows the current bytes and re-licenses the
        // write. Creating a NEW file is always allowed.
        if let Some(ledger) = ledger {
            if let Some(existing) = existing {
                match ledger.check(path, &existing) {
                    ReadState::Unread => {
                        return Err(read_first_error(
                            &substrate.display_path(path),
                            "overwriting",
                        ));
                    }
                    ReadState::Stale => {
                        return Err(stale_error(&substrate.display_path(path)));
                    }
                    ReadState::FreshPartial => {
                        return Err(full_read_error(
                            &substrate.display_path(path),
                            "overwriting",
                        ));
                    }
                    ReadState::FreshFull => {}
                }
            }
        }
        substrate.write_text(path, content).await?;
        content.to_string()
    };

    // Self-record the new content so a subsequent edit_file is licensed and the
    // session's snapshot of this path stays current.
    if let Some(ledger) = ledger {
        ledger.record(path, &combined, true);
    }

    Ok(json!({
        "path": substrate.display_path(path),
        "bytes_written": content.len(),
        "append": append,
    }))
}

async fn exec_edit_file(
    substrate: &Arc<dyn Substrate>,
    ledger: Option<&ReadLedger>,
    params: &Value,
) -> Result<Value, String> {
    let path = params
        .get("path")
        .and_then(|v| v.as_str())
        .ok_or("missing 'path' parameter")?;
    let old_text = params
        .get("old_text")
        .and_then(|v| v.as_str())
        .ok_or("missing 'old_text' parameter")?;
    let new_text = params
        .get("new_text")
        .and_then(|v| v.as_str())
        .ok_or("missing 'new_text' parameter")?;
    let replace_all = params
        .get("replace_all")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);

    let _mutation_guard = match ledger {
        Some(ledger) => Some(ledger.mutation_lock(path).lock_owned().await),
        None => None,
    };

    let content = substrate.read_text(path).await?;

    // Read-before-edit / staleness guard: the session must have read this exact
    // path, and its content must still match what was read (a write self-records,
    // so a write→edit chain is fine). (H1/F4-remainder, audit 2026-07-06.)
    let full_read = if let Some(ledger) = ledger {
        match ledger.check(path, &content) {
            ReadState::Unread => {
                return Err(read_first_error(&substrate.display_path(path), "editing"));
            }
            ReadState::Stale => {
                return Err(stale_error(&substrate.display_path(path)));
            }
            ReadState::FreshPartial if replace_all => {
                return Err(full_read_error(
                    &substrate.display_path(path),
                    "replacing every occurrence in",
                ));
            }
            ReadState::FreshPartial => false,
            ReadState::FreshFull => true,
        }
    } else {
        false
    };

    // An empty old_text is never a real edit request: `str::matches("")`
    // yields char_count+1 hits, and with replace_all that would interleave
    // new_text at every char boundary — silent whole-file corruption reported
    // as success. Reject up front. (H1/F4-remainder review, audit 2026-07-06.)
    if old_text.is_empty() {
        return Err(
            "old_text must be non-empty — pass the exact existing text to replace \
             (use write_file to replace a whole file)"
                .to_string(),
        );
    }

    let count = content.matches(old_text).count();
    if count == 0 {
        let mut msg = format!("old_text not found in '{}'", substrate.display_path(path));
        if looks_like_pasted_line_number(old_text) {
            msg.push_str(
                " — old_text looks like it includes read_file's line-number prefixes; \
                 strip them and retry",
            );
        }
        return Err(msg);
    }
    let new_content = if replace_all {
        content.replace(old_text, new_text)
    } else {
        if count > 1 {
            return Err(format!(
                "old_text found {count} times in '{}' and must match uniquely — \
                 pass `replace_all: true` to replace every occurrence, or add \
                 surrounding context to old_text so it matches one place",
                substrate.display_path(path)
            ));
        }
        content.replacen(old_text, new_text, 1)
    };
    substrate.write_text(path, &new_content).await?;

    // Self-record the post-edit content so the session's snapshot stays current
    // and a follow-up edit doesn't spuriously read as stale.
    if let Some(ledger) = ledger {
        ledger.record(path, &new_content, full_read);
    }

    Ok(json!({
        "edited": substrate.display_path(path),
        "diff_summary": format!(
            "replaced {} lines with {} lines",
            old_text.lines().count(),
            new_text.lines().count()
        ),
        "replacements": count,
    }))
}

async fn exec_list_dir(substrate: &Arc<dyn Substrate>, params: &Value) -> Result<Value, String> {
    let path = params.get("path").and_then(|v| v.as_str()).unwrap_or(".");

    if !substrate.is_local() {
        return list_dir_via_command(substrate, path).await;
    }

    let full_path = local_resolve(path)?;
    let mut entries = Vec::new();

    let read_dir = std::fs::read_dir(&full_path)
        .map_err(|e| format!("failed to read dir '{}': {e}", full_path.display()))?;
    for entry in read_dir {
        let entry = entry.map_err(|e| format!("failed to read dir entry: {e}"))?;
        let file_name = entry.file_name().to_string_lossy().to_string();
        if should_skip_name(&file_name) {
            continue;
        }
        let metadata = entry
            .metadata()
            .map_err(|e| format!("failed to read metadata for '{}': {e}", file_name))?;
        entries.push(json!({
            "name": file_name,
            "path": entry.path().display().to_string(),
            "is_dir": metadata.is_dir(),
            "size_bytes": if metadata.is_file() { Some(metadata.len()) } else { None::<u64> },
        }));
    }

    Ok(json!({
        "path": full_path.display().to_string(),
        "entries": entries,
    }))
}

async fn exec_find_files(substrate: &Arc<dyn Substrate>, params: &Value) -> Result<Value, String> {
    let pattern = params
        .get("pattern")
        .and_then(|v| v.as_str())
        .ok_or("missing 'pattern' parameter")?;
    let root = params.get("path").and_then(|v| v.as_str()).unwrap_or(".");
    let max_results = params
        .get("max_results")
        .and_then(|v| v.as_u64())
        .unwrap_or(1000) as usize;

    if !substrate.is_local() {
        return find_files_via_command(substrate, pattern, root, max_results).await;
    }

    let root_path = local_resolve(root)?;
    let matcher = glob_to_regex(pattern)?;
    // A pattern with a path separator is matched against each file's path
    // relative to the search root (so `src/**/*.rs` scopes to a subtree); a
    // bare pattern is matched against the basename (so `*.rs` finds every `.rs`
    // at any depth). Shared with the non-local path via `glob_haystack`. (F4.)
    let pattern_has_sep = pattern.contains('/');
    let root_str = root_path.to_string_lossy().to_string();
    let mut files = Vec::new();

    walk_files(&root_path, &mut |path| {
        if files.len() >= max_results {
            return;
        }
        if let Some(full) = path.to_str() {
            if matcher.is_match(&glob_haystack(pattern_has_sep, full, &root_str)) {
                files.push(path.display().to_string());
            }
        }
    })?;

    Ok(json!({
        "files": files,
        "count": files.len(),
        "truncated": files.len() >= max_results,
    }))
}

async fn exec_grep_files(substrate: &Arc<dyn Substrate>, params: &Value) -> Result<Value, String> {
    let pattern = params
        .get("pattern")
        .and_then(|v| v.as_str())
        .ok_or("missing 'pattern' parameter")?;
    let root = params.get("path").and_then(|v| v.as_str()).unwrap_or(".");
    let max_results = params
        .get("max_results")
        .and_then(|v| v.as_u64())
        .unwrap_or(50) as usize;

    if !substrate.is_local() {
        return grep_files_via_command(substrate, pattern, root, max_results).await;
    }

    let root_path = local_resolve(root)?;
    let regex = Regex::new(pattern).map_err(|e| format!("invalid regex pattern: {e}"))?;
    let mut matches = Vec::new();

    walk_files(&root_path, &mut |path| {
        if matches.len() >= max_results || !is_text_file(path) {
            return;
        }
        let Ok(content) = std::fs::read_to_string(path) else {
            return;
        };
        if content.len() > MAX_FILE_BYTES {
            return;
        }
        for (idx, line) in content.lines().enumerate() {
            if regex.is_match(line) {
                matches.push(json!({
                    "path": path.display().to_string(),
                    "line": idx + 1,
                    "text": line,
                }));
                if matches.len() >= max_results {
                    break;
                }
            }
        }
    })?;

    Ok(json!({
        "matches": matches,
        "count": matches.len(),
        "truncated": matches.len() >= max_results,
    }))
}

fn exec_calculate(params: &Value) -> Result<Value, String> {
    let expression = params
        .get("expression")
        .and_then(|v| v.as_str())
        .ok_or("missing 'expression' parameter")?;
    // fasteval ships `sin/cos/abs/log/min/max/pi()/e()` and `^` (exponentiation)
    // as built-ins, but not `sqrt`, `ln`, or the bare `pi`/`e` constants.
    // fasteval consults this namespace only for names it doesn't resolve
    // itself, so the shim fills those gaps without shadowing any built-in —
    // making the `calculate` tool's supported surface explicit here rather
    // than inherited from the dependency.
    let mut ns = |name: &str, args: Vec<f64>| -> Option<f64> {
        match (name, args.as_slice()) {
            ("sqrt", [x]) => Some(x.sqrt()),
            ("ln", [x]) => Some(x.ln()),
            ("pi", []) => Some(std::f64::consts::PI),
            ("e", []) => Some(std::f64::consts::E),
            _ => None,
        }
    };
    let result = fasteval::ez_eval(expression, &mut ns)
        .map_err(|e| format!("failed to evaluate expression: {e}"))?;
    Ok(json!({ "result": result }))
}

// ─── Local-path resolution (host CWD), used only on the local fast path ───
//
// Mirrors `LocalSubstrate::resolve_path` exactly: absolute paths pass through,
// relative paths join the host process current_dir(). The directory-walking
// convenience tools (list/find/grep) use it directly when the bound substrate
// is the host; non-local substrates compose on `run_command` instead.
fn local_resolve(path: &str) -> Result<PathBuf, String> {
    crate::substrate::LocalSubstrate::resolve_path(path)
}

fn should_skip_name(name: &str) -> bool {
    name.starts_with('.') || matches!(name, "node_modules" | "__pycache__" | "target")
}

fn is_text_file(path: &Path) -> bool {
    matches!(
        path.extension().and_then(|v| v.to_str()),
        Some(
            "c" | "cc"
                | "cpp"
                | "cs"
                | "css"
                | "go"
                | "h"
                | "html"
                | "ini"
                | "java"
                | "js"
                | "json"
                | "jsx"
                | "kt"
                | "md"
                | "py"
                | "rb"
                | "rs"
                | "sh"
                | "sql"
                | "toml"
                | "ts"
                | "tsx"
                | "txt"
                | "xml"
                | "yaml"
                | "yml"
        )
    )
}

fn walk_files(root: &Path, visit: &mut dyn FnMut(&Path)) -> Result<(), String> {
    if root.is_file() {
        visit(root);
        return Ok(());
    }

    let read_dir = std::fs::read_dir(root)
        .map_err(|e| format!("failed to read dir '{}': {e}", root.display()))?;
    for entry in read_dir {
        let entry = entry.map_err(|e| format!("failed to read dir entry: {e}"))?;
        let path = entry.path();
        let file_name = entry.file_name().to_string_lossy().to_string();
        if should_skip_name(&file_name) {
            continue;
        }
        let metadata = entry
            .metadata()
            .map_err(|e| format!("failed to read metadata for '{}': {e}", path.display()))?;
        if metadata.is_dir() {
            walk_files(&path, visit)?;
        } else if metadata.is_file() {
            visit(&path);
        }
    }
    Ok(())
}

/// Translate a glob to an anchored regex with path-segment awareness so
/// recursive path patterns work, not just basenames (F4, audit 2026-07-06):
/// - `*`   matches within one path segment (`[^/]*`)
/// - `**/` matches any number of leading segments, including none (`(?:.*/)?`)
/// - `**`  matches across segments (`.*`)
/// - `?`   matches a single non-separator char (`[^/]`)
/// A pattern with no `/` is matched against the basename by the caller, so
/// `*.rs` still finds `lib.rs` at any depth; a pattern with `/` (e.g.
/// `src/**/*.rs`) is matched against the path relative to the search root.
fn glob_to_regex(pattern: &str) -> Result<Regex, String> {
    let chars: Vec<char> = pattern.chars().collect();
    let mut re = String::from("^");
    let mut i = 0;
    while i < chars.len() {
        match chars[i] {
            '*' => {
                if i + 1 < chars.len() && chars[i + 1] == '*' {
                    i += 1; // consume the second '*'
                    if i + 1 < chars.len() && chars[i + 1] == '/' {
                        i += 1; // consume the '/': `**/` → optional leading segments
                        re.push_str("(?:.*/)?");
                    } else {
                        re.push_str(".*");
                    }
                } else {
                    re.push_str("[^/]*");
                }
            }
            '?' => re.push_str("[^/]"),
            c => re.push_str(&regex::escape(&c.to_string())),
        }
        i += 1;
    }
    re.push('$');
    Regex::new(&re).map_err(|e| format!("invalid glob pattern: {e}"))
}

/// Pick the string a candidate file is matched against for a glob search: the
/// path relative to the search `root` when the pattern contains a separator
/// (so `src/**/*.rs` scopes to a subtree), else the basename (so `*.rs` finds
/// every match at any depth). Shared by the local directory walk AND the
/// non-local `find` path so both substrates honor the same path-glob semantics
/// the tool schema advertises — otherwise the sandbox/remote path silently
/// returns nothing for a `/`-bearing pattern. (F4, audit 2026-07-06.)
fn glob_haystack(pattern_has_sep: bool, full: &str, root: &str) -> String {
    if pattern_has_sep {
        let full = full.replace('\\', "/");
        let root = root.replace('\\', "/");
        full.strip_prefix(&root)
            .unwrap_or(&full)
            .trim_start_matches('/')
            .to_string()
    } else {
        full.rsplit(['/', '\\']).next().unwrap_or(full).to_string()
    }
}

// ─── Non-local composition on run_command ─────────────────────────────────
//
// For non-host substrates (e.g. a VM bridge) the directory-walking convenience
// tools have no host fs to walk, so they compose on the substrate's
// `run_command`, mirroring the bridge's "no ls/find/grep — reduce to a shell
// command" design. These paths are NOT exercised by existing consumers (which
// all default to LocalSubstrate), so they introduce no behavior change there.

fn shell_quote(s: &str) -> String {
    // POSIX single-quote escaping: ' -> '\''
    format!("'{}'", s.replace('\'', "'\\''"))
}

async fn list_dir_via_command(substrate: &Arc<dyn Substrate>, path: &str) -> Result<Value, String> {
    let cmd = format!("ls -1Ap {}", shell_quote(path));
    let out = substrate.run_command(&cmd, Some(30.0)).await?;
    let entries: Vec<Value> = out
        .stdout
        .lines()
        .filter(|l| !l.is_empty())
        .filter(|name| {
            let bare = name.trim_end_matches('/');
            !should_skip_name(bare)
        })
        .map(|name| {
            let is_dir = name.ends_with('/');
            let bare = name.trim_end_matches('/');
            json!({
                "name": bare,
                "path": format!("{}/{}", path.trim_end_matches('/'), bare),
                "is_dir": is_dir,
                "size_bytes": Value::Null,
            })
        })
        .collect();
    Ok(json!({ "path": path, "entries": entries }))
}

async fn find_files_via_command(
    substrate: &Arc<dyn Substrate>,
    pattern: &str,
    root: &str,
    max_results: usize,
) -> Result<Value, String> {
    // List every file, then apply the SAME matcher the local walk uses, so a
    // path glob (`src/**/*.rs`) works here too. `find -name <pattern>` matched
    // the basename only and never matched a `/`-bearing pattern — the tool
    // schema advertises path globs on every substrate, so the non-local path
    // must honor them or silently return nothing. (F4, audit 2026-07-06.)
    let cmd = format!("find {} -type f", shell_quote(root));
    let out = substrate.run_command(&cmd, Some(30.0)).await?;
    let matcher = glob_to_regex(pattern)?;
    let pattern_has_sep = pattern.contains('/');
    let mut files: Vec<String> = Vec::new();
    let mut truncated = false;
    for line in out.stdout.lines() {
        if line.is_empty() {
            continue;
        }
        let name = line.rsplit(['/', '\\']).next().unwrap_or(line);
        if should_skip_name(name) {
            continue;
        }
        if !matcher.is_match(&glob_haystack(pattern_has_sep, line, root)) {
            continue;
        }
        if files.len() >= max_results {
            truncated = true;
            break;
        }
        files.push(line.to_string());
    }
    Ok(json!({
        "files": files,
        "count": files.len(),
        "truncated": truncated,
    }))
}

async fn grep_files_via_command(
    substrate: &Arc<dyn Substrate>,
    pattern: &str,
    root: &str,
    max_results: usize,
) -> Result<Value, String> {
    let cmd = format!("grep -rnE {} {}", shell_quote(pattern), shell_quote(root));
    let out = substrate.run_command(&cmd, Some(30.0)).await?;
    let mut matches = Vec::new();
    for line in out.stdout.lines() {
        if matches.len() >= max_results {
            break;
        }
        // grep -rn format: path:line:text
        let mut parts = line.splitn(3, ':');
        let (Some(p), Some(ln), Some(text)) = (parts.next(), parts.next(), parts.next()) else {
            continue;
        };
        let Ok(line_no) = ln.parse::<usize>() else {
            continue;
        };
        matches.push(json!({ "path": p, "line": line_no, "text": text }));
    }
    let truncated = matches.len() >= max_results;
    Ok(json!({
        "matches": matches,
        "count": matches.len(),
        "truncated": truncated,
    }))
}

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

    #[test]
    fn glob_patterns_match_file_names() {
        let regex = glob_to_regex("*.rs").unwrap();
        assert!(regex.is_match("lib.rs"));
        assert!(!regex.is_match("lib.ts"));
    }

    /// F4 (audit 2026-07-06): the local walk and the non-local `find` path
    /// share `glob_haystack`, so a `/`-bearing pattern matches the path
    /// relative to the search root on EVERY substrate (the non-local path used
    /// to `find -name` and silently returned nothing for a path glob). This
    /// exercises the shared matching logic both branches now depend on.
    #[test]
    fn glob_haystack_supports_path_and_basename_matching() {
        // path pattern → relative-to-root (normalized to '/'); bare → basename
        assert_eq!(
            glob_haystack(true, "/root/src/inner/deep.rs", "/root"),
            "src/inner/deep.rs"
        );
        assert_eq!(
            glob_haystack(false, "/root/src/inner/deep.rs", "/root"),
            "deep.rs"
        );

        // Combined with the translator, a recursive path glob scopes to the
        // subtree and rejects the wrong extension — the behavior the non-local
        // substrate previously could not produce.
        let m = glob_to_regex("src/**/*.rs").unwrap();
        assert!(m.is_match(&glob_haystack(true, "/root/src/top.rs", "/root")));
        assert!(m.is_match(&glob_haystack(true, "/root/src/inner/deep.rs", "/root")));
        assert!(!m.is_match(&glob_haystack(true, "/root/src/inner/note.txt", "/root")));
    }

    /// F4 (audit 2026-07-06): the file search must support recursive path globs
    /// (`src/**/*.rs`), not just basename matching — otherwise the agent cannot
    /// scope a search to a subtree and resorts to guessing.
    #[tokio::test]
    async fn find_files_supports_recursive_path_globs() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = std::env::temp_dir().join(format!(
            "car-find-glob-{}",
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(dir.join("src").join("inner")).unwrap();
        std::fs::write(dir.join("src").join("top.rs"), "x").unwrap();
        std::fs::write(dir.join("src").join("inner").join("deep.rs"), "x").unwrap();
        std::fs::write(dir.join("src").join("inner").join("note.txt"), "x").unwrap();
        let root = dir.to_string_lossy().to_string();

        let r = exec_find_files(
            &substrate,
            &json!({ "path": root, "pattern": "src/**/*.rs" }),
        )
        .await
        .unwrap();
        let joined = r["files"]
            .as_array()
            .unwrap()
            .iter()
            .map(|v| v.as_str().unwrap())
            .collect::<Vec<_>>()
            .join("\n");

        assert!(
            joined.contains("deep.rs"),
            "recursive glob missed nested file:\n{joined}"
        );
        assert!(
            joined.contains("top.rs"),
            "recursive glob missed top-level file:\n{joined}"
        );
        assert!(
            !joined.contains("note.txt"),
            "glob matched the wrong extension:\n{joined}"
        );

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// F4 (audit 2026-07-06): the NON-LOCAL substrate path (`find_files_via_command`)
    /// must honor recursive path globs too — it lists every file via `run_command`
    /// then applies the SAME matcher as the local walk. Previously untested; a mock
    /// substrate (`is_local()` defaults to false) with scripted `find` stdout pins
    /// it, so a regression that reverts to basename-only `-name` matching is caught.
    #[tokio::test]
    async fn find_files_non_local_substrate_applies_path_glob() {
        use crate::substrate::CommandOutput;

        struct RemoteStub {
            stdout: String,
        }
        #[async_trait::async_trait]
        impl Substrate for RemoteStub {
            fn name(&self) -> &str {
                "test-remote"
            }
            // is_local() defaults to false -> exercises the non-local path.
            async fn run_command(
                &self,
                _cmd: &str,
                _timeout_s: Option<f64>,
            ) -> Result<CommandOutput, String> {
                Ok(CommandOutput {
                    stdout: self.stdout.clone(),
                    stderr: String::new(),
                    exit_code: 0,
                })
            }
            async fn read_text(&self, _path: &str) -> Result<String, String> {
                Err("unused".into())
            }
            async fn write_text(&self, _path: &str, _content: &str) -> Result<(), String> {
                Err("unused".into())
            }
            async fn read_bytes(
                &self,
                _path: &str,
                _offset: Option<u64>,
                _len: Option<u64>,
            ) -> Result<Vec<u8>, String> {
                Err("unused".into())
            }
            async fn write_bytes(&self, _path: &str, _bytes: &[u8]) -> Result<(), String> {
                Err("unused".into())
            }
        }

        // Scripted `find <root> -type f` output — matching + non-matching paths.
        let substrate: Arc<dyn Substrate> = Arc::new(RemoteStub {
            stdout: [
                "/root/src/top.rs",
                "/root/src/inner/deep.rs",
                "/root/src/inner/note.txt",
                "/root/README.md",
            ]
            .join("\n"),
        });

        let r = exec_find_files(
            &substrate,
            &json!({ "path": "/root", "pattern": "src/**/*.rs" }),
        )
        .await
        .unwrap();
        let files: Vec<&str> = r["files"]
            .as_array()
            .unwrap()
            .iter()
            .map(|v| v.as_str().unwrap())
            .collect();

        // The recursive path glob scopes to src/ and rejects the wrong extension —
        // the exact behavior the non-local path silently lacked before F4.
        assert_eq!(files, vec!["/root/src/top.rs", "/root/src/inner/deep.rs"]);
        assert_eq!(r["count"], 2);
    }

    /// Unique nanos-named temp dir for a test, created and returned.
    fn fresh_dir(tag: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!(
            "car-agent-basics-{tag}-{}",
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        std::fs::create_dir_all(&dir).unwrap();
        dir
    }

    #[tokio::test]
    async fn read_write_roundtrip_against_local_substrate() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = fresh_dir("roundtrip");
        let path = dir.join("note.txt").to_string_lossy().to_string();

        let w = exec_write_file(&substrate, None, &json!({ "path": path, "content": "abc" }))
            .await
            .unwrap();
        assert_eq!(w["bytes_written"], 3);

        // The published, ungated execute path retains its historic raw content.
        let r = exec_read_file(&substrate, None, &json!({ "path": path }))
            .await
            .unwrap();
        assert_eq!(r["content"], "abc");
        assert_eq!(r["size_bytes"], 3);
        assert_eq!(r["total_lines"], 1);

        // append composes correctly through the substrate
        exec_write_file(
            &substrate,
            None,
            &json!({ "path": path, "content": "def", "append": true }),
        )
        .await
        .unwrap();
        let r2 = exec_read_file(&substrate, None, &json!({ "path": path }))
            .await
            .unwrap();
        assert_eq!(r2["content"], "abcdef");

        // edit unique-match
        let e = exec_edit_file(
            &substrate,
            None,
            &json!({ "path": path, "old_text": "abc", "new_text": "XYZ" }),
        )
        .await
        .unwrap();
        assert!(e["edited"].is_string());
        assert_eq!(e["replacements"], 1);
        let r3 = exec_read_file(&substrate, None, &json!({ "path": path }))
            .await
            .unwrap();
        assert_eq!(r3["content"], "XYZdef");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (a) read output is line-numbered `cat -n` style, 1-based, and when an
    /// `offset` is given the numbering starts at `offset + 1` while
    /// `size_bytes`/`total_lines` still describe the FULL file.
    #[tokio::test]
    async fn read_file_output_is_line_numbered() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("linenum");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        exec_write_file(
            &substrate,
            None,
            &json!({ "path": path, "content": "alpha\nbeta\ngamma" }),
        )
        .await
        .unwrap();

        let r = execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        assert_eq!(r["content"], "     1\talpha\n     2\tbeta\n     3\tgamma");
        assert_eq!(r["total_lines"], 3);

        // Offset slice: numbering continues from offset + 1, full-file metadata.
        let r2 = execute_with_ledger(
            &substrate,
            &ledger,
            "read_file",
            &json!({ "path": path, "offset": 1, "limit": 1 }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(r2["content"], "     2\tbeta");
        assert_eq!(r2["total_lines"], 3);

        std::fs::remove_dir_all(&dir).ok();
    }

    #[tokio::test]
    async fn plain_execute_preserves_legacy_raw_read_output() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = fresh_dir("rawread");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(&path, "alpha\nbeta\n").unwrap();

        let result = execute(&substrate, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        assert_eq!(result["content"], "alpha\nbeta\n");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (b) `edit_file` refuses a path the session never read, then succeeds once
    /// `read_file` has run — the read-before-edit guard.
    #[tokio::test]
    async fn edit_requires_prior_read() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("editread");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        // Create on disk directly — the ledger has no record of this path.
        std::fs::write(dir.join("f.txt"), "hello world").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "hello", "new_text": "hi" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("before editing it"), "{err}");
        assert!(err.contains("read_file"), "{err}");

        // Reading licenses the edit.
        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "hello", "new_text": "hi" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 1);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (b) `edit_file` refuses a stale file — one that changed on disk after the
    /// session read it — until it is re-read.
    #[tokio::test]
    async fn edit_detects_stale_file() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("stale");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "version one").unwrap();

        // Read records the current content; then the file changes underneath.
        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        std::fs::write(dir.join("f.txt"), "version two changed").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "version", "new_text": "v" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("changed since you last read it"), "{err}");

        // Re-reading clears the staleness.
        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "version", "new_text": "v" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert!(ok["edited"].is_string());

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (review) CRLF files keep their `\r` in the numbered display so multi-line
    /// `old_text` copied from read output matches the on-disk bytes exactly.
    /// `str::lines()` would strip the `\r` and make every multi-line edit on a
    /// CRLF file unmatchable.
    #[tokio::test]
    async fn read_file_preserves_crlf_line_endings() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("crlf");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "line one\r\nline two\r\n").unwrap();

        let out = execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let shown = out["content"].as_str().unwrap();
        assert_eq!(
            shown, "     1\tline one\r\n     2\tline two\r",
            "\\r must survive into the numbered display"
        );

        // The round-trip proof: multi-line old_text reconstructed from the
        // display (prefixes stripped, \r kept) matches the file and edits it.
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "line one\r\nline two", "new_text": "merged" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 1);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (review) An empty `old_text` is rejected up front — `matches("")` is
    /// char_count+1, so with `replace_all` it would interleave `new_text` at
    /// every char boundary (silent whole-file corruption reported as success).
    #[tokio::test]
    async fn edit_rejects_empty_old_text() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = fresh_dir("emptyold");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        exec_write_file(&substrate, None, &json!({ "path": path, "content": "abc" }))
            .await
            .unwrap();

        for replace_all in [false, true] {
            let err = exec_edit_file(
                &substrate,
                None,
                &json!({
                    "path": path,
                    "old_text": "",
                    "new_text": "X",
                    "replace_all": replace_all
                }),
            )
            .await
            .unwrap_err();
            assert!(err.contains("old_text must be non-empty"), "{err}");
        }
        // The file is untouched.
        assert_eq!(std::fs::read_to_string(dir.join("f.txt")).unwrap(), "abc");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (review) `write_file` over an existing file refuses when the file changed
    /// since the session's last read — a blind overwrite would destroy content
    /// the session never observed. Re-reading re-licenses the write. This is the
    /// staleness half the docs promise alongside the read-first gate.
    #[tokio::test]
    async fn write_existing_rejects_stale_after_external_change() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("stalewrite");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "original").unwrap();

        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        // The file changes underneath (external process / shell command).
        std::fs::write(dir.join("f.txt"), "changed underneath").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "clobber" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("changed since you last read it"), "{err}");

        // Append over stale content is refused the same way.
        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": " + more", "append": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("changed since you last read it"), "{err}");

        // Re-reading shows the current bytes and re-licenses the write.
        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "rewritten" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(
            std::fs::read_to_string(dir.join("f.txt")).unwrap(),
            "rewritten"
        );

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (c) `replace_all: true` replaces every occurrence and reports the count;
    /// the default path still refuses a non-unique match and points at the flag.
    #[tokio::test]
    async fn replace_all_replaces_every_occurrence() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = fresh_dir("replaceall");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        exec_write_file(
            &substrate,
            None,
            &json!({ "path": path, "content": "a x a x a" }),
        )
        .await
        .unwrap();

        // Default (unique) edit refuses the 3-way match and names the remedy.
        let err = exec_edit_file(
            &substrate,
            None,
            &json!({ "path": path, "old_text": "a", "new_text": "b" }),
        )
        .await
        .unwrap_err();
        assert!(err.contains("replace_all"), "{err}");

        // replace_all replaces every occurrence.
        let ok = exec_edit_file(
            &substrate,
            None,
            &json!({ "path": path, "old_text": "a", "new_text": "b", "replace_all": true }),
        )
        .await
        .unwrap();
        assert_eq!(ok["replacements"], 3);
        let r = exec_read_file(&substrate, None, &json!({ "path": path }))
            .await
            .unwrap();
        assert_eq!(r["content"], "b x b x b");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (d) Creating a brand-new file needs no prior read.
    #[tokio::test]
    async fn write_new_file_allowed() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("writenew");
        let path = dir.join("new.txt").to_string_lossy().to_string();

        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "fresh" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["bytes_written"], 5);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (d) Overwriting an EXISTING file the session never read is refused.
    #[tokio::test]
    async fn write_existing_requires_prior_read() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("writeexisting");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "existing content").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "clobber" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("before overwriting it"), "{err}");
        assert!(err.contains("read_file"), "{err}");

        // Reading licenses the overwrite.
        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "clobber" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["bytes_written"], 7);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (d) A successful write self-records the new content, so a follow-up
    /// `edit_file` on the same path is licensed WITHOUT an intervening read —
    /// the "session knows the current content" contract the loops rely on.
    #[tokio::test]
    async fn write_self_records_enabling_edit() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("writeedits");
        let path = dir.join("f.txt").to_string_lossy().to_string();

        execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "one two three" }),
        )
        .await
        .unwrap()
        .unwrap();
        // No read_file in between — the write recorded the content.
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "two", "new_text": "TWO" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 1);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#2) A successful edit self-records the new content, so a SECOND edit with
    /// no intervening read is licensed. Deleting the edit self-record makes the
    /// ledger stale here and fails this test.
    #[tokio::test]
    async fn edit_self_records_enabling_second_edit_without_reread() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("editselfrec");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "one two three").unwrap();

        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "one", "new_text": "1" }),
        )
        .await
        .unwrap()
        .unwrap();

        // No read between the two edits — the first edit recorded the new content.
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "two", "new_text": "2" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 1);
        assert_eq!(
            std::fs::read_to_string(dir.join("f.txt")).unwrap(),
            "1 2 three"
        );

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#3) A sliced read (offset/limit) records the FULL file's hash, not the
    /// returned slice — so editing a line OUTSIDE the slice is licensed AND
    /// Fresh. If the slice were hashed, `check()` would return Stale.
    #[tokio::test]
    async fn sliced_read_hashes_full_file_licensing_edit() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("slicedread");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "l1\nl2\nl3\nl4").unwrap();

        let r = execute_with_ledger(
            &substrate,
            &ledger,
            "read_file",
            &json!({ "path": path, "offset": 1, "limit": 1 }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(r["content"], "     2\tl2"); // only the slice is returned

        // l4 is outside the returned slice; the edit is still licensed + Fresh.
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "l4", "new_text": "L4" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 1);

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#4) Appending onto an EXISTING file the session never read is refused
    /// (same read-first guard as an overwrite); reading it licenses the append.
    #[tokio::test]
    async fn append_to_existing_unread_requires_prior_read() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("appendunread");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "existing content").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": " more", "append": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("before overwriting it"), "{err}");

        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": " more", "append": true }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["append"], true);
        assert_eq!(
            std::fs::read_to_string(dir.join("f.txt")).unwrap(),
            "existing content more"
        );

        std::fs::remove_dir_all(&dir).ok();
    }

    #[tokio::test]
    async fn append_to_existing_empty_file_requires_prior_read() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("appendempty");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "new", "append": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("before overwriting it"), "{err}");
        assert!(std::fs::read_to_string(dir.join("f.txt"))
            .unwrap()
            .is_empty());

        std::fs::remove_dir_all(&dir).ok();
    }

    #[tokio::test]
    async fn partial_read_cannot_authorize_whole_file_mutation() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("partialread");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "first\nsecond\nthird").unwrap();

        execute_with_ledger(
            &substrate,
            &ledger,
            "read_file",
            &json!({ "path": path, "offset": 0, "limit": 1 }),
        )
        .await
        .unwrap()
        .unwrap();

        let overwrite = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "replacement" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(overwrite.contains("full current content"), "{overwrite}");

        let replace_all = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "i", "new_text": "I", "replace_all": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(
            replace_all.contains("full current content"),
            "{replace_all}"
        );

        // A normal unique edit remains usable after the focused read.
        let edit = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "first", "new_text": "FIRST" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(edit["replacements"], 1);

        std::fs::remove_dir_all(&dir).ok();
    }

    #[tokio::test]
    async fn guarded_write_refuses_existing_non_utf8_file() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("nonutf8write");
        let path = dir.join("f.bin").to_string_lossy().to_string();
        std::fs::write(dir.join("f.bin"), [0xff, 0x00, 0xfe]).unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "text" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("cannot modify existing file"), "{err}");
        assert_eq!(
            std::fs::read(dir.join("f.bin")).unwrap(),
            [0xff, 0x00, 0xfe]
        );

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#4) Appending onto a STALE record (file changed on disk after the read)
    /// is refused with the stale error until re-read — the append arm gates
    /// staleness, not just presence.
    #[tokio::test]
    async fn append_detects_stale_after_external_change() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("appendstale");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "v1").unwrap();

        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        std::fs::write(dir.join("f.txt"), "v2 changed").unwrap();

        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": " appended", "append": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("changed since you last read it"), "{err}");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#5) The read-before-edit gate sits above BOTH edit arms: a `replace_all`
    /// edit is licensed by a read, self-records, and is refused as stale after an
    /// external change — exactly like the unique-match arm.
    #[tokio::test]
    async fn replace_all_edit_is_gated_by_the_ledger() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();
        let dir = fresh_dir("replaceallgate");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "a a a").unwrap();

        execute_with_ledger(&substrate, &ledger, "read_file", &json!({ "path": path }))
            .await
            .unwrap()
            .unwrap();
        let ok = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "a", "new_text": "b", "replace_all": true }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok["replacements"], 3);

        // Self-recorded: a second replace_all with no read succeeds.
        let ok2 = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "b", "new_text": "c", "replace_all": true }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(ok2["replacements"], 3);

        // External change → the replace_all edit is refused as stale.
        std::fs::write(dir.join("f.txt"), "c c c c").unwrap();
        let err = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "c", "new_text": "d", "replace_all": true }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(err.contains("changed since you last read it"), "{err}");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#6a) Every builtin name is HANDLED (returns `Some`), and no error it
    /// produces — including the deliberate gate errors — starts with "unknown
    /// tool". That prefix is the ONLY fall-through trigger at every call site, so
    /// this pins that a builtin can never be re-dispatched to a second ledger.
    #[tokio::test]
    async fn builtin_names_never_return_unknown_tool_prefix() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let ledger = ReadLedger::new();

        for name in [
            "read_file",
            "write_file",
            "edit_file",
            "list_dir",
            "find_files",
            "grep_files",
            "calculate",
        ] {
            let result = execute_with_ledger(&substrate, &ledger, name, &json!({})).await;
            let inner = result.unwrap_or_else(|| panic!("{name} must be handled, not None"));
            if let Err(e) = &inner {
                assert!(
                    !e.starts_with("unknown tool"),
                    "{name} error must not start with 'unknown tool': {e}"
                );
            }
        }

        // Only a genuinely unknown name is None (→ "unknown tool" at the caller).
        assert!(
            execute_with_ledger(&substrate, &ledger, "no_such_tool", &json!({}))
                .await
                .is_none()
        );

        // The deliberate gate errors also never masquerade as "unknown tool".
        let dir = fresh_dir("unknownprefix");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        std::fs::write(dir.join("f.txt"), "content").unwrap();
        let edit_err = execute_with_ledger(
            &substrate,
            &ledger,
            "edit_file",
            &json!({ "path": path, "old_text": "content", "new_text": "x" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(!edit_err.starts_with("unknown tool"), "{edit_err}");
        assert!(edit_err.contains("before editing it"), "{edit_err}");
        let write_err = execute_with_ledger(
            &substrate,
            &ledger,
            "write_file",
            &json!({ "path": path, "content": "y" }),
        )
        .await
        .unwrap()
        .unwrap_err();
        assert!(!write_err.starts_with("unknown tool"), "{write_err}");

        std::fs::remove_dir_all(&dir).ok();
    }

    /// (#7) Lexical `.` components are normalized in the ledger key, so rooted
    /// `./x` and `x` paths do not alias into a spurious Unread.
    #[test]
    fn ledger_normalizes_dot_components() {
        let ledger = ReadLedger::new();
        ledger.record("./src/x.rs", "content", true);
        assert_eq!(ledger.check("src/x.rs", "content"), ReadState::FreshFull);
        assert_eq!(ledger.check("./src/x.rs", "content"), ReadState::FreshFull);

        let ledger2 = ReadLedger::new();
        ledger2.record("src/x.rs", "content", true);
        assert_eq!(ledger2.check("./src/x.rs", "content"), ReadState::FreshFull);

        // Unrelated paths are still Unread, while adapter-rooted interior dots
        // normalize to the same ledger key.
        assert_eq!(ledger.check("other.rs", "content"), ReadState::Unread);
        let ledger3 = ReadLedger::new();
        ledger3.record("/root/a/./b", "c", true);
        assert_eq!(ledger3.check("/root/a/b", "c"), ReadState::FreshFull);
    }

    #[test]
    fn session_ledgers_share_mutation_locks_without_sharing_observations() {
        let ledgers = SessionReadLedgers::new();
        let first = ledgers.ledger_for(Some("first"));
        let second = ledgers.ledger_for(Some("second"));
        first.record("f.txt", "first view", true);

        assert_eq!(
            second.check("f.txt", "first view"),
            ReadState::Unread,
            "one session's read must not authorize another session"
        );
        assert!(Arc::ptr_eq(
            &first.mutation_lock("f.txt"),
            &second.mutation_lock("f.txt")
        ));
    }

    /// (#8) A no-match `old_text` shaped like read_file's line-number prefix gets
    /// a targeted hint; an ordinary no-match does not.
    #[tokio::test]
    async fn edit_no_match_hints_pasted_line_number() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let dir = fresh_dir("linenumhint");
        let path = dir.join("f.txt").to_string_lossy().to_string();
        exec_write_file(
            &substrate,
            None,
            &json!({ "path": path, "content": "hello world" }),
        )
        .await
        .unwrap();

        let err = exec_edit_file(
            &substrate,
            None,
            &json!({ "path": path, "old_text": "     1\thello world", "new_text": "hi" }),
        )
        .await
        .unwrap_err();
        assert!(err.contains("line-number prefixes"), "{err}");

        let plain = exec_edit_file(
            &substrate,
            None,
            &json!({ "path": path, "old_text": "absent", "new_text": "x" }),
        )
        .await
        .unwrap_err();
        assert!(!plain.contains("line-number prefixes"), "{plain}");
        assert!(plain.contains("old_text not found"), "{plain}");

        std::fs::remove_dir_all(&dir).ok();
    }

    #[tokio::test]
    async fn calculate_is_pure() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        let out = execute(
            &substrate,
            "calculate",
            &json!({ "expression": "2 + 3 * 4" }),
        )
        .await
        .unwrap()
        .unwrap();
        assert_eq!(out["result"], 14.0);
    }

    #[tokio::test]
    async fn unknown_tool_returns_none() {
        let substrate: Arc<dyn Substrate> = Arc::new(crate::substrate::LocalSubstrate::new());
        assert!(execute(&substrate, "nope", &json!({})).await.is_none());
    }

    /// Evaluate via the public `calculate` tool contract and return the
    /// `result` float, so the test exercises the same path the runtime does.
    fn calc(expr: &str) -> f64 {
        exec_calculate(&json!({ "expression": expr }))
            .unwrap_or_else(|e| panic!("calculate({expr:?}) failed: {e}"))
            .get("result")
            .and_then(|v| v.as_f64())
            .unwrap_or_else(|| panic!("calculate({expr:?}) returned no numeric result"))
    }

    /// Pins the math semantics of the `calculate` builtin independently of the
    /// backend evaluator. The load-bearing case is `^`: this tool is a
    /// calculator, so `^` MUST mean exponentiation (2^3 == 8), not the
    /// bitwise-XOR meaning it carries in C-family languages. The tool
    /// description documents this contract for the model; this test enforces
    /// it for the implementation.
    #[test]
    fn calculate_contract_semantics() {
        assert_eq!(calc("2 + 3 * 4"), 14.0, "operator precedence");
        assert_eq!(calc("(1 + 2) * 3"), 9.0, "parentheses override precedence");
        assert_eq!(calc("2^3"), 8.0, "^ is exponentiation, not XOR");
        assert_eq!(calc("2^10"), 1024.0, "^ is exponentiation");
        assert_eq!(calc("10 % 3"), 1.0, "modulo");
        assert_eq!(calc("-5 + 2"), -3.0, "unary minus");
        // Built-in functions (fasteval-native).
        assert_eq!(calc("sin(0)"), 0.0, "native function: sin");
        assert_eq!(calc("abs(-3)"), 3.0, "native function: abs");
        // Functions/constants filled by our namespace shim.
        assert_eq!(calc("sqrt(16)"), 4.0, "shim function: sqrt");
        assert!((calc("ln(e)") - 1.0).abs() < 1e-12, "shim: ln + e constant");
        assert!(
            (calc("pi") - std::f64::consts::PI).abs() < 1e-12,
            "shim: pi constant"
        );
    }

    #[test]
    fn calculate_rejects_invalid_expression() {
        assert!(exec_calculate(&json!({ "expression": "2 +" })).is_err());
        assert!(exec_calculate(&json!({})).is_err(), "missing parameter");
    }
}