decorated-pi 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # decorated-pi
 
-`decorated-pi` is a Pi extension that adds stronger edit tool, safety gates, LSP tools, image/compaction model helpers, smarter `@` file search, dynamic subdirectory `AGENTS.md` loading, and a few workflow quality-of-life improvements.
+`decorated-pi` is a practical enhancement pack for [Pi](https://github.com/earendil-works/pi).
 
 ## Install
 
@@ -20,24 +20,45 @@ Replaces Pi's built-in `edit` / `write` with a stronger `patch` tool:
 - **mtime tracking** — records file modification time on `read`, rejects `patch` if the file changed since last read, preventing blind or stale edits
 - **explicit overwrite** — offer atomic `overwrite: true` mode for overwrite files or full-file creation to prevent unintened overwrite
 
-### 2. Smart `@` File Search
+### 2. Secret redaction
 
-Replaces Pi's default file search with a faster, project-aware search strategy:
+Three-layer detection: high-confidence known-format patterns (AWS, GitHub, OpenAI, etc.), config-key regex matching, and adjusted Shannon entropy heuristics for unknown secret-like values.
 
-- Uses project-aware file discovery
-- Prioritizes filename-based matches for more intuitive results
-- Reduces clutter from hidden, cache, and build directories
-- Keeps default suggestions focused on visible project files
+### 3. Built-in MCP Client
+
+Zero-config MCP client with two built-in servers:
 
-### 3. LSP Tool Suite
+| Server | Tool Prefix | Source |
+| --- | --- | --- |
+| Context7 | `context7_*` | `https://mcp.context7.com/mcp` |
+| Exa | `exa_*` | `https://mcp.exa.ai/mcp` |
 
-Based on [@spences10/pi-lsp](https://github.com/spences10/my-pi/tree/main/packages/pi-lsp), with major additions:
+**Project-level config** — add custom MCP servers by placing an `mcp.json` or `.mcp.json` (also `.pi/mcp.json`, `.agents/mcp.json`, `.claude/mcp.json` and their `.`-prefixed variants) anywhere in your project tree. Servers found closer to `cwd` take precedence over ancestor directories.
 
-- C/C++ and Lua support
-- `lsp_find_symbol`, `lsp_rename`, multi-file support merged into `lsp_diagnostics`
-- Force-sync on `didChange` (no stale diagnostics)
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "url": "https://my-mcp.example.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
 
-Supported languages: c/cpp, go, java, lua, python, ruby, rust, svelte, typescript
+**Global config** — persist custom servers in `~/.pi/agent/decorated-pi.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": { "url": "https://my-mcp.example.com/mcp" }
+  }
+}
+```
+
+**Priority**: project > global > builtin. A server with the same name from a higher-priority source overrides lower ones.
+
+Use `/mcp` to view connection status and registered tools.
 
 ### 4. Auxiliary Models (Image + Compact)
 
@@ -46,31 +67,32 @@ Uses cheaper models for auxiliary tasks, configured via `/dp-model`:
 - **Image read fallback** — when the model reads an image file, detects type via magic bytes, calls a configured vision-capable model, and replaces the read result with image analysis text (jpeg, png, gif, webp)
 - **Compact model** — uses a configured model for context compaction (instead of the main model), auto-resumes after compaction.
 
-### 5. Safety Layer
-
-- **Dangerous bash guard**
-  - asks for confirmation on destructive commands such as:
-    - `rm`
-    - `sudo`
-    - `svn commit/revert`
-    - `git reset/restore/clean/push/revert`
-    - `npm publish`
-    - `>` / `1>` / `2>` / `&>` / `tee` overwrite existing files
-  - Hints the agent to use `edit` instead of `write` on non-empty files
-- **Protected paths**
-  - Blocks read/write access (via `write`/`edit`/`read` tools or `cat`/`head`/`tail`/`grep`/`rg` etc. bash commands) to sensitive locations such as `.env`, `.git/`, `.ssh/`, `*.pem`, `*.key`, etc.
-- **Secret redaction**
-  - Three-layer detection: high-confidence known-format patterns (AWS, GitHub, OpenAI, etc.), config-key regex matching, and adjusted Shannon entropy heuristics for unknown secret-like values.
-  - Based on [opencode-secrets-protect](https://github.com/jscheel/opencode-secrets-protect)
-
-### 6. Dynamic Subdirectory `AGENTS.md` / `CLAUDE.md`
+### 5. Smart `@` File Search
+
+Replaces Pi's default file search with a faster, project-aware search strategy:
+
+- Uses project-aware file discovery
+- Prioritizes filename-based matches for more intuitive results
+- Reduces clutter from hidden, cache, and build directories
+- Keeps default suggestions focused on visible project files
+
+### 6. LSP Tool Suite
+
+A cleaned-up, minimal LSP toolset. The extension keeps only the two LSP tools that cover the most practical coding workflows: checking diagnostics after edits and inspecting file structure before focused changes.
+
+- **`lsp_diagnostics`** — file diagnostics with severity filtering
+- **`lsp_document_symbols`** — file symbol outline
+
+Supported languages: c/cpp, go, java, lua, json, python, ruby, rust, svelte, typescript
+
+### 7. Dynamic Subdirectory `AGENTS.md` / `CLAUDE.md`
 
 When the agent reads or edits a file:
 
 - discovers `AGENTS.md` / `CLAUDE.md` in the file's directory and ancestor directories
 - injects newly discovered guidance into tool results
 
-### 7. Extend Providers
+### 8. Extend Providers
 
 Extend providers are registered via `/login` → "Use a subscription":
 
@@ -95,9 +117,10 @@ Modules can be toggled on/off. Changes take effect after `/reload`.
 | Module | Default | Effect when disabled |
 | -------- | --------- | --------------------- |
 | `patch` | `true` | Reverts to Pi's built-in `edit` / `write` tools |
-| `safety` | `true` | No command guard, no protected path check, no secret redaction |
+| `safety` | `true` | No secret redaction on `read` / `bash` output |
 | `lsp` | `true` | All `lsp_*` tools unregistered — no diagnostics, hover, etc. |
 | `smart-at` | `true` | Fallback to Pi's built-in `@` file completion |
+| `mcp` | `true` | All `{server}_*` MCP tools unregistered |
 
 Use `/dp-settings` to toggle, or edit the config file directly:
 
@@ -107,7 +130,8 @@ Use `/dp-settings` to toggle, or edit the config file directly:
     "patch": true,
     "safety": true,
     "lsp": false,
-    "smart-at": true
+    "smart-at": true,
+    "mcp": true
   }
 }
 ```

package/extensions/file-times.ts

@@ -4,11 +4,26 @@
  * - `read` tool records mtime when the LLM reads a file
  * - `patch` tool checks mtime before editing — rejects if file changed since last read
  * - `patch` tool updates mtime after a successful write
+ * - Markers are persisted to session custom entries and restored from the
+ *   current branch after the last compaction boundary.
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+export const FILE_TIMES_CUSTOM_TYPE = "decorated-pi.file-times";
+
+export interface FileTimeMarkerData {
+  path: string;
+  mtimeMs: number;
+}
+
+interface SessionLikeEntry {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
 /** Last-known mtime for each absolute file path (ms since epoch). */
 const readMarkers = new Map<string, number>();
 
@@ -54,7 +69,50 @@ export function checkStaleFile(absPath: string, displayPath: string): string | u
   return undefined;
 }
 
-/** Clear all tracked file times (e.g., on session start). */
+function toStoredPath(cwd: string, absPath: string): string {
+  const normalizedCwd = path.normalize(cwd);
+  const normalizedAbs = path.normalize(absPath);
+  const rel = path.relative(normalizedCwd, normalizedAbs);
+  if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) return rel;
+  return normalizedAbs;
+}
+
+function lastCompactionIndex(entries: SessionLikeEntry[]): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]?.type === "compaction") return i;
+  }
+  return -1;
+}
+
+function isFileTimeMarkerData(value: unknown): value is FileTimeMarkerData {
+  return !!value
+    && typeof value === "object"
+    && typeof (value as any).path === "string"
+    && typeof (value as any).mtimeMs === "number";
+}
+
+/** Build a session-persisted marker payload for the current file version. */
+export function createFileTimeMarkerData(cwd: string, absPath: string): FileTimeMarkerData | undefined {
+  if (!fs.existsSync(absPath)) return undefined;
+  return {
+    path: toStoredPath(cwd, absPath),
+    mtimeMs: getFileMtime(absPath),
+  };
+}
+
+/** Restore markers from the current branch, ignoring anything before the last compaction. */
+export function restoreReadMarkersFromBranch(entries: SessionLikeEntry[], cwd: string): void {
+  clearReadMarkers();
+  const start = lastCompactionIndex(entries) + 1;
+  for (const entry of entries.slice(start)) {
+    if (entry.type !== "custom" || entry.customType !== FILE_TIMES_CUSTOM_TYPE) continue;
+    if (!isFileTimeMarkerData(entry.data)) continue;
+    const absPath = resolveAbsolutePath(cwd, entry.data.path);
+    readMarkers.set(absPath, entry.data.mtimeMs);
+  }
+}
+
+/** Clear all tracked file times (e.g., on session start or compaction). */
 export function clearReadMarkers(): void {
   readMarkers.clear();
 }
@@ -63,4 +121,4 @@ export function clearReadMarkers(): void {
 export function resolveAbsolutePath(cwd: string, filePath: string): string {
   if (path.isAbsolute(filePath)) return path.normalize(filePath);
   return path.normalize(path.resolve(cwd, filePath));
-}
+}

package/extensions/guidance.ts

@@ -9,9 +9,11 @@ export function setupGuidance(pi: ExtensionAPI) {
     const guidance = [
       DECORATED_PI_GUIDANCE_MARKER,
       "",
-      "Before taking any action on a user's prompt, briefly restate your understanding of what the user wants. If ambiguous, ask clarifying questions. Only proceed after intent is clear.",
-      "",
-      "For medium-to-large tasks (more than 3 steps or touching multiple files/systems), break the task into discrete steps. For small tasks (1-2 steps), do it directly.",
+      "- Before acting on a user's prompt, ensure you fully understand their needs. If the intent is ambiguous, ask clarifying questions. Proceed only when the intent is clear.",
+      "- Look before you leap! Ensure you have conducted thorough research before taking any action.",
+      "- Exercise caution when performing any **write** operations, especially when you are in a research or exploration phase.",
+      "- You don't need to read **AGENTS.md** or **CLAUDE.md** files unless you're explicitly asked to, these files will loaded automatically if neccessary.",
+      "- CAUTION: Do not perform write operations in the following directories unless explicitly instructed: `node_modules`, `venv`, `env`, `__pycache__`, `.git` or any other hidden directories.",
     ].join("\n");
 
     return {

package/extensions/index.ts

@@ -13,6 +13,7 @@ import { setupGuidance } from "./guidance";
 import { setupLsp } from "./lsp/index";
 import { setupProviders } from "./providers/index";
 import { setupSmartAt } from "./smart-at";
+import { setupMcp } from "./mcp/index.js";
 import { isModuleEnabled } from "./settings";
 
 export default function (pi: ExtensionAPI) {
@@ -29,4 +30,5 @@ export default function (pi: ExtensionAPI) {
   if (isModuleEnabled("safety"))    setupSafety(pi);
   if (isModuleEnabled("lsp"))       setupLsp(pi);
   if (isModuleEnabled("smart-at"))  setupSmartAt(pi);
+  if (isModuleEnabled("mcp"))       setupMcp(pi);
 }

package/extensions/io.ts

@@ -18,11 +18,15 @@
  *   2. TUI rendering MUST mirror the edit tool pattern exactly
  *   3. getPatchHeaderBg: settledError MUST be checked first
  *   4. renderResult must NOT return the Box
+ *      renderCall returns the Box (callComponent). If renderResult
+ *      also returns it, pi's ToolExecutionComponent adds it twice
+ *      to the container, causing duplicate boxes. renderResult
+ *      must return context.lastComponent (a separate Container).
  *   5. Error text must go INSIDE the Box, not in the result Container
  *   6. prepareArguments must handle literal newlines in JSON strings
  */
 
-import { defineTool, isReadToolResult, keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineTool, isReadToolResult, keyHint, getLanguageFromPath, highlightCode, type ExtensionAPI } 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 { Type } from "typebox";
@@ -30,10 +34,17 @@ import {
   applyPatch,
   formatPatchResult,
   generatePatchDiff,
-  computePatchPreview,
   type PatchPreview,
 } from "./patch.js";
-import { recordReadTime, checkStaleFile, clearReadMarkers, resolveAbsolutePath } from "./file-times.js";
+import {
+  recordReadTime,
+  checkStaleFile,
+  clearReadMarkers,
+  resolveAbsolutePath,
+  FILE_TIMES_CUSTOM_TYPE,
+  createFileTimeMarkerData,
+  restoreReadMarkersFromBranch,
+} from "./file-times.js";
 
 // ─── Schema ─────────────────────────────────────────────────────────────────────────
 
@@ -142,9 +153,17 @@ 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[];
+  };
 }
 
-function createPatchCallComponent(): PatchCallComponent {
+export function createPatchCallComponent(): PatchCallComponent {
   return Object.assign(new Box(1, 1, (text: string) => text), {
     preview: undefined,
     previewArgsKey: undefined,
@@ -165,6 +184,88 @@ 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);
@@ -187,6 +288,14 @@ function createSingleLineComponent(text: string) {
   };
 }
 
+function formatPatchMetaLine(line: string, theme: any): string {
+  const missingSuffix = " (missing)";
+  if (line.endsWith(missingSuffix)) {
+    return theme.fg("accent", line.slice(0, -missingSuffix.length)) + theme.fg("warning", missingSuffix);
+  }
+  return theme.fg("accent", line);
+}
+
 function appendPatchDiffChildren(parent: Box, body: string, theme: any): void {
   const rawLines = body.split("\n");
   let buffer: string[] = [];
@@ -200,17 +309,17 @@ function appendPatchDiffChildren(parent: Box, body: string, theme: any): void {
   for (const line of rawLines) {
     if (line.startsWith("@@ lines ")) {
       flush();
-      parent.addChild(createSingleLineComponent(theme.fg("accent", line)) as any);
+      parent.addChild(createSingleLineComponent(formatPatchMetaLine(line, theme)) as any);
       continue;
     }
     if (line === "anchors:") {
       flush();
-      parent.addChild(createSingleLineComponent(theme.fg("accent", line)) as any);
+      parent.addChild(createSingleLineComponent(formatPatchMetaLine(line, theme)) as any);
       continue;
     }
     if (line.startsWith("  - ")) {
       flush();
-      parent.addChild(createSingleLineComponent(theme.fg("accent", line)) as any);
+      parent.addChild(createSingleLineComponent(formatPatchMetaLine(line, theme)) as any);
       continue;
     }
     buffer.push(line);
@@ -219,7 +328,7 @@ function appendPatchDiffChildren(parent: Box, body: string, theme: any): void {
   flush();
 }
 
-function buildPatchCallComponent(component: PatchCallComponent, args: any, theme: any, expanded = false) {
+export function buildPatchCallComponent(component: PatchCallComponent, args: any, theme: any, expanded = false) {
   component.setBgFn(getPatchHeaderBg(component, theme));
   component.clear();
 
@@ -255,13 +364,19 @@ function buildPatchCallComponent(component: PatchCallComponent, args: any, theme
   const FOLD_THRESHOLD = 45;
 
   component.addChild(new Spacer(1));
+  const isOverwrite = "isOverwrite" in preview && preview.isOverwrite;
+
   if (lines.length > FOLD_THRESHOLD && !expanded) {
     // 折叠态: 显示前几行 + 摘要
-    const shown = lines.slice(0, 10).join("\n");
-    const isOverwrite = "isOverwrite" in preview && preview.isOverwrite;
     if (isOverwrite) {
-      component.addChild(new Text(theme.fg("toolDiffAdded", shown), 0, 0));
+      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);
     }
     component.addChild(new Text(
@@ -270,9 +385,12 @@ function buildPatchCallComponent(component: PatchCallComponent, args: any, theme
     ));
   } else {
     // 展开态: 完整显示
-    const isOverwrite = "isOverwrite" in preview && preview.isOverwrite;
     if (isOverwrite) {
-      component.addChild(new Text(theme.fg("toolDiffAdded", body), 0, 0));
+      if (component.overwriteHighlightCache) {
+        addHighlightedContent(component, component.overwriteHighlightCache.highlightedLines);
+      } else {
+        component.addChild(new Text(theme.fg("toolDiffAdded", body), 0, 0));
+      }
     } else {
       appendPatchDiffChildren(component, body, theme);
     }
@@ -284,10 +402,14 @@ function buildPatchCallComponent(component: PatchCallComponent, args: any, theme
 // ─── Setup ──────────────────────────────────────────────────────────────────────────
 
 export function setupIO(pi: ExtensionAPI) {
-  pi.on("session_start", () => {
-    clearReadMarkers();
+  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"].includes(t)));
+    pi.setActiveTools(active.filter(t => !["edit", "write", "grep", "find", "ls"].includes(t)));
+  });
+
+  pi.on("session_compact", () => {
+    clearReadMarkers();
   });
 
   // Track file read times
@@ -298,24 +420,28 @@ export function setupIO(pi: ExtensionAPI) {
     const cwd: string = ctx.cwd ?? process.cwd();
     const absPath = resolveAbsolutePath(cwd, filePath);
     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 optional anchor to narrow search.",
+      "Edits a file using exact string replacement, with anchor support and overwrite mode.",
       "When old_str is not unique, add more surrounding context or use anchor to narrow search.",
-      "If possible, prefer anchor for more robust edits. Anchor must be a unique string that appears BEFORE old_str in the file.",
       "",
       "Examples:",
-      '  { path: "src/foo.ts", edits: [{ anchor: "function bar() {", old_str: "return x", new_str: "return y" }] }',
       '  { 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 examples (provide enough context to make it unique):",
-      '  prefer "function foo()" over "foo".',
-      '  prefer "class Foo" over "Foo".',
-      '  prefer "## Section Title" in md file edits.',
+      "",
+      "Anchor (optional): narrows old_str search to lines after a unique marker.",
+      "  Code: use the enclosing definition — function/class/struct/method signature.",
+      '  e.g. "function handleClick() {" or "class UserService {" or "struct Config {".',
+      "  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.",
     promptGuidelines: [
@@ -341,6 +467,8 @@ export function setupIO(pi: ExtensionAPI) {
       for (const filePath of [...result.modified, ...result.created]) {
         const absPath = resolveAbsolutePath(cwd, filePath);
         recordReadTime(absPath);
+        const marker = createFileTimeMarkerData(cwd, absPath);
+        if (marker) pi.appendEntry(FILE_TIMES_CUSTOM_TYPE, marker);
       }
 
       const summary = formatPatchResult(result);
@@ -361,16 +489,34 @@ export function setupIO(pi: ExtensionAPI) {
         component.previewArgsKey = argsKey;
         component.previewPending = false;
         component.settledError = false;
+        component.overwriteHighlightCache = undefined;
       }
 
-      if (context.argsComplete && !component.preview && !component.previewPending) {
-        component.previewPending = true;
-        void computePatchPreview(args, context.cwd).then((preview: any) => {
-          component.preview = preview;
-          context.invalidate();
-        });
+      // 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.
+      // Skipping async preview here avoids a redundant file read — same design as
+      // Pi's native edit tool where renderResult overwrites the preview with execute's diff.
+
       return buildPatchCallComponent(component, args, theme, context.expanded);
     },
 
@@ -379,10 +525,42 @@ 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 };
+            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;
+            }
+          }
+        }
+
+        // 更新错误状态
         if (callComponent.settledError !== context.isError) {
           callComponent.settledError = context.isError;
           changed = true;
         }
+
         if (changed) {
           buildPatchCallComponent(callComponent, context.args, theme, options.expanded);
           if (context.isError) {
@@ -398,6 +576,9 @@ export function setupIO(pi: ExtensionAPI) {
         }
       }
 
+      // Return empty Container — the Box (callComponent) already holds all content.
+      // Per pitfall #4: returning the Box would cause ToolExecutionComponent to add
+      // it twice to the container, producing duplicate rendering.
       const component = context.lastComponent ?? new Container();
       component.clear();
       return component;