teapot-coding-agent 0.22.13 → 0.24.0

package/dist/agent/tools.js

@@ -16,6 +16,38 @@ function clip(s, max) {
 async function readText(p) {
     return fs.readFile(p, "utf8");
 }
+/**
+ * Optimistic-concurrency guard (#5). The model reads a file, thinks, then
+ * writes — and in between, a sub-agent, a background job or the operator may
+ * have changed it. Anchored edits usually fail safe (old_text is gone, so the
+ * call errors), but two paths silently clobber work nobody looked at:
+ * `replace_all` rewrites every occurrence present NOW, including ones that
+ * appeared after the model formed its plan, and write_file/apply_patch replace
+ * whole files unconditionally.
+ *
+ * A caller that passes `base_content` (the bytes it actually read) therefore
+ * gets a refusal instead of a lost update — the same contract the web file
+ * editor already enforces (see api.ts PUT /file). The check is advisory by
+ * design: omitting the parameter keeps today's behaviour, so this can never
+ * break a working agent loop that does not use it.
+ */
+function staleGuard(pathArg, base, current) {
+    if (typeof base !== "string")
+        return null; // not supplied → no check
+    if (base === current)
+        return null; // unchanged → proceed
+    const rel = pathArg;
+    return {
+        ok: false,
+        result: `${rel} changed on disk since you read it — nothing was written.\n` +
+            `your base_content: ${base.length} bytes, on disk now: ${current === null ? "(deleted)" : `${current.length} bytes`}.\n` +
+            `Re-read ${rel}, redo the edit against the current content, and pass the fresh text as base_content.`,
+    };
+}
+/** Read the file for a guarded write, or null when it does not exist. */
+async function currentOrNull(p) {
+    return fs.readFile(p, "utf8").catch(() => null);
+}
 /** Resolve a path inside the workspace; reject escapes (incl. symlink targets).
  *  KNOWN LIMIT (review finding, accepted): the check-then-open pattern has a
  *  TOCTOU window — a symlink swapped in between safeJoin() and fs.open() could
@@ -56,6 +88,28 @@ function bgMapFor(cwd) {
     }
     return m;
 }
+/**
+ * Environment for every shell the agent runs.
+ *
+ * `PWD` is deliberately removed: the server's own PWD would contradict the
+ * `cwd` we spawn with, so a command trusting `$PWD` would act on the wrong
+ * directory (#34). `bash` re-creates PWD from its actual cwd.
+ */
+function shellEnv() {
+    const { PWD: _pwd, ...rest } = process.env;
+    return { ...rest, TERM: "dumb", GIT_PAGER: "cat", PAGER: "cat" };
+}
+/**
+ * Human-readable elapsed-time suffix appended to a shell result so the MODEL
+ * sees how long a command actually took (#26). Only the operator saw it — the
+ * model happily re-issued commands that ran for tens of minutes.
+ *
+ * Kept terse and single-line: it rides along with the tool output, and mirrors
+ * what bash_output already prints for a still-running job.
+ */
+export function elapsed(t0, now = Date.now()) {
+    return `\n[took ${((now - t0) / 1000).toFixed(1)}s]`;
+}
 function startBackgroundShell(cmd, ctx) {
     const map = bgMapFor(ctx.cwd);
     // opportunistic cleanup of long-dead jobs so the map can't grow forever
@@ -64,11 +118,13 @@ function startBackgroundShell(cmd, ctx) {
             void id;
     }
     const id = `bg${++bgSeq}`;
-    const child = spawn("/bin/bash", ["-lc", cmd], {
+    // plain `-c`, not `-lc`: a login shell sources ~/.bash_profile, whose `cd`
+    // would move background jobs out of the workspace (#34)
+    const child = spawn("/bin/bash", ["-c", cmd], {
         cwd: ctx.cwd,
         detached: true,
         stdio: ["ignore", "pipe", "pipe"],
-        env: { ...process.env, TERM: "dumb", GIT_PAGER: "cat", PAGER: "cat" },
+        env: shellEnv(),
     });
     const sh = {
         id, cmd, child,
@@ -83,14 +139,31 @@ function startBackgroundShell(cmd, ctx) {
     };
     child.stdout?.on("data", collect);
     child.stderr?.on("data", collect);
-    child.on("close", (code) => {
+    // "exit" (process gone) and "close" (all stdio drained) are DIFFERENT events.
+    // A backgrounded grandchild that inherits stdout — `npm run dev &`,
+    // `docker compose up &`, a script that forks a watcher — keeps the pipe open,
+    // so "close" can stay pending long after the shell itself is dead. Keying
+    // the exit state off "close" alone left such jobs marked running FOREVER:
+    // hasRunningBgShells() said yes, the auto-continue loop kept breaking out on
+    // "background job still running", and the agent sat in "running" with the
+    // job long dead and no notification ever delivered (#23).
+    //
+    // So: "exit" is authoritative for state and for the completion
+    // notification; "close" only means "output finally drained" and is used to
+    // capture the tail. The notify() helper keeps this exactly-once.
+    let exitNotified = false;
+    const notify = (code) => {
         sh.exited = true;
-        sh.code = code;
+        if (code !== null)
+            sh.code = code;
+        if (exitNotified)
+            return;
+        exitNotified = true;
         // tell the harness so the agent learns the outcome WITHOUT polling
         try {
             ctx.onBackgroundExit?.({
                 id,
-                code,
+                code: sh.code,
                 cmd,
                 durationMs: Date.now() - sh.startedAt,
                 outputTail: sh.out.slice(-2000),
@@ -99,7 +172,9 @@ function startBackgroundShell(cmd, ctx) {
         catch {
             /* notification is best-effort */
         }
-    });
+    };
+    child.on("exit", (code) => notify(code));
+    child.on("close", (code) => notify(code));
     map.set(id, sh);
     return id;
 }
@@ -132,11 +207,15 @@ export function hasRunningBgShells(cwd) {
 /** Run a command in its own process group; kill the whole group on timeout. */
 function runShell(cmd, ctx, timeoutMs) {
     return new Promise((resolve) => {
-        const child = spawn("/bin/bash", ["-lc", cmd], {
+        const t0 = Date.now();
+        // `bash -l` sources /etc/profile + ~/.bash_profile, either of which may
+        // `cd` somewhere — which silently moved every later relative path out of
+        // the workspace (#34). Plain `-c` starts in ctx.cwd and stays there.
+        const child = spawn("/bin/bash", ["-c", cmd], {
             cwd: ctx.cwd,
             detached: true, // own process group
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, TERM: "dumb", GIT_PAGER: "cat", PAGER: "cat" },
+            env: shellEnv(),
         });
         let out = "";
         let done = false;
@@ -176,7 +255,7 @@ function runShell(cmd, ctx, timeoutMs) {
             ctx.signal?.removeEventListener("abort", onAbort);
             if (!done) {
                 done = true;
-                resolve({ ok: false, result: `spawn error: ${err.message}` });
+                resolve({ ok: false, result: `spawn error: ${err.message}${elapsed(t0)}` });
             }
         });
         child.on("close", (code, signal) => {
@@ -188,14 +267,17 @@ function runShell(cmd, ctx, timeoutMs) {
             if (killReason) {
                 resolve({
                     ok: false,
-                    result: `${killReason}. Partial output:\n${clip(out.trim() || "(no output)", ctx.maxOutputBytes)}`,
+                    result: `${killReason}. Partial output:\n${clip(out.trim() || "(no output)", ctx.maxOutputBytes)}${elapsed(t0)}`,
                 });
                 return;
             }
             resolve({
                 ok: code === 0,
                 result: (code === 0 ? "" : `exit=${code}${signal ? ` signal=${signal}` : ""}\n`) +
-                    clip(out.trim() || "(no output)", ctx.maxOutputBytes),
+                    clip(out.trim() || "(no output)", ctx.maxOutputBytes) +
+                    // the model, not just the operator, needs to know a command was slow —
+                    // otherwise it happily re-issues something that takes 40 minutes (#26)
+                    elapsed(t0),
             });
         });
     });
@@ -511,19 +593,214 @@ async function applyPatch(patch, ctx) {
     catch (e) {
         return { ok: false, result: `patch validation failed: ${e.message}` };
     }
-    // phase 2 — commit
-    for (const w of writes) {
-        await fs.mkdir(path.dirname(w.abs), { recursive: true });
-        await fs.writeFile(w.abs, w.content, "utf8");
+    // phase 2 — commit.
+    //
+    // Phase 1 validates every hunk in memory, so a CONTENT mismatch never
+    // lands halfway. An I/O failure still could: the old loop wrote straight
+    // to the final paths, so a failure on write k of n left writes 1..k-1
+    // already on disk while the tool reported "patch failed". apply_patch is
+    // documented as atomic, so make the commit phase live up to it:
+    //   1. back up the current bytes of every path we are about to change
+    //   2. write each new file to a sibling temp file, then rename() over the
+    //      target (rename within a directory is atomic, so a reader never
+    //      observes a half-written file)
+    //   3. on ANY failure, restore the backups and remove temp files
+    // Deletes are only performed once every write has landed, and a failed
+    // delete is now reported instead of silently swallowed.
+    const backups = new Map();
+    const temps = [];
+    try {
+        for (const w of writes) {
+            if (!backups.has(w.abs))
+                backups.set(w.abs, await fs.readFile(w.abs, "utf8").catch(() => null));
+            await fs.mkdir(path.dirname(w.abs), { recursive: true });
+            const tmp = `${w.abs}.teapot-patch-${process.pid}-${temps.length}.tmp`;
+            temps.push(tmp);
+            await fs.writeFile(tmp, w.content, "utf8");
+            await fs.rename(tmp, w.abs);
+        }
+    }
+    catch (e) {
+        await rollbackWrites(backups, temps);
+        return {
+            ok: false,
+            result: `patch commit failed and was rolled back (no files changed): ${e.message}\n` +
+                "re-read the files and regenerate the patch",
+        };
+    }
+    // writes are in — now the deletes. A delete that fails is a real, visible
+    // inconsistency (the old content moved/updated but the source survived),
+    // so roll the whole patch back rather than report a false success.
+    const removed = [];
+    try {
+        for (const d of deletes) {
+            await fs.rm(d);
+            removed.push(d);
+        }
+    }
+    catch (e) {
+        for (const d of removed) {
+            const orig = await fs.readFile(d, "utf8").catch(() => null);
+            if (orig !== null)
+                await fs.writeFile(d, orig, "utf8").catch(() => { });
+        }
+        await rollbackWrites(backups, temps);
+        return {
+            ok: false,
+            result: `patch commit failed and was rolled back (no files changed): ${e.message}`,
+        };
     }
-    for (const d of deletes)
-        await fs.rm(d).catch(() => { });
     return { ok: true, result: `patch applied:\n${summary.join("\n")}` };
 }
+/**
+ * Undo a partially committed patch: restore each target's original bytes
+ * (null = it did not exist before, so remove the file we created) and clean
+ * up any temp file that never made it through its rename.
+ */
+async function rollbackWrites(backups, temps) {
+    for (const t of temps)
+        await fs.rm(t, { force: true }).catch(() => { });
+    for (const [abs, orig] of backups) {
+        if (orig === null)
+            await fs.rm(abs, { force: true }).catch(() => { });
+        else
+            await fs.writeFile(abs, orig, "utf8").catch(() => { });
+    }
+}
+/* ---------- hashline: stable, verifiable line anchors (#7 / #4) ----------
+ *
+ * The default `N| ` gutter is a trap: read_file prints it, but edit_file's
+ * old_text must NOT contain it — so the model strips the gutter by hand on
+ * every read, and the only mitigation is a sentence in the tool description.
+ *
+ * Format follows the established "hashline" convention used across AI coding
+ * harnesses (quangdang46/hashline, kebbbnnn/hashline, opencode-hashline,
+ * pi-hashline-edit-pro, …) so anchors read the same everywhere:
+ *
+ *     12:a3f1| function calculateTotal(items) {
+ *
+ * i.e. `LINE:HASH| content` — the line number is KEPT (humans and models both
+ * navigate by line) and the content hash is ADDED as an integrity anchor.
+ *
+ * Design points taken from those implementations rather than invented:
+ *  - the hash covers the STRIPPED content, so re-indenting a line does not
+ *    invalidate its anchor;
+ *  - blank/whitespace-only lines get a fixed reserved hash;
+ *  - when a hash occurs more than once, the anchor's line number disambiguates
+ *    via PROXIMITY search, instead of silently taking the first match.
+ */
+const HASH_BLANK = "    "; // 4 spaces: reserved, cannot collide with a hex hash
+// A real hash is 4 HEX chars, but the shape also accepts other 4-8 char
+// alphanumerics: a model that mistypes or invents an anchor is common enough
+// that we should still recognise the SHAPE and say "that anchor is malformed"
+// rather than falling through to "no similar text found" (#7).
+const ANCHOR_RE = /^\s*(\d+):([0-9a-z]{4,8}| {4})\|/;
+/** 4-char content hash (FNV-1a 32-bit → hex), of the STRIPPED line */
+export function hashLine(content) {
+    const stripped = content.trim();
+    if (!stripped)
+        return HASH_BLANK;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < stripped.length; i++) {
+        h ^= stripped.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return (h >>> 0).toString(16).padStart(8, "0").slice(-4);
+}
+/** `LINE:HASH| content` for each line, 1-indexed */
+export function renderHashlines(lines, startLine = 1) {
+    return lines
+        .map((l, i) => `${startLine + i}:${hashLine(l)}| ${l}`)
+        .join("\n");
+}
+/** parse a `LINE:HASH` anchor; returns null when the text is not an anchor */
+export function parseAnchor(anchor) {
+    const m = /^\s*(\d+):([0-9a-z]{4,8}| {4})\s*$/.exec(anchor);
+    if (!m)
+        return null;
+    return { line: Number(m[1]), hash: m[2] };
+}
+/**
+ * Locate the line an anchor refers to.
+ *
+ * The hash is authoritative; the line number only disambiguates when the same
+ * content appears twice (proximity search). Falling back to "nearest line" for
+ * an unknown hash is deliberately NOT done — that would silently edit the wrong
+ * line, which is the entire failure mode hashline exists to prevent.
+ */
+export function resolveAnchor(lines, anchor) {
+    const hits = [];
+    for (let i = 0; i < lines.length; i++)
+        if (hashLine(lines[i]) === anchor.hash)
+            hits.push(i);
+    if (!hits.length)
+        return {
+            error: /^[0-9a-f]{4}$/.test(anchor.hash) || anchor.hash === HASH_BLANK
+                ? `no line matches hash ${anchor.hash} — the file changed since you read it (re-read it)`
+                : // distinguish "you invented/mistyped this anchor" from "the file moved",
+                    // which sends the agent to fix the right thing (#7)
+                    `hash ${JSON.stringify(anchor.hash)} is not a valid anchor (expected 4 hex chars) — re-read the file and copy the anchor verbatim`,
+        };
+    if (hits.length === 1)
+        return { index: hits[0], how: "unique" };
+    const target = anchor.line - 1;
+    const best = hits.reduce((a, b) => (Math.abs(b - target) < Math.abs(a - target) ? b : a));
+    return { index: best, how: `ambiguous, resolved by proximity to line ${anchor.line}` };
+}
+/** Is this whole block a hashline block (every line carries an anchor)? */
+export function isHashlineBlock(block) {
+    const rows = block.split("\n").filter((l) => l !== "");
+    if (!rows.length)
+        return false;
+    return rows.every((l) => ANCHOR_RE.test(l));
+}
+/**
+ * Turn a copied hashline block back into file content.
+ *
+ * The anchors are verified against the CURRENT file, so a stale read is
+ * refused instead of editing the wrong bytes — the whole point of the format.
+ */
+export function resolveHashlineBlock(block, lines) {
+    const rows = block.split("\n").filter((l) => l !== "");
+    const picked = [];
+    const content = [];
+    const notes = [];
+    const used = new Set();
+    for (const row of rows) {
+        const a = parseAnchor(row.slice(0, row.indexOf("|")));
+        if (!a)
+            return { error: `not a valid hashline anchor: ${row.slice(0, 12)}…` };
+        const r = resolveAnchor(lines, a);
+        if ("error" in r)
+            return { error: r.error };
+        if (used.has(r.index))
+            return { error: `anchor ${a.line}:${a.hash} resolves to a line already used in this block` };
+        used.add(r.index);
+        picked.push(r.index);
+        content.push(lines[r.index]);
+        if (r.how !== "unique")
+            notes.push(r.how);
+    }
+    if (!picked.length)
+        return { error: "empty hashline block" };
+    return { text: content.join("\n"), indices: picked, notes };
+}
+/** normalize the read_file line-reference argument */
+export function lineIdMode(args) {
+    const v = args.line_ids ?? args.hashline;
+    if (v === true)
+        return "hash";
+    const s = String(v ?? "").trim().toLowerCase();
+    return s === "hash" || s === "hashline" || s === "true" ? "hash" : "none";
+}
 export const TOOLS = [
     {
         name: "read_file",
         description: "Read a text file from the workspace. Returns numbered lines (`N| ` prefixes are display-only — never copy them into edit_file). " +
+            "With `line_ids:\"hash\"` it instead returns `LINE:HASH| content` anchors (the hashline format used by other coding harnesses), " +
+            "which edit_file accepts VERBATIM and re-verifies against the file — so prefer it when you intend to edit what you just read. " +
+            "Pass `paths` (max 10) to read SEVERAL files in one call instead of one call per file; " +
+            "pass `fuzzy` when you do not know the exact path. " +
             "With `pattern`, acts like grep: only matching lines (JS regex, optional `ignore_case`) plus `context` surrounding lines are returned. " +
             "A negative `offset` counts from the end (-30 → last 30 lines, or last 30 matches in pattern mode).",
         parameters: {
@@ -535,14 +812,79 @@ export const TOOLS = [
                 pattern: { type: "string", description: "JS regex — return only matching lines (+context) instead of the whole file" },
                 context: { type: "number", description: "context lines around each pattern match (max 5)" },
                 ignore_case: { type: "boolean", description: "case-insensitive pattern matching" },
+                paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Read SEVERAL files in one call (max 10) instead of one call per file. " +
+                        "Each comes back under its own `--- path ---` header, and a file that " +
+                        "cannot be read is reported inline without failing the others.",
+                },
+                fuzzy: {
+                    type: "string",
+                    description: "Read the file when you do not know its exact path. Matches loosely " +
+                        "(characters in order, ignoring separators and case); if several files " +
+                        "match it lists them so you can pick the right one with `path`.",
+                },
+                line_ids: {
+                    type: "string",
+                    enum: ["none", "hash"],
+                    description: "'hash' → `LINE:HASH| content` anchors that you can hand to edit_file VERBATIM; " +
+                        "the hash is verified against the file, so a stale read is refused instead of editing the wrong lines. " +
+                        "'none' (default) → `N| ` gutters, which are display-only and must be stripped by hand.",
+                },
             },
             required: ["path"],
         },
         async run(args, ctx) {
+            // #16: MULTI-FILE and FUZZY reads.
+            //
+            // Both are opt-in and handled HERE rather than by restructuring this
+            // tool: `paths` re-enters executeTool once per file, and `fuzzy` locates
+            // a file then re-enters it. Nothing about the single-file path below
+            // changes, so its output stays byte-identical — which #7's hashline
+            // anchors and the existing tests both depend on.
+            if (Array.isArray(args.paths) && args.paths.length) {
+                const wanted = args.paths
+                    .map((v) => str(v).trim())
+                    .filter(Boolean);
+                if (!wanted.length)
+                    return { ok: false, result: "paths must contain at least one path" };
+                if (wanted.length > MAX_MULTI_READ) {
+                    return {
+                        ok: false,
+                        result: `too many paths (${wanted.length}); the maximum is ${MAX_MULTI_READ} — read fewer files per call`,
+                    };
+                }
+                const chunks = [];
+                for (const rel of wanted) {
+                    const r = await executeTool("read_file", JSON.stringify({ ...args, path: rel, paths: undefined }), ctx);
+                    // one bad file must not sink the others: report it inline
+                    chunks.push(`--- ${rel} ---\n${r.ok ? r.result : `ERROR: ${r.result}`}`);
+                }
+                return { ok: true, result: chunks.join("\n\n") };
+            }
+            if (args.fuzzy)
+                return fuzzyRead(str(args.fuzzy), ctx, args);
             const p = safeJoin(ctx.cwd, str(args.path));
-            const text = await readText(p);
+            let text;
+            try {
+                text = await readText(p);
+            }
+            catch (err) {
+                // name the file, not just the errno: a multi-file read reports each bad
+                // path inline, and "ENOENT … /tmp/xyz/nope.ts" leaves the model to work
+                // out which of the paths it asked for (#16)
+                const code = err.code;
+                return {
+                    ok: false,
+                    result: code === "ENOENT" ? `cannot read ${str(args.path)}: no such file` : `cannot read ${str(args.path)}: ${err.message}`,
+                };
+            }
             ctx.onFileRead?.(str(args.path));
             const lines = text.split("\n");
+            // #7/#4: opt-in hashline output. Default stays the historical `N| ` so
+            // nothing that depends on it changes until the mode is chosen.
+            const idMode = lineIdMode(args);
             // grep mode
             if (typeof args.pattern === "string" && args.pattern !== "") {
                 const re = compileRegex(args.pattern, args.ignore_case === true);
@@ -569,7 +911,9 @@ export const TOOLS = [
                     else
                         regions.push([s, e]);
                 }
-                const parts = regions.map(([s, e]) => lines.slice(s, e + 1).map((l, k) => `${s + k + 1}| ${l}`).join("\n"));
+                const parts = regions.map(([s, e]) => idMode === "hash"
+                    ? renderHashlines(lines.slice(s, e + 1), s + 1)
+                    : lines.slice(s, e + 1).map((l, k) => `${s + k + 1}| ${l}`).join("\n"));
                 let result = parts.join("\n--\n");
                 if (idxs.length > page.length || off > 0)
                     result += `\n(${off + 1}–${off + page.length} of ${idxs.length} matches)`;
@@ -579,21 +923,27 @@ export const TOOLS = [
             let off = num(args.offset, 1);
             off = off < 0 ? Math.max(0, lines.length + off) : Math.max(0, off - 1);
             const lim = num(args.limit, 2000);
-            const slice = lines.slice(off, off + lim).map((l, i) => `${off + i + 1}| ${l}`);
+            const pageLines = lines.slice(off, off + lim);
+            const slice = idMode === "hash" ? renderHashlines(pageLines, off + 1) : pageLines.map((l, i) => `${off + i + 1}| ${l}`).join("\n");
             const more = off + lim < lines.length ? `\n... (${lines.length - off - lim} more lines)` : "";
-            return { ok: true, result: slice.join("\n") + more };
+            return { ok: true, result: slice + more };
         },
     },
     {
         name: "write_file",
         description: "Create ONE new file, or replace a file's entire content (parent dirs auto-created). " +
             "Creating files as part of a larger batch of edits → one apply_patch instead. " +
-            "Partial changes to an existing file → edit_file.",
+            "Partial changes to an existing file → edit_file. " +
+            "Pass base_content (the bytes you read) when rewriting a file that may have changed under you — the write is refused rather than clobbering a concurrent edit.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string" },
                 content: { type: "string" },
+                base_content: {
+                    type: "string",
+                    description: "Optional: the exact bytes you read before writing. The write is REFUSED if the file changed since — re-read and retry instead of clobbering someone else's edit.",
+                },
             },
             required: ["path", "content"],
         },
@@ -610,6 +960,9 @@ export const TOOLS = [
                 };
             }
             const p = safeJoin(ctx.cwd, str(args.path));
+            const stale = staleGuard(str(args.path), args.base_content, await currentOrNull(p));
+            if (stale)
+                return stale;
             await fs.mkdir(path.dirname(p), { recursive: true });
             await fs.writeFile(p, args.content, "utf8");
             return { ok: true, result: `wrote ${p} (${args.content.length} bytes)` };
@@ -620,7 +973,10 @@ export const TOOLS = [
         description: "Make exactly ONE small, unique replacement in one existing file — the cheapest tool for a single spot change. " +
             "Copy old_text from the file contents (NOT from read_file's `N| ` prefixed display); it must appear exactly once — " +
             "if it matches several places, add surrounding lines or pass replace_all=true. " +
-            "Two or more changes (or a rename/delete) → use apply_patch instead.",
+            "Or read with read_file(line_ids:\"hash\") and pass that block VERBATIM — `LINE:HASH| ` anchors are verified against the " +
+            "current file, and a block whose anchors no longer match is refused as a stale read instead of editing the wrong lines. " +
+            "Two or more changes (or a rename/delete) → use apply_patch instead. " +
+            "Pass base_content (the bytes you read) whenever the file may have changed under you — especially with replace_all, which otherwise rewrites occurrences that appeared after you read.",
         parameters: {
             type: "object",
             properties: {
@@ -628,20 +984,50 @@ export const TOOLS = [
                 old_text: { type: "string" },
                 new_text: { type: "string" },
                 replace_all: { type: "boolean", description: "replace every occurrence instead of requiring uniqueness" },
+                base_content: {
+                    type: "string",
+                    description: "Optional: the exact bytes you read before editing. Refuses the edit if the file changed since — important with replace_all, which otherwise rewrites occurrences that appeared after you read.",
+                },
             },
             required: ["path", "old_text", "new_text"],
         },
         async run(args, ctx) {
             const p = safeJoin(ctx.cwd, str(args.path));
             let text = await readText(p);
-            const oldText = str(args.old_text);
+            const stale = staleGuard(str(args.path), args.base_content, text);
+            if (stale)
+                return stale;
+            let oldText = str(args.old_text);
             const newText = str(args.new_text);
             if (!oldText)
                 return { ok: false, result: "old_text is required" };
             const replaceAll = args.replace_all === true;
-            let count = text.split(oldText).length - 1;
+            // #7/#4: accept a block copied straight out of read_file's hashline
+            // output. When the anchors do not verify we FAIL with the specific reason
+            // rather than silently falling back to literal matching — a literal match
+            // that happened to succeed would edit the wrong bytes, which is the exact
+            // failure mode hashline exists to prevent.
+            //
+            // On success we edit by RESOLVED LINE INDEX rather than by searching for
+            // the text: the anchors already pinpointed the lines, so a block whose
+            // content legitimately appears twice (the case proximity search exists
+            // for) must not then fail the uniqueness check on the resolved text.
+            let hashNote = "";
+            let hashNotes = [];
+            let hashSpan = null;
+            if (isHashlineBlock(oldText)) {
+                const srcLines = text.replace(/\r\n/g, "\n").split("\n");
+                const r = resolveHashlineBlock(oldText, srcLines);
+                if ("error" in r)
+                    hashNote = r.error;
+                else {
+                    oldText = r.text;
+                    hashNotes = r.notes;
+                    hashSpan = { start: r.indices[0], end: r.indices[r.indices.length - 1] + 1 };
+                }
+            }
+            let count = hashNote ? 0 : text.split(oldText).length - 1;
             let normalized = false;
-            // tolerate LF patterns against CRLF files (convert once, on success)
             if (count === 0 && oldText.includes("\n") && text.includes("\r\n")) {
                 const lf = text.replace(/\r\n/g, "\n");
                 const lfCount = lf.split(oldText).length - 1;
@@ -685,21 +1071,45 @@ export const TOOLS = [
                     : `No similar text found — re-read ${str(args.path)} around the target area and copy old_text exactly.`;
                 return {
                     ok: false,
-                    result: `old_text not found in file. ${hint} Watch indentation/trailing spaces and drop the \`N| \` line-number prefixes.`,
+                    // a hashline block that did not resolve gets ITS reason — the generic
+                    // "not found" would send the model hunting for a whitespace problem
+                    // when the real issue is a stale read (#7)
+                    result: hashNote
+                        ? `old_text is a hashline block but did not resolve: ${hashNote}.`
+                        : `old_text not found in file. ${hint} Watch indentation/trailing spaces and drop the \`N| \` line-number prefixes.`,
                 };
             }
-            if (count > 1 && !replaceAll) {
+            if (count > 1 && !replaceAll && !hashSpan) {
                 const at = matchLines(text, oldText);
                 return {
                     ok: false,
                     result: `old_text matched ${count} times (lines ${at.slice(0, 5).join(", ")}) and must be unique — add surrounding lines to old_text, or pass replace_all=true`,
                 };
             }
-            await fs.writeFile(p, replaceAll ? text.split(oldText).join(newText) : text.replace(oldText, newText), "utf8");
-            const where = count > 1 ? ` (${count} occurrences)` : "";
+            // A verified hashline block is addressed BY LINE INDEX: the anchors
+            // already proved which lines it means, so a block whose content occurs
+            // twice must still edit the anchored occurrence rather than fail the
+            // uniqueness check (#4).
+            const out = hashSpan
+                ? text
+                    .split("\n")
+                    .slice(0, hashSpan.start)
+                    .concat(newText.split("\n"), text.split("\n").slice(hashSpan.end))
+                    .join("\n")
+                : replaceAll
+                    ? text.split(oldText).join(newText)
+                    : text.replace(oldText, newText);
+            await fs.writeFile(p, out, "utf8");
+            const where = hashSpan
+                ? ` (lines ${hashSpan.start + 1}–${hashSpan.end}, verified by hash anchor)`
+                : count > 1
+                    ? ` (${count} occurrences)`
+                    : "";
             return {
                 ok: true,
-                result: `${replaceAll ? "replaced all" : "edited"}${where}${normalized ? " (file converted CRLF→LF)" : ""}`,
+                result: `${replaceAll && !hashSpan ? "replaced all" : "edited"}${where}` +
+                    `${hashNotes.length ? ` (${hashNotes[0]})` : ""}` +
+                    `${normalized ? " (file converted CRLF→LF)" : ""}`,
             };
         },
     },
@@ -1041,11 +1451,20 @@ export const TOOLS = [
     {
         name: "load_skill",
         description: "Load a skill's full instructions by name. Use when the system prompt's skill list " +
-            "matches your current task; follow the loaded playbook.",
+            "matches your current task; follow the loaded playbook. " +
+            // #25: the instruction used to need a SECOND, separately-queued message that
+            // only arrived at the next turn boundary. Passing `instructions` delivers it
+            // in the SAME turn as the playbook, so "load X and do Y" costs one round-trip.
+            "Pass `instructions` with what you want done with it to receive both at once.",
         parameters: {
             type: "object",
             properties: {
                 name: { type: "string", description: "skill name from the list in your system prompt" },
+                instructions: {
+                    type: "string",
+                    description: "Optional: what you want done with this skill (the task, constraints, scope). " +
+                        "Delivered in this same turn — no need to queue a follow-up message.",
+                },
             },
             required: ["name"],
         },
@@ -1076,6 +1495,13 @@ export const TOOLS = [
                         listed.map((f) => `- ${f}`).join("\n") +
                         `\nRun scripts with bash (chmod +x first if needed).`;
             }
+            // #25: deliver the caller's instructions in THIS result, so the model does
+            // not have to queue a second message that only lands next turn.
+            const instructions = str(args.instructions).trim();
+            if (instructions)
+                result +=
+                    `\n\n--- Instructions for this task (from the same call):\n${instructions}\n` +
+                        "Apply the playbook above to these instructions now, in this turn.";
             return { ok: true, result };
         },
     },
@@ -1163,6 +1589,103 @@ export const TOOLS = [
         },
     },
 ];
+/** #16: how many files one read_file call may cover. Each costs context, so an
+ *  unbounded array would just be a way to overflow the window in one shot. */
+const MAX_MULTI_READ = 10;
+/**
+ * Subsequence match: every character of `needle` appears in `hay`, in order,
+ * gaps allowed (#16 "fuzzy").
+ *
+ * Deliberately not a ranked edit-distance search. This answers "is this the
+ * file I meant", and it can only say yes or no — it cannot rank a plausible
+ * WRONG file above the right one, which is the failure mode that actually costs
+ * an agent time. Searching file CONTENT is what bash/grep are for.
+ */
+export function fuzzyPathMatch(needle, hay) {
+    const n = needle.toLowerCase().replace(/[\s._/-]+/g, "");
+    if (!n)
+        return false;
+    const h = hay.toLowerCase();
+    let i = 0;
+    for (const ch of h) {
+        if (ch === n[i])
+            i++;
+        if (i === n.length)
+            return true;
+    }
+    return false;
+}
+/**
+ * Locate a file by a loose name and read it (#16).
+ *
+ * Walks the workspace (skipping .git, node_modules and build noise) and ranks
+ * matches: exact path, exact basename, ends-with, then subsequence. When
+ * several match it LISTS them rather than picking one — guessing here would have
+ * the agent edit the wrong file, which is the expensive mistake.
+ */
+async function fuzzyRead(needle, ctx, args) {
+    const q = needle.trim();
+    if (!q)
+        return { ok: false, result: "fuzzy needs a non-empty search string" };
+    const SKIP = new Set([".git", "node_modules", "dist", "build", ".cache", "coverage", "__pycache__"]);
+    const found = [];
+    const walk = async (dir, rel, depth) => {
+        if (depth > 12)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith("."))
+                continue;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (SKIP.has(e.name))
+                    continue;
+                await walk(path.join(dir, e.name), r, depth + 1);
+                continue;
+            }
+            let rank = -1;
+            if (r === q)
+                rank = 0;
+            else if (e.name === q)
+                rank = 1;
+            else if (r.endsWith("/" + q) || r.endsWith(q))
+                rank = 2;
+            else if (fuzzyPathMatch(q, r))
+                rank = 3;
+            if (rank >= 0)
+                found.push({ rel: r, rank });
+        }
+    };
+    await walk(ctx.cwd, "", 0);
+    if (!found.length) {
+        return {
+            ok: false,
+            result: `no file matches "${q}" under the workspace. ` +
+                "Use list_dir to see what exists, or pass the exact path instead of fuzzy.",
+        };
+    }
+    found.sort((a, b) => a.rank - b.rank || a.rel.length - b.rel.length || a.rel.localeCompare(b.rel));
+    const best = found[0];
+    // Only a confident match is read directly. If the query is vague enough that
+    // several files match, LIST them: guessing would hand the agent the wrong
+    // file, and the cost of that mistake is far higher than one extra call.
+    // An exact path or basename is unambiguous, so those still read straight away.
+    if (best.rank <= 1 || found.length === 1) {
+        // re-enter the tool so a unique match behaves exactly like a normal read
+        return executeTool("read_file", JSON.stringify({ ...args, path: best.rel, fuzzy: undefined }), ctx);
+    }
+    return {
+        ok: true,
+        result: `${found.length} files match "${q}" — pass the exact path (or a longer query) to read one:\n` +
+            found.slice(0, 8).map((f) => `  ${f.rel}`).join("\n"),
+    };
+}
 /** Current skills across the configured roots (for the system prompt listing). */
 export async function currentSkills(ctx) {
     return discoverSkills(ctx.skillRoots ?? []);
@@ -1175,6 +1698,218 @@ export function toolSpecs() {
 }
 /** tools that mutate the workspace — blocked for read-only personas */
 const MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch", "bash"]);
+/** per-tool aliases: the common wrong key -> the key the schema declares. */
+const ARG_ALIASES = {
+    bash: { cmd: "command", script: "command", shell: "command", input: "command" },
+    read_file: { file_path: "path", filepath: "path", file: "path", name: "path" },
+    write_file: { file_path: "path", filepath: "path", file: "path" },
+    edit_file: { file_path: "path", filepath: "path", oldValue: "old_text", newValue: "new_text" },
+    apply_patch: { patch_text: "patch", diff: "patch" },
+    list_dir: { file_path: "path", dir: "path", directory: "path" },
+    list_children: { file_path: "path", dir: "path" },
+    read_url: { uri: "url", link: "url" },
+};
+/**
+ * The one argument each tool's whole call usually boils down to. Used to
+ * salvage a bare word ("ls") that was never wrapped in JSON at all — but ONLY
+ * for tools where that is unambiguous, so "12" is never mistaken for a path.
+ */
+const PRIMARY_STRING_ARG = {
+    bash: "command",
+    read_file: "path",
+    write_file: "content",
+    list_dir: "path",
+    list_children: "path",
+    read_url: "url",
+    load_skill: "name",
+    save_skill: "content",
+};
+/** keys whose schema type is a number / boolean, per tool. */
+const NUMERIC_ARGS = {
+    read_file: ["offset", "limit", "context"],
+    bash: ["timeout_ms"],
+    list_dir: [],
+    write_file: [],
+};
+const BOOL_ARGS = {
+    read_file: ["ignore_case"],
+    bash: ["background"],
+    edit_file: ["replace_all"],
+    write_file: [],
+    list_dir: [],
+};
+/** markdown/backtick framing models like to wrap a path in */
+function unframe(v) {
+    const m = /^[`*_\s]+(.+?)[`*_\s]*$/.exec(v);
+    return m ? m[1] : v;
+}
+/** coerce "100" -> 100, "true" -> true; returns undefined when not coercible */
+function coerceScalar(v) {
+    if (typeof v !== "string")
+        return v;
+    const t = v.trim();
+    if (t === "true")
+        return true;
+    if (t === "false")
+        return false;
+    if (t !== "" && !Number.isNaN(Number(t)) && /^[-+]?\d+(\.\d+)?$/.test(t))
+        return Number(t);
+    return v;
+}
+/** Turn a value into an array, tolerating a bare scalar or a JSON array. */
+function toArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string") {
+        const t = v.trim();
+        if (t.startsWith("[")) {
+            try {
+                const p = JSON.parse(t);
+                if (Array.isArray(p))
+                    return p;
+            }
+            catch {
+                /* fall through — treat as a single element */
+            }
+        }
+        return [v];
+    }
+    if (v === undefined || v === null)
+        return [];
+    return [v];
+}
+export function repairToolInput(name, rawArgs) {
+    const notes = [];
+    let parsed;
+    try {
+        parsed = rawArgs?.trim() ? JSON.parse(rawArgs) : {};
+    }
+    catch {
+        // not JSON at all: a whole call was stringified, or the model emitted a
+        // bare word. Only salvageable when the tool takes a single obvious string.
+        const bare = rawArgs?.trim().replace(/^[`*\s]+|[`*\s]+$/g, "");
+        const primary = PRIMARY_STRING_ARG[name];
+        // a bare number/boolean is never a path or a command — refusing is far
+        // better than inventing one (#17)
+        const isScalarish = bare !== "" && /^(true|false|null|-?\d+(\.\d+)?)$/i.test(bare);
+        if (bare && primary && !isScalarish && !bare.startsWith("{") && !bare.startsWith("[")) {
+            notes.push(`wrapped a bare string as {"${primary}": …}`);
+            return { args: { [primary]: unframe(bare) }, notes };
+        }
+        return { args: {}, notes, error: `arguments were not valid JSON — send a JSON object, e.g. {"…"}` };
+    }
+    // a JSON-stringified object arrives as a string
+    if (typeof parsed === "string" && /[{[]/.test(parsed.trim().slice(0, 2))) {
+        try {
+            parsed = JSON.parse(parsed);
+            notes.push("unwrapped a JSON-stringified argument object");
+        }
+        catch {
+            /* leave as-is; it may genuinely be a string argument */
+        }
+    }
+    // a bare scalar where an object is required
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        if (parsed === null || parsed === undefined)
+            return { args: {}, notes, error: "arguments were empty" };
+        // An ARRAY is a legitimate value for a path-ish argument, but only for the
+        // tools that actually take one — inventing {path:[…]} for apply_patch would
+        // hand the tool a key it has never heard of (#17).
+        if (Array.isArray(parsed) && name === "read_file") {
+            notes.push("kept the array as a paths list");
+            return { args: { paths: parsed }, notes };
+        }
+        const primary = PRIMARY_STRING_ARG[name];
+        if (primary && typeof parsed === "string") {
+            notes.push(`wrapped a bare string as {"${primary}": …}`);
+            return { args: { [primary]: unframe(parsed) }, notes };
+        }
+        return {
+            args: {},
+            notes,
+            error: `expected a JSON object for ${name}, got a bare ${Array.isArray(parsed) ? "array" : typeof parsed}` +
+                (primary ? ` — send {"${primary}": …}` : ""),
+        };
+    }
+    const args = { ...parsed };
+    // alias normalisation
+    for (const [from, to] of Object.entries(ARG_ALIASES[name] ?? {})) {
+        if (!(from in args))
+            continue;
+        if (!(to in args)) {
+            args[to] = args[from];
+            notes.push(`renamed "${from}" -> "${to}"`);
+        }
+        else {
+            // both present: the schema key wins and the stray alias is DROPPED, not
+            // left behind as an unknown argument the tool would ignore (#17)
+            notes.push(`dropped "${from}" — "${to}" was also given and wins`);
+        }
+        delete args[from];
+    }
+    // string -> number / boolean for the keys whose schema says so
+    for (const k of NUMERIC_ARGS[name] ?? []) {
+        if (k in args) {
+            const c = coerceScalar(args[k]);
+            if (typeof c !== typeof args[k]) {
+                args[k] = c;
+                notes.push(`coerced "${k}" to ${typeof c}`);
+            }
+        }
+    }
+    for (const k of BOOL_ARGS[name] ?? []) {
+        if (k in args) {
+            const c = coerceScalar(args[k]);
+            if (typeof c !== typeof args[k]) {
+                args[k] = c;
+                notes.push(`coerced "${k}" to ${typeof c}`);
+            }
+        }
+    }
+    // an array-typed arg arriving as a scalar
+    if (name === "read_file" && "paths" in args) {
+        const before = args.paths;
+        args.paths = toArray(before);
+        if (!Array.isArray(before))
+            notes.push('coerced "paths" to an array');
+    }
+    // a JSON-stringified object hiding inside a single argument, e.g.
+    // {"path": "{\"path\": \"a.ts\"}"} — unwrap it and merge its keys
+    // Only PATH-like keys: `content`/`old_text`/`new_text` legitimately hold JSON
+    // (writing a .json file!), and unwrapping those would REPLACE the file's
+    // actual data with an inner field — silent data loss, not repair.
+    for (const k of ["path", "command"]) {
+        const v = args[k];
+        if (typeof v !== "string")
+            continue;
+        const t = v.trim();
+        if (!/^[{[]/.test(t))
+            continue;
+        try {
+            const inner = JSON.parse(t);
+            if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+                delete args[k];
+                Object.assign(args, inner);
+                notes.push(`unwrapped a JSON-stringified object out of "${k}"`);
+                break;
+            }
+        }
+        catch {
+            /* genuinely not JSON — leave it alone */
+        }
+    }
+    // markdown framing on a path
+    for (const k of ["path", "file_path"]) {
+        if (typeof args[k] === "string") {
+            const f = unframe(args[k]);
+            if (f !== args[k]) {
+                args[k] = f;
+                notes.push(`stripped markdown framing from "${k}"`);
+            }
+        }
+    }
+    return { args, notes };
+}
 export async function executeTool(name, rawArgs, ctx) {
     const def = TOOLS.find((t) => t.name === name);
     if (!def)
@@ -1184,13 +1919,15 @@ export async function executeTool(name, rawArgs, ctx) {
     // read-only personas (researcher/reviewer) are enforced, not just asked
     if (ctx.readOnly && MUTATING_TOOLS.has(name))
         return { ok: false, result: `${name} is blocked: this agent runs with read-only tools` };
-    let args;
-    try {
-        args = rawArgs ? JSON.parse(rawArgs) : {};
-    }
-    catch {
-        return { ok: false, result: `invalid JSON arguments: ${rawArgs.slice(0, 200)}` };
-    }
+    // #17: repair the call before handing it to the tool. A model that sends
+    // {"cmd":"ls"} or {"limit":"100"} should get the work done, not a generic parse
+    // failure and a wasted turn. Unrepairable calls say what to send instead.
+    const repaired = repairToolInput(name, rawArgs);
+    if (repaired.error)
+        return { ok: false, result: `${name}: ${repaired.error}` };
+    const args = repaired.args;
+    if (repaired.notes.length && process.env.TEAPOT_DEBUG_REPAIR)
+        console.error(`[repair] ${name}: ${repaired.notes.join("; ")}`);
     try {
         return await def.run(args, ctx);
     }