token-goat 2.9.28 → 2.9.30

package/dist/{token-goat-chunk-SJEKA7Y2.mjs → token-goat-chunk-ZQSJMO2R.mjs}

@@ -1,95 +1,124 @@
 import { createRequire as __cjsRequire } from 'node:module';
 const require = __cjsRequire(import.meta.url);
 import {
-  ABSENT_PIN,
   CONTENT_MAX_INPUT_CHARS,
-  ConfinementIdentityError,
+  checkSemanticReadiness,
   compressText,
   createHandoff,
-  fileIdentity,
-  findSpecSeparator,
-  parseColonLineSpec,
-  parseLineRange,
-  pinKey,
   resolveHandoff,
   retrieveText,
   runBrief,
   runChanged,
   runExports,
-  runGrep,
   runImports,
   runOutline,
-  runRead,
   runRefs,
   runSection,
   runSemantic,
   runSkeleton,
   runSymbol,
+  statThroughHandle
+} from "./token-goat-chunk-CZ3LUXYZ.mjs";
+import "./token-goat-chunk-ZCDTCVIS.mjs";
+import {
+  ABSENT_PIN,
+  ConfinementIdentityError,
+  expandSpecPath,
+  fileIdentity,
+  findSpecSeparator,
+  parseColonLineSpec,
+  parseLineRange,
+  pinKey,
+  resolveProjectConfinement,
+  runGrep,
+  runRead,
   withPinnedReads
-} from "./token-goat-chunk-VWZKZPSR.mjs";
-import "./token-goat-chunk-4STDIGYC.mjs";
-import "./token-goat-chunk-DA43OE7L.mjs";
+} from "./token-goat-chunk-PU7V3FD6.mjs";
+import "./token-goat-chunk-XKI4SEMX.mjs";
+import "./token-goat-chunk-SMVRN2HU.mjs";
+import "./token-goat-chunk-4JJS54TR.mjs";
+import "./token-goat-chunk-RC35RBUL.mjs";
+import "./token-goat-chunk-5RG5SBL6.mjs";
+import "./token-goat-chunk-54K3EUV3.mjs";
+import "./token-goat-chunk-YARZFCZS.mjs";
 import {
   buildProjectMap,
   formatProjectMap,
-  getDirtyPathsFor,
   getEmbeddingCoverage,
   getProjectIndexCounts,
-  isWorkerRunning,
+  isIndexEmptyForProject,
   mapLookupBytesSaved
-} from "./token-goat-chunk-6Z5ULNE5.mjs";
-import "./token-goat-chunk-IZXKVT4A.mjs";
-import "./token-goat-chunk-RJH64KQH.mjs";
-import "./token-goat-chunk-MMLMALWK.mjs";
-import "./token-goat-chunk-6CCQDAYY.mjs";
-import "./token-goat-chunk-GGLEE35R.mjs";
+} from "./token-goat-chunk-FBNQNSJK.mjs";
+import "./token-goat-chunk-MNWKPRAL.mjs";
+import "./token-goat-chunk-67TQJ76B.mjs";
+import {
+  getDirtyPathsFor
+} from "./token-goat-chunk-H2PHHGM5.mjs";
+import "./token-goat-chunk-P4QMM4WK.mjs";
+import {
+  isWorkerRunning
+} from "./token-goat-chunk-5KDMCMF2.mjs";
+import "./token-goat-chunk-ATCPY7EQ.mjs";
+import "./token-goat-chunk-VPBBTSJR.mjs";
+import "./token-goat-chunk-Y776AENC.mjs";
+import "./token-goat-chunk-SJHWVNDQ.mjs";
+import "./token-goat-chunk-AFLYLHDH.mjs";
 import {
   claudeConfigDir
-} from "./token-goat-chunk-MAMQPC43.mjs";
-import "./token-goat-chunk-HXNAC4ZF.mjs";
-import "./token-goat-chunk-BJBRGPBX.mjs";
-import "./token-goat-chunk-4JMWPWCS.mjs";
-import "./token-goat-chunk-4RN64ZND.mjs";
+} from "./token-goat-chunk-BPGCUMR7.mjs";
+import "./token-goat-chunk-C63JQV5K.mjs";
+import "./token-goat-chunk-JB6QN6VF.mjs";
+import {
+  embeddingsDepsAvailable
+} from "./token-goat-chunk-RHXKCZX3.mjs";
+import "./token-goat-chunk-EVMZJ27Z.mjs";
+import {
+  pathSuffixClause
+} from "./token-goat-chunk-HYBFA5X3.mjs";
+import "./token-goat-chunk-5Y6ZYL6U.mjs";
+import "./token-goat-chunk-ARDNEC2U.mjs";
 import {
   recordStat,
   savedTokensFromBytes
-} from "./token-goat-chunk-MVSWBNMD.mjs";
-import "./token-goat-chunk-LKSXAMJB.mjs";
-import "./token-goat-chunk-YWSP6IU7.mjs";
+} from "./token-goat-chunk-3Z5S4KGM.mjs";
+import {
+  getDb
+} from "./token-goat-chunk-VL3YIFHZ.mjs";
+import "./token-goat-chunk-XB5KKOCG.mjs";
+import "./token-goat-chunk-QSBRTGM2.mjs";
+import "./token-goat-chunk-N2NMER56.mjs";
 import "./token-goat-chunk-3BTK54F3.mjs";
+import "./token-goat-chunk-4FVIAHSI.mjs";
+import {
+  loadConfig,
+  resolveProjectRoot
+} from "./token-goat-chunk-7IN2MKDS.mjs";
+import "./token-goat-chunk-U4N3BN2W.mjs";
+import "./token-goat-chunk-YZAAZU2S.mjs";
+import {
+  envStrList
+} from "./token-goat-chunk-IVE6U7KV.mjs";
 import "./token-goat-chunk-XTQAOTSO.mjs";
 import "./token-goat-chunk-AH6QILZM.mjs";
-import "./token-goat-chunk-66LODAUT.mjs";
+import "./token-goat-chunk-Y4AFKTHK.mjs";
 import {
-  checkEmbeddingPreflight,
-  embeddingsDepsAvailable
-} from "./token-goat-chunk-D5ICEPSB.mjs";
-import "./token-goat-chunk-HUDC5GS5.mjs";
+  extractErrorMessage
+} from "./token-goat-chunk-GOLEOXZP.mjs";
 import {
-  getDb
-} from "./token-goat-chunk-M56BWPBN.mjs";
+  foldCaseForContainment
+} from "./token-goat-chunk-AM5V6GSX.mjs";
 import {
-  envStrList,
-  loadConfig,
-  resolveProjectRoot
-} from "./token-goat-chunk-CC2PYJM7.mjs";
-import "./token-goat-chunk-EEIDFMEM.mjs";
-import "./token-goat-chunk-OSUFN2FV.mjs";
+  displaySafeJson,
+  normalizePath
+} from "./token-goat-chunk-FNFBKLRD.mjs";
 import {
   ENV_KEYS,
   VERSION,
   dataDir,
-  extractErrorMessage,
-  foldCaseForContainment,
   globalDbPath
-} from "./token-goat-chunk-L45ZQRT7.mjs";
-import {
-  displaySafeJson,
-  normalizePath
-} from "./token-goat-chunk-NMTKNYGF.mjs";
-import "./token-goat-chunk-Y4AFKTHK.mjs";
-import "./token-goat-chunk-GMOUBOX4.mjs";
-import "./token-goat-chunk-RRNZMM3A.mjs";
+} from "./token-goat-chunk-VES7EL7O.mjs";
+import "./token-goat-chunk-KWPNJBDH.mjs";
+import "./token-goat-chunk-HAVAOB3S.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
@@ -103,6 +132,7 @@ var TOKEN_GOAT_RETRY_RE = /token-goat (\w[\w-]*) "([^"]+)"/g;
 var MCP_MAX_LIMIT = 1e3;
 var MCP_MAX_CONTEXT_LINES = 50;
 var MCP_MAX_OUTPUT_LINES = 1e4;
+var MCP_MAX_MIN_LINES = 1e5;
 var RETRY_PARAM_BY_COMMAND = {
   read: "spec",
   section: "spec",
@@ -173,8 +203,86 @@ function realPathForContainment(p) {
 function forCompare(p) {
   return process.platform === "win32" ? foldCaseForContainment(p) : p;
 }
-function resolveToolRoot(projectRoot) {
-  const resolved = resolveProjectRoot(projectRoot !== void 0 ? { project: projectRoot } : {});
+function inferProjectRootFromTarget(target) {
+  const file = specFilePart(target);
+  if (!file) return null;
+  if (path.isAbsolute(file)) {
+    if (fs.existsSync(file)) {
+      try {
+        return resolveProjectRoot({ project: path.dirname(file) });
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+  try {
+    if (fs.existsSync(path.resolve(process.cwd(), file))) {
+      return null;
+    }
+  } catch {
+  }
+  const dbPath = globalDbPath();
+  if (fs.existsSync(dbPath)) {
+    try {
+      const db = getDb(dbPath);
+      const suffix = pathSuffixClause("path");
+      const rows = db.prepare(`SELECT path FROM files WHERE ${suffix.clause} ORDER BY length(path), path LIMIT 5`).all(...suffix.params(normalizePath(file)));
+      for (const row of rows) {
+        if (fs.existsSync(row.path)) {
+          return resolveProjectRoot({ project: path.dirname(row.path) });
+        }
+      }
+    } catch {
+    }
+  }
+  if (!file.includes("/") && !file.includes("\\") && !file.includes(".")) {
+    if (fs.existsSync(dbPath)) {
+      try {
+        const db = getDb(dbPath);
+        const rows = db.prepare(`SELECT file_path FROM symbols WHERE name = ? LIMIT 5`).all(file);
+        for (const row of rows) {
+          if (fs.existsSync(row.file_path)) {
+            return resolveProjectRoot({ project: path.dirname(row.file_path) });
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function rootHasIndexedFiles(root) {
+  const dbPath = globalDbPath();
+  if (!fs.existsSync(dbPath)) return false;
+  try {
+    const prefix = normalizePath(root).toLowerCase().replace(/\/+$/, "") + "/";
+    const row = getDb(dbPath).prepare(`SELECT 1 FROM files WHERE TG_LOWER(substr(path, 1, ?)) = ? LIMIT 1`).get(prefix.length, prefix);
+    return row !== void 0;
+  } catch {
+    return false;
+  }
+}
+function resolveToolRoot(projectRoot, candidateTargets) {
+  if (projectRoot !== void 0) {
+    const resolved2 = resolveProjectRoot({ project: projectRoot });
+    assertRootAllowed(resolved2);
+    return resolved2;
+  }
+  if (candidateTargets && candidateTargets.length > 0) {
+    for (const target of candidateTargets) {
+      if (!target) continue;
+      const inferred = inferProjectRootFromTarget(target);
+      if (inferred && rootHasIndexedFiles(inferred)) {
+        try {
+          assertRootAllowed(inferred);
+          return inferred;
+        } catch {
+        }
+      }
+    }
+  }
+  const resolved = resolveProjectRoot({});
   assertRootAllowed(resolved);
   return resolved;
 }
@@ -221,6 +329,12 @@ function assertRootAllowed(resolvedRoot) {
 }
 var NO_CHECK_PINS = [];
 function identityOf(p) {
+  try {
+    return fileIdentity(statThroughHandle(p));
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return null;
+  }
   try {
     return fileIdentity(fs.statSync(p, { bigint: true }));
   } catch {
@@ -236,8 +350,9 @@ function pinsFor(abs, real, identity) {
 }
 function checkWithinProjectRoot(target, resolvedRoot) {
   const rootReal = realPathForContainment(resolvedRoot);
-  const abs = path.resolve(resolvedRoot, normalizePath(target));
-  const absRaw = path.resolve(resolvedRoot, target);
+  const spelled = expandSpecPath(target);
+  const abs = path.resolve(resolvedRoot, normalizePath(spelled));
+  const absRaw = path.resolve(resolvedRoot, spelled);
   const identity = identityOf(absRaw);
   const realNative = realPathForContainment(abs);
   if (rootReal === null) return { inside: false, reason: "unresolvable-root", pins: NO_CHECK_PINS };
@@ -262,19 +377,26 @@ function specFilePart(spec) {
   const colonIdx = findSpecSeparator(spec);
   return colonIdx === -1 ? spec : spec.slice(0, colonIdx);
 }
+function specFileCandidates(spec) {
+  const file = specFilePart(spec);
+  const out = [file];
+  for (let idx = file.indexOf("::"); idx !== -1; idx = file.indexOf("::", idx + 1)) if (idx > 0) out.push(file.slice(0, idx));
+  return out;
+}
 var NO_PINS = /* @__PURE__ */ new Map();
-function refusalText(file, resolvedRoot, reason) {
+function refusalText(file, resolvedRoot, reason, projectRootWasOmitted = false) {
   const escapeHatch = "Set mcp.confine_reads_to_project_root = false (or TOKEN_GOAT_MCP_CONFINE_READS=0) to allow cross-root reads.";
+  const omittedNote = projectRootWasOmitted ? ` Note: projectRoot was omitted and defaulted to server process cwd "${resolvedRoot}". Pass projectRoot: "<workspace-path>" if your target is in another directory.` : "";
   if (reason === "unresolvable-root") {
-    return `refused: the project root "${resolvedRoot}" could not be resolved, so no path can be confirmed to sit inside it. This is a broken workspace root -- an unmounted share, a deleted directory, or a permission change on a parent -- not a request to read outside the project.`;
+    return `refused: the project root "${resolvedRoot}" could not be resolved, so no path can be confirmed to sit inside it. This is a broken workspace root -- an unmounted share, a deleted directory, or a permission change on a parent -- not a request to read outside the project.` + omittedNote;
   }
   if (reason === "unresolvable-target") {
-    return `refused: "${file}" could not be resolved to a real location, so it cannot be confirmed to sit inside the project root. A symlink loop, a permission error on a parent directory, or a path past the operating system's length limit all produce this. The check fails closed rather than falling back to comparing the text of the path.`;
+    return `refused: "${file}" could not be resolved to a real location, so it cannot be confirmed to sit inside the project root. A symlink loop, a permission error on a parent directory, or a path past the operating system's length limit all produce this. The check fails closed rather than falling back to comparing the text of the path.` + omittedNote;
   }
   const rootScope = loadConfig().mcp.allowed_roots.length === 0 ? "Each call is confined to the projectRoot it names, and that root comes from the caller: set mcp.allowed_roots (or TOKEN_GOAT_MCP_ALLOWED_ROOTS) to pin which roots may be named at all." : "Each call is confined to the projectRoot it names, which must itself sit inside mcp.allowed_roots.";
-  return `refused: "${file}" is outside the project root "${resolvedRoot}". ${rootScope} ${escapeHatch}`;
+  return `refused: "${file}" is outside the project root "${resolvedRoot}". ${rootScope} ${escapeHatch}${omittedNote}`;
 }
-function confineTargets(targets, resolvedRoot, splitCommas = true) {
+function confineTargets(targets, resolvedRoot, splitCommas = true, projectRootWasOmitted = false) {
   if (!loadConfig(resolvedRoot).mcp.confine_reads_to_project_root) return { ok: true, targets, pins: NO_PINS };
   const allowedRoots = loadConfig().mcp.allowed_roots;
   const checked = [];
@@ -282,31 +404,32 @@ function confineTargets(targets, resolvedRoot, splitCommas = true) {
   for (const raw of targets) {
     const parts = splitCommas ? raw.split(",") : [raw];
     for (const part of parts) {
-      const file = specFilePart(part);
-      if (file === "") continue;
-      let check = checkWithinProjectRoot(file, resolvedRoot);
-      if (!check.inside) {
-        for (const allowed of allowedRoots) {
-          const altCheck = checkWithinProjectRoot(file, allowed);
-          if (altCheck.inside) {
-            check = altCheck;
-            break;
+      for (const file of specFileCandidates(part)) {
+        if (file === "") continue;
+        let check = checkWithinProjectRoot(file, resolvedRoot);
+        if (!check.inside) {
+          for (const allowed of allowedRoots) {
+            const altCheck = checkWithinProjectRoot(file, allowed);
+            if (altCheck.inside) {
+              check = altCheck;
+              break;
+            }
           }
         }
-      }
-      if (!check.inside) {
-        for (const aux of getStandardAuxiliaryRoots(file)) {
-          const auxCheck = checkWithinProjectRoot(file, aux);
-          if (auxCheck.inside) {
-            check = auxCheck;
-            break;
+        if (!check.inside) {
+          for (const aux of getStandardAuxiliaryRoots(file)) {
+            const auxCheck = checkWithinProjectRoot(file, aux);
+            if (auxCheck.inside) {
+              check = auxCheck;
+              break;
+            }
           }
         }
+        if (!check.inside) {
+          return { ok: false, refusal: toCallToolResult({ text: refusalText(file, resolvedRoot, check.reason, projectRootWasOmitted), code: 1 }) };
+        }
+        for (const [key, identity] of check.pins) pins.set(key, identity);
       }
-      if (!check.inside) {
-        return { ok: false, refusal: toCallToolResult({ text: refusalText(file, resolvedRoot, check.reason), code: 1 }) };
-      }
-      for (const [key, identity] of check.pins) pins.set(key, identity);
     }
     checked.push(splitCommas ? parts.join(",") : parts[0]);
   }
@@ -325,12 +448,28 @@ function withConfinedRead(pins, fn) {
     throw err;
   }
 }
+function noteOmittedProjectRoot(result, root, projectRootWasOmitted) {
+  if (!projectRootWasOmitted) return result;
+  if (!isIndexEmptyForProject(globalDbPath(), root)) return result;
+  const note = `
+(Note: projectRoot was omitted and defaulted to server cwd "${root}", which has no files indexed. Pass projectRoot: "<workspace-path>" to target your workspace.)`;
+  const contents = result.content;
+  if (!Array.isArray(contents)) return result;
+  for (const item of contents) {
+    if (item && typeof item === "object" && "text" in item && typeof item.text === "string") {
+      if (!item.text.includes("projectRoot was omitted")) {
+        item.text += note;
+      }
+    }
+  }
+  return result;
+}
 function mcpToolAllowlist() {
   const names = envStrList(ENV_KEYS.MCP_TOOLS, [], ",");
   return names.length === 0 ? null : new Set(names);
 }
 async function createMcpServer() {
-  const [{ McpServer }, { z }] = await Promise.all([import("./token-goat-chunk-XBESNWEX.mjs"), import("./token-goat-chunk-CHLHM42P.mjs")]);
+  const [{ McpServer }, { z }] = await Promise.all([import("./token-goat-chunk-JN4XMLSD.mjs"), import("./token-goat-chunk-CHLHM42P.mjs")]);
   const server = new McpServer({ name: "token-goat", version: VERSION });
   const allowlist = mcpToolAllowlist();
   if (allowlist !== null) {
@@ -349,10 +488,7 @@ async function createMcpServer() {
       }
     }, 0).unref();
   }
-  const makeProjectRootField = (verb) => z.string().optional().describe(
-    `absolute path to the workspace root to scope this ${verb} to; defaults to the MCP server process's cwd, which is not always the actual workspace root for MCP clients -- pass this explicitly when it might differ`
-  );
-  const projectRootField = makeProjectRootField("lookup");
+  const projectRootField = z.string().optional().describe("absolute workspace root; defaults to the server's cwd, which may not be the workspace, so pass it when unsure");
   server.registerTool(
     "symbol",
     {
@@ -369,36 +505,41 @@ async function createMcpServer() {
     },
     (args) => {
       const { name, limit, file, kind, json, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, file ? [file] : name ? [name] : void 0);
       let confinedFile = file;
       let pins = NO_PINS;
       if (file !== void 0) {
-        const gate = confineTargets([file], root);
+        const gate = confineTargets([file], root, true, projectRootWasOmitted);
         if (!gate.ok) return gate.refusal;
         confinedFile = gate.targets[0];
         pins = gate.pins;
       }
-      return withConfinedRead(
-        pins,
-        () => toCallToolResult(
-          runSymbol({
-            name,
-            limit: limit ?? 20,
-            ...confinedFile !== void 0 ? { file: confinedFile } : {},
-            ...kind !== void 0 ? { kind } : {},
-            ...json === true ? { json: true } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          pins,
+          () => toCallToolResult(
+            runSymbol({
+              name,
+              limit: limit ?? 20,
+              ...confinedFile !== void 0 ? { file: confinedFile } : {},
+              ...kind !== void 0 ? { kind } : {},
+              ...json === true ? { json: true } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
   server.registerTool(
     "read",
     {
-      description: "Read one symbol's full body, given a spec of the form file::symbol, or a line range file@N-M / file@N, or a bare file path. Pass a comma-separated spec (file::a,b) to fetch several symbols' bodies from one file in a single call.",
+      description: "Read a symbol's full body (file::symbol), several from one file (file::a,b), a line range (file@N-M, file@N), or a file.",
       inputSchema: {
-        spec: z.string().describe("file::symbol, file@N-M, file@N, a bare file path, or comma-separated file::a,b for a merged multi-symbol view"),
+        spec: z.string().describe("file::symbol, file::a,b, file@N-M, file@N, or a file path"),
         json: z.boolean().optional().describe("output as JSON"),
         forceRefresh: z.boolean().optional().describe("reparse file from disk before querying (ignore stale index)"),
         stats: z.boolean().optional().describe("add per-symbol reference count and doc-coverage flag"),
@@ -409,20 +550,25 @@ async function createMcpServer() {
     },
     (args) => {
       const { spec, json, forceRefresh, stats, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([spec], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [spec]);
+      const gate = confineTargets([spec], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
-      return withConfinedRead(
-        gate.pins,
-        () => toCallToolResult(
-          runRead({
-            spec: gate.targets[0],
-            ...json === true ? { json: true } : {},
-            ...forceRefresh === true ? { forceRefresh: true } : {},
-            ...stats === true ? { stats: true } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          gate.pins,
+          () => toCallToolResult(
+            runRead({
+              spec: gate.targets[0],
+              ...json === true ? { json: true } : {},
+              ...forceRefresh === true ? { forceRefresh: true } : {},
+              ...stats === true ? { stats: true } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
@@ -439,18 +585,23 @@ async function createMcpServer() {
     },
     (args) => {
       const { spec, json, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([spec], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [spec]);
+      const gate = confineTargets([spec], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
-      return withConfinedRead(
-        gate.pins,
-        () => toCallToolResult(
-          runSection({
-            spec: gate.targets[0],
-            ...json === true ? { json: true } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          gate.pins,
+          () => toCallToolResult(
+            runSection({
+              spec: gate.targets[0],
+              ...json === true ? { json: true } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
@@ -461,7 +612,7 @@ async function createMcpServer() {
       inputSchema: {
         file: z.string().describe("file path"),
         json: z.boolean().optional().describe("output as JSON"),
-        minLines: z.number().int().optional().describe("only show symbols at least N lines long"),
+        minLines: z.number().int().nonnegative().max(MCP_MAX_MIN_LINES).optional().describe("only show symbols at least N lines long"),
         forceRefresh: z.boolean().optional().describe("reparse file from disk before querying (ignore stale index)"),
         stats: z.boolean().optional().describe("add per-symbol reference count and doc-coverage flag"),
         projectRoot: projectRootField
@@ -470,21 +621,26 @@ async function createMcpServer() {
     },
     (args) => {
       const { file, json, minLines, forceRefresh, stats, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([file], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [file]);
+      const gate = confineTargets([file], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
-      return withConfinedRead(
-        gate.pins,
-        () => toCallToolResult(
-          runSkeleton({
-            file: gate.targets[0],
-            ...json === true ? { json: true } : {},
-            ...minLines !== void 0 ? { minLines } : {},
-            ...forceRefresh === true ? { forceRefresh: true } : {},
-            ...stats === true ? { stats: true } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          gate.pins,
+          () => toCallToolResult(
+            runSkeleton({
+              file: gate.targets[0],
+              ...json === true ? { json: true } : {},
+              ...minLines !== void 0 ? { minLines } : {},
+              ...forceRefresh === true ? { forceRefresh: true } : {},
+              ...stats === true ? { stats: true } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
@@ -495,7 +651,7 @@ async function createMcpServer() {
       inputSchema: {
         file: z.string().describe("file path"),
         json: z.boolean().optional().describe("output as JSON"),
-        minLines: z.number().int().optional().describe("only show symbols at least N lines long"),
+        minLines: z.number().int().nonnegative().max(MCP_MAX_MIN_LINES).optional().describe("only show symbols at least N lines long"),
         forceRefresh: z.boolean().optional().describe("reparse file from disk before querying (ignore stale index)"),
         stats: z.boolean().optional().describe("add per-symbol reference count and doc-coverage flag"),
         projectRoot: projectRootField
@@ -504,37 +660,42 @@ async function createMcpServer() {
     },
     (args) => {
       const { file, json, minLines, forceRefresh, stats, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([file], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [file]);
+      const gate = confineTargets([file], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
-      return withConfinedRead(
-        gate.pins,
-        () => toCallToolResult(
-          runOutline({
-            file: gate.targets[0],
-            ...json === true ? { json: true } : {},
-            ...minLines !== void 0 ? { minLines } : {},
-            ...forceRefresh === true ? { forceRefresh: true } : {},
-            ...stats === true ? { stats: true } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          gate.pins,
+          () => toCallToolResult(
+            runOutline({
+              file: gate.targets[0],
+              ...json === true ? { json: true } : {},
+              ...minLines !== void 0 ? { minLines } : {},
+              ...forceRefresh === true ? { forceRefresh: true } : {},
+              ...stats === true ? { stats: true } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
   server.registerTool(
     "semantic",
     {
-      description: "Semantic search over the indexed project (falls back to full-text search when no embedding index is available). Scoped to projectRoot if given, else the MCP server process's own cwd -- which may not be the actual workspace root for a client that launched the server from elsewhere, so pass projectRoot explicitly when in doubt.",
+      description: "Semantic search over the indexed project; falls back to full-text search without an embedding index.",
       inputSchema: {
         query: z.string().describe("natural-language search query"),
         limit: z.number().int().positive().max(MCP_MAX_LIMIT).optional().describe("max results (default: 20)"),
-        grep: z.string().optional().describe("filter to hits whose file path matches this regex (literal substring if it does not compile as regex); matched against the path as rendered, same convention as refs --grep"),
-        excludeTests: z.boolean().optional().describe("hide hits whose file is a test file (opt-in; default output is unchanged)"),
-        preflight: z.boolean().optional().describe("run semantic embedding preflight check and return status"),
-        warm: z.boolean().optional().describe("warm up the embedding model session in memory before query execution"),
+        grep: z.string().optional().describe("only hits whose file path matches this regex (a literal substring if it is not valid regex)"),
+        excludeTests: z.boolean().optional().describe("hide hits in test files"),
+        preflight: z.boolean().optional().describe("report whether embeddings are ready, instead of searching"),
+        warm: z.boolean().optional().describe("load the embedding model before the query"),
         json: z.boolean().optional().describe("output as JSON"),
-        projectRoot: makeProjectRootField("search")
+        projectRoot: projectRootField
       },
       // openWorldHint stays false although a first call on a machine with no cached model downloads one over the network: what this tool interacts with is the local index, and the download provisions the tool rather than being the tool reaching out. A client reading `true` here would take it as "this searches the internet", which is the wrong warning.
       annotations: { readOnlyHint: true, openWorldHint: false }
@@ -558,9 +719,9 @@ async function createMcpServer() {
   server.registerTool(
     "index_status",
     {
-      description: 'Report whether the index for a project can be trusted right now: whether it has ever been indexed at all, current file/symbol counts, dirty-reindex-queue depth, whether the background worker is alive, and whether embeddings are available (semantic silently degrades to full-text search without them). Call this after an unexpectedly empty result from another token-goat tool (symbol/read/semantic/refs/brief/...) to tell apart "no match" from "the index is not ready yet" -- an MCP-only client has no hook layer to warn about this on its own, so an empty tool result and a stale/unindexed project look identical without this check.',
+      description: 'Whether the project index can be trusted now: indexed at all, file and symbol counts, reindex queue depth, worker alive, and embeddings available (without them semantic falls back to full-text search). Call it when another token-goat tool returns nothing, to tell "no match" from "index not ready".',
       inputSchema: {
-        projectRoot: makeProjectRootField("check")
+        projectRoot: projectRootField
       },
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
@@ -595,7 +756,7 @@ async function createMcpServer() {
         }
       }
       const embeddingsEnabled = loadConfig(rootDir).indexing?.embeddings_enabled ?? true;
-      const preflight = await checkEmbeddingPreflight({
+      const preflight = await checkSemanticReadiness({
         projectRoot: rootDir,
         ...coverage !== void 0 ? { coverage } : {}
       });
@@ -620,13 +781,13 @@ async function createMcpServer() {
   server.registerTool(
     "refs",
     {
-      description: "Find references to one or more symbols (spec: file::symbol, symbol, or comma-separated a,b,c / file::a,b for a merged multi-symbol view). For an unambiguous TypeScript symbol, automatically type-resolves candidates via the TypeScript compiler API to drop same-named-different-symbol false positives; falls back to name-based matching when that is not possible.",
+      description: "Find references to symbols. An unambiguous TypeScript symbol is type-resolved, dropping same-named symbols; anything else matches by name.",
       inputSchema: {
-        spec: z.string().describe("file::symbol, symbol, or comma-separated a,b,c / file::a,b for a merged multi-symbol view"),
+        spec: z.string().describe("file::symbol, symbol, a,b,c, or file::a,b"),
         callers: z.boolean().optional().describe("group references by their enclosing caller symbol"),
         limit: z.number().int().positive().max(MCP_MAX_LIMIT).optional().describe("max results"),
         top: z.number().int().positive().max(MCP_MAX_LIMIT).optional().describe(
-          "for a high-fanout symbol, group references by file (count only) and show only the top N files by reference count instead of a per-line dump"
+          "list only the top N files by reference count, instead of every reference"
         ),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
@@ -635,9 +796,16 @@ async function createMcpServer() {
     },
     (args) => {
       const { spec, callers, limit, top, json, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([spec], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [spec]);
+      const gate = confineTargets([spec], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
+      if (projectRootWasOmitted && isIndexEmptyForProject(globalDbPath(), root)) {
+        return toCallToolResult({
+          text: `Error: projectRoot was omitted and defaulted to server cwd "${root}", which has no files indexed. Pass projectRoot: "<workspace-path>" to target your workspace.`,
+          code: 1
+        });
+      }
       return withConfinedRead(
         gate.pins,
         () => toCallToolResultFromExitCode(
@@ -656,36 +824,41 @@ async function createMcpServer() {
   server.registerTool(
     "brief",
     {
-      description: "One-shot symbol orientation: signature, location, token count, body, callers, and containing doc section, in a single call (spec: file::symbol; comma-separated file::a,b for a merged multi-symbol view; cross-file a.ts::x,b.ts::y is also supported -- unlike refs, a bare symbol name with no file is not accepted). Prefer this over separate read + refs calls when the goal is to understand a symbol, not just fetch its source: it folds the work of read (body) and refs --callers (call sites) into one result, at a fraction of the combined round-trip cost.",
+      description: "Understand a symbol in one call: signature, location, token count, body, callers and containing doc section. Prefer it to read plus refs. Spec file::symbol, file::a,b or a.ts::x,b.ts::y; a bare name without a file is not accepted.",
       inputSchema: {
-        spec: z.string().describe("file::symbol; comma-separated file::a,b for a merged multi-symbol view; cross-file a.ts::x,b.ts::y is also supported"),
+        spec: z.string().describe("file::symbol, file::a,b, or a.ts::x,b.ts::y"),
         limit: z.number().int().positive().max(MCP_MAX_LIMIT).optional().describe("max callers to show (default: 20)"),
         json: z.boolean().optional().describe("output as JSON"),
-        context: z.number().int().nonnegative().max(MCP_MAX_CONTEXT_LINES).optional().describe("lines of call-site source to show before and after each caller (default 0)"),
-        excludeTests: z.boolean().optional().describe("hide callers whose call site lives in a test file (opt-in; default output is unchanged)"),
-        grep: z.string().optional().describe("only show callers whose enclosing symbol name matches this regex (literal substring if it is not valid regex)"),
-        projectRoot: makeProjectRootField("orient")
+        context: z.number().int().nonnegative().max(MCP_MAX_CONTEXT_LINES).optional().describe("call-site lines to show around each caller (default 0)"),
+        excludeTests: z.boolean().optional().describe("hide callers in test files"),
+        grep: z.string().optional().describe("only callers whose enclosing symbol matches this regex (a literal substring if it is not valid regex)"),
+        projectRoot: projectRootField
       },
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { spec, limit, json, context, excludeTests, grep, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([spec], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [spec]);
+      const gate = confineTargets([spec], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
-      return withConfinedRead(
-        gate.pins,
-        () => toCallToolResultFromExitCode(
-          () => runBrief({
-            spec: gate.targets[0],
-            ...json === true ? { json: true } : {},
-            ...limit !== void 0 ? { limit } : {},
-            ...context !== void 0 ? { context } : {},
-            ...excludeTests === true ? { excludeTests: true } : {},
-            ...grep !== void 0 ? { grep } : {},
-            projectRoot: root
-          })
-        )
+      return noteOmittedProjectRoot(
+        withConfinedRead(
+          gate.pins,
+          () => toCallToolResultFromExitCode(
+            () => runBrief({
+              spec: gate.targets[0],
+              ...json === true ? { json: true } : {},
+              ...limit !== void 0 ? { limit } : {},
+              ...context !== void 0 ? { context } : {},
+              ...excludeTests === true ? { excludeTests: true } : {},
+              ...grep !== void 0 ? { grep } : {},
+              projectRoot: root
+            })
+          )
+        ),
+        root,
+        projectRootWasOmitted
       );
     }
   );
@@ -695,13 +868,16 @@ async function createMcpServer() {
       description: "Project overview: file count, languages, headline symbols, and recently modified files.",
       inputSchema: {
         compact: z.boolean().optional().describe("compact, low-token summary"),
-        projectRoot: makeProjectRootField("overview")
+        projectRoot: projectRootField
       },
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { compact, projectRoot } = args;
-      const map = buildProjectMap(resolveToolRoot(projectRoot), { compact: compact === true });
+      const root = resolveToolRoot(projectRoot);
+      const projectDenial = resolveProjectConfinement(root).denial;
+      if (projectDenial !== null) return toCallToolResult({ text: projectDenial, code: 1 });
+      const map = buildProjectMap(root, { compact: compact === true });
       const text = formatProjectMap(map, map.compact);
       const bytesSaved = mapLookupBytesSaved(map, text);
       recordStat("map_lookup", bytesSaved, savedTokensFromBytes(bytesSaved));
@@ -744,14 +920,15 @@ async function createMcpServer() {
         recursive: z.boolean().optional().describe("descend into subdirectories (default: true)"),
         context: z.number().int().nonnegative().max(MCP_MAX_CONTEXT_LINES).optional().describe("lines of context to show before and after each match"),
         // runGrep takes no projectRoot of its own (its `path` array is its scope), so this field only names the root the confinement check is made against -- without it, a search rooted anywhere but the server process's cwd is refused.
-        projectRoot: makeProjectRootField("search")
+        projectRoot: projectRootField
       },
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { pattern, path: searchPath, maxLines, json, recursive, context, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets(searchPath === void 0 ? [root] : searchPath, root, false);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, searchPath);
+      const gate = confineTargets(searchPath === void 0 ? [root] : searchPath, root, false, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
       const confinedPath = searchPath === void 0 ? void 0 : [...gate.targets];
       return withConfinedRead(
@@ -783,8 +960,9 @@ async function createMcpServer() {
     },
     (args) => {
       const { file, json, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([file], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [file]);
+      const gate = confineTargets([file], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
       return withConfinedRead(
         gate.pins,
@@ -807,8 +985,9 @@ async function createMcpServer() {
     },
     (args) => {
       const { file, json, projectRoot } = args;
-      const root = resolveToolRoot(projectRoot);
-      const gate = confineTargets([file], root);
+      const projectRootWasOmitted = projectRoot === void 0;
+      const root = resolveToolRoot(projectRoot, [file]);
+      const gate = confineTargets([file], root, true, projectRootWasOmitted);
       if (!gate.ok) return gate.refusal;
       return withConfinedRead(
         gate.pins,
@@ -851,7 +1030,7 @@ async function createMcpServer() {
       inputSchema: {
         name: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/).describe("handoff name"),
         text: z.string().max(CONTENT_MAX_INPUT_CHARS).describe("handoff text"),
-        projectRoot: makeProjectRootField("scope")
+        projectRoot: projectRootField
       },
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
@@ -867,7 +1046,7 @@ async function createMcpServer() {
       inputSchema: {
         name: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/).describe("handoff name"),
         full: z.boolean().optional().describe("return full text instead of a compact payload"),
-        projectRoot: makeProjectRootField("scope")
+        projectRoot: projectRootField
       },
       // Reads like a read, and is not one: resolving compactly runs the handoff text back through compressText, which stores the compact payload so the recovery id it hands back can be redeemed. A measurement, not a reading of this code -- the guard hashes the store's bytes around every tool call, and this is the tool it caught.
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
@@ -885,5 +1064,6 @@ async function createMcpServer() {
 export {
   checkWithinProjectRoot,
   createMcpServer,
+  inferProjectRootFromTarget,
   mcpToolAllowlist
 };