decorated-pi 0.5.2 → 0.5.3

package/README.md

@@ -14,12 +14,10 @@ pi install /path/to/decorated-pi
 
 ### 1. Patch Tool
 
-Replaces Pi's built-in `edit` / `write` with a stronger `patch` tool that adds unique safety and usability improvements on top of the native tools.
+Replaces Pi's built-in `edit` with a stronger `patch` tool that adds unique safety and usability improvements on top of the native tools.
 
 | Capability | Pi native `edit` | `patch` |
 | ------ | :---: | :---: |
-| Exact string replacement | ✅ `oldText` | ✅ `old_str` |
-| Atomic overwrite | ✅ `write` | ✅ `overwrite` |
 | Syntax‑highlighted overwrite | ✅ streaming | ✅ incremental |
 | **Anchor‑based search** | ❌ extending `oldText` for uniqueness | ✅ `anchor` bounds scope for precise matching |
 | **Fuzzy whitespace match** | ❌ only reports "not found" | ✅ auto‑corrects tab↔space / trailing whitespace mismatches |

package/extensions/index.ts

@@ -4,8 +4,6 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-// Extend prompt cache TTL for all providers: Anthropic 1h, OpenAI 24h
-process.env.PI_CACHE_RETENTION ??= "long";
 import { setupSafety } from "./safety/index.js";
 import { setupModelIntegration } from "./model-integration";
 import { setupSlash } from "./slash";

package/extensions/io-tool-output.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared tool-output externalization helpers.
+ *
+ * Used by `setupIO` (for read / bash) and `maybeExternalizeMcpResult` (for MCP tools).
+ * Each writes to the same temp dir; MCP also adds a 2KB preview, while read / bash
+ * emit a single-line placeholder.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+
+export const TOOL_OUTPUT_TEMP_DIR = path.join(os.tmpdir(), "decorated-pi-results");
+
+/** Write content to a temp file under TOOL_OUTPUT_TEMP_DIR.
+ *  Returns the file path, or undefined on failure (e.g., /tmp full). */
+export function writeOutputToTemp(
+  toolName: string,
+  toolCallId: string,
+  content: string,
+): string | undefined {
+  try {
+    if (!fs.existsSync(TOOL_OUTPUT_TEMP_DIR)) {
+      fs.mkdirSync(TOOL_OUTPUT_TEMP_DIR, { recursive: true });
+    }
+    const id = toolCallId ? toolCallId.slice(0, 12) : randomBytes(8).toString("hex");
+    const filePath = path.join(TOOL_OUTPUT_TEMP_DIR, `${toolName}-${id}.txt`);
+    fs.writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  } catch {
+    return undefined;
+  }
+}

package/extensions/io.ts

@@ -26,9 +26,10 @@
  *   6. prepareArguments must handle literal newlines in JSON strings
  */
 
-import { defineTool, isReadToolResult, keyHint, getLanguageFromPath, highlightCode, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, isEditToolResult, isReadToolResult, isWriteToolResult, keyHint, type ExtensionAPI, type ToolResultEvent, type ToolResultEventResult } from "@earendil-works/pi-coding-agent";
 import { renderDiff } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { writeOutputToTemp } from "./io-tool-output.js";
 import { Type } from "typebox";
 import {
   applyPatch,
@@ -64,15 +65,9 @@ const PatchSchema = Type.Object({
   path: Type.String({
     description: "Path to the file to edit (relative or absolute).",
   }),
-  edits: Type.Optional(Type.Array(EditSchema, {
-    description: "Targeted replacements applied sequentially.",
-  })),
-  overwrite: Type.Optional(Type.Boolean({
-    description: "If true, replace the entire file atomically (write temp → mv).",
-  })),
-  new_str: Type.Optional(Type.String({
-    description: "Entire new file content when overwrite is true.",
-  })),
+  edits: Type.Array(EditSchema, {
+    description: "Targeted replacements applied sequentially. Each edit does exact string replacement with optional anchor.",
+  }),
 });
 
 // ─── Argument repair ───────────────────────────────────────────────────────────────
@@ -105,26 +100,6 @@ export function preparePatchArguments(input: any): any {
 
   const args = input as Record<string, any>;
 
-  // Legacy multi-file format: { patches: [{ path, edits }] } → extract first
-  if (Array.isArray(args.patches) && !args.path) {
-    const first = args.patches[0];
-    if (first && typeof first === "object" && first.path) {
-      Object.assign(args, first);
-      delete args.patches;
-    }
-  } else if (typeof args.patches === "string" && !args.path) {
-    try {
-      const parsed = jsonParseWithNewlineFix(args.patches);
-      if (Array.isArray(parsed) && parsed.length > 0 && parsed[0]?.path) {
-        Object.assign(args, parsed[0]);
-        delete args.patches;
-      } else if (parsed && typeof parsed === "object" && parsed.path) {
-        Object.assign(args, parsed);
-        delete args.patches;
-      }
-    } catch { /* keep original */ }
-  }
-
   // Edits serialized as JSON string
   if (typeof args.edits === "string") {
     try {
@@ -153,14 +128,6 @@ interface PatchCallComponent extends Box {
   previewArgsKey?: string;
   previewPending?: boolean;
   settledError: boolean;
-  /** Overwrite streaming highlight cache (mirrors write tool design) */
-  overwriteHighlightCache?: {
-    rawPath: string;
-    lang: string | undefined;
-    rawContent: string;
-    normalizedLines: string[];
-    highlightedLines: string[];
-  };
 }
 
 export function createPatchCallComponent(): PatchCallComponent {
@@ -184,88 +151,10 @@ function getPatchCallComponent(state: any, lastComponent: any): PatchCallCompone
   return comp;
 }
 
-// ─── Syntax highlighting for overwrite mode (mirrors write tool's incremental design) ──
-
-const OVERWRITE_PARTIAL_HIGHLIGHT_LINES = 50;
-
-function normalizeDisplayText(text: string): string {
-  return text.replace(/\r/g, "");
-}
-
 function replaceTabs(text: string): string {
   return text.replace(/\t/g, "    ");
 }
 
-function highlightSingleLine(line: string, lang: string | undefined): string {
-  const highlighted = highlightCode(line, lang);
-  return highlighted[0] ?? "";
-}
-
-function refreshOverwriteHighlightPrefix(cache: NonNullable<PatchCallComponent["overwriteHighlightCache"]>): void {
-  const prefixCount = Math.min(OVERWRITE_PARTIAL_HIGHLIGHT_LINES, cache.normalizedLines.length);
-  if (prefixCount === 0) return;
-  const prefixSource = cache.normalizedLines.slice(0, prefixCount).join("\n");
-  const prefixHighlighted = highlightCode(prefixSource, cache.lang);
-  for (let i = 0; i < prefixCount; i++) {
-    cache.highlightedLines[i] =
-      prefixHighlighted[i] ?? highlightSingleLine(cache.normalizedLines[i] ?? "", cache.lang);
-  }
-}
-
-function rebuildOverwriteHighlightCache(rawPath: string, fileContent: string): PatchCallComponent["overwriteHighlightCache"] | undefined {
-  const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
-  if (!lang) return undefined;
-  const normalized = replaceTabs(normalizeDisplayText(fileContent));
-  return {
-    rawPath,
-    lang,
-    rawContent: fileContent,
-    normalizedLines: normalized.split("\n"),
-    highlightedLines: highlightCode(normalized, lang),
-  };
-}
-
-function updateOverwriteHighlightCache(
-  cache: PatchCallComponent["overwriteHighlightCache"] | undefined,
-  rawPath: string,
-  fileContent: string,
-): PatchCallComponent["overwriteHighlightCache"] | undefined {
-  if (cache) {
-    const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
-    if (!lang || cache.lang !== lang || cache.rawPath !== rawPath) {
-      return rebuildOverwriteHighlightCache(rawPath, fileContent);
-    }
-    if (!fileContent.startsWith(cache.rawContent)) {
-      return rebuildOverwriteHighlightCache(rawPath, fileContent);
-    }
-    if (fileContent.length === cache.rawContent.length) return cache;
-    const deltaRaw = fileContent.slice(cache.rawContent.length);
-    const deltaNormalized = replaceTabs(normalizeDisplayText(deltaRaw));
-    cache.rawContent = fileContent;
-    if (cache.normalizedLines.length === 0) {
-      cache.normalizedLines.push("");
-      cache.highlightedLines.push("");
-    }
-    const segments = deltaNormalized.split("\n");
-    const lastIndex = cache.normalizedLines.length - 1;
-    cache.normalizedLines[lastIndex] += segments[0];
-    cache.highlightedLines[lastIndex] = highlightSingleLine(cache.normalizedLines[lastIndex]!, cache.lang);
-    for (let i = 1; i < segments.length; i++) {
-      cache.normalizedLines.push(segments[i]!);
-      cache.highlightedLines.push(highlightSingleLine(segments[i]!, cache.lang));
-    }
-    refreshOverwriteHighlightPrefix(cache);
-    return cache;
-  }
-  return rebuildOverwriteHighlightCache(rawPath, fileContent);
-}
-
-function addHighlightedContent(parent: Box, lines: string[]): void {
-  for (const line of lines) {
-    parent.addChild(new Text(line, 0, 0));
-  }
-}
-
 function getPatchHeaderBg(component: PatchCallComponent, theme: any) {
   if (component.settledError) {
     return (text: string) => theme.bg("toolErrorBg", text);
@@ -335,9 +224,7 @@ export function buildPatchCallComponent(component: PatchCallComponent, args: any
   let label = "";
   if (args?.path) {
     label = theme.fg("accent", args.path);
-    if (args.overwrite) {
-      label += theme.fg("error", " [overwrite]");
-    } else if (args.edits?.length > 0) {
+    if (Array.isArray(args.edits) && args.edits.length > 0) {
       label += theme.fg("dim", ` (${args.edits.length} edit${args.edits.length > 1 ? "s" : ""})`);
     }
   }
@@ -348,9 +235,7 @@ export function buildPatchCallComponent(component: PatchCallComponent, args: any
 
   const preview = component.preview;
   let body = "";
-  if ("isOverwrite" in preview && preview.isOverwrite && preview.preview) {
-    body = preview.preview;
-  } else if ("diff" in preview && preview.diff) {
+  if ("diff" in preview && preview.diff) {
     body = preview.diff;
   } else if ("error" in preview && preview.error) {
     component.addChild(new Spacer(1));
@@ -364,36 +249,18 @@ export function buildPatchCallComponent(component: PatchCallComponent, args: any
   const FOLD_THRESHOLD = 45;
 
   component.addChild(new Spacer(1));
-  const isOverwrite = "isOverwrite" in preview && preview.isOverwrite;
 
   if (lines.length > FOLD_THRESHOLD && !expanded) {
     // 折叠态: 显示前几行 + 摘要
-    if (isOverwrite) {
-      if (component.overwriteHighlightCache) {
-        const n = Math.min(10, component.overwriteHighlightCache.highlightedLines.length);
-        addHighlightedContent(component, component.overwriteHighlightCache.highlightedLines.slice(0, n));
-      } else {
-        component.addChild(new Text(theme.fg("toolDiffAdded", lines.slice(0, 10).join("\n")), 0, 0));
-      }
-    } else {
-      const shown = lines.slice(0, 10).join("\n");
-      appendPatchDiffChildren(component, shown, theme);
-    }
+    const shown = lines.slice(0, 10).join("\n");
+    appendPatchDiffChildren(component, shown, theme);
     component.addChild(new Text(
       theme.fg("dim", `  ... ${lines.length - 10} more lines (`) + keyHint("app.tools.expand", "expand") + theme.fg("dim", ")"),
       0, 0,
     ));
   } else {
     // 展开态: 完整显示
-    if (isOverwrite) {
-      if (component.overwriteHighlightCache) {
-        addHighlightedContent(component, component.overwriteHighlightCache.highlightedLines);
-      } else {
-        component.addChild(new Text(theme.fg("toolDiffAdded", body), 0, 0));
-      }
-    } else {
-      appendPatchDiffChildren(component, body, theme);
-    }
+    appendPatchDiffChildren(component, body, theme);
   }
 
   return component;
@@ -401,17 +268,51 @@ export function buildPatchCallComponent(component: PatchCallComponent, args: any
 
 // ─── Setup ──────────────────────────────────────────────────────────────────────────
 
+export const OUTPUT_EXTERNALIZE_THRESHOLD = 30_000; // 30KB — match Claude Code's bash truncation threshold
+
+/** If the tool result content is a single text string longer than the
+ *  threshold, replace it with a one-line placeholder pointing at the
+ *  full output on disk. Returns the modified result, or undefined to
+ *  leave the original content untouched. */
+export function maybeExternalizeToolResult(event: ToolResultEvent): ToolResultEventResult | undefined {
+  const content = event.content;
+  if (!Array.isArray(content) || content.length === 0) return undefined;
+  const first = content[0];
+  if (first?.type !== "text" || typeof first.text !== "string") return undefined;
+  const text = first.text;
+  if (text.length <= OUTPUT_EXTERNALIZE_THRESHOLD) return undefined;
+
+  const filePath = writeOutputToTemp(event.toolName, event.toolCallId, text);
+  if (!filePath) return undefined; // write failed — keep original content
+
+  return {
+    content: [{
+      type: "text" as const,
+      text: `[Output truncated: ${text.length.toLocaleString()} chars. Full output: ${filePath}]`,
+    }],
+  };
+}
+
 export function setupIO(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
     restoreReadMarkersFromBranch(ctx.sessionManager.getBranch() as any[], ctx.cwd);
     const active = pi.getActiveTools();
-    pi.setActiveTools(active.filter(t => !["edit", "write", "grep", "find", "ls"].includes(t)));
+    // Remove: edit (replaced by patch), grep/find/ls (replaced by bash)
+    // Keep: write (full-file write)
+    pi.setActiveTools(active.filter(t => !["edit", "grep", "find", "ls"].includes(t)));
   });
 
   pi.on("session_compact", () => {
     clearReadMarkers();
   });
 
+  // Externalize large tool results (read / bash) to a temp file.
+  // Keeps the messages segment small so prompt cache stays warm across turns.
+  pi.on("tool_result", (event) => {
+    if (event.toolName !== "read" && event.toolName !== "bash") return;
+    return maybeExternalizeToolResult(event);
+  });
+
   // Track file read times
   pi.on("tool_result", (event, ctx) => {
     if (!isReadToolResult(event)) return;
@@ -424,18 +325,31 @@ export function setupIO(pi: ExtensionAPI) {
     if (marker) pi.appendEntry(FILE_TIMES_CUSTOM_TYPE, marker);
   });
 
+  // Track file write times (for write and edit, in case patch module is disabled)
+  pi.on("tool_result", (event, ctx) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) return;
+    const filePath = event.input?.path;
+    if (typeof filePath !== "string" || !filePath.trim()) return;
+    const cwd: string = ctx.cwd ?? process.cwd();
+    const absPath = resolveAbsolutePath(cwd, filePath);
+    // Only record if the write succeeded (not an error result)
+    if (event.isError) return;
+    recordReadTime(absPath);
+    const marker = createFileTimeMarkerData(cwd, absPath);
+    if (marker) pi.appendEntry(FILE_TIMES_CUSTOM_TYPE, marker);
+  });
+
   pi.registerTool(defineTool({
     name: "patch",
     label: "Patch",
     description: [
-      "Edits a file using exact string replacement, with anchor support and overwrite mode.",
+      "Edits a file using exact string replacement, with anchor support.",
       "When old_str is not unique, add more surrounding context or use anchor to narrow search.",
       "",
       "Examples:",
       '  { path: "src/foo.ts", edits: [{ old_str: "return 1", new_str: "return 42" }] }',
       '  { path: "src/foo.ts", edits: [{ anchor: "function bar() {", old_str: "return x", new_str: "return x + 1" }] }',
       '  { path: "src/foo.ts", edits: [{ anchor: "function init() {", old_str: "const DEBUG = true;", new_str: "const DEBUG = false;" }, { old_str: "log(\"debug\");", new_str: "// debug disabled" }] }',
-      '  { path: "src/bar.ts", overwrite: true, new_str: "entire file content" }',
       "",
       "Anchor (optional): narrows old_str search to lines after a unique marker.",
       "  Code: use the enclosing definition — function/class/struct/method signature.",
@@ -443,21 +357,20 @@ export function setupIO(pi: ExtensionAPI) {
       "  Non-code (markdown, config, etc.): use section headings, key names, or distinctive lines.",
       '  e.g. "## API Reference" in .md or "[dependencies]" in .toml files.',
     ].join("\n"),
-    promptSnippet: "Edits a file using exact string replacement, with anchor support and overwrite mode.",
+    promptSnippet: "Edits a file using exact string replacement, with anchor support.",
     promptGuidelines: [
-      "Always prefer modifying files with PATCH tool over bash commands or python scripts.",
-      "For full-file replacement, always use patch tool to prevent unintended edits or data loss.",
+      "Always prefer modifying files with patch tool over bash commands or python scripts.",
       "To prevent hallucinations: 1. Keep each edit batch ≤ 5 changes; 2. Process remaining revisions in sequential steps",
       "On repeated failures: read the file first to confirm information accuracy.",
     ],
     parameters: PatchSchema,
     renderShell: "self",
     prepareArguments: preparePatchArguments,
-    execute: async (_toolCallId: string, input: { path: string; edits?: any[]; overwrite?: boolean; new_str?: string }, _signal: any, _onUpdate: any, ctx: any) => {
+    execute: async (_toolCallId: string, input: { path: string; edits: any[] }, _signal: any, _onUpdate: any, ctx: any) => {
       const cwd: string = ctx.cwd ?? process.cwd();
 
-      // Stale-read protection (only for edits, not overwrite)
-      if (!input.overwrite && input.path?.trim()) {
+      // Stale-read protection
+      if (input.path?.trim()) {
         const absPath = resolveAbsolutePath(cwd, input.path);
         const staleError = checkStaleFile(absPath, input.path);
         if (staleError) throw new Error(staleError);
@@ -491,28 +404,6 @@ export function setupIO(pi: ExtensionAPI) {
         component.previewArgsKey = argsKey;
         component.previewPending = false;
         component.settledError = false;
-        component.overwriteHighlightCache = undefined;
-      }
-
-      // Overwrite streaming: incrementally highlight as new_str streams in
-      if (args?.overwrite && typeof args?.path === "string" && typeof args?.new_str === "string") {
-        if (context.argsComplete) {
-          // Final: full rebuild for best quality
-          component.overwriteHighlightCache = rebuildOverwriteHighlightCache(args.path, args.new_str);
-        } else {
-          // Streaming: incremental update
-          component.overwriteHighlightCache = updateOverwriteHighlightCache(
-            component.overwriteHighlightCache, args.path, args.new_str,
-          );
-        }
-        // Inject highlighted content as synthetic preview for buildPatchCallComponent
-        const cache = component.overwriteHighlightCache;
-        if (cache) {
-          component.preview = { preview: cache.rawContent, isOverwrite: true };
-        } else {
-          // No language detected: fall back to plain text
-          component.preview = { preview: args.new_str, isOverwrite: true };
-        }
       }
 
       // Preview diff is computed during execute and delivered via result.details.diff.
@@ -527,37 +418,17 @@ export function setupIO(pi: ExtensionAPI) {
       let changed = false;
 
       if (callComponent) {
-        // overwrite: 保留完整文件预览，不要被空 diff 覆盖成只剩 header
-        const overwriteContent = !context.isError && context.args?.overwrite && typeof context.args?.new_str === "string"
-          ? context.args.new_str
-          : undefined;
-
-        if (typeof overwriteContent === "string") {
-          const nextCache = rebuildOverwriteHighlightCache(context.args?.path, overwriteContent);
-          const prevContent = (callComponent.overwriteHighlightCache?.rawContent ?? undefined);
-          const prevPath = callComponent.overwriteHighlightCache?.rawPath;
-          callComponent.overwriteHighlightCache = nextCache;
-          if (
-            !(callComponent.preview && "isOverwrite" in callComponent.preview && callComponent.preview.isOverwrite && callComponent.preview.preview === overwriteContent) ||
-            prevContent !== overwriteContent ||
-            prevPath !== context.args?.path
-          ) {
-            callComponent.preview = { preview: overwriteContent, isOverwrite: true };
+        // Use execute's returned diff (same design as Pi's native edit tool)
+        const resultDiff = !context.isError && result.details?.diff;
+        if (typeof resultDiff === "string") {
+          const newPreview = { diff: resultDiff };
+          if (callComponent.preview?.diff !== resultDiff) {
+            callComponent.preview = newPreview;
             changed = true;
           }
-        } else {
-          // 非 overwrite：优先使用 execute 返回的 diff（与 Pi 原生 edit 工具一致）
-          const resultDiff = !context.isError && result.details?.diff;
-          if (typeof resultDiff === "string") {
-            const newPreview = { diff: resultDiff };
-            if (callComponent.preview?.diff !== resultDiff) {
-              callComponent.preview = newPreview;
-              changed = true;
-            }
-          }
         }
 
-        // 更新错误状态
+        // Update error state
         if (callComponent.settledError !== context.isError) {
           callComponent.settledError = context.isError;
           changed = true;

package/extensions/mcp/builtin.ts

@@ -340,3 +340,37 @@ export function cleanupStaleCache(configs: McpServerConfig[], cwd?: string): voi
     }
   }
 }
+
+// ── Large result externalization ────────────────────────────────────────
+
+export const EXTERNALIZE_THRESHOLD = 50_000; // 50KB
+export const EXTERNALIZE_PREVIEW_SIZE = 2_000; // 2KB preview
+import { writeOutputToTemp } from "../io-tool-output.js";
+
+/**
+ * If content exceeds threshold, save to temp file and return preview + path.
+ * Otherwise return original content unchanged.
+ * Falls back to returning full text if file write fails.
+ */
+export function maybeExternalizeMcpResult(
+  text: string,
+  toolName: string,
+  toolCallId: string,
+): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown> } {
+  if (text.length <= EXTERNALIZE_THRESHOLD) {
+    return { content: [{ type: "text", text }], details: {} };
+  }
+
+  const filePath = writeOutputToTemp(toolName, toolCallId, text);
+  if (!filePath) {
+    return { content: [{ type: "text", text }], details: {} };
+  }
+  const preview = text.slice(0, EXTERNALIZE_PREVIEW_SIZE);
+  return {
+    content: [{ type: "text", text: `${preview}\n\n[Truncated: ${text.length.toLocaleString()} chars total. Full output saved to: ${filePath}]` }],
+    details: {
+      fullOutputPath: filePath,
+      truncation: { truncated: true, outputChars: EXTERNALIZE_PREVIEW_SIZE, totalChars: text.length, maxBytes: EXTERNALIZE_THRESHOLD },
+    },
+  };
+}

package/extensions/mcp/index.ts

@@ -4,6 +4,8 @@ import { McpConnection } from "./client.js";
 import {
   resolveMcpConfigs,
   loadMcpCache, updateServerCache, cleanupStaleCache,
+  maybeExternalizeMcpResult,
+  BUILTIN_MCP_SERVERS,
   type McpServerConfig, type McpToolCache,
 } from "./builtin.js";
 
@@ -51,7 +53,24 @@ function formatMcpResultText(text: string, expanded: boolean, theme: any): strin
     text,
     expanded ? Number.MAX_SAFE_INTEGER : MCP_RESULT_FOLD_LINES,
   );
-  let rendered = displayLines.join("\n") ? theme.fg("toolOutput", displayLines.join("\n")) : "";
+  
+  // Check for externalization message in the last line
+  const lastLine = displayLines[displayLines.length - 1] || "";
+  let outputLines = [...displayLines];
+  let truncationMsg = "";
+  
+  if (lastLine.startsWith('[Truncated: ') && lastLine.endsWith(']')) {
+    truncationMsg = lastLine;
+    outputLines = outputLines.slice(0, -1);
+  }
+  
+  const outputText = outputLines.join("\n");
+  let rendered = outputText ? theme.fg("toolOutput", outputText) : "";
+  
+  if (truncationMsg) {
+    rendered += (rendered ? "\n" : "") + theme.fg("warning", truncationMsg);
+  }
+  
   if (!expanded && remainingLines > 0) {
     rendered += `${theme.fg("muted", `\n... (${remainingLines} more lines, ${totalLines} total,`)} ${keyHint("app.tools.expand", "to expand")})`;
   }
@@ -100,10 +119,11 @@ function cacheScopeForSource(source: string): "global" | "project" {
 
 // ── register cached tools ─────────────────────────────────────────────────
 
-function registerCachedTools(pi: ExtensionAPI, configs: McpServerConfig[]): void {
-  const cache = loadMcpCache(cachedCwd);
-  if (!cache) return;
-
+function registerCachedToolsFromCache(
+  pi: ExtensionAPI,
+  cache: McpCache,
+  configs: McpServerConfig[]
+): void {
   for (const config of configs) {
     if (!config.enabled) continue;
     const entry = cache.servers[config.name];
@@ -122,15 +142,19 @@ function registerCachedTools(pi: ExtensionAPI, configs: McpServerConfig[]): void
         execute: async (_id, params, _signal, _update, _ctx) => {
           const conn = activeConnections.find(c => c.serverName === config.name);
           if (!conn) {
+            // Tool is registered from cache before connectAll finishes. Tell the
+            // model to retry — connection is establishing in the background.
+            const status = allServers.get(config.name);
+            const state = status?.state ?? "connecting";
             return {
-              content: [{ type: "text", text: `MCP server "${config.name}" is not connected.` }],
-              isError: true,
+              content: [{ type: "text", text: `MCP server "${config.name}" is ${state}. Please retry shortly.` }],
+              isError: false,
               details: {},
             };
           }
           try {
             const text = await conn.callTool(t.name, params as Record<string, unknown>);
-            return { content: [{ type: "text", text }], isError: false, details: {} };
+            return maybeExternalizeMcpResult(text, toolName, _id);
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             return {
@@ -145,9 +169,18 @@ function registerCachedTools(pi: ExtensionAPI, configs: McpServerConfig[]): void
   }
 }
 
+function registerCachedTools(pi: ExtensionAPI, configs: McpServerConfig[]): void {
+  const cache = loadMcpCache(cachedCwd);
+  if (!cache) return;
+  registerCachedToolsFromCache(pi, cache, configs);
+}
+
 // ── connect ───────────────────────────────────────────────────────────────
 
-async function connectAll(configs: McpServerConfig[], ui?: { notify: (msg: string, type: string) => void }): Promise<void> {
+async function connectAll(
+  configs: McpServerConfig[],
+  ui?: { notify: (msg: string, type: string) => void }
+): Promise<{ schemaChanges: string[]; hasNewServer: boolean }> {
   // Load current cache for comparison
   const cache = loadMcpCache(cachedCwd);
   const schemaChanges: string[] = [];
@@ -241,10 +274,17 @@ async function connectAll(configs: McpServerConfig[], ui?: { notify: (msg: strin
   await connectPromise;
   connectPromise = null;
 
-  // Notify about schema changes
-  if (schemaChanges.length > 0 && ui) {
-    ui.notify(`MCP schema updated: ${schemaChanges.join('; ')}. Run /reload to apply.`, "warning");
+  // Determine whether any server had no cached tools (first-time connection).
+  let hasNewServer = false;
+  for (const server of configs) {
+    const cachedEntry = cache?.servers[server.name];
+    if (!cachedEntry || cachedEntry.tools.length === 0) {
+      hasNewServer = true;
+      break;
+    }
   }
+
+  return { schemaChanges, hasNewServer };
 }
 
 // ── setup ─────────────────────────────────────────────────────────────────
@@ -263,11 +303,27 @@ export function setupMcp(pi: ExtensionAPI) {
 
     const enabledConfigs = configs.filter(s => s.enabled);
 
-    // Register tools from cache — prompt-stable, works even if MCP is down
-    registerCachedTools(pi, enabledConfigs);
+    // Load cache and register tools immediately (before connectAll)
+    const cache = loadMcpCache(cachedCwd);
+    if (cache) {
+      registerCachedToolsFromCache(pi, cache, enabledConfigs);
+    }
 
-    // Connect in background, pass UI for schema change notifications
-    void connectAll(enabledConfigs, ctx.hasUI ? ctx.ui : undefined);
+    // Connect in background (fire-and-forget, don't block session_start)
+    void connectAll(enabledConfigs, ctx.hasUI ? ctx.ui : undefined).then(({ schemaChanges, hasNewServer }) => {
+      // Re-register tools when:
+      //   - A server was not in cache before (first connection)
+      //   - Schema changed (tools added/removed/changed)
+      if (hasNewServer || schemaChanges.length > 0) {
+        const cache = loadMcpCache(cachedCwd);
+        if (cache) {
+          registerCachedToolsFromCache(pi, cache, enabledConfigs);
+        }
+      }
+      if (schemaChanges.length > 0 && ctx.hasUI) {
+        ctx.ui.notify(`MCP schema updated: ${schemaChanges.join('; ')}.`, "info");
+      }
+    });
   });
 
   pi.on("session_shutdown", () => {

package/extensions/slash.ts

@@ -255,8 +255,11 @@ class McpStatusComponent extends Container {
         if (s.tools.length > 0) {
           lines.push(`    ${s.toolCount} tool${s.toolCount === 1 ? "" : "s"}:`);
           for (const tool of s.tools.slice(0, 6)) {
-            const td = tool.description
-              ? ` — ${tool.description.slice(0, 55)}`
+            const flat = (tool.description ?? "").replace(/\s+/g, " ").trim();
+            const td = flat
+              ? flat.length > 55
+                ? ` — ${flat.slice(0, 55)}…`
+                : ` — ${flat}`
               : "";
             lines.push(`      ${tool.name}${td}`);
           }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "decorated-pi",
-    "version": "0.5.2",
+    "version": "0.5.3",
     "description": "decorated-pi is a practical enhancement pack for pi — smarter tools that are token efficient and cache friendly.",
     "keywords": [
         "pi",
@@ -13,7 +13,6 @@
         "language-server",
         "secret-detection"
     ],
-    "type": "commonjs",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -46,6 +45,6 @@
     "scripts": {
         "prepack": "depcheck --fail-on-missing",
         "test": "vitest run",
-        "prepublishOnly": "npm install --package-lock-only --no-audit --no-fund && npm test && depcheck --fail-on-missing && publint"
+        "prepublishOnly": "npm install --no-audit --no-fund && npm test && depcheck --fail-on-missing && publint"
     }
 }