@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

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

@@ -1,34 +1,22 @@
-/** 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}`, {
       nextQueries: ["Fix the target or operation and retry"],
+      message: outcome.message,
     });
   }
   if (outcome.kind === "ambiguous") {
@@ -40,15 +28,18 @@ export async function executeRefactorPlanTool(
       .join("\n");
     return searchErrorResult(`**Refactor ambiguous:**\n${candidates}`, {
       nextQueries: ["Use a precise target handle or anchor"],
+      message: "The refactor target is ambiguous.",
     });
   }
 
-  const assembly = assembleRefactorPlanDetails(outcome.plan, ctx.cwd);
+  const assembly = assembleRefactorPlanDetails(outcome.plan, cwd);
   return {
     content: renderRefactorPlanResult(assembly),
     details: {
       type: "search",
       data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
     },
   };
 }

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_refactor_plan/tui.ts

@@ -0,0 +1,54 @@
+/** TUI renderer for code_refactor_plan. */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  formatCallPath,
+  formatCallValue,
+  type ResultOptios,
+  renderSimpleResult,
+  type ToolRendererContext,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
+
+/** Render the compact code_refactor_plan call header. */
+export function renderRefactorPlanCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as {
+    operation?: Record<string, { newName?: unknown } | undefined>;
+    target?: { anchor?: { file?: unknown }; handle?: unknown };
+  };
+
+  let content = theme.fg("toolTitle", "code_refactor_plan");
+  const operation = params.operation ? Object.entries(params.operation)[0] : undefined;
+  if (operation) {
+    content += ` ${theme.fg("accent", formatCallValue(operation[0], 40) ?? "operation")}`;
+    const newName =
+      operation[1] && typeof operation[1] === "object"
+        ? formatCallValue(operation[1].newName)
+        : null;
+    if (newName) content += ` ${theme.fg("muted", newName)}`;
+  }
+
+  const anchorFile = formatCallPath(params.target?.anchor?.file);
+  if (anchorFile) {
+    content += ` ${theme.fg("muted", anchorFile)}`;
+  } else {
+    const handle = formatCallValue(params.target?.handle);
+    if (handle) content += ` ${theme.fg("muted", handle)}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** Render code_refactor_plan progress, status, and structured result details. */
+export function renderRefactorPlanResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  context: ToolRendererContext | undefined,
+): ReturnType<typeof renderSimpleResult> {
+  return renderSimpleResult(result, options, theme, "Planning…", context);
+}

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,8 +9,9 @@ import {
   assembleToolResult,
   type ResultProvenance,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import type { ResolveDetails } 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 {
@@ -18,6 +19,7 @@ export interface ResolveResultAssembly {
   readonly cwd: string;
   readonly assembled: ToolResultAssembly<TargetWorkflowOutcome>;
   readonly details: ResolveDetails;
+  readonly displaySections: readonly ToolDisplaySection[];
 }
 
 interface ResolveProjection {
@@ -56,16 +58,19 @@ export function assembleResolveResult(
     provenance,
   });
 
+  const details = {
+    ...projection.details,
+    omittedCount: assembled.totals.omittedCount,
+    evidenceLists: [...assembled.evidenceLists],
+    nextQueries: assembledNextQueries(assembled),
+  };
+
   return Object.freeze({
     outcome,
     cwd,
     assembled,
-    details: {
-      ...projection.details,
-      omittedCount: assembled.totals.omittedCount,
-      evidenceLists: [...assembled.evidenceLists],
-      nextQueries: assembledNextQueries(assembled),
-    },
+    details,
+    displaySections: resolveDisplaySections(details),
   });
 }
 
@@ -100,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: [],
     },
   };
 }
@@ -233,6 +238,38 @@ function toTargetDetails(target: Readonly<TargetStoreEntry>, cwd: string) {
   };
 }
 
+function resolveDisplaySections(details: ResolveDetails): ToolDisplaySection[] {
+  if (details.targets.length > 0) {
+    return [
+      createToolDisplaySection({
+        key: "resolve.targets",
+        title: "Targets",
+        items: details.targets,
+        totalCount: details.targetCount,
+        omittedCount: details.omittedCount,
+        format: (target) =>
+          `${target.name ?? "anonymous"} (${target.kind ?? "unknown"}) — ${target.file}:${target.displayLine}:${target.displayCharacter} [${target.targetId}]`,
+      }),
+    ];
+  }
+
+  if (details.candidates && details.candidates.length > 0) {
+    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}]`,
+      }),
+    ];
+  }
+
+  return [];
+}
+
 function resolveProvenance(outcome: TargetWorkflowOutcome): ResultProvenance[] {
   const sources = new Set<"semantic" | "structural">();
   if (outcome.kind === "resolved") {
@@ -252,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/code_resolve/tui.ts

@@ -0,0 +1,60 @@
+/** TUI renderer for code_resolve. */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  formatCallPath,
+  formatCallValue,
+  type ResultOptios,
+  renderSimpleResult,
+  type ToolRendererContext,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
+import type { CodeResolveToolParams } from "./execute.ts";
+
+/** Render the compact code_resolve call header. */
+export function renderResolveCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as Partial<CodeResolveToolParams>;
+  let content = theme.fg("toolTitle", "code_resolve");
+  const target = params.target;
+  if (!target || typeof target !== "object") return new Text(content, 0, 0);
+
+  const targetRecord = target as unknown as Record<string, unknown>;
+  if (targetRecord.symbol && typeof targetRecord.symbol === "object") {
+    content += renderResolveSymbol(targetRecord.symbol, theme);
+  } else if (targetRecord.anchor && typeof targetRecord.anchor === "object") {
+    content += renderResolveAnchor(targetRecord.anchor, theme);
+  } else {
+    const file = formatCallPath(targetRecord.file);
+    if (file) content += ` ${theme.fg("accent", file)}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+function renderResolveSymbol(value: object, theme: Theme): string {
+  const symbol = value as { query?: unknown; symbolKind?: unknown };
+  const query = formatCallValue(symbol.query);
+  const kind = formatCallValue(symbol.symbolKind, 30);
+  return `${query ? ` ${theme.fg("accent", query)}` : ""}${kind ? theme.fg("dim", ` [${kind}]`) : ""}`;
+}
+
+function renderResolveAnchor(value: object, theme: Theme): string {
+  const point = value as { file?: unknown; line?: unknown };
+  const file = formatCallPath(point.file);
+  const line = typeof point.line === "number" ? `:${point.line}` : "";
+  return file ? ` ${theme.fg("accent", file)}${theme.fg("warning", line)}` : "";
+}
+
+/** Render code_resolve progress, status, and structured result details. */
+export function renderResolveResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  context: ToolRendererContext | undefined,
+): ReturnType<typeof renderSimpleResult> {
+  return renderSimpleResult(result, options, theme, "Resolving…", context);
+}

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 }),
+  };
+}

package/src/tool/infra/workflow-control.ts

@@ -2,10 +2,18 @@ import type { WorkflowControl } from "../../session/workflow-control.ts";
 import type { CodeIntelToolExecCtx } from "../../types/index.ts";
 import { emitToolProgress } from "./progress.ts";
 
+/**
+ * Internal absolute deadline for one public code tool call. Pi supplies only
+ * a signal, so the adapter derives one bounded deadline per call.
+ */
+export const DEFAULT_WORKFLOW_DEADLINE_MS = 60_000;
+
 /** Translate Pi execution controls into presentation-free session controls. */
 export function toWorkflowControl(ctx: CodeIntelToolExecCtx): WorkflowControl {
   return {
+    operationId: ctx.operationId,
     signal: ctx.signal,
+    deadline: Date.now() + DEFAULT_WORKFLOW_DEADLINE_MS,
     progress: (event) => emitToolProgress(ctx.onUpdate, `${event.intent}: ${event.message}`),
   };
 }

package/src/tool/{refactor-plan/markdown.ts → refactor-markdown.ts}

@@ -1,10 +1,7 @@
-import { renderEvidenceListDisclosure } from "../../analysis/evidence.ts";
-import { toDisplayPath } from "../../analysis/search/paths.ts";
-import { assembledNextQueries } from "../result/assembly.ts";
-import type {
-  RefactorApplyResultAssembly,
-  RefactorPlanResultAssembly,
-} from "../result/refactor.ts";
+import { renderEvidenceListDisclosure } from "../analysis/evidence.ts";
+import { toDisplayPath } from "../analysis/search/paths.ts";
+import { assembledNextQueries } from "./result/assembly.ts";
+import type { RefactorApplyResultAssembly, RefactorPlanResultAssembly } from "./result/refactor.ts";
 
 /** Render a refactor plan from its canonical assembled evidence. */
 export function renderRefactorPlanResult(assembly: RefactorPlanResultAssembly): string {