@termaxjs/web-ai 0.1.1

package/dist/lib/security.js

@@ -0,0 +1,376 @@
+/**
+ * Path-safety guards for AI tool calls.
+ *
+ * Goals:
+ *  - Block reads of files that almost always contain secrets (.env*, *.pem,
+ *    id_rsa*, .aws/credentials, .ssh/, .git/, kube/azure config, etc.).
+ *  - Block writes/exec into the same set, plus directories where automated
+ *    mutation is dangerous (system dirs, Windows system dirs).
+ *
+ * This is a *defense layer*, not a sandbox. The model may still be coaxed
+ * into doing something silly within allowed paths — the user-confirmation
+ * UI for write/exec is the real safety net. These checks ensure that
+ * read tools (which auto-approve) can never silently exfiltrate obvious
+ * secrets, and that a single bad approval can't blow up the system.
+ *
+ * Defense-in-depth notes:
+ *  - Comparison surface is lowercased *only for matching*. Original path is
+ *    preserved for basename pattern checks and error messages.
+ *  - Windows drive prefix (e.g. `C:`) is stripped from the comparison form so
+ *    Unix-style root prefix checks behave consistently on both platforms.
+ *  - Protected directories match exact-equal-or-descendant, not raw
+ *    substring-with-trailing-slash. Bare names (`/Users/me/.ssh`) and
+ *    case-variants (`/Users/me/.SSH/config` on macOS/Windows case-insensitive
+ *    filesystems) are caught.
+ *  - The caller is expected to additionally validate the *canonical* path
+ *    (post symlink resolution) via `getAiAdapter().native.canonicalize` + a second
+ *    `checkReadable` pass, since a symlink at an "innocent" path can point
+ *    into a protected directory.
+ */
+const SECRET_BASENAME_PATTERNS = [
+    // Match `.env` and `.env.<suffix>` with no required tail anchor — Windows
+    // strips trailing dots/spaces at open time and NTFS exposes alternate data
+    // streams via `name:stream`, both of which would otherwise slip past a `$`
+    // anchored pattern (`.env.`, `.env::$DATA`).
+    /^\.env(\..+)?(?:[.\s:]|$)/i,
+    /^.*\.pem(?:[.\s:]|$)/i,
+    /^.*\.key(?:[.\s:]|$)/i, // private keys
+    /^.*\.p12(?:[.\s:]|$)/i,
+    /^.*\.pfx(?:[.\s:]|$)/i,
+    /^.*\.asc(?:[.\s:]|$)/i, // PGP armored keys
+    /^.*\.gpg(?:[.\s:]|$)/i,
+    /^.*\.keystore(?:[.\s:]|$)/i,
+    /^.*\.jks(?:[.\s:]|$)/i,
+    // Match `id_rsa`, `id_rsa.pub`, and common backup/copy patterns like
+    // `id_rsa.bak`, `id_rsa_old`, `id_rsa-backup`.
+    /^id_(rsa|dsa|ecdsa|ed25519)([._-].*)?(?:[.\s:]|$)/i,
+    /^known_hosts(?:[.\s:]|$)/i,
+    /^authorized_keys(?:[.\s:]|$)/i,
+    /^htpasswd(?:[.\s:]|$)/i,
+    /^\.netrc(?:[.\s:]|$)/i,
+    /^_netrc(?:[.\s:]|$)/i, // Windows variant
+    /^credentials(?:[.\s:]|$)/i, // .aws/credentials, gcloud, etc.
+    /^\.pgpass(?:[.\s:]|$)/i,
+    /^\.npmrc(?:[.\s:]|$)/i,
+    /^\.pypirc(?:[.\s:]|$)/i,
+    /^secrets?\.(json|ya?ml|toml|env)(?:[.\s:]|$)/i,
+    /^service[-_]?account.*\.json(?:[.\s:]|$)/i, // GCP service account keys
+];
+/**
+ * Protected directories. Matched as **exact path** OR **prefix where the next
+ * char is a separator** — never raw substring. Listed without trailing slash;
+ * the comparator handles separators.
+ */
+const PROTECTED_DIRS = [
+    "/.ssh",
+    "/.gnupg",
+    "/.aws",
+    "/.azure",
+    "/.kube",
+    "/.docker",
+    "/.config/gh",
+    "/.config/git",
+    "/.config/gcloud",
+    "/.config/op", // 1Password CLI
+    "/.git", // git internals — refusing avoids tools mutating refs/objects
+    "/.terraform.d",
+    "/library/keychains",
+    "/library/cookies",
+    // System dirs holding host secrets/PII/process state. Per-PID files under
+    // /proc leak env vars and command lines from other processes; /sys exposes
+    // kernel state and hardware identifiers. /etc and /private/etc hold global
+    // config that frequently contains credentials in basenames the regex won't
+    // match (passwd, shadow, master.passwd, *.cnf, *.conf with creds).
+    "/etc",
+    "/private/etc",
+    "/proc",
+    "/sys",
+    "/var/db",
+    "/var/root",
+    "/private/var/db",
+    "/private/var/root",
+    // Windows user profile equivalents (post drive-strip + lowercase).
+    "/appdata/roaming/microsoft/credentials",
+    "/appdata/local/microsoft/credentials",
+    "/appdata/roaming/gcloud",
+];
+/**
+ * Write-only deny prefixes (system locations). Read access is *not* universally
+ * blocked — reading `/etc/hosts` is fine; writing to it isn't.
+ */
+const WRITE_DENY_PREFIXES = [
+    "/etc/",
+    "/var/db/",
+    "/var/root/",
+    "/system/", // case-folded from /System/
+    "/library/keychains/",
+    "/library/launchagents/",
+    "/library/launchdaemons/",
+    "/private/etc/",
+    "/private/var/db/",
+    "/usr/bin/",
+    "/usr/sbin/",
+    "/usr/local/bin/",
+    "/bin/",
+    "/sbin/",
+    "/boot/",
+    // Windows (post drive-strip + lowercase). Note: these block writes to the
+    // system drive's Windows / Program Files. Drives are stripped, so any
+    // /windows/... etc. matches regardless of drive letter.
+    "/windows/",
+    "/program files/",
+    "/program files (x86)/",
+    "/programdata/",
+];
+function basename(p) {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+/**
+ * Build a normalized *comparison surface* — never used as a real path:
+ *  - back-slashes -> forward-slashes
+ *  - strip Windows drive prefix (e.g. `C:`)
+ *  - strip UNC prefix `//?/`
+ *  - strip NTFS alternate-data-stream suffix (`name:stream` / `name::$DATA`)
+ *    from each path segment — Windows reads `foo:stream` as `foo` for our
+ *    purposes, so the comparison surface should too
+ *  - strip trailing dots/spaces from each segment — Windows discards these
+ *    at open time, so `.env.` and `.env ` open `.env`
+ *  - collapse duplicate slashes
+ *  - lowercase (so case variants match on case-insensitive filesystems)
+ *  - drop trailing slash (except for root)
+ */
+function comparisonForm(p) {
+    let s = p.replace(/\\/g, "/");
+    // UNC / extended-length prefix: \\?\C:\... or //?/C:/... → strip up to drive.
+    s = s.replace(/^\/\/\?\//, "/");
+    // Drive prefix: C:/foo → /foo. Important: do this BEFORE lowercasing so we
+    // don't have to special-case "c:" vs "C:".
+    s = s.replace(/^[a-zA-Z]:/, "");
+    // Strip NTFS alternate-data-stream syntax from each segment. `name:stream`
+    // and `name::$DATA` both read the same underlying file from `name`, so
+    // they must compare-equal to `name`.
+    s = s
+        .split("/")
+        .map((seg) => {
+        const colon = seg.indexOf(":");
+        return colon === -1 ? seg : seg.slice(0, colon);
+    })
+        .join("/");
+    // Strip trailing dots/spaces from each segment (Windows behavior).
+    s = s
+        .split("/")
+        .map((seg) => seg.replace(/[.\s]+$/, ""))
+        .join("/");
+    // Collapse duplicate slashes (//foo → /foo). Preserve a possible leading
+    // single slash.
+    s = s.replace(/\/{2,}/g, "/");
+    s = s.toLowerCase();
+    // Drop trailing slash so "/foo/" and "/foo" compare equal.
+    if (s.length > 1 && s.endsWith("/"))
+        s = s.slice(0, -1);
+    return s;
+}
+function isUnderProtected(cmp, dir) {
+    // Ensure cmp is prefixed with / so relative paths like '.ssh/config'
+    // match protected directory entries like '/.ssh'.
+    const norm = cmp.startsWith("/") ? cmp : `/${cmp}`;
+    return `${norm}/`.includes(`${dir}/`);
+}
+function describeProtected(dir) {
+    // "/.ssh" -> ".ssh", "/.config/gh" -> ".config/gh"
+    return dir.replace(/^\//, "");
+}
+export function checkReadable(path) {
+    if (typeof path !== "string" || path.length === 0) {
+        return { ok: false, reason: "Refused: empty path." };
+    }
+    // Reject NUL and control bytes in paths — these are never legitimate and
+    // are a classic truncation/injection vector.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching C0 controls is the entire point of this security check.
+    if (/[\x00-\x1f]/.test(path)) {
+        return { ok: false, reason: "Refused: path contains control bytes." };
+    }
+    const base = basename(path);
+    for (const re of SECRET_BASENAME_PATTERNS) {
+        if (re.test(base)) {
+            return {
+                ok: false,
+                reason: `Refused: "${base}" matches a sensitive-file pattern.`,
+            };
+        }
+    }
+    const cmp = comparisonForm(path);
+    for (const dir of PROTECTED_DIRS) {
+        if (isUnderProtected(cmp, dir)) {
+            return {
+                ok: false,
+                reason: `Refused: path is inside a protected directory (${describeProtected(dir)}).`,
+            };
+        }
+    }
+    return { ok: true };
+}
+export function checkWritable(path) {
+    // Writes inherit all read restrictions, plus system-directory blocks.
+    const r = checkReadable(path);
+    if (!r.ok)
+        return r;
+    const cmp = comparisonForm(path);
+    // Ensure the comparison surface has a leading separator for prefix matching.
+    const cmpForPrefix = cmp.startsWith("/") ? cmp : `/${cmp}`;
+    for (const prefix of WRITE_DENY_PREFIXES) {
+        if (cmpForPrefix.startsWith(prefix) ||
+            `${cmpForPrefix}/`.startsWith(prefix)) {
+            return {
+                ok: false,
+                reason: `Refused: writes under "${prefix.replace(/\/$/, "")}" are not allowed.`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Lightweight heuristic for blocking obviously destructive shell commands
+ * even after the user has approved them. The approval UI shows the command
+ * verbatim, so the user is the primary gate; this just catches a couple of
+ * patterns that almost certainly indicate the model went off the rails.
+ */
+/**
+ * Two-phase safety check that also defends against symlink traversal: first
+ * checks the literal path, then (if it exists) canonicalizes it via the
+ * native FS and re-checks the resolved path. A symlink at `./innocent.txt`
+ * pointing into `~/.ssh/id_rsa` is caught on the second pass.
+ *
+ * Returns the canonical path on success so callers can use it for the actual
+ * read — avoids TOCTOU between the safety check and the read.
+ */
+export async function checkReadableCanonical(path, canonicalize) {
+    const initial = checkReadable(path);
+    if (!initial.ok)
+        return initial;
+    let canonical;
+    try {
+        canonical = await canonicalize(path);
+    }
+    catch {
+        // Path doesn't exist yet — fine for the read tool to surface ENOENT.
+        return { ok: true, canonical: path };
+    }
+    // Always recheck — even when canonicalize returns the same string, the
+    // checks themselves can have OS-specific gaps (NTFS streams, trailing
+    // dot/space) that warrant a second pass against the comparison form.
+    const recheck = checkReadable(canonical);
+    if (!recheck.ok)
+        return recheck;
+    return { ok: true, canonical };
+}
+/**
+ * Same pattern as {@link checkReadableCanonical} but for writes. The canonical
+ * path is only available if the file already exists — for new-file creates
+ * we additionally canonicalize the parent directory.
+ */
+export async function checkWritableCanonical(path, canonicalize) {
+    const initial = checkWritable(path);
+    if (!initial.ok)
+        return initial;
+    // Try canonicalizing the target itself first.
+    try {
+        const canonical = await canonicalize(path);
+        // Always recheck the canonical form — same rationale as checkReadableCanonical.
+        const recheck = checkWritable(canonical);
+        if (!recheck.ok)
+            return recheck;
+        return { ok: true, canonical };
+    }
+    catch {
+        // Target doesn't exist — canonicalize the parent so we still catch a
+        // symlinked parent directory (`./project -> /Users/me/.ssh`).
+        const lastSep = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+        if (lastSep > 0) {
+            const parent = path.slice(0, lastSep);
+            const tail = path.slice(lastSep);
+            try {
+                const canonParent = await canonicalize(parent);
+                const recheckParent = checkWritable(canonParent + tail);
+                if (!recheckParent.ok)
+                    return recheckParent;
+                return { ok: true, canonical: canonParent + tail };
+            }
+            catch {
+                // Parent doesn't exist either — let the caller surface the actual error.
+            }
+        }
+        return { ok: true, canonical: path };
+    }
+}
+export function checkShellCommand(cmd) {
+    const c = cmd.trim();
+    if (c.length === 0) {
+        return { ok: false, reason: "Refused: empty command." };
+    }
+    // Block C0 controls. CR/LF would let a second statement smuggle past the
+    // approval UI, which shows the command as one logical line.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching C0 controls is the entire point of this security check.
+    if (/[\x00-\x1f]/.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: command contains control characters (including CR/LF). Commands must be single-line.",
+        };
+    }
+    // Block Unicode bidi-override and invisible directional marks. These let an
+    // attacker craft a command whose visual order (in the approval UI's <pre>
+    // block) differs from its logical execution order — a Trojan Source attack.
+    // Legitimate shell commands do not need RTL overrides.
+    if (/[\u202A-\u202E\u2066-\u2069\u200E\u200F\u061C]/.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: command contains Unicode bidirectional override characters.",
+        };
+    }
+    // rm -rf / (and variants with quoted /, --no-preserve-root, etc.)
+    if (/\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*|--recursive\s+--force|--force\s+--recursive)\s+(['"]?\/['"]?\s*($|;|&|\|))/.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: command attempts to recursively delete the filesystem root.",
+        };
+    }
+    // rm -rf ~ / $HOME / ${HOME}, with or without a trailing path — wiping the user's home dir
+    if (/\brm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s+(['"]?(~(\/[^\s'"]*)?|\$\{?HOME\}?(\/[^\s'"]*)?)['"]?)(\s|$|;|&|\|)/.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: command attempts to recursively delete the home directory.",
+        };
+    }
+    if (/--no-preserve-root/.test(c)) {
+        return { ok: false, reason: "Refused: --no-preserve-root is not allowed." };
+    }
+    // dd to a raw disk device
+    if (/\bdd\b[^|]*\bof=\/dev\/(disk|sd|nvme|hd)/i.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: dd to a block device is not allowed.",
+        };
+    }
+    // mkfs / fdisk / diskutil eraseDisk / parted
+    if (/\b(mkfs(\.[a-z0-9]+)?|fdisk|parted)\b/.test(c) ||
+        /\bdiskutil\s+erase/i.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: disk-formatting commands are not allowed.",
+        };
+    }
+    // Fork bomb
+    if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;/.test(c)) {
+        return { ok: false, reason: "Refused: fork-bomb pattern detected." };
+    }
+    // Pipe-to-shell from network. The user already approves the command, but
+    // this combo is overwhelmingly malicious-payload-shaped and worth flagging.
+    if (/\b(curl|wget)\b[^|;&]*\|\s*(ba|z|k|d|fi|c)?sh\b/.test(c)) {
+        return {
+            ok: false,
+            reason: "Refused: piping a network download directly into a shell is blocked. Download first, inspect, then run.",
+        };
+    }
+    return { ok: true };
+}

package/dist/tools/agent.d.ts

@@ -0,0 +1,4 @@
+import type { ToolContext } from "./context.js";
+export declare function buildManagedAgentTools(ctx: ToolContext): {
+    run_subagent: any;
+};

package/dist/tools/agent.js

@@ -0,0 +1,22 @@
+import { getAiAdapter } from "../config.js";
+import { tool } from "ai";
+import { z } from "zod";
+export function buildManagedAgentTools(ctx) {
+    return {
+        run_subagent: tool({
+            description: "Spawn a managed subagent.",
+            inputSchema: z.object({
+                prompt: z.string(),
+            }),
+            execute: async ({ prompt }) => {
+                try {
+                    const result = await getAiAdapter().spawnManagedAgent({ prompt });
+                    return result;
+                }
+                catch (e) {
+                    return { error: String(e) };
+                }
+            },
+        }),
+    };
+}

package/dist/tools/context.d.ts

@@ -0,0 +1,30 @@
+export type ToolContext = {
+    /** Active terminal tab cwd, used to resolve relative paths. Null = home. */
+    getCwd: () => string | null;
+    /** Workspace root (explorer root). Used by tools that operate over the project. */
+    getWorkspaceRoot: () => string | null;
+    /** Last N lines of the active terminal buffer (or null if not a terminal tab). */
+    getTerminalContext: () => string | null;
+    isActiveTerminalPrivate: () => boolean;
+    /**
+     * Type a string into the active terminal at the prompt — without executing.
+     * Returns false if there is no active terminal tab to inject into.
+     */
+    injectIntoActivePty: (text: string) => boolean;
+    /** Open a new preview tab (in-app iframe) at the given URL. */
+    openPreview: (url: string) => boolean;
+    /** Spawn a Claude Code agent in a new terminal tab, bound to this session. */
+    spawnAgent: (prompt: string) => {
+        tabId: number;
+        leafId: number;
+    } | null;
+    /** Read the terminal scrollback tail of a managed agent's leaf. */
+    readAgentOutput: (leafId: number) => string | null;
+    readCache: Map<string, {
+        size: number;
+        hash: number;
+    }>;
+    /** Active chat session id — used by tools that persist per-session state (todos). */
+    getSessionId: () => string | null;
+};
+export declare function resolvePath(rawPath: string, cwd: string | null): string;

package/dist/tools/context.js

@@ -0,0 +1,8 @@
+export function resolvePath(rawPath, cwd) {
+    if (rawPath.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(rawPath))
+        return rawPath;
+    if (!cwd)
+        throw new Error(`cannot resolve relative path "${rawPath}": no active terminal cwd. Pass an absolute path.`);
+    const sep = cwd.includes("\\") && !cwd.includes("/") ? "\\" : "/";
+    return cwd.endsWith(sep) ? `${cwd}${rawPath}` : `${cwd}${sep}${rawPath}`;
+}

package/dist/tools/edit.d.ts

@@ -0,0 +1,27 @@
+import { type ToolContext } from "./context.js";
+type EditResult = {
+    ok: true;
+    replacements: number;
+    bytesWritten: number;
+    path: string;
+} | {
+    error: string;
+    path: string;
+};
+export declare function buildEditTools(ctx: ToolContext): {
+    readonly edit: import("ai").Tool<{
+        path: string;
+        old_string: string;
+        new_string: string;
+        replace_all?: boolean | undefined;
+    }, EditResult>;
+    readonly multi_edit: import("ai").Tool<{
+        path: string;
+        edits: {
+            old_string: string;
+            new_string: string;
+            replace_all?: boolean | undefined;
+        }[];
+    }, EditResult>;
+};
+export {};

package/dist/tools/edit.js

@@ -0,0 +1,161 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { getAiAdapter } from "../config.js";
+import { checkWritableCanonical } from "../lib/security.js";
+import { resolvePath } from "./context.js";
+function djb2(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    return h >>> 0;
+}
+async function applyEdits(abs, edits, kind, readCache) {
+    const r = await getAiAdapter().native.readFile(abs);
+    if (r.kind === "binary")
+        return { error: "binary file refused", path: abs };
+    if (r.kind === "toolarge")
+        return { error: `file too large (${r.size} bytes)`, path: abs };
+    const original = r.content;
+    let content = original;
+    let totalReplacements = 0;
+    for (const e of edits) {
+        if (e.old_string === e.new_string) {
+            return {
+                error: "old_string and new_string are identical",
+                path: abs,
+            };
+        }
+        if (e.old_string.length === 0) {
+            return { error: "old_string cannot be empty", path: abs };
+        }
+        if (e.replace_all) {
+            const before = content;
+            content = content.split(e.old_string).join(e.new_string);
+            const occurrences = (before.length - content.length) /
+                (e.old_string.length - e.new_string.length || 1) || 0;
+            // Recover count via direct search to avoid divide-by-zero edge cases.
+            let n = 0;
+            let i = before.indexOf(e.old_string, 0);
+            while (i !== -1) {
+                n++;
+                i = before.indexOf(e.old_string, i + e.old_string.length);
+            }
+            if (n === 0) {
+                return {
+                    error: `old_string not found: ${JSON.stringify(e.old_string.slice(0, 80))}`,
+                    path: abs,
+                };
+            }
+            totalReplacements += n;
+            void occurrences;
+        }
+        else {
+            const first = content.indexOf(e.old_string);
+            if (first === -1) {
+                return {
+                    error: `old_string not found: ${JSON.stringify(e.old_string.slice(0, 80))}`,
+                    path: abs,
+                };
+            }
+            const second = content.indexOf(e.old_string, first + 1);
+            if (second !== -1) {
+                return {
+                    error: "old_string is not unique. Provide more surrounding context, or set replace_all=true.",
+                    path: abs,
+                };
+            }
+            content =
+                content.slice(0, first) +
+                    e.new_string +
+                    content.slice(first + e.old_string.length);
+            totalReplacements += 1;
+        }
+    }
+    if (getAiAdapter().isPlanActive()) {
+        getAiAdapter().enqueuePlanEdit({
+            id: crypto.randomUUID(),
+            kind,
+            path: abs,
+            originalContent: original,
+            proposedContent: content,
+            isNewFile: false,
+        });
+        return {
+            ok: true,
+            replacements: totalReplacements,
+            bytesWritten: content.length,
+            path: abs,
+        };
+    }
+    try {
+        await getAiAdapter().native.writeFile(abs, content);
+        readCache.set(abs, { size: content.length, hash: djb2(content) });
+        return {
+            ok: true,
+            replacements: totalReplacements,
+            bytesWritten: content.length,
+            path: abs,
+        };
+    }
+    catch (err) {
+        return { error: String(err), path: abs };
+    }
+}
+export function buildEditTools(ctx) {
+    return {
+        edit: tool({
+            description: "Replace an exact string in a file. Requires read_file on this path first in the current session — this prevents blind edits. `old_string` must be unique in the file unless `replace_all: true`. Asks for user approval before writing.",
+            inputSchema: z.object({
+                path: z.string(),
+                old_string: z
+                    .string()
+                    .describe("Exact substring to replace. Must be unique unless replace_all."),
+                new_string: z.string().describe("Replacement substring."),
+                replace_all: z.boolean().optional(),
+            }),
+            needsApproval: true,
+            execute: async ({ path, old_string, new_string, replace_all }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkWritableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                if (!ctx.readCache.has(abs)) {
+                    return {
+                        error: "must call read_file on this path first (read-before-edit invariant).",
+                        path: abs,
+                    };
+                }
+                return applyEdits(abs, [{ old_string, new_string, replace_all }], "edit", ctx.readCache);
+            },
+        }),
+        multi_edit: tool({
+            description: "Apply several exact-string replacements to a single file atomically. Each edit is applied in order to the running buffer; if any edit's old_string is missing or non-unique, the whole batch aborts before writing. Requires prior read_file on the path. Asks for user approval before writing.",
+            inputSchema: z.object({
+                path: z.string(),
+                edits: z
+                    .array(z.object({
+                    old_string: z.string(),
+                    new_string: z.string(),
+                    replace_all: z.boolean().optional(),
+                }))
+                    .min(1),
+            }),
+            needsApproval: true,
+            execute: async ({ path, edits }) => {
+                const reqPath = resolvePath(path, ctx.getCwd());
+                const safety = await checkWritableCanonical(reqPath, getAiAdapter().native.canonicalize);
+                if (!safety.ok)
+                    return { error: safety.reason, path: reqPath };
+                const abs = safety.canonical;
+                if (!ctx.readCache.has(abs)) {
+                    return {
+                        error: "must call read_file on this path first (read-before-edit invariant).",
+                        path: abs,
+                    };
+                }
+                return applyEdits(abs, edits, "multi_edit", ctx.readCache);
+            },
+        }),
+    };
+}