skyloom 1.17.0 → 1.18.0

package/src/core/search.ts

@@ -0,0 +1,138 @@
+/**
+ * Code search — a dependency-light, cross-platform engine for "find where X is
+ * used and read it in context". Backs the code_search tool and is the fallback
+ * for grep when ripgrep/grep aren't installed (common on Windows), so search
+ * never silently returns nothing just because a binary is missing.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { globSync } from 'glob';
+
+export interface SearchOptions {
+  pattern: string;
+  /** Root directory to search (default: cwd). */
+  root?: string;
+  /** Glob to restrict files (e.g. "**\/*.ts"). Default: all files. */
+  glob?: string;
+  /** Case-insensitive match (default false). */
+  ignoreCase?: boolean;
+  /** Treat pattern as a regular expression (default true). */
+  regex?: boolean;
+  /** Lines of context around each match (default 0). */
+  context?: number;
+  /** Cap on total matches returned (default 200). */
+  maxResults?: number;
+  /** Skip files larger than this many bytes (default 2 MiB). */
+  maxFileBytes?: number;
+}
+
+export interface SearchMatch {
+  file: string;     // relative to root
+  line: number;     // 1-based
+  text: string;
+  before?: string[];
+  after?: string[];
+}
+
+export interface SearchResult {
+  matches: SearchMatch[];
+  filesScanned: number;
+  truncated: boolean;
+  error?: string;
+}
+
+/** Directories never worth searching — vendored, generated, or VCS internals. */
+const DEFAULT_IGNORES = [
+  '**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**',
+  '**/coverage/**', '**/.next/**', '**/out/**', '**/.cache/**',
+  '**/vendor/**', '**/.venv/**', '**/__pycache__/**',
+];
+
+function looksBinary(buf: Buffer): boolean {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true; // NUL byte ⇒ binary
+  return false;
+}
+
+/** Pure-JS recursive code search. No external process required. */
+export function searchCode(opts: SearchOptions): SearchResult {
+  const root = path.resolve(opts.root || process.cwd());
+  const maxResults = opts.maxResults ?? 200;
+  const maxFileBytes = opts.maxFileBytes ?? 2 * 1024 * 1024;
+  const context = Math.max(0, opts.context ?? 0);
+
+  let matcher: (line: string) => boolean;
+  if (opts.regex === false) {
+    const needle = opts.ignoreCase ? opts.pattern.toLowerCase() : opts.pattern;
+    matcher = (line) => (opts.ignoreCase ? line.toLowerCase() : line).includes(needle);
+  } else {
+    let re: RegExp;
+    try {
+      re = new RegExp(opts.pattern, opts.ignoreCase ? 'i' : '');
+    } catch (e) {
+      return { matches: [], filesScanned: 0, truncated: false, error: `invalid regex: ${e}` };
+    }
+    matcher = (line) => re.test(line);
+  }
+
+  let files: string[];
+  try {
+    files = globSync(opts.glob || '**/*', {
+      cwd: root, nodir: true, dot: false, ignore: DEFAULT_IGNORES,
+    });
+  } catch (e) {
+    return { matches: [], filesScanned: 0, truncated: false, error: `glob failed: ${e}` };
+  }
+
+  const matches: SearchMatch[] = [];
+  let filesScanned = 0;
+  let truncated = false;
+
+  for (const rel of files) {
+    if (matches.length >= maxResults) { truncated = true; break; }
+    const abs = path.join(root, rel);
+    let buf: Buffer;
+    try {
+      const stat = fs.statSync(abs);
+      if (stat.size > maxFileBytes) continue;
+      buf = fs.readFileSync(abs);
+    } catch { continue; }
+    if (looksBinary(buf)) continue;
+
+    filesScanned++;
+    const lines = buf.toString('utf8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (!matcher(lines[i])) continue;
+      const m: SearchMatch = { file: rel.split(path.sep).join('/'), line: i + 1, text: lines[i] };
+      if (context > 0) {
+        m.before = lines.slice(Math.max(0, i - context), i);
+        m.after = lines.slice(i + 1, i + 1 + context);
+      }
+      matches.push(m);
+      if (matches.length >= maxResults) { truncated = true; break; }
+    }
+  }
+
+  return { matches, filesScanned, truncated };
+}
+
+/** Render a SearchResult as ripgrep-style `file:line:text` (with context). */
+export function formatSearchResult(res: SearchResult): string {
+  if (res.error) return `Search error: ${res.error}`;
+  if (res.matches.length === 0) return 'No matches found.';
+  const out: string[] = [];
+  let lastFile = '';
+  for (const m of res.matches) {
+    if (m.file !== lastFile) { if (out.length) out.push(''); lastFile = m.file; }
+    for (let k = 0; k < (m.before?.length || 0); k++) {
+      out.push(`${m.file}:${m.line - (m.before!.length - k)}- ${m.before![k]}`);
+    }
+    out.push(`${m.file}:${m.line}: ${m.text}`);
+    for (let k = 0; k < (m.after?.length || 0); k++) {
+      out.push(`${m.file}:${m.line + k + 1}- ${m.after![k]}`);
+    }
+  }
+  if (res.truncated) out.push(`\n…[results truncated at ${res.matches.length} matches — narrow the pattern or glob]`);
+  return out.join('\n');
+}

package/src/core/security.ts

@@ -77,6 +77,7 @@ const TOOL_DANGER_MAP: Record<string, DangerLevel> = {
 
   write_file: DangerLevel.LOW,
   edit_file: DangerLevel.LOW,
+  apply_patch: DangerLevel.LOW,
   copy_file: DangerLevel.LOW,
   move_file: DangerLevel.LOW,
   make_directory: DangerLevel.LOW,
@@ -164,7 +165,7 @@ export const PERMISSION_MODE_ALIASES: Record<string, ApprovalMode> = {
 };
 
 /** Tools that mutate the filesystem — the ones acceptEdits waves through. */
-const EDIT_TOOL_RE = /^(write_|edit_|append_|replace_|create_|make_|copy_|move_|delete_)/;
+const EDIT_TOOL_RE = /^(write_|edit_|append_|replace_|create_|make_|copy_|move_|delete_)|^apply_patch$/;
 export function isEditTool(toolName: string): boolean { return EDIT_TOOL_RE.test(toolName); }
 
 /**

package/src/core/tool.ts

@@ -46,6 +46,14 @@ export interface ToolDefinition {
    */
   idempotent?: boolean;
   timeout?: number;
+  /**
+   * Optional output guard: inspect the handler's result and return an error
+   * message if it's not valid (else null/undefined). A non-null return makes
+   * the call fail — routed through the same retry + circuit-breaker path as a
+   * thrown error — so a tool/plugin can reject malformed output instead of
+   * passing garbage back to the model as "success".
+   */
+  validateOutput?: (result: string, params: Record<string, unknown>) => string | null | undefined;
 }
 
 /** Order-stable JSON key so {a,b} and {b,a} hash to the same cache/dedup key. */
@@ -430,6 +438,13 @@ export class ToolRegistry extends EventEmitter {
           if (timer) clearTimeout(timer);
         }
 
+        // Output guard: a non-null message means the result is invalid. Throw so
+        // it flows through the same retry + breaker path as any other failure.
+        if (tool.validateOutput) {
+          const outErr = tool.validateOutput(result, params);
+          if (outErr) throw new Error(`invalid tool output: ${outErr}`);
+        }
+
         const duration = Date.now() - startTime;
 
         // Cache result

package/src/tools/builtin.ts

@@ -12,6 +12,8 @@ import { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck } from './guards
 import { webSearch, formatSearchResults, readPage } from './websearch';
 import { countOccurrences, unifiedDiff } from '../core/diff';
 import { getDiagnostics, formatDiagnostics } from '../core/diagnostics';
+import { searchCode, formatSearchResult } from '../core/search';
+import { applyPatch } from '../core/patch';
 
 // Re-exported so existing importers/tests keep resolving these from builtin.
 export { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck };
@@ -142,6 +144,30 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
     },
   });
 
+  registry.register({
+    name: 'apply_patch',
+    description: 'Apply an atomic, multi-file edit in one call — ideal for larger refactors touching several places/files. The whole patch is validated before anything is written, so a bad block aborts cleanly with no half-applied changes. Each SEARCH must match the file exactly and uniquely. Format:\n*** Update File: path\n<<<<<<< SEARCH\nold exact text\n=======\nnew text\n>>>>>>> REPLACE\n(repeat blocks; also *** Add File: path / full content, and *** Delete File: path)',
+    parameters: [
+      { name: 'patch', type: 'string', description: 'The patch text in the *** Update/Add/Delete File + SEARCH/REPLACE format', required: true },
+    ],
+    handler: async (params) => {
+      let snapshot: ((abs: string) => void) | undefined;
+      try {
+        const { getFileCheckpoints } = require('../core/file_checkpoint');
+        const cp = getFileCheckpoints();
+        snapshot = (abs: string) => { try { cp.snapshot(abs); } catch { /* best-effort */ } };
+      } catch { /* checkpointing optional */ }
+      try {
+        return applyPatch(String(params.patch || ''), {
+          fenceCheck: (abs: string) => fenceCheck(abs),
+          snapshot,
+        });
+      } catch (e) {
+        return `Error applying patch: ${e}`;
+      }
+    },
+  });
+
   registry.register({
     name: 'delete_file',
     description: 'Delete a file at the given path.',
@@ -470,10 +496,39 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
 
   // ── Utility Tools ──
 
+  registry.register({
+    name: 'code_search',
+    idempotent: true,
+    description: 'Search source code for a regex pattern across files. Returns file:line matches with optional surrounding context. Use this to find where a symbol/string is defined or used. Restrict scope with glob (e.g. "**/*.ts") and add context lines to read around hits.',
+    parameters: [
+      { name: 'pattern', type: 'string', description: 'Regex (or literal if regex=false) to search for', required: true },
+      { name: 'path', type: 'string', description: 'Root directory to search (default: cwd)', required: false },
+      { name: 'glob', type: 'string', description: 'Restrict to files matching this glob, e.g. "**/*.ts"', required: false },
+      { name: 'context', type: 'number', description: 'Lines of context around each match (default 0)', required: false },
+      { name: 'ignore_case', type: 'boolean', description: 'Case-insensitive match (default false)', required: false },
+      { name: 'regex', type: 'boolean', description: 'Treat pattern as regex (default true; false = literal substring)', required: false },
+      { name: 'max_results', type: 'number', description: 'Max matches to return (default 200)', required: false },
+    ],
+    handler: async (params) => {
+      const root = params.path ? path.resolve(params.path as string) : process.cwd();
+      const fenced = fenceCheck(root); if (fenced) return fenced;
+      const res = searchCode({
+        pattern: String(params.pattern || ''),
+        root,
+        glob: params.glob ? String(params.glob) : undefined,
+        context: params.context != null ? Number(params.context) : 0,
+        ignoreCase: params.ignore_case === true,
+        regex: params.regex !== false,
+        maxResults: params.max_results != null ? Number(params.max_results) : 200,
+      });
+      return formatSearchResult(res);
+    },
+  });
+
   registry.register({
     name: 'grep',
     idempotent: true,
-    description: 'Search for a pattern in files using ripgrep or grep.',
+    description: 'Search for a regex pattern in files using ripgrep/grep, with a built-in fallback when neither is installed. For richer control (glob, context, ignore-case) prefer code_search.',
     parameters: [
       { name: 'pattern', type: 'string', description: 'Regex pattern to search for', required: true },
       { name: 'path', type: 'string', description: 'Directory to search in', required: false },
@@ -496,12 +551,13 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
           const out = execFileSync(bin, args, { encoding: 'utf-8', maxBuffer: 1024 * 1024 });
           return out || 'No matches found.';
         } catch (e: any) {
-          // exit status 1 = ran successfully, zero matches; anything else
-          // (e.g. binary not installed) falls through to the next variant.
+          // exit status 1 = ran successfully, zero matches. Any other failure
+          // (e.g. binary not installed) falls through to the next variant, then
+          // to the pure-JS engine so search works even with no rg/grep.
           if (e?.status === 1) return 'No matches found.';
         }
       }
-      return 'No matches found.';
+      return formatSearchResult(searchCode({ pattern: pat, root: searchDir, maxResults: 200 }));
     },
   });
 

package/tests/patch.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { parsePatch, applyPatch } from "../src/core/patch";
+
+describe("patch · parsePatch", () => {
+  it("parses update / add / delete operations", () => {
+    const text = [
+      "*** Begin Patch",
+      "*** Update File: a.ts",
+      "<<<<<<< SEARCH",
+      "const x = 1;",
+      "=======",
+      "const x = 2;",
+      ">>>>>>> REPLACE",
+      "*** Add File: b.ts",
+      "export const y = 3;",
+      "*** Delete File: c.ts",
+      "*** End Patch",
+    ].join("\n");
+    const r = parsePatch(text) as any;
+    expect(r.error).toBeUndefined();
+    expect(r.ops).toHaveLength(3);
+    expect(r.ops[0]).toMatchObject({ op: "update", path: "a.ts" });
+    expect(r.ops[0].blocks[0]).toEqual({ search: "const x = 1;", replace: "const x = 2;" });
+    expect(r.ops[1]).toMatchObject({ op: "add", path: "b.ts", content: "export const y = 3;\n" });
+    expect(r.ops[2]).toMatchObject({ op: "delete", path: "c.ts" });
+  });
+
+  it("errors on an unterminated SEARCH", () => {
+    const text = "*** Update File: a.ts\n<<<<<<< SEARCH\nfoo\n";
+    expect((parsePatch(text) as any).error).toContain("Unterminated SEARCH");
+  });
+
+  it("errors on stray content outside a file section", () => {
+    expect((parsePatch("hello world") as any).error).toContain("Unexpected line");
+  });
+});
+
+describe("patch · applyPatch (atomic, multi-file)", () => {
+  let dir: string;
+  beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), "sky-patch-")); });
+  afterEach(() => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+  function write(name: string, content: string) {
+    const p = path.join(dir, name);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+  }
+  const read = (name: string) => fs.readFileSync(path.join(dir, name), "utf8");
+
+  it("applies update + add + delete in one shot", () => {
+    write("a.ts", "const x = 1;\nkeep me\n");
+    write("c.ts", "delete me\n");
+    const patch = [
+      "*** Update File: a.ts",
+      "<<<<<<< SEARCH",
+      "const x = 1;",
+      "=======",
+      "const x = 42;",
+      ">>>>>>> REPLACE",
+      "*** Add File: sub/b.ts",
+      "export const y = 3;",
+      "*** Delete File: c.ts",
+    ].join("\n");
+    const out = applyPatch(patch, { cwd: dir });
+    expect(out).toContain("Applied patch");
+    expect(read("a.ts")).toBe("const x = 42;\nkeep me\n");
+    expect(read("sub/b.ts")).toBe("export const y = 3;\n");
+    expect(fs.existsSync(path.join(dir, "c.ts"))).toBe(false);
+  });
+
+  it("applies multiple blocks to one file", () => {
+    write("m.ts", "alpha\nbeta\ngamma\n");
+    const patch = [
+      "*** Update File: m.ts",
+      "<<<<<<< SEARCH", "alpha", "=======", "ALPHA", ">>>>>>> REPLACE",
+      "<<<<<<< SEARCH", "gamma", "=======", "GAMMA", ">>>>>>> REPLACE",
+    ].join("\n");
+    applyPatch(patch, { cwd: dir });
+    expect(read("m.ts")).toBe("ALPHA\nbeta\nGAMMA\n");
+  });
+
+  it("is atomic: a failing block leaves ALL files untouched", () => {
+    write("a.ts", "good\n");
+    write("b.ts", "target\n");
+    const patch = [
+      "*** Update File: a.ts",
+      "<<<<<<< SEARCH", "good", "=======", "changed", ">>>>>>> REPLACE",
+      "*** Update File: b.ts",
+      "<<<<<<< SEARCH", "NOT THERE", "=======", "x", ">>>>>>> REPLACE",
+    ].join("\n");
+    const out = applyPatch(patch, { cwd: dir });
+    expect(out).toContain("SEARCH block not found");
+    expect(read("a.ts")).toBe("good\n");   // first file NOT written
+    expect(read("b.ts")).toBe("target\n");
+  });
+
+  it("rejects an ambiguous SEARCH block", () => {
+    write("d.ts", "dup\ndup\n");
+    const patch = ["*** Update File: d.ts", "<<<<<<< SEARCH", "dup", "=======", "x", ">>>>>>> REPLACE"].join("\n");
+    expect(applyPatch(patch, { cwd: dir })).toContain("ambiguous");
+  });
+
+  it("refuses to Add over an existing file", () => {
+    write("exists.ts", "already\n");
+    const patch = "*** Add File: exists.ts\nnew content\n";
+    const out = applyPatch(patch, { cwd: dir });
+    expect(out).toContain("already exists");
+    expect(read("exists.ts")).toBe("already\n");
+  });
+
+  it("treats $-patterns in replacement literally", () => {
+    write("e.ts", "VAL\n");
+    const patch = ["*** Update File: e.ts", "<<<<<<< SEARCH", "VAL", "=======", "$1$&x", ">>>>>>> REPLACE"].join("\n");
+    applyPatch(patch, { cwd: dir });
+    expect(read("e.ts")).toBe("$1$&x\n");
+  });
+
+  it("honors the fence check by aborting", () => {
+    write("a.ts", "good\n");
+    const patch = ["*** Update File: a.ts", "<<<<<<< SEARCH", "good", "=======", "bad", ">>>>>>> REPLACE"].join("\n");
+    const out = applyPatch(patch, { cwd: dir, fenceCheck: () => "路径越界" });
+    expect(out).toContain("路径越界");
+    expect(read("a.ts")).toBe("good\n");
+  });
+});

package/tests/protocol.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { engineeringProtocol } from "../src/core/protocol";
+
+describe("protocol · engineeringProtocol", () => {
+  it("zh protocol covers the senior-engineer discipline and names real tools", () => {
+    const p = engineeringProtocol("zh");
+    expect(p).toContain("工程标准");
+    expect(p).toContain("根因");          // root-cause, not symptom
+    expect(p).toContain("最小");          // minimal diffs
+    expect(p).toContain("先理解");        // understand before changing
+    expect(p).toContain("get_diagnostics"); // verify loop wired to real tool
+    expect(p).toContain("code_search");
+  });
+
+  it("en protocol mirrors the zh one", () => {
+    const p = engineeringProtocol("en");
+    expect(p).toContain("Engineering Standard");
+    expect(p).toContain("Root cause");
+    expect(p).toContain("Minimal");
+    expect(p).toContain("get_diagnostics");
+    expect(p).toContain("code_search");
+  });
+
+  it("defaults to zh", () => {
+    expect(engineeringProtocol()).toBe(engineeringProtocol("zh"));
+  });
+});

package/tests/search.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { searchCode, formatSearchResult } from "../src/core/search";
+
+describe("search · searchCode (pure JS)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "sky-search-"));
+    fs.writeFileSync(path.join(root, "a.ts"), "const Foo = 1;\nexport function useFoo() { return Foo; }\n");
+    fs.writeFileSync(path.join(root, "b.js"), "// foo lower\nconst x = 2;\n");
+    fs.mkdirSync(path.join(root, "sub"));
+    fs.writeFileSync(path.join(root, "sub", "c.ts"), "import { useFoo } from '../a';\n");
+    // should be ignored by default
+    fs.mkdirSync(path.join(root, "node_modules", "dep"), { recursive: true });
+    fs.writeFileSync(path.join(root, "node_modules", "dep", "x.ts"), "const Foo = 999;\n");
+  });
+  afterEach(() => { try { fs.rmSync(root, { recursive: true, force: true }); } catch {} });
+
+  it("finds matches with file:line", () => {
+    const res = searchCode({ pattern: "useFoo", root });
+    const files = res.matches.map((m) => m.file).sort();
+    expect(files).toContain("a.ts");
+    expect(files).toContain("sub/c.ts");
+    const a = res.matches.find((m) => m.file === "a.ts")!;
+    expect(a.line).toBe(2);
+    expect(a.text).toContain("useFoo");
+  });
+
+  it("skips node_modules by default", () => {
+    const res = searchCode({ pattern: "Foo", root });
+    expect(res.matches.some((m) => m.file.includes("node_modules"))).toBe(false);
+  });
+
+  it("restricts by glob", () => {
+    const res = searchCode({ pattern: "foo", root, glob: "**/*.ts", ignoreCase: true });
+    expect(res.matches.some((m) => m.file === "b.js")).toBe(false);
+    expect(res.matches.some((m) => m.file === "a.ts")).toBe(true);
+  });
+
+  it("honors ignoreCase", () => {
+    // b.js contains lowercase "foo"; capital "Foo" only matches case-insensitively.
+    expect(searchCode({ pattern: "Foo", root, glob: "b.js" }).matches.length).toBe(0);
+    expect(searchCode({ pattern: "Foo", root, glob: "b.js", ignoreCase: true }).matches.length).toBe(1);
+  });
+
+  it("returns context lines", () => {
+    const res = searchCode({ pattern: "useFoo", root, glob: "a.ts", context: 1 });
+    const m = res.matches[0];
+    expect(m.before).toEqual(["const Foo = 1;"]);
+  });
+
+  it("treats pattern as literal when regex=false", () => {
+    fs.writeFileSync(path.join(root, "d.ts"), "a.b.c\n");
+    const asRegex = searchCode({ pattern: "a.b", root, glob: "d.ts" });          // '.' = any char
+    const literal = searchCode({ pattern: "a.b", root, glob: "d.ts", regex: false });
+    expect(asRegex.matches.length).toBe(1);
+    expect(literal.matches.length).toBe(1);
+    const noLit = searchCode({ pattern: "axb", root, glob: "d.ts", regex: false });
+    expect(noLit.matches.length).toBe(0);
+  });
+
+  it("caps results and flags truncation", () => {
+    fs.writeFileSync(path.join(root, "many.ts"), Array.from({ length: 50 }, () => "hit").join("\n"));
+    const res = searchCode({ pattern: "hit", root, glob: "many.ts", maxResults: 10 });
+    expect(res.matches.length).toBe(10);
+    expect(res.truncated).toBe(true);
+  });
+
+  it("reports an invalid regex instead of throwing", () => {
+    const res = searchCode({ pattern: "(", root });
+    expect(res.error).toContain("invalid regex");
+  });
+});
+
+describe("search · formatSearchResult", () => {
+  it("renders file:line and a no-match message", () => {
+    expect(formatSearchResult({ matches: [], filesScanned: 3, truncated: false })).toBe("No matches found.");
+    const s = formatSearchResult({
+      matches: [{ file: "a.ts", line: 2, text: "  return Foo;" }],
+      filesScanned: 1, truncated: false,
+    });
+    expect(s).toContain("a.ts:2:");
+    expect(s).toContain("return Foo");
+  });
+});

package/tests/tool.test.ts

@@ -16,6 +16,7 @@ function makeTool(overrides: Partial<ToolDefinition> & { name: string }): ToolDe
     maxRetries: overrides.maxRetries,
     retryDelay: overrides.retryDelay,
     timeout: overrides.timeout,
+    validateOutput: overrides.validateOutput,
   };
 }
 
@@ -184,6 +185,49 @@ describe('ToolRegistry · input validation + coercion', () => {
   });
 });
 
+describe('ToolRegistry · output validation', () => {
+  let registry: ToolRegistry;
+  beforeEach(() => { registry = new ToolRegistry(); });
+
+  it('fails the call when validateOutput rejects the result', async () => {
+    registry.register(makeTool({
+      name: 'guarded',
+      maxRetries: 0,
+      handler: async () => 'garbage',
+      validateOutput: (r) => (r === 'garbage' ? 'looks like garbage' : null),
+    }));
+    const res = await registry.execute('guarded', {});
+    expect(res.success).toBe(false);
+    expect(res.error).toContain('invalid tool output');
+    expect(res.error).toContain('looks like garbage');
+  });
+
+  it('passes when validateOutput accepts the result', async () => {
+    registry.register(makeTool({
+      name: 'ok',
+      handler: async () => 'fine',
+      validateOutput: () => null,
+    }));
+    const res = await registry.execute('ok', {});
+    expect(res.success).toBe(true);
+    expect(res.result).toBe('fine');
+  });
+
+  it('retries a rejected output through the normal retry path', async () => {
+    let n = 0;
+    registry.register(makeTool({
+      name: 'retryout',
+      maxRetries: 1,
+      retryDelay: 0,
+      handler: async () => `v${++n}`,
+      validateOutput: (r) => (r === 'v1' ? 'first is bad' : null),
+    }));
+    const res = await registry.execute('retryout', {});
+    expect(res.success).toBe(true);
+    expect(res.result).toBe('v2');
+  });
+});
+
 describe('stableStringify', () => {
   it('produces an order-independent key for objects', async () => {
     const { stableStringify } = await import('../src/core/tool');