@mrclrchtr/supi-code-intelligence 6.4.0 → 7.0.0

package/src/tool/code_health/tui.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
 import {
   formatProjectServerRouteStatusCounts,
   type ProjectServerRouteStatusCounts,
@@ -31,6 +31,11 @@ import {
   readRefreshStatus,
   readSourceTrackingStatus,
 } from "./refresh-status.ts";
+import {
+  formatCompactDiagnosticEvidence,
+  formatDiagnosticEvidence,
+  withDiagnosticScope,
+} from "./scope.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
 /** ── renderCall ────────────────────────────────────────────────── */
@@ -64,12 +69,16 @@ export function renderHealthResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Gathering workspace health…", theme);
 
   const data =
     result.details?.type === "health" ? (result.details.data as Record<string, unknown>) : null;
-  const executionError = renderExecutionError(context, "code_health failed", theme);
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_health failed" },
+    theme,
+  );
   if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);
@@ -136,7 +145,7 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
     formatSectionSummary(
       section,
       section.key === "diagnostics"
-        ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data))
+        ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data), diagnosticScopeKind(data))
         : null,
       theme,
       fileReadinessPending,
@@ -230,36 +239,6 @@ function readDiagnosticEvidence(
   return readRecord(readRecord(data?.diagnosticObservation)?.evidence);
 }
 
-function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  if (!evidence) return null;
-  const counts = [
-    evidence.requested,
-    evidence.confirmed,
-    evidence.unconfirmed,
-    evidence.failed,
-    evidence.removed,
-  ];
-  if (!counts.every(isEvidenceCount)) return null;
-  return `req ${evidence.requested} · conf ${evidence.confirmed} · unconf ${evidence.unconfirmed} · failed ${evidence.failed} · removed ${evidence.removed}`;
-}
-
-function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  if (!evidence) return null;
-  const counts = [
-    evidence.requested,
-    evidence.confirmed,
-    evidence.unconfirmed,
-    evidence.failed,
-    evidence.removed,
-  ];
-  if (!counts.every(isEvidenceCount)) return null;
-  return `${evidence.requested} requested, ${evidence.confirmed} confirmed, ${evidence.unconfirmed} unconfirmed, ${evidence.failed} failed, ${evidence.removed} removed`;
-}
-
-function isEvidenceCount(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0;
-}
-
 function readRecord(value: unknown): Record<string, unknown> | null {
   return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
 }
@@ -324,21 +303,29 @@ function buildDiagnosticSummary(data: Record<string, unknown> | null, theme: The
     const label = isPendingFileReadiness(data)
       ? "Diagnostics pending — LSP may still be warming; retry shortly"
       : "Diagnostics unavailable";
-    return new Text(theme.fg("warning", label), 0, 0);
+    return new Text(theme.fg("warning", withDiagnosticScope(label, data)), 0, 0);
   }
   const trackedFiles = diagnosticScopeKind(data) === "tracked-files";
   if (section.status === "partial") {
     const coverage = formatDiagnosticEvidence(readDiagnosticEvidence(data));
     const label = trackedFiles ? "Tracked-file diagnostics partial" : "Diagnostics partial";
-    return new Text(theme.fg("warning", coverage ? `${label} (${coverage})` : label), 0, 0);
+    const summary = coverage ? `${label} (${coverage})` : label;
+    return new Text(theme.fg("warning", withDiagnosticScope(summary, data)), 0, 0);
   }
   if (section.itemCount === 0) {
-    return new Text(theme.fg("success", diagnosticEmptySummary(data)), 0, 0);
+    return new Text(
+      theme.fg("success", withDiagnosticScope(diagnosticEmptySummary(data), data)),
+      0,
+      0,
+    );
   }
 
   const fileLabel = `${trackedFiles ? "tracked " : ""}${section.itemCount === 1 ? "file" : "files"}`;
   return new Text(
-    theme.fg("warning", theme.bold(`${section.itemCount} ${fileLabel} with issues`)),
+    theme.fg(
+      "warning",
+      theme.bold(withDiagnosticScope(`${section.itemCount} ${fileLabel} with issues`, data)),
+    ),
     0,
     0,
   );

package/src/tool/code_inspect/tui.ts

@@ -40,5 +40,11 @@ export function renderInspectResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Inspecting…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Inspecting…", failure: "code_inspect failed" },
+    context,
+  );
 }

package/src/tool/code_orientation/result.ts

@@ -1,5 +1,8 @@
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
-import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import {
+  type EvidenceListMetadata,
+  renderEvidenceListMetadataDisclosure,
+} from "../../analysis/evidence.ts";
 import type { ReadNextItem } from "../../analysis/read-next.ts";
 import type {
   OrientationCandidate,
@@ -15,6 +18,7 @@ import {
   type ResultSection,
   type ToolResultAssembly,
 } from "../result/assembly.ts";
+import { formatCandidateRow } from "../result/candidate-row.ts";
 import { createToolDisplaySection } from "../result/display.ts";
 import type {
   ContextDetails,
@@ -47,17 +51,17 @@ export interface OrientationResultAssembly {
 /** Build structured candidate rows for an unresolved Orientation target. */
 export function orientationCandidateDisplaySections(
   candidates: readonly OrientationCandidate[],
-  omittedCount = 0,
+  evidence: EvidenceListMetadata,
 ): readonly ToolDisplaySection[] {
   return [
     createToolDisplaySection({
       key: "orientation.candidates",
       title: "Candidates",
       items: candidates,
-      totalCount: candidates.length + omittedCount,
-      omittedCount,
-      format: (candidate) =>
-        `${candidate.rank}. ${candidate.name} (${candidate.kind ?? "unknown"}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`,
+      totalCount: evidence.totalCount,
+      omittedCount: evidence.omittedCount,
+      partialReason: evidence.partialReason,
+      format: (candidate) => formatCandidateRow(candidate, "rank-first"),
     }),
   ];
 }
@@ -215,13 +219,23 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
         `${candidate.rank}. **${candidate.name}** (\`${candidate.kind ?? "unknown"}\`) — \`${candidate.file}\`:${candidate.line}:${candidate.character} — \`${candidate.targetId}\``,
       );
     }
+    const evidence: EvidenceListMetadata = {
+      key: "orientation.candidates",
+      totalCount: outcome.totalCount,
+      shownCount: candidates.length,
+      omittedCount: outcome.omittedCount,
+      partialReason: outcome.partialReason,
+    };
+    const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+    if (disclosure) lines.push("", disclosure);
     const nextQueries =
       outcome.kind === "kind-mismatch"
         ? ["Retry without symbolKind, use an observed provider kind, or focus one handle"]
         : ["Use one candidate handle as focus.target.handle"];
     const details = assembleOrientationDetails({
       confidence: "semantic",
-      omittedCount: outcome.omittedCount,
+      omittedCount: evidence.omittedCount ?? 0,
+      evidenceLists: [evidence],
       candidates,
       nextQueries,
     });
@@ -231,7 +245,8 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
         type: "context",
         data: details,
         status: "completed",
-        displaySections: orientationCandidateDisplaySections(candidates, outcome.omittedCount),
+        message: orientationSelectionMessage(outcome),
+        displaySections: orientationCandidateDisplaySections(candidates, evidence),
       },
     };
   }
@@ -246,3 +261,11 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
     },
   };
 }
+
+function orientationSelectionMessage(
+  outcome: Extract<OrientationOutcome, { kind: "disambiguation" | "kind-mismatch" }>,
+): string {
+  return outcome.kind === "kind-mismatch"
+    ? `No Orientation target matched provider kind ${outcome.requestedKind}.`
+    : "Multiple Orientation targets require one candidate.";
+}

package/src/tool/code_orientation/tui.ts

@@ -1,6 +1,7 @@
 /** TUI renderer for code_orientation. */
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { renderCandidateSelection } from "../../ui/tui/candidate-selection.ts";
 import {
   type EvidenceEntry,
   formatCallPath,
@@ -50,15 +51,35 @@ export function renderOrientationResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Orienting…", theme);
 
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_orientation failed" },
+    theme,
+  );
+  if (executionError) return executionError;
+
+  const candidateSelection = renderCandidateSelection(
+    result,
+    options,
+    theme,
+    "orientation.candidates",
+  );
+  if (candidateSelection) return candidateSelection;
+
+  return renderOrientationDetails(result, options, theme);
+}
+
+function renderOrientationDetails(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+): Component {
   const data =
     result.details?.type === "context" ? (result.details.data as Record<string, unknown>) : null;
   const markdownText = result.content.find((c) => c.type === "text")?.text ?? "";
-
-  const executionError = renderExecutionError(context, "code_orientation failed", theme);
-  if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);
 

package/src/tool/code_refactor_apply/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Apply a fresh stored refactor plan to change its files. It does not create or regenerate a plan.";
+  "Apply a stored refactor plan by its returned planId after freshness and edit-safety checks. Changed files reject the apply and require a new plan; this tool does not regenerate one.";
 
 export const promptSnippet = "apply a stored refactor plan";
 

package/src/tool/code_refactor_apply/tui.ts

@@ -1,6 +1,6 @@
 /** TUI renderer for code_refactor_apply. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
 import {
   formatCallValue,
   type ResultOptios,
@@ -33,10 +33,14 @@ export function renderRefactorApplyResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Applying…", theme);
 
-  const executionError = renderExecutionError(context, "code_refactor_apply failed", theme);
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_refactor_apply failed" },
+    theme,
+  );
   if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);

package/src/tool/code_refactor_plan/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Preview a semantic refactor without changing files or falling back to text edits.";
+  "Create and store a semantic refactor preview without changing files. Unsupported operations do not fall back to text edits.";
 
 export const promptSnippet = "preview a semantic refactor";
 

package/src/tool/code_refactor_plan/tui.ts

@@ -50,5 +50,11 @@ export function renderRefactorPlanResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Planning…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Planning…", failure: "code_refactor_plan failed" },
+    context,
+  );
 }

package/src/tool/code_resolve/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Resolve a real symbol anchor or semantic query to target handles, or list a file's declarations as a target group. Symbol lookup does not fall back to text search.";
+  "Resolve a real symbol anchor or semantic query to target handles for later code tools, or list a file's declarations as a target group. This tool does not search file text.";
 
 export const promptSnippet = "resolve symbols or file declarations";
 
-export const promptGuidelines = [
-  "Use code_resolve when a symbol query can match multiple symbols or when a later tool requires a target handle.",
-];
+export const promptGuidelines: string[] = [];

package/src/tool/code_resolve/result.ts

@@ -10,6 +10,7 @@ import {
   type ResultProvenance,
   type ToolResultAssembly,
 } from "../result/assembly.ts";
+import { formatCandidateRow } from "../result/candidate-row.ts";
 import { createToolDisplaySection } from "../result/display.ts";
 import type { ResolveDetails, ToolDisplaySection } from "../result/types.ts";
 
@@ -25,7 +26,7 @@ export interface ResolveResultAssembly {
 interface ResolveProjection {
   readonly key: string;
   readonly title: string;
-  readonly status: "complete" | "unavailable";
+  readonly status: "complete" | "partial" | "unavailable";
   readonly items: readonly unknown[];
   readonly confidence: ConfidenceMode;
   readonly evidence: EvidenceListMetadata | null;
@@ -153,19 +154,19 @@ function projectTargetGroup(
 function projectCandidateOutcome(
   outcome: Extract<TargetWorkflowOutcome, { kind: "disambiguation" | "kind-mismatch" }>,
 ): ResolveProjection {
-  const totalCount = outcome.candidates.length + outcome.omittedCount;
   const evidence: EvidenceListMetadata = {
     key: "resolve.candidates",
-    totalCount,
+    totalCount: outcome.totalCount,
     shownCount: outcome.candidates.length,
     omittedCount: outcome.omittedCount,
-    partialReason: null,
+    partialReason: outcome.partialReason,
   };
+  const collectedCount = evidence.shownCount + (evidence.omittedCount ?? 0);
   const mismatch = outcome.kind === "kind-mismatch";
   return {
     key: "resolve.candidates",
     title: mismatch ? "Near matches" : "Candidates",
-    status: "complete",
+    status: outcome.partialReason ? "partial" : "complete",
     items: outcome.candidates,
     confidence: "semantic",
     evidence,
@@ -173,7 +174,7 @@ function projectCandidateOutcome(
       resultKind: outcome.kind,
       ...(mismatch ? { requestedKind: outcome.requestedKind } : {}),
       confidence: "semantic",
-      targetCount: totalCount,
+      targetCount: evidence.totalCount ?? collectedCount,
       omittedCount: outcome.omittedCount,
       evidenceLists: [evidence],
       targets: [],
@@ -254,15 +255,17 @@ function resolveDisplaySections(details: ResolveDetails): ToolDisplaySection[] {
   }
 
   if (details.candidates && details.candidates.length > 0) {
+    const evidence = details.evidenceLists?.find((entry) => entry.key === "resolve.candidates");
+    if (!evidence) return [];
     return [
       createToolDisplaySection({
         key: "resolve.candidates",
         title: "Candidates",
         items: details.candidates,
-        totalCount: details.targetCount,
-        omittedCount: details.omittedCount,
-        format: (candidate) =>
-          `${candidate.rank}. ${candidate.name} (${candidate.kind ?? "unknown"}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`,
+        totalCount: evidence.totalCount,
+        omittedCount: evidence.omittedCount,
+        partialReason: evidence.partialReason,
+        format: (candidate) => formatCandidateRow(candidate, "rank-first"),
       }),
     ];
   }

package/src/tool/code_resolve/tui.ts

@@ -1,6 +1,7 @@
 /** TUI renderer for code_resolve. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { renderCandidateSelection } from "../../ui/tui/candidate-selection.ts";
 import {
   formatCallPath,
   formatCallValue,
@@ -56,5 +57,21 @@ export function renderResolveResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Resolving…", context);
+  if (!options.isPartial && !context?.isError) {
+    const candidateSelection = renderCandidateSelection(
+      result,
+      options,
+      theme,
+      "resolve.candidates",
+    );
+    if (candidateSelection) return candidateSelection;
+  }
+
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Resolving…", failure: "code_resolve failed" },
+    context,
+  );
 }

package/src/tool/infra/truncate.ts

@@ -48,7 +48,7 @@ export function truncateToolContent(
   return { text: `${result.content}${notice}`, truncated: true };
 }
 
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CodeIntelResult } from "../../types/index.ts";
@@ -57,7 +57,9 @@ import type { ToolOutputTruncationDetails } from "../result/types.ts";
 /**
  * Apply the canonical output bound to one assembled code-tool result:
  * truncate at PI limits, spill the full content to a temp file when it
- * overflowed, and record truncation details.
+ * overflowed or the human display omits returned evidence. A display-only
+ * continuation does not add text to model content. File failure is fatal only
+ * when model content would otherwise be lost.
  */
 export function boundCodeToolResult(
   content: string,
@@ -71,19 +73,43 @@ export function boundCodeToolResult(
     maxLines: options.maxLines,
     maxBytes: options.maxBytes,
   });
-  if (truncated && content.length > 0) {
-    const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
-    const spillPath = join(dir, `${options.toolName}-output.md`);
-    writeFileSync(spillPath, content, "utf-8");
-    return {
-      content: [
-        { type: "text" as const, text: `${text}\n_Full output saved to: \`${spillPath}\`_` },
-      ],
-      details: withTruncation({ truncated: true, fullOutputPath: spillPath }),
-    };
+  const displayTruncated = details?.truncation?.displayTruncated === true;
+  const truncation = { truncated, ...(displayTruncated ? { displayTruncated } : {}) };
+  if ((truncated || displayTruncated) && content.length > 0) {
+    try {
+      const spillPath = saveFullContent(content, options.toolName);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: truncated ? `${text}\n_Full output saved to: \`${spillPath}\`_` : text,
+          },
+        ],
+        details: withTruncation({ ...truncation, fullOutputPath: spillPath }),
+      };
+    } catch (error) {
+      if (truncated) throw error;
+      // Keep valid evidence when only its optional human continuation failed.
+    }
   }
   return {
     content: [{ type: "text" as const, text }],
-    details: withTruncation({ truncated: false }),
+    details: withTruncation(truncation),
   };
 }
+
+function saveFullContent(content: string, toolName: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "supi-ci-"));
+  const spillPath = join(dir, `${toolName}-output.md`);
+  try {
+    writeFileSync(spillPath, content, "utf-8");
+    return spillPath;
+  } catch (error) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* Preserve the write error. */
+    }
+    throw error;
+  }
+}

package/src/tool/result/candidate-row.ts

@@ -0,0 +1,27 @@
+/** Candidate fields used by the three target-selection row formats. */
+export interface CandidateRowData {
+  readonly targetId: string;
+  readonly name: string;
+  readonly kind: string | null;
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly rank?: number;
+}
+
+/** The order used for the target id and rank in one candidate row. */
+export type CandidateRowOrder = "handle-first" | "rank-first";
+
+/** Format one candidate row for a serialized display section or TUI fallback. */
+export function formatCandidateRow(
+  candidate: CandidateRowData,
+  order: CandidateRowOrder,
+  fallbackRank = 1,
+): string {
+  const kind = candidate.kind ?? "unknown";
+  if (order === "handle-first") {
+    return `${candidate.targetId} — ${candidate.name} (${kind}) at ${candidate.file}:${candidate.line}:${candidate.character}`;
+  }
+  const rank = candidate.rank && candidate.rank > 0 ? candidate.rank : fallbackRank;
+  return `${rank}. ${candidate.name} (${kind}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`;
+}

package/src/tool/result/errors.ts

@@ -1,27 +1,42 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
 import type { CodeIntelResult, ToolDisplaySection } from "../../types/index.ts";
+import { assembledNextQueries, assembleToolResult } from "./assembly.ts";
 
-/** Full error result for search-family tools. */
+/** Full failure or candidate-selection result for search-family tools. */
 export function searchErrorResult(
   content: string,
   opts?: {
+    /** Candidate selection is not invalid usage. Defaults to invalid-input. */
+    status?: "invalid-input" | "disambiguation";
     scope?: string | null;
     nextQueries?: string[];
     message?: string;
     displaySections?: readonly ToolDisplaySection[];
+    /** Evidence retained when a target still needs selection. */
+    evidenceLists?: readonly EvidenceListMetadata[];
+    confidence?: ConfidenceMode;
   },
 ): CodeIntelResult {
+  const assembled = assembleToolResult({
+    data: null,
+    confidence: opts?.confidence ?? "unavailable",
+    evidenceLists: opts?.evidenceLists,
+    nextQueries: opts?.nextQueries,
+  });
   return {
     content,
     details: {
       type: "search" as const,
       data: {
-        confidence: "unavailable" as const,
+        confidence: assembled.confidence,
         scope: opts?.scope ?? null,
-        candidateCount: 0,
-        omittedCount: 0,
-        nextQueries: opts?.nextQueries ?? [],
+        candidateCount: assembled.totals.candidateCount,
+        omittedCount: assembled.totals.omittedCount,
+        ...(opts?.evidenceLists ? { evidenceLists: [...assembled.evidenceLists] } : {}),
+        nextQueries: assembledNextQueries(assembled),
       },
-      status: "invalid-input",
+      status: opts?.status ?? "invalid-input",
       ...(opts?.message ? { message: opts.message } : {}),
       ...(opts?.displaySections ? { displaySections: opts.displaySections } : {}),
     },

package/src/tool/result/types.ts

@@ -22,9 +22,13 @@ import type { ResultProvenance } from "./assembly.ts";
 /** Final state for a public tool result. */
 export type ToolResultStatus = "completed" | "invalid-input" | "disambiguation" | "unavailable";
 
-/** Truncation state for model-facing tool content. */
+/** Separate model-content and human-display bounds, with one optional continuation file. */
 export interface ToolOutputTruncationDetails {
+  /** Model content exceeded the PI output limit. */
   truncated: boolean;
+  /** The TUI omits evidence that remains in the model content. */
+  displayTruncated?: boolean;
+  /** Full returned content, not evidence beyond the requested result limit. */
   fullOutputPath?: string;
 }
 
@@ -240,9 +244,9 @@ export interface HealthDetails {
   serverInventoryAvailable: boolean;
   /** Server inventory remains workspace-wide even for a scoped diagnostic request. */
   serverInventoryScope: "workspace";
-  /** Exact status and evidence boundary of the diagnostic observation. */
+  /** Diagnostic result scope and exact evidence boundary for this health call. */
   diagnosticObservation: HealthDiagnosticObservation;
-  /** Current or most recent explicit diagnostic refresh attempt. */
+  /** Current or most recent refresh, including typed maintenance scope and evidence. */
   refresh: HealthRefreshState;
   structuralAvailable: boolean;
   /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */

package/src/tool/schemas.ts

@@ -21,6 +21,11 @@ export const QueryParam = Type.String({
   description: "Human or code reference to resolve or search for.",
   minLength: 1,
 });
+export const FindQueryParam = Type.String({
+  description:
+    "AST mode: name or import module-specifier substring. Semantic mode: workspace-symbol query.",
+  minLength: 1,
+});
 const LineParam = Type.Integer({ description: "1-based line.", minimum: 1 });
 const CharacterParam = Type.Integer({
   description: "1-based UTF-16 column.",

package/src/types/execution.ts

@@ -1,5 +1,6 @@
 import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
 import type { WorkspaceCodeIntelligenceSession } from "../session/session.ts";
+import type { GraphDetails } from "../tool/code_graph/details.ts";
 import type {
   ContextDetails,
   HealthDetails,
@@ -59,6 +60,7 @@ export interface CodeIntelResult {
     | (CodeIntelResultDetails & { type: "context"; data: ContextDetails })
     | (CodeIntelResultDetails & { type: "inspect"; data: InspectDetails })
     | (CodeIntelResultDetails & { type: "search"; data: SearchDetails })
+    | (CodeIntelResultDetails & { type: "graph"; data: GraphDetails })
     | (CodeIntelResultDetails & { type: "resolve"; data: ResolveDetails })
     | (CodeIntelResultDetails & { type: "health"; data: HealthDetails });
 }

package/src/types/index.ts

@@ -16,6 +16,8 @@ export type {
 
 // ── Detail types ────────────────────────────────────────────────────────
 
+export type { GraphDetails, GraphSectionDetails } from "../tool/code_graph/details.ts";
+
 export type {
   AnchoredResolutionMetadata,
   AnchoredResolutionSource,