token-goat 2.9.12 → 2.9.14

package/dist/token-goat-chunk-Y4AFKTHK.mjs

@@ -0,0 +1,22 @@
+import { createRequire as __cjsRequire } from 'node:module';
+const require = __cjsRequire(import.meta.url);
+import {
+  init_define_import_meta_env
+} from "./token-goat-chunk-A37V4PBF.mjs";
+
+// src/document_refusal.ts
+init_define_import_meta_env();
+var MAX_DOCUMENT_WORK_MILLIS = 6e4;
+var DocumentRefusedError = class extends Error {
+  transient;
+  constructor(message, name, transient = false) {
+    super(message);
+    this.name = name;
+    this.transient = transient;
+  }
+};
+
+export {
+  MAX_DOCUMENT_WORK_MILLIS,
+  DocumentRefusedError
+};

package/dist/token-goat-chunk-YHGTGG6K.mjs

@@ -0,0 +1,396 @@
+import { createRequire as __cjsRequire } from 'node:module';
+const require = __cjsRequire(import.meta.url);
+import {
+  MAX_ZIP_INPUT_BYTES,
+  MAX_ZIP_OUTPUT_BYTES,
+  ZipInputTooLargeError,
+  ZipOutputTooLargeError,
+  unzipBounded
+} from "./token-goat-chunk-XTQAOTSO.mjs";
+import {
+  createLazyModuleLoader
+} from "./token-goat-chunk-AH6QILZM.mjs";
+import {
+  DocumentRefusedError,
+  MAX_DOCUMENT_WORK_MILLIS
+} from "./token-goat-chunk-Y4AFKTHK.mjs";
+import {
+  pushAll
+} from "./token-goat-chunk-AMYCQJX4.mjs";
+import {
+  init_define_import_meta_env
+} from "./token-goat-chunk-A37V4PBF.mjs";
+
+// src/ooxml_extract.ts
+init_define_import_meta_env();
+import * as fs from "node:fs";
+
+// src/xml_parser.ts
+init_define_import_meta_env();
+var MAX_XML_DEPTH = 512;
+var XmlTooDeepError = class extends DocumentRefusedError {
+  constructor(message) {
+    super(message, "XmlTooDeepError");
+  }
+};
+var NAMED_ENTITIES = {
+  lt: "<",
+  gt: ">",
+  amp: "&",
+  quot: '"',
+  apos: "'"
+};
+function decodeXmlEntities(text) {
+  if (!text.includes("&")) return text;
+  return text.replace(/&(#[xX][0-9a-fA-F]+|#[0-9]+|[a-zA-Z_][\w.:-]*);/g, (whole, body) => {
+    if (body.charCodeAt(0) === 35) {
+      const isHex = body.charCodeAt(1) === 120 || body.charCodeAt(1) === 88;
+      const digits = isHex ? body.slice(2) : body.slice(1);
+      const code = parseInt(digits, isHex ? 16 : 10);
+      if (!Number.isFinite(code) || code < 0 || code > 1114111) return whole;
+      if (code >= 55296 && code <= 57343) return whole;
+      return String.fromCodePoint(code);
+    }
+    const named = NAMED_ENTITIES[body];
+    return named ?? whole;
+  });
+}
+function newFrame(name) {
+  return { name, children: /* @__PURE__ */ new Map(), text: [], attrs: [] };
+}
+function finishFrame(frame) {
+  const text = frame.text.join("");
+  if (frame.children.size === 0 && frame.attrs.length === 0) return text;
+  const obj = {};
+  for (const [key, value] of frame.children) obj[key] = value;
+  if (text.length > 0) obj["#text"] = text;
+  for (const [key, value] of frame.attrs) obj[`@_${key}`] = value;
+  return obj;
+}
+function addChild(parent, name, value) {
+  const existing = parent.children.get(name);
+  if (existing === void 0 && !parent.children.has(name)) {
+    parent.children.set(name, value);
+    return;
+  }
+  if (Array.isArray(existing)) {
+    existing.push(value);
+    return;
+  }
+  parent.children.set(name, [existing, value]);
+}
+var WHITESPACE = /* @__PURE__ */ new Set([" ", "	", "\n", "\r"]);
+function findTagEnd(src, from) {
+  let quote = "";
+  for (let i = from; i < src.length; i++) {
+    const ch = src[i];
+    if (quote !== "") {
+      if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ">") return i;
+  }
+  return -1;
+}
+function skipDeclaration(src, from) {
+  let quote = "";
+  let inSubset = false;
+  for (let i = from + 2; i < src.length; i++) {
+    const ch = src[i];
+    if (quote !== "") {
+      if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "[") inSubset = true;
+    else if (ch === "]") inSubset = false;
+    else if (ch === ">" && !inSubset) return i + 1;
+  }
+  return src.length;
+}
+function parseTagBody(body) {
+  let i = 0;
+  while (i < body.length && !WHITESPACE.has(body[i])) i++;
+  const name = body.slice(0, i);
+  const attrs = [];
+  while (i < body.length) {
+    while (i < body.length && WHITESPACE.has(body[i])) i++;
+    if (i >= body.length) break;
+    const nameStart = i;
+    while (i < body.length && !WHITESPACE.has(body[i]) && body[i] !== "=") i++;
+    const attrName = body.slice(nameStart, i);
+    if (attrName.length === 0) {
+      i++;
+      continue;
+    }
+    while (i < body.length && WHITESPACE.has(body[i])) i++;
+    if (body[i] !== "=") {
+      attrs.push([attrName, ""]);
+      continue;
+    }
+    i++;
+    while (i < body.length && WHITESPACE.has(body[i])) i++;
+    const quote = body[i];
+    if (quote === '"' || quote === "'") {
+      const valueStart = i + 1;
+      const valueEnd = body.indexOf(quote, valueStart);
+      const end = valueEnd === -1 ? body.length : valueEnd;
+      attrs.push([attrName, decodeXmlEntities(body.slice(valueStart, end))]);
+      i = end + 1;
+    } else {
+      const valueStart = i;
+      while (i < body.length && !WHITESPACE.has(body[i])) i++;
+      attrs.push([attrName, decodeXmlEntities(body.slice(valueStart, i))]);
+    }
+  }
+  return { name, attrs };
+}
+function parseXml(xml) {
+  const src = xml.charCodeAt(0) === 65279 ? xml.slice(1) : xml;
+  const root = newFrame("");
+  const stack = [root];
+  const len = src.length;
+  let i = 0;
+  const top = () => stack[stack.length - 1];
+  const pushText = (from, to) => {
+    if (to > from) top().text.push(decodeXmlEntities(src.slice(from, to)));
+  };
+  const closeElement = (name) => {
+    let target = -1;
+    for (let k = stack.length - 1; k >= 1; k--) {
+      if (stack[k].name === name) {
+        target = k;
+        break;
+      }
+    }
+    if (target === -1) return;
+    while (stack.length > target) {
+      const frame = stack.pop();
+      addChild(top(), frame.name, finishFrame(frame));
+    }
+  };
+  while (i < len) {
+    const lt = src.indexOf("<", i);
+    if (lt === -1) {
+      pushText(i, len);
+      break;
+    }
+    pushText(i, lt);
+    if (src.startsWith("<!--", lt)) {
+      const end2 = src.indexOf("-->", lt + 4);
+      i = end2 === -1 ? len : end2 + 3;
+      continue;
+    }
+    if (src.startsWith("<![CDATA[", lt)) {
+      const end2 = src.indexOf("]]>", lt + 9);
+      top().text.push(src.slice(lt + 9, end2 === -1 ? len : end2));
+      i = end2 === -1 ? len : end2 + 3;
+      continue;
+    }
+    if (src.startsWith("<!", lt)) {
+      i = skipDeclaration(src, lt);
+      continue;
+    }
+    if (src.startsWith("<?", lt)) {
+      const end2 = src.indexOf("?>", lt + 2);
+      const { name: name2, attrs: attrs2 } = parseTagBody(src.slice(lt + 2, end2 === -1 ? len : end2));
+      if (name2.length > 0) {
+        const frame2 = newFrame(`?${name2}`);
+        frame2.attrs = attrs2;
+        addChild(top(), frame2.name, finishFrame(frame2));
+      }
+      i = end2 === -1 ? len : end2 + 2;
+      continue;
+    }
+    if (src.startsWith("</", lt)) {
+      const end2 = src.indexOf(">", lt + 2);
+      closeElement(src.slice(lt + 2, end2 === -1 ? len : end2).trim());
+      i = end2 === -1 ? len : end2 + 1;
+      continue;
+    }
+    const end = findTagEnd(src, lt + 1);
+    const tagEnd = end === -1 ? len : end;
+    let body = src.slice(lt + 1, tagEnd);
+    const selfClosing = body.endsWith("/");
+    if (selfClosing) body = body.slice(0, -1);
+    const { name, attrs } = parseTagBody(body);
+    i = end === -1 ? len : end + 1;
+    if (name.length === 0) continue;
+    const frame = newFrame(name);
+    frame.attrs = attrs;
+    if (selfClosing) {
+      addChild(top(), name, finishFrame(frame));
+      continue;
+    }
+    if (stack.length > MAX_XML_DEPTH) {
+      throw new XmlTooDeepError(`XML nesting deeper than ${MAX_XML_DEPTH} elements; refusing to parse (this file is not something any office application produces)`);
+    }
+    stack.push(frame);
+  }
+  while (stack.length > 1) {
+    const frame = stack.pop();
+    addChild(top(), frame.name, finishFrame(frame));
+  }
+  return Object.fromEntries(root.children);
+}
+
+// src/ooxml_extract.ts
+var MAX_OOXML_WORK_MILLIS = MAX_DOCUMENT_WORK_MILLIS;
+var OoxmlTookTooLongError = class extends DocumentRefusedError {
+  constructor(message) {
+    super(message, "OoxmlTookTooLongError", true);
+  }
+};
+var NotAnOfficeDocumentError = class extends DocumentRefusedError {
+  constructor(message, cause) {
+    super(message, "NotAnOfficeDocumentError");
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+function ooxmlWorkDeadline() {
+  return Date.now() + MAX_OOXML_WORK_MILLIS;
+}
+function assertOoxmlWithinDeadline(deadline, hint) {
+  if (Date.now() > deadline) {
+    throw new OoxmlTookTooLongError(`reading this document's slides/sheets passed the ${MAX_OOXML_WORK_MILLIS}ms limit. ${hint}`);
+  }
+}
+var loadFflate = createLazyModuleLoader(
+  async () => await import("fflate"),
+  "office-file reading disabled (fflate unavailable)"
+);
+function accessFailureMessage(err, filePath) {
+  const code = err?.code;
+  if (code === "ENOENT") return `File not found: ${filePath}`;
+  return `could not read ${filePath} (${code ?? "unknown error"})`;
+}
+async function readOoxmlZip(filePath, kind) {
+  const fflate = await loadFflate();
+  if (!fflate) throw new Error("fflate is not installed; run `npm install fflate` to enable this command");
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch (err) {
+    throw new Error(accessFailureMessage(err, filePath), { cause: err });
+  }
+  if (!stat.isFile()) throw new NotAnOfficeDocumentError(`not a valid ${kind} file: ${filePath}`);
+  if (stat.size > MAX_ZIP_INPUT_BYTES) throw new ZipInputTooLargeError(filePath, stat.size, MAX_ZIP_INPUT_BYTES);
+  let data;
+  try {
+    data = fs.readFileSync(filePath);
+  } catch (err) {
+    throw new Error(accessFailureMessage(err, filePath), { cause: err });
+  }
+  try {
+    return unzipBounded(fflate, new Uint8Array(data), { limitBytes: MAX_ZIP_OUTPUT_BYTES, shouldExtract: () => true });
+  } catch (err) {
+    if (err instanceof ZipOutputTooLargeError) throw err;
+    throw new NotAnOfficeDocumentError(`not a valid ${kind} file: ${filePath}`, err);
+  }
+}
+var MAX_OOXML_PART_BYTES = 32 * 1024 * 1024;
+var OoxmlPartTooLargeError = class extends DocumentRefusedError {
+  constructor(entryPath, bytes) {
+    super(`${entryPath} is ${bytes} bytes, past the ${MAX_OOXML_PART_BYTES}-byte limit for one part of an office file. Split the document, or extract from a smaller copy.`, "OoxmlPartTooLargeError");
+  }
+};
+var MAX_OOXML_DOCUMENT_PART_BYTES = 64 * 1024 * 1024;
+var OoxmlDocumentTooLargeError = class extends DocumentRefusedError {
+  constructor(entryPath, spentBytes, partBytes) {
+    super(`decoding ${entryPath} (${partBytes} bytes, after ${spentBytes} already decoded) would take this office file past the ${MAX_OOXML_DOCUMENT_PART_BYTES}-byte limit on the XML one document may have decoded at once. Split the document, or extract from a smaller copy.`, "OoxmlDocumentTooLargeError");
+  }
+};
+function ooxmlPartBudget() {
+  return { spent: 0 };
+}
+function decodeZipEntry(entries, entryPath, budget) {
+  const bytes = entries[entryPath];
+  if (bytes === void 0) return null;
+  if (bytes.length > MAX_OOXML_PART_BYTES) throw new OoxmlPartTooLargeError(entryPath, bytes.length);
+  if (budget.spent + bytes.length > MAX_OOXML_DOCUMENT_PART_BYTES) throw new OoxmlDocumentTooLargeError(entryPath, budget.spent, bytes.length);
+  budget.spent += bytes.length;
+  return new TextDecoder("utf-8").decode(bytes);
+}
+async function parseOoxmlPart(xmlText) {
+  return parseXml(xmlText);
+}
+function pushTextValue(runs, val) {
+  if (Array.isArray(val)) {
+    for (const v of val) pushTextValue(runs, v);
+  } else if (typeof val === "string") {
+    runs.push(val);
+  } else if (typeof val === "number" || typeof val === "boolean") {
+    runs.push(String(val));
+  } else if (val !== null && typeof val === "object" && "#text" in val) {
+    runs.push(String(val["#text"]));
+  }
+}
+function collectTextRuns(node, tag) {
+  const runs = [];
+  function walk(n) {
+    if (Array.isArray(n)) {
+      n.forEach(walk);
+      return;
+    }
+    if (n !== null && typeof n === "object") {
+      const obj = n;
+      for (const [key, val] of Object.entries(obj)) {
+        if (key === tag) {
+          pushTextValue(runs, val);
+        } else if (val !== null && typeof val === "object") {
+          walk(val);
+        }
+      }
+    }
+  }
+  walk(node);
+  return runs;
+}
+function collectElements(node, tag) {
+  const out = [];
+  function walk(n) {
+    if (Array.isArray(n)) {
+      n.forEach(walk);
+      return;
+    }
+    if (n !== null && typeof n === "object") {
+      const obj = n;
+      for (const [key, val] of Object.entries(obj)) {
+        if (key === tag) {
+          if (Array.isArray(val)) pushAll(out, val);
+          else out.push(val);
+        } else if (val !== null && typeof val === "object") {
+          walk(val);
+        }
+      }
+    }
+  }
+  walk(node);
+  return out;
+}
+function sortNumberedParts(paths, pattern) {
+  return paths.map((p) => {
+    const m = pattern.exec(p);
+    return { p, n: m?.[1] !== void 0 ? parseInt(m[1], 10) : Number.MAX_SAFE_INTEGER };
+  }).sort((a, b) => a.n - b.n).map((x) => x.p);
+}
+
+export {
+  NotAnOfficeDocumentError,
+  ooxmlWorkDeadline,
+  assertOoxmlWithinDeadline,
+  readOoxmlZip,
+  ooxmlPartBudget,
+  decodeZipEntry,
+  parseOoxmlPart,
+  collectTextRuns,
+  collectElements,
+  sortNumberedParts
+};

package/dist/{token-goat-chunk-SBYRP3X4.mjs → token-goat-chunk-YTQHZJXW.mjs}

@@ -25,8 +25,7 @@ import {
   runSkeleton,
   runSymbol,
   withPinnedReads
-} from "./token-goat-chunk-4CK445AW.mjs";
-import "./token-goat-chunk-6F5TLJC7.mjs";
+} from "./token-goat-chunk-RUDOKYPJ.mjs";
 import {
   buildProjectMap,
   embeddingsDepsAvailable,
@@ -35,16 +34,28 @@ import {
   getProjectIndexCounts,
   isWorkerRunning,
   mapLookupBytesSaved
-} from "./token-goat-chunk-GM6QZWCF.mjs";
+} from "./token-goat-chunk-IT6O3PNN.mjs";
+import "./token-goat-chunk-VZYD4OZB.mjs";
+import "./token-goat-chunk-NEI4NC54.mjs";
+import "./token-goat-chunk-EG3663UT.mjs";
+import "./token-goat-chunk-3BTK54F3.mjs";
+import "./token-goat-chunk-XTQAOTSO.mjs";
+import "./token-goat-chunk-AH6QILZM.mjs";
+import "./token-goat-chunk-Y4AFKTHK.mjs";
+import "./token-goat-chunk-DBNY4RLN.mjs";
 import {
-  envStrList,
   getDb,
-  loadConfig,
   recordStat,
-  resolveProjectRoot,
   savedTokensFromBytes
-} from "./token-goat-chunk-TOGYS5A7.mjs";
+} from "./token-goat-chunk-T2IWWTHB.mjs";
+import {
+  envStrList,
+  loadConfig,
+  resolveProjectRoot
+} from "./token-goat-chunk-SAQ5PG4L.mjs";
 import "./token-goat-chunk-EEIDFMEM.mjs";
+import "./token-goat-chunk-HF6H7RNK.mjs";
+import "./token-goat-chunk-POBYR64E.mjs";
 import {
   ENV_KEYS,
   VERSION,
@@ -54,7 +65,8 @@ import {
   foldCaseForContainment,
   globalDbPath,
   normalizePath
-} from "./token-goat-chunk-LOCOX2ML.mjs";
+} from "./token-goat-chunk-AMYCQJX4.mjs";
+import "./token-goat-chunk-GMOUBOX4.mjs";
 import {
   init_define_import_meta_env
 } from "./token-goat-chunk-A37V4PBF.mjs";
@@ -242,7 +254,7 @@ function mcpToolAllowlist() {
   return names.length === 0 ? null : new Set(names);
 }
 async function createMcpServer() {
-  const [{ McpServer }, { z }] = await Promise.all([import("./token-goat-chunk-LHLQFGWQ.mjs"), import("./token-goat-chunk-T6M7DAW3.mjs")]);
+  const [{ McpServer }, { z }] = await Promise.all([import("./token-goat-chunk-OMNQUUIT.mjs"), import("./token-goat-chunk-T6M7DAW3.mjs")]);
   const server = new McpServer({ name: "token-goat", version: VERSION });
   const allowlist = mcpToolAllowlist();
   if (allowlist !== null) {
@@ -276,7 +288,8 @@ async function createMcpServer() {
         kind: z.string().optional().describe("restrict to one kind (function, class, ...)"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { name, limit, file, kind, json, projectRoot } = args;
@@ -314,7 +327,9 @@ async function createMcpServer() {
         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
-      }
+      },
+      // What readOnlyHint claims here, once, for all fifteen tools that carry it: the caller's own environment is untouched -- the project's files, and anything the caller would notice missing. Three things these tools do are deliberately outside that. They append a row to token-goat's `stats` table. They may reparse a file whose index entry is stale, and enqueue it for the background indexer. Opening a database for the first time creates its schema. All three are token-goat's own derived state, rebuilt from the project on demand and worth nothing if deleted; calling a symbol lookup a writing tool on their account would cost the caller a confirmation prompt for every read while protecting nothing. A tool that touches anything the caller owns says so instead, and the guard beside this file measures which tools those are rather than trusting the claim.
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { spec, json, forceRefresh, stats, projectRoot } = args;
@@ -343,7 +358,8 @@ async function createMcpServer() {
         spec: z.string().describe("file::Heading"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { spec, json, projectRoot } = args;
@@ -373,7 +389,8 @@ async function createMcpServer() {
         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
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { file, json, minLines, forceRefresh, stats, projectRoot } = args;
@@ -406,7 +423,8 @@ async function createMcpServer() {
         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
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { file, json, minLines, forceRefresh, stats, projectRoot } = args;
@@ -439,7 +457,9 @@ async function createMcpServer() {
         excludeTests: z.boolean().optional().describe("hide hits whose file is a test file (opt-in; default output is unchanged)"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: makeProjectRootField("search")
-      }
+      },
+      // 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 }
     },
     async (args) => {
       const { query, limit, grep, excludeTests, json, projectRoot } = args;
@@ -461,7 +481,8 @@ async function createMcpServer() {
       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.',
       inputSchema: {
         projectRoot: makeProjectRootField("check")
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { projectRoot } = args;
@@ -520,7 +541,8 @@ async function createMcpServer() {
         ),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { spec, callers, limit, top, json, projectRoot } = args;
@@ -554,7 +576,8 @@ async function createMcpServer() {
         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")
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { spec, limit, json, context, excludeTests, grep, projectRoot } = args;
@@ -584,7 +607,8 @@ async function createMcpServer() {
       inputSchema: {
         compact: z.boolean().optional().describe("compact, low-token summary"),
         projectRoot: makeProjectRootField("overview")
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { compact, projectRoot } = args;
@@ -604,7 +628,8 @@ async function createMcpServer() {
         symbolMode: z.boolean().optional().describe("list symbols instead of files"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { ref, symbolMode, json, projectRoot } = args;
@@ -631,7 +656,8 @@ async function createMcpServer() {
         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")
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { pattern, path: searchPath, maxLines, json, recursive, context, projectRoot } = args;
@@ -663,7 +689,8 @@ async function createMcpServer() {
         file: z.string().describe("file path"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { file, json, projectRoot } = args;
@@ -686,7 +713,8 @@ async function createMcpServer() {
         file: z.string().describe("file path"),
         json: z.boolean().optional().describe("output as JSON"),
         projectRoot: projectRootField
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const { file, json, projectRoot } = args;
@@ -707,7 +735,9 @@ async function createMcpServer() {
       description: "Compress arbitrary local text, persist it in the bounded local cache, and return an opaque recovery ID plus metadata.",
       inputSchema: {
         text: z.string().max(CONTENT_MAX_INPUT_CHARS).describe("text to compress")
-      }
+      },
+      // destructiveHint is true for every tool that writes here, including the ones that only ever add: the store is bounded by item count and by total bytes, so a write can evict an earlier entry and leave a recovery id the caller is holding unredeemable. idempotentHint survives a repeat writing a fresh timestamp and another stats row, on the same reading of "its environment" set out on the read tool above.
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     (args) => toCallToolResult({ text: displaySafeJson(compressionPayload(compressText(args.text))), code: 0 })
   );
@@ -717,7 +747,8 @@ async function createMcpServer() {
       description: "Retrieve original text from a token-goat compression ID.",
       inputSchema: {
         id: z.string().regex(/^tg_[0-9a-f]{16}$/).describe("opaque token-goat content ID")
-      }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
     },
     (args) => {
       const text = retrieveText(args.id);
@@ -732,7 +763,8 @@ async function createMcpServer() {
         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")
-      }
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
     },
     (args) => toCallToolResult({
       text: displaySafeJson(createHandoff(args.name, args.text, resolveToolRoot(args.projectRoot))),
@@ -747,7 +779,9 @@ async function createMcpServer() {
         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")
-      }
+      },
+      // 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 }
     },
     (args) => {
       const result = resolveHandoff(args.name, {