s-app-scoder-agent 0.8.21 → 0.9.3

package/dist/tools.js

@@ -3,12 +3,13 @@ import { spawn, spawnSync } from "node:child_process";
 import { resolve, dirname, basename, join, relative, isAbsolute, sep } from "node:path";
 import { unifiedDiff } from "./diff.js";
 import { detectImageBytes } from "./tui/image.js";
-import { discoverSkills, findSkill } from "./skills.js";
+import { discoverSkills, findSkill, loadSkillSection } from "./skills.js";
 import { redactSecrets } from "./llm.js";
 import { loadRcFile } from "./config.js";
 import { resolveSandbox } from "./sandbox.js";
 import * as ui from "./ui.js";
 import { toolWebFetch } from "./webfetch.js";
+import { buildRepoMap, renderRepoMap } from "./repo-map.js";
 /**
  * G7: max chars tool output — default 20_000, runtime override qua
  * setMaxOutputChars (agent constructor gọi với config.limits).
@@ -56,7 +57,7 @@ function safePath(workdir, p) {
     for (;;) {
         try {
             const real = realpathSync(probe);
-            const reconstructed = real + missing.map((s) => `/${s}`).join("");
+            const reconstructed = real + [...missing].reverse().map((s) => `/${s}`).join("");
             const rel = relative(realWorkdir, reconstructed.length > 0 ? reconstructed : real);
             if (rel.startsWith("..") || isAbsolute(rel)) {
                 throw new Error(`Path escapes working directory: ${p}`);
@@ -97,12 +98,22 @@ export function isProtectedEnvFile(relPath) {
         return "ask";
     return null;
 }
+/** Coerce a schema-provided numeric-ish arg to a positive int, else fallback. */
+function toPosInt(v, fallback) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+}
 function toolReadFile(workdir, args) {
     return toResult(() => {
         const abs = safePath(workdir, args.path);
         // H-04: .env read policy — ask trước khi trả nội dung (secrets hygiene).
         const rel = relative(workdir, abs);
-        const envPolicy = isProtectedEnvFile(rel);
+        let policyPath = rel;
+        try {
+            policyPath = relative(workdir, realpathSync(abs));
+        }
+        catch { /* handled by safePath */ }
+        const envPolicy = isProtectedEnvFile(policyPath.toLowerCase());
         if (envPolicy === "ask") {
             return {
                 ok: false,
@@ -135,10 +146,20 @@ function toolReadFile(workdir, args) {
         if (image) {
             return { ok: true, output: `[image: ${args.path}]`, image };
         }
+        if (statSync(abs).size > MAX_FILE_SIZE_BYTES) {
+            return { ok: false, output: `ERROR: ${args.path} exceeds the ${MAX_FILE_SIZE_BYTES / 1024 / 1024}MB edit limit.` };
+        }
         const content = readFileSync(abs, "utf8");
         const lines = content.split("\n");
-        const numbered = lines.map((l, i) => `${i + 1}: ${l}`).join("\n");
-        return { ok: true, output: clamp(numbered) };
+        const total = lines.length;
+        // v2: line-range reads — offset (1-based, default 1) + limit (default all).
+        const offset = Math.min(toPosInt(args.offset, 1), total);
+        const limit = Math.min(toPosInt(args.limit, total - offset + 1), 2000);
+        const slice = lines.slice(offset - 1, offset - 1 + limit);
+        const numbered = slice.map((l, i) => `${offset + i}: ${l}`).join("\n");
+        const end = offset + slice.length - 1;
+        const header = offset > 1 || end < total ? `[lines ${offset}-${end} of ${total} — ${args.path}]\n` : "";
+        return { ok: true, output: clamp(header + numbered) };
     });
 }
 function toToolDiff(path, diff) {
@@ -206,6 +227,47 @@ async function toolWriteFile(ctx, args) {
         diff: toToolDiff(args.path, diff),
     };
 }
+/** v2: whitespace-insensitive regex for edit_file fuzzy fallback. */
+function wsInsensitiveRegex(s) {
+    let rx = "";
+    for (const ch of s) {
+        if (/\s/.test(ch))
+            rx += "\\s+";
+        else
+            rx += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(rx);
+}
+/** Apply one exact (or whitespace-tolerant) replacement to in-memory content. */
+function applyOneEdit(content, path, oldString, newString) {
+    if (typeof oldString !== "string" || oldString.length === 0) {
+        return { ok: false, error: "old_string must be a non-empty string." };
+    }
+    if (content.includes(oldString)) {
+        const count = content.split(oldString).length - 1;
+        if (count > 1) {
+            return { ok: false, error: `old_string matches ${count} locations in ${path}; include more surrounding context to make it unique.` };
+        }
+        // Function replacement: avoids JS $-pattern interpolation ($&, $', $`, $1…)
+        // which would corrupt literal text like "$&" in the new content.
+        return { ok: true, content: content.replace(oldString, () => newString), fuzzy: false };
+    }
+    // v2 fuzzy fallback: exact string missing → retry with whitespace-tolerant
+    // matching (indent/trailing-space drift between model and file). Reports
+    // ambiguity instead of guessing when multiple regions match.
+    const all = [...content.matchAll(new RegExp(wsInsensitiveRegex(oldString).source, "g"))];
+    if (all.length === 0) {
+        return { ok: false, error: `old_string not found in ${path}. Read the file again and retry with exact text.` };
+    }
+    if (all.length > 1) {
+        return { ok: false, error: `old_string not found exactly and ${all.length} whitespace-tolerant matches exist in ${path}; include more surrounding context to disambiguate.` };
+    }
+    return {
+        ok: true,
+        content: content.slice(0, all[0].index) + newString + content.slice(all[0].index + all[0][0].length),
+        fuzzy: true,
+    };
+}
 async function toolEditFile(ctx, args) {
     let abs;
     try {
@@ -215,16 +277,10 @@ async function toolEditFile(ctx, args) {
         return { ok: false, output: `ERROR: ${err.message}` };
     }
     const content = readFileSync(abs, "utf8");
-    if (!content.includes(args.old_string)) {
-        return { ok: false, output: `old_string not found in ${args.path}. Read the file again and retry with exact text.` };
-    }
-    const count = content.split(args.old_string).length - 1;
-    if (count > 1) {
-        return { ok: false, output: `old_string matches ${count} locations in ${args.path}; include more surrounding context to make it unique.` };
-    }
-    // Function replacement: avoids JS $-pattern interpolation ($&, $', $`, $1…)
-    // which would corrupt literal text like "$&" in the new content.
-    const newContent = content.replace(args.old_string, () => args.new_string);
+    const outcome = applyOneEdit(content, args.path, args.old_string, args.new_string);
+    if (!outcome.ok)
+        return { ok: false, output: outcome.error };
+    const newContent = outcome.content;
     const diff = unifiedDiff(args.path, content, newContent);
     const gate = await gateWrite(ctx, args.path, diff);
     if (gate)
@@ -233,7 +289,65 @@ async function toolEditFile(ctx, args) {
     const fmtNote = formatFile(ctx, abs);
     return {
         ok: true,
-        output: `Edited ${args.path}${fmtNote ? `\n${fmtNote}` : ""}`,
+        output: `Edited ${args.path}${outcome.fuzzy ? " (fuzzy whitespace match)" : ""}${fmtNote ? `\n${fmtNote}` : ""}`,
+        diff: toToolDiff(args.path, diff),
+    };
+}
+async function toolApplyPatch(ctx, args) {
+    let abs;
+    try {
+        abs = safePath(ctx.workdir, args.path);
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: ${err.message}` };
+    }
+    if (!Array.isArray(args.edits) || args.edits.length === 0) {
+        return { ok: false, output: "ERROR: edits must be a non-empty array." };
+    }
+    if (args.edits.length > 50) {
+        return { ok: false, output: `ERROR: too many edits (${args.edits.length}); split into chunks of at most 50.` };
+    }
+    let content;
+    try {
+        if (statSync(abs).size > MAX_FILE_SIZE_BYTES) {
+            return { ok: false, output: `ERROR: ${args.path} exceeds the ${MAX_FILE_SIZE_BYTES / 1024 / 1024}MB patch limit.` };
+        }
+        content = readFileSync(abs, "utf8");
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: cannot read ${args.path}: ${err.message}` };
+    }
+    const original = content;
+    let fuzzy = 0;
+    for (let i = 0; i < args.edits.length; i++) {
+        const e = args.edits[i];
+        if (!e || typeof e.old_string !== "string" || typeof e.new_string !== "string") {
+            return { ok: false, output: `ERROR: edit #${i + 1} must have string old_string and new_string. No changes written.` };
+        }
+        const outcome = applyOneEdit(content, args.path, e.old_string, e.new_string);
+        if (!outcome.ok) {
+            return {
+                ok: false,
+                output: `ERROR: edit #${i + 1}/${args.edits.length} failed — ${outcome.error} No changes written.`,
+            };
+        }
+        content = outcome.content;
+        if (outcome.fuzzy)
+            fuzzy++;
+    }
+    if (content === original) {
+        return { ok: true, output: `No changes to ${args.path} (all edits were no-ops).` };
+    }
+    const diff = unifiedDiff(args.path, original, content);
+    const gate = await gateWrite(ctx, args.path, diff);
+    if (gate)
+        return gate;
+    writeFileSync(abs, content, "utf8");
+    const fmtNote = formatFile(ctx, abs);
+    const fuzzyNote = fuzzy > 0 ? ` (${fuzzy} fuzzy whitespace match${fuzzy === 1 ? "" : "es"})` : "";
+    return {
+        ok: true,
+        output: `Applied ${args.edits.length} edit${args.edits.length === 1 ? "" : "s"} to ${args.path}${fuzzyNote}${fmtNote ? `\n${fmtNote}` : ""}`,
         diff: toToolDiff(args.path, diff),
     };
 }
@@ -241,9 +355,17 @@ function toolListFiles(workdir, args) {
     return toResult(() => {
         const root = safePath(workdir, args.path ?? ".");
         const skip = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", ".venv"]);
+        // v2: configurable depth (default 4, cap 8), hidden-dotfiles opt-in, exclude globs.
+        const maxDepth = Math.min(toPosInt(args.depth, 4), 8);
+        const includeHidden = args.include_hidden === true || args.include_hidden === "true";
+        const excludeRx = args.exclude
+            ? new RegExp(args.exclude.split(/[,\s]+/).filter(Boolean)
+                .map((g) => globToRegExp(g).source)
+                .join("|"))
+            : null;
         const out = [];
         const walk = (dir, depth) => {
-            if (depth > 4 || out.length > 500)
+            if (depth > maxDepth || out.length > 500)
                 return;
             let entries;
             try {
@@ -255,15 +377,20 @@ function toolListFiles(workdir, args) {
             for (const e of entries) {
                 if (skip.has(e))
                     continue;
+                if (!includeHidden && e.startsWith(".") && e !== ".github")
+                    continue;
+                if (excludeRx?.test(e))
+                    continue;
                 const full = join(dir, e);
                 let st;
                 try {
+                    safePath(workdir, relative(workdir, full));
                     st = statSync(full);
                 }
                 catch {
                     continue;
                 }
-                const rel = relative(workdir, full);
+                const rel = relative(workdir, full).split(sep).join("/");
                 if (st.isDirectory()) {
                     out.push(`${rel}/`);
                     walk(full, depth + 1);
@@ -314,6 +441,10 @@ export function toolGrep(workdir, args) {
         if (!pattern)
             return { ok: false, output: "ERROR: pattern is required." };
         const root = safePath(workdir, args.path ?? ".");
+        // v2: context lines + hit cap — before/after look like ripgrep -B/-A.
+        const ctxBefore = Math.min(toPosInt(args.context_before, 0), 20);
+        const ctxAfter = Math.min(toPosInt(args.context_after, 0), 20);
+        const maxResults = Math.min(toPosInt(args.max_results, MAX_SEARCH_HITS), 100);
         // Fast path: ripgrep (respects .gitignore, fast, JSON output). Skip
         // common noise dirs even when the project has no .gitignore.
         const rgArgs = [
@@ -324,22 +455,42 @@ export function toolGrep(workdir, args) {
             "--glob", "!build", "--glob", "!.next", "--glob", "!__pycache__",
             "--glob", "!.venv",
         ];
+        if (ctxBefore > 0)
+            rgArgs.push("-B", String(ctxBefore));
+        if (ctxAfter > 0)
+            rgArgs.push("-A", String(ctxAfter));
         if (args.include)
             rgArgs.push("-g", args.include);
+        if (args.type)
+            rgArgs.push("--type", String(args.type));
         const rg = spawnSync("rg", rgArgs, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
         const lines = [];
         let count = 0;
         if ((rg.status ?? 2) === 0 || rg.stdout) {
+            let prevLine = -1;
+            let prevRel = "";
             for (const line of rg.stdout.split("\n")) {
-                if (!line || count >= MAX_SEARCH_HITS)
+                if (!line)
+                    continue;
+                if (count >= maxResults)
                     break;
                 try {
                     const j = JSON.parse(line);
-                    if (j.type !== "match" || !j.data)
+                    if (!j.data || (j.type !== "match" && j.type !== "context"))
                         continue;
                     const rel = relative(workdir, j.data.path?.text ?? "").split(sep).join("/");
-                    lines.push(`${rel}:${j.data.line_number}: ${(j.data.lines?.text ?? "").trimEnd().slice(0, 200)}`);
-                    count++;
+                    const ln = j.data.line_number ?? 0;
+                    const text = (j.data.lines?.text ?? "").trimEnd().slice(0, 200);
+                    // GNU-style: match lines keep ':' separators, context lines use '-'.
+                    if (rel !== prevRel || (prevLine >= 0 && ln > prevLine + 1)) {
+                        if (lines.length > 0)
+                            lines.push("--");
+                    }
+                    lines.push(`${rel}${j.type === "match" ? ":" : "-"}${ln}${j.type === "match" ? ":" : "-"} ${text}`);
+                    if (j.type === "match")
+                        count++;
+                    prevLine = ln;
+                    prevRel = rel;
                 }
                 catch { /* skip malformed */ }
             }
@@ -349,14 +500,30 @@ export function toolGrep(workdir, args) {
             // status >= 2 → rg error; fall through to grep fallback.
         }
         // Fallback: grep -rn (portable) — output already path:line:text.
-        const g = spawnSync("grep", ["-rn", "--binary-files=without-match", "-I", "-m", "5", "-e", pattern, root], { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+        const gArgs = ["-rn", "--binary-files=without-match", "-I", "-m", "5", "-e", pattern];
+        if (ctxBefore > 0)
+            gArgs.push("-B", String(ctxBefore));
+        if (ctxAfter > 0)
+            gArgs.push("-A", String(ctxAfter));
+        gArgs.push(root);
+        const g = spawnSync("grep", gArgs, { encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
         if ((g.status ?? 2) <= 1) {
-            const hits = (g.stdout ?? "").split("\n").filter(Boolean).slice(0, MAX_SEARCH_HITS)
-                .map((l) => l.startsWith(root) ? relative(workdir, root).split(sep).join("/") + l.slice(root.length) : l);
-            return { ok: true, output: hits.length > 0 ? clamp(hits.join("\n")) : "(no matches)" };
+            const hits = (g.stdout ?? "").split("\n").filter(Boolean);
+            const out = [];
+            let matches = 0;
+            for (const l of hits) {
+                // Context lines GNU-separated with '-'; matches with ':'.
+                const isMatch = /^[^:]*:\d+:/.test(l);
+                if (isMatch && matches >= maxResults)
+                    continue;
+                if (isMatch)
+                    matches++;
+                out.push(l.startsWith(root) ? relative(workdir, root).split(sep).join("/") + l.slice(root.length) : l);
+            }
+            return { ok: true, output: out.length > 0 ? clamp(out.join("\n")) : "(no matches)" };
         }
         // rg vắng mặt + grep vắng mặt/lỗi → scan JS thuần (luôn chạy được, không cần binary).
-        return jsGrepFallback(workdir, root, pattern, args.include);
+        return jsGrepFallback(workdir, root, pattern, args.include, ctxBefore, ctxAfter, maxResults);
     });
 }
 /**
@@ -365,7 +532,7 @@ export function toolGrep(workdir, args) {
  * — quan trọng trên Windows máy chưa cài ripgrep. Pattern là regex JS; regex
  * không hợp lệ → coi như literal substring.
  */
-function jsGrepFallback(workdir, root, pattern, include) {
+function jsGrepFallback(workdir, root, pattern, include, ctxBefore = 0, ctxAfter = 0, maxResults = MAX_SEARCH_HITS) {
     let rx;
     try {
         rx = new RegExp(pattern);
@@ -377,8 +544,9 @@ function jsGrepFallback(workdir, root, pattern, include) {
         ? globToRegExp(include.includes("/") ? include : `**/${include}`)
         : null;
     const hits = [];
+    let matches = 0;
     walkFiles(root, (_name, abs) => {
-        if (hits.length >= MAX_SEARCH_HITS)
+        if (matches >= maxResults)
             return;
         const rel = relative(workdir, abs).split(sep).join("/");
         if (includeRx && !includeRx.test(rel))
@@ -391,11 +559,34 @@ function jsGrepFallback(workdir, root, pattern, include) {
             if (buf.includes(0))
                 return; // skip binary (NUL byte)
             const lines = buf.toString("utf8").split("\n");
-            let perFile = 0;
-            for (let i = 0; i < lines.length && perFile < 5 && hits.length < MAX_SEARCH_HITS; i++) {
-                if (rx.test(lines[i])) {
-                    hits.push(`${rel}:${i + 1}: ${lines[i].trimEnd().slice(0, 200)}`);
-                    perFile++;
+            // Collect matching line numbers, then emit merged windows with context.
+            const matchIdx = [];
+            for (let i = 0; i < lines.length && matchIdx.length < 5; i++) {
+                if (rx.test(lines[i]))
+                    matchIdx.push(i);
+            }
+            if (matchIdx.length === 0)
+                return;
+            // Merge overlapping windows.
+            const windows = [];
+            for (const i of matchIdx) {
+                const lo = Math.max(0, i - ctxBefore), hi = Math.min(lines.length - 1, i + ctxAfter);
+                const last = windows[windows.length - 1];
+                if (last && lo <= last[1] + 1)
+                    last[1] = Math.max(last[1], hi);
+                else
+                    windows.push([lo, hi]);
+            }
+            for (const [lo, hi] of windows) {
+                if (hits.length > 0 && hits[hits.length - 1] !== "--")
+                    hits.push("--");
+                for (let i = lo; i <= hi; i++) {
+                    const isMatch = matchIdx.includes(i);
+                    if (isMatch && matches >= maxResults)
+                        break;
+                    hits.push(`${rel}${isMatch ? ":" : "-"}${i + 1}${isMatch ? ":" : "-"} ${lines[i].trimEnd().slice(0, 200)}`);
+                    if (isMatch)
+                        matches++;
                 }
             }
         }
@@ -645,12 +836,14 @@ export async function toolRunCommand(workdir, args, signal, onOutput, sandbox) {
             signal?.addEventListener("abort", onAbort, { once: true });
         child.stdout?.on("data", (c) => {
             const s = c.toString("utf8");
-            stdout += s;
+            if (stdout.length < MAX_OUTPUT_CHARS)
+                stdout += s.slice(0, MAX_OUTPUT_CHARS - stdout.length);
             onOutput?.("stdout", redactSecrets(s)); // G3
         });
         child.stderr?.on("data", (c) => {
             const s = c.toString("utf8");
-            stderr += s;
+            if (stderr.length < MAX_OUTPUT_CHARS)
+                stderr += s.slice(0, MAX_OUTPUT_CHARS - stderr.length);
             onOutput?.("stderr", redactSecrets(s)); // G3
         });
         child.on("error", (err) => {
@@ -694,6 +887,7 @@ const obj = (properties, required) => ({
     additionalProperties: false,
 });
 const str = (description) => ({ type: "string", description });
+const num = (description) => ({ type: "number", description });
 export const AGENT_TOOLS = [
     {
         spec: {
@@ -701,7 +895,10 @@ export const AGENT_TOOLS = [
             function: {
                 name: "load_skill",
                 description: "Load the full instructions of a named skill from the AVAILABLE SKILLS index (project + global). Call this at the start of a task when it matches a skill, then follow the returned instructions exactly.",
-                parameters: obj({ name: str("Skill name from the AVAILABLE SKILLS index, e.g. 'prompt-gate-workflow'") }, ["name"]),
+                parameters: obj({
+                    name: str("Skill name from the AVAILABLE SKILLS index, e.g. 'prompt-gate-workflow'"),
+                    section: str("Optional section heading to load (progressive disclosure). Omit for full body."),
+                }, ["name"]),
             },
         },
         run: (ctx, args) => {
@@ -713,7 +910,10 @@ export const AGENT_TOOLS = [
                 const names = discoverSkills(ctx.workdir).map((s) => s.name).join(", ");
                 return { ok: false, output: `ERROR: skill "${name}" not found${names ? ` — available: ${names}` : " — no skills discovered"}.` };
             }
-            return { ok: true, output: `# skill: ${skill.name} (${skill.scope})\n\n${skill.body}` };
+            const section = args.section;
+            const body = section ? loadSkillSection(skill, String(section)) : skill.body;
+            const refs = skill.references?.length ? `\n\nReferences: ${skill.references.join(", ")}` : "";
+            return { ok: true, output: `# skill: ${skill.name} (${skill.scope})${skill.version ? ` v${skill.version}` : ""}\n\n${body}${refs}` };
         },
     },
     {
@@ -721,7 +921,8 @@ export const AGENT_TOOLS = [
             type: "function",
             function: {
                 name: "write_todos",
-                description: "Write the full task plan (replaces the previous list). Use at the start of a multi-step task and update as you go: mark items completed IMMEDIATELY after finishing them, set exactly one item in_progress, and add newly discovered steps. The user sees this list live.",
+                description: "Write the full task plan (replaces the previous list). Use at the start of a multi-step task and update as you go: mark items completed IMMEDIATELY after finishing them, set exactly one item in_progress, and add newly discovered steps. " +
+                    "v2: each item may carry verify (how you will know it's done), depends_on (earlier step ids), files (expected paths) and acceptance (criteria). The user sees this list live.",
                 parameters: obj({
                     todos: {
                         type: "array",
@@ -729,8 +930,13 @@ export const AGENT_TOOLS = [
                         items: {
                             type: "object",
                             properties: {
+                                id: { type: "string", description: "Stable step id (e.g. 't1'). Auto-assigned when omitted." },
                                 content: { type: "string", description: "Imperative step, e.g. 'Fix null check in UserService'" },
                                 status: { type: "string", enum: ["pending", "in_progress", "completed"] },
+                                verify: { type: "string", description: "How to verify the step — command or observable behavior" },
+                                depends_on: { type: "array", items: { type: "string" }, description: "Ids of steps that must complete first" },
+                                files: { type: "array", items: { type: "string" }, description: "Files this step is expected to touch" },
+                                acceptance: { type: "string", description: "Criteria for the step to count as done" },
                             },
                             required: ["content", "status"],
                             additionalProperties: false,
@@ -744,18 +950,45 @@ export const AGENT_TOOLS = [
             if (!Array.isArray(todos))
                 return { ok: false, output: "ERROR: todos must be an array of {content, status}." };
             const clean = [];
-            for (const t of todos) {
+            for (const [i, t] of todos.entries()) {
                 if (typeof t?.content !== "string" || !t.content.trim()) {
                     return { ok: false, output: "ERROR: every todo needs a non-empty content string." };
                 }
                 if (!["pending", "in_progress", "completed"].includes(t.status)) {
                     return { ok: false, output: `ERROR: invalid status "${String(t.status)}" (pending|in_progress|completed).` };
                 }
-                clean.push({ content: t.content.trim().slice(0, 200), status: t.status });
+                const item = {
+                    id: typeof t.id === "string" && t.id.trim() ? t.id.trim().slice(0, 32) : `t${i + 1}`,
+                    content: t.content.trim().slice(0, 200),
+                    status: t.status,
+                };
+                if (typeof t.verify === "string" && t.verify.trim())
+                    item.verify = t.verify.trim().slice(0, 300);
+                if (typeof t.acceptance === "string" && t.acceptance.trim())
+                    item.acceptance = t.acceptance.trim().slice(0, 300);
+                if (Array.isArray(t.depends_on))
+                    item.depends_on = t.depends_on.filter((x) => typeof x === "string").slice(0, 10);
+                if (Array.isArray(t.files))
+                    item.files = t.files.filter((x) => typeof x === "string").slice(0, 20);
+                clean.push(item);
+            }
+            // v2 rule: exactly one in_progress at a time.
+            const inProgress = clean.filter((t) => t.status === "in_progress");
+            if (inProgress.length > 1) {
+                return { ok: false, output: `ERROR: exactly one in_progress step allowed (got ${inProgress.length}: ${inProgress.map((t) => t.content).join(" | ")}). Mark the others pending or completed.` };
+            }
+            // v2 rule: depends_on must reference earlier ids in the SAME plan.
+            const ids = new Set(clean.map((t) => t.id));
+            for (const t of clean) {
+                for (const dep of t.depends_on ?? []) {
+                    if (!ids.has(dep))
+                        return { ok: false, output: `ERROR: step "${t.content}" depends_on unknown id "${dep}" — ids in this plan: ${[...ids].join(", ")}` };
+                }
             }
             ctx.plan?.set(clean);
             const done = clean.filter((t) => t.status === "completed").length;
-            return { ok: true, output: `Plan updated: ${done}/${clean.length} completed.` };
+            const next = clean.find((t) => t.status === "in_progress");
+            return { ok: true, output: `Plan updated: ${done}/${clean.length} completed.${next ? ` In progress: ${next.content}` : " (none in progress)"}` };
         },
     },
     {
@@ -763,8 +996,13 @@ export const AGENT_TOOLS = [
             type: "function",
             function: {
                 name: "list_files",
-                description: "List files and directories recursively under a path in the working directory.",
-                parameters: obj({ path: str("Relative path, defaults to '.'") }, []),
+                description: "List files and directories recursively under a path in the working directory. Hidden dotfiles are excluded unless include_hidden=true; pass depth / exclude to shape the output.",
+                parameters: obj({
+                    path: str("Relative path, defaults to '.'"),
+                    depth: num("Max directory depth to recurse (default 4, cap 8)"),
+                    exclude: str("Comma/space-separated globs to exclude, e.g. '*.log,coverage'"),
+                    include_hidden: str("'true' to include dotfiles (default: excluded)"),
+                }, []),
             },
         },
         run: (ctx, args) => toolListFiles(ctx.workdir, args),
@@ -774,8 +1012,12 @@ export const AGENT_TOOLS = [
             type: "function",
             function: {
                 name: "read_file",
-                description: "Read a text file. Returns content with 1-based line numbers. Image files (PNG/JPG/GIF) return an `[image: path]` placeholder rendered inline by the TUI.",
-                parameters: obj({ path: str("Relative file path") }, ["path"]),
+                description: "Read a text file. Returns content with 1-based line numbers. Pass offset (1-based start line) and limit to read a slice instead of the whole file. Image files (PNG/JPG/GIF) return an `[image: path]` placeholder rendered inline by the TUI.",
+                parameters: obj({
+                    path: str("Relative file path"),
+                    offset: num("1-based line to start from (default: 1)"),
+                    limit: num("Max lines to read (default: whole file, capped at 2000)"),
+                }, ["path"]),
             },
         },
         run: (ctx, args) => toolReadFile(ctx.workdir, args),
@@ -796,7 +1038,8 @@ export const AGENT_TOOLS = [
             type: "function",
             function: {
                 name: "edit_file",
-                description: "Replace an exact unique substring in a file. old_string must appear exactly once; include enough surrounding context.",
+                description: "Replace an exact unique substring in a file. old_string must appear exactly once; include enough surrounding context. " +
+                    "For multiple replacements in the same file, use apply_patch (atomic, one write).",
                 parameters: obj({
                     path: str("Relative file path"),
                     old_string: str("Exact text to replace"),
@@ -806,6 +1049,29 @@ export const AGENT_TOOLS = [
         },
         run: (ctx, args) => toolEditFile(ctx, args),
     },
+    {
+        spec: {
+            type: "function",
+            function: {
+                name: "apply_patch",
+                description: "Apply multiple exact replacements to ONE file atomically. Edits run in order; each old_string must match exactly once " +
+                    "in the content produced by the previous edits. If any edit fails, nothing is written. " +
+                    "Use this instead of repeated edit_file calls for multi-hunk changes.",
+                parameters: obj({
+                    path: str("Relative file path"),
+                    edits: {
+                        type: "array",
+                        description: "Ordered list of replacements applied atomically (1–50).",
+                        items: obj({
+                            old_string: str("Exact text to replace (must be unique at its turn)"),
+                            new_string: str("Replacement text"),
+                        }, ["old_string", "new_string"]),
+                    },
+                }, ["path", "edits"]),
+            },
+        },
+        run: (ctx, args) => toolApplyPatch(ctx, args),
+    },
     {
         spec: {
             type: "function",
@@ -814,7 +1080,7 @@ export const AGENT_TOOLS = [
                 description: "Run a shell command in the working directory (sh/bash -c; Windows: Git Bash when installed, else cmd /c). Use for builds, tests, git, installing deps, etc.",
                 parameters: obj({
                     command: str("Shell command to run"),
-                    timeout_secs: str("Timeout in seconds (default 120, max 600)"),
+                    timeout_secs: num("Timeout in seconds (default 120, max 600)"),
                 }, ["command"]),
             },
         },
@@ -846,12 +1112,16 @@ export const AGENT_TOOLS = [
             type: "function",
             function: {
                 name: "grep",
-                description: "Search file contents with a regex (ripgrep-backed, gitignore-aware). Returns path:line:text hits, max 50. " +
-                    "Use for finding code by symbol, error string, or pattern. Combine with read_file for context.",
+                description: "Search file contents with a regex (ripgrep-backed, gitignore-aware). Returns path:line:text hits (max 50 by default), with optional context lines and a hit cap. " +
+                    "Use for finding code by symbol, error string, or pattern. Combine with read_file for full context.",
                 parameters: obj({
                     pattern: str("Regular expression to search for"),
                     path: str("Directory or file to search (default: workdir root)"),
                     include: str("Glob filter for filenames, e.g. '*.ts'"),
+                    context_before: num("Context lines to print before each match (default 0)"),
+                    context_after: num("Context lines to print after each match (default 0)"),
+                    max_results: num("Max matching lines to return (default 50, cap 100)"),
+                    type: str("ripgrep file type filter, e.g. 'ts', 'py' (rg only; ignored by fallbacks)"),
                 }, ["pattern"]),
             },
         },
@@ -872,6 +1142,29 @@ export const AGENT_TOOLS = [
         },
         run: (ctx, args) => toolGlob(ctx.workdir, args),
     },
+    {
+        spec: {
+            type: "function",
+            function: {
+                name: "repo_map",
+                description: "Return the repository map — file tree with sizes + exported symbols (regex-extracted, budget-bounded, cached). " +
+                    "Use to orient before reading files; cheaper than listing/reading everything.",
+                parameters: obj({ path: str("Sub-directory to map (default: repo root)") }, []),
+            },
+        },
+        run: (ctx, args) => {
+            try {
+                const sub = typeof args.path === "string" ? args.path.trim() : "";
+                const out = sub
+                    ? renderRepoMap(ctx.workdir, 4000, sub)
+                    : buildRepoMap(ctx.workdir);
+                return { ok: true, output: out };
+            }
+            catch (err) {
+                return { ok: false, output: `ERROR: repo map failed: ${err.message}` };
+            }
+        },
+    },
 ];
 /** task tool — runner resolved from ctx.taskRunner (per-agent, no global). */
 const taskTool = {
@@ -879,22 +1172,46 @@ const taskTool = {
         type: "function",
         function: {
             name: "task",
-            description: "Delegate a self-contained subtask to a subagent that runs its own agent loop with its own context. " +
+            description: "Delegate self-contained subtasks to subagents that run their own agent loop with their own context. " +
                 "WHEN TO USE: broad codebase exploration (find where X lives, summarize module Y) so the main " +
-                "conversation stays lean, or an independent subtask that needs many steps. " +
-                "The prompt must be self-contained (the subagent sees nothing else); it returns a summary. " +
+                "conversation stays lean, or independent subtasks that need many steps. " +
+                "SINGLE: pass description + prompt. BATCH: pass tasks[] to run up to 8 subtasks concurrently " +
+                "(bounded at 4 in flight) and get one merged result. " +
+                "Every prompt must be self-contained (the subagent sees nothing else); each returns a summary. " +
                 "Prefer this over reading dozens of files yourself.",
             parameters: obj({
-                description: str("One-line summary of the subtask (shown in the UI)"),
-                prompt: str("Self-contained instructions for the subagent, including any file paths and the expected output"),
+                description: str("One-line summary of the subtask (single mode; shown in the UI)"),
+                prompt: str("Self-contained instructions for the subagent (single mode)"),
                 agent: str("Optional agent name from the available agents (default: explore for research, build for changes)"),
-            }, ["description", "prompt"]),
+                tasks: {
+                    type: "array",
+                    description: "Batch mode: up to 8 subtasks run concurrently. When set, description/prompt are ignored.",
+                    items: obj({
+                        description: str("One-line summary of this subtask (shown in the UI)"),
+                        prompt: str("Self-contained instructions for this subagent"),
+                        agent: str("Optional agent name for this subtask"),
+                    }, ["description", "prompt"]),
+                },
+            }, []),
         },
     },
     run: (ctx, args) => {
         if (!ctx.taskRunner)
             return { ok: false, output: "ERROR: task tool not wired (no runner in context)." };
-        return ctx.taskRunner(ctx, args);
+        const a = args;
+        if (Array.isArray(a.tasks) && a.tasks.length > 0) {
+            if (a.tasks.length > 8) {
+                return { ok: false, output: `ERROR: too many tasks (${a.tasks.length}); split into batches of at most 8.` };
+            }
+            const invalid = a.tasks.findIndex((t) => !t || typeof t.prompt !== "string" || !t.prompt.trim());
+            if (invalid >= 0)
+                return { ok: false, output: `ERROR: tasks[${invalid}] is missing a non-empty prompt.` };
+            return ctx.taskRunner(ctx, { tasks: a.tasks });
+        }
+        if (typeof a.prompt !== "string" || !a.prompt.trim()) {
+            return { ok: false, output: "ERROR: task requires a non-empty `prompt` (single mode) or a non-empty `tasks` array (batch mode)." };
+        }
+        return ctx.taskRunner(ctx, a);
     },
 };
 export function getTool(name) {