open-codebase-index 0.22.2 → 0.22.4

package/dist/index.cjs

@@ -1,4 +1,4 @@
-// opencode-codebase-index - Semantic codebase search for OpenCode
+// open-codebase-index - Semantic codebase indexing and search
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -1925,6 +1925,9 @@ var RELATIONSHIP_TYPES = [
 ];
 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;
@@ -2548,6 +2551,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();
@@ -2596,13 +2609,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;
@@ -2635,6 +2648,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,
@@ -8613,12 +8635,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";
@@ -9067,9 +9089,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);
@@ -12942,6 +12964,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,
@@ -13133,6 +13169,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) => {
@@ -14400,7 +14446,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) {
@@ -14454,15 +14501,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 };
@@ -14678,17 +14729,17 @@ async function getIndexLogs(projectRoot, host, args) {
 function addKnowledgeBase(projectRoot, host, knowledgeBasePath) {
   const root = getProjectRoot(projectRoot, host);
   const inputPath = knowledgeBasePath.trim();
-  const normalizedPath = path20.resolve(
+  const normalizedPath2 = path20.resolve(
     path20.isAbsolute(inputPath) ? inputPath : resolveKnowledgeBasePath(inputPath, root)
   );
-  if (!(0, import_fs13.existsSync)(normalizedPath)) {
-    return `Error: Directory does not exist: ${normalizedPath}`;
+  if (!(0, import_fs13.existsSync)(normalizedPath2)) {
+    return `Error: Directory does not exist: ${normalizedPath2}`;
   }
   let realPath;
   try {
-    realPath = (0, import_fs13.realpathSync)(normalizedPath);
+    realPath = (0, import_fs13.realpathSync)(normalizedPath2);
   } catch {
-    return `Error: Cannot resolve path: ${normalizedPath}`;
+    return `Error: Cannot resolve path: ${normalizedPath2}`;
   }
   const blockedPrefixes = [
     "/etc",
@@ -14711,34 +14762,34 @@ function addKnowledgeBase(projectRoot, 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 stat4 = (0, import_fs13.statSync)(normalizedPath);
+    const stat4 = (0, import_fs13.statSync)(normalizedPath2);
     if (!stat4.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}
 `;
@@ -16783,6 +16834,8 @@ var GitHeadWatcher = class {
   debounceTimer = null;
   debounceMs = 100;
   // Short debounce for git operations
+  readyPromise = Promise.resolve();
+  resolveReady = null;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
   }
@@ -16791,8 +16844,12 @@ var GitHeadWatcher = class {
       return;
     }
     if (!isGitRepo(this.projectRoot)) {
+      this.readyPromise = Promise.resolve();
       return;
     }
+    this.readyPromise = new Promise((resolve15) => {
+      this.resolveReady = resolve15;
+    });
     this.onBranchChange = handler;
     this.currentBranch = getCurrentBranch(this.projectRoot);
     const headPath = getHeadPath(this.projectRoot);
@@ -16807,6 +16864,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) {
@@ -16844,10 +16905,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
@@ -16897,7 +16964,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;
@@ -17032,6 +17102,181 @@ var pr_impact = tool({
   }
 });
 
+// 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/tools/context-search.ts
 var MIN_CONTEXT_RESULT_LIMIT = 1;
 var MAX_CONTEXT_RESULT_LIMIT = 100;
@@ -17134,6 +17379,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) {
@@ -17173,6 +17439,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,
@@ -17201,8 +17468,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),
@@ -17222,7 +17501,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) => {
@@ -17231,13 +17510,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: {
@@ -17245,7 +17534,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)
+        }
       }
     };
   };
@@ -17259,8 +17551,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) {
@@ -17278,8 +17580,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")
           );
         }
       }
@@ -17298,7 +17610,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])
+          }
         }
       };
     }
@@ -17338,8 +17653,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")
       );
     }
   }
@@ -17355,7 +17679,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])
+      }
     }
   };
 }
@@ -17436,17 +17763,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
     })
   });
 }
@@ -17513,7 +17850,11 @@ async function resolveCodebaseContext(projectRoot, host, input) {
 
 // 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);
@@ -17616,9 +17957,9 @@ function parseGitActivity(output) {
     if (!filePath || addedRaw === "-" || deletedRaw === "-") continue;
     const churn = Number(addedRaw) + Number(deletedRaw);
     if (!Number.isFinite(churn) || churn <= 0) continue;
-    const normalizedPath = normalizePath3(filePath);
-    const previous = activity.get(normalizedPath);
-    activity.set(normalizedPath, {
+    const normalizedPath2 = normalizePath3(filePath);
+    const previous = activity.get(normalizedPath2);
+    activity.set(normalizedPath2, {
       churn: (previous?.churn ?? 0) + churn,
       commits: (previous?.commits ?? 0) + 1,
       latestDate: previous?.latestDate ?? latestDate,
@@ -18208,8 +18549,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 normalizedPath2 = s.filePath.replace(/\\/g, "/");
+        return normalizedPath2 === normalizedDir || normalizedPath2.startsWith(normalizedDirWithSlash) || normalizedPath2.endsWith(`/${normalizedDir}`) || normalizedPath2.includes(normalizedAbsoluteSuffix);
       }
     );
   }
@@ -18283,6 +18624,26 @@ var z3 = tool.schema;
 var DEFAULT_HOST = "opencode";
 var CHUNK_TYPE_VALUES = CHUNK_TYPES;
 var RELATIONSHIP_TYPE_VALUES = RELATIONSHIP_TYPES;
+function stableSortedDiagnosticValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stableSortedDiagnosticValue(item));
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+  const sorted = {};
+  for (const [key, item] of entries) {
+    sorted[key] = stableSortedDiagnosticValue(item);
+  }
+  return sorted;
+}
+function formatCodebaseContextDiagnostic(details) {
+  const sorted = stableSortedDiagnosticValue(details);
+  return `
+Diagnostics:
+${JSON.stringify(sorted, null, 2)}`;
+}
 function initializeTools2(projectRoot, config) {
   initializeTools(projectRoot, config, DEFAULT_HOST);
 }
@@ -18302,10 +18663,29 @@ var codebase_context = tool({
     maxDepth: z3.number().int().min(MIN_CONTEXT_PATH_DEPTH).max(MAX_CONTEXT_PATH_DEPTH).nullable().optional().default(10).describe(`Maximum call-path traversal depth (${MIN_CONTEXT_PATH_DEPTH}-${MAX_CONTEXT_PATH_DEPTH})`),
     fileType: z3.string().nullable().optional().describe("Filter by file extension"),
     directory: z3.string().nullable().optional().describe("Filter by directory path"),
-    tokenBudget: z3.number().int().min(MIN_CONTEXT_PACK_TOKEN_BUDGET).max(MAX_CONTEXT_PACK_TOKEN_BUDGET).nullable().optional().default(DEFAULT_CONTEXT_PACK_TOKEN_BUDGET).describe(`Maximum response tokens (${MIN_CONTEXT_PACK_TOKEN_BUDGET}-${MAX_CONTEXT_PACK_TOKEN_BUDGET})`)
+    tokenBudget: z3.number().int().min(MIN_CONTEXT_PACK_TOKEN_BUDGET).max(MAX_CONTEXT_PACK_TOKEN_BUDGET).nullable().optional().default(DEFAULT_CONTEXT_PACK_TOKEN_BUDGET).describe(`Maximum response tokens (${MIN_CONTEXT_PACK_TOKEN_BUDGET}-${MAX_CONTEXT_PACK_TOKEN_BUDGET})`),
+    diagnostic: z3.boolean().optional().describe("Collect diagnostic routing and search traces without changing normal text output.")
+  },
+  async execute(args, context) {
+    const result = await executeCodebaseContext(context?.worktree, DEFAULT_HOST, args);
+    if (!args.diagnostic || !result.details?.diagnostic) {
+      return result.text;
+    }
+    return `${result.text}${formatCodebaseContextDiagnostic(result.details.diagnostic)}`;
+  }
+});
+var codebase_edit_context = tool({
+  description: "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 the target cannot be resolved.",
+  args: {
+    query: z3.string().describe("The requested change or target behavior"),
+    symbol: z3.string().nullable().optional().describe("Authoritative target symbol when known"),
+    filePath: z3.string().nullable().optional().describe("Optional file path used to disambiguate duplicate symbol names"),
+    callerLimit: z3.number().int().min(MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).max(MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).nullable().optional().default(DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT),
+    calleeLimit: z3.number().int().min(MIN_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).max(MAX_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT).nullable().optional().default(DEFAULT_CODEBASE_EDIT_CONTEXT_EDGE_LIMIT),
+    tokenBudget: z3.number().int().min(MIN_CONTEXT_PACK_TOKEN_BUDGET).max(MAX_CONTEXT_PACK_TOKEN_BUDGET).nullable().optional().default(DEFAULT_CONTEXT_PACK_TOKEN_BUDGET)
   },
   async execute(args, context) {
-    return (await executeCodebaseContext(context?.worktree, DEFAULT_HOST, args)).text;
+    return (await executeCodebaseEditContext(context?.worktree, DEFAULT_HOST, args)).text;
   }
 });
 var codebase_peek = tool({
@@ -18562,6 +18942,7 @@ var index_visualize = tool({
 // 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",
@@ -18585,6 +18966,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,
@@ -18601,6 +18983,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,
@@ -18621,6 +19004,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,
@@ -19075,6 +19459,7 @@ var plugin = async ({ directory, worktree }) => {
     return {
       tool: {
         [TOOL_NAME.CODEBASE_CONTEXT]: codebase_context,
+        [TOOL_NAME.CODEBASE_EDIT_CONTEXT]: codebase_edit_context,
         [TOOL_NAME.CODEBASE_SEARCH]: codebase_search,
         [TOOL_NAME.CODEBASE_PEEK]: codebase_peek,
         [TOOL_NAME.INDEX_CODEBASE]: index_codebase,