zidane 2.2.2 → 3.0.1

package/dist/{chunk-O2XZLJMG.js → chunk-QFHGWKK3.js}

@@ -11,13 +11,104 @@ import {
 } from "./chunk-2EQT4EHD.js";
 import {
   connectMcpServers
-} from "./chunk-DRAYZZ23.js";
+} from "./chunk-R74LQKAM.js";
+import {
+  toolOutputByteLength
+} from "./chunk-JH6IAAFA.js";
 import {
   AgentAbortedError,
   AgentProviderError,
   toTypedError
 } from "./chunk-LNN5UTS2.js";
 
+// src/tools/edit-utils.ts
+function countExactMatches(haystack, needle) {
+  if (needle.length === 0)
+    return 0;
+  let count = 0;
+  let idx = 0;
+  while (true) {
+    const next = haystack.indexOf(needle, idx);
+    if (next === -1)
+      break;
+    count++;
+    idx = next + needle.length;
+  }
+  return count;
+}
+
+// src/tools/edit.ts
+var edit = {
+  spec: {
+    name: "edit",
+    description: "Replace exact `old_string` with `new_string` in a file. Fails if `old_string` is not unique unless `replace_all: true`. Prefer over `write_file` for surgical changes \u2014 preserves the rest of the file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative file path." },
+        old_string: { type: "string", description: "Exact substring to find." },
+        new_string: { type: "string", description: "Replacement substring." },
+        replace_all: { type: "boolean", description: "Replace every occurrence. Default: false." }
+      },
+      required: ["path", "old_string", "new_string"]
+    }
+  },
+  async execute({ path, old_string, new_string, replace_all }, ctx) {
+    const target = path;
+    const find = old_string;
+    const replacement = new_string;
+    const replaceAll = replace_all === true;
+    if (find === replacement)
+      return `Edit error: old_string and new_string are identical \u2014 nothing to change in ${target}.`;
+    if (find.length === 0)
+      return `Edit error: old_string is empty. Use write_file to create or fully overwrite a file.`;
+    let original;
+    try {
+      original = await ctx.execution.readFile(ctx.handle, target);
+    } catch {
+      return `Edit error: file not found: ${target}`;
+    }
+    const occurrences = countExactMatches(original, find);
+    if (occurrences === 0) {
+      const preview = nearestMatchPreview(original, find);
+      return preview ? `Edit error: old_string not found in ${target}. Closest match in the file: ${preview}` : `Edit error: old_string not found in ${target}.`;
+    }
+    if (occurrences > 1 && !replaceAll)
+      return `Edit error: old_string appears ${occurrences} times in ${target}. Pass replace_all=true or expand old_string for uniqueness.`;
+    const updated = replaceAll ? original.split(find).join(replacement) : original.replace(find, replacement);
+    if (updated === original)
+      return `Edit error: replacement produced no change in ${target}.`;
+    await ctx.execution.writeFile(ctx.handle, target, updated);
+    return `Edited ${target}: replaced ${occurrences} occurrence${occurrences === 1 ? "" : "s"}.`;
+  }
+};
+function nearestMatchPreview(haystack, needle) {
+  const needleFirstLine = needle.split("\n")[0];
+  if (needleFirstLine.length < 3)
+    return null;
+  const lines = haystack.split("\n");
+  let bestScore = 0;
+  let bestIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const score = sharedPrefixLength(lines[i], needleFirstLine);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIdx = i;
+    }
+  }
+  if (bestIdx < 0 || bestScore < Math.min(8, Math.floor(needleFirstLine.length / 2)))
+    return null;
+  const snippet = lines[bestIdx].slice(0, 80);
+  return `line ${bestIdx + 1}: ${JSON.stringify(snippet)}`;
+}
+function sharedPrefixLength(a, b) {
+  const max = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max && a.charCodeAt(i) === b.charCodeAt(i))
+    i++;
+  return i;
+}
+
 // src/tools/glob.ts
 var DEFAULT_LIMIT = 1e3;
 var SAFE_GLOB_PATTERN_RE = /^[\w./*?[\]{}!,^@+-]+$/;
@@ -74,6 +165,207 @@ var glob = {
   }
 };
 
+// src/tools/grep.ts
+var DEFAULT_HEAD_LIMIT = 250;
+var DEFAULT_OUTPUT_MODE = "files_with_matches";
+var grep = {
+  spec: {
+    name: "grep",
+    description: "Search file contents by regex. Returns matching paths (default), match content, or per-file counts. Backed by ripgrep when available with a Bun.Glob fallback for in-process runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        "pattern": { type: "string", description: "Regex (PCRE-flavored via ripgrep, JS regex via fallback)." },
+        "path": { type: "string", description: 'File or directory to search. Default: ".".' },
+        "glob": { type: "string", description: 'Restrict to files matching this glob, e.g. "**/*.ts".' },
+        "type": { type: "string", description: 'rg file type filter, e.g. "ts", "py", "rust". Ignored by the fallback.' },
+        "output_mode": { type: "string", enum: ["content", "files_with_matches", "count"], description: 'Default: "files_with_matches".' },
+        "-i": { type: "boolean", description: "Case-insensitive match." },
+        "-n": { type: "boolean", description: "Show line numbers (content mode). Default: true." },
+        "-A": { type: "integer", description: "Lines of trailing context (content mode)." },
+        "-B": { type: "integer", description: "Lines of leading context (content mode)." },
+        "-C": { type: "integer", description: "Lines of surrounding context (content mode). Overridden by -A/-B if set." },
+        "multiline": { type: "boolean", description: "Allow patterns to match across line boundaries." },
+        "head_limit": { type: "integer", description: "Cap output entries. Default: 250. Set 0 for unlimited." },
+        "offset": { type: "integer", description: "Skip first N entries. Default: 0." }
+      },
+      required: ["pattern"]
+    }
+  },
+  async execute(rawInput, ctx) {
+    const input = rawInput;
+    const useRg = await isRipgrepAvailable(ctx);
+    if (useRg)
+      return runViaRipgrep(input, ctx);
+    if (ctx.execution.type === "process")
+      return runInProcess(input, ctx);
+    return "grep error: ripgrep is not available in the execution context. Install `rg` or use the `shell` tool with grep/awk.";
+  }
+};
+async function isRipgrepAvailable(ctx) {
+  const result = await ctx.execution.exec(ctx.handle, "rg --version");
+  return result.exitCode === 0;
+}
+async function runViaRipgrep(input, ctx) {
+  const args = ["rg"];
+  const mode = input.output_mode ?? DEFAULT_OUTPUT_MODE;
+  if (mode === "files_with_matches")
+    args.push("--files-with-matches");
+  else if (mode === "count")
+    args.push("--count");
+  else
+    args.push(input["-n"] ?? true ? "--line-number" : "--no-line-number");
+  if (input["-i"])
+    args.push("-i");
+  if (mode === "content") {
+    if (typeof input["-A"] === "number")
+      args.push("-A", String(input["-A"]));
+    if (typeof input["-B"] === "number")
+      args.push("-B", String(input["-B"]));
+    if (typeof input["-C"] === "number" && typeof input["-A"] !== "number" && typeof input["-B"] !== "number")
+      args.push("-C", String(input["-C"]));
+  }
+  if (input.multiline)
+    args.push("--multiline", "--multiline-dotall");
+  if (input.glob)
+    args.push("--glob", input.glob);
+  if (input.type)
+    args.push("--type", input.type);
+  args.push("--", input.pattern);
+  args.push(input.path ?? ".");
+  const command = args.map(shellQuote).join(" ");
+  const result = await ctx.execution.exec(ctx.handle, command);
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    return `grep error: ${result.stderr.trim() || `rg exited with code ${result.exitCode}`}`;
+  }
+  return formatPaginated(result.stdout, input);
+}
+function shellQuote(arg) {
+  if (/^[\w@%+=:,./-]+$/.test(arg))
+    return arg;
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+async function runInProcess(input, ctx) {
+  const mode = input.output_mode ?? DEFAULT_OUTPUT_MODE;
+  const flags = `${input["-i"] ? "i" : ""}${input.multiline ? "s" : ""}${mode !== "content" ? "" : "g"}`;
+  let regex;
+  try {
+    regex = new RegExp(input.pattern, flags || void 0);
+  } catch (err) {
+    return `grep error: invalid regex: ${err.message}`;
+  }
+  const files = await enumerateFiles(input, ctx);
+  const showLineNumbers = input["-n"] ?? true;
+  const before = input["-B"] ?? input["-C"] ?? 0;
+  const after = input["-A"] ?? input["-C"] ?? 0;
+  const lines = [];
+  for (const path of files) {
+    let content;
+    try {
+      content = await ctx.execution.readFile(ctx.handle, path);
+    } catch {
+      continue;
+    }
+    if (input.multiline) {
+      const allMatches = [...content.matchAll(new RegExp(regex.source, `${flags.replace(/g/, "")}g`))];
+      if (allMatches.length === 0)
+        continue;
+      if (mode === "files_with_matches") {
+        lines.push(path);
+        continue;
+      }
+      if (mode === "count") {
+        lines.push(`${path}:${allMatches.length}`);
+        continue;
+      }
+      for (const m of allMatches) {
+        const lineStart = content.lastIndexOf("\n", m.index - 1) + 1;
+        const lineEnd = content.indexOf("\n", m.index);
+        const snippet = content.slice(lineStart, lineEnd === -1 ? void 0 : lineEnd);
+        const lineNo = content.slice(0, m.index).split("\n").length;
+        lines.push(formatContentLine(path, lineNo, snippet, showLineNumbers));
+      }
+      continue;
+    }
+    const fileLines = content.split("\n");
+    const matched = [];
+    for (let i = 0; i < fileLines.length; i++) {
+      regex.lastIndex = 0;
+      if (regex.test(fileLines[i]))
+        matched.push(i);
+    }
+    if (matched.length === 0)
+      continue;
+    if (mode === "files_with_matches") {
+      lines.push(path);
+      continue;
+    }
+    if (mode === "count") {
+      lines.push(`${path}:${matched.length}`);
+      continue;
+    }
+    const includeLineNos = /* @__PURE__ */ new Set();
+    for (const m of matched) {
+      for (let i = Math.max(0, m - before); i <= Math.min(fileLines.length - 1, m + after); i++)
+        includeLineNos.add(i);
+    }
+    const sorted = [...includeLineNos].sort((a, b) => a - b);
+    let prev = -2;
+    for (const lineNo of sorted) {
+      if (lineNo > prev + 1 && lines.length > 0)
+        lines.push("--");
+      const snippet = fileLines[lineNo];
+      lines.push(formatContentLine(path, lineNo + 1, snippet, showLineNumbers));
+      prev = lineNo;
+    }
+  }
+  return formatPaginated(lines.join("\n"), input);
+}
+function formatContentLine(path, lineNo, snippet, showLineNumbers) {
+  return showLineNumbers ? `${path}:${lineNo}:${snippet}` : `${path}:${snippet}`;
+}
+async function enumerateFiles(input, ctx) {
+  const cwd = ctx.handle.cwd;
+  const root = input.path ?? ".";
+  if (input.path && !input.path.includes("*") && !input.path.includes("?")) {
+    try {
+      const stat = await ctx.execution.exec(ctx.handle, `test -f ${shellQuote(input.path)} && echo file || echo dir`);
+      if (stat.stdout.trim() === "file")
+        return [input.path];
+    } catch {
+    }
+  }
+  const pattern = input.glob ?? "**/*";
+  const glob2 = new Bun.Glob(pattern);
+  const out = [];
+  const scanRoot = root === "." ? cwd : `${cwd.replace(/\/$/, "")}/${root.replace(/^\.\//, "")}`;
+  for await (const file of glob2.scan({ cwd: scanRoot, onlyFiles: true })) {
+    out.push(root === "." ? file : `${root.replace(/\/$/, "")}/${file}`);
+  }
+  return out.sort();
+}
+function formatPaginated(text, input) {
+  const headLimit = typeof input.head_limit === "number" && input.head_limit >= 0 ? input.head_limit : DEFAULT_HEAD_LIMIT;
+  const offset = typeof input.offset === "number" && input.offset > 0 ? Math.floor(input.offset) : 0;
+  if (!text.trim())
+    return "(no matches)";
+  const lines = text.split("\n").filter((l) => l.length > 0);
+  const total = lines.length;
+  const sliced = headLimit === 0 ? lines.slice(offset) : lines.slice(offset, offset + headLimit);
+  if (sliced.length === 0)
+    return "(no matches in this slice)";
+  const truncatedHead = offset > 0;
+  const truncatedTail = headLimit > 0 && offset + headLimit < total;
+  let out = sliced.join("\n");
+  if (truncatedHead)
+    out = `\u2026(${offset} earlier matches skipped)\u2026
+${out}`;
+  if (truncatedTail)
+    out = `${out}
+\u2026(${total - offset - headLimit} more matches; re-run with offset=${offset + headLimit} or larger head_limit)`;
+  return out;
+}
+
 // src/tools/interaction.ts
 function createInteractionTool(options) {
   const name = options.name ?? "interaction";
@@ -114,55 +406,251 @@ var listFiles = {
   }
 };
 
+// src/tools/multi-edit.ts
+var multiEdit = {
+  spec: {
+    name: "multi_edit",
+    description: "Apply a sequential list of edits to a file atomically. Each edit operates on the result of the previous edit. All edits must succeed for any to be written. Prefer this over multiple `edit` calls when several non-overlapping changes are needed in the same file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Relative file path." },
+        edits: {
+          type: "array",
+          description: "List of edits applied in order; each operates on the previous edit's output.",
+          items: {
+            type: "object",
+            properties: {
+              old_string: { type: "string" },
+              new_string: { type: "string" },
+              replace_all: { type: "boolean" }
+            },
+            required: ["old_string", "new_string"]
+          }
+        }
+      },
+      required: ["path", "edits"]
+    }
+  },
+  async execute({ path, edits }, ctx) {
+    const target = path;
+    const steps = edits;
+    if (!Array.isArray(steps) || steps.length === 0)
+      return `multi_edit error: edits must be a non-empty array.`;
+    let current;
+    try {
+      current = await ctx.execution.readFile(ctx.handle, target);
+    } catch {
+      return `multi_edit error: file not found: ${target}`;
+    }
+    let applied = 0;
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const find = step.old_string;
+      const replacement = step.new_string;
+      const replaceAll = step.replace_all === true;
+      if (typeof find !== "string" || typeof replacement !== "string")
+        return `multi_edit error: edit #${i + 1} is missing old_string or new_string.`;
+      if (find.length === 0)
+        return `multi_edit error: edit #${i + 1} has empty old_string. Use write_file to fully replace a file.`;
+      if (find === replacement)
+        return `multi_edit error: edit #${i + 1} old_string and new_string are identical.`;
+      const occurrences = countExactMatches(current, find);
+      if (occurrences === 0)
+        return `multi_edit error: edit #${i + 1} old_string not found in ${target}.`;
+      if (occurrences > 1 && !replaceAll)
+        return `multi_edit error: edit #${i + 1} old_string appears ${occurrences} times. Pass replace_all=true on this edit or expand old_string for uniqueness.`;
+      current = replaceAll ? current.split(find).join(replacement) : current.replace(find, replacement);
+      applied += occurrences;
+    }
+    await ctx.execution.writeFile(ctx.handle, target, current);
+    return `Edited ${target}: applied ${steps.length} edit${steps.length === 1 ? "" : "s"} (${applied} replacement${applied === 1 ? "" : "s"}).`;
+  }
+};
+
 // src/tools/read-file.ts
+import { Buffer } from "buffer";
+var DEFAULT_LINE_LIMIT = 2e3;
+var DEFAULT_BYTE_CAP = 65536;
+var BINARY_PROBE_BYTES = 8e3;
 var readFile = {
   spec: {
     name: "read_file",
-    description: "Read the contents of a file at the given path (relative to project root).",
+    description: "Read a file by path. Returns lines [offset..offset+limit). Default offset=1, limit=2000. A trailing footer explains how to read the rest when truncated. Binary files return a short marker rather than mojibake.",
     inputSchema: {
       type: "object",
       properties: {
-        path: { type: "string", description: "Relative file path" }
+        path: { type: "string", description: "Relative file path." },
+        offset: { type: "integer", description: "1-indexed line number to start from. Default: 1." },
+        limit: { type: "integer", description: "Max lines to return. Default: 2000. Set 0 for unlimited." },
+        maxBytes: { type: "integer", description: "Hard byte cap regardless of line count. Default: 65536. Set 0 for unlimited." }
       },
       required: ["path"]
     }
   },
-  async execute({ path }, ctx) {
+  async execute({ path, offset, limit, maxBytes }, ctx) {
+    let raw;
     try {
-      return await ctx.execution.readFile(ctx.handle, path);
+      raw = await ctx.execution.readFile(ctx.handle, path);
     } catch {
       return `File not found: ${path}`;
     }
+    const totalBytes = Buffer.byteLength(raw);
+    if (looksBinary(raw)) {
+      return `[binary file: ${path}, ${totalBytes} bytes; use shell with hexdump | xxd | od to inspect]`;
+    }
+    const offsetN = normalizeInteger(offset, 1);
+    const limitN = normalizeInteger(limit, DEFAULT_LINE_LIMIT);
+    const maxBytesN = normalizeInteger(maxBytes, DEFAULT_BYTE_CAP);
+    const lines = raw.split("\n");
+    const totalLines = lines.length;
+    const startIdx = Math.max(0, offsetN - 1);
+    const endIdx = limitN > 0 ? Math.min(totalLines, startIdx + limitN) : totalLines;
+    let slice = lines.slice(startIdx, endIdx);
+    let bytesUsed = 0;
+    let bytesCut = false;
+    if (maxBytesN > 0) {
+      const truncatedSlice = [];
+      for (const line of slice) {
+        const lineBytes = Buffer.byteLength(line) + 1;
+        if (bytesUsed + lineBytes > maxBytesN && truncatedSlice.length > 0) {
+          bytesCut = true;
+          break;
+        }
+        truncatedSlice.push(line);
+        bytesUsed += lineBytes;
+        if (bytesUsed >= maxBytesN) {
+          break;
+        }
+      }
+      if (truncatedSlice.length < slice.length)
+        bytesCut = true;
+      slice = truncatedSlice;
+    }
+    let midLineCut = false;
+    if (maxBytesN > 0 && slice.length > 0) {
+      const bodyBytes = Buffer.byteLength(slice.join("\n"));
+      if (bodyBytes > maxBytesN) {
+        const lastIdx = slice.length - 1;
+        const lastLine = slice[lastIdx];
+        const otherBytes = lastIdx > 0 ? Buffer.byteLength(slice.slice(0, lastIdx).join("\n")) + 1 : 0;
+        const budgetForLast = Math.max(0, maxBytesN - otherBytes);
+        let cut = Math.min(lastLine.length, budgetForLast);
+        while (cut > 0 && Buffer.byteLength(lastLine.slice(0, cut)) > budgetForLast)
+          cut--;
+        slice[lastIdx] = lastLine.slice(0, cut);
+        midLineCut = true;
+        bytesCut = true;
+      }
+    }
+    const body = slice.join("\n");
+    const linesReturned = slice.length;
+    const lastLineRead = startIdx + linesReturned;
+    const linesTruncated = endIdx < totalLines || bytesCut;
+    if (!linesTruncated && offsetN === 1)
+      return body;
+    if (!linesTruncated) {
+      return `${body}
+
+\u2026read lines ${offsetN}-${lastLineRead} of ${totalLines}.`;
+    }
+    if (midLineCut) {
+      return `${body}
+
+\u2026truncated mid-line at line ${lastLineRead} (byte cap ${maxBytesN} reached). File has ${totalLines} lines, ${totalBytes} bytes total. Raise maxBytes, or use shell with sed/awk to read the remainder of this line.`;
+    }
+    const reason = bytesCut ? `byte cap (${maxBytesN}) reached` : `line limit (${limitN}) reached`;
+    return `${body}
+
+\u2026truncated at line ${lastLineRead} (${reason}). File has ${totalLines} lines, ${totalBytes} bytes total \u2014 re-read with offset=${lastLineRead + 1} to continue.`;
   }
 };
+function normalizeInteger(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    return fallback;
+  if (value < 0)
+    return fallback;
+  return Math.floor(value);
+}
+var REPLACEMENT_RATIO_THRESHOLD = 0.01;
+var REPLACEMENT_MIN_COUNT = 5;
+function looksBinary(text) {
+  const sample = text.length > BINARY_PROBE_BYTES ? text.slice(0, BINARY_PROBE_BYTES) : text;
+  if (sample.includes("\0"))
+    return true;
+  if (sample.length === 0)
+    return false;
+  let replacementCount = 0;
+  for (let i = 0; i < sample.length; i++) {
+    if (sample.charCodeAt(i) === 65533)
+      replacementCount++;
+  }
+  return replacementCount >= REPLACEMENT_MIN_COUNT && replacementCount / sample.length > REPLACEMENT_RATIO_THRESHOLD;
+}
 
 // src/tools/shell.ts
+import { Buffer as Buffer2 } from "buffer";
+var DEFAULT_MAX_OUTPUT_BYTES = 8192;
 var shell = {
   spec: {
     name: "shell",
-    description: "Execute a shell command and return stdout+stderr. Runs in the project root.",
+    description: "Execute a shell command in the project root and return its combined stdout/stderr. Output is tail-priority truncated at 8 KB by default; errors and exit-code summaries live in the tail. Set maxOutputBytes=0 to disable truncation.",
     inputSchema: {
       type: "object",
       properties: {
-        command: { type: "string", description: "The shell command to run" }
+        command: { type: "string", description: "Shell command to run." },
+        timeout: { type: "integer", description: "Per-call timeout in milliseconds." },
+        maxOutputBytes: { type: "integer", description: "Truncate combined stdout+stderr beyond this many bytes. Default: 8192. Set 0 for unlimited." }
       },
       required: ["command"]
     }
   },
-  async execute({ command }, ctx) {
-    const result = await ctx.execution.exec(ctx.handle, command);
-    if (result.exitCode === 0) {
-      return result.stdout || "(no output)";
-    }
-    return `Exit code ${result.exitCode}
-${result.stdout}
+  async execute({ command, timeout, maxOutputBytes }, ctx) {
+    const execOpts = {};
+    if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0)
+      execOpts.timeout = Math.max(1, Math.ceil(timeout / 1e3));
+    const result = await ctx.execution.exec(ctx.handle, command, execOpts);
+    const cap = normalizeCap(maxOutputBytes);
+    if (result.exitCode === 0)
+      return truncateTail(result.stdout || "(no output)", cap);
+    const combined = `${result.stdout}
 ${result.stderr}`.trim();
+    return `Exit code ${result.exitCode}
+${truncateTail(combined, cap)}`;
   }
 };
+function normalizeCap(value) {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    return DEFAULT_MAX_OUTPUT_BYTES;
+  if (value < 0)
+    return DEFAULT_MAX_OUTPUT_BYTES;
+  return Math.floor(value);
+}
+function truncateTail(text, cap) {
+  if (cap === 0)
+    return text;
+  const totalBytes = Buffer2.byteLength(text);
+  if (totalBytes <= cap)
+    return text;
+  let bytes = 0;
+  let charIdx = text.length;
+  while (charIdx > 0) {
+    const ch = text[charIdx - 1];
+    const chBytes = Buffer2.byteLength(ch);
+    if (bytes + chBytes > cap)
+      break;
+    bytes += chBytes;
+    charIdx--;
+  }
+  const tail = text.slice(charIdx);
+  const droppedBytes = totalBytes - Buffer2.byteLength(tail);
+  return `\u2026(${droppedBytes} bytes truncated from head)\u2026
+${tail}`;
+}
 
 // src/tools/skills-read.ts
 var SNIFF_BYTES = 8192;
-function looksBinary(text) {
+function looksBinary2(text) {
   const len = Math.min(text.length, SNIFF_BYTES);
   for (let i = 0; i < len; i++) {
     if (text.charCodeAt(i) === 0)
@@ -214,7 +702,7 @@ function createSkillsReadTool(options) {
         const message = err instanceof Error ? err.message : String(err);
         return `Error reading "${relPath}" in skill "${skillName}": ${message}`;
       }
-      if (looksBinary(content)) {
+      if (looksBinary2(content)) {
         return JSON.stringify({
           kind: "binary-unsupported",
           path: validated.absolutePath,
@@ -456,14 +944,156 @@ function rewriteMessagesToWire(messages, maps) {
 }
 
 // src/tools/validation.ts
+var TRUE_STRINGS = /* @__PURE__ */ new Set(["true", "True", "TRUE", "1", "yes", "Yes", "YES"]);
+var FALSE_STRINGS = /* @__PURE__ */ new Set(["false", "False", "FALSE", "0", "no", "No", "NO"]);
 function validateToolArgs(input, schema) {
   const required = schema.required ?? [];
+  const properties = schema.properties ?? {};
   for (const field of required) {
     if (!(field in input) || input[field] === void 0 || input[field] === null) {
       return { valid: false, error: `Missing required field: ${field}` };
     }
   }
-  return { valid: true };
+  let coerced;
+  const coercions = [];
+  for (const [key, value] of Object.entries(input)) {
+    const propSchema = properties[key];
+    if (!propSchema?.type)
+      continue;
+    if (value === void 0 || value === null)
+      continue;
+    const outcome = coerceValue(value, propSchema);
+    if (outcome.error) {
+      return { valid: false, error: `Field "${key}": ${outcome.error}` };
+    }
+    if (outcome.changed) {
+      if (!coerced)
+        coerced = { ...input };
+      coerced[key] = outcome.value;
+      coercions.push(key);
+    }
+  }
+  return {
+    valid: true,
+    coercedInput: coerced ?? input,
+    coercions
+  };
+}
+function coerceValue(value, schema) {
+  const declaredTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
+  for (const t of declaredTypes) {
+    if (matchesType(value, t)) {
+      if (schema.enum && !schema.enum.includes(value)) {
+        return {
+          value,
+          changed: false,
+          error: `must be one of ${JSON.stringify(schema.enum)}, got ${formatValue(value)}`
+        };
+      }
+      return { value, changed: false };
+    }
+  }
+  for (const t of declaredTypes) {
+    const coerced = tryCoerce(value, t);
+    if (coerced.ok) {
+      if (schema.enum && !schema.enum.includes(coerced.value)) {
+        return {
+          value,
+          changed: false,
+          error: `must be one of ${JSON.stringify(schema.enum)}, got ${formatValue(coerced.value)}`
+        };
+      }
+      return { value: coerced.value, changed: true };
+    }
+  }
+  const expected = declaredTypes.join(" | ");
+  return {
+    value,
+    changed: false,
+    error: `expected ${expected}, got ${jsonType(value)} ${formatValue(value)}`
+  };
+}
+function matchesType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "null":
+      return value === null;
+    default:
+      return true;
+  }
+}
+function tryCoerce(value, type) {
+  if (typeof value === "string") {
+    if (type === "boolean") {
+      const trimmed = value.trim();
+      if (TRUE_STRINGS.has(trimmed))
+        return { ok: true, value: true };
+      if (FALSE_STRINGS.has(trimmed))
+        return { ok: true, value: false };
+      return { ok: false };
+    }
+    if (type === "number") {
+      const n = Number(value.trim());
+      return Number.isFinite(n) ? { ok: true, value: n } : { ok: false };
+    }
+    if (type === "integer") {
+      const n = Number(value.trim());
+      return Number.isInteger(n) ? { ok: true, value: n } : { ok: false };
+    }
+    if (type === "array" || type === "object") {
+      try {
+        const parsed = JSON.parse(value);
+        if (type === "array" && Array.isArray(parsed))
+          return { ok: true, value: parsed };
+        if (type === "object" && parsed !== null && typeof parsed === "object" && !Array.isArray(parsed))
+          return { ok: true, value: parsed };
+        return { ok: false };
+      } catch {
+        return { ok: false };
+      }
+    }
+    if (type === "null") {
+      return value === "" || value === "null" ? { ok: true, value: null } : { ok: false };
+    }
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (type === "string")
+      return { ok: true, value: String(value) };
+    if (type === "integer" && Number.isInteger(value))
+      return { ok: true, value };
+  }
+  if (typeof value === "boolean" && type === "string")
+    return { ok: true, value: String(value) };
+  return { ok: false };
+}
+function jsonType(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function formatValue(value) {
+  let s;
+  try {
+    s = JSON.stringify(value);
+  } catch {
+    s = String(value);
+  }
+  if (s === void 0)
+    s = String(value);
+  return s.length > 80 ? `${s.slice(0, 77)}...` : s;
 }
 
 // src/loop.ts
@@ -716,6 +1346,29 @@ async function executeTurn(ctx, turn) {
     content: toolResultMsg.content,
     createdAt: Date.now()
   });
+  if (typeof ctx.toolOutputBudget === "number" && ctx.toolOutputBudget > 0) {
+    const totalBytes = toolResults.reduce(
+      (sum, r) => sum + toolOutputByteLength(r.content),
+      0
+    );
+    if (totalBytes > ctx.toolOutputBudget) {
+      const warning = `[Tool output budget exceeded: ${totalBytes} bytes returned in this turn (cap: ${ctx.toolOutputBudget}). Summarize the salient findings before calling more tools.]`;
+      const userMsg = ctx.provider.userMessage(warning);
+      ctx.turns.push({
+        id: await ctx.generateTurnId(),
+        runId: ctx.runId,
+        role: userMsg.role,
+        content: userMsg.content,
+        createdAt: Date.now()
+      });
+      await ctx.hooks.callHook("budget:exceeded", {
+        turn,
+        turnId,
+        bytes: totalBytes,
+        budget: ctx.toolOutputBudget
+      });
+    }
+  }
   return { ended: false, turnId, usage: result.usage };
 }
 function stripImagesForNonVision(provider, output) {
@@ -742,29 +1395,64 @@ async function executeSingleTool(ctx, call, turnId) {
   if (gateCtx.block) {
     return { result: { id: callId, content: `Blocked: ${gateCtx.reason}` } };
   }
-  const effectiveInput = gateCtx.input;
+  let effectiveInput = gateCtx.input;
   if (!toolDef) {
-    const err = new Error(`Unknown tool: ${call.name}`);
-    await ctx.hooks.callHook("tool:error", {
+    const unknownCtx = {
       turnId,
       callId,
       name: call.name,
       displayName,
       input: effectiveInput,
-      error: err
-    });
-    return { result: { id: callId, content: `Tool error: ${err.message}` } };
+      suppressError: false
+    };
+    await ctx.hooks.callHook("tool:unknown", unknownCtx);
+    const content = unknownCtx.result ?? `Tool error: Unknown tool: ${call.name}`;
+    if (!unknownCtx.suppressError) {
+      const err = new Error(`Unknown tool: ${call.name}`);
+      await ctx.hooks.callHook("tool:error", {
+        turnId,
+        callId,
+        name: call.name,
+        displayName,
+        input: effectiveInput,
+        error: err
+      });
+    }
+    return { result: { id: callId, content } };
   }
   const validation = validateToolArgs(effectiveInput, toolDef.spec.inputSchema);
   if (!validation.valid) {
+    await ctx.hooks.callHook("validation:reject", {
+      turnId,
+      callId,
+      name: call.name,
+      displayName,
+      input: effectiveInput,
+      reason: validation.error ?? "invalid input",
+      schema: toolDef.spec.inputSchema
+    });
     return { result: { id: callId, content: `Validation error: ${validation.error}` } };
   }
+  effectiveInput = validation.coercedInput ?? effectiveInput;
+  const coercions = validation.coercions && validation.coercions.length > 0 ? validation.coercions : void 0;
+  if (coercions) {
+    await ctx.hooks.callHook("validation:coerce", {
+      turnId,
+      callId,
+      name: call.name,
+      displayName,
+      input: effectiveInput,
+      coercions,
+      schema: toolDef.spec.inputSchema
+    });
+  }
   await ctx.hooks.callHook("tool:before", {
     turnId,
     callId,
     name: call.name,
     displayName,
-    input: effectiveInput
+    input: effectiveInput,
+    ...coercions ? { coercions } : {}
   });
   let output;
   let isError = false;
@@ -809,7 +1497,9 @@ async function executeSingleTool(ctx, call, turnId) {
     displayName,
     input: effectiveInput,
     result: output,
-    isError
+    isError,
+    outputBytes: toolOutputByteLength(output),
+    ...coercions ? { coercions } : {}
   };
   await ctx.hooks.callHook("tool:transform", transformCtx);
   output = transformCtx.result;
@@ -821,7 +1511,9 @@ async function executeSingleTool(ctx, call, turnId) {
     name: call.name,
     displayName,
     input: effectiveInput,
-    result: output
+    result: output,
+    outputBytes: toolOutputByteLength(output),
+    ...coercions ? { coercions } : {}
   });
   return { result: { id: callId, content: output } };
 }
@@ -946,6 +1638,9 @@ var HOOK_EVENT_NAMES = [
   "tool:after",
   "tool:error",
   "tool:transform",
+  "tool:unknown",
+  "validation:reject",
+  "validation:coerce",
   "context:transform",
   "steer:inject",
   "spawn:before",
@@ -974,6 +1669,7 @@ var HOOK_EVENT_NAMES = [
   "skills:deactivate",
   "usage",
   "output",
+  "budget:exceeded",
   "agent:abort",
   "agent:done",
   "session:start",
@@ -993,7 +1689,8 @@ function resolveBehavior(agentBehavior, runBehavior) {
     maxTokens: runBehavior?.maxTokens ?? agentBehavior?.maxTokens,
     thinkingBudget: runBehavior?.thinkingBudget ?? agentBehavior?.thinkingBudget,
     schema: runBehavior?.schema ?? agentBehavior?.schema,
-    cache: runBehavior?.cache ?? agentBehavior?.cache ?? true
+    cache: runBehavior?.cache ?? agentBehavior?.cache ?? true,
+    toolOutputBudget: runBehavior?.toolOutputBudget ?? agentBehavior?.toolOutputBudget
   };
 }
 function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }) {
@@ -1116,7 +1813,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
     }
     const thinking = options.thinking ?? "off";
     const model = options.model ?? provider.meta.defaultModel;
-    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache } = resolveBehavior(agentBehavior, options.behavior);
+    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget } = resolveBehavior(agentBehavior, options.behavior);
     let system = options.system || agentSystem || "You are a helpful assistant.";
     if (skillsCatalog) {
       system = `${system}
@@ -1251,6 +1948,7 @@ ${skillsCatalog}`;
         thinkingBudget,
         schema,
         cache,
+        toolOutputBudget,
         runStartMs
       });
       const finalStats = {
@@ -1546,7 +2244,7 @@ function createSpawnTool(options = {}) {
     },
     spec: {
       name: "spawn",
-      description: "Spawn a sub-agent to work on a specific task. The sub-agent runs independently with its own tool access and returns its final response. Use this to delegate work, parallelize tasks, or isolate concerns.",
+      description: "Spawn a sub-agent for a self-contained task that benefits from isolation (separate context window, separate retries) \u2014 for example, a deep research dive or a long codegen pass on a specific file. The sub-agent runs independently with its own tool access and returns its final response. Do NOT spawn for sequential steps you could do yourself.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1695,22 +2393,33 @@ function createSpawnTool(options = {}) {
 var spawn = createSpawnTool();
 
 // src/tools/write-file.ts
+import { Buffer as Buffer3 } from "buffer";
 var writeFile = {
   spec: {
     name: "write_file",
-    description: "Write content to a file. Creates parent directories if needed.",
+    description: 'Write content to a file (creates parent directories). Returns Created / Updated / "No change needed" so the model can detect no-ops without a separate read.',
     inputSchema: {
       type: "object",
       properties: {
-        path: { type: "string", description: "Relative file path" },
-        content: { type: "string", description: "File content to write" }
+        path: { type: "string", description: "Relative file path." },
+        content: { type: "string", description: "File content." }
       },
       required: ["path", "content"]
     }
   },
   async execute({ path, content }, ctx) {
-    await ctx.execution.writeFile(ctx.handle, path, content);
-    return `Wrote ${content.length} bytes to ${path}`;
+    const targetPath = path;
+    const targetContent = content;
+    let existing;
+    try {
+      existing = await ctx.execution.readFile(ctx.handle, targetPath);
+    } catch {
+    }
+    const bytes = Buffer3.byteLength(targetContent);
+    if (existing === targetContent)
+      return `No change needed: ${targetPath} already at target state (${bytes} bytes).`;
+    await ctx.execution.writeFile(ctx.handle, targetPath, targetContent);
+    return existing === void 0 ? `Created ${targetPath} (${bytes} bytes).` : `Updated ${targetPath} (${bytes} bytes).`;
   }
 };
 
@@ -1720,9 +2429,12 @@ export {
   createSkillsRunScriptTool,
   createSkillsUseTool,
   createAgent,
+  edit,
   glob,
+  grep,
   createInteractionTool,
   listFiles,
+  multiEdit,
   readFile,
   shell,
   createSpawnTool,