@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/tool/{health → code_health}/tui.ts

@@ -6,33 +6,43 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import {
   type EvidenceEntry,
-  formatEvidenceEntry,
+  formatCallValue,
   type ResultOptios,
+  renderDomainError,
+  renderDomainResult,
   renderEvidenceLines,
+  renderExecutionError,
   renderMarkdownDetail,
   renderPartial,
+  renderToolDisplaySections,
+  renderTruncationDisclosure,
+  type ToolRendererContext,
   type ToolResult,
 } from "../../ui/tui/common.ts";
 import type { CodeHealthToolParams } from "./execute.ts";
+import { readPreviousRefreshStatus, readRefreshStatus } from "./refresh-status.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
 /** ── renderCall ────────────────────────────────────────────────── */
 
-export function renderHealthCall(args: unknown, theme: Theme, _context: unknown): Text {
-  const params = (args ?? {}) as CodeHealthToolParams;
+export function renderHealthCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as Partial<CodeHealthToolParams>;
   const sections =
     params.include === undefined
       ? "diag, servers"
-      : params.include.length > 0
-        ? params.include.join(", ")
+      : Array.isArray(params.include) && params.include.length > 0
+        ? params.include.map((section) => formatCallValue(section, 20) ?? "?").join(", ")
         : "none";
 
   let content = theme.fg("toolTitle", "code_health");
   content += ` ${theme.fg("accent", sections)}`;
 
-  if (params.scope) {
-    content += ` ${theme.fg("dim", params.scope)}`;
-  }
+  const scope = formatCallValue(params.scope);
+  if (scope) content += ` ${theme.fg("dim", scope)}`;
 
   return new Text(content, 0, 0);
 }
@@ -43,27 +53,29 @@ export function renderHealthResult(
   result: ToolResult,
   options: ResultOptios,
   theme: Theme,
-  _context: unknown,
+  context: ToolRendererContext | undefined,
 ): Container | Text {
-  if (options.isPartial) {
-    return renderPartial("Gathering workspace health…", theme);
-  }
+  if (options.isPartial) return renderPartial("Gathering workspace health…", theme);
 
-  const container = new Container();
   const data =
     result.details?.type === "health" ? (result.details.data as Record<string, unknown>) : null;
-
-  if (result.isError) {
-    container.addChild(new Text(theme.fg("error", "code_health failed"), 0, 0));
-    return container;
-  }
+  const executionError = renderExecutionError(context, "code_health failed", theme);
+  if (executionError) return executionError;
+  const domainError = renderDomainError(result, theme);
+  if (domainError) return renderDomainResult(result, options, theme, domainError);
 
   if (!options.expanded) {
-    container.addChild(buildCompactSummary(data, theme));
-    return container;
+    const compact = buildCompactSummary(data, theme);
+    const truncation = renderTruncationDisclosure(result, theme);
+    if (!truncation) return compact;
+    const compactContainer = new Container();
+    compactContainer.addChild(compact);
+    compactContainer.addChild(new Spacer(1));
+    compactContainer.addChild(truncation);
+    return compactContainer;
   }
 
-  // Expanded view
+  const container = new Container();
   container.addChild(buildStatusBar(data, theme));
   const capabilityWarnings = readCapabilityWarnings(data);
   if (capabilityWarnings.length > 0) {
@@ -72,8 +84,7 @@ export function renderHealthResult(
   }
   container.addChild(new Spacer(1));
   container.addChild(buildDiagnosticSummary(data, theme));
-  const diagnosticEntries = buildDiagnosticEntries(data, theme);
-  if (diagnosticEntries) container.addChild(diagnosticEntries);
+  renderToolDisplaySections(container, result.details?.displaySections, theme);
   container.addChild(buildHealthSectionSummary(data, theme));
 
   const lists = data?.evidenceLists as EvidenceEntry[] | undefined;
@@ -82,6 +93,11 @@ export function renderHealthResult(
     renderEvidenceLines(container, lists, theme);
   }
 
+  const truncation = renderTruncationDisclosure(result, theme);
+  if (truncation) {
+    container.addChild(new Spacer(1));
+    container.addChild(truncation);
+  }
   renderMarkdownDetail(container, result, theme);
 
   return container;
@@ -105,12 +121,22 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
   const semanticRequested = sections.some(
     (section) => section.key === "diagnostics" || section.key === "servers",
   );
-  const segments = sections.map((section) => formatSectionSummary(section, undefined, theme));
+  const segments = sections.map((section) =>
+    formatSectionSummary(
+      section,
+      section.key === "diagnostics"
+        ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data))
+        : null,
+      theme,
+    ),
+  );
   if (semanticRequested) {
     const semanticStatus = readSemanticStatus(data);
     const statusColor = semanticStatus.startsWith("ready") ? "success" : "warning";
     segments.push(`${theme.fg("dim", "lsp")} ${theme.fg(statusColor, semanticStatus)}`);
   }
+  const previousRefresh = readPreviousRefreshStatus(data);
+  if (previousRefresh) segments.push(theme.fg("dim", previousRefresh));
   const capabilityWarningCount = readCapabilityWarnings(data).length;
   if (capabilityWarningCount > 0) {
     const label = capabilityWarningCount === 1 ? "capability warning" : "capability warnings";
@@ -123,20 +149,20 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
 
 function formatSectionSummary(
   section: HealthSectionSummary,
-  evidence: EvidenceEntry | undefined,
+  coverage: string | null,
   theme: Theme,
 ): string {
   const label = sectionLabel(section.key);
+  const coverageSuffix = coverage ? ` (${coverage})` : "";
   if (section.status === "unavailable" || !section.available) {
-    return `${theme.fg("dim", label)} ${theme.fg("warning", "unavailable")}`;
+    return `${theme.fg("dim", label)} ${theme.fg("warning", "unavailable")}${coverageSuffix}`;
   }
   if (section.status === "partial") {
-    return `${theme.fg("dim", label)} ${theme.fg("warning", "partial")}`;
+    return `${theme.fg("dim", label)} ${theme.fg("warning", "partial")}${coverageSuffix}`;
   }
-  if (evidence) return theme.fg("success", theme.bold(formatEvidenceEntry(evidence)));
 
-  const suffix = section.key === "diagnostics" ? " with issues" : "";
-  return `${theme.fg("dim", label)} ${theme.fg("success", theme.bold(`${section.itemCount}`))}${theme.fg("muted", suffix)}`;
+  const suffix = section.key === "diagnostics" && !coverage ? " with issues" : "";
+  return `${theme.fg("dim", label)} ${theme.fg("success", theme.bold(`${section.itemCount}`))}${theme.fg("muted", suffix)}${coverageSuffix}`;
 }
 
 function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Text {
@@ -162,32 +188,6 @@ function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Tex
   return new Text(lines.join("  "), 0, 0);
 }
 
-function readRefreshStatus(data: Record<string, unknown> | null): string | null {
-  const refresh = readRecord(data?.refresh);
-  if (!refresh) return null;
-
-  switch (refresh.kind) {
-    case "completed": {
-      const attempted = readNumber(refresh.attemptedActiveClients);
-      const restarted = readNumber(refresh.restartedClients);
-      const stale = readRecord(refresh.staleAssessment);
-      const noOp = attempted === 0 && restarted === 0;
-      const base = noOp
-        ? "refresh completed no-op"
-        : `refresh completed: ${attempted} clients targeted, ${restarted} restarted`;
-      return stale?.suspected === true
-        ? `${base}; stale pattern suspected in ${readNumber(stale.matchedFileCount)} files`
-        : base;
-    }
-    case "failed":
-      return `refresh failed${typeof refresh.reason === "string" ? `: ${refresh.reason}` : ""}`;
-    case "not-attempted":
-      return "refresh not attempted";
-    default:
-      return null;
-  }
-}
-
 function diagnosticEmptySummary(data: Record<string, unknown> | null): string {
   return diagnosticScopeKind(data) === "file"
     ? "No errors or warnings for file"
@@ -200,12 +200,44 @@ function diagnosticScopeKind(data: Record<string, unknown> | null): string | nul
   return typeof scope?.kind === "string" ? scope.kind : null;
 }
 
-function readRecord(value: unknown): Record<string, unknown> | null {
-  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+function readDiagnosticEvidence(
+  data: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+  return readRecord(readRecord(data?.diagnosticObservation)?.evidence);
 }
 
-function readNumber(value: unknown): number {
-  return typeof value === "number" ? value : 0;
+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;
 }
 
 interface RenderedCapabilityWarning {
@@ -268,14 +300,9 @@ function buildDiagnosticSummary(data: Record<string, unknown> | null, theme: The
   }
   const trackedFiles = diagnosticScopeKind(data) === "tracked-files";
   if (section.status === "partial") {
-    return new Text(
-      theme.fg(
-        "warning",
-        trackedFiles ? "Tracked-file diagnostics partial" : "Diagnostics partial",
-      ),
-      0,
-      0,
-    );
+    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);
   }
   if (section.itemCount === 0) {
     return new Text(theme.fg("success", diagnosticEmptySummary(data)), 0, 0);
@@ -289,36 +316,6 @@ function buildDiagnosticSummary(data: Record<string, unknown> | null, theme: The
   );
 }
 
-/** Render per-file diagnostic messages in expanded detailed mode. */
-function buildDiagnosticEntries(data: Record<string, unknown> | null, theme: Theme): Text | null {
-  const observation = readRecord(data?.diagnosticObservation);
-  const entries = observation?.entries;
-  if (!Array.isArray(entries) || entries.length === 0) return null;
-
-  const lines: string[] = [];
-  for (const raw of entries) {
-    const entry = readRecord(raw);
-    if (!entry || !Array.isArray(entry.messages) || entry.messages.length === 0) continue;
-    lines.push(theme.fg("dim", `  ${typeof entry.file === "string" ? entry.file : ""}`));
-    for (const rawMsg of entry.messages) {
-      const formatted = formatDiagnosticMessage(readRecord(rawMsg), theme);
-      if (formatted) lines.push(formatted);
-    }
-  }
-
-  return lines.length > 0 ? new Text(lines.join("\n"), 0, 0) : null;
-}
-
-function formatDiagnosticMessage(msg: Record<string, unknown> | null, theme: Theme): string | null {
-  if (!msg || typeof msg.message !== "string") return null;
-  const line = typeof msg.line === "number" ? `L${msg.line} ` : "";
-  const isError = msg.severity === "error";
-  const color = isError ? "error" : "warning";
-  const icon = isError ? "✖" : "⚠";
-  const source = typeof msg.source === "string" ? ` [${msg.source}]` : "";
-  return `    ${theme.fg(color, `${icon} ${line}${msg.severity}${source}`)}: ${msg.message}`;
-}
-
 function readHealthSections(data: Record<string, unknown> | null): HealthSectionSummary[] {
   const value = data?.sections;
   if (!Array.isArray(value)) return [];

package/src/tool/{inspect → code_inspect}/execute.ts

@@ -4,9 +4,7 @@ import type { InspectWorkflowInput } from "../../session/inspect-types.ts";
 import type { SourcePointInput } from "../../session/target-input.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
-import { inspectErrorResult } from "../result/errors.ts";
-import { assembleInspectResult } from "../result/inspect.ts";
-import { renderInspectResult } from "./markdown.ts";
+import { finishInspectResult } from "./result.ts";
 
 export interface CodeInspectToolParams {
   point: SourcePointInput;
@@ -18,17 +16,5 @@ export async function executeInspectTool(
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
   const outcome = await ctx.session.inspect(params as InspectWorkflowInput, toWorkflowControl(ctx));
-  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
-  if (outcome.kind === "invalid-input") {
-    return inspectErrorResult(`**Error:** ${outcome.message}`, {
-      focusTarget: "invalid input",
-      nextQueries: ["Provide an existing file and exact 1-based point"],
-    });
-  }
-
-  const assembly = assembleInspectResult(outcome.data, outcome.nextQueries);
-  return {
-    content: renderInspectResult(assembly),
-    details: { type: "inspect", data: assembly.details },
-  };
+  return finishInspectResult(outcome);
 }

package/src/tool/code_inspect/guidance.ts

@@ -0,0 +1,6 @@
+export const toolDescription =
+  "Inspect one exact point for syntax, the narrowest enclosing declaration, hover, definition, and nearby diagnostics. Use for point facts, not broad Orientation.";
+
+export const promptSnippet = "factual point inspection";
+
+export const promptGuidelines: string[] = [];

package/src/tool/{inspect → code_inspect}/markdown.ts

@@ -1,6 +1,6 @@
 import { renderEvidenceListDisclosure } from "../../analysis/evidence.ts";
 import type { InspectObservation } from "../../session/inspect-types.ts";
-import type { InspectResultAssembly } from "../result/inspect.ts";
+import type { InspectResultAssembly } from "./result.ts";
 
 export function renderInspectResult(assembly: InspectResultAssembly): string {
   const input = assembly.data;

package/src/tool/{result/inspect.ts → code_inspect/result.ts}

@@ -16,8 +16,9 @@ import {
   type ResultProvenance,
   type ResultSection,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import type { InspectDetails, InspectSectionDetails } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection, truncateDisplayText } from "../result/display.ts";
+import type { InspectDetails, InspectSectionDetails, ToolDisplaySection } from "../result/types.ts";
 
 export type { InspectResultData } from "../../session/inspect-types.ts";
 
@@ -30,6 +31,7 @@ export interface InspectResultAssembly {
   diagnosticEvidence: EvidenceList<InspectDiagnostic> | null;
   assembled: ToolResultAssembly<InspectResultData>;
   details: InspectDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 /** Assemble code_inspect evidence/details before presentation adapters render it. */
@@ -62,6 +64,14 @@ export function assembleInspectResult(
     provenance,
   });
 
+  const displaySections = buildInspectDisplaySections({
+    data,
+    displayedDefinitions: definitionEvidence?.items ?? [],
+    displayedDiagnostics: diagnosticEvidence?.items ?? [],
+    definitionEvidence,
+    diagnosticEvidence,
+  });
+
   return {
     data,
     displayedDefinitions: definitionEvidence?.items ?? [],
@@ -69,6 +79,7 @@ export function assembleInspectResult(
     definitionEvidence,
     diagnosticEvidence,
     assembled,
+    displaySections,
     details: {
       confidence: data.confidence,
       focusTarget: `${data.relPath}:${data.line}:${data.character}`,
@@ -80,6 +91,107 @@ export function assembleInspectResult(
   };
 }
 
+function buildInspectDisplaySections(input: {
+  data: InspectResultData;
+  displayedDefinitions: readonly InspectDefinition[];
+  displayedDiagnostics: readonly InspectDiagnostic[];
+  definitionEvidence: EvidenceList<InspectDefinition> | null;
+  diagnosticEvidence: EvidenceList<InspectDiagnostic> | null;
+}): ToolDisplaySection[] {
+  const sections: ToolDisplaySection[] = [];
+  const { data } = input;
+
+  if (data.sections.node.kind !== "unavailable" && data.sections.node.data) {
+    const node = data.sections.node.data;
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.node",
+        title: "Syntax node",
+        items: [node],
+        format: (item) =>
+          `${item.type} at ${data.relPath}:${item.startLine}:${item.startCharacter}–${item.endLine}:${item.endCharacter}${item.text ? ` — ${truncateDisplayText(item.text, 160)}` : ""}`,
+        partialReason: observationReason(data.sections.node),
+      }),
+    );
+  }
+
+  if (data.sections.enclosingSymbol.kind !== "unavailable" && data.sections.enclosingSymbol.data) {
+    const symbol = data.sections.enclosingSymbol.data;
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.enclosingSymbol",
+        title: "Enclosing symbol",
+        items: [symbol],
+        format: (item) =>
+          `${item.name} (${item.kind}) L${item.startLine}:${item.startCharacter}–L${item.endLine}:${item.endCharacter}`,
+        partialReason: observationReason(data.sections.enclosingSymbol),
+      }),
+    );
+  }
+
+  if (data.sections.hover.kind !== "unavailable" && data.sections.hover.data) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.hover",
+        title: "Hover",
+        items: [data.sections.hover.data],
+        format: (hover) => truncateDisplayText(hover, 240),
+        partialReason: observationReason(data.sections.hover),
+      }),
+    );
+  }
+
+  if (input.displayedDefinitions.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.definitions",
+        title: "Definitions",
+        items: input.displayedDefinitions,
+        totalCount: input.definitionEvidence?.metadata.totalCount,
+        omittedCount: input.definitionEvidence?.metadata.omittedCount,
+        partialReason: input.definitionEvidence?.metadata.partialReason,
+        format: (definition) => `${definition.file}:${definition.line}:${definition.character}`,
+      }),
+    );
+  }
+
+  if (input.displayedDiagnostics.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "inspect.diagnostics",
+        title: "Diagnostics",
+        items: input.displayedDiagnostics,
+        totalCount: input.diagnosticEvidence?.metadata.totalCount,
+        omittedCount: input.diagnosticEvidence?.metadata.omittedCount,
+        partialReason: input.diagnosticEvidence?.metadata.partialReason,
+        format: (diagnostic) =>
+          `L${diagnostic.line}:${diagnostic.character} ${formatDiagnosticSeverity(diagnostic.severity)}: ${truncateDisplayText(diagnostic.message, 200)}`,
+      }),
+    );
+  }
+
+  return sections;
+}
+
+function observationReason<T>(observation: InspectObservation<T>): string | null {
+  return observation.kind === "partial" ? observation.reason : null;
+}
+
+function formatDiagnosticSeverity(severity: number): string {
+  switch (severity) {
+    case 1:
+      return "Error";
+    case 2:
+      return "Warning";
+    case 3:
+      return "Info";
+    case 4:
+      return "Hint";
+    default:
+      return "Diagnostic";
+  }
+}
+
 function listEvidence<T>(
   key: string,
   observation: InspectObservation<readonly T[]>,
@@ -200,3 +312,32 @@ function overallProvenance(data: InspectResultData): ResultProvenance[] {
     ...(structural ? [{ source: "structural" as const, capability: "tree-sitter" }] : []),
   ];
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { inspectErrorResult } from "../result/errors.ts";
+import { renderInspectResult } from "./markdown.ts";
+
+type InspectOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["inspect"]>>;
+
+/** Assemble the final model-visible code_inspect result for one workflow outcome. */
+export function finishInspectResult(outcome: InspectOutcome): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return inspectErrorResult(`**Error:** ${outcome.message}`, {
+      focusTarget: "invalid input",
+      nextQueries: ["Provide an existing file and exact 1-based point"],
+      message: outcome.message,
+    });
+  }
+
+  const assembly = assembleInspectResult(outcome.data, outcome.nextQueries);
+  return {
+    content: renderInspectResult(assembly),
+    details: {
+      type: "inspect",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}

package/src/tool/code_inspect/spec.ts

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { MaxResultsParam, SourcePointParam } from "../schemas.ts";
+import { executeInspectTool } from "./execute.ts";
+import { renderInspectCall, renderInspectResult } from "./tui.ts";
+
+export const CODE_INSPECT_TOOL_NAME = "code_inspect";
+export const CODE_INSPECT_TOOL_LABEL = "Code Inspect";
+
+/** Canonical provider-facing metadata for the code_inspect tool. */
+export const codeInspectSpec = {
+  name: CODE_INSPECT_TOOL_NAME,
+  label: CODE_INSPECT_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      point: SourcePointParam,
+      maxResults: Type.Optional(MaxResultsParam),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeInspectTool(params as Parameters<typeof executeInspectTool>[0], ctx),
+  renderCall: renderInspectCall,
+  renderResult: renderInspectResult,
+} as const;

package/src/tool/code_inspect/tui.ts

@@ -0,0 +1,44 @@
+/** TUI renderer for code_inspect. */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  formatCallPath,
+  type ResultOptios,
+  renderSimpleResult,
+  type ToolRendererContext,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
+
+/** Render the compact code_inspect call header. */
+export function renderInspectCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as {
+    point?: { file?: unknown; line?: unknown; character?: unknown };
+  };
+
+  let content = theme.fg("toolTitle", "code_inspect");
+  const point = params.point;
+  if (point && typeof point === "object") {
+    const file = formatCallPath(point.file);
+    if (file) content += ` ${theme.fg("accent", file)}`;
+    if (typeof point.line === "number") content += theme.fg("warning", `:${point.line}`);
+    if (typeof point.character === "number") {
+      content += theme.fg("dim", `:${point.character}`);
+    }
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** Render code_inspect progress, status, and structured result details. */
+export function renderInspectResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  context: ToolRendererContext | undefined,
+): ReturnType<typeof renderSimpleResult> {
+  return renderSimpleResult(result, options, theme, "Inspecting…", context);
+}

package/src/tool/code_orientation/execute.ts

@@ -0,0 +1,25 @@
+/** Thin Pi adapter for the session-owned Orientation workflow. */
+
+import type {
+  OrientationFocusInput,
+  OrientationWorkflowInput,
+} from "../../session/orientation-types.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { finishOrientationResult } from "./result.ts";
+
+export interface CodeOrientationToolParams {
+  focus?: OrientationFocusInput;
+  maxResults?: number;
+}
+
+export async function executeOrientationTool(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.orient(
+    params as OrientationWorkflowInput,
+    toWorkflowControl(ctx),
+  );
+  return finishOrientationResult(outcome);
+}

package/src/tool/code_orientation/guidance.ts

@@ -0,0 +1,9 @@
+export const toolDescription =
+  "Orient around the workspace or one path, module, or target focus before surgical work. Omit focus for workspace Orientation. Workspace Orientation includes manifest and dependency inventories. For one-file work, use focused path Orientation. Directory focus may surface local instruction files.";
+
+export const promptSnippet = "workspace/path/module/symbol Orientation";
+
+export const promptGuidelines = [
+  "Use code_orientation before broad file reading when you need direct workspace, package, directory, file, or symbol facts.",
+  "Use code_graph for relationships and code_health for provider or diagnostic state.",
+];

package/src/tool/{orientation → code_orientation}/markdown.ts

@@ -6,7 +6,7 @@ import type {
   OrientationSectionData,
 } from "../../session/orientation-types.ts";
 import { assembledReadNext } from "../result/assembly.ts";
-import type { OrientationResultAssembly } from "../result/orientation.ts";
+import type { OrientationResultAssembly } from "./result.ts";
 
 /**
  * Sole model-facing markdown adapter for Orientation.