@skein-code/cli 0.3.17 → 0.3.19

package/README.md

@@ -441,10 +441,24 @@ npm run benchmark:context -- \
 ```
 
 It reports Recall@5/10/20, MRR, useful-token ratio, stale-hit rate, and cold,
-incremental, and warm-query latency. The included fixture only validates the
-metric pipeline; it is not evidence for performance on a production repository.
-`--fresh-index` deletes and rebuilds that workspace's local index, so use it only
-where rebuilding the index is intended.
+incremental, and warm-query latency. `context-benchmark-v2` covers TypeScript,
+Python, SQL, CJK, Markdown, mixed-language queries, and a TypeScript import
+neighbor that has no direct lexical match. Its checked-in thresholds fail the
+command instead of allowing a retrieval change to lower the quality bar.
+
+The persisted local index now stores content-addressed TypeScript compiler AST
+facts for definitions, calls, and relative imports. Matching definitions can
+expand a query and import/call neighbors may receive a bounded graph score;
+Python and SQL continue to use explicit syntax-aware fallbacks. Search and
+context JSON expose the index generation, file hash, matched/expanded terms,
+and bm25/path/symbol/phrase/graph breakdown without persisting the query or an
+additional copy of source. Index schema v2 artifacts rebuild as v3 rather than
+being trusted after the parser contract changes.
+
+The included fixture is a deterministic regression gate, not evidence for
+performance on every production repository. `--fresh-index` deletes and
+rebuilds that workspace's local index, so use it only where rebuilding the
+index is intended.
 
 ## Safety model
 

package/dist/cli.js

@@ -220,7 +220,7 @@ function isSqliteBusy(error) {
 // package.json
 var package_default = {
   name: "@skein-code/cli",
-  version: "0.3.17",
+  version: "0.3.19",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,6 +236,12 @@ var package_default = {
   },
   skein: {
     releaseNotes: [
+      "Local index v3 records TypeScript AST definitions, calls, and relative import adjacency for graph-assisted retrieval",
+      "Context hits expose generation, content hash, matched terms, and bm25/path/symbol/phrase/graph score provenance",
+      "Context benchmark v2 locks multilingual recall, MRR, useful-token, stale-hit, incremental-index, and warm-latency gates",
+      "Large MCP catalogs now disclose at most eight request-relevant schemas per run while preserving network permissions",
+      "Token Ledger receipts report deferred progressive schemas and selected definitions remain stable across tool turns",
+      "A deterministic Token Economy replay benchmark guards evidence, output-firewall, and no-progress invariants",
       "Calibrated Type-1/2 duplication matches now block completion until reuse or exact audited suppression",
       "Type-3 duplication remains warning-only and Type-4 semantic equivalence remains explicitly unsupported",
       "Duplication benchmark fixtures report deterministic recall, precision, false-positive rate, and latency",
@@ -278,6 +284,7 @@ var package_default = {
     "test:pty": "sh test/pty/run-visual.sh",
     "benchmark:context": "tsx scripts/benchmark-local-index.ts",
     "benchmark:duplication": "tsx scripts/benchmark-duplication.ts",
+    "benchmark:token-economy": "tsx scripts/benchmark-token-economy.ts",
     "verify:package": "node scripts/verify-package.mjs",
     "release:verify": "npm run check && npm run verify:package --",
     typecheck: "tsc --noEmit",
@@ -297,6 +304,7 @@ var package_default = {
     react: "^19.2.3",
     "string-width": "^8.2.2",
     "strip-ansi": "^7.2.0",
+    typescript: "^5.9.3",
     yaml: "^2.8.2",
     zod: "^4.4.3"
   },
@@ -306,7 +314,6 @@ var package_default = {
     "@types/react": "^19.2.7",
     tsup: "^8.5.1",
     tsx: "^4.21.0",
-    typescript: "^5.9.3",
     vitest: "^4.0.18"
   },
   overrides: {
@@ -2606,8 +2613,9 @@ function countExplicitPaths(value) {
 // src/context/local-index.ts
 import { createHash as createHash6 } from "node:crypto";
 import { lstat as lstat8, readFile as readFile3, stat as stat3 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname7, extname as extname2, isAbsolute as isAbsolute3, join as join7, relative as relative5, resolve as resolve8, sep as sep4 } from "node:path";
+import { basename as basename5, dirname as dirname7, extname as extname2, isAbsolute as isAbsolute3, join as join7, posix, relative as relative5, resolve as resolve8, sep as sep4 } from "node:path";
 import fg from "fast-glob";
+import ts from "typescript";
 import { z as z3 } from "zod";
 
 // src/tools/workspace.ts
@@ -3059,10 +3067,13 @@ var indexedFileSchema = z3.object({
   ctimeMs: z3.number().optional(),
   size: z3.number().nonnegative(),
   contentHash: contentHashSchema,
-  chunks: z3.array(indexedChunkSchema)
+  chunks: z3.array(indexedChunkSchema),
+  definitions: z3.array(z3.string()),
+  references: z3.array(z3.string()),
+  imports: z3.array(z3.string())
 }).strict();
 var localIndexSchema = z3.object({
-  version: z3.literal(2),
+  version: z3.literal(3),
   createdAt: z3.string(),
   generation: z3.string().min(1),
   roots: z3.array(z3.string()),
@@ -3108,6 +3119,8 @@ var LocalContextIndex = class {
   index;
   workspace;
   queryCache = /* @__PURE__ */ new Map();
+  queryCacheHits = 0;
+  queryCacheMisses = 0;
   fingerprintCache;
   dirtyPaths = /* @__PURE__ */ new Set();
   refreshState = "current";
@@ -3253,7 +3266,7 @@ var LocalContextIndex = class {
         const nextFiles = [...files.values()].sort((left, right) => left.absolutePath.localeCompare(right.absolutePath));
         const generation = createGeneration(nextFiles);
         this.index = {
-          version: 2,
+          version: 3,
           createdAt: (/* @__PURE__ */ new Date()).toISOString(),
           generation,
           roots: this.roots,
@@ -3305,6 +3318,8 @@ var LocalContextIndex = class {
       files: this.index?.files.length ?? 0,
       chunks: this.index?.files.reduce((total, file) => total + file.chunks.length, 0) ?? 0,
       queryCacheEntries: this.queryCache.size,
+      queryCacheHits: this.queryCacheHits,
+      queryCacheMisses: this.queryCacheMisses,
       refreshState: this.refreshState,
       dirtyPaths: this.dirtyPaths.size,
       ...this.refreshError ? { refreshError: this.refreshError } : {},
@@ -3387,12 +3402,13 @@ var LocalContextIndex = class {
         ctimeMs: info.ctimeMs,
         size: info.size,
         contentHash,
-        chunks: chunkFile(safeItem, content)
+        chunks: chunkFile(safeItem, content),
+        ...extractSourceFacts(safeItem.path, content)
       });
     }
     const generation = createGeneration(files);
     this.index = {
-      version: 2,
+      version: 3,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
       generation,
       roots: this.roots,
@@ -3457,7 +3473,8 @@ var LocalContextIndex = class {
         ctimeMs: info.ctimeMs,
         size: info.size,
         contentHash: hashContent(content),
-        chunks: chunkFile(safeItem, content)
+        chunks: chunkFile(safeItem, content),
+        ...extractSourceFacts(safeItem.path, content)
       };
     } catch {
       return void 0;
@@ -3480,7 +3497,8 @@ var LocalContextIndex = class {
           path: file.path,
           absolutePath: file.absolutePath
         }, content);
-        if (!chunksMatch(expectedChunks, file.chunks)) return false;
+        const expectedFacts = extractSourceFacts(file.path, content);
+        if (!chunksMatch(expectedChunks, file.chunks) || !sameStrings(expectedFacts.definitions, file.definitions) || !sameStrings(expectedFacts.references, file.references) || !sameStrings(expectedFacts.imports, file.imports)) return false;
       } catch {
         return false;
       }
@@ -3520,10 +3538,14 @@ var LocalContextIndex = class {
     return matches.length === 1 ? { root, path, absolutePath } : void 0;
   }
   rank(query, topK) {
-    const chunks = (this.index?.files ?? []).flatMap((file) => file.chunks);
+    const index = this.index;
+    const files = index?.files ?? [];
+    const chunks = files.flatMap((file) => file.chunks);
     if (!chunks.length) return [];
-    const terms = [...new Set(tokenize(query))];
-    if (!terms.length) return [];
+    const directTerms = [...new Set(tokenize(query))];
+    if (!directTerms.length || !index) return [];
+    const expandedTerms = expandQueryTerms(files, directTerms);
+    const terms = [.../* @__PURE__ */ new Set([...directTerms, ...expandedTerms])];
     const queryTerms = new Set(terms);
     const documentFrequency = new Map([...queryTerms].map((term) => [term, 0]));
     for (const chunk of chunks) {
@@ -3532,22 +3554,51 @@ var LocalContextIndex = class {
       }
     }
     const averageLength = chunks.reduce((sum, chunk) => sum + chunk.tokens.length, 0) / Math.max(chunks.length, 1);
-    return chunks.map((chunk) => ({ chunk, score: scoreChunk(
-      chunk,
-      terms,
-      query,
-      documentFrequency,
-      chunks.length,
-      averageLength
-    ) })).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.chunk.absolutePath.localeCompare(right.chunk.absolutePath)).slice(0, topK).map(({ chunk, score }) => ({
-      path: chunk.absolutePath,
-      startLine: chunk.startLine,
-      endLine: chunk.endLine,
-      content: chunk.content,
-      score,
-      source: "local-bm25+path+symbol",
-      ...chunk.symbol ? { symbol: chunk.symbol } : {}
-    }));
+    const filesByPath = new Map(files.map((file) => [file.absolutePath, file]));
+    const graphBoosts = buildGraphBoosts(files, directTerms);
+    const coverageTerms = directTerms.filter((term) => !retrievalStopWords.has(term));
+    const scored = chunks.map((chunk) => {
+      const lexical = scoreChunk(
+        chunk,
+        terms,
+        query,
+        documentFrequency,
+        chunks.length,
+        averageLength
+      );
+      const graph = graphBoosts.get(chunk.absolutePath)?.score ?? 0;
+      const score = lexical.bm25 + lexical.path + lexical.symbol + lexical.phrase + graph;
+      return { chunk, lexical, graph, score };
+    }).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.chunk.absolutePath.localeCompare(right.chunk.absolutePath));
+    const covered = scored.filter(({ lexical, graph }) => graph > 0 || hasSufficientQueryCoverage(lexical.matchedTerms, coverageTerms));
+    return (covered.length ? covered : scored).slice(0, topK).map(({ chunk, lexical, graph, score }) => {
+      const file = filesByPath.get(chunk.absolutePath);
+      const breakdown = {
+        bm25: roundScore(lexical.bm25),
+        path: roundScore(lexical.path),
+        symbol: roundScore(lexical.symbol),
+        phrase: roundScore(lexical.phrase),
+        graph: roundScore(graph),
+        total: roundScore(score)
+      };
+      const provenance = {
+        generation: index.generation,
+        contentHash: file?.contentHash ?? hashContent(chunk.content),
+        matchedTerms: lexical.matchedTerms.slice(0, 16),
+        expandedTerms: expandedTerms.slice(0, 16),
+        score: breakdown
+      };
+      return {
+        path: chunk.absolutePath,
+        startLine: chunk.startLine,
+        endLine: chunk.endLine,
+        content: chunk.content,
+        score,
+        source: "local-bm25+path+symbol+graph",
+        ...chunk.symbol ? { symbol: chunk.symbol } : {},
+        provenance
+      };
+    });
   }
   async hitsAreCurrent(hits) {
     const files = new Map((this.index?.files ?? []).map((file) => [file.absolutePath, file]));
@@ -3571,10 +3622,17 @@ var LocalContextIndex = class {
   }
   getCachedHits(query, topK) {
     const generation = this.index?.generation;
-    if (!generation) return void 0;
+    if (!generation) {
+      this.queryCacheMisses += 1;
+      return void 0;
+    }
     const key = `${generation}\0${topK}\0${query}`;
     const cached = this.queryCache.get(key);
-    if (!cached) return void 0;
+    if (!cached) {
+      this.queryCacheMisses += 1;
+      return void 0;
+    }
+    this.queryCacheHits += 1;
     this.queryCache.delete(key);
     this.queryCache.set(key, cached);
     return cloneHits(cached);
@@ -3670,6 +3728,9 @@ function chunksMatch(expected, actual) {
     return Boolean(candidate) && chunk.id === candidate?.id && chunk.root === candidate.root && chunk.path === candidate.path && chunk.absolutePath === candidate.absolutePath && chunk.startLine === candidate.startLine && chunk.endLine === candidate.endLine && chunk.content === candidate.content && chunk.symbol === candidate.symbol && chunk.tokens.length === candidate.tokens.length && chunk.tokens.every((token, tokenIndex) => token === candidate.tokens[tokenIndex]);
   });
 }
+function sameStrings(expected, actual) {
+  return expected.length === actual.length && expected.every((value, index) => value === actual[index]);
+}
 function existingBuildResult(status, started) {
   if (!status.available || !status.generation) {
     throw new Error("The existing local context index is unavailable.");
@@ -3724,7 +3785,8 @@ function packContextHits(hits, roots, maxTokens, engine) {
   const text = selected.map((hit) => {
     const shownPath = workspaceAliasPath(hit.path, roots);
     const symbol = hit.symbol ? ` symbol="${escapeAttribute(hit.symbol)}"` : "";
-    return `<code path="${escapeAttribute(shownPath)}" lines="${hit.startLine}-${hit.endLine}" score="${hit.score.toFixed(3)}"${symbol}>
+    const provenance = hit.provenance ? ` source="${escapeAttribute(hit.source)}" hash="${hit.provenance.contentHash.slice(0, 12)}" graph-score="${hit.provenance.score.graph.toFixed(3)}"` : "";
+    return `<code path="${escapeAttribute(shownPath)}" lines="${hit.startLine}-${hit.endLine}" score="${hit.score.toFixed(3)}"${symbol}${provenance}>
 ${hit.content}
 </code>`;
   }).join("\n\n");
@@ -3740,7 +3802,17 @@ ${hit.content}
   };
 }
 function cloneHits(hits) {
-  return hits.map((hit) => ({ ...hit }));
+  return hits.map((hit) => ({
+    ...hit,
+    ...hit.provenance ? {
+      provenance: {
+        ...hit.provenance,
+        matchedTerms: [...hit.provenance.matchedTerms],
+        expandedTerms: [...hit.provenance.expandedTerms],
+        score: { ...hit.provenance.score }
+      }
+    } : {}
+  }));
 }
 function cloneDuplicationBaseline(baseline) {
   return {
@@ -3842,6 +3914,109 @@ function detectSymbol(lines) {
   }
   return void 0;
 }
+function extractSourceFacts(path, content) {
+  const extension = extname2(path).toLocaleLowerCase();
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(extension)) {
+    return extractTypeScriptFacts(path, content);
+  }
+  if (extension === ".py") return extractPythonFacts(content);
+  if (extension === ".sql") return extractSqlFacts(content);
+  return { definitions: [], references: [], imports: [] };
+}
+function extractTypeScriptFacts(path, content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  const source = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, false, scriptKind(path));
+  const addName = (name) => {
+    if (!name) return;
+    if (ts.isIdentifier(name)) definitions.add(name.text);
+    else if (ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) definitions.add(name.text);
+    else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+      for (const element of name.elements) if (ts.isBindingElement(element)) addName(element.name);
+    }
+  };
+  const addCallReference = (expression) => {
+    if (ts.isIdentifier(expression)) references.add(expression.text);
+    else if (ts.isPropertyAccessExpression(expression)) references.add(expression.name.text);
+    else if (ts.isElementAccessExpression(expression) && ts.isIdentifier(expression.expression)) {
+      references.add(expression.expression.text);
+    }
+  };
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) imports.add(node.moduleSpecifier.text);
+    } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && node.moduleReference.expression && ts.isStringLiteral(node.moduleReference.expression)) {
+      imports.add(node.moduleReference.expression.text);
+    } else if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) {
+      addName(node.name);
+    } else if (ts.isVariableDeclaration(node) || ts.isBindingElement(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
+      addName(node.name);
+    } else if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+      addCallReference(node.expression);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function scriptKind(path) {
+  switch (extname2(path).toLocaleLowerCase()) {
+    case ".tsx":
+      return ts.ScriptKind.TSX;
+    case ".jsx":
+      return ts.ScriptKind.JSX;
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return ts.ScriptKind.JS;
+    default:
+      return ts.ScriptKind.TS;
+  }
+}
+function extractPythonFacts(content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  for (const line of content.split("\n")) {
+    const definition = line.match(/^\s*(?:async\s+)?(?:def|class)\s+([\p{L}_][\p{L}\p{N}_]*)/u);
+    if (definition?.[1]) definitions.add(definition[1]);
+    const imported = line.match(/^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))/u);
+    if (imported?.[1] || imported?.[2]) imports.add(imported[1] ?? imported[2] ?? "");
+    for (const call of line.matchAll(/([\p{L}_][\p{L}\p{N}_]*)\s*\(/gu)) {
+      if (call[1] && !["def", "class", "if", "for", "while"].includes(call[1])) references.add(call[1]);
+    }
+  }
+  for (const definition of definitions) references.delete(definition);
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function extractSqlFacts(content) {
+  const definitions = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  const imports = /* @__PURE__ */ new Set();
+  for (const definition of content.matchAll(/\bcreate\s+(?:table|view|function|procedure)\s+(?:if\s+not\s+exists\s+)?([\w.]+)/giu)) {
+    if (definition[1]) definitions.add(definition[1]);
+  }
+  for (const reference2 of content.matchAll(/\b(?:from|join|update|into)\s+([\w.]+)/giu)) {
+    if (reference2[1]) references.add(reference2[1]);
+  }
+  return {
+    definitions: sortedValues(definitions),
+    references: sortedValues(references),
+    imports: sortedValues(imports)
+  };
+}
+function sortedValues(values) {
+  return [...values].filter(Boolean).sort((left, right) => left.localeCompare(right));
+}
 function tokenize(input2) {
   const normalized = input2.replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([\p{Ll}])([\p{Lu}])/gu, "$1 $2").toLocaleLowerCase();
   const base = normalized.match(/[\p{L}\p{N}_-]+/gu) ?? [];
@@ -3857,24 +4032,123 @@ function tokenize(input2) {
   }
   return output2;
 }
+var retrievalStopWords = /* @__PURE__ */ new Set([
+  "add",
+  "audit",
+  "change",
+  "code",
+  "create",
+  "explain",
+  "find",
+  "fix",
+  "implement",
+  "inspect",
+  "review",
+  "show",
+  "test",
+  "the",
+  "update",
+  "where",
+  "with",
+  "\u4FEE\u6539",
+  "\u4FEE\u590D",
+  "\u5B9E\u73B0",
+  "\u5BA1\u67E5",
+  "\u67E5\u627E",
+  "\u89E3\u91CA",
+  "\u6D4B\u8BD5",
+  "\u66F4\u65B0"
+]);
+function hasSufficientQueryCoverage(matchedTerms, coverageTerms) {
+  if (!coverageTerms.length) return matchedTerms.length > 0;
+  const matched = new Set(matchedTerms);
+  const covered = [...new Set(coverageTerms)].filter((term) => matched.has(term)).length;
+  return covered >= Math.min(2, new Set(coverageTerms).size);
+}
+function expandQueryTerms(files, directTerms) {
+  const expanded = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    for (const definition of file.definitions) {
+      const definitionTerms = [...new Set(tokenize(definition))];
+      if (!definitionMatchesQuery(definitionTerms, directTerms)) continue;
+      for (const term of definitionTerms) if (!directTerms.includes(term)) expanded.add(term);
+    }
+  }
+  return [...expanded].sort((left, right) => left.localeCompare(right)).slice(0, 24);
+}
+function buildGraphBoosts(files, directTerms) {
+  const anchors = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    for (const definition of file.definitions) {
+      if (!definitionMatchesQuery(tokenize(definition), directTerms)) continue;
+      const values = anchors.get(file.absolutePath) ?? /* @__PURE__ */ new Set();
+      values.add(definition.toLocaleLowerCase());
+      anchors.set(file.absolutePath, values);
+    }
+  }
+  if (!anchors.size) return /* @__PURE__ */ new Map();
+  const boosts = /* @__PURE__ */ new Map();
+  const addBoost = (path, score) => {
+    boosts.set(path, { score: (boosts.get(path)?.score ?? 0) + score });
+  };
+  const anchorSymbols = new Set([...anchors.values()].flatMap((symbols) => [...symbols]));
+  for (const file of files) {
+    if (file.references.some((reference2) => anchorSymbols.has(reference2.toLocaleLowerCase()))) {
+      addBoost(file.absolutePath, 1.5);
+    }
+    for (const specifier of file.imports) {
+      for (const target of resolveImportTargets(file, specifier, files)) {
+        if (anchors.has(target)) addBoost(file.absolutePath, 1.25);
+        if (anchors.has(file.absolutePath)) addBoost(target, 0.75);
+      }
+    }
+  }
+  return boosts;
+}
+function definitionMatchesQuery(definitionTerms, queryTerms) {
+  const definitions = new Set(definitionTerms);
+  const shared = [...new Set(queryTerms)].filter((term) => definitions.has(term));
+  const required = Math.min(2, Math.max(1, Math.min(definitions.size, queryTerms.length)));
+  return shared.length >= required;
+}
+function resolveImportTargets(importer, specifier, files) {
+  if (!specifier.startsWith(".")) return [];
+  const base = posix.normalize(posix.join(posix.dirname(importer.path), specifier));
+  const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+  const importedExtension = posix.extname(base);
+  const extensionless = extensions.includes(importedExtension) ? base.slice(0, -importedExtension.length) : base;
+  const candidates = /* @__PURE__ */ new Set([
+    base,
+    ...extensions.map((extension) => `${extensionless}${extension}`),
+    ...extensions.map((extension) => posix.join(extensionless, `index${extension}`))
+  ]);
+  return files.filter((file) => file.root === importer.root && candidates.has(file.path)).map((file) => file.absolutePath);
+}
 function scoreChunk(chunk, terms, rawQuery, documentFrequency, documentCount, averageLength) {
   const frequencies = /* @__PURE__ */ new Map();
   for (const token of chunk.tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
   const k1 = 1.2;
   const b = 0.75;
-  let score = 0;
+  let bm25 = 0;
+  let path = 0;
+  let symbol = 0;
+  const matchedTerms = [];
   for (const term of terms) {
     const frequency = frequencies.get(term) ?? 0;
     if (!frequency) continue;
+    matchedTerms.push(term);
     const df = documentFrequency.get(term) ?? 0;
     const idf = Math.log(1 + (documentCount - df + 0.5) / (df + 0.5));
-    score += idf * (frequency * (k1 + 1) / (frequency + k1 * (1 - b + b * chunk.tokens.length / averageLength)));
-    if (chunk.path.toLocaleLowerCase().includes(term)) score += 1.5;
-    if (chunk.symbol?.toLocaleLowerCase().includes(term)) score += 2.5;
+    bm25 += idf * (frequency * (k1 + 1) / (frequency + k1 * (1 - b + b * chunk.tokens.length / averageLength)));
+    if (chunk.path.toLocaleLowerCase().includes(term)) path += 1.5;
+    if (chunk.symbol?.toLocaleLowerCase().includes(term)) symbol += 2.5;
   }
   const phrase = rawQuery.trim().toLocaleLowerCase();
-  if (phrase.length > 3 && chunk.content.toLocaleLowerCase().includes(phrase)) score += 3;
-  return score;
+  const phraseScore = phrase.length > 3 && chunk.content.toLocaleLowerCase().includes(phrase) ? 3 : 0;
+  return { bm25, path, symbol, phrase: phraseScore, matchedTerms };
+}
+function roundScore(value) {
+  return Number(value.toFixed(6));
 }
 
 // src/context/context-engine.ts
@@ -3985,7 +4259,10 @@ function formatContextHits(hits, roots) {
   return hits.map((hit) => {
     const path = workspaceAliasPath(hit.path, roots);
     const symbol = hit.symbol ? ` ${hit.symbol}` : "";
-    return `[${hit.source} ${hit.score.toFixed(3)}]${symbol} ${path}:${hit.startLine}-${hit.endLine}`;
+    const score = hit.provenance?.score;
+    const breakdown = score ? ` bm25=${score.bm25.toFixed(2)} path=${score.path.toFixed(2)} symbol=${score.symbol.toFixed(2)} graph=${score.graph.toFixed(2)}` : "";
+    const hash4 = hit.provenance?.contentHash.slice(0, 12);
+    return `[${hit.source} ${hit.score.toFixed(3)}${breakdown}${hash4 ? ` hash=${hash4}` : ""}]${symbol} ${path}:${hit.startLine}-${hit.endLine}`;
   }).join("\n");
 }
 
@@ -9715,7 +9992,7 @@ async function evaluateReuseGate(input2) {
     candidates.push({
       path: hit.path,
       ...hit.symbol ? { symbol: hit.symbol.slice(0, 160) } : {},
-      score: roundScore(hit.score),
+      score: roundScore2(hit.score),
       read
     });
   }
@@ -9823,7 +10100,7 @@ function unresolvedReceipt(input2, queryHash, targetPaths, trigger, detail) {
 function hash3(value) {
   return createHash13("sha256").update(value).digest("hex");
 }
-function roundScore(value) {
+function roundScore2(value) {
   return Number.isFinite(value) ? Math.round(value * 1e3) / 1e3 : 0;
 }
 
@@ -10085,6 +10362,7 @@ var AgentRunner = class {
     };
     const changeSequenceAtStart = this.changeSequence;
     const runStartedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const loadedProgressiveTools = /* @__PURE__ */ new Set();
     const runChangedFiles = /* @__PURE__ */ new Set();
     const verificationEvidence = [];
     const toolRecovery = new ToolRecoveryController();
@@ -10248,7 +10526,9 @@ var AgentRunner = class {
           activeDuplicationMatchIds(
             this.session.audit ?? [],
             this.session.duplicationSuppressions ?? []
-          ).size > 0
+          ).size > 0,
+          request,
+          loadedProgressiveTools
         );
         const estimatedInputTokens = estimateMessages2(messages) + estimateToolDefinitions(visibleTools);
         if (availableTokens <= 0 || estimatedInputTokens >= availableTokens) {
@@ -10313,7 +10593,10 @@ var AgentRunner = class {
           },
           inputSource: actualInputTokens === void 0 ? "estimated" : "actual",
           outputSource: actualOutputTokens === void 0 ? "estimated" : "actual",
-          tools: { loaded: visibleTools.map((tool) => tool.name), deferredCount: 0 },
+          tools: {
+            loaded: visibleTools.map((tool) => tool.name),
+            deferredCount: Math.max(0, this.tools.definitions().filter((tool) => tool.progressive).length - visibleTools.filter((tool) => tool.progressive).length)
+          },
           retrieval: tokenRetrievalReceipt(packed)
         });
         await emit({
@@ -11079,10 +11362,25 @@ ${content}` : content,
     ...failure ? { metadata: { failure } } : {}
   };
 }
-function visibleToolDefinitions(tools, askMode, contractEnabled, artifactReadAvailable, duplicationAvailable) {
-  return tools.definitions().filter(
+function visibleToolDefinitions(tools, askMode, contractEnabled, artifactReadAvailable, duplicationAvailable, request, loadedProgressiveTools) {
+  const eligible = tools.definitions().filter(
     (tool) => (!askMode || tool.category === "read") && (contractEnabled || tool.name !== "task_contract") && (artifactReadAvailable || tool.name !== "read_tool_artifact") && (duplicationAvailable || tool.name !== "duplication_audit")
   );
+  const progressive = eligible.filter((tool) => tool.progressive);
+  if (progressive.length <= 8) return eligible;
+  for (const tool of selectProgressiveTools(progressive, request, 8)) {
+    loadedProgressiveTools.add(tool.name);
+  }
+  return eligible.filter((tool) => !tool.progressive || loadedProgressiveTools.has(tool.name));
+}
+function selectProgressiveTools(tools, request, limit) {
+  const terms = new Set(request.toLocaleLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) ?? []);
+  return tools.map((tool) => {
+    const searchable = `${tool.name.replaceAll("_", " ")} ${tool.description}`.toLocaleLowerCase();
+    let score = 0;
+    for (const term of terms) if (searchable.includes(term)) score += term.length;
+    return { tool, score };
+  }).sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name)).slice(0, limit).map(({ tool }) => tool);
 }
 function formatToolError(error) {
   const normalized = toError(error);
@@ -18995,7 +19293,8 @@ function createMcpToolAdapter(options) {
       // MCP servers are an external trust boundary. Read-only annotations are
       // hints from that server and must not lower the local permission level.
       category: "network",
-      inputSchema: inputSchema13
+      inputSchema: inputSchema13,
+      progressive: true
     },
     permissionCategories: () => ["network"],
     async execute(arguments_, context) {