@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.0

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

@@ -14,9 +14,13 @@ import {
   assembleToolResult,
   type ResultSection,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import { createToolDisplaySection } from "./display.ts";
-import type { ContextDetails, OrientationSectionDetails, ToolDisplaySection } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection } from "../result/display.ts";
+import type {
+  ContextDetails,
+  OrientationSectionDetails,
+  ToolDisplaySection,
+} from "../result/types.ts";
 
 export interface OrientationDetailsInput {
   readonly confidence: ConfidenceMode;
@@ -182,3 +186,63 @@ function uniqueProvenance(sections: readonly OrientationSectionData[]) {
     }),
   );
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { contextErrorResult } from "../result/errors.ts";
+import { renderOrientationResult } from "./markdown.ts";
+
+type OrientationOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["orient"]>>;
+
+/** Assemble the final model-visible code_orientation result for one workflow outcome. */
+export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return contextErrorResult(`**Error:** ${outcome.message}`, {
+      nextQueries: ["Choose an existing path, module, or precise target"],
+      message: outcome.message,
+    });
+  }
+  if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
+    const candidates = outcome.candidates ?? [];
+    const lines = [
+      outcome.kind === "kind-mismatch"
+        ? `# No Orientation target matched provider kind \`${outcome.requestedKind}\``
+        : "# Multiple Orientation targets",
+      "",
+    ];
+    for (const candidate of candidates) {
+      lines.push(
+        `${candidate.rank}. **${candidate.name}** (\`${candidate.kind ?? "unknown"}\`) — \`${candidate.file}\`:${candidate.line}:${candidate.character} — \`${candidate.targetId}\``,
+      );
+    }
+    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,
+      candidates,
+      nextQueries,
+    });
+    return {
+      content: lines.join("\n"),
+      details: {
+        type: "context",
+        data: details,
+        status: "completed",
+        displaySections: orientationCandidateDisplaySections(candidates, outcome.omittedCount),
+      },
+    };
+  }
+  const assembly = assembleOrientationResult(outcome.data);
+  return {
+    content: renderOrientationResult(assembly),
+    details: {
+      type: "context",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}

package/src/tool/code_orientation/spec.ts

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { MaxResultsParam, OrientationFocusParam } from "../schemas.ts";
+import { executeOrientationTool } from "./execute.ts";
+import { renderOrientationCall, renderOrientationResult } from "./tui.ts";
+
+export const CODE_ORIENTATION_TOOL_NAME = "code_orientation";
+export const CODE_ORIENTATION_TOOL_LABEL = "Code Orientation";
+
+/** Canonical provider-facing metadata for the code_orientation tool. */
+export const codeOrientationSpec = {
+  name: CODE_ORIENTATION_TOOL_NAME,
+  label: CODE_ORIENTATION_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      focus: Type.Optional(OrientationFocusParam),
+      maxResults: Type.Optional(MaxResultsParam),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeOrientationTool(params as Parameters<typeof executeOrientationTool>[0], ctx),
+  renderCall: renderOrientationCall,
+  renderResult: renderOrientationResult,
+} as const;

package/src/tool/code_refactor_apply/execute.ts

@@ -0,0 +1,17 @@
+/** Thin Pi adapter for session-owned refactor application. */
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { finishRefactorApplyResult } from "./result.ts";
+
+export interface CodeRefactorApplyToolParams {
+  planId: string;
+}
+
+export async function executeRefactorApplyTool(
+  params: CodeRefactorApplyToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.applyRefactor(params, toWorkflowControl(ctx));
+  return finishRefactorApplyResult(outcome);
+}

package/src/tool/code_refactor_apply/guidance.ts

@@ -0,0 +1,5 @@
+export const toolDescription = "Apply one stored refactor plan by planId.";
+
+export const promptSnippet = "apply a fresh stored refactor plan";
+
+export const promptGuidelines: string[] = [];

package/src/tool/{refactor-apply/execute.ts → code_refactor_apply/result.ts}

@@ -1,20 +1,14 @@
-/** Thin Pi adapter for session-owned refactor application. */
+/** Result assembly for code_refactor_apply. */
 
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
-import { toWorkflowControl } from "../infra/workflow-control.ts";
-import { renderRefactorApplyResult } from "../refactor-plan/markdown.ts";
+import { renderRefactorApplyResult } from "../refactor-markdown.ts";
 import { searchErrorResult } from "../result/errors.ts";
 import { assembleRefactorApplyDetails } from "../result/refactor.ts";
 
-export interface CodeRefactorApplyToolParams {
-  planId: string;
-}
+type RefactorApplyOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["applyRefactor"]>>;
 
-export async function executeRefactorApplyTool(
-  params: CodeRefactorApplyToolParams,
-  ctx: CodeIntelToolExecCtx,
-): Promise<CodeIntelResult> {
-  const outcome = await ctx.session.applyRefactor(params, toWorkflowControl(ctx));
+/** Assemble the final model-visible code_refactor_apply result for one workflow outcome. */
+export function finishRefactorApplyResult(outcome: RefactorApplyOutcome): CodeIntelResult {
   if (outcome.kind === "unavailable") throw new Error(outcome.reason);
   if (outcome.kind === "invalid-input") {
     return searchErrorResult(`**Error:** ${outcome.message}`, {

package/src/tool/code_refactor_apply/spec.ts

@@ -0,0 +1,26 @@
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { executeRefactorApplyTool } from "./execute.ts";
+import { renderRefactorApplyCall, renderRefactorApplyResult } from "./tui.ts";
+
+export const CODE_REFACTOR_APPLY_TOOL_NAME = "code_refactor_apply";
+export const CODE_REFACTOR_APPLY_TOOL_LABEL = "Code Refactor Apply";
+
+/** Canonical provider-facing metadata for the code_refactor_apply tool. */
+export const codeRefactorApplySpec = {
+  name: CODE_REFACTOR_APPLY_TOOL_NAME,
+  label: CODE_REFACTOR_APPLY_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      planId: Type.String({
+        description: "planId returned by code_refactor_plan.",
+        minLength: 1,
+      }),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeRefactorApplyTool(params as Parameters<typeof executeRefactorApplyTool>[0], ctx),
+  renderCall: renderRefactorApplyCall,
+  renderResult: renderRefactorApplyResult,
+} as const;

package/src/tool/code_refactor_plan/execute.ts

@@ -0,0 +1,27 @@
+/** Thin Pi adapter for session-owned refactor planning. */
+
+import type {
+  RefactorOperationInput,
+  RefactorPlanWorkflowInput,
+} from "../../session/refactor-types.ts";
+import type { RefactorTargetInput } from "../../session/target-input.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { finishRefactorPlanResult } from "./result.ts";
+
+export interface CodeRefactorPlanToolParams {
+  target: RefactorTargetInput;
+  operation: RefactorOperationInput;
+}
+
+export async function executeRefactorPlanTool(
+  params: CodeRefactorPlanToolParams,
+  ctx: CodeIntelToolExecCtx,
+  _invokedAs: "code_refactor_plan" = "code_refactor_plan",
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.planRefactor(
+    params as RefactorPlanWorkflowInput,
+    toWorkflowControl(ctx),
+  );
+  return finishRefactorPlanResult(outcome, ctx.cwd);
+}

package/src/tool/code_refactor_plan/guidance.ts

@@ -0,0 +1,8 @@
+export const toolDescription =
+  "Preview one semantic rename or extraction and return a planId without mutating files.";
+
+export const promptSnippet = "preview a precise semantic refactor";
+
+export const promptGuidelines = [
+  "Use code_refactor_plan for preview only, then call code_refactor_apply with its planId.",
+];

package/src/tool/{refactor-plan/execute.ts → code_refactor_plan/result.ts}

@@ -1,30 +1,17 @@
-/** Thin Pi adapter for session-owned refactor planning. */
+/** Result assembly for code_refactor_plan. */
 
-import type {
-  RefactorOperationInput,
-  RefactorPlanWorkflowInput,
-} from "../../session/refactor-types.ts";
-import type { RefactorTargetInput } from "../../session/target-input.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
-import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { renderRefactorPlanResult } from "../refactor-markdown.ts";
 import { searchErrorResult } from "../result/errors.ts";
 import { assembleRefactorPlanDetails } from "../result/refactor.ts";
-import { renderRefactorPlanResult } from "./markdown.ts";
 
-export interface CodeRefactorPlanToolParams {
-  target: RefactorTargetInput;
-  operation: RefactorOperationInput;
-}
+type RefactorPlanOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["planRefactor"]>>;
 
-export async function executeRefactorPlanTool(
-  params: CodeRefactorPlanToolParams,
-  ctx: CodeIntelToolExecCtx,
-  _invokedAs: "code_refactor_plan" = "code_refactor_plan",
-): Promise<CodeIntelResult> {
-  const outcome = await ctx.session.planRefactor(
-    params as RefactorPlanWorkflowInput,
-    toWorkflowControl(ctx),
-  );
+/** Assemble the final model-visible code_refactor_plan result for one workflow outcome. */
+export function finishRefactorPlanResult(
+  outcome: RefactorPlanOutcome,
+  cwd: string,
+): CodeIntelResult {
   if (outcome.kind === "unavailable") throw new Error(outcome.reason);
   if (outcome.kind === "invalid-input") {
     return searchErrorResult(`**Error:** ${outcome.message}`, {
@@ -45,7 +32,7 @@ export async function executeRefactorPlanTool(
     });
   }
 
-  const assembly = assembleRefactorPlanDetails(outcome.plan, ctx.cwd);
+  const assembly = assembleRefactorPlanDetails(outcome.plan, cwd);
   return {
     content: renderRefactorPlanResult(assembly),
     details: {

package/src/tool/code_refactor_plan/spec.ts

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { RefactorOperationParam, RefactorTargetParam } from "../schemas.ts";
+import { executeRefactorPlanTool } from "./execute.ts";
+import { renderRefactorPlanCall, renderRefactorPlanResult } from "./tui.ts";
+
+export const CODE_REFACTOR_PLAN_TOOL_NAME = "code_refactor_plan";
+export const CODE_REFACTOR_PLAN_TOOL_LABEL = "Code Refactor Plan";
+
+/** Canonical provider-facing metadata for the code_refactor_plan tool. */
+export const codeRefactorPlanSpec = {
+  name: CODE_REFACTOR_PLAN_TOOL_NAME,
+  label: CODE_REFACTOR_PLAN_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      target: RefactorTargetParam,
+      operation: RefactorOperationParam,
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeRefactorPlanTool(params as Parameters<typeof executeRefactorPlanTool>[0], ctx),
+  renderCall: renderRefactorPlanCall,
+  renderResult: renderRefactorPlanResult,
+} as const;

package/src/tool/code_resolve/execute.ts

@@ -0,0 +1,19 @@
+/** Thin Pi adapter for code_resolve. */
+
+import type { ResolveTargetInput } from "../../session/target-input.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { finishResolveResult } from "./result.ts";
+
+export interface CodeResolveToolParams {
+  target: ResolveTargetInput;
+  maxResults?: number;
+}
+
+export async function executeResolveTool(
+  params: CodeResolveToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  const outcome = await ctx.session.resolve(params, toWorkflowControl(ctx));
+  return finishResolveResult(outcome, ctx.cwd);
+}

package/src/tool/code_resolve/guidance.ts

@@ -0,0 +1,8 @@
+export const toolDescription =
+  "Resolve one provider-backed anchor or semantic symbol query to session handles, or enumerate a file's declarations as a bounded Target group. Anchors must identify real symbols";
+
+export const promptSnippet = "resolve a precise target or enumerate a file’s target group";
+
+export const promptGuidelines = [
+  "Use code_resolve when a symbol query may be ambiguous, when later calls should share a stable target handle, or when a known file’s declarations should be enumerated.",
+];

package/src/tool/{resolve → code_resolve}/markdown.ts

@@ -3,8 +3,8 @@
 import { relative } from "node:path";
 import { renderEvidenceListMetadataDisclosure } from "../../analysis/evidence.ts";
 import type { TargetStoreEntry } from "../../session/target-store.ts";
-import type { ResolveResultAssembly } from "../result/resolve.ts";
 import type { ResolveDetails } from "../result/types.ts";
+import type { ResolveResultAssembly } from "./result.ts";
 
 /** Render an assembled resolve result into markdown. */
 export function renderResolveResult(assembly: ResolveResultAssembly): string {

package/src/tool/{result/resolve.ts → code_resolve/result.ts}

@@ -9,9 +9,9 @@ import {
   assembleToolResult,
   type ResultProvenance,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import { createToolDisplaySection } from "./display.ts";
-import type { ResolveDetails, ToolDisplaySection } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection } from "../result/display.ts";
+import type { ResolveDetails, ToolDisplaySection } from "../result/types.ts";
 
 /** Presentation-neutral assembled code_resolve result. */
 export interface ResolveResultAssembly {
@@ -105,7 +105,7 @@ function projectResolved(target: Readonly<TargetStoreEntry>, cwd: string): Resol
       omittedCount: 0,
       evidenceLists: [evidence],
       targets: [toTargetDetails(target, cwd)],
-      nextQueries: buildResolveNextQueries(target.targetId, target.kind),
+      nextQueries: [],
     },
   };
 }
@@ -289,26 +289,39 @@ function resolveProvenance(outcome: TargetWorkflowOutcome): ResultProvenance[] {
   ];
 }
 
-/** Suggested surviving graph relations for a resolved symbol kind. */
-export function suggestedResolveRelations(kind: string | undefined | null): string[] {
-  switch (kind?.toLowerCase()) {
-    case "function":
-    case "method":
-    case "constructor":
-      return ["references", "callees"];
-    case "class":
-    case "interface":
-    case "type":
-    case "enum":
-      return ["references", "implements"];
-    default:
-      return ["references"];
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { renderResolveResult } from "./markdown.ts";
+
+type ResolveOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["resolve"]>>;
+
+/** Assemble the final model-visible code_resolve result for one workflow outcome. */
+export function finishResolveResult(outcome: ResolveOutcome, cwd: string): CodeIntelResult {
+  if (outcome.kind === "unavailable") {
+    throw new Error(outcome.reason);
   }
-}
 
-function buildResolveNextQueries(targetId: string, kind: string | null): string[] {
-  const relations = suggestedResolveRelations(kind);
-  return [
-    `Use code_graph with target.handle "${targetId}" and relations ${JSON.stringify(relations)}`,
-  ];
+  const assembly = assembleResolveResult(outcome, cwd);
+  const content = renderResolveResult(assembly);
+
+  return {
+    content,
+    details: {
+      type: "resolve",
+      data: assembly.details,
+      status:
+        outcome.kind === "resolved" || outcome.kind === "target-group"
+          ? "completed"
+          : outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch"
+            ? "disambiguation"
+            : "invalid-input",
+      ...(outcome.kind === "invalid-input"
+        ? { message: outcome.message }
+        : outcome.kind === "disambiguation"
+          ? { message: "Multiple target matches require one candidate." }
+          : outcome.kind === "kind-mismatch"
+            ? { message: `No target matched provider kind ${outcome.requestedKind}.` }
+            : {}),
+      displaySections: assembly.displaySections,
+    },
+  };
 }

package/src/tool/code_resolve/spec.ts

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { MaxResultsParam, ResolveTargetParam } from "../schemas.ts";
+import { executeResolveTool } from "./execute.ts";
+import { renderResolveCall, renderResolveResult } from "./tui.ts";
+
+export const CODE_RESOLVE_TOOL_NAME = "code_resolve";
+export const CODE_RESOLVE_TOOL_LABEL = "Code Resolve";
+
+/** Canonical provider-facing metadata for the code_resolve tool. */
+export const codeResolveSpec = {
+  name: CODE_RESOLVE_TOOL_NAME,
+  label: CODE_RESOLVE_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      target: ResolveTargetParam,
+      maxResults: Type.Optional(MaxResultsParam),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeResolveTool(params as Parameters<typeof executeResolveTool>[0], ctx),
+  renderCall: renderResolveCall,
+  renderResult: renderResolveResult,
+} as const;

package/src/tool/guidance.ts

@@ -1,12 +1,52 @@
-// Model-facing descriptions and concise sibling-selection guidance.
+// Model-facing prompt surfaces for the eight public code-intelligence tools.
+//
+// Ownership map (docs/pi/tool-guidance.md): each model-facing fact lives in
+// exactly one home — the per-tool guidance module. This aggregator assembles
+// the canonical surface map consumed by registration.
+// Parameter mechanics (formats, enum semantics, cross-field rules) live in
+// schemas.ts / per-tool spec.ts and are not repeated here.
 
-import {
-  DEFAULT_AST_SCAN_MAX_FILES,
-  DEFAULT_AST_SCAN_TIMEOUT_MS,
-} from "../analysis/search/ast-scan.ts";
 import type { CodeIntelligenceToolName } from "../types/index.ts";
-
-const AST_SCAN_TIMEOUT_SECONDS = DEFAULT_AST_SCAN_TIMEOUT_MS / 1_000;
+import {
+  toolDescription as findDescription,
+  promptGuidelines as findGuidelines,
+  promptSnippet as findSnippet,
+} from "./code_find/guidance.ts";
+import {
+  toolDescription as graphDescription,
+  promptGuidelines as graphGuidelines,
+  promptSnippet as graphSnippet,
+} from "./code_graph/guidance.ts";
+import {
+  toolDescription as healthDescription,
+  promptGuidelines as healthGuidelines,
+  promptSnippet as healthSnippet,
+} from "./code_health/guidance.ts";
+import {
+  toolDescription as inspectDescription,
+  promptGuidelines as inspectGuidelines,
+  promptSnippet as inspectSnippet,
+} from "./code_inspect/guidance.ts";
+import {
+  toolDescription as orientationDescription,
+  promptGuidelines as orientationGuidelines,
+  promptSnippet as orientationSnippet,
+} from "./code_orientation/guidance.ts";
+import {
+  toolDescription as applyDescription,
+  promptGuidelines as applyGuidelines,
+  promptSnippet as applySnippet,
+} from "./code_refactor_apply/guidance.ts";
+import {
+  toolDescription as planDescription,
+  promptGuidelines as planGuidelines,
+  promptSnippet as planSnippet,
+} from "./code_refactor_plan/guidance.ts";
+import {
+  toolDescription as resolveDescription,
+  promptGuidelines as resolveGuidelines,
+  promptSnippet as resolveSnippet,
+} from "./code_resolve/guidance.ts";
 
 export interface CodeIntelligenceToolPromptSurface {
   description: string;
@@ -21,64 +61,43 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
 
 export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
   code_resolve: {
-    description:
-      "Resolve one provider-backed anchor or semantic symbol query to session handles, or enumerate a file's declarations as a bounded Target group. Requires a concrete ready LSP client; anchors must identify real symbols, and symbol lookup never falls back to text search. symbolKind is an exact provider-reported LSP kind filter. File groups keep overloads distinct and disclose omissions and provenance.",
-    promptSnippet: "code_resolve — resolve a precise target or enumerate a file’s target group",
-    promptGuidelines: [
-      "Use code_resolve when a symbol query may be ambiguous, when later calls should share a stable target handle, or when a known file’s declarations should be enumerated.",
-    ],
+    description: resolveDescription,
+    promptSnippet: resolveSnippet,
+    promptGuidelines: resolveGuidelines,
   },
   code_inspect: {
-    description:
-      "Inspect one exact point for syntax, the narrowest enclosing declaration, hover, definition, and diagnostics intersecting the nearby line window. Use for point facts, not broad Orientation. Completed-empty, partial, and unavailable sections are disclosed independently; no action is applied.",
-    promptSnippet: "code_inspect — factual point inspection",
-    promptGuidelines: [],
+    description: inspectDescription,
+    promptSnippet: inspectSnippet,
+    promptGuidelines: inspectGuidelines,
   },
   code_orientation: {
-    description:
-      "Orient around the workspace or one path, module, or target focus before surgical work. Omit focus for workspace Orientation. Directory focus may surface local instruction files. Use code_graph for relations and code_health for health.",
-    promptSnippet: "code_orientation — workspace/path/module/symbol Orientation",
-    promptGuidelines: [
-      "Use code_orientation before broad file reading when you need direct workspace, package, directory, file, or symbol facts.",
-      "Use focus.path for a known workspace path, focus.module for a discovered module name, and focus.target for a precise symbol.",
-      "Use code_graph for relationships and code_health for provider or diagnostic state.",
-    ],
+    description: orientationDescription,
+    promptSnippet: orientationSnippet,
+    promptGuidelines: orientationGuidelines,
   },
   code_graph: {
-    description:
-      'Collect references, structural callees, and implementations for one target. Defaults to references; "all" selects all three. Callees match source shape, not symbol identity; calleeDepth:"deep" includes nested scopes. Per-relation failures are disclosed; no edges are invented.',
-    promptSnippet: "code_graph — provider-backed and structural relation evidence",
-    promptGuidelines: [],
+    description: graphDescription,
+    promptSnippet: graphSnippet,
+    promptGuidelines: graphGuidelines,
   },
   code_find: {
-    description: `Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic"; AST requires kind. Use PI grep for literal/regex source search. Modes never silently fall back. Definition/type/interface/class/method/enum use outline support; import/export use their matching extractors; call uses registered call-site queries. Unscoped AST scans visible regular files supported by the selected kind's structural operation, excluding hidden entries and common generated/dependency directories without reading ignore files or following descendant symlinks. Explicit roots are honored; operation-ineligible files are disclosed, and exact ineligible scopes fail rather than widening. A ${AST_SCAN_TIMEOUT_SECONDS}-second deadline and ${DEFAULT_AST_SCAN_MAX_FILES}-file cap cover enumeration and analysis. Incomplete scans disclose limitations and unknown match totals.`,
-    promptSnippet: "code_find — explicit structural or semantic code search",
-    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.",
-    ],
+    description: findDescription,
+    promptSnippet: findSnippet,
+    promptGuidelines: findGuidelines,
   },
   code_health: {
-    description:
-      "Report live diagnostics as observations, language-server status, and final semantic health state. Use refresh:true to report a diagnostic-recovery attempt before finalizing semantic state. Tracked-file snapshots do not prove workspace completeness; server inventory is workspace-wide. Capability Warnings supplement diagnostic/server results.",
-    promptSnippet: "code_health — live workspace health observations",
-    promptGuidelines: [
-      "Use code_health with refresh:true before relying on potentially stale diagnostics.",
-    ],
+    description: healthDescription,
+    promptSnippet: healthSnippet,
+    promptGuidelines: healthGuidelines,
   },
   code_refactor_plan: {
-    description:
-      "Preview a precise semantic rename or extraction and return a planId without mutating files. Requires one handle/anchor target and one operation; unavailable precise edits never fall back to text edits. Apply separately with code_refactor_apply.",
-    promptSnippet: "code_refactor_plan — preview a precise semantic refactor",
-    promptGuidelines: [
-      "Use code_refactor_plan for preview only, then explicitly call code_refactor_apply with its planId.",
-    ],
+    description: planDescription,
+    promptSnippet: planSnippet,
+    promptGuidelines: planGuidelines,
   },
   code_refactor_apply: {
-    description:
-      "Apply one stored refactor plan by planId. Revalidates freshness, file fingerprints, ranges, and edit overlap before mutation; never composes or regenerates plans.",
-    promptSnippet: "code_refactor_apply — apply a fresh stored refactor plan",
-    promptGuidelines: [
-      "Use code_refactor_apply only with a planId returned by code_refactor_plan.",
-    ],
+    description: applyDescription,
+    promptSnippet: applySnippet,
+    promptGuidelines: applyGuidelines,
   },
 };

package/src/tool/infra/truncate.ts

@@ -47,3 +47,43 @@ export function truncateToolContent(
   const notice = `\n[truncated: kept ${result.outputLines} of ${result.totalLines} lines (${formatSize(result.outputBytes)} of ${formatSize(result.totalBytes)})]\n`;
   return { text: `${result.content}${notice}`, truncated: true };
 }
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CodeIntelResult } from "../../types/index.ts";
+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.
+ */
+export function boundCodeToolResult(
+  content: string,
+  details: CodeIntelResult["details"],
+  options: { toolName: string; maxLines?: number; maxBytes?: number },
+): { content: Array<{ type: "text"; text: string }>; details: CodeIntelResult["details"] } {
+  const withTruncation = (truncation: ToolOutputTruncationDetails) =>
+    details ? { ...details, truncation } : details;
+
+  const { text, truncated } = truncateToolContent(content, {
+    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 }),
+    };
+  }
+  return {
+    content: [{ type: "text" as const, text }],
+    details: withTruncation({ truncated: false }),
+  };
+}