@wrongstack/tools 0.305.1 → 0.306.0

package/dist/codebase-index/codebase-search-tool.d.ts

@@ -17,6 +17,11 @@
  */
 import type { Tool } from '@wrongstack/core/types';
 import type { SearchResult } from './schema.js';
+/**
+ * Language ids the index understands. Single source for the `lang` enum here
+ * and the `langs` validation in codebase-index-tool.ts.
+ */
+export declare const INDEXABLE_LANG_IDS: readonly ['ts', 'tsx', 'js', 'jsx', 'go', 'py', 'rs', 'json', 'yaml'];
 export declare const codebaseSearchTool: Tool<CodebaseSearchInput, CodebaseSearchOutput>;
 interface CodebaseSearchInput {
     query: string;

package/dist/codebase-index/index.js

@@ -8491,6 +8491,160 @@ function ensureCodebaseIndexServer(options) {
 }
 
 // src/codebase-index/codebase-index-tool.ts
+import { ToolValidationError } from "@wrongstack/core/types";
+
+// src/codebase-index/codebase-search-tool.ts
+import { toErrorMessage as toErrorMessage2 } from "@wrongstack/core/utils";
+var INDEXABLE_LANG_IDS = [
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+  "go",
+  "py",
+  "rs",
+  "json",
+  "yaml"
+];
+var codebaseSearchTool = {
+  name: "codebase-search",
+  category: "Project",
+  icon: "index",
+  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Use `grep` instead for exact text, regexes, unsupported content, or concrete usage sites. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
+  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.",
+  permission: "auto",
+  mutating: false,
+  capabilities: ["fs.read"],
+  // The index host has its own 30s read watchdog. Leave enough headroom for
+  // worker teardown and structured timeout reporting.
+  timeoutMs: 35e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query \u2014 searches symbol names, signatures, and doc comments"
+      },
+      kind: {
+        type: "string",
+        enum: [
+          "class",
+          "interface",
+          "enum",
+          "type",
+          "function",
+          "method",
+          "var",
+          "const",
+          "let",
+          "property",
+          "parameter",
+          "namespace",
+          "object",
+          "literal",
+          "schema",
+          "struct",
+          "trait",
+          "impl",
+          "static",
+          "mod"
+        ],
+        description: "Filter by indexed symbol kind"
+      },
+      lang: {
+        type: "string",
+        enum: [...INDEXABLE_LANG_IDS],
+        description: "Filter by indexed language"
+      },
+      lspKind: {
+        type: "integer",
+        description: "Filter by LSP SymbolKind number (e.g. 5=Class, 12=Function, 11=Interface, 10=Enum)"
+      },
+      file: {
+        type: "string",
+        description: "Filter to files matching this path substring"
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum results to return (default 20, max 100)",
+        minimum: 1,
+        maximum: 100
+      },
+      preferLsp: {
+        type: "boolean",
+        description: "Prefer live LSP results over the index. Ignored unless the LSP plugin is active; when it is active and this is true, results come from live workspaceSymbol queries."
+      }
+    },
+    required: ["query"]
+  },
+  async execute(input, ctx, execOpts) {
+    const state = getIndexState();
+    if (state.indexing && !state.ready) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
+      };
+    }
+    if (state.lastError) {
+      const circuit = state.circuit;
+      const retryHint = circuit.state === "open" ? `Indexing is paused (circuit open, retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s); the user can run /codebase-reindex to retry now.` : "Try /codebase-reindex.";
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
+      };
+    }
+    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
+    let searched;
+    try {
+      searched = await searchCodebaseIndex(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          query: input.query,
+          kind: input.kind?.toLowerCase(),
+          lang: input.lang?.toLowerCase(),
+          file: input.file,
+          lspKind: input.lspKind,
+          limit
+        },
+        { signal: execOpts?.signal }
+      );
+    } catch (err) {
+      if (execOpts?.signal?.aborted) throw err;
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index query failed: ${toErrorMessage2(err)}. Fall back to grep/glob for this lookup.`
+      };
+    }
+    const { results, total } = searched;
+    let hasPersistedIndex = state.ready || total > 0;
+    if (!hasPersistedIndex) {
+      try {
+        const stats = await codebaseIndexStats(
+          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
+          { signal: execOpts?.signal }
+        );
+        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
+      } catch {
+      }
+    }
+    return {
+      results,
+      total,
+      query: input.query,
+      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
+    };
+  }
+};
+
+// src/codebase-index/codebase-index-tool.ts
+var MAX_REPORTED_ERRORS = 20;
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
@@ -8516,12 +8670,23 @@ var codebaseIndexTool = {
       },
       langs: {
         type: "array",
-        items: { type: "string" },
-        description: "Limit reindex to specific languages: ts, tsx, js, jsx, go, py, rs"
+        items: { type: "string", enum: [...INDEXABLE_LANG_IDS] },
+        description: `Limit reindex to specific languages: ${INDEXABLE_LANG_IDS.join(", ")}`
       }
     }
   },
   async execute(input, ctx, execOpts) {
+    if (input.langs) {
+      const unknown = input.langs.filter(
+        (lang) => !INDEXABLE_LANG_IDS.includes(lang)
+      );
+      if (unknown.length > 0) {
+        throw new ToolValidationError({
+          message: `codebase-index: unknown lang(s) ${unknown.map((l) => `"${l}"`).join(", ")}. Valid ids: ${INDEXABLE_LANG_IDS.join(", ")}.`,
+          field: "langs"
+        });
+      }
+    }
     if (isIndexing()) {
       return {
         filesIndexed: 0,
@@ -8543,23 +8708,32 @@ var codebaseIndexTool = {
         note: `Codebase indexing is paused after repeated failures (last: ${circuit.lastFailure ?? "unknown"}). Auto-retry possible in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s; the user can run /codebase-reindex to retry immediately.`
       };
     }
-    return await runStartupIndex({
+    const result = await runStartupIndex({
       projectRoot: ctx.projectRoot,
       force: input.force ?? false,
       langs: input.langs,
       indexDir: codebaseIndexDirOverride(ctx),
       signal: execOpts?.signal
     });
+    if (result.errors.length > MAX_REPORTED_ERRORS) {
+      const hidden = result.errors.length - MAX_REPORTED_ERRORS;
+      return {
+        ...result,
+        errors: [...result.errors.slice(0, MAX_REPORTED_ERRORS), `+${hidden} more`]
+      };
+    }
+    return result;
   }
 };
 
 // src/codebase-index/codebase-incoming-calls-tool.ts
+import { toErrorMessage as toErrorMessage3 } from "@wrongstack/core/utils";
 var codebaseIncomingCallsTool = {
   name: "codebase-incoming-calls",
   category: "Project",
   icon: "index",
-  description: "Find all callers of a function, method, or symbol \u2014 who invokes or references it. Uses the codebase index ref graph for instant, exact results. Always use this instead of grep when checking impact of a change.",
-  usageHint: 'CALL THIS BEFORE REFACTORING OR CHANGING ANY FUNCTION:\n\n- NEVER use grep or manual line reading to check where a function is called.\n- ALWAYS call codebase-incoming-calls({ symbol: "funcName" }) first.\n- Returns exact files, line numbers, caller signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Combine with codebase-outgoing-calls to see what the symbol itself calls.\nIf the index is not built, run codebase-index first.',
+  description: "Find all callers of a function, method, or symbol \u2014 who invokes or references it. Uses the codebase index ref graph for instant, exact results. Prefer this over grep for change-impact checks when the index is available.",
+  usageHint: 'CALL THIS BEFORE REFACTORING OR CHANGING ANY FUNCTION:\n\n- Prefer this over grep when the index is available; fall back to grep when the index is cold/unavailable or for dynamic dispatch the ref graph cannot see.\n- Call codebase-incoming-calls({ symbol: "funcName" }) before editing the symbol.\n- Returns exact files, line numbers, caller signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Combine with codebase-outgoing-calls to see what the symbol itself calls.\nIf the index is not built, run codebase-index first.',
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8611,16 +8785,27 @@ var codebaseIncomingCallsTool = {
     }
     const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 50), 200));
     const transitive = input.transitive === true;
-    const { calls, symbolFound, ambiguous, totalMatches } = await incomingCallsService2(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
+    let serviced;
+    try {
+      serviced = await incomingCallsService2(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          symbol: input.symbol,
+          file: input.file,
+          limit,
+          transitive
+        }
+      );
+    } catch (err) {
+      return {
         symbol: input.symbol,
-        file: input.file,
-        limit,
-        transitive
-      }
-    );
+        calls: [],
+        total: 0,
+        indexStatus: `Index query failed: ${toErrorMessage3(err)}. Fall back to grep for this lookup.`
+      };
+    }
+    const { calls, symbolFound, ambiguous, totalMatches } = serviced;
     if (!symbolFound) {
       let hasPersistedIndex = state.ready;
       if (!hasPersistedIndex) {
@@ -8665,12 +8850,13 @@ var codebaseIncomingCallsTool = {
 };
 
 // src/codebase-index/codebase-outgoing-calls-tool.ts
+import { toErrorMessage as toErrorMessage4 } from "@wrongstack/core/utils";
 var codebaseOutgoingCallsTool = {
   name: "codebase-outgoing-calls",
   category: "Project",
   icon: "index",
   description: "Find all functions/methods/symbols that a given symbol calls or depends on \u2014 its callees. Uses the codebase index ref graph for instant, exact results. Use this to understand a function's dependencies before modifying it.",
-  usageHint: 'USE THIS TO UNDERSTAND A FUNCTION\'S DEPENDENCIES:\n\n- Call codebase-outgoing-calls({ symbol: "funcName" }) to see everything it calls.\n- Returns exact files, line numbers, callee signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Pair with codebase-incoming-calls for a complete impact picture: incoming = who calls you, outgoing = what you call.\nIf the index is not built, run codebase-index first.',
+  usageHint: 'USE THIS TO UNDERSTAND A FUNCTION\'S DEPENDENCIES:\n\n- Prefer this over grep when the index is available; fall back to grep when the index is cold/unavailable or for dynamic dispatch the ref graph cannot see.\n- Call codebase-outgoing-calls({ symbol: "funcName" }) to see everything it calls.\n- Returns exact files, line numbers, callee signatures, and call types in milliseconds.\n- Use `file` to disambiguate when multiple symbols share a name.\n- Pair with codebase-incoming-calls for a complete impact picture: incoming = who calls you, outgoing = what you call.\nIf the index is not built, run codebase-index first.',
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8722,16 +8908,27 @@ var codebaseOutgoingCallsTool = {
     }
     const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 50), 200));
     const transitive = input.transitive === true;
-    const { calls, symbolFound, unresolvedCount, totalMatches } = await outgoingCallsService2(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
+    let serviced;
+    try {
+      serviced = await outgoingCallsService2(
+        {
+          projectRoot: ctx.projectRoot,
+          indexDir: codebaseIndexDirOverride(ctx),
+          symbol: input.symbol,
+          file: input.file,
+          limit,
+          transitive
+        }
+      );
+    } catch (err) {
+      return {
         symbol: input.symbol,
-        file: input.file,
-        limit,
-        transitive
-      }
-    );
+        calls: [],
+        total: 0,
+        indexStatus: `Index query failed: ${toErrorMessage4(err)}. Fall back to grep for this lookup.`
+      };
+    }
+    const { calls, symbolFound, unresolvedCount, totalMatches } = serviced;
     if (!symbolFound) {
       let hasPersistedIndex = state.ready;
       if (!hasPersistedIndex) {
@@ -8775,132 +8972,6 @@ var codebaseOutgoingCallsTool = {
   }
 };
 
-// src/codebase-index/codebase-search-tool.ts
-var codebaseSearchTool = {
-  name: "codebase-search",
-  category: "Project",
-  icon: "index",
-  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Prefer this before broad `tree`, `glob`, or `grep` exploration when finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
-  usageHint: "FIRST CHOICE FOR INDEXABLE CODE UNDERSTANDING:\n\n- Call before broad `tree`, `glob`, or `grep` exploration when locating symbols, concepts, definitions, or candidate modules.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\n- If `indexStatus` reports no persisted data, run `codebase-index` and retry.\nUse `grep` afterwards for exact text, regexes, unsupported content, or concrete usage sites.",
-  permission: "auto",
-  mutating: false,
-  capabilities: ["fs.read"],
-  // The index host has its own 30s read watchdog. Leave enough headroom for
-  // worker teardown and structured timeout reporting.
-  timeoutMs: 35e3,
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: "Search query \u2014 searches symbol names, signatures, and doc comments"
-      },
-      kind: {
-        type: "string",
-        enum: [
-          "class",
-          "interface",
-          "enum",
-          "type",
-          "function",
-          "method",
-          "var",
-          "const",
-          "let",
-          "property",
-          "parameter",
-          "namespace",
-          "object",
-          "literal",
-          "schema",
-          "struct",
-          "trait",
-          "impl",
-          "static",
-          "mod"
-        ],
-        description: "Filter by indexed symbol kind"
-      },
-      lang: {
-        type: "string",
-        enum: ["ts", "tsx", "js", "jsx", "go", "py", "rs", "json", "yaml"],
-        description: "Filter by indexed language"
-      },
-      lspKind: {
-        type: "integer",
-        description: "Filter by LSP SymbolKind number (e.g. 5=Class, 12=Function, 11=Interface, 10=Enum)"
-      },
-      file: {
-        type: "string",
-        description: "Filter to files matching this path substring"
-      },
-      limit: {
-        type: "integer",
-        description: "Maximum results to return (default 20, max 100)",
-        minimum: 1,
-        maximum: 100
-      },
-      preferLsp: {
-        type: "boolean",
-        description: "Prefer live LSP results over the index. Index-only when the LSP plugin is not active. When the LSP plugin is active and this is true, results come from live workspaceSymbol queries."
-      }
-    },
-    required: ["query"]
-  },
-  async execute(input, ctx, execOpts) {
-    const state = getIndexState();
-    if (state.indexing && !state.ready) {
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.`
-      };
-    }
-    if (state.lastError) {
-      const circuit = state.circuit;
-      const retryHint = circuit.state === "open" ? `Indexing is paused (circuit open, retry in ${Math.ceil(circuit.cooldownRemainingMs / 1e3)}s); the user can run /codebase-reindex to retry now.` : "Try /codebase-reindex.";
-      return {
-        results: [],
-        total: 0,
-        query: input.query,
-        indexStatus: `Index build failed: ${state.lastError}. ${retryHint}`
-      };
-    }
-    const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 20), 100));
-    const { results, total } = await searchCodebaseIndex(
-      {
-        projectRoot: ctx.projectRoot,
-        indexDir: codebaseIndexDirOverride(ctx),
-        query: input.query,
-        kind: input.kind?.toLowerCase(),
-        lang: input.lang?.toLowerCase(),
-        file: input.file,
-        lspKind: input.lspKind,
-        limit
-      },
-      { signal: execOpts?.signal }
-    );
-    let hasPersistedIndex = state.ready || total > 0;
-    if (!hasPersistedIndex) {
-      try {
-        const stats = await codebaseIndexStats(
-          { projectRoot: ctx.projectRoot, indexDir: codebaseIndexDirOverride(ctx) },
-          { signal: execOpts?.signal }
-        );
-        hasPersistedIndex = stats.totalFiles > 0 || stats.lastIndexed !== null;
-      } catch {
-      }
-    }
-    return {
-      results,
-      total,
-      query: input.query,
-      ...hasPersistedIndex ? {} : { indexStatus: "No persisted index data found. Run codebase-index to build it." }
-    };
-  }
-};
-
 // src/codebase-index/codebase-stats-tool.ts
 var codebaseStatsTool = {
   name: "codebase-stats",
@@ -8994,9 +9065,9 @@ import * as path14 from "node:path";
 var deadCodeScanTool = {
   name: "dead-code-scan",
   category: "Project",
-  icon: "search",
+  icon: "index",
   description: "Scan TypeScript/JavaScript source files for exported symbols that appear unused anywhere in the project. Uses the codebase-index reference graph (import/call/type-ref edges) to compute transitive reachability from package.json entry points. Requires a built codebase-index (run `codebase-index` first if you get no results).",
-  usageHint: 'PASS `path` TO SCOPE THE SCAN:\n\n- Defaults to the project root (all indexed files).\n- `path` can be a directory to scope the scan (e.g. "src/util/").\n- `entryPoints` overrides auto-detected entry points (comma-separated file paths).\n\nThe scan runs against the existing index; results are best-effort.',
+  usageHint: "SCANS ALL INDEXED FILES UNDER THE PROJECT ROOT:\n\n- `projectRoot` defaults to the current project root; `indexDir` overrides the resolved index location.\n- `entryPoints` is an array of file paths that AUGMENTS the auto-discovered entry points (package.json bin/main/exports/types plus conventional src/index.ts-style files) \u2014 it does not replace them.\n\nThe scan runs against the existing index; results are best-effort (dynamic imports, external consumers, and config-driven registration are invisible).",
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],

package/dist/diff.d.ts

@@ -12,7 +12,12 @@ interface DiffOutput {
     diff: string;
     files: string[];
     truncated: boolean;
+    /**
+     * The format actually produced: 'unified' or 'stat' on the git path,
+     * 'dump' on the files-only line-numbered dump path.
+     */
     mode: string;
+    note?: string | undefined;
 }
 export declare const diffTool: Tool<DiffInput, DiffOutput>;
 export {};

package/dist/diff.js

@@ -4,8 +4,10 @@ import { statSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path2 from "node:path";
 import { buildChildEnv } from "@wrongstack/core/utils";
+import { ToolValidationError } from "@wrongstack/core/types";
 
 // src/_util.ts
+import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import * as Core from "@wrongstack/core/utils";
 function resolvePath(input, ctx) {
@@ -29,14 +31,48 @@ function ensureInsideRoot(absPath, ctx) {
 function safeResolve(input, ctx) {
   return ensureInsideRoot(resolvePath(input, ctx), ctx);
 }
+async function resolveRealInsideRoot(absPath, ctx) {
+  if (ctx.allowOutsideProjectRoot) return absPath;
+  const realRoots = await Promise.all(
+    allowedRoots(ctx).map((r) => fsp.realpath(r).catch(() => path.resolve(r)))
+  );
+  let probe = absPath;
+  const pendingTail = [];
+  for (; ; ) {
+    let real;
+    try {
+      real = await fsp.realpath(probe);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const parent = path.dirname(probe);
+        if (parent === probe) return absPath;
+        pendingTail.unshift(path.basename(probe));
+        probe = parent;
+        continue;
+      }
+      throw err;
+    }
+    if (isInsideAny(real, realRoots)) {
+      return pendingTail.length > 0 ? path.join(real, ...pendingTail) : real;
+    }
+    throw new Error(
+      `Path "${absPath}" resolves through a symlink outside project root "${realRoots[0]}"`
+    );
+  }
+}
+async function safeResolveReal(input, ctx) {
+  const abs = safeResolve(input, ctx);
+  return await resolveRealInsideRoot(abs, ctx);
+}
 
 // src/diff.ts
 var MAX_FILE_DUMP_BYTES = 5 * 1024 * 1024;
+var MAX_GIT_DIFF_CHARS = 1e5;
 var diffTool = {
   name: "diff",
   category: "Filesystem",
   description: "Show file content with line numbers, staged/working-tree diffs via git, or commit/branch diffs. A safer and more structured alternative to raw `git diff` via shell.",
-  usageHint: 'USE FOR CODE REVIEW AND CHANGE INSPECTION:\n\n- `files` + no `a`/`b` \u2192 show file content with line numbers (NOT a unified diff; no +/- prefixes).\n- `a` and/or `b` \u2192 git-style commit/branch diff (unified format, real +/- prefixes).\n- `staged: true` \u2192 only show staged changes.\n- `mode` can be "unified", "stat", or "side-by-side" (only affects the git-diff path).\n\nNOTE: For a true file-vs-file unified diff, supply `a` and `b` so the tool delegates to `git diff`. The `files`-only path is a line-numbered dump, not a diff.\n\nThis tool has important safety guards against flag injection (see previous security findings).',
+  usageHint: 'USE FOR CODE REVIEW AND CHANGE INSPECTION:\n\n- `files` + no `a`/`b` \u2192 show file content with line numbers (NOT a unified diff; no +/- prefixes). Result `mode` is "dump".\n- `a` and/or `b` \u2192 git-style commit/branch diff (unified format, real +/- prefixes).\n- `staged: true` \u2192 only show staged changes.\n- `mode` only affects the git-diff path: "stat" runs `git diff --stat`; "side-by-side" is not supported and falls back to unified (result `mode` reports what was produced).\n- `context` sets the unified-diff context line count on the git path (`-U<n>`); the dump path has no context notion.\n\nNOTE: For a true file-vs-file unified diff, supply `a` and `b` so the tool delegates to `git diff`. The `files`-only path is a line-numbered dump, not a diff.\n\nThis tool has important safety guards against flag injection (see previous security findings).',
   permission: "auto",
   mutating: false,
   maxOutputBytes: 262144,
@@ -69,11 +105,12 @@ var diffTool = {
       mode: {
         type: "string",
         enum: ["unified", "side-by-side", "stat"],
-        description: 'Output format. "unified" is default, "stat" shows summary only.'
+        description: 'Output format for the git-diff path. "unified" is default; "stat" shows a summary only; "side-by-side" is not supported and falls back to unified. The `files`-only dump path ignores this.'
       },
       context: {
         type: "integer",
-        description: "Number of context lines for unified diffs (default: 3)."
+        minimum: 0,
+        description: "Number of context lines for git unified diffs (default: 3, passed as -U<n>). Ignored by the `files`-only dump path."
       }
     }
   },
@@ -86,16 +123,31 @@ var diffTool = {
 };
 async function gitDiff(input, ctx, signal) {
   if (input.a?.startsWith("-")) {
-    throw new Error(`diff: unsafe ref "${input.a}" \u2014 refs may not begin with '-' (flag injection)`);
+    throw new ToolValidationError({
+      message: `diff: unsafe ref "${input.a}" \u2014 refs may not begin with '-' (flag injection)`,
+      field: "a"
+    });
   }
   if (input.b?.startsWith("-")) {
-    throw new Error(`diff: unsafe ref "${input.b}" \u2014 refs may not begin with '-' (flag injection)`);
+    throw new ToolValidationError({
+      message: `diff: unsafe ref "${input.b}" \u2014 refs may not begin with '-' (flag injection)`,
+      field: "b"
+    });
   }
+  const requestedMode = input.mode ?? "unified";
+  const statMode = requestedMode === "stat";
+  const effectiveMode = statMode ? "stat" : "unified";
+  const sideBySideNote = requestedMode === "side-by-side" ? "side-by-side output is not supported; a unified diff was produced instead." : void 0;
   const gitDir = findGitDir(ctx.cwd);
   if (!gitDir) {
-    return { diff: "", files: [], truncated: false, mode: "unified" };
+    return { diff: "", files: [], truncated: false, mode: effectiveMode };
   }
   const args = ["diff", "--no-color"];
+  if (statMode) args.push("--stat");
+  if (!statMode && input.context !== void 0) {
+    const contextLines = Math.max(0, Math.floor(input.context));
+    if (Number.isFinite(contextLines)) args.push(`-U${contextLines}`);
+  }
   if (input.staged) args.push("--staged");
   if (input.a) args.push(input.a);
   if (input.b) args.push(input.b);
@@ -104,11 +156,22 @@ async function gitDiff(input, ctx, signal) {
     args.push("--", ...files.map((f) => f.trim()));
   }
   const result = await runGit(args, gitDir, signal);
+  let diff = result.stdout;
+  let truncated = false;
+  if (diff.length > MAX_GIT_DIFF_CHARS) {
+    let clipped = diff.slice(0, MAX_GIT_DIFF_CHARS);
+    const nl = clipped.lastIndexOf("\n");
+    if (nl > 0) clipped = clipped.slice(0, nl);
+    diff = `${clipped}
+\u2026[git diff truncated: ${result.stdout.length - clipped.length} of ${result.stdout.length} characters omitted]`;
+    truncated = true;
+  }
   return {
-    diff: result.stdout,
+    diff,
     files: [],
-    truncated: result.stdout.length > 1e5,
-    mode: "unified"
+    truncated,
+    mode: effectiveMode,
+    note: sideBySideNote
   };
 }
 function findGitDir(cwd) {
@@ -154,13 +217,13 @@ async function fileDiff(input, ctx, _signal) {
       diff: "No files specified",
       files: [],
       truncated: false,
-      mode: input.mode ?? "unified"
+      mode: "dump"
     };
   }
   const results = [];
   let truncated = false;
   for (const file of files) {
-    const absPath = safeResolve(file, ctx);
+    const absPath = await safeResolveReal(file, ctx);
     const stat2 = await fs.stat(absPath).catch(() => null);
     if (!stat2?.isFile()) continue;
     if (stat2.size > MAX_FILE_DUMP_BYTES) {
@@ -178,7 +241,10 @@ async function fileDiff(input, ctx, _signal) {
     diff: results.join("\n\n"),
     files,
     truncated,
-    mode: input.mode ?? "unified"
+    // Honest mode: this path always produces a line-numbered dump — it never
+    // honors `mode`, so it must not echo the requested value back.
+    mode: "dump",
+    note: input.mode !== void 0 ? "The `files`-only path is a line-numbered dump; `mode` only affects the git-diff path (`a`/`b`)." : void 0
   };
 }
 function formatWithLineNumbers(file, lines) {