opencode-codebase-index 0.22.2 → 0.22.4

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// opencode-codebase-index - Semantic codebase search for OpenCode
+// open-codebase-index - Semantic codebase indexing and search
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -1277,6 +1277,7 @@ function createSummaryMarkdown(summary, comparison, gate, sweep) {
   lines.push(`| Hit@10 | ${formatPct(summary.metrics.hitAt10)} |`);
   lines.push(`| MRR@10 | ${summary.metrics.mrrAt10.toFixed(4)} |`);
   lines.push(`| nDCG@10 | ${summary.metrics.ndcgAt10.toFixed(4)} |`);
+  lines.push(`| Graph-neighbor recall | ${(summary.metrics.graphNeighborRecall ?? 0).toFixed(4)} |`);
   lines.push(`| Distinct Top@3 | ${formatPct(summary.metrics.distinctTop3Ratio)} |`);
   lines.push(`| Raw Distinct Top@3 | ${formatPct(summary.metrics.rawDistinctTop3Ratio)} |`);
   lines.push(`| Latency p50 | ${formatMs(summary.metrics.latencyMs.p50)} |`);
@@ -6640,12 +6641,12 @@ function diversifyGroupBySymbol(entries, getCandidate) {
   return [...primary, ...remainder];
 }
 function buildDiversityKey(metadata) {
-  const normalizedPath = metadata.filePath.toLowerCase();
+  const normalizedPath3 = metadata.filePath.toLowerCase();
   const normalizedName = (metadata.name ?? "").trim().toLowerCase();
   if (normalizedName.length > 0) {
-    return `${normalizedPath}#${normalizedName}`;
+    return `${normalizedPath3}#${normalizedName}`;
   }
-  return normalizedPath;
+  return normalizedPath3;
 }
 function rankHybridResults(query, semanticResults, keywordResults, options) {
   const prioritizeSourcePaths = options.prioritizeSourcePaths ?? classifyQueryIntentRaw(query) === "source";
@@ -7094,9 +7095,9 @@ function normalizeFilePathForHintMatch(filePath) {
   return filePath.replace(/\\/g, "/").toLowerCase().replace(/^\.\//, "");
 }
 function pathMatchesHint(filePath, hint) {
-  const normalizedPath = normalizeFilePathForHintMatch(filePath);
+  const normalizedPath3 = normalizeFilePathForHintMatch(filePath);
   const normalizedHint = normalizeFilePathForHintMatch(hint);
-  return normalizedPath.endsWith(normalizedHint) || normalizedPath.includes(`/${normalizedHint}`) || normalizedPath.includes(normalizedHint);
+  return normalizedPath3.endsWith(normalizedHint) || normalizedPath3.includes(`/${normalizedHint}`) || normalizedPath3.includes(normalizedHint);
 }
 function extractFilePathHint(query) {
   const match = query.match(FILE_PATH_HINT_SUFFIX_REGEX);
@@ -11370,6 +11371,20 @@ var Indexer = class _Indexer {
       requestedLimit = nextLimit;
     }
   }
+  buildCandidateSnapshot(candidate) {
+    return {
+      id: candidate.id,
+      filePath: candidate.metadata.filePath,
+      startLine: candidate.metadata.startLine,
+      endLine: candidate.metadata.endLine,
+      score: candidate.score,
+      chunkType: candidate.metadata.chunkType,
+      name: candidate.metadata.name
+    };
+  }
+  buildCandidateSnapshotList(candidates) {
+    return candidates.map((candidate) => this.buildCandidateSnapshot(candidate));
+  }
   searchSemanticCandidates(store, embedding, initialLimit, branchChunkIds, shouldPrefilterByBranch) {
     return this.searchCandidatesWithBranchPrefilter(
       initialLimit,
@@ -11561,6 +11576,16 @@ var Indexer = class _Indexer {
       prefilterMs: Math.round(prefilterMs * 100) / 100,
       fusionMs: Math.round(fusionMs * 100) / 100
     });
+    if (options?.trace) {
+      options.trace({
+        semanticCandidates: this.buildCandidateSnapshotList(scopedSemanticCandidates),
+        keywordCandidates: this.buildCandidateSnapshotList(scopedKeywordCandidates),
+        hybridCandidates: this.buildCandidateSnapshotList(combined),
+        postExternalRerankCandidates: this.buildCandidateSnapshotList(rerankedCombined),
+        tieredCandidates: this.buildCandidateSnapshotList(tiered),
+        finalCandidates: this.buildCandidateSnapshotList(finalResults)
+      });
+    }
     const metadataOnly = options?.metadataOnly ?? false;
     return Promise.all(
       finalResults.map(async (r) => {
@@ -12609,6 +12634,42 @@ var Indexer = class _Indexer {
   }
 };
 
+// src/tools/contracts.ts
+var CHUNK_TYPES = [
+  "function",
+  "class",
+  "method",
+  "interface",
+  "type",
+  "enum",
+  "struct",
+  "impl",
+  "trait",
+  "module",
+  "other"
+];
+var CALL_GRAPH_DIRECTIONS = ["callers", "callees"];
+var RELATIONSHIP_TYPES = [
+  "Call",
+  "MethodCall",
+  "Constructor",
+  "Import",
+  "Inherits",
+  "Implements"
+];
+var INDEX_LOG_CATEGORIES = ["search", "embedding", "cache", "gc", "branch", "general"];
+var INDEX_LOG_LEVELS = ["error", "warn", "info", "debug"];
+var MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT = 1;
+var MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT = 20;
+var DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT = 5;
+var CODE_COMMUNITIES_MIN_SIZE = 1;
+var CODE_COMMUNITIES_DEFAULT_LIMIT = 20;
+var CODE_COMMUNITIES_MAX_LIMIT = 100;
+var CODE_COMMUNITIES_DEFAULT_HUB_THRESHOLD = 5;
+var CODE_COMMUNITIES_MIN_COUPLING = 1;
+var CODE_COMMUNITIES_DEFAULT_COUPLING_LIMIT = 20;
+var CODE_COMMUNITIES_MAX_COUPLING_LIMIT = 100;
+
 // src/tools/operations.ts
 import { existsSync as existsSync12, realpathSync as realpathSync5, statSync as statSync5 } from "fs";
 import * as path21 from "path";
@@ -12737,39 +12798,6 @@ function formatCodeCommunities(result) {
   return lines.join("\n");
 }
 
-// src/tools/contracts.ts
-var CHUNK_TYPES = [
-  "function",
-  "class",
-  "method",
-  "interface",
-  "type",
-  "enum",
-  "struct",
-  "impl",
-  "trait",
-  "module",
-  "other"
-];
-var CALL_GRAPH_DIRECTIONS = ["callers", "callees"];
-var RELATIONSHIP_TYPES = [
-  "Call",
-  "MethodCall",
-  "Constructor",
-  "Import",
-  "Inherits",
-  "Implements"
-];
-var INDEX_LOG_CATEGORIES = ["search", "embedding", "cache", "gc", "branch", "general"];
-var INDEX_LOG_LEVELS = ["error", "warn", "info", "debug"];
-var CODE_COMMUNITIES_MIN_SIZE = 1;
-var CODE_COMMUNITIES_DEFAULT_LIMIT = 20;
-var CODE_COMMUNITIES_MAX_LIMIT = 100;
-var CODE_COMMUNITIES_DEFAULT_HUB_THRESHOLD = 5;
-var CODE_COMMUNITIES_MIN_COUPLING = 1;
-var CODE_COMMUNITIES_DEFAULT_COUPLING_LIMIT = 20;
-var CODE_COMMUNITIES_MAX_COUPLING_LIMIT = 100;
-
 // src/tools/context-pack.ts
 import { get_encoding } from "tiktoken";
 var MIN_CONTEXT_PACK_TOKEN_BUDGET = 128;
@@ -12871,6 +12899,16 @@ function compactEvidenceValue(value, maxChars) {
 }
 var MAX_EXACT_SEARCH_HANDOFF_NAMES = 3;
 var MAX_EXACT_SEARCH_HANDOFF_NAME_CHARS = 64;
+function toContextPackTraceCandidate(result) {
+  return {
+    filePath: result.filePath,
+    startLine: result.startLine,
+    endLine: result.endLine,
+    score: result.score,
+    chunkType: result.chunkType,
+    name: result.name
+  };
+}
 function formatExactSearchHandoff(results) {
   const suggestedNames = [];
   const seen = /* @__PURE__ */ new Set();
@@ -12919,13 +12957,13 @@ function buildContextPack(results, options = {}) {
   const maxResults = Math.max(0, Math.floor(options.maxResults ?? results.length));
   const includeExactSearchHandoff = options.includeExactSearchHandoff ?? false;
   const candidateCount = results.length;
-  const deduplicated = deduplicateContextCandidates(
-    rankContextCandidates(
-      results,
-      options.preferImplementationPaths ?? false
-    )
-  );
-  const diversified = diversifyContextCandidates(deduplicated);
+  const preserveInputOrder = options.preserveInputOrder ?? false;
+  const ranked = preserveInputOrder ? results.map((result, originalIndex) => ({ result, originalIndex })) : rankContextCandidates(results, options.preferImplementationPaths ?? false);
+  const rankedCandidates = ranked.map((entry) => toContextPackTraceCandidate(entry.result));
+  const deduplicated = deduplicateContextCandidates(ranked);
+  const deduplicatedCandidates = deduplicated.map((result) => toContextPackTraceCandidate(result));
+  const diversified = preserveInputOrder ? deduplicated : diversifyContextCandidates(deduplicated);
+  const diversifiedCandidates = diversified.map((result) => toContextPackTraceCandidate(result));
   const duplicateCount = candidateCount - deduplicated.length;
   const selectable = diversified.slice(0, maxResults);
   const limitOmittedCount = deduplicated.length - selectable.length;
@@ -12958,6 +12996,15 @@ function buildContextPack(results, options = {}) {
   const fitted = fitTextToContextBudget(text, tokenBudget);
   const budgetOmittedCount = selectable.length - selected.length;
   const omittedCount = candidateCount - selected.length;
+  if (options.trace) {
+    options.trace({
+      inputCandidates: results.map(toContextPackTraceCandidate),
+      rankedCandidates,
+      deduplicatedCandidates,
+      diversifiedCandidates,
+      selectedCandidates: selected.map(toContextPackTraceCandidate)
+    });
+  }
   return {
     requestedTokenBudget,
     tokenBudget,
@@ -14705,7 +14752,8 @@ async function searchCodebase(projectRoot, host, query, options = {}) {
     definitionIntent: options.definitionIntent,
     blameAuthor: options.blameAuthor,
     blameSha: options.blameSha,
-    blameSince: options.blameSince
+    blameSince: options.blameSince,
+    trace: options.trace
   });
 }
 async function searchCodebaseWithEffectiveness(projectRoot, host, route, query, options, render) {
@@ -14759,15 +14807,19 @@ async function implementationLookup(projectRoot, host, query, options = {}) {
   return indexer.search(query, options.limit, {
     fileType: options.fileType,
     directory: options.directory,
-    definitionIntent: true
+    definitionIntent: true,
+    trace: options.trace
   });
 }
 async function getCallGraphData(projectRoot, host, params) {
   await ensureAutoIndexReadyForRetrieval(projectRoot, host);
   const root = getProjectRoot(projectRoot, host);
   const indexer = getIndexerForProject(root, host);
+  return getCallGraphDataForIndexer(indexer, root, params);
+}
+async function getCallGraphDataForIndexer(indexer, projectRoot, params) {
   const symbols = await indexer.getCallGraphSymbols();
-  const resolution = resolveCallGraphSymbol(symbols, root, params.name, params.filePath, params.symbolId);
+  const resolution = resolveCallGraphSymbol(symbols, projectRoot, params.name, params.filePath, params.symbolId);
   const direction = params.direction === "callees" ? "callees" : "callers";
   if (resolution.status !== "resolved") {
     return { direction, resolution, callers: [], callees: [], relationshipType: params.relationshipType };
@@ -15095,6 +15147,27 @@ function buildRecoveryDetails(attempts, successIndex) {
     successfulAttemptIndex: successIndex
   };
 }
+function serializeAttempts(attempts) {
+  return attempts.map((attempt) => ({
+    kind: attempt.kind,
+    scope: attempt.scope,
+    resultCount: attempt.resultCount,
+    relaxedFields: attempt.relaxedFields
+  }));
+}
+function buildSearchDiagnostic(attempt) {
+  if (!attempt) {
+    return void 0;
+  }
+  return {
+    route: attempt.kind,
+    routedQuery: attempt.query,
+    searchQuery: attempt.query,
+    searchScope: attempt.scopeFilter,
+    searchTrace: attempt.searchTrace,
+    contextPackTrace: attempt.contextPackTrace
+  };
+}
 function trimOrUndefined2(value) {
   const normalized = value?.trim();
   if (!normalized) {
@@ -15134,6 +15207,7 @@ async function resolveSearchContext(input, operations) {
   const hasFilters = Boolean(fileType || directory);
   const relaxedFields = relaxedHintFields(fileType, directory);
   const attempts = [];
+  const attemptStates = [];
   const decisions = {
     inferredDefinitionMiss: false,
     fallbackFromOriginalConceptualToInferred: false,
@@ -15162,8 +15236,20 @@ async function resolveSearchContext(input, operations) {
     if (seenAttempts.has(key)) {
       return [];
     }
-    const results = await runAttempt();
+    const attemptState = {
+      kind,
+      scope: describeScope(scope.fileType, scope.directory),
+      resultCount: 0,
+      relaxedFields: [...relaxedFieldsForAttempt],
+      query: attemptQuery,
+      scopeFilter: scope
+    };
+    const results = await runAttempt((trace) => {
+      attemptState.searchTrace = trace;
+    });
+    attemptState.resultCount = results.length;
     seenAttempts.add(key);
+    attemptStates.push(attemptState);
     attempts.push({
       kind,
       scope: describeScope(scope.fileType, scope.directory),
@@ -15183,7 +15269,7 @@ async function resolveSearchContext(input, operations) {
       symbol,
       scope,
       relaxedFieldsForAttempt,
-      () => operations.lookup(symbol, MAX_CONTEXT_RESULT_LIMIT, scope)
+      (trace) => operations.lookup(symbol, MAX_CONTEXT_RESULT_LIMIT, scope, input.diagnostic ? trace : void 0)
     );
   };
   const tryConceptualSearch = async (searchQuery, scope, relaxedFieldsForAttempt) => {
@@ -15192,13 +15278,23 @@ async function resolveSearchContext(input, operations) {
       searchQuery,
       scope,
       relaxedFieldsForAttempt,
-      () => operations.search(searchQuery, MAX_CONTEXT_RESULT_LIMIT, scope)
+      (trace) => operations.search(searchQuery, MAX_CONTEXT_RESULT_LIMIT, scope, input.diagnostic ? trace : void 0)
     );
   };
-  const toResult = (route, routedQuery, pack) => {
+  const findSuccessfulAttemptState = (route) => {
+    for (let index = attemptStates.length - 1; index >= 0; index -= 1) {
+      const attempt = attemptStates[index];
+      if (attempt.kind === route && attempt.resultCount > 0) {
+        return attempt;
+      }
+    }
+    return void 0;
+  };
+  const toResult = (route, routedQuery, pack, successfulAttempt) => {
     const base = packedResult(route, routedQuery, pack);
     const baseDetails = base.details;
     const successIndex = findSuccessfulAttemptIndex(route, attempts);
+    const successState = successfulAttempt ?? findSuccessfulAttemptState(route);
     return {
       text: base.text,
       details: {
@@ -15206,7 +15302,10 @@ async function resolveSearchContext(input, operations) {
         tokenBudget: baseDetails.tokenBudget,
         tokenEstimate: baseDetails.tokenEstimate,
         truncated: false,
-        recovery: buildRecoveryDetails(attempts, successIndex)
+        recovery: buildRecoveryDetails(serializeAttempts(attemptStates), successIndex),
+        ...input.diagnostic && {
+          diagnostic: buildSearchDiagnostic(successState)
+        }
       }
     };
   };
@@ -15220,8 +15319,18 @@ async function resolveSearchContext(input, operations) {
         buildContextPack(scopedDefinitionResults, {
           tokenBudget,
           maxResults: limit,
-          heading
-        })
+          heading,
+          preserveInputOrder: true,
+          ...input.diagnostic ? {
+            trace: (trace) => {
+              const attemptState = findSuccessfulAttemptState("definition");
+              if (attemptState) {
+                attemptState.contextPackTrace = trace;
+              }
+            }
+          } : void 0
+        }),
+        findSuccessfulAttemptState("definition")
       );
     }
     if (explicitSymbol) {
@@ -15239,8 +15348,18 @@ async function resolveSearchContext(input, operations) {
             buildContextPack(unscopedDefinitionResults, {
               tokenBudget,
               maxResults: limit,
-              heading: heading2
-            })
+              heading: heading2,
+              preserveInputOrder: true,
+              ...input.diagnostic ? {
+                trace: (trace) => {
+                  const attemptState = findSuccessfulAttemptState("definition");
+                  if (attemptState) {
+                    attemptState.contextPackTrace = trace;
+                  }
+                }
+              } : void 0
+            }),
+            findSuccessfulAttemptState("definition")
           );
         }
       }
@@ -15259,7 +15378,10 @@ Explicit symbol lookup only; conceptual search was not attempted.`
           tokenBudget: heading.tokenBudget,
           tokenEstimate: heading.tokenEstimate,
           truncated: heading.truncated,
-          recovery: buildRecoveryDetails(attempts, null)
+          recovery: buildRecoveryDetails(serializeAttempts(attemptStates), null),
+          ...input.diagnostic && {
+            diagnostic: buildSearchDiagnostic(attemptStates[attemptStates.length - 1])
+          }
         }
       };
     }
@@ -15299,8 +15421,17 @@ Explicit symbol lookup only; conceptual search was not attempted.`
           maxResults: limit,
           heading,
           includeExactSearchHandoff: true,
-          preferImplementationPaths: intent.preferSourcePaths || intent.primary !== "docs" && intent.primary !== "test"
-        })
+          preferImplementationPaths: intent.preferSourcePaths || intent.primary !== "docs" && intent.primary !== "test",
+          ...input.diagnostic ? {
+            trace: (trace) => {
+              const attemptState = findSuccessfulAttemptState("conceptual");
+              if (attemptState) {
+                attemptState.contextPackTrace = trace;
+              }
+            }
+          } : void 0
+        }),
+        findSuccessfulAttemptState("conceptual")
       );
     }
   }
@@ -15316,7 +15447,10 @@ Explicit symbol lookup only; conceptual search was not attempted.`
       tokenBudget: fallbackText.tokenBudget,
       tokenEstimate: fallbackText.tokenEstimate,
       truncated: fallbackText.truncated,
-      recovery: buildRecoveryDetails(attempts, null)
+      recovery: buildRecoveryDetails(serializeAttempts(attemptStates), null),
+      ...input.diagnostic && {
+        diagnostic: buildSearchDiagnostic(attemptStates[attemptStates.length - 1])
+      }
     }
   };
 }
@@ -15397,17 +15531,27 @@ async function resolveCodebaseContextUnmeasured(projectRoot, host, input) {
       details: fittedDetails("path", fitted, 0)
     };
   }
-  return resolveSearchContext({ query: input.query, symbol, limit, tokenBudget, fileType, directory }, {
-    lookup: (lookupSymbol, retrievalLimit, scope) => implementationLookup(projectRoot, host, lookupSymbol, {
+  return resolveSearchContext({
+    query: input.query,
+    symbol,
+    limit,
+    tokenBudget,
+    fileType,
+    directory,
+    diagnostic: input.diagnostic
+  }, {
+    lookup: (lookupSymbol, retrievalLimit, scope, trace) => implementationLookup(projectRoot, host, lookupSymbol, {
       limit: retrievalLimit,
       fileType: scope.fileType,
-      directory: scope.directory
+      directory: scope.directory,
+      trace
     }),
-    search: (queryText, retrievalLimit, scope) => searchCodebase(projectRoot, host, queryText, {
+    search: (queryText, retrievalLimit, scope, trace) => searchCodebase(projectRoot, host, queryText, {
       limit: retrievalLimit,
       fileType: scope.fileType,
       directory: scope.directory,
-      metadataOnly: true
+      metadataOnly: true,
+      trace
     })
   });
 }
@@ -15472,6 +15616,181 @@ async function resolveCodebaseContext(projectRoot, host, input) {
   }
 }
 
+// src/tools/edit-context.ts
+function edgeLimit(value) {
+  if (value === null || value === void 0 || !Number.isFinite(value)) {
+    return DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT;
+  }
+  return Math.min(
+    MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT,
+    Math.max(MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT, Math.floor(value))
+  );
+}
+function normalizedPath(value) {
+  return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function pathsMatch(left, right) {
+  const normalizedLeft = normalizedPath(left);
+  const normalizedRight = normalizedPath(right);
+  return normalizedLeft === normalizedRight || normalizedLeft.endsWith(`/${normalizedRight}`) || normalizedRight.endsWith(`/${normalizedLeft}`);
+}
+function targetSource(results, resolution) {
+  return results.find((result) => pathsMatch(result.filePath, resolution.filePath) && result.startLine <= resolution.startLine && result.endLine >= resolution.startLine) ?? results.find((result) => pathsMatch(result.filePath, resolution.filePath) && result.name === resolution.name);
+}
+function formatSource(result) {
+  const name = result.name ? ` ${result.name}` : "";
+  return [
+    "## Target implementation",
+    `${result.filePath}:${result.startLine}-${result.endLine} (${result.chunkType}${name})`,
+    "```",
+    result.content,
+    "```"
+  ].join("\n");
+}
+function formatCallers(edges) {
+  if (edges.length === 0) return "## Direct callers\nNone found.";
+  return [
+    "## Direct callers",
+    ...edges.map((edge) => `- ${edge.fromSymbolName ?? "<unknown>"} at ${edge.fromSymbolFilePath ?? "<unknown file>"}:${edge.line} (${edge.callType}, ${edge.isResolved ? "resolved" : "unresolved"})`)
+  ].join("\n");
+}
+function formatCallees(edges, sourceFilePath) {
+  if (edges.length === 0) return "## Direct callees\nNone found.";
+  return [
+    "## Direct callees",
+    ...edges.map((edge) => `- ${edge.targetName} from ${sourceFilePath}:${edge.line} (${edge.callType}, ${edge.isResolved ? "resolved" : "unresolved"})`)
+  ].join("\n");
+}
+function formatResolutionRisk(resolution) {
+  if (resolution.status === "ambiguous") {
+    const candidates = resolution.candidates.map((candidate) => `${candidate.filePath}:${candidate.startLine}`).join(", ");
+    return `Risk: symbol "${resolution.name}" is ambiguous. Pass filePath to select a target.${candidates ? ` Candidates: ${candidates}.` : ""}`;
+  }
+  if (resolution.filePath && resolution.totalCandidates > 0) {
+    return `Risk: symbol "${resolution.name}" did not resolve at filePath="${resolution.filePath}". Review the conceptual evidence before editing.`;
+  }
+  return `Risk: symbol "${resolution.name}" could not be resolved. Review the conceptual evidence before editing.`;
+}
+async function fallbackPack(dependencies, query, risk, resolution, tokenBudget, candidateSource = []) {
+  const conceptual = await dependencies.searchCodebase(query, { limit: 5 });
+  const pack = buildContextPack([...candidateSource, ...conceptual], {
+    tokenBudget: tokenBudget ?? void 0,
+    heading: "## Conceptual evidence",
+    maxResults: 5,
+    includeExactSearchHandoff: false,
+    preferImplementationPaths: true
+  });
+  const fitted = fitTextToContextBudget(`${risk}
+
+${pack.text}`, tokenBudget ?? void 0);
+  return {
+    text: fitted.text,
+    details: {
+      resolution,
+      tokenBudget: fitted.tokenBudget,
+      tokenEstimate: fitted.tokenEstimate,
+      truncated: fitted.truncated,
+      sourceIncluded: candidateSource.length > 0,
+      callerCount: 0,
+      calleeCount: 0
+    }
+  };
+}
+async function resolveCodebaseEditContextWithDependencies(input, dependencies) {
+  const symbol = input.symbol?.trim();
+  if (!symbol) {
+    return fallbackPack(
+      dependencies,
+      input.query,
+      "Risk: no authoritative symbol was supplied. Review the conceptual evidence before editing.",
+      "not_requested",
+      input.tokenBudget
+    );
+  }
+  let callersResult;
+  try {
+    callersResult = await dependencies.getCallGraphData({
+      name: symbol,
+      filePath: input.filePath ?? void 0,
+      direction: "callers"
+    });
+  } catch (error) {
+    const candidates = await dependencies.implementationLookup(symbol, { limit: 5 });
+    const message = error instanceof Error ? error.message : String(error);
+    return fallbackPack(
+      dependencies,
+      input.query,
+      `Risk: graph data is unavailable (${message}). Target and dependencies are not graph-verified.`,
+      "graph_unavailable",
+      input.tokenBudget,
+      candidates
+    );
+  }
+  if (callersResult.resolution.status !== "resolved") {
+    return fallbackPack(
+      dependencies,
+      input.query,
+      formatResolutionRisk(callersResult.resolution),
+      callersResult.resolution.status,
+      input.tokenBudget
+    );
+  }
+  const resolution = callersResult.resolution;
+  const [definitionsResult, calleesResult] = await Promise.allSettled([
+    dependencies.implementationLookup(symbol, { limit: 10 }),
+    dependencies.getCallGraphData({
+      name: symbol,
+      filePath: input.filePath ?? resolution.filePath,
+      direction: "callees"
+    })
+  ]);
+  if (definitionsResult.status === "rejected") throw definitionsResult.reason;
+  let graphRisk;
+  let callees = [];
+  if (calleesResult.status === "rejected") {
+    const message = calleesResult.reason instanceof Error ? calleesResult.reason.message : String(calleesResult.reason);
+    graphRisk = `Risk: callee graph data is unavailable (${message}). Dependency evidence is incomplete.`;
+  } else if (calleesResult.value.resolution.status !== "resolved") {
+    graphRisk = "Risk: the target resolved for callers but not callees. Dependency evidence is incomplete.";
+  } else {
+    callees = calleesResult.value.callees.slice(0, edgeLimit(input.calleeLimit));
+  }
+  const source = targetSource(definitionsResult.value, resolution);
+  const callers = callersResult.callers.slice(0, edgeLimit(input.callerLimit));
+  const sourceBudget = Math.max(
+    MIN_CONTEXT_PACK_TOKEN_BUDGET,
+    Math.floor((input.tokenBudget ?? DEFAULT_CONTEXT_PACK_TOKEN_BUDGET) * 0.6)
+  );
+  const sourceText = source ? fitTextToContextBudget(formatSource(source), sourceBudget).text : `## Target implementation
+Risk: no implementation source matched the resolved target at ${resolution.filePath}:${resolution.startLine}.`;
+  const fitted = fitTextToContextBudget([
+    `# Pre-edit context for ${resolution.name}`,
+    graphRisk,
+    sourceText,
+    formatCallers(callers),
+    formatCallees(callees, resolution.filePath)
+  ].filter((section) => section !== void 0).join("\n\n"), input.tokenBudget ?? void 0);
+  return {
+    text: fitted.text,
+    details: {
+      resolution: "resolved",
+      tokenBudget: fitted.tokenBudget,
+      tokenEstimate: fitted.tokenEstimate,
+      truncated: fitted.truncated,
+      sourceIncluded: source !== void 0,
+      callerCount: callers.length,
+      calleeCount: callees.length
+    }
+  };
+}
+async function resolveCodebaseEditContext(projectRoot, host, input) {
+  return resolveCodebaseEditContextWithDependencies(input, {
+    searchCodebase: (query, options) => searchCodebase(projectRoot, host, query, options),
+    implementationLookup: (query, options) => implementationLookup(projectRoot, host, query, options),
+    getCallGraphData: (params) => getCallGraphData(projectRoot, host, params)
+  });
+}
+
 // src/eval/budget.ts
 function evaluateBudgetGate(budget, summary, comparison) {
   const BASELINE_P95_EPSILON_MS = 1e-3;
@@ -15495,6 +15814,24 @@ function evaluateBudgetGate(budget, summary, comparison) {
       message: `Raw Distinct Top@3 ${summary.metrics.rawDistinctTop3Ratio.toFixed(4)} is below minimum ${thresholds.minRawDistinctTop3Ratio.toFixed(4)}`
     });
   }
+  if (thresholds.minGraphNeighborRecall !== void 0 && summary.metrics.graphNeighborRecall !== void 0 && summary.metrics.graphNeighborRecall < thresholds.minGraphNeighborRecall) {
+    violations.push({
+      metric: "minGraphNeighborRecall",
+      message: `Graph-neighbor recall ${summary.metrics.graphNeighborRecall.toFixed(4)} is below minimum ${thresholds.minGraphNeighborRecall.toFixed(4)}`
+    });
+  }
+  if (thresholds.minRouteAccuracy !== void 0 && summary.metrics.routeAccuracy < thresholds.minRouteAccuracy) {
+    violations.push({
+      metric: "minRouteAccuracy",
+      message: `Route accuracy ${summary.metrics.routeAccuracy.toFixed(4)} is below minimum ${thresholds.minRouteAccuracy.toFixed(4)}`
+    });
+  }
+  if (thresholds.minOutcomeAccuracy !== void 0 && summary.metrics.outcomeAccuracy < thresholds.minOutcomeAccuracy) {
+    violations.push({
+      metric: "minOutcomeAccuracy",
+      message: `Outcome accuracy ${summary.metrics.outcomeAccuracy.toFixed(4)} is below minimum ${thresholds.minOutcomeAccuracy.toFixed(4)}`
+    });
+  }
   if (comparison) {
     if (thresholds.hitAt5MaxDrop !== void 0 && comparison.deltas.hitAt5.absolute < -thresholds.hitAt5MaxDrop) {
       violations.push({
@@ -15672,6 +16009,14 @@ function isSymbolIntended(query) {
 function isExpectedFile(filePath, relevant) {
   return relevant.some((entry) => pathMatchesExpected(filePath, entry.path));
 }
+function graphNeighborMatches(query, result) {
+  const expected = query.expected.graphNeighbor;
+  if (!expected || result.graphDirection !== expected.direction) return false;
+  if (expected.filePath !== void 0 && !pathMatchesExpected(result.filePath, expected.filePath)) {
+    return false;
+  }
+  return expected.symbol === void 0 || result.name === expected.symbol;
+}
 function resultRelevance(filePath, symbol, relevant, isSymbolIntendedQuery) {
   let relevance = 0;
   for (const entry of relevant) {
@@ -15819,6 +16164,7 @@ function buildPerQueryResult(query, results, latencyMs, k, route = {
     routeMatched: query.expected.expectedRoute ? query.expected.expectedRoute === route.resolvedRoute : void 0,
     outcomeMatched: query.expected.expectedOutcome === void 0 ? void 0 : query.expected.expectedOutcome === "results" ? deduped.length > 0 : deduped.length === 0,
     recoveryMatched: query.expected.recoveryExpectation === void 0 ? void 0 : query.expected.recoveryExpectation === "filter-relaxed" ? context?.recoveryRelaxed === true : context?.recoveryUsed !== true,
+    graphNeighborMatched: query.expected.graphNeighbor === void 0 ? void 0 : results.some((result) => graphNeighborMatches(query, result)),
     language: query.language,
     difficulty: query.difficulty,
     tags: query.tags,
@@ -15868,7 +16214,7 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
     "no-relevant-hit-top-k": 0
   };
   const latencies = perQuery.map((item) => item.latencyMs);
-  const contextQueries = perQuery.filter((item) => item.retrievalMode === "context");
+  const contextQueries = perQuery.filter((item) => item.retrievalMode !== "search");
   const contextResponseTokens = contextQueries.map((item) => item.responseTokens);
   const totalContextResponseTokens = contextResponseTokens.reduce((sum2, value) => sum2 + value, 0);
   const contextTokenUnits = totalContextResponseTokens / 1e3;
@@ -15878,6 +16224,8 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
   let outcomeExpectedCount = 0;
   let recoveryMatchedCount = 0;
   let recoveryExpectedCount = 0;
+  let graphNeighborMatchedCount = 0;
+  let graphNeighborExpectedCount = 0;
   for (const query of perQuery) {
     if (positiveQueryIds.has(query.id)) {
       if (query.hitAt1) sum.hitAt1 += 1;
@@ -15906,6 +16254,10 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
       recoveryExpectedCount += 1;
       if (query.recoveryMatched) recoveryMatchedCount += 1;
     }
+    if (query.graphNeighborMatched !== void 0) {
+      graphNeighborExpectedCount += 1;
+      if (query.graphNeighborMatched) graphNeighborMatchedCount += 1;
+    }
   }
   const queryTokens = queries.reduce((acc, q) => acc + estimateTokens(q.query), 0);
   return {
@@ -15918,6 +16270,7 @@ function computeEvalMetrics(queries, perQuery, embeddingCallCount, embeddingToke
     routeAccuracy: routeExpectedCount === 0 ? 0 : routeMatchedCount / routeExpectedCount,
     outcomeAccuracy: outcomeExpectedCount === 0 ? 0 : outcomeMatchedCount / outcomeExpectedCount,
     recoveryAccuracy: recoveryExpectedCount === 0 ? 0 : recoveryMatchedCount / recoveryExpectedCount,
+    graphNeighborRecall: graphNeighborExpectedCount === 0 ? 0 : graphNeighborMatchedCount / graphNeighborExpectedCount,
     distinctTop3Ratio: safeDiv(sum.distinctTop3Ratio),
     rawDistinctTop3Ratio: safeDiv(sum.rawDistinctTop3Ratio),
     latencyMs: {
@@ -16183,14 +16536,29 @@ function parseQueryArgs(value, path31) {
     throw new Error(`${path31} must be an object`);
   }
   const symbol = parseStringOrUndefined(value.symbol, `${path31}.symbol`);
+  const filePath = parseStringOrUndefined(value.filePath, `${path31}.filePath`);
   const fileType = parseStringOrUndefined(value.fileType, `${path31}.fileType`);
   const directory = parseStringOrUndefined(value.directory, `${path31}.directory`);
+  const callerLimit = parsePositiveIntegerOrUndefined(value.callerLimit, `${path31}.callerLimit`);
+  const calleeLimit = parsePositiveIntegerOrUndefined(value.calleeLimit, `${path31}.calleeLimit`);
+  const tokenBudget = parsePositiveIntegerOrUndefined(value.tokenBudget, `${path31}.tokenBudget`);
   return {
     ...symbol !== void 0 ? { symbol } : {},
+    ...filePath !== void 0 ? { filePath } : {},
     ...fileType !== void 0 ? { fileType } : {},
-    ...directory !== void 0 ? { directory } : {}
+    ...directory !== void 0 ? { directory } : {},
+    ...callerLimit !== void 0 ? { callerLimit } : {},
+    ...calleeLimit !== void 0 ? { calleeLimit } : {},
+    ...tokenBudget !== void 0 ? { tokenBudget } : {}
   };
 }
+function parsePositiveIntegerOrUndefined(value, path31) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new Error(`${path31} must be a positive integer`);
+  }
+  return value;
+}
 var SEMVER_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 function parseSemanticVersion(value, path31) {
   if (!isNonEmptyString(value)) {
@@ -16203,8 +16571,8 @@ function parseSemanticVersion(value, path31) {
 }
 function parseRetrievalMode(value, path31) {
   if (value === void 0 || value === "search") return "search";
-  if (value === "context") return value;
-  throw new Error(`${path31} must be one of: search, context`);
+  if (value === "context" || value === "edit-context") return value;
+  throw new Error(`${path31} must be one of: search, context, edit-context`);
 }
 function parseStringOrUndefined(value, path31) {
   if (value === void 0 || value === null) return void 0;
@@ -16244,6 +16612,25 @@ function parseEvidenceRelevance(value, path31) {
   }
   return value;
 }
+function parseExpectedGraphNeighbor(value, path31) {
+  if (value === void 0) return void 0;
+  if (!isRecord3(value)) {
+    throw new Error(`${path31} must be an object`);
+  }
+  if (value.direction !== "caller" && value.direction !== "callee") {
+    throw new Error(`${path31}.direction must be one of: caller, callee`);
+  }
+  const filePath = parseStringOrUndefined(value.filePath, `${path31}.filePath`);
+  const symbol = parseStringOrUndefined(value.symbol, `${path31}.symbol`);
+  if (filePath === void 0 && symbol === void 0) {
+    throw new Error(`${path31} must include filePath or symbol`);
+  }
+  return {
+    direction: value.direction,
+    ...filePath !== void 0 ? { filePath } : {},
+    ...symbol !== void 0 ? { symbol } : {}
+  };
+}
 function parseExpected(input, path31) {
   if (!isRecord3(input)) {
     throw new Error(`${path31} must be an object`);
@@ -16256,9 +16643,11 @@ function parseExpected(input, path31) {
   const expectedOutcomeRaw = input.expectedOutcome;
   const recoveryExpectationRaw = input.recoveryExpectation;
   const gradedEvidenceRaw = input.gradedEvidence;
+  const graphNeighborRaw = input.graphNeighbor;
   const filePath = parseStringOrUndefined(filePathRaw, `${path31}.filePath`);
   const acceptableFiles = isStringArray4(acceptableFilesRaw) ? acceptableFilesRaw : void 0;
   const gradedEvidence = parseGradedEvidence(gradedEvidenceRaw, `${path31}.gradedEvidence`);
+  const graphNeighbor = parseExpectedGraphNeighbor(graphNeighborRaw, `${path31}.graphNeighbor`);
   const expectedOutcome = parseExpectedOutcome(expectedOutcomeRaw, `${path31}.expectedOutcome`);
   if (expectedOutcome !== "no-results" && !filePath && (!acceptableFiles || acceptableFiles.length === 0) && gradedEvidence.length === 0) {
     throw new Error(
@@ -16287,7 +16676,8 @@ function parseExpected(input, path31) {
     expectedRoute,
     expectedOutcome,
     recoveryExpectation,
-    ...gradedEvidence.length > 0 ? { gradedEvidence } : {}
+    ...gradedEvidence.length > 0 ? { gradedEvidence } : {},
+    ...graphNeighbor !== void 0 ? { graphNeighbor } : {}
   };
 }
 function parseQueryLanguage(value, path31) {
@@ -16422,6 +16812,21 @@ function parseBudget(raw, sourceLabel) {
         "minRawDistinctTop3Ratio",
         sourceLabel
       ),
+      minGraphNeighborRecall: parseThresholdValue(
+        thresholds.minGraphNeighborRecall,
+        "minGraphNeighborRecall",
+        sourceLabel
+      ),
+      minRouteAccuracy: parseThresholdValue(
+        thresholds.minRouteAccuracy,
+        "minRouteAccuracy",
+        sourceLabel
+      ),
+      minOutcomeAccuracy: parseThresholdValue(
+        thresholds.minOutcomeAccuracy,
+        "minOutcomeAccuracy",
+        sourceLabel
+      ),
       maxContextResponseTokensAverage: parseThresholdValue(
         thresholds.maxContextResponseTokensAverage,
         "maxContextResponseTokensAverage",
@@ -16486,6 +16891,120 @@ function buildDatasetFingerprint(dataset) {
   const canonical = JSON.stringify(normalizeForFingerprint(dataset));
   return crypto2.createHash("sha256").update(canonical).digest("hex");
 }
+function normalizedPath2(value) {
+  return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function pathsMatch2(left, right) {
+  const normalizedLeft = normalizedPath2(left);
+  const normalizedRight = normalizedPath2(right);
+  return normalizedLeft === normalizedRight || normalizedLeft.endsWith(`/${normalizedRight}`) || normalizedRight.endsWith(`/${normalizedLeft}`);
+}
+function toEvalSearchResult(result) {
+  return {
+    filePath: result.filePath,
+    startLine: result.startLine,
+    endLine: result.endLine,
+    score: result.score,
+    chunkType: result.chunkType,
+    name: result.name
+  };
+}
+function selectResolvedTarget(definitions, resolution) {
+  if (resolution?.status !== "resolved") return definitions[0];
+  return definitions.find((result) => pathsMatch2(result.filePath, resolution.filePath) && result.startLine <= resolution.startLine && result.endLine >= resolution.startLine) ?? definitions.find((result) => pathsMatch2(result.filePath, resolution.filePath) && result.name === resolution.name) ?? definitions[0];
+}
+function callerResult(edge) {
+  if (!edge.fromSymbolFilePath) return void 0;
+  return {
+    filePath: edge.fromSymbolFilePath,
+    startLine: edge.line,
+    endLine: edge.line,
+    score: 0,
+    chunkType: "graph-caller",
+    name: edge.fromSymbolName,
+    graphDirection: "caller"
+  };
+}
+function calleeResult(edge, symbols) {
+  const symbol = edge.toSymbolId ? symbols.find((candidate) => candidate.id === edge.toSymbolId) : symbols.filter((candidate) => candidate.name === edge.targetName).length === 1 ? symbols.find((candidate) => candidate.name === edge.targetName) : void 0;
+  if (!symbol) return void 0;
+  return {
+    filePath: symbol.filePath,
+    startLine: symbol.startLine,
+    endLine: symbol.endLine,
+    score: 0,
+    chunkType: "graph-callee",
+    name: symbol.name,
+    graphDirection: "callee"
+  };
+}
+async function runEditContextQuery(indexer, projectRoot, query) {
+  let definitions = [];
+  let conceptual = [];
+  let callers;
+  let callees;
+  const editContext = await resolveCodebaseEditContextWithDependencies({
+    query: query.query,
+    symbol: query.args?.symbol,
+    filePath: query.args?.filePath ?? query.expected.filePath,
+    callerLimit: query.args?.callerLimit,
+    calleeLimit: query.args?.calleeLimit,
+    tokenBudget: query.args?.tokenBudget
+  }, {
+    searchCodebase: async (searchQuery, options) => {
+      conceptual = await indexer.search(searchQuery, options?.limit, {
+        filterByBranch: !!query.expected.branch
+      });
+      return conceptual;
+    },
+    implementationLookup: async (symbol, options) => {
+      definitions = await indexer.search(symbol, options?.limit, {
+        filterByBranch: !!query.expected.branch,
+        definitionIntent: true
+      });
+      return definitions;
+    },
+    getCallGraphData: async (params) => {
+      const result = await getCallGraphDataForIndexer(indexer, projectRoot, params);
+      if (params.direction === "callers") callers = result;
+      else callees = result;
+      return result;
+    }
+  });
+  const resolution = callers?.resolution;
+  const target = selectResolvedTarget(definitions, resolution);
+  const targetCandidates = target ? [target] : [...definitions, ...conceptual];
+  const results = targetCandidates.filter((candidate) => (resolution?.status !== "resolved" || editContext.details.sourceIncluded) && editContext.text.includes(
+    `${candidate.filePath}:${candidate.startLine}-${candidate.endLine}`
+  )).map(toEvalSearchResult);
+  if (query.expected.graphNeighbor) {
+    const symbols = await indexer.getCallGraphSymbols();
+    const callerLimit = query.args?.callerLimit ?? DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT;
+    const calleeLimit = query.args?.calleeLimit ?? DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT;
+    const publishedCallers = (callers?.callers ?? []).slice(0, callerLimit).filter((edge) => editContext.text.includes(
+      `${edge.fromSymbolName ?? "<unknown>"} at ${edge.fromSymbolFilePath ?? "<unknown file>"}:${edge.line} (${edge.callType}, ${edge.isResolved ? "resolved" : "unresolved"})`
+    ));
+    const publishedCallees = (callees?.callees ?? []).slice(0, calleeLimit).filter((edge) => resolution?.status === "resolved" && editContext.text.includes(
+      `${edge.targetName} from ${resolution.filePath}:${edge.line} (${edge.callType}, ${edge.isResolved ? "resolved" : "unresolved"})`
+    ));
+    results.push(
+      ...publishedCallers.map(callerResult).filter((item) => item !== void 0),
+      ...publishedCallees.map((edge) => calleeResult(edge, symbols)).filter((item) => item !== void 0)
+    );
+  }
+  return {
+    results,
+    resolvedRoute: resolution?.status === "resolved" ? "definition" : "search",
+    routedQuery: query.args?.symbol ?? query.query,
+    context: {
+      tokenBudget: editContext.details.tokenBudget,
+      responseTokens: editContext.details.tokenEstimate,
+      candidateCount: results.length,
+      deduplicatedCount: results.length,
+      omittedCount: 0
+    }
+  };
+}
 async function runEvaluation(options) {
   const datasetPath = toAbsolute(options.projectRoot, options.datasetPath);
   const againstPath = options.againstPath ? toAbsolute(options.projectRoot, options.againstPath) : void 0;
@@ -16517,6 +17036,7 @@ async function runEvaluation(options) {
         );
       }
       const start = performance3.now();
+      const editContextResult = query.retrievalMode === "edit-context" ? await runEditContextQuery(indexer, options.projectRoot, query) : void 0;
       const contextResult = query.retrievalMode === "context" ? await resolveSearchContext({
         query: query.query,
         symbol: query.args?.symbol,
@@ -16540,31 +17060,32 @@ async function runEvaluation(options) {
           directory: scope.directory
         })
       }) : void 0;
-      const result = contextResult?.details?.results ?? await indexer.search(query.query, 10, {
+      const result = editContextResult?.results ?? contextResult?.details?.results ?? await indexer.search(query.query, 10, {
         metadataOnly: true,
         filterByBranch: !!query.expected.branch,
         fileType: query.args?.fileType,
         directory: query.args?.directory
       });
       const elapsed = performance3.now() - start;
-      const resolvedRoute = contextResult?.details?.route === "definition" ? "definition" : "search";
-      const routedQuery = contextResult?.details?.routedQuery ?? query.query;
+      const resolvedRoute = editContextResult?.resolvedRoute ?? (contextResult?.details?.route === "definition" ? "definition" : "search");
+      const routedQuery = editContextResult?.routedQuery ?? contextResult?.details?.routedQuery ?? query.query;
       const successfulRecoveryAttempt = contextResult?.details?.recovery?.successfulAttemptIndex;
       const recoveryAttempts = contextResult?.details?.recovery?.attempts ?? [];
       const recoveryRelaxed = successfulRecoveryAttempt === void 0 ? false : (recoveryAttempts[successfulRecoveryAttempt]?.relaxedFields.length ?? 0) > 0;
       const recoveryUsed = recoveryAttempts.length > 1 || recoveryAttempts.some((attempt) => attempt.relaxedFields.length > 0);
-      const materialized = result.map((item) => ({
-        filePath: item.filePath,
-        startLine: item.startLine,
-        endLine: item.endLine,
-        score: item.score,
-        chunkType: item.chunkType,
-        name: item.name
-      }));
-      perQuery.push(buildPerQueryResult(query, materialized, elapsed, 10, {
-        resolvedRoute,
-        routedQuery
-      }, contextResult?.details ? {
+      const materialized = result.map((item) => {
+        const graphDirection = "graphDirection" in item && (item.graphDirection === "caller" || item.graphDirection === "callee") ? item.graphDirection : void 0;
+        return {
+          filePath: item.filePath,
+          startLine: item.startLine,
+          endLine: item.endLine,
+          score: item.score,
+          chunkType: item.chunkType,
+          name: item.name,
+          graphDirection
+        };
+      });
+      const contextMeasurement = editContextResult?.context ?? (contextResult?.details ? {
         tokenBudget: contextResult.details.tokenBudget,
         responseTokens: contextResult.details.tokenEstimate,
         candidateCount: contextResult.details.candidateCount ?? 0,
@@ -16572,7 +17093,11 @@ async function runEvaluation(options) {
         omittedCount: contextResult.details.omittedCount ?? 0,
         recoveryUsed,
         recoveryRelaxed
-      } : void 0));
+      } : void 0);
+      perQuery.push(buildPerQueryResult(query, materialized, elapsed, 10, {
+        resolvedRoute,
+        routedQuery
+      }, contextMeasurement));
     }
     const logger = indexer.getLogger();
     const metricSnapshot = logger.getMetrics();
@@ -17108,7 +17633,11 @@ import { z as z2 } from "zod";
 
 // src/tools/execute-common.ts
 async function executeCodebaseContext(projectRoot, host, args) {
-  return { text: (await resolveCodebaseContext(projectRoot, host, args)).text };
+  const result = await resolveCodebaseContext(projectRoot, host, args);
+  return { text: result.text, details: result.details };
+}
+async function executeCodebaseEditContext(projectRoot, host, args) {
+  return { text: (await resolveCodebaseEditContext(projectRoot, host, args)).text };
 }
 async function executeIndexCodebase(projectRoot, host, args, onProgress) {
   const result = await runIndexCodebase(projectRoot, host, args, onProgress);
@@ -17224,6 +17753,7 @@ function formatPrImpact(result) {
 // src/tools/tool-names.ts
 var TOOL_NAME = {
   CODEBASE_CONTEXT: "codebase_context",
+  CODEBASE_EDIT_CONTEXT: "codebase_edit_context",
   CODEBASE_SEARCH: "codebase_search",
   CODEBASE_PEEK: "codebase_peek",
   FIND_SIMILAR: "find_similar",
@@ -17247,6 +17777,7 @@ var TOOL_NAME = {
 };
 var PORTABLE_TOOL_NAMES = [
   TOOL_NAME.CODEBASE_CONTEXT,
+  TOOL_NAME.CODEBASE_EDIT_CONTEXT,
   TOOL_NAME.CODEBASE_SEARCH,
   TOOL_NAME.CODEBASE_PEEK,
   TOOL_NAME.INDEX_CODEBASE,
@@ -17263,6 +17794,7 @@ var PORTABLE_TOOL_NAMES = [
 ];
 var OPENCODE_TOOL_NAMES = [
   TOOL_NAME.CODEBASE_CONTEXT,
+  TOOL_NAME.CODEBASE_EDIT_CONTEXT,
   TOOL_NAME.CODEBASE_SEARCH,
   TOOL_NAME.CODEBASE_PEEK,
   TOOL_NAME.INDEX_CODEBASE,
@@ -17283,6 +17815,7 @@ var OPENCODE_TOOL_NAMES = [
 ];
 var PI_TOOL_NAMES = [
   TOOL_NAME.CODEBASE_CONTEXT,
+  TOOL_NAME.CODEBASE_EDIT_CONTEXT,
   TOOL_NAME.CODEBASE_SEARCH,
   TOOL_NAME.CODEBASE_PEEK,
   TOOL_NAME.FIND_SIMILAR,
@@ -17326,10 +17859,30 @@ function registerMcpTools(server, runtime) {
       directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
       tokenBudget: allowNullAsUndefined(
         z2.number().int().min(MIN_CONTEXT_PACK_TOKEN_BUDGET).max(MAX_CONTEXT_PACK_TOKEN_BUDGET).optional().default(DEFAULT_CONTEXT_PACK_TOKEN_BUDGET)
-      ).describe(`Maximum response tokens for this context pack (${MIN_CONTEXT_PACK_TOKEN_BUDGET}-${MAX_CONTEXT_PACK_TOKEN_BUDGET})`)
+      ).describe(`Maximum response tokens for this context pack (${MIN_CONTEXT_PACK_TOKEN_BUDGET}-${MAX_CONTEXT_PACK_TOKEN_BUDGET})`),
+      diagnostic: z2.boolean().optional().describe("Collect diagnostic routing and search traces without changing normal text output.")
     },
     async (args) => {
       const result = await executeCodebaseContext(runtime.projectRoot, runtime.host, args);
+      return {
+        content: [{ type: "text", text: result.text }],
+        ...args.diagnostic ? { structuredContent: result.details } : {}
+      };
+    }
+  );
+  server.tool(
+    TOOL_NAME.CODEBASE_EDIT_CONTEXT,
+    "PRE-EDIT TOOL for a known or suspected symbol. Returns token-bounded target source, direct callers and callees, or a risk-marked conceptual fallback when resolution is unsafe.",
+    {
+      query: z2.string().describe("The requested change or target behavior."),
+      symbol: allowNullAsUndefined(z2.string().optional()).describe("Authoritative target symbol when known."),
+      filePath: allowNullAsUndefined(z2.string().optional()).describe("Optional file path used to disambiguate duplicate symbol names."),
+      callerLimit: allowNullAsUndefined(z2.number().int().min(MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).max(MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).optional().default(DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT)),
+      calleeLimit: allowNullAsUndefined(z2.number().int().min(MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).max(MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).optional().default(DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT)),
+      tokenBudget: allowNullAsUndefined(z2.number().int().min(MIN_CONTEXT_PACK_TOKEN_BUDGET).max(MAX_CONTEXT_PACK_TOKEN_BUDGET).optional().default(DEFAULT_CONTEXT_PACK_TOKEN_BUDGET))
+    },
+    async (args) => {
+      const result = await executeCodebaseEditContext(runtime.projectRoot, runtime.host, args);
       return { content: [{ type: "text", text: result.text }] };
     }
   );
@@ -19592,6 +20145,8 @@ var GitHeadWatcher = class {
   debounceTimer = null;
   debounceMs = 100;
   // Short debounce for git operations
+  readyPromise = Promise.resolve();
+  resolveReady = null;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
   }
@@ -19600,8 +20155,12 @@ var GitHeadWatcher = class {
       return;
     }
     if (!isGitRepo(this.projectRoot)) {
+      this.readyPromise = Promise.resolve();
       return;
     }
+    this.readyPromise = new Promise((resolve18) => {
+      this.resolveReady = resolve18;
+    });
     this.onBranchChange = handler;
     this.currentBranch = getCurrentBranch(this.projectRoot);
     const headPath = getHeadPath(this.projectRoot);
@@ -19616,6 +20175,10 @@ var GitHeadWatcher = class {
     });
     this.watcher.on("change", () => this.handleHeadChange());
     this.watcher.on("add", () => this.handleHeadChange());
+    this.watcher.once("ready", () => {
+      this.resolveReady?.();
+      this.resolveReady = null;
+    });
   }
   handleHeadChange() {
     if (this.debounceTimer) {
@@ -19653,10 +20216,16 @@ var GitHeadWatcher = class {
       await watcher.close();
     }
     this.onBranchChange = null;
+    this.resolveReady?.();
+    this.resolveReady = null;
+    this.readyPromise = Promise.resolve();
   }
   isRunning() {
     return this.watcher !== null;
   }
+  async waitUntilReady() {
+    await this.readyPromise;
+  }
 };
 
 // src/watcher/index.ts
@@ -19706,7 +20275,10 @@ function createWatcherWithIndexer(getIndexer, projectRoot, config, host, options
     fileWatcher,
     gitWatcher,
     whenReady() {
-      return fileWatcher.waitUntilReady();
+      return Promise.all([
+        fileWatcher.waitUntilReady(),
+        gitWatcher?.waitUntilReady()
+      ]).then(() => void 0);
     },
     async stop() {
       stopped = true;
@@ -19767,9 +20339,9 @@ function parseGitActivity(output) {
     if (!filePath || addedRaw === "-" || deletedRaw === "-") continue;
     const churn = Number(addedRaw) + Number(deletedRaw);
     if (!Number.isFinite(churn) || churn <= 0) continue;
-    const normalizedPath = normalizePath4(filePath);
-    const previous = activity.get(normalizedPath);
-    activity.set(normalizedPath, {
+    const normalizedPath3 = normalizePath4(filePath);
+    const previous = activity.get(normalizedPath3);
+    activity.set(normalizedPath3, {
       churn: (previous?.churn ?? 0) + churn,
       commits: (previous?.commits ?? 0) + 1,
       latestDate: previous?.latestDate ?? latestDate,
@@ -20359,8 +20931,8 @@ function transformForVisualization(symbols, edges, options = {}) {
     const normalizedAbsoluteSuffix = `/${normalizedDirWithSlash}`;
     filteredSymbols = symbols.filter(
       (s) => {
-        const normalizedPath = s.filePath.replace(/\\/g, "/");
-        return normalizedPath === normalizedDir || normalizedPath.startsWith(normalizedDirWithSlash) || normalizedPath.endsWith(`/${normalizedDir}`) || normalizedPath.includes(normalizedAbsoluteSuffix);
+        const normalizedPath3 = s.filePath.replace(/\\/g, "/");
+        return normalizedPath3 === normalizedDir || normalizedPath3.startsWith(normalizedDirWithSlash) || normalizedPath3.endsWith(`/${normalizedDir}`) || normalizedPath3.includes(normalizedAbsoluteSuffix);
       }
     );
   }