teapot-coding-agent 0.23.0 → 0.24.0

package/dist/agent/tools.js

@@ -88,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
@@ -96,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,
@@ -183,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;
@@ -227,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) => {
@@ -239,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),
             });
         });
     });
@@ -636,10 +667,140 @@ async function rollbackWrites(backups, temps) {
             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: {
@@ -651,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);
@@ -685,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)`;
@@ -695,9 +923,10 @@ 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 };
         },
     },
     {
@@ -744,6 +973,8 @@ 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. " +
+            "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: {
@@ -766,14 +997,37 @@ export const TOOLS = [
             const stale = staleGuard(str(args.path), args.base_content, text);
             if (stale)
                 return stale;
-            const oldText = str(args.old_text);
+            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;
@@ -817,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)" : ""}`,
             };
         },
     },
@@ -1173,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"],
         },
@@ -1208,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 };
         },
     },
@@ -1295,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 ?? []);
@@ -1307,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)
@@ -1316,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);
     }