@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.1

package/src/tool/code_find/spec.ts

@@ -0,0 +1,37 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { FindScopeParam, MaxResultsParam, QueryParam } from "../schemas.ts";
+import { CODE_FIND_AST_KINDS } from "./ast-kinds.ts";
+import { executeFindTool } from "./execute.ts";
+import { CODE_FIND_MODES } from "./modes.ts";
+import { renderFindCall, renderFindResult } from "./tui.ts";
+
+export const CODE_FIND_TOOL_NAME = "code_find";
+export const CODE_FIND_TOOL_LABEL = "Code Find";
+
+/** Canonical provider-facing metadata for the code_find tool. */
+export const codeFindSpec = {
+  name: CODE_FIND_TOOL_NAME,
+  label: CODE_FIND_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      query: QueryParam,
+      scope: Type.Optional(FindScopeParam),
+      mode: StringEnum(CODE_FIND_MODES, {
+        description: 'Required code-aware search mode. mode:"ast" requires `kind`.',
+      }),
+      kind: Type.Optional(
+        StringEnum(CODE_FIND_AST_KINDS, {
+          description: 'AST kind for mode:"ast".',
+        }),
+      ),
+      maxResults: Type.Optional(MaxResultsParam),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeFindTool(params as Parameters<typeof executeFindTool>[0], ctx),
+  renderCall: renderFindCall,
+  renderResult: renderFindResult,
+} as const;

package/src/tool/code_graph/execute.ts

@@ -0,0 +1,24 @@
+/** Thin Pi adapter for the session-owned code_graph workflow. */
+
+import type { GraphWorkflowInput, RequestedGraphRelation } from "../../session/graph-types.ts";
+import type { GraphTargetInput } from "../../session/target-input.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { finishGraphResult } from "./result.ts";
+
+export type GraphRelation = RequestedGraphRelation;
+
+export interface CodeGraphToolParams {
+  target: GraphTargetInput;
+  relations?: GraphRelation[];
+  calleeDepth?: "direct" | "deep";
+  maxResults?: number;
+}
+
+export async function executeGraphTool(
+  params: CodeGraphToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.graph(params as GraphWorkflowInput, toWorkflowControl(ctx));
+  return finishGraphResult(outcome, ctx.cwd);
+}

package/src/tool/code_graph/guidance.ts

@@ -0,0 +1,6 @@
+export const toolDescription =
+  "Collect references, structural callees, and implementations for one target. Callees match source shape, not symbol identity.";
+
+export const promptSnippet = "provider-backed and structural relation evidence";
+
+export const promptGuidelines: string[] = [];

package/src/tool/{graph → code_graph}/markdown.ts

@@ -17,7 +17,7 @@ import type {
   ReferenceEntry,
 } from "../../analysis/relations/types.ts";
 import { toDisplayPath } from "../../analysis/search/paths.ts";
-import type { GraphResultAssembly } from "../result/graph.ts";
+import type { GraphResultAssembly } from "./result.ts";
 
 /** Render an assembled graph result. */
 export function renderGraphResult(assembly: GraphResultAssembly): string {

package/src/tool/{result/graph.ts → code_graph/result.ts}

@@ -13,9 +13,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";
 
 export type { GraphRelationKind, GraphSection } from "../../session/graph-types.ts";
 
@@ -73,7 +73,7 @@ export function assembleGraphResult(input: {
       provenance: section.kind === "ok" ? graphProvenance([section]) : [],
     })),
     evidenceLists,
-    nextQueries: ["Use code_orientation on an exact result before editing"],
+    nextQueries: [],
     readNext: sections.flatMap((section) => (section.kind === "ok" ? section.readNext : [])),
     candidateCount,
     confidence,
@@ -233,3 +233,68 @@ function graphConfidence(sections: readonly AssembledGraphSection[]): Confidence
   );
   return hasSemantic ? "semantic" : hasStructural ? "structural" : "unavailable";
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { searchErrorResult } from "../result/errors.ts";
+import { renderGraphResult } from "./markdown.ts";
+
+type GraphOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["graph"]>>;
+
+/** Assemble the final model-visible code_graph result for one workflow outcome. */
+export function finishGraphResult(outcome: GraphOutcome, cwd: string): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return searchErrorResult(`**Error:** ${outcome.message}`, { message: outcome.message });
+  }
+  if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
+    const lines = [
+      outcome.kind === "kind-mismatch"
+        ? `**No target matched provider kind \`${outcome.requestedKind}\`. Near matches:**`
+        : "**Target is ambiguous. Choose one candidate handle:**",
+      "",
+    ];
+    for (const candidate of outcome.candidates) {
+      lines.push(
+        `- \`${candidate.targetId}\` — ${candidate.name} (\`${candidate.kind ?? "unknown"}\`) at ${candidate.file}:${candidate.line}:${candidate.character}`,
+      );
+    }
+    if (outcome.kind === "kind-mismatch") {
+      lines.push(
+        "",
+        "Retry without `symbolKind`, use an observed provider kind, or choose a handle.",
+      );
+    }
+    return searchErrorResult(lines.join("\n"), {
+      message:
+        outcome.kind === "kind-mismatch"
+          ? `No target matched provider kind ${outcome.requestedKind}.`
+          : "The target is ambiguous.",
+      displaySections: [
+        createToolDisplaySection({
+          key: "graph.candidates",
+          title: "Candidates",
+          items: outcome.candidates,
+          format: (candidate) =>
+            `${candidate.targetId} — ${candidate.name} (${candidate.kind ?? "unknown"}) at ${candidate.file}:${candidate.line}:${candidate.character}`,
+        }),
+      ],
+    });
+  }
+
+  const assembly = assembleGraphResult({
+    displayName: outcome.displayName,
+    sections: outcome.sections,
+    resolvedDisplayFile: outcome.resolvedDisplayFile,
+    maxResults: outcome.maxResults,
+    cwd,
+  });
+  return {
+    content: renderGraphResult(assembly),
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}

package/src/tool/code_graph/spec.ts

@@ -0,0 +1,39 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { GraphTargetParam, MaxResultsParam } from "../schemas.ts";
+import { executeGraphTool } from "./execute.ts";
+import { renderGraphCall, renderGraphResult } from "./tui.ts";
+
+export const CODE_GRAPH_TOOL_NAME = "code_graph";
+export const CODE_GRAPH_TOOL_LABEL = "Code Graph";
+
+/** Canonical provider-facing metadata for the code_graph tool. */
+export const codeGraphSpec = {
+  name: CODE_GRAPH_TOOL_NAME,
+  label: CODE_GRAPH_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      target: GraphTargetParam,
+      relations: Type.Optional(
+        Type.Array(StringEnum(["all", "references", "callees", "implements"]), {
+          description:
+            'Requested relations; defaults to ["references"]. "all" must be the only item.',
+          minItems: 1,
+          uniqueItems: true,
+        }),
+      ),
+      maxResults: Type.Optional(MaxResultsParam),
+      calleeDepth: Type.Optional(
+        StringEnum(["direct", "deep"], {
+          description: "direct excludes nested scopes; deep includes them.",
+        }),
+      ),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeGraphTool(params as Parameters<typeof executeGraphTool>[0], ctx),
+  renderCall: renderGraphCall,
+  renderResult: renderGraphResult,
+} as const;

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

@@ -3,9 +3,7 @@
 import type { HealthSection, HealthWorkflowInput } from "../../session/health-types.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
-import { healthErrorResult } from "../result/errors.ts";
-import { assembleHealthResult } from "../result/health.ts";
-import { renderHealthResult } from "./markdown.ts";
+import { finishHealthResult } from "./result.ts";
 
 export interface CodeHealthToolParams {
   scope?: string;
@@ -19,19 +17,5 @@ export async function executeHealthTool(
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
   const outcome = await ctx.session.health(params as HealthWorkflowInput, toWorkflowControl(ctx));
-  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
-  if (outcome.kind === "invalid-input") {
-    return healthErrorResult(`**Error:** ${outcome.message}`, outcome.message);
-  }
-
-  const assembly = assembleHealthResult(outcome.data);
-  return {
-    content: renderHealthResult(assembly, ctx.cwd),
-    details: {
-      type: "health",
-      data: assembly.details,
-      status: "completed",
-      displaySections: assembly.displaySections,
-    },
-  };
+  return finishHealthResult(outcome, ctx.cwd);
 }

package/src/tool/code_health/guidance.ts

@@ -0,0 +1,8 @@
+export const toolDescription =
+  "Report live diagnostics as observations, language-server status, and final semantic health state. Tracked-file snapshots do not prove workspace completeness; server inventory is workspace-wide.";
+
+export const promptSnippet = "live workspace health observations";
+
+export const promptGuidelines = [
+  "Use code_health with refresh:true before relying on potentially stale diagnostics.",
+];

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

@@ -8,23 +8,14 @@
 import type { CapabilityWarningReport } from "../../analysis/capability/capability-warnings.ts";
 import type {
   HealthData,
+  HealthDiagnosticObservation,
   HealthDiagnosticScope,
   HealthRefreshAttempt,
   HealthResultAssembly,
   HealthSection,
-} from "../result/health.ts";
+} from "./result.ts";
 import { formatSemanticHealthState } from "./semantic-state.ts";
 
-export type {
-  HealthData,
-  HealthDiagnosticObservation,
-  HealthDiagnosticScope,
-  HealthRefreshAttempt,
-  HealthRefreshState,
-  HealthSection,
-  SemanticHealthState,
-} from "../result/health.ts";
-
 export function renderHealthResult(result: HealthResultAssembly, cwd: string): string {
   const data = result.data;
   const lines: string[] = ["## Code Health", ""];
@@ -74,7 +65,7 @@ function renderRefreshStatus(
       return;
     case "not-requested":
       if (data.refresh.lastAttempt) {
-        renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
+        renderRetainedAttempt(lines, data.refresh.lastAttempt, cwd);
       } else {
         lines.push(
           "**Diagnostic refresh attempt**: not requested this session. Use `refresh: true` to try one.",
@@ -116,16 +107,27 @@ function staleAssessmentText(
 }
 
 function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
-  const outcome =
-    attempt.kind === "completed"
-      ? completedRefreshText(attempt)
-      : `failed — ${attempt.reason}${attempt.diagnosticEvidence ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}` : ""}`;
+  const outcome = refreshAttemptOutcome(attempt);
   const label = refreshAttemptLabel(attempt);
   lines.push(
-    `**Last ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
+    `**Previous ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
+  );
+}
+
+function renderRetainedAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
+  const label =
+    attempt.operationScope === "file-runtime" ? "File LSP maintenance" : "Diagnostic refresh";
+  lines.push(
+    `**${label}**: not requested for this call. Previous attempt ${asSentence(refreshAttemptOutcome(attempt))} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
   );
 }
 
+function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
+  return attempt.kind === "completed"
+    ? completedRefreshText(attempt)
+    : `failed — ${attempt.reason}${attempt.diagnosticEvidence ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}` : ""}`;
+}
+
 function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {
   return attempt.operationScope === "file-runtime" ? "file runtime" : "workspace runtime";
 }
@@ -170,7 +172,12 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
     lines.push("Diagnostics were not requested.");
   } else {
     lines.push(`**Evidence scope**: ${formatDiagnosticScope(observation.scope, cwd)}.`);
-    lines.push(`**Evidence coverage**: ${formatDiagnosticEvidence(observation.evidence)}.`);
+    renderFileScopeStatus(lines, observation, cwd);
+    // The evidence line is bounded by the client's tracked documents; a file
+    // created after the last refresh is pulled on the next pass. Labeling the
+    // bound prevents misreading a first-call partial as an exclusion verdict.
+    const bound = observation.scope.kind === "tracked-files" ? " (tracked-file bound)" : "";
+    lines.push(`**Evidence coverage**: ${formatDiagnosticEvidence(observation.evidence)}${bound}.`);
     lines.push("");
     renderDiagnosticObservation(lines, data, cwd);
   }
@@ -178,6 +185,49 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
   lines.push("");
 }
 
+/**
+ * Render the tsconfig coverage verdict for a single-file health request.
+ *
+ * Written in plain vocabulary (no basis terms) so a reader without tsconfig
+ * background can act on it: the sentence names the deciding config and states
+ * whether the file's errors are part of workspace diagnostics. The structured
+ * decision basis stays in the diagnostics.scope debug event.
+ */
+function renderFileScopeStatus(
+  lines: string[],
+  observation: Extract<
+    HealthDiagnosticObservation,
+    { kind: "completed" | "partial" | "unavailable" }
+  >,
+  cwd: string,
+): void {
+  if (observation.scope.kind !== "file" || !observation.scopeStatus) return;
+
+  const decision = observation.scopeStatus;
+  switch (decision.status) {
+    case "included":
+      lines.push(
+        `**Tsconfig**: covered by ${formatConfigPath(decision.configPath, cwd)} — part of workspace diagnostics.`,
+      );
+      return;
+    case "excluded":
+      lines.push(
+        `**Tsconfig**: NOT covered by ${formatConfigPath(decision.configPath, cwd)} — not part of workspace diagnostics.`,
+      );
+      return;
+    case "no-config":
+      lines.push("**Tsconfig**: no tsconfig.json or jsconfig.json found — nothing filtered.");
+      return;
+    case "out-of-tree":
+      lines.push("**Tsconfig**: outside the project root — not part of workspace diagnostics.");
+  }
+}
+
+function formatConfigPath(configPath: string | null, cwd: string): string {
+  if (!configPath) return "no config";
+  return `\`${makeRelative(cwd, configPath)}\``;
+}
+
 function formatDiagnosticEvidence(evidence: {
   requested: number;
   confirmed: number;

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

@@ -5,9 +5,9 @@ import {
   type ResultProvenance,
   type ResultSection,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import { createToolDisplaySection, truncateDisplayText } from "./display.ts";
-import type { HealthDetails, HealthSectionDetails, ToolDisplaySection } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection, truncateDisplayText } from "../result/display.ts";
+import type { HealthDetails, HealthSectionDetails, ToolDisplaySection } from "../result/types.ts";
 
 export type {
   HealthData,
@@ -21,7 +21,7 @@ export type {
   HealthStaleAssessment,
   SemanticHealthState,
 } from "../../session/health-types.ts";
-export type { HealthSectionDetails } from "./types.ts";
+export type { HealthSectionDetails } from "../result/types.ts";
 
 export interface HealthResultAssembly {
   data: HealthData;
@@ -241,3 +241,28 @@ function uniqueProvenance(provenance: readonly ResultProvenance[]): ResultProven
     return true;
   });
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { healthErrorResult } from "../result/errors.ts";
+import { renderHealthResult } from "./markdown.ts";
+
+type HealthOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["health"]>>;
+
+/** Assemble the final model-visible code_health result for one workflow outcome. */
+export function finishHealthResult(outcome: HealthOutcome, cwd: string): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return healthErrorResult(`**Error:** ${outcome.message}`, outcome.message);
+  }
+
+  const assembly = assembleHealthResult(outcome.data);
+  return {
+    content: renderHealthResult(assembly, cwd),
+    details: {
+      type: "health",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}

package/src/tool/code_health/spec.ts

@@ -0,0 +1,41 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { ScopeParam } from "../schemas.ts";
+import { executeHealthTool } from "./execute.ts";
+import { renderHealthCall, renderHealthResult } from "./tui.ts";
+
+export const CODE_HEALTH_TOOL_NAME = "code_health";
+export const CODE_HEALTH_TOOL_LABEL = "Code Health";
+
+/** Canonical provider-facing metadata for the code_health tool. */
+export const codeHealthSpec = {
+  name: CODE_HEALTH_TOOL_NAME,
+  label: CODE_HEALTH_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      scope: Type.Optional(ScopeParam),
+      refresh: Type.Optional(
+        Type.Boolean({
+          description: "Attempt diagnostic recovery before collecting; result reports the outcome.",
+        }),
+      ),
+      include: Type.Optional(
+        Type.Array(StringEnum(["diagnostics", "servers"]), {
+          description: "Requested health-signal sections.",
+          uniqueItems: true,
+        }),
+      ),
+      level: Type.Optional(
+        StringEnum(["summary", "detailed"], {
+          description: "Detail level for the health report.",
+        }),
+      ),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
+  renderCall: renderHealthCall,
+  renderResult: renderHealthResult,
+} as const;

package/src/tool/code_inspect/execute.ts

@@ -0,0 +1,20 @@
+/** Thin Pi adapter for session-owned point inspection. */
+
+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 { finishInspectResult } from "./result.ts";
+
+export interface CodeInspectToolParams {
+  point: SourcePointInput;
+  maxResults?: number;
+}
+
+export async function executeInspectTool(
+  params: CodeInspectToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.inspect(params as InspectWorkflowInput, toWorkflowControl(ctx));
+  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,9 +16,9 @@ import {
   type ResultProvenance,
   type ResultSection,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import { createToolDisplaySection, truncateDisplayText } from "./display.ts";
-import type { InspectDetails, InspectSectionDetails, ToolDisplaySection } 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";
 
@@ -312,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_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.