pi-hashline-edit-pro 0.15.4 → 0.16.0

package/index.ts

@@ -4,6 +4,7 @@ import { join, isAbsolute } from "path";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
 import { regReplaceFlat } from "./src/replace-flat";
+import { regReplaceUndo } from "./src/replace-undo";
 import { regRead, fmtReadPreview } from "./src/read";
 import { toLF, stripBOM } from "./src/replace-diff";
 import { visLines } from "./src/utils";
@@ -22,7 +23,7 @@ export default function (pi: ExtensionAPI): void {
   // Register the bulk-mode replace tool by default. The session_start handler
   // will re-register with the correct mode from the persisted config.
   regReplace(pi);
-
+  regReplaceUndo(pi);
   const debugValue = process.env.PI_HASHLINE_DEBUG;
   // Initial auto-read from env var; session_start overrides with persisted value
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-bulk.md

@@ -94,9 +94,7 @@ Rules:
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
-
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
 Wrong: To replace lines 2-3 in this function:
@@ -129,3 +127,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace-flat.md

@@ -79,7 +79,8 @@ Rules:
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
 - The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
+- `hash_range_inclusive` and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as a proper array and array of strings respectively.
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
@@ -112,3 +113,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace.md

@@ -142,7 +142,8 @@ Rules:
 - All changes in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
 - If `content_lines` matches current content, the replace is classified as `noop` (file unchanged).
 - The `hash_range_inclusive` is inclusive — the entire span from the first anchor through the second anchor is deleted and replaced with `content_lines`. The old lines in that span are gone. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
-On success, the response text is empty (or contains only warnings if present). {{AUTO_READ_GUIDANCE}}
+- `changes` (in bulk mode), `hash_range_inclusive`, and `content_lines` must be native JSON values, not JSON strings. Do not serialize them — pass them as proper arrays and strings.
+On success, the response text shows the line change summary (e.g. "Added 3 line(s), removed 1 line(s).") plus any warnings if present. {{AUTO_READ_GUIDANCE}}
 
 ⚠️ Common mistake: `hash_range_inclusive` replaces the ENTIRE range. Every line from the first anchor through the second anchor is deleted and replaced with `content_lines`. Do not include "context" or "surrounding" lines in `content_lines` — they are outside the range and will be preserved automatically.
 
@@ -176,3 +177,5 @@ Error recovery:
 - `[E_BARE_HASH_PREFIX]` — a `content_lines` entry starts with `HASH│`. Remove the hash prefix; keep only the literal line content that appears after `│` in `read` output. `hash_range_inclusive` uses hashes, `content_lines` does not.
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
+
+**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/src/file-reader.ts

@@ -1,58 +1,60 @@
 import { constants } from "fs";
 import { lineHashes } from "./hashline";
 import { loadFileKindAndText, type LFile } from "./file-kind";
+import { resolveTarget } from "./fs-write";
 import { toCwd } from "./path-utils";
 import { detectEnding, toLF, stripBOM } from "./replace-diff";
 import { abortIf } from "./runtime";
 import { assertText, valAccess } from "./validation";
 
 export interface NormFile {
-	absolutePath: string;
-	normalized: string;
-	bom: string;
-	originalEnding: "\r\n" | "\n";
-	fileHashes: string[];
-	hadUtf8DecodeErrors: boolean;
+  absolutePath: string;
+  normalized: string;
+  bom: string;
+  originalEnding: "\r\n" | "\n";
+  fileHashes: string[];
+  hadUtf8DecodeErrors: boolean;
 }
 
 export async function readNormFile(
-	path: string,
-	cwd: string,
-	signal: AbortSignal | undefined,
-	accessMode: number = constants.R_OK,
-	preloadedFile?: LFile,
-	maxLines?: number,
+  path: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  accessMode: number = constants.R_OK,
+  preloadedFile?: LFile,
+  maxLines?: number,
 ): Promise<NormFile> {
-	const absolutePath = toCwd(path, cwd);
+  const absolutePath = toCwd(path, cwd);
+  const resolvedPath = await resolveTarget(absolutePath);
 
-	abortIf(signal);
-	await valAccess(absolutePath, path, accessMode);
+  abortIf(signal);
+  await valAccess(resolvedPath, path, accessMode);
 
-	abortIf(signal);
-	const file = preloadedFile ?? (await loadFileKindAndText(absolutePath));
-	assertText(file, path);
+  abortIf(signal);
+  const file = preloadedFile ?? (await loadFileKindAndText(resolvedPath));
+  assertText(file, path);
 
-	abortIf(signal);
-	const { bom, text: rawContent } = stripBOM(file.text);
-	const originalEnding = detectEnding(rawContent);
-	const normalized = toLF(rawContent);
+  abortIf(signal);
+  const { bom, text: rawContent } = stripBOM(file.text);
+  const originalEnding = detectEnding(rawContent);
+  const normalized = toLF(rawContent);
 
-	if (maxLines !== undefined) {
-		const lineCount = normalized.split("\n").length;
-		if (lineCount > maxLines) {
-			throw new Error(
-				`[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
-			);
-		}
-	}
+  if (maxLines !== undefined) {
+    const lineCount = normalized.split("\n").length;
+    if (lineCount > maxLines) {
+      throw new Error(
+        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+      );
+    }
+  }
 
-	const fileHashes = await lineHashes(normalized, absolutePath);
-	return {
-		absolutePath,
-		normalized,
-		bom,
-		originalEnding,
-		fileHashes,
-		hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
-	};
+  const fileHashes = await lineHashes(normalized, resolvedPath);
+  return {
+    absolutePath: resolvedPath,
+    normalized,
+    bom,
+    originalEnding,
+    fileHashes,
+    hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
+  };
 }

package/src/replace-flat.ts

@@ -1,313 +1,17 @@
-import { Markdown, Text } from "@earendil-works/pi-tui";
 import type {
   ExtensionAPI,
-  ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { constants } from "fs";
 import {
-  genDiff,
-  restoreEndings,
-} from "./replace-diff";
-import { readNormFile } from "./file-reader";
-import { normReq } from "./replace-normalize";
-import { isRec } from "./utils";
-import { MAX_HASH_LINES } from "./constants";
-import { resolveTarget, writeAtomic } from "./fs-write";
-import {
-  applyEdits,
-  resEdits,
-  type HTEdit,
-} from "./hashline";
-import { toCwd } from "./path-utils";
-import { abortIf } from "./runtime";
-import { fileSnap } from "./snapshot";
-import {
-  buildChanged,
-  buildNoop,
-  type RMeta,
-  type RMetrics,
-} from "./replace-response";
-import {
-  buildAppliedText,
-  mkMdTheme,
-  fmtCall,
-  fmtResultMd,
-  getPreviewInput,
-  getResultText,
-  isApplied,
-  type RPreview,
-  type RRState,
-} from "./replace-render";
-import { loadP, loadGuide } from "./prompts";
-import { execPipeline, compPreview, type ReplaceDetails } from "./replace";
-import { readAutoReadSync } from "./config";
-
-const contentLinesSchema = Type.Array(Type.String(), {
-  description:
-    "literal replacement file content, one string per line. Must not include the HASH│ prefix from read output.",
-});
-
-const hashRangeInclSchema = Type.Array(
-  Type.String({ description: "anchor (3-char HASH)" }),
-  {
-    description: "inclusive hash range to replace [start_hash, end_hash]. Each element must be the 3-character hash anchor only; do not include the │ separator or line content.",
-    minItems: 2,
-    maxItems: 2,
-  },
-);
-
-/**
- * Flat-mode schema: hash_range_inclusive and content_lines are at the top
- * level instead of inside a "changes" array. Only a single edit is supported
- * per call (no bulk changes).
- */
-export const flatEditToolSchema = Type.Object(
-  {
-    path: Type.String({ description: "path" }),
-    hash_range_inclusive: hashRangeInclSchema,
-    content_lines: contentLinesSchema,
-  },
-  { additionalProperties: false },
-);
-
-type ToolDef = ToolDefinition<
-  typeof flatEditToolSchema,
-  ReplaceDetails,
-  RRState
-> & { renderShell?: "default" | "self" };
-
-function reuseText(context: any, content: string): Text {
-  const t = context.lastComponent instanceof Text
-    ? context.lastComponent
-    : new Text("", 0, 0);
-  t.setText(content);
-  return t;
-}
-
-function reuseMarkdown(context: any, content: string, theme: any): Markdown {
-  const m = context.lastComponent instanceof Markdown
-    ? context.lastComponent
-    : new Markdown("", 0, 0, mkMdTheme(theme));
-  m.setText(content);
-  return m;
-}
-
-export function buildToolDef(): ToolDef {
-  const autoRead = readAutoReadSync();
-  const readGuidance = autoRead
-    ? "Anchors are provided automatically after write operations when auto-read is enabled."
-    : "Call `read` to get fresh anchors for follow-up edits.";
-
-  const E_DESC = loadP("../prompts/replace-flat.md", {
-    AUTO_READ_GUIDANCE: readGuidance,
-  });
-  const E_SNIPPET = loadP("../prompts/replace-flat-snippet.md");
-  const E_GUIDE = loadGuide("../prompts/replace-flat-guidelines.md", {
-    AUTO_READ_GUIDANCE: readGuidance,
-  });
-
-  return {
-    name: "replace",
-    label: "Replace",
-    description: E_DESC,
-    parameters: flatEditToolSchema,
-    promptSnippet: E_SNIPPET,
-    promptGuidelines: E_GUIDE,
-    prepareArguments: (args: unknown) => {
-      // Minimal normalization: file_path → path, JSON string parsing.
-      // The flat-to-canonical conversion happens in execute().
-      if (!isRec(args)) return args as any;
-      const record = { ...args };
-      if (typeof record.path !== "string" && typeof record.file_path === "string") {
-        record.path = record.file_path;
-        delete record.file_path;
-      }
-      if (typeof record.hash_range_inclusive === "string") {
-        try { record.hash_range_inclusive = JSON.parse(record.hash_range_inclusive as string); } catch { /* keep as-is */ }
-      }
-      if (typeof record.content_lines === "string") {
-        try { record.content_lines = JSON.parse(record.content_lines as string); } catch { /* keep as-is */ }
-      }
-      return record as any;
-    },
-    renderShell: "default",
-    renderCall(args, theme, context) {
-      const previewInput = getPreviewInput(args);
-      if (context.executionStarted) {
-        context.state.argsKey = undefined;
-        context.state.preview = undefined;
-        context.state.previewGeneration =
-          (context.state.previewGeneration ?? 0) + 1;
-      } else if (!context.argsComplete || !previewInput) {
-        context.state.argsKey = undefined;
-        context.state.preview = undefined;
-        context.state.previewGeneration =
-          (context.state.previewGeneration ?? 0) + 1;
-      } else {
-        const argsKey = JSON.stringify(previewInput);
-        if (context.state.argsKey !== argsKey) {
-          context.state.argsKey = argsKey;
-          context.state.preview = undefined;
-          const previewGeneration = (context.state.previewGeneration ?? 0) + 1;
-          context.state.previewGeneration = previewGeneration;
-          compPreview(previewInput, context.cwd)
-            .then((preview) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = preview;
-                context.invalidate();
-              }
-            })
-            .catch((err: unknown) => {
-              if (
-                context.state.argsKey === argsKey &&
-                context.state.previewGeneration === previewGeneration
-              ) {
-                context.state.preview = {
-                  error: err instanceof Error ? err.message : String(err),
-                };
-                context.invalidate();
-              }
-            });
-        }
-      }
-      const text =
-        (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-      text.setText(
-        fmtCall(
-          getPreviewInput(args) ?? undefined,
-          context.state as RRState,
-          context.expanded,
-          theme,
-        ),
-      );
-      return text;
-    },
-
-    renderResult(result, { isPartial }, theme, context) {
-      if (isPartial) {
-        return reuseText(context, theme.fg("warning", "Editing..."));
-      }
-
-      const typedResult = result as {
-        content?: Array<{ type: string; text?: string }>;
-        details?: ReplaceDetails;
-      };
-      const renderedText = getResultText(typedResult);
-
-      const renderState = context.state as RRState | undefined;
-      if (renderState) {
-        renderState.preview = undefined;
-        renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
-      }
-
-      if (context.isError) {
-        return renderedText
-          ? reuseText(context, `\n${theme.fg("error", renderedText)}`)
-          : new Text("", 0, 0);
-      }
-
-      if (isApplied(typedResult.details)) {
-        const appliedText = buildAppliedText(renderedText, typedResult.details, theme);
-        return appliedText ? reuseText(context, appliedText) : new Text("", 0, 0);
-      }
-
-      if (!renderedText) return new Text("", 0, 0);
-      return reuseMarkdown(context, fmtResultMd(renderedText), theme);
-    },
-
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      // Wrap flat params into canonical shape for the pipeline
-      const canonical = normReq({
-        path: params.path,
-        changes: [{
-          hash_range_inclusive: params.hash_range_inclusive,
-          content_lines: params.content_lines,
-        }],
-      });
-      const normalizedParams = canonical as { path: string; changes: HTEdit[] };
-      const path = normalizedParams.path;
-      const absolutePath = toCwd(path, ctx.cwd);
-      const mutationTargetPath = await resolveTarget(absolutePath);
-      return withFileMutationQueue(mutationTargetPath, async () => {
-        abortIf(signal);
-
-        const {
-          originalNormalized,
-          originalHashes,
-          result,
-          bom,
-          originalEnding,
-          hadUtf8DecodeErrors,
-          warnings,
-          noopEdits,
-          firstChangedLine,
-          lastChangedLine,
-          resultHashes,
-        } = await execPipeline(
-          normalizedParams,
-          ctx.cwd,
-          constants.R_OK | constants.W_OK,
-          signal,
-        );
-
-        const editsAttempted = 1; // flat mode: exactly one edit per call
-
-        if (originalNormalized === result) {
-          const noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;
-          return buildNoop({
-            path,
-            noopEdits,
-            snapshotId: noopSnapshotId,
-            editMeta: {
-              editsAttempted,
-              noopEditsCount: noopEdits?.length ?? 0,
-            },
-            warnings,
-          });
-        }
-
-        if (hadUtf8DecodeErrors) {
-          warnings.push(
-            "Non-UTF-8 bytes were shown as U+FFFD; this edit rewrote the file as UTF-8.",
-          );
-        }
-
-        abortIf(signal);
-        await writeAtomic(
-          absolutePath,
-          bom + restoreEndings(result, originalEnding),
-        );
-        const updatedSnapshotId = (await fileSnap(absolutePath))
-          .snapshotId;
+  buildToolDef,
+  flatEditToolSchema,
+} from "./replace";
 
-        const editMeta: RMeta = {
-          editsAttempted,
-          noopEditsCount: noopEdits?.length ?? 0,
-          firstChangedLine,
-          lastChangedLine,
-        };
+export { flatEditToolSchema };
 
-        const successInput = {
-          path,
-          originalNormalized,
-          originalHashes,
-          result,
-          resultHashes,
-          warnings,
-          snapshotId: updatedSnapshotId,
-          editMeta,
-        };
-        return buildChanged(successInput);
-      });
-    },
-  };
+export function buildToolDefFlat() {
+  return buildToolDef({ flat: true });
 }
 
 export function regReplaceFlat(pi: ExtensionAPI): void {
-  pi.registerTool(buildToolDef());
+  pi.registerTool(buildToolDef({ flat: true }));
 }

package/src/replace-normalize.ts

@@ -13,34 +13,56 @@ function tryParseJSON<T>(value: unknown, guard: (v: unknown) => v is T): T | und
  * Coerces an array of edit items: JSON-string items → objects,
  * JSON-string content_lines → string arrays. Shared by the `changes`
  * and `edits` normalization branches.
+ * Returns a warning if any item was a JSON string.
  */
-function coerceEditArray(items: unknown[]): unknown[] {
-  return items
-    .map((item: unknown) => tryParseJSON(item, isRec) ?? item)
+function coerceEditArray(items: unknown[]): { result: unknown[]; warnings: string[] } {
+  const warnings: string[] = [];
+  const result = items
+    .map((item: unknown) => {
+      if (typeof item === "string") {
+        const parsed = tryParseJSON(item, isRec);
+        if (parsed) {
+          warnings.push("Edit item was passed as a JSON string instead of a native object. Use native JSON values, not serialized strings.");
+          return parsed;
+        }
+      }
+      return item;
+    })
     .map((change: unknown) => {
       if (!isRec(change)) return change;
       if (typeof change.content_lines !== "string") return change;
       const parsed = tryParseJSON(change.content_lines, (v): v is string[] =>
         Array.isArray(v) && v.every((i) => typeof i === "string"),
       );
-      return parsed ? { ...change, content_lines: parsed } : change;
+      if (parsed) {
+        warnings.push("content_lines was passed as a JSON string inside an edit item. Use a native array of strings.");
+        return { ...change, content_lines: parsed };
+      }
+      return change;
     });
+  return { result, warnings };
 }
 
 /**
  * Normalizes a field from `from` to `to`: JSON-string arrays → real arrays,
  * single objects → wrapped in array. Shared by the `changes` and `edits`
  * normalization branches.
+ * Returns a warning if the field was a JSON string.
  */
 function normalizeField(
   record: Record<string, unknown>,
   from: string,
   to: string,
-): void {
-  if (!has(record, from)) return;
+): string | undefined {
+  if (!has(record, from)) return undefined;
   const raw = tryParseJSON(record[from], Array.isArray) ?? record[from];
+  const wasString = typeof record[from] === "string" && raw !== record[from];
   if (Array.isArray(raw)) {
-    record[to] = coerceEditArray(raw);
+    const { result, warnings } = coerceEditArray(raw);
+    record[to] = result;
+    if (warnings.length > 0) {
+      return warnings.join(" ");
+    }
   } else {
     const single =
       typeof raw === "string"
@@ -48,9 +70,19 @@ function normalizeField(
         : isRec(raw)
           ? raw
           : undefined;
-    if (single) record[to] = coerceEditArray([single]);
+    if (single) {
+      const { result, warnings } = coerceEditArray([single]);
+      record[to] = result;
+      if (warnings.length > 0) {
+        return warnings.join(" ");
+      }
+    }
   }
   if (from !== to) delete record[from];
+  if (wasString) {
+    return `Field "${from}" was passed as a JSON string instead of a native array. Use native JSON values, not serialized strings.`;
+  }
+  return undefined;
 }
 
 export function normReq(input: unknown): unknown {
@@ -59,25 +91,36 @@ export function normReq(input: unknown): unknown {
   }
 
   const record: Record<string, unknown> = { ...input };
+  const warnings: string[] = [];
 
   if (typeof record.path !== "string" && typeof record.file_path === "string") {
     record.path = record.file_path;
     delete record.file_path;
   }
 
-  normalizeField(record, "changes", "changes");
-  normalizeField(record, "edits", "changes");
+  const w1 = normalizeField(record, "changes", "changes");
+  if (w1) warnings.push(w1);
+  const w2 = normalizeField(record, "edits", "changes");
+  if (w2) warnings.push(w2);
 
   // Handle flat format: hash_range_inclusive and content_lines at top level
   // (no changes array). Wrap them into a single-element changes array.
   if (!Array.isArray(record.changes) && has(record, "hash_range_inclusive") && has(record, "content_lines")) {
-    const hri = tryParseJSON(record.hash_range_inclusive, (v): v is string[] =>
+    const hriRaw = record.hash_range_inclusive;
+    const hri = tryParseJSON(hriRaw, (v): v is string[] =>
       Array.isArray(v) && v.length === 2 && v.every((i) => typeof i === "string")
-    ) ?? record.hash_range_inclusive;
+    ) ?? hriRaw;
+    if (typeof hriRaw === "string" && hri !== hriRaw) {
+      warnings.push("hash_range_inclusive was passed as a JSON string instead of a native array. Use native JSON values.");
+    }
 
-    const cl = tryParseJSON(record.content_lines, (v): v is string[] =>
+    const clRaw = record.content_lines;
+    const cl = tryParseJSON(clRaw, (v): v is string[] =>
       Array.isArray(v) && v.every((i) => typeof i === "string")
-    ) ?? record.content_lines;
+    ) ?? clRaw;
+    if (typeof clRaw === "string" && cl !== clRaw) {
+      warnings.push("content_lines was passed as a JSON string instead of a native array. Use native JSON values.");
+    }
 
     if (Array.isArray(hri) && Array.isArray(cl)) {
       record.changes = [{ hash_range_inclusive: hri, content_lines: cl }];
@@ -86,6 +129,9 @@ export function normReq(input: unknown): unknown {
     }
   }
 
+  if (warnings.length > 0) {
+    (record as Record<string, unknown>)._normWarnings = warnings;
+  }
+
   return record;
 }
-

package/src/replace-response.ts

@@ -148,11 +148,14 @@ export function buildChanged(input: SuccessInput): TResult {
   const removedLines = cntDiff(diffResult.diff, "-");
   const warningsBlock = warnBlock(warnings);
   const successPrefix = `Successfully replaced in ${path}.`;
+  const lineSummary = addedLines > 0 || removedLines > 0
+    ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
+    : "";
   const text = resultLines.length === 0
     ? "File is empty. Use replace to insert content."
     : warningsBlock
-      ? `${successPrefix}${warningsBlock}`
-      : successPrefix;
+      ? `${successPrefix}${lineSummary}${warningsBlock}`
+      : `${successPrefix}${lineSummary}`;
 
   const metrics = buildM({
     classification: "applied",

package/src/replace-undo.ts

@@ -0,0 +1,122 @@
+import { readFile } from "fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { getUndo, clearUndo } from "./undo-store";
+import { loadHashStore, saveHashStore } from "./hash-store";
+import { resolveTarget, writeAtomic } from "./fs-write";
+import { toCwd } from "./path-utils";
+import { toLF, stripBOM, genDiff, restoreEndings } from "./replace-diff";
+
+function cntDiff(diff: string, marker: "+" | "-"): number {
+  if (!diff) return 0;
+  let count = 0;
+  for (const line of diff.split("\n")) {
+    if (
+      line.startsWith(marker) &&
+      !line.startsWith(`${marker}${marker}${marker}`)
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function regReplaceUndo(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "last_replace_undo",
+    label: "Undo Last Replace",
+    description:
+      "Undo the last replace operation on a file, reverting it to its previous state. " +
+      "Use this when a replace produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). " +
+      "After undoing, call `read` to get fresh anchors for a corrected replace.",
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path to the file to undo the last replace on",
+      }),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const path = params.path;
+      const absolutePath = toCwd(path, ctx.cwd);
+      const mutationTargetPath = await resolveTarget(absolutePath);
+
+      const undo = getUndo(mutationTargetPath);
+      if (!undo) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No undo history for ${path}. There is no previous replace to revert.`,
+            },
+          ],
+          isError: true,
+          details: {},
+        };
+      }
+
+      return withFileMutationQueue(mutationTargetPath, async () => {
+        // Read current file content to compute diff against the pre-replace state
+        let currentNormalized = "";
+        try {
+          const currentRaw = await readFile(mutationTargetPath, "utf-8");
+          const { text: currentStripped } = stripBOM(currentRaw);
+          currentNormalized = toLF(currentStripped);
+        } catch {
+          // File may have been deleted; treat as empty
+          currentNormalized = "";
+        }
+
+        // Compute diff: old = pre-replace (undo.content), new = current
+        const diffResult = genDiff(undo.content, currentNormalized, 0);
+        const linesAddedByReplace = cntDiff(diffResult.diff, "+");
+        const linesRemovedByReplace = cntDiff(diffResult.diff, "-");
+
+        // Write the pre-edit content back to the file
+        await writeAtomic(
+          mutationTargetPath,
+          undo.bom + restoreEndings(undo.content, undo.originalEnding),
+        );
+
+        // Restore the hash store snapshot so the next read returns the same hashes
+        const store = await loadHashStore();
+        store.snapshots[mutationTargetPath] = {
+          content: undo.content,
+          hashes: undo.hashes,
+        };
+        await saveHashStore(store);
+
+        // Clear undo so a second call without an intervening replace is a no-op
+        clearUndo(mutationTargetPath);
+
+        const parts: string[] = [
+          `Undone last replace on ${path}.`,
+        ];
+        if (linesAddedByReplace > 0 || linesRemovedByReplace > 0) {
+          parts.push(
+            `Removed ${linesAddedByReplace} line(s) that were added and restored ${linesRemovedByReplace} line(s) that were removed.`,
+          );
+        }
+        parts.push(
+          "File reverted to previous state. Call `read` to get fresh anchors for follow-up edits.",
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: parts.join("\n"),
+            },
+          ],
+          details: {
+            metrics: {
+              added_lines: linesRemovedByReplace,
+              removed_lines: linesAddedByReplace,
+              classification: "applied" as const,
+            },
+          },
+        };
+      });
+    },
+  });
+}

package/src/replace.ts

@@ -44,6 +44,7 @@ import {
 } from "./replace-render";
 import { loadP, loadGuide } from "./prompts";
 import { readAutoReadSync } from "./config";
+import { saveUndo } from "./undo-store";
 
 const contentLinesSchema = Type.Array(Type.String(), {
   description:
@@ -75,6 +76,20 @@ export const editToolSchema = Type.Object(
   { additionalProperties: false },
 );
 
+/**
+ * Flat-mode schema: hash_range_inclusive and content_lines are at the top
+ * level instead of inside a "changes" array. Only a single edit is supported
+ * per call (no bulk changes).
+ */
+export const flatEditToolSchema = Type.Object(
+  {
+    path: Type.String({ description: "path" }),
+    hash_range_inclusive: hashRangeInclSchema,
+    content_lines: contentLinesSchema,
+  },
+  { additionalProperties: false },
+);
+
 export type ReqParams = {
   path: string;
   changes: HTEdit[];
@@ -154,6 +169,7 @@ export async function execPipeline(
   );
 
   const absolutePath = toCwd(path, cwd);
+  const resolvedPath = await resolveTarget(absolutePath);
   const resolved = resEdits(toolEdits);
   const anchorResult = applyEdits(
     originalNormalized,
@@ -165,15 +181,27 @@ export async function execPipeline(
 
   const result = anchorResult.content;
 
-  // Collect hashes targeted by the edit for hash-aware diff disambiguation
+  // Collect hashes targeted by the edit for hash-aware diff disambiguation.
+  // Include every hash in the replaced range, not just the boundary anchors,
+  // so that a surviving line whose content is identical to an interior line
+  // of the edit is not matched to a removed hash.
+  // Use originalHashes.indexOf to find line numbers since resEdits returns
+  // HEdit[] (Anchor = { hash }) not RHEdit[] (RAnchor = { line, hash }).
   const removedHashes = new Set<string>();
   for (const edit of resolved) {
-    removedHashes.add(edit.hash_range_inclusive[0].hash);
-    removedHashes.add(edit.hash_range_inclusive[1].hash);
+    const startHash = edit.hash_range_inclusive[0].hash;
+    const endHash = edit.hash_range_inclusive[1].hash;
+    const startLine = originalHashes.indexOf(startHash);
+    const endLine = originalHashes.indexOf(endHash);
+    if (startLine >= 0 && endLine >= 0) {
+      for (let i = startLine; i <= endLine; i++) {
+        removedHashes.add(originalHashes[i]!);
+      }
+    }
   }
 
   // Compute stable result hashes using hash-aware preservation
-  const resultHashes = await lineHashes(result, absolutePath, {
+  const resultHashes = await lineHashes(result, resolvedPath, {
     content: originalNormalized,
     hashes: originalHashes,
     removedHashes,
@@ -247,12 +275,12 @@ export async function compPreview(
 }
 
 type ToolDef = ToolDefinition<
-  typeof editToolSchema,
+  any,
   ReplaceDetails,
   RRState
 > & { renderShell?: "default" | "self" };
 
-function reuseText(context: any, content: string): Text {
+export function reuseText(context: any, content: string): Text {
   const t = context.lastComponent instanceof Text
     ? context.lastComponent
     : new Text("", 0, 0);
@@ -260,7 +288,7 @@ function reuseText(context: any, content: string): Text {
   return t;
 }
 
-function reuseMarkdown(context: any, content: string, theme: any): Markdown {
+export function reuseMarkdown(context: any, content: string, theme: any): Markdown {
   const m = context.lastComponent instanceof Markdown
     ? context.lastComponent
     : new Markdown("", 0, 0, mkMdTheme(theme));
@@ -268,29 +296,49 @@ function reuseMarkdown(context: any, content: string, theme: any): Markdown {
   return m;
 }
 
-export function buildToolDef(): ToolDef {
+export function buildToolDef(opts: { flat: boolean }): ToolDef {
   const autoRead = readAutoReadSync();
   const readGuidance = autoRead
     ? "Anchors are provided automatically after write operations when auto-read is enabled."
     : "Call `read` to get fresh anchors for follow-up edits.";
 
-  const E_DESC = loadP("../prompts/replace-bulk.md", {
+  const E_DESC = loadP(opts.flat ? "../prompts/replace-flat.md" : "../prompts/replace-bulk.md", {
     AUTO_READ_GUIDANCE: readGuidance,
   });
-  const E_SNIPPET = loadP("../prompts/replace-bulk-snippet.md");
-  const E_GUIDE = loadGuide("../prompts/replace-bulk-guidelines.md", {
+  const E_SNIPPET = loadP(opts.flat ? "../prompts/replace-flat-snippet.md" : "../prompts/replace-bulk-snippet.md");
+  const E_GUIDE = loadGuide(opts.flat ? "../prompts/replace-flat-guidelines.md" : "../prompts/replace-bulk-guidelines.md", {
     AUTO_READ_GUIDANCE: readGuidance,
   });
 
+  const parameters = opts.flat ? flatEditToolSchema : editToolSchema;
+
   return {
     name: "replace",
     label: "Replace",
     description: E_DESC,
-    parameters: editToolSchema,
+    parameters,
     promptSnippet: E_SNIPPET,
     promptGuidelines: E_GUIDE,
-    prepareArguments: (args: unknown) =>
-      normReq(args) as ReqParams,
+    prepareArguments: opts.flat
+      ? (args: unknown) => {
+          // Minimal normalization: file_path → path, JSON string parsing.
+          // The flat-to-canonical conversion happens in execute().
+          if (!isRec(args)) return args as any;
+          const record = { ...args };
+          if (typeof record.path !== "string" && typeof record.file_path === "string") {
+            record.path = record.file_path;
+            delete record.file_path;
+          }
+          if (typeof record.hash_range_inclusive === "string") {
+            try { record.hash_range_inclusive = JSON.parse(record.hash_range_inclusive as string); } catch { /* keep as-is */ }
+          }
+          if (typeof record.content_lines === "string") {
+            try { record.content_lines = JSON.parse(record.content_lines as string); } catch { /* keep as-is */ }
+          }
+          return record as any;
+        }
+      : (args: unknown) =>
+          normReq(args) as ReqParams,
     renderShell: "default",
     renderCall(args, theme, context) {
       const previewInput = getPreviewInput(args);
@@ -380,9 +428,19 @@ export function buildToolDef(): ToolDef {
     },
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const normalized = normReq(params);
-      assertReq(normalized);
-      const normalizedParams = normalized;
+      // Flat mode: wrap top-level fields into a single-element changes array.
+      // Bulk mode: use params as-is after normReq normalization.
+      const canonical = opts.flat
+        ? normReq({
+            path: (params as any).path,
+            changes: [{
+              hash_range_inclusive: (params as any).hash_range_inclusive,
+              content_lines: (params as any).content_lines,
+            }],
+          })
+        : normReq(params);
+      const normWarnings = (canonical as Record<string, unknown>)._normWarnings as string[] | undefined;
+      const normalizedParams = canonical as { path: string; changes: HTEdit[] };
       const path = normalizedParams.path;
       const absolutePath = toCwd(path, ctx.cwd);
       const mutationTargetPath = await resolveTarget(absolutePath);
@@ -408,9 +466,15 @@ export function buildToolDef(): ToolDef {
           signal,
         );
 
-        const editsAttempted = Array.isArray(normalizedParams.changes)
-          ? normalizedParams.changes.length
-          : 0;
+        const editsAttempted = opts.flat
+          ? 1
+          : Array.isArray(normalizedParams.changes)
+            ? normalizedParams.changes.length
+            : 0;
+
+        if (normWarnings) {
+          warnings.push(...normWarnings);
+        }
 
         if (originalNormalized === result) {
           const noopSnapshotId = (await fileSnap(absolutePath)).snapshotId;
@@ -437,6 +501,12 @@ export function buildToolDef(): ToolDef {
           absolutePath,
           bom + restoreEndings(result, originalEnding),
         );
+        saveUndo(mutationTargetPath, {
+          content: originalNormalized,
+          bom,
+          originalEnding,
+          hashes: originalHashes,
+        });
         const updatedSnapshotId = (await fileSnap(absolutePath))
           .snapshotId;
 
@@ -464,5 +534,5 @@ export function buildToolDef(): ToolDef {
 }
 
 export function regReplace(pi: ExtensionAPI): void {
-  pi.registerTool(buildToolDef());
+  pi.registerTool(buildToolDef({ flat: false }));
 }

package/src/undo-store.ts

@@ -0,0 +1,35 @@
+/**
+ * In-memory undo store for the last_replace_undo tool.
+ *
+ * Before each successful replace, the pre-edit file state (normalized content,
+ * BOM, original line ending, and hashes) is saved keyed by absolute path.
+ * The undo tool reads this entry, restores the file, and clears the entry.
+ *
+ * Only the most recent replace per file is tracked — calling undo twice
+ * without an intervening replace will produce "no undo history".
+ */
+
+export interface UndoEntry {
+  /** Normalized (LF) content before the edit */
+  content: string;
+  /** BOM prefix that was stripped from the original file */
+  bom: string;
+  /** Original line ending detected before the edit */
+  originalEnding: "\r\n" | "\n";
+  /** Hash array for the pre-edit content */
+  hashes: string[];
+}
+
+const undoMap = new Map<string, UndoEntry>();
+
+export function saveUndo(path: string, entry: UndoEntry): void {
+  undoMap.set(path, entry);
+}
+
+export function getUndo(path: string): UndoEntry | undefined {
+  return undoMap.get(path);
+}
+
+export function clearUndo(path: string): void {
+  undoMap.delete(path);
+}