@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.0

package/src/session/health-workflow.ts

@@ -4,6 +4,7 @@ import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
 import { isCodeRequestInterruption } from "@mrclrchtr/supi-code-runtime/api";
 import type {
   LspRuntimeController,
+  WorkspaceDiagnosticReport,
   WorkspaceLspRuntime,
   WorkspaceLspRuntimeState,
 } from "@mrclrchtr/supi-lsp/api";
@@ -18,6 +19,7 @@ import {
 } from "../analysis/health/diagnostics.ts";
 import { describeStructuralState } from "../analysis/health/recovery.ts";
 import { collectServers } from "../analysis/health/signals.ts";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { resolveScope } from "../analysis/search/paths.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
 import { collectHealthRefreshAttempt } from "./health-refresh.ts";
@@ -72,7 +74,7 @@ export async function runHealthWorkflow(
   const serverInventoryAvailable = lspState.kind === "ready" || lspState.kind === "disabled";
 
   const diagnosticsScope = diagnosticScope(scopeFilter);
-  const refresh = await collectRefreshState({
+  const refreshCollection = await collectRefreshState({
     refreshRequested: request.refresh === true,
     diagnosticsRequested: included.includes("diagnostics"),
     runtime,
@@ -102,10 +104,12 @@ export async function runHealthWorkflow(
     detailed: level === "detailed",
     requestControl: control,
     refreshEvidence:
-      (refresh.kind === "completed" || refresh.kind === "failed") &&
-      refresh.operationScope === "workspace-runtime"
-        ? refresh.diagnosticEvidence
+      (refreshCollection.attempt.kind === "completed" ||
+        refreshCollection.attempt.kind === "failed") &&
+      refreshCollection.attempt.operationScope === "workspace-runtime"
+        ? refreshCollection.attempt.diagnosticEvidence
         : undefined,
+    refreshReport: refreshCollection.diagnosticReport,
   });
   // A cancellation that landed during diagnostic resolution must not produce
   // a completed health result the caller no longer awaits.
@@ -121,7 +125,7 @@ export async function runHealthWorkflow(
     structuralStatus: describeStructuralState(capabilityStates.structural),
     diagnostics,
     servers,
-    refresh,
+    refresh: refreshCollection.attempt,
     level,
     capabilityWarnings: capabilityWarnings?.hasWarnings ? capabilityWarnings : undefined,
   };
@@ -154,7 +158,7 @@ async function establishSemanticHealthState(
     );
     if (readiness.kind === "ready") return { kind: "ready" };
     if (readiness.kind === "timeout") {
-      return { kind: "pending", reason: "File semantic readiness timed out" };
+      return { kind: "pending", reason: SEMANTIC_READINESS_TIMEOUT_REASON };
     }
     return { kind: "unavailable", reason: readiness.reason };
   }
@@ -213,6 +217,11 @@ function collectCapabilityWarnings(
   return report.hasWarnings ? report : undefined;
 }
 
+interface HealthRefreshStateCollection {
+  readonly attempt: HealthRefreshState;
+  readonly diagnosticReport?: WorkspaceDiagnosticReport;
+}
+
 interface RefreshStateOptions {
   readonly refreshRequested: boolean;
   readonly diagnosticsRequested: boolean;
@@ -224,27 +233,35 @@ interface RefreshStateOptions {
 }
 
 /** Run the requested workspace-runtime refresh and retain only facts the runtime establishes. */
-async function collectRefreshState(options: RefreshStateOptions): Promise<HealthRefreshState> {
+async function collectRefreshState(
+  options: RefreshStateOptions,
+): Promise<HealthRefreshStateCollection> {
   const { deps, diagnosticsRequested, diagnosticsScope, lspState, runtime } = options;
   if (!diagnosticsRequested) {
     return {
-      kind: "not-requested",
-      reason: "Diagnostics were not requested.",
-      lastAttempt: deps.lastRefreshAttempt,
+      attempt: {
+        kind: "not-requested",
+        reason: "Diagnostics were not requested.",
+        lastAttempt: deps.lastRefreshAttempt,
+      },
     };
   }
   if (!options.refreshRequested) {
     return {
-      kind: "not-requested",
-      reason: "Refresh was not requested.",
-      lastAttempt: deps.lastRefreshAttempt,
+      attempt: {
+        kind: "not-requested",
+        reason: "Refresh was not requested.",
+        lastAttempt: deps.lastRefreshAttempt,
+      },
     };
   }
   if (!runtime) {
     return {
-      kind: "not-attempted",
-      reason: refreshUnavailableReason(lspState),
-      lastAttempt: deps.lastRefreshAttempt,
+      attempt: {
+        kind: "not-attempted",
+        reason: refreshUnavailableReason(lspState),
+        lastAttempt: deps.lastRefreshAttempt,
+      },
     };
   }
 
@@ -270,7 +287,7 @@ async function collectRefreshState(options: RefreshStateOptions): Promise<Health
           message: "Refreshing diagnostics and recovery state",
         }),
     });
-    deps.trackRefreshAttempt(attempt);
+    deps.trackRefreshAttempt(attempt.attempt);
     return attempt;
   } catch (error) {
     // Cancellation must propagate; a cancelled caller no longer awaits a
@@ -285,7 +302,7 @@ async function collectRefreshState(options: RefreshStateOptions): Promise<Health
       reason: errorMessage(error),
     };
     deps.trackRefreshAttempt(attempt);
-    return attempt;
+    return { attempt };
   }
 }
 

package/src/session/input/workflows.ts

@@ -1,7 +1,7 @@
 /** Runtime parsers for inspection, Orientation, graph, and find workflows. */
 
-import { type CodeFindAstKind, isCodeFindAstKind } from "../../tool/find/ast-kinds.ts";
-import { CODE_FIND_MODES } from "../../tool/find/modes.ts";
+import { type CodeFindAstKind, isCodeFindAstKind } from "../../tool/code_find/ast-kinds.ts";
+import { CODE_FIND_MODES } from "../../tool/code_find/modes.ts";
 import type { FindMode, FindWorkflowInput } from "../find-types.ts";
 import type { GraphWorkflowInput, RequestedGraphRelation } from "../graph-types.ts";
 import type { InspectWorkflowInput } from "../inspect-types.ts";

package/src/session/inspect-workflow.ts

@@ -2,6 +2,7 @@
 
 import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
 import { withSemanticRequestControl } from "../analysis/provider.ts";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import type { CapabilityAdapter, ReadinessOutcome } from "./capability-adapter.ts";
 import { parseInspectWorkflowInput } from "./input/workflows.ts";
 import { collectInspectSections } from "./inspect/collect.ts";
@@ -155,7 +156,7 @@ function semanticReadinessReason(readiness: ReadinessOutcome): string {
     case "ready":
       return "No semantic provider is active for this file.";
     case "timeout":
-      return "Semantic readiness timed out.";
+      return SEMANTIC_READINESS_TIMEOUT_REASON;
     case "unavailable":
       return readiness.reason;
   }

package/src/session/orientation/collect.ts

@@ -183,7 +183,7 @@ async function buildEnrichedDefsSection(
       hasStructuralEvidence,
       hasSemanticEvidence: contextHasSemanticEvidence,
       status: contextHasSemanticEvidence ? "partial" : "unavailable",
-      reason: "Definition targets require a live language server.",
+      reason: deps.semanticReadinessReason ?? "Definition targets require a live language server.",
       evidenceLists: [],
     };
   }
@@ -292,7 +292,7 @@ async function buildDiagnosticsSection(
         },
       ],
       false,
-      "Diagnostics require a live language server.",
+      deps.semanticReadinessReason ?? "Diagnostics require a live language server.",
     );
   }
 

package/src/session/orientation-types.ts

@@ -37,6 +37,8 @@ export interface OrientationDeps {
   readonly provider: CodeProvider | null;
   readonly cwd: string;
   readonly lspRuntime: WorkspaceLspRuntimeState;
+  /** Typed reason to surface when target semantic readiness timed out. */
+  readonly semanticReadinessReason?: string;
   readonly requestControl?: CodeRequestControl;
 }
 

package/src/session/orientation-workflow.ts

@@ -9,6 +9,7 @@ import {
   findInstructionFilesForDirectory,
 } from "../analysis/instruction-files.ts";
 import { createStructuralCodeProvider, withSemanticRequestControl } from "../analysis/provider.ts";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { normalizePath } from "../analysis/search/paths.ts";
 import { loadCodeIntelligenceConfig } from "../config.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
@@ -33,6 +34,8 @@ export interface OrientationWorkflowDeps extends TargetWorkflowDeps {
   readonly markInstructionDirsSurfaced: (directories: string[]) => void;
   /** Whether the project is trusted — controls instruction-file discovery. */
   readonly projectTrusted: boolean;
+  /** Global config home for hermetic config reads; undefined uses os.homedir(). */
+  readonly homeDir?: string;
 }
 
 /** Resolve the Orientation focus and collect immutable facts for presentation adapters. */
@@ -146,11 +149,13 @@ async function orientTarget(options: {
   const provider = semanticReady
     ? withSemanticRequestControl(deps.capability.getProvider(deps.cwd), control)
     : createStructuralCodeProvider(deps.capability.getStructuralProvider(deps.cwd));
+  const semanticReadinessReason =
+    readiness.kind === "timeout" ? SEMANTIC_READINESS_TIMEOUT_REASON : undefined;
   const lspRuntime = semanticReady
     ? deps.capability.getLspRuntimeState(deps.cwd)
     : {
         kind: "unavailable" as const,
-        reason: readiness.kind === "timeout" ? "Semantic readiness timed out" : readiness.reason,
+        reason: readiness.kind === "timeout" ? SEMANTIC_READINESS_TIMEOUT_REASON : readiness.reason,
       };
   const result = await executeOrientation(
     { target: entry, maxResults },
@@ -158,6 +163,7 @@ async function orientTarget(options: {
       model,
       provider,
       lspRuntime,
+      semanticReadinessReason,
       cwd: deps.cwd,
       requestControl: control,
     },
@@ -201,7 +207,7 @@ function addInstructionFiles(
   deps: OrientationWorkflowDeps,
 ): Awaited<ReturnType<typeof executeOrientation>> {
   if (!deps.projectTrusted || !isDirectory(focusPath)) return result;
-  const config = loadCodeIntelligenceConfig(deps.cwd);
+  const config = loadCodeIntelligenceConfig(deps.cwd, deps.homeDir);
   const matches = findInstructionFilesForDirectory({
     directory: focusPath,
     cwd: deps.cwd,

package/src/session/refactor-workflow.ts

@@ -7,6 +7,7 @@ import type {
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { toLspPosition } from "@mrclrchtr/supi-lsp/api";
+import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { applyWorkspaceEdit } from "../analysis/refactor/apply.ts";
 import {
   establishMutationAuthority,
@@ -93,7 +94,7 @@ export async function runRefactorPlanWorkflow(
     control,
   );
   if (readiness.kind === "timeout") {
-    return { kind: "unavailable", reason: "Semantic readiness timed out." };
+    return { kind: "unavailable", reason: SEMANTIC_READINESS_TIMEOUT_REASON };
   }
   if (readiness.kind === "unavailable") return readiness;
   throwIfAborted(control);

package/src/session/session.ts

@@ -138,6 +138,8 @@ export class WorkspaceCodeIntelligenceSession {
 
   /** Whether the hidden architecture overview has been injected. */
   #hasInjectedOverview = false;
+  /** Pinned overview setting; null until resolved once per session. */
+  #overviewEnabled: boolean | null = null;
 
   /** Most recent explicit diagnostic refresh attempt, including its established outcome. */
   #lastHealthRefreshAttempt: HealthRefreshAttempt | null = null;
@@ -166,6 +168,9 @@ export class WorkspaceCodeIntelligenceSession {
   /** Whether the project owning this session is trusted for config loading. */
   #projectTrusted = false;
 
+  /** Global config home for hermetic config reads; undefined uses os.homedir(). */
+  #homeDir: string | undefined;
+
   constructor(cwd: string, capability?: CapabilityAdapter) {
     this.cwd = cwd;
     this.#capability = capability ?? new WorkspaceCapabilityAdapter();
@@ -176,6 +181,11 @@ export class WorkspaceCodeIntelligenceSession {
     this.#projectTrusted = trusted;
   }
 
+  /** Record the global-config home used for session config reads. */
+  setHomeDir(homeDir?: string): void {
+    this.#homeDir = homeDir;
+  }
+
   /** Attach lifecycle-owned LSP state without exposing it to Tool adapters. */
   attachLspController(controller: LspRuntimeController | null): void {
     this.#lspController = controller;
@@ -194,9 +204,22 @@ export class WorkspaceCodeIntelligenceSession {
     this.#hasInjectedOverview = true;
   }
 
+  /**
+   * Pin the overview setting resolved once per session. The first resolution
+   * wins; later config changes never toggle the setting mid-session.
+   */
+  setOverviewEnabledOnce(enabled: boolean): void {
+    this.#overviewEnabled ??= enabled;
+  }
+
+  /** Whether the overview setting has been pinned for this session. */
+  hasPinnedOverview(): boolean {
+    return this.#overviewEnabled !== null;
+  }
+
   /** Atomically claim first-turn overview injection for this workspace session. */
   claimOverviewInjection(): boolean {
-    if (this.#hasInjectedOverview) return false;
+    if (this.#overviewEnabled === false || this.#hasInjectedOverview) return false;
     this.#hasInjectedOverview = true;
     return true;
   }
@@ -284,6 +307,7 @@ export class WorkspaceCodeIntelligenceSession {
         surfacedInstructionDirs: this.#surfacedInstructionDirs,
         markInstructionDirsSurfaced: (directories) => this.markInstructionDirsSurfaced(directories),
         projectTrusted: this.#projectTrusted,
+        homeDir: this.#homeDir,
       },
       control,
     );

package/src/substrate/lsp/maintenance.ts

@@ -13,16 +13,38 @@ import {
   isCodeRequestInterruption,
   throwIfCodeRequestInterrupted,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type { DiagnosticEvidenceSummary } from "@mrclrchtr/supi-lsp/api";
 import {
-  clearTsconfigCache,
+  FileChangeType,
+  type FileEvent,
+  invalidateTsconfigCacheForConfig,
+  invalidateTsconfigCacheForConfigDir,
   isLikelyStaleDiagnostic,
+  isProjectConfigFileName,
   raceRequestControl,
   syncWorkspaceSentinelSnapshot,
   type WorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
 import { mergeDiagnosticEvidence } from "../../diagnostics/evidence.ts";
 
+/** Options shared by the workspace and file-scoped maintenance passes. */
+export interface LspMaintenanceOptions {
+  control?: CodeRequestControl;
+  /**
+   * Workspace-relative scope prefix for source-file discovery. Discovery only
+   * tracks created files inside this prefix; null disables the scope bound.
+   */
+  scope?: string | null;
+  /**
+   * Track files created since the last refresh so the following refresh pull
+   * includes them. Only the workspace-runtime path sets this; the snapshot is
+   * still widened on file-scoped passes so later diffs stay correct.
+   */
+  trackSources?: boolean;
+}
+
 /**
  * Run sentinel-sync, diagnostic refresh, and stale-module resync as a single
  * maintenance pass. Call before explicit diagnostic queries (code_health with
@@ -32,28 +54,28 @@ export async function refreshLspMaintenance(
   runtime: WorkspaceLspRuntime,
   cwd: string,
   sentinelSnapshot: Map<string, number>,
-  control?: CodeRequestControl,
+  options: LspMaintenanceOptions = {},
 ): Promise<WorkspaceLspMaintenanceResult> {
-  const { snapshot } = synchronizeSentinels(runtime, cwd, sentinelSnapshot);
+  const { snapshot } = await synchronizeSentinels(runtime, cwd, sentinelSnapshot, options);
   let diagnosticEvidence = emptyEvidence();
   let failureReason: string | undefined;
 
   // Refresh before stale-module inspection. The refresh owns deleted-file
   // classification; later snapshots must not erase its removed evidence.
   try {
-    diagnosticEvidence = await runtime.refreshOpenDiagnostics(undefined, control);
+    diagnosticEvidence = await runtime.refreshOpenDiagnostics(undefined, options.control);
   } catch (error) {
-    if (isCodeRequestInterruption(error, control)) throw error;
+    if (isCodeRequestInterruption(error, options.control)) throw error;
     failureReason = errorMessage(error);
     diagnosticEvidence = readRuntimeEvidence(runtime);
   }
 
   try {
-    const staleResult = await resyncStaleModuleFiles(runtime, cwd, control);
+    const staleResult = await resyncStaleModuleFiles(runtime, cwd, options.control);
     diagnosticEvidence = mergeDiagnosticEvidence(diagnosticEvidence, staleResult.evidence, cwd);
     if (staleResult.completed) failureReason = undefined;
   } catch (error) {
-    if (isCodeRequestInterruption(error, control)) throw error;
+    if (isCodeRequestInterruption(error, options.control)) throw error;
     // Keep evidence from the first refresh when stale inspection fails.
   }
 
@@ -93,15 +115,13 @@ export async function refreshFileLspMaintenance(options: {
   const { runtime, cwd, sentinelSnapshot, filePath, control } = options;
   // A cancelled caller stops before any maintenance work starts.
   throwIfCodeRequestInterrupted(control);
-  const { snapshot } = synchronizeSentinels(runtime, cwd, sentinelSnapshot);
+  const { snapshot } = await synchronizeSentinels(runtime, cwd, sentinelSnapshot);
   const target = nodePath.resolve(filePath);
-  const stale = runtime
-    .getOutstandingDiagnostics(1)
-    .entries.some(
-      (entry) =>
-        nodePath.resolve(cwd, entry.file) === target &&
-        entry.diagnostics.some((diagnostic) => isLikelyStaleDiagnostic(diagnostic)),
-    );
+  const stale = confirmedOutstandingDiagnostics(runtime, cwd).some(
+    (entry) =>
+      nodePath.resolve(cwd, entry.file) === target &&
+      entry.diagnostics.some((diagnostic) => isLikelyStaleDiagnostic(diagnostic)),
+  );
 
   runtime.pruneMissingFiles();
   if (stale) {
@@ -116,29 +136,91 @@ export async function refreshFileLspMaintenance(options: {
   return { snapshot, matchedStaleFileCount: stale ? 1 : 0 };
 }
 
-function synchronizeSentinels(
+/**
+ * Sync the widened workspace snapshot, forward sentinel changes, and track
+ * source files newly created since the last pass.
+ *
+ * The snapshot is widened to every regular file on every pass so later diffs
+ * see genuine creations. Only sentinel-file events are forwarded as workspace
+ * changes (config semantics unchanged); created source files are tracked only
+ * on the workspace-runtime path and only once the snapshot was primed by an
+ * earlier pass — the first pass establishes the baseline and cannot tell a
+ * just-created file from a long-existing one.
+ */
+async function synchronizeSentinels(
   runtime: WorkspaceLspRuntime,
   cwd: string,
   sentinelSnapshot: Map<string, number>,
+  options: LspMaintenanceOptions = {},
 ) {
-  const state = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot);
-  if (state.changes.length > 0) {
-    clearTsconfigCache();
-    runtime.noteWorkspaceChanges(state.changes);
+  const primed = sentinelSnapshot.size > 0;
+  const state = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot, {
+    includeSourceFiles: true,
+  });
+
+  invalidateChangedProjectConfigs(state.changes);
+  if (state.changes.length > 0) runtime.noteWorkspaceChanges(state.changes);
+
+  if (options.trackSources && primed) {
+    await trackCreatedSourceFiles(runtime, state.sourceChanges, options.scope);
   }
+
   return state;
 }
 
-/** Re-open files with stale module-resolution errors. */
+/** Invalidate cached tsconfig scope parses only for config files that changed. */
+function invalidateChangedProjectConfigs(changes: readonly FileEvent[]): void {
+  for (const change of changes) {
+    const filePath = uriToFile(change.uri);
+    if (!isProjectConfigFileName(nodePath.basename(filePath))) continue;
+    // Change-targeted invalidation: only config files affect tsconfig scope
+    // decisions. A created config can also turn previously empty lookups into
+    // resolved ones below the new config's directory.
+    invalidateTsconfigCacheForConfig(filePath);
+    if (change.type === FileChangeType.Created) {
+      invalidateTsconfigCacheForConfigDir(nodePath.dirname(filePath));
+    }
+  }
+}
+
+/** Track source files newly created since the last pass, within the scope bound. */
+async function trackCreatedSourceFiles(
+  runtime: WorkspaceLspRuntime,
+  sourceChanges: readonly FileEvent[],
+  scope: string | null | undefined,
+): Promise<void> {
+  for (const change of sourceChanges) {
+    if (change.type !== FileChangeType.Created) continue;
+    const filePath = uriToFile(change.uri);
+    if (scope && !isWithinOrEqual(scope, filePath)) continue;
+    // Best-effort: a file no client can serve stays untracked and is
+    // simply absent from evidence until a later explicit request.
+    await runtime.trackFile(filePath);
+  }
+}
+
+/** Return only diagnostics whose document evidence is confirmed. */
+function confirmedOutstandingDiagnostics(runtime: WorkspaceLspRuntime, cwd: string) {
+  const outstanding = runtime.getOutstandingDiagnostics(1);
+  const confirmedFiles = new Set(
+    outstanding.evidence.documents
+      .filter((document) => document.status === "confirmed")
+      .map((document) => nodePath.resolve(cwd, document.file)),
+  );
+  return outstanding.entries.filter((entry) =>
+    confirmedFiles.has(nodePath.resolve(cwd, entry.file)),
+  );
+}
+
+/** Re-open files with confirmed stale module-resolution errors. */
 async function resyncStaleModuleFiles(
   runtime: WorkspaceLspRuntime,
   cwd: string,
   control?: CodeRequestControl,
 ): Promise<{ evidence: DiagnosticEvidenceSummary; completed: boolean }> {
-  const outstanding = runtime.getOutstandingDiagnostics(1);
   const staleFiles: string[] = [];
 
-  for (const entry of outstanding.entries) {
+  for (const entry of confirmedOutstandingDiagnostics(runtime, cwd)) {
     if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
       staleFiles.push(entry.file);
     }

package/src/substrate/lsp/recovery.ts

@@ -11,7 +11,11 @@ import type {
   ToolResultEvent,
 } from "@earendil-works/pi-coding-agent";
 import { fileToUri } from "@mrclrchtr/supi-core/path";
-import { clearTsconfigCache } from "@mrclrchtr/supi-lsp/api";
+import {
+  invalidateTsconfigCacheForConfig,
+  invalidateTsconfigCacheForConfigDir,
+  isProjectConfigFileName,
+} from "@mrclrchtr/supi-lsp/api";
 import type { LspAdapterState } from "./state.ts";
 
 /** Tool names whose successful results should trigger workspace change notifications. */
@@ -37,10 +41,12 @@ export function registerWorkspaceRecoveryHandler(pi: ExtensionAPI, state: LspAda
       const normalized = filePath.startsWith("@") ? filePath.slice(1) : filePath;
       const resolved = nodePath.resolve(cwd, normalized);
 
-      // Invalidate tsconfig cache when config files change
-      const ext = nodePath.extname(resolved).toLowerCase();
-      if (ext === ".json" || ext === ".jsonc") {
-        clearTsconfigCache();
+      // Invalidate the tsconfig scope cache only when a project config itself
+      // changed; other .json/.jsonc writes (package.json and friends) do not
+      // affect scope decisions and keep their cached parses.
+      if (isProjectConfigFileName(nodePath.basename(resolved))) {
+        invalidateTsconfigCacheForConfig(resolved);
+        invalidateTsconfigCacheForConfigDir(nodePath.dirname(resolved));
       }
 
       runtime.noteWorkspaceChanges([{ uri: fileToUri(resolved), type: 2 }]);

package/src/tool/code_find/execute.ts

@@ -0,0 +1,23 @@
+/** Thin Pi adapter for the session-owned code_find workflow. */
+
+import type { FindMode, FindWorkflowInput } from "../../session/find-types.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import type { CodeFindAstKind } from "./ast-kinds.ts";
+import { finishFindResult } from "./result.ts";
+
+export interface CodeFindToolParams {
+  query: string;
+  scope?: string[];
+  mode: FindMode;
+  kind?: CodeFindAstKind;
+  maxResults?: number;
+}
+
+export async function executeFindTool(
+  params: CodeFindToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.find(params as FindWorkflowInput, toWorkflowControl(ctx));
+  return finishFindResult(outcome, params.scope);
+}

package/src/tool/code_find/guidance.ts

@@ -0,0 +1,8 @@
+export const toolDescription =
+  'Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic". Modes never silently fall back. Unscoped AST scans cover visible supported files, skipping hidden and generated/dependency directories.';
+
+export const promptSnippet = "explicit structural or semantic code search";
+
+export const promptGuidelines = [
+  "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
+];

package/src/tool/{find → code_find}/render.ts

@@ -4,8 +4,8 @@ import {
   type EvidenceListMetadata,
   renderEvidenceListMetadataDisclosure,
 } from "../../analysis/evidence.ts";
-import type { FindResultAssembly } from "../result/find.ts";
 import { renderStructuredEmptyState, renderStructuredMatches } from "./markdown.ts";
+import type { FindResultAssembly } from "./result.ts";
 
 export function renderFindResult(assembly: FindResultAssembly): string {
   const { outcome } = assembly;

package/src/tool/{result/find.ts → code_find/result.ts}

@@ -10,9 +10,9 @@ import {
   assembleToolResult,
   type ResultProvenance,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import { createToolDisplaySection } from "./display.ts";
-import type { SearchDetails, ToolDisplaySection } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection } from "../result/display.ts";
+import type { SearchDetails, ToolDisplaySection } from "../result/types.ts";
 
 /** Presentation-neutral assembled find result. */
 export interface FindResultAssembly {
@@ -81,16 +81,9 @@ function findNextQueries(outcome: Extract<FindWorkflowOutcome, { kind: "complete
   if (outcome.data.kind === "semantic" && outcome.data.symbols.length === 0) {
     return [
       "If you know the file, use code_resolve with a file selector to enumerate document declarations",
-      "Change mode only when you need a different code-aware evidence substrate",
     ];
   }
-  if (outcome.data.kind === "ast" && outcome.data.astKind === "call") {
-    return [
-      "Use code_graph references on a resolved target for symbol-identity relationships",
-      "Use PI grep for literal or regex source matches when it is active",
-    ];
-  }
-  return ["Change mode only when you need a different code-aware evidence substrate"];
+  return [];
 }
 
 function createFindEvidence(outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>): {
@@ -157,3 +150,35 @@ function findProvenance(
     ? [{ source: "semantic", capability: "workspace-symbol" }]
     : [{ source: "structural", capability: "tree-sitter" }];
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { searchErrorResult } from "../result/errors.ts";
+import { renderFindResult } from "./render.ts";
+
+type FindOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["find"]>>;
+
+/** Assemble the final model-visible code_find result for one workflow outcome. */
+export function finishFindResult(
+  outcome: FindOutcome,
+  scope: readonly string[] | undefined,
+): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return searchErrorResult(`**Error:** ${outcome.message}`, {
+      scope: Array.isArray(scope) ? scope.join(", ") : null,
+      nextQueries: ["Fix the search input and retry"],
+      message: outcome.message,
+    });
+  }
+
+  const assembly = assembleFindWorkflowResult(outcome);
+  return {
+    content: renderFindResult(assembly),
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}