open-codebase-index 0.22.3 → 0.22.4

package/dist/pi-extension.js

@@ -2041,6 +2041,9 @@ function findKnowledgeBasePathIndex(knowledgeBases, inputPath, projectRoot3) {
 }
 
 // src/tools/contracts.ts
+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;
@@ -2664,6 +2667,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();
@@ -2712,13 +2725,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;
@@ -2751,6 +2764,15 @@ function buildContextPack(results, options = {}) {
   const fitted = fitTextToContextBudget(text3, 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,
@@ -8575,12 +8597,12 @@ function diversifyGroupBySymbol(entries, getCandidate) {
   return [...primary, ...remainder];
 }
 function buildDiversityKey(metadata) {
-  const normalizedPath = metadata.filePath.toLowerCase();
+  const normalizedPath2 = metadata.filePath.toLowerCase();
   const normalizedName = (metadata.name ?? "").trim().toLowerCase();
   if (normalizedName.length > 0) {
-    return `${normalizedPath}#${normalizedName}`;
+    return `${normalizedPath2}#${normalizedName}`;
   }
-  return normalizedPath;
+  return normalizedPath2;
 }
 function rankHybridResults(query, semanticResults, keywordResults, options) {
   const prioritizeSourcePaths = options.prioritizeSourcePaths ?? classifyQueryIntentRaw(query) === "source";
@@ -9029,9 +9051,9 @@ function normalizeFilePathForHintMatch(filePath) {
   return filePath.replace(/\\/g, "/").toLowerCase().replace(/^\.\//, "");
 }
 function pathMatchesHint(filePath, hint) {
-  const normalizedPath = normalizeFilePathForHintMatch(filePath);
+  const normalizedPath2 = normalizeFilePathForHintMatch(filePath);
   const normalizedHint = normalizeFilePathForHintMatch(hint);
-  return normalizedPath.endsWith(normalizedHint) || normalizedPath.includes(`/${normalizedHint}`) || normalizedPath.includes(normalizedHint);
+  return normalizedPath2.endsWith(normalizedHint) || normalizedPath2.includes(`/${normalizedHint}`) || normalizedPath2.includes(normalizedHint);
 }
 function extractFilePathHint(query) {
   const match = query.match(FILE_PATH_HINT_SUFFIX_REGEX);
@@ -12904,6 +12926,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,
@@ -13095,6 +13131,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) => {
@@ -14355,7 +14401,8 @@ async function searchCodebase(projectRoot3, host, query, options = {}) {
     definitionIntent: options.definitionIntent,
     blameAuthor: options.blameAuthor,
     blameSha: options.blameSha,
-    blameSince: options.blameSince
+    blameSince: options.blameSince,
+    trace: options.trace
   });
 }
 async function searchCodebaseWithEffectiveness(projectRoot3, host, route, query, options, render) {
@@ -14409,15 +14456,19 @@ async function implementationLookup(projectRoot3, 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(projectRoot3, host, params) {
   await ensureAutoIndexReadyForRetrieval(projectRoot3, host);
   const root = getProjectRoot(projectRoot3, host);
   const indexer = getIndexerForProject(root, host);
+  return getCallGraphDataForIndexer(indexer, root, params);
+}
+async function getCallGraphDataForIndexer(indexer, projectRoot3, params) {
   const symbols = await indexer.getCallGraphSymbols();
-  const resolution = resolveCallGraphSymbol(symbols, root, params.name, params.filePath, params.symbolId);
+  const resolution = resolveCallGraphSymbol(symbols, projectRoot3, 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 };
@@ -14645,17 +14696,17 @@ async function getIndexLogs(projectRoot3, host, args) {
 function addKnowledgeBase(projectRoot3, host, knowledgeBasePath) {
   const root = getProjectRoot(projectRoot3, host);
   const inputPath = knowledgeBasePath.trim();
-  const normalizedPath = path20.resolve(
+  const normalizedPath2 = path20.resolve(
     path20.isAbsolute(inputPath) ? inputPath : resolveKnowledgeBasePath(inputPath, root)
   );
-  if (!existsSync12(normalizedPath)) {
-    return `Error: Directory does not exist: ${normalizedPath}`;
+  if (!existsSync12(normalizedPath2)) {
+    return `Error: Directory does not exist: ${normalizedPath2}`;
   }
   let realPath;
   try {
-    realPath = realpathSync5(normalizedPath);
+    realPath = realpathSync5(normalizedPath2);
   } catch {
-    return `Error: Cannot resolve path: ${normalizedPath}`;
+    return `Error: Cannot resolve path: ${normalizedPath2}`;
   }
   const blockedPrefixes = [
     "/etc",
@@ -14678,34 +14729,34 @@ function addKnowledgeBase(projectRoot3, host, knowledgeBasePath) {
   ];
   for (const prefix of blockedPrefixes) {
     if (realPath === prefix || realPath.startsWith(`${prefix}/`)) {
-      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath}`;
+      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath2}`;
     }
   }
   for (const dotDir of sensitiveDotDirs) {
     const sensitiveDir = path20.join(homeDir, dotDir);
     if (sensitiveDir && (realPath === sensitiveDir || realPath.startsWith(`${sensitiveDir}/`))) {
-      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath}`;
+      return `Error: Adding sensitive directory as knowledge base is not allowed: ${normalizedPath2}`;
     }
   }
   try {
-    const stat = statSync5(normalizedPath);
+    const stat = statSync5(normalizedPath2);
     if (!stat.isDirectory()) {
-      return `Error: Path is not a directory: ${normalizedPath}`;
+      return `Error: Path is not a directory: ${normalizedPath2}`;
     }
   } catch (error) {
-    return `Error: Cannot access directory: ${normalizedPath} - ${error instanceof Error ? error.message : String(error)}`;
+    return `Error: Cannot access directory: ${normalizedPath2} - ${error instanceof Error ? error.message : String(error)}`;
   }
   const config = loadEditableConfig(root, host);
   const knowledgeBases = Array.isArray(config.knowledgeBases) ? config.knowledgeBases : [];
-  const alreadyExists = hasMatchingKnowledgeBasePath(knowledgeBases, normalizedPath, root);
+  const alreadyExists = hasMatchingKnowledgeBasePath(knowledgeBases, normalizedPath2, root);
   if (alreadyExists) {
-    return `Knowledge base already configured: ${normalizedPath}`;
+    return `Knowledge base already configured: ${normalizedPath2}`;
   }
-  knowledgeBases.push(normalizedPath);
+  knowledgeBases.push(normalizedPath2);
   config.knowledgeBases = knowledgeBases;
   saveConfig(root, config, host);
   refreshIndexerForDirectory(root, host);
-  let result = `${normalizedPath}
+  let result = `${normalizedPath2}
 `;
   result += `Total knowledge bases: ${knowledgeBases.length}
 `;
@@ -14880,6 +14931,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) {
@@ -14919,6 +14991,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,
@@ -14947,8 +15020,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),
@@ -14968,7 +15053,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) => {
@@ -14977,13 +15062,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: {
@@ -14991,7 +15086,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)
+        }
       }
     };
   };
@@ -15005,8 +15103,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) {
@@ -15024,8 +15132,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")
           );
         }
       }
@@ -15044,7 +15162,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])
+          }
         }
       };
     }
@@ -15084,8 +15205,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")
       );
     }
   }
@@ -15101,7 +15231,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])
+      }
     }
   };
 }
@@ -15182,17 +15315,27 @@ async function resolveCodebaseContextUnmeasured(projectRoot3, host, input) {
       details: fittedDetails("path", fitted, 0)
     };
   }
-  return resolveSearchContext({ query: input.query, symbol, limit, tokenBudget, fileType, directory }, {
-    lookup: (lookupSymbol, retrievalLimit, scope) => implementationLookup(projectRoot3, host, lookupSymbol, {
+  return resolveSearchContext({
+    query: input.query,
+    symbol,
+    limit,
+    tokenBudget,
+    fileType,
+    directory,
+    diagnostic: input.diagnostic
+  }, {
+    lookup: (lookupSymbol, retrievalLimit, scope, trace) => implementationLookup(projectRoot3, host, lookupSymbol, {
       limit: retrievalLimit,
       fileType: scope.fileType,
-      directory: scope.directory
+      directory: scope.directory,
+      trace
     }),
-    search: (queryText, retrievalLimit, scope) => searchCodebase(projectRoot3, host, queryText, {
+    search: (queryText, retrievalLimit, scope, trace) => searchCodebase(projectRoot3, host, queryText, {
       limit: retrievalLimit,
       fileType: scope.fileType,
       directory: scope.directory,
-      metadataOnly: true
+      metadataOnly: true,
+      trace
     })
   });
 }
@@ -15257,12 +15400,188 @@ async function resolveCodebaseContext(projectRoot3, 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(projectRoot3, host, input) {
+  return resolveCodebaseEditContextWithDependencies(input, {
+    searchCodebase: (query, options) => searchCodebase(projectRoot3, host, query, options),
+    implementationLookup: (query, options) => implementationLookup(projectRoot3, host, query, options),
+    getCallGraphData: (params) => getCallGraphData(projectRoot3, host, params)
+  });
+}
+
 // src/adapters/pi/call-graph.ts
 import { Type } from "typebox";
 
 // 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",
@@ -15286,6 +15605,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,
@@ -15302,6 +15622,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,
@@ -15322,6 +15643,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,
@@ -15436,6 +15758,7 @@ function codebaseIndexPiExtension(pi) {
         Type2.Integer({ minimum: MIN_CONTEXT_PATH_DEPTH, maximum: MAX_CONTEXT_PATH_DEPTH }),
         Type2.Null()
       ], { default: 10, description: `Maximum call-graph traversal depth (${MIN_CONTEXT_PATH_DEPTH}-${MAX_CONTEXT_PATH_DEPTH})` })),
+      diagnostic: Type2.Optional(Type2.Union([Type2.Boolean(), Type2.Null()], { description: "Collect diagnostic routing and search traces without changing normal output." })),
       fileType: Type2.Optional(Type2.Union([Type2.String(), Type2.Null()], { description: "Filter by file extension, e.g., ts, py, rs" })),
       directory: Type2.Optional(Type2.Union([Type2.String(), Type2.Null()], { description: "Filter by directory path" })),
       tokenBudget: Type2.Optional(Type2.Union([
@@ -15447,10 +15770,40 @@ function codebaseIndexPiExtension(pi) {
       }))
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = await resolveCodebaseContext(projectRoot2(ctx), HOST2, params);
+      const normalizedParams = {
+        ...params,
+        diagnostic: params.diagnostic ?? void 0
+      };
+      const result = await resolveCodebaseContext(projectRoot2(ctx), HOST2, normalizedParams);
       return text2(result.text, result.details);
     }
   });
+  pi.registerTool({
+    name: TOOL_NAME.CODEBASE_EDIT_CONTEXT,
+    label: "Codebase Edit Context",
+    description: "PRE-EDIT TOOL for a known or suspected symbol. Returns bounded target source and direct graph evidence, with a risk-marked fallback when unresolved.",
+    parameters: Type2.Object({
+      query: Type2.String({ description: "The requested change or target behavior" }),
+      symbol: Type2.Optional(Type2.Union([Type2.String(), Type2.Null()])),
+      filePath: Type2.Optional(Type2.Union([Type2.String(), Type2.Null()])),
+      callerLimit: Type2.Optional(Type2.Union([
+        Type2.Integer({ minimum: MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT, maximum: MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT }),
+        Type2.Null()
+      ], { default: DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT })),
+      calleeLimit: Type2.Optional(Type2.Union([
+        Type2.Integer({ minimum: MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT, maximum: MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT }),
+        Type2.Null()
+      ], { default: DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT })),
+      tokenBudget: Type2.Optional(Type2.Union([
+        Type2.Integer({ minimum: MIN_CONTEXT_PACK_TOKEN_BUDGET, maximum: MAX_CONTEXT_PACK_TOKEN_BUDGET }),
+        Type2.Null()
+      ], { default: DEFAULT_CONTEXT_PACK_TOKEN_BUDGET }))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const result = await resolveCodebaseEditContext(projectRoot2(ctx), HOST2, params);
+      return text2(result.text);
+    }
+  });
   pi.registerTool({
     name: TOOL_NAME.CODEBASE_SEARCH,
     label: "Codebase Search",