pi-readseek 0.3.23 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {

package/src/edit.ts

@@ -20,9 +20,10 @@ import { resolveSyntaxValidateMode, type SyntaxValidateOptions } from "./syntax-
 import { replaceSymbol } from "./replace-symbol.js";
 import { buildEditPreviewKey, buildPendingEditPreviewData, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { buildDiffData, type DiffBlockRange } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FreshAnchorsPredicate } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { resolveEditDiffDisplay } from "./readseek-settings.js";
 
@@ -566,22 +567,17 @@ export async function executeEdit(opts: ExecuteEditOptions): Promise<any> {
 
 
 export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "mutating" as const,
-		readOnly: false,
+	const tool = registerReadseekTool(pi, {
+		policy: "mutating",
 		pythonName: "edit",
-		defaultExposure: "not-safe-by-default" as const,
-	};
-	const tool = {
+		defaultExposure: "not-safe-by-default",
+	}, {
 		name: "edit",
 		label: "Edit",
 		description: EDIT_PROMPT_METADATA.description,
 		promptSnippet: EDIT_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: EDIT_PROMPT_METADATA.promptGuidelines,
 		parameters: hashlineEditSchema,
-		ptc: toolConfig,
 		renderShell: "default" as const,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			return executeEdit({
@@ -645,7 +641,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			const { isPartial, isError, expanded: baseExpanded, width, context } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) {
-				return new Text(clampLinesToWidth([summaryLine("pending edit")], width).join("\n"), 0, 0);
+				return renderPendingResult("pending edit", width);
 			}
 
 			// Extract data from result
@@ -698,8 +694,6 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/grep.ts

@@ -17,8 +17,9 @@ import { throwIfAborted } from "./runtime.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
@@ -508,21 +509,15 @@ export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
 }
 
 export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "grep",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "grep",
 		label: "grep",
 		description: GREP_PROMPT_METADATA.description,
 		parameters: grepSchema,
-		ptc: toolConfig,
 		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
 		promptGuidelines: options.searchGuideline
 			? [GREP_PROMPT_METADATA.promptGuidelines[0], options.searchGuideline]
@@ -558,16 +553,12 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending search", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 
-			if (isError || result.isError) {
-				const firstLine = textContent.split("\n")[0] || "Error";
-				const body = expanded && textContent ? textContent : firstLine;
-				return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-			}
+			if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
 			const readseekValue = (result.details as any)?.readseekValue as {
 				tool: "grep";
@@ -607,8 +598,6 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 			}
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/read.ts

@@ -26,8 +26,9 @@ import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { readseekRead } from "./readseek-client.js";
 import { Text } from "@earendil-works/pi-tui";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidth } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const READ_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/read.md", import.meta.url),
@@ -423,16 +424,11 @@ function splitReadseekLines(text: string): string[] {
 }
 
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
+	const tool = registerReadseekTool(pi, {
+		policy: "read-only",
 		pythonName: "read",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
+		defaultExposure: "safe-by-default",
+	}, {
 		name: "read",
 		label: "Read",
 		description: READ_PROMPT_METADATA.description,
@@ -460,7 +456,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				}),
 			),
 		}),
-		ptc: toolConfig,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			return executeRead({
 				toolCallId,
@@ -489,7 +484,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
-			if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending read")], width).join("\n"), 0, 0);
+			if (isPartial) return renderPendingResult("pending read", width);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
@@ -516,8 +511,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidth(textContent, width);
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
-	} satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-	pi.registerTool(tool);
+	});
 	return tool;
 }

package/src/readseek-client.ts

@@ -203,6 +203,28 @@ export function isReadseekAvailable(): boolean {
 	}
 }
 
+export interface ReadseekFailure {
+	code: "readseek-not-installed" | "readseek-execution-error";
+	message: string;
+	hint?: string;
+}
+
+/**
+ * Classify an error thrown while invoking readseek into the shared failure
+ * taxonomy: a missing binary or package (`readseek-not-installed`, with an
+ * install hint) versus any other execution error.
+ */
+export function classifyReadseekFailure(err: unknown): ReadseekFailure {
+	const message = String((err as { message?: unknown } | null)?.message || err);
+	const missing =
+		(err as { code?: unknown } | null)?.code === "ENOENT" ||
+		/Cannot find package|Cannot find module|no such file/i.test(message);
+	if (missing) {
+		return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
+	}
+	return { code: "readseek-execution-error", message };
+}
+
 function directoryExists(dirPath: string): boolean {
 	try {
 		return statSync(dirPath).isDirectory();

package/src/refs.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekRefs, type ReadseekReference } from "./readseek-client.js";
+import { classifyReadseekFailure, readseekRefs, type ReadseekReference } from "./readseek-client.js";
 import { buildRefsOutput, type RefsOutputFile, type RefsOutputLine } from "./refs-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -29,10 +30,6 @@ const REFS_PROMPT_METADATA = defineToolPromptMetadata({
   promptSnippet: "Find references to an identifier with readseek and return edit-ready anchors",
 });
 
-export function isRefsAvailable(): boolean {
-  return isReadseekAvailable();
-}
-
 interface RefsToolOptions {
   onFileAnchored?: FileAnchoredCallback;
 }
@@ -127,28 +124,17 @@ export async function executeRefs(opts: ExecuteRefsOptions): Promise<any> {
       details: { readseekValue: builtOutput.readseekValue },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "refs",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    return buildToolErrorResult("refs", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "refs",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "refs",
     label: "References",
     description: REFS_PROMPT_METADATA.description,
@@ -165,7 +151,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeRefs({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -186,8 +171,6 @@ export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}
         unitPlural: "references",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/register-tool.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type ReadseekToolPolicy = "read-only" | "mutating";
+
+export type ReadseekToolExposure = "safe-by-default" | "opt-in" | "not-safe-by-default";
+
+/**
+ * Per-tool fields of the pi tool config (`ptc`) that genuinely differ between
+ * readseek tools. The remaining fields are constant or derived.
+ */
+export interface ReadseekToolConfig {
+  policy: ReadseekToolPolicy;
+  pythonName: string;
+  defaultExposure: ReadseekToolExposure;
+}
+
+export interface ReadseekToolPtc extends ReadseekToolConfig {
+  callable: true;
+  enabled: true;
+  readOnly: boolean;
+}
+
+type ToolSpec = Parameters<ExtensionAPI["registerTool"]>[0];
+
+/**
+ * Attach the standard `ptc` envelope to a tool definition and register it.
+ *
+ * `callable` and `enabled` are always true and `readOnly` is derived from
+ * `policy`, so callers supply only the fields that vary between tools.
+ */
+export function registerReadseekTool<T extends ToolSpec>(
+  pi: ExtensionAPI,
+  config: ReadseekToolConfig,
+  tool: T,
+): T & { ptc: ReadseekToolPtc } {
+  const ptc: ReadseekToolPtc = {
+    callable: true,
+    enabled: true,
+    policy: config.policy,
+    readOnly: config.policy === "read-only",
+    pythonName: config.pythonName,
+    defaultExposure: config.defaultExposure,
+  };
+  const registered = { ...tool, ptc };
+  pi.registerTool(registered);
+  return registered;
+}

package/src/sg.ts

@@ -6,9 +6,10 @@ import { stat as fsStat } from "node:fs/promises";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildReadseekLineWithHash, buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
 import { resolveToCwd } from "./path-utils.js";
-import { isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
+import { classifyReadseekFailure, isReadseekAvailable, readseekSearch, type ReadseekHashline, type ReadseekSearchFileOutput } from "./readseek-client.js";
 import { buildSgOutput } from "./sg-output.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 import { clampLineToWidth, renderAnchoredFilesResult, renderToolLabel } from "./tui-render-utils.js";
 
@@ -193,28 +194,17 @@ export async function executeSg(opts: ExecuteSgOptions): Promise<any> {
       },
     };
   } catch (err: any) {
-    const message = String(err?.message || err);
-    const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
-    return buildToolErrorResult(
-      "search",
-      missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
-      message,
-      missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
-    );
+    const failure = classifyReadseekFailure(err);
+    return buildToolErrorResult("search", failure.code, failure.message, failure.hint ? { hint: failure.hint } : {});
   }
 }
 
 export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "read-only" as const,
-    readOnly: true,
+  const tool = registerReadseekTool(pi, {
+    policy: "read-only",
     pythonName: "search",
-    defaultExposure: "opt-in" as const,
-  };
-
-  const tool = {
+    defaultExposure: "opt-in",
+  }, {
     name: "search",
     label: "Structural Search",
     description: SG_PROMPT_METADATA.description,
@@ -228,7 +218,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
       others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
       ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
     }),
-    ptc: toolConfig,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       return executeSg({ params, signal, cwd: ctx.cwd, onFileAnchored: options.onFileAnchored });
     },
@@ -249,8 +238,6 @@ export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
         unitPlural: "matches",
       });
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-
-  pi.registerTool(tool);
+  });
   return tool;
 }

package/src/tui-render-utils.ts

@@ -156,6 +156,27 @@ export function wrapReadHashlinesForWidth(text: string, width: number | undefine
   return output.join("\n");
 }
 
+/**
+ * Render the `isPartial` placeholder line shared by every tool's `renderResult`.
+ */
+export function renderPendingResult(pendingLabel: string, width: number | undefined): Text {
+  return new Text(clampLinesToWidth([summaryLine(pendingLabel)], width).join("\n"), 0, 0);
+}
+
+/**
+ * Render a tool result error: the first line of `textContent`, or its full body
+ * when expanded, prefixed and clamped to width. Tools pass their own `fallback`
+ * for the empty-content case.
+ */
+export function renderErrorResult(
+  textContent: string,
+  options: { expanded: boolean; width: number | undefined; fallback?: string },
+): Text {
+  const firstLine = textContent.split("\n")[0] || (options.fallback ?? "Error");
+  const body = options.expanded && textContent ? textContent : firstLine;
+  return new Text(clampLinesToWidth(summaryLine(body).split("\n"), options.width).join("\n"), 0, 0);
+}
+
 export interface AnchoredFilesLabels {
   pendingLabel: string;
   emptyLabel: string;
@@ -178,15 +199,11 @@ export function renderAnchoredFilesResult(
 ): Text {
   const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-  if (isPartial) return new Text(clampLinesToWidth([summaryLine(labels.pendingLabel)], width).join("\n"), 0, 0);
+  if (isPartial) return renderPendingResult(labels.pendingLabel, width);
 
   const content = result.content?.[0];
   const textContent = content?.type === "text" ? content.text : "";
-  if (isError || result.isError) {
-    const firstLine = textContent.split("\n")[0] || "Error";
-    const body = expanded && textContent ? textContent : firstLine;
-    return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
-  }
+  if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
 
   const readseekValue = (result.details as any)?.readseekValue as
     | { files: Array<{ path: string; lines: any[] }> }

package/src/write.ts

@@ -14,9 +14,10 @@ import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { buildPendingWritePreviewData, buildWritePreviewKey, resolvePendingDiffPreview, type PendingDiffPreviewResult } from "./pending-diff-preview.js";
 import { generateCompactOrFullDiff, normalizeToLF, hasBareCarriageReturn } from "./edit-diff.js";
 import { buildDiffData, type DiffData } from "./diff-data.js";
-import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, linkToolPath, renderErrorResult, renderToolLabel, summaryLine } from "./tui-render-utils.js";
 import { DiffPreviewComponent } from "./tui-diff-component.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
+import { registerReadseekTool } from "./register-tool.js";
 
 const WRITE_PENDING_PREVIEW_STATE_KEY = "hashline-write-pending-preview";
 
@@ -169,6 +170,30 @@ function mapFsWriteError(err: any, path: string): MappedFsError {
   };
 }
 
+function buildWriteFsErrorResult(err: any, absolutePath: string) {
+  const mapped = mapFsWriteError(err, absolutePath);
+  return {
+    content: [{ type: "text" as const, text: mapped.message }],
+    isError: true,
+    details: {
+      readseekValue: {
+        tool: "write" as const,
+        path: absolutePath,
+        lines: [] as ReadseekLine[],
+        warnings: [] as ReadseekWarning[],
+        ok: false,
+        error: buildReadseekError(
+          mapped.code,
+          mapped.message,
+          undefined,
+          mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
+        ),
+      },
+      warnings: [] as string[],
+    },
+  };
+}
+
 export async function executeWrite(opts: {
   path: string;
   content: string;
@@ -301,21 +326,16 @@ export async function executeWrite(opts: {
 }
 
 export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions = {}) {
-  const toolConfig = {
-    callable: true,
-    enabled: true,
-    policy: "mutating" as const,
-    readOnly: false,
+  const tool = registerReadseekTool(pi, {
+    policy: "mutating",
     pythonName: "write",
-    defaultExposure: "not-safe-by-default" as const,
-  };
-  const tool = {
+    defaultExposure: "not-safe-by-default",
+  }, {
     name: "write",
     label: "write",
     description: WRITE_PROMPT_METADATA.description,
     promptSnippet: WRITE_PROMPT_METADATA.promptSnippet,
     promptGuidelines: WRITE_PROMPT_METADATA.promptGuidelines,
-    ptc: toolConfig,
     parameters: Type.Object({
       path: Type.String({ description: "File path" }),
       content: Type.String({ description: "File content" }),
@@ -325,112 +345,72 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const cwd = ctx?.cwd ?? process.cwd();
       const absolutePath = resolveToCwd(params.path, cwd);
       try {
-      return await withFileMutationQueue(absolutePath, async () => {
-      let result: WriteResult;
-      try {
-        result = await executeWrite({
-          path: absolutePath,
-          content: params.content,
-          map: params.map,
-          cwd,
-        });
-      } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
+        return await withFileMutationQueue(absolutePath, async () => {
+          let result: WriteResult;
+          try {
+            result = await executeWrite({
               path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
-            },
-            warnings: [] as string[],
-          },
-        };
-      }
+              content: params.content,
+              map: params.map,
+              cwd,
+            });
+          } catch (err: any) {
+            return buildWriteFsErrorResult(err, absolutePath);
+          }
 
-      if (result.readseekValue.lines.length > 0) {
-        options.onFileAnchored?.(absolutePath);
-      }
+          if (result.readseekValue.lines.length > 0) {
+            options.onFileAnchored?.(absolutePath);
+          }
 
-      // Lift binary-content signal into a fatal readseekValue.error envelope so
-      // downstream consumers get the same taxonomy shape as every other tool.
-      // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
-      // backward compatibility (see AC 12 — warnings namespace alignment).
-      const binaryWarning = result.readseekValue.warnings.find((w) => w.code === "binary-content");
-      if (binaryWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("binary-content", binaryWarning.message),
-            },
-            warnings: result.warnings,
-          },
-        };
-      }
+          // Lift binary-content signal into a fatal readseekValue.error envelope so
+          // downstream consumers get the same taxonomy shape as every other tool.
+          // The existing ReadseekWarning entry is preserved on readseekValue.warnings for
+          // backward compatibility (see AC 12 — warnings namespace alignment).
+          const binaryWarning = result.readseekValue.warnings.find((w) => w.code === "binary-content");
+          if (binaryWarning) {
+            return {
+              content: [{ type: "text" as const, text: result.text }],
+              isError: true,
+              details: {
+                readseekValue: {
+                  ...result.readseekValue,
+                  ok: false,
+                  error: buildReadseekError("binary-content", binaryWarning.message),
+                },
+                warnings: result.warnings,
+              },
+            };
+          }
 
-      const bareCrWarning = result.readseekValue.warnings.find((w) => w.code === "bare-cr");
-      if (bareCrWarning) {
-        return {
-          content: [{ type: "text" as const, text: result.text }],
-          isError: true,
-          details: {
-            readseekValue: {
-              ...result.readseekValue,
-              ok: false,
-              error: buildReadseekError("bare-cr", bareCrWarning.message),
-            },
-            warnings: result.warnings,
-          },
-        };
-      }
+          const bareCrWarning = result.readseekValue.warnings.find((w) => w.code === "bare-cr");
+          if (bareCrWarning) {
+            return {
+              content: [{ type: "text" as const, text: result.text }],
+              isError: true,
+              details: {
+                readseekValue: {
+                  ...result.readseekValue,
+                  ok: false,
+                  error: buildReadseekError("bare-cr", bareCrWarning.message),
+                },
+                warnings: result.warnings,
+              },
+            };
+          }
 
-      return {
-        content: [{ type: "text" as const, text: result.text }],
-        details: {
-          ...(result.diff !== undefined ? { diff: result.diff } : {}),
-          ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
-          ...(result.writeState ? { writeState: result.writeState } : {}),
-          readseekValue: result.readseekValue,
-          warnings: result.warnings,
-        },
-      };
-      });
-      } catch (err: any) {
-        const mapped = mapFsWriteError(err, absolutePath);
-        return {
-          content: [{ type: "text" as const, text: mapped.message }],
-          isError: true,
-          details: {
-            readseekValue: {
-              tool: "write" as const,
-              path: absolutePath,
-              lines: [] as ReadseekLine[],
-              warnings: [] as ReadseekWarning[],
-              ok: false,
-              error: buildReadseekError(
-                mapped.code,
-                mapped.message,
-                undefined,
-                mapped.includeMeta ? { fsCode: err?.code, fsMessage: err?.message } : undefined,
-              ),
+          return {
+            content: [{ type: "text" as const, text: result.text }],
+            details: {
+              ...(result.diff !== undefined ? { diff: result.diff } : {}),
+              ...(result.diffData !== undefined ? { diffData: result.diffData } : {}),
+              ...(result.writeState ? { writeState: result.writeState } : {}),
+              readseekValue: result.readseekValue,
+              warnings: result.warnings,
             },
-            warnings: [] as string[],
-          },
-        };
+          };
+        });
+      } catch (err: any) {
+        return buildWriteFsErrorResult(err, absolutePath);
       }
     },
     renderCall(args: any, theme: any, context: any = {}) {
@@ -478,9 +458,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       const details = result.details ?? {};
       const output = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (result.isError || details.readseekValue?.ok === false) {
-        const firstLine = output.split("\n")[0] || "write failed";
-        const body = expanded && output ? output : firstLine;
-        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+        return renderErrorResult(output, { expanded, width, fallback: "write failed" });
       }
       const diffData = details.diffData;
       const state = details.writeState === "overwritten" ? "overwritten" : "created";
@@ -510,7 +488,6 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       }
       return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
     },
-  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
-  pi.registerTool(tool);
+  });
   return tool;
 }