@d3ara1n/pi-hashline-edit 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @d3ara1n/pi-hashline-edit
 
-> Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash, replacing `oldText`/`newText` matching.
+> Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash (replacing `oldText`/`newText` matching), plus a location-blind `replace` tool for bulk + regex transforms.
 
 Edits reference lines by `LINE#HASH` anchors (copied from `read`/`grep` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
 
@@ -22,7 +22,7 @@ Routine local code editing in pi — the common case. If you spend turns fightin
 
 ## When to turn it off
 
-Set `hashlineEdit.enabled = false` (or uninstall) to fall back to the built-in `read`/`edit`/`grep` when you need **remote or custom-storage files** — the overrides read/write/search the local filesystem directly, so pi's custom `ReadOperations`/`GrepOperations` (SSH, etc.) aren't supported. The same switch lets you opt out per-project.
+Set `hashlineEdit.enabled = false` (or uninstall) to fall back to the built-in `read`/`edit`/`grep` when you need **remote or custom-storage files** — the overrides read/write/search the local filesystem directly, so pi's custom `ReadOperations`/`GrepOperations` (SSH, etc.) aren't supported. The same switch lets you opt out per-project. All four tools — `read`, `grep`, `edit`, `replace` — are one set governed by this switch: when disabled, `read`/`grep`/`edit` delegate to the built-ins and `replace` refuses (it has no built-in counterpart).
 
 ## Gotchas (vs. the built-in `read`/`edit`)
 
@@ -31,6 +31,18 @@ Once hashline overrides the built-ins, a few things behave differently:
 - **`read` is globally overridden.** Every read shows the `LINE#HASH│` prefix on each line — even reads that won't lead to an edit. This is expected (it's the substrate the reliability is built on), just don't be surprised when the format changes for all files.
 - **Conservative overlap.** Two ops whose ranges touch (e.g. `insert_after` immediately followed by `replace` at the same line) are rejected to avoid backfill ambiguity — issue them as two separate `edit` calls.
 
+## `replace` — bulk + regex
+
+A separate, location-blind tool for transforms `edit` can't express: replace **all** occurrences of a string/regex across the whole file in one call. Use it for renames, normalizations, and pattern-based rewrites that would otherwise need many individual anchored ops.
+
+- **Two modes** — `regex: false` (default) treats `find` as a literal substring (replaceAll; the replacement is inserted verbatim, no `$` expansion); `regex: true` treats `find` as a JavaScript pattern source and `replace` supports `$1`, `$2`, `$&`, …
+- **Flags** — `flags` adds regex flags in both modes (`g` is always forced so every occurrence is replaced): `i` (case-insensitive), `m` (per-line `^`/`$`), `s` (dotall, `.` matches `\n`), `u` (unicode).
+- **Safety** — a `maxMatches` cap (default 2000) errors *before writing* if exceeded, so a runaway pattern can't produce a catastrophic write. `0` matches is an error (no silent no-op).
+- **Shares the edit queue** — `replace` and `edit` on the same file are serialized via the same mutation queue, so concurrent edits never interleave.
+- **Returns a diff + fresh anchors** for the changed region, so a follow-up `edit` can chain on the new content without a re-read (when the region is small).
+
+`edit` vs `replace`: `edit` is **surgical and verified** (you point at a `LINE#HASH` and the tool confirms the line is unchanged before rewriting it). `replace` is **global and unverified** (you give a pattern, it rewrites every match sight-unseen). Pick by intent: change a known spot → `edit`; transform every occurrence → `replace`.
+
 ## Design
 
 - **Per-line hash + line number, dual anchor**: `read` shows each line as `3#aF3│code`; `edit` references `LINE#HASH`. The line number is the address; the hash is a checksum that the line at that address is still what was read.
@@ -39,7 +51,7 @@ Once hashline overrides the built-ins, a few things behave differently:
 - **Shifted-anchor recovery**: a mismatched anchor isn't a dead end. The applicator rescans ±`shiftRadius` lines for the original content — holding the original line number fixed and re-hashing each candidate (`hash(line, candidate) === cited` iff the candidate *is* the original) — and returns a ready-to-resend anchor on a unique hit, the candidate list when ambiguous, or the cited line's live content when nothing matches. The model retries without a re-read in the common drift case.
 - **Atomic batches, all failures collected**: every op in one `edit` is verified against the same snapshot; if any anchor fails, *all* failures (each with its recovery) are returned together and nothing is written — partial writes would shift lines and invalidate the very recovery info just returned.
 - **Chain edits without re-reading**: a successful `edit` returns `Updated anchors` for the lines it produced (and the line that shifted into a deletion gap), so the next edit can cite them directly.
-- **No legacy compatibility**: `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use.
+- **No legacy compatibility on `edit`**: `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use. Bulk/regex replacement is a *separate* tool, `replace`, not an `edit` mode (see below).
 
 ## Protocol
 
@@ -77,6 +89,28 @@ src/util.ts · 1 match
 
 Ops: `replace` · `delete` · `insert_after` · `insert_before` · `append` · `prepend`. `anchor`/`end` = `{line, hash}` from read; `body` = new content lines (string[], omit for `delete`).
 
+`replace` takes `path`, `find`, `replace` (+ optional `regex`, `flags`, `maxMatches`) and substitutes **every** match:
+
+```jsonc
+{
+  "path": "src/foo.ts",
+  "find": "oldName",
+  "replace": "newName"
+}
+```
+
+Regex with a capture group (rename `getName()` → `get_name()` everywhere):
+
+```jsonc
+{ "path": "src/foo.ts", "find": "get([A-Z]\w*)", "replace": "get_$1", "regex": true }
+```
+
+Case-insensitive literal rename across the whole file:
+
+```jsonc
+{ "path": "src/foo.ts", "find": "TODO", "replace": "FIXME", "flags": "i" }
+```
+
 ## Configuration
 
 Add a `hashlineEdit` field to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` in a project (project replaces global):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-hashline-edit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Hashline-style file editing for pi — line-anchored edits verified by content hash, replacing oldText/newText matching",
   "keywords": [

package/src/index.ts

@@ -3,8 +3,11 @@
  *
  * Overrides the built-in read/edit: read outputs "lineNo#hash│content";
  * edit accepts structured hashline ops (edits[] with LINE#HASH anchors), and
- * legacy oldText/newText is rejected explicitly (no silent degradation). Each
- * tool carries its own renderer.
+ * legacy oldText/newText is rejected explicitly (no silent degradation). grep
+ * is overridden the same way so results carry usable anchors. A separate
+ * `replace` tool adds location-blind bulk + regex replacement (replaceAll and
+ * full JS regex with capture groups) for renames/pattern transforms that
+ * would need many individual edits. Each tool carries its own renderer.
  *
  * @module pi-hashline-edit
  */
@@ -15,6 +18,7 @@ import { getState } from "./pi/state.ts";
 import { makeEditOverride } from "./pi/edit-tool.ts";
 import { makeReadOverride } from "./pi/read-tool.ts";
 import { makeGrepOverride } from "./pi/grep-tool.ts";
+import { makeReplaceTool } from "./pi/replace-tool.ts";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();
@@ -28,4 +32,5 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool(makeReadOverride(cwd));
 	pi.registerTool(makeEditOverride(cwd));
 	pi.registerTool(makeGrepOverride(cwd));
+	pi.registerTool(makeReplaceTool(cwd));
 }

package/src/pi/edit-tool.ts

@@ -209,7 +209,9 @@ export function makeEditOverride(cwd: string) {
 			}
 			const diff: string | undefined = result.details?.diff;
 			if (!diff) {
-				const t = content?.type === "text" ? content.text : "Edited";
+				// No net diff (e.g. a successful but non-mutating edit): show only the summary
+				// line — content.text also carries `Updated anchors` (hashline) for the model.
+				const t = content?.type === "text" ? content.text.split("\n")[0] : "Edited";
 				return new Text(theme.fg("success", t), 0, 0);
 			}
 			// details.diff is pi-format (+N/-N/<space>N content); color by leading char
@@ -279,11 +281,16 @@ async function runHashline(absPath: string, displayPath: string, editOps: readon
 		return errResult(`Error writing ${displayPath}: ${msg}`);
 	}
 
-	// pi's generateDiffString returns the display diff (colored by the renderer) and the first changed line
-	const { diff, firstChangedLine } = generateDiffString(currentText, result.text);
+	// generateDiffString / generateUnifiedPatch split on \n, so raw CRLF content would
+	// leave a trailing \r on every diff line — the TUI line-wrapper (wrapTextWithAnsi)
+	// then emits a spurious blank line per diff line. Normalize to LF for diff/patch
+	// only; the disk write above already preserved the original line endings.
+	const oldLf = currentText.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const newLf = result.text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const { diff, firstChangedLine } = generateDiffString(oldLf, newLf);
 	const details: EditToolDetails = {
 		diff,
-		patch: generateUnifiedPatch(displayPath, currentText, result.text),
+		patch: generateUnifiedPatch(displayPath, oldLf, newLf),
 		firstChangedLine,
 	};
 	const anchors = formatUpdatedAnchors(result.text, result.touchedLines, hashLen);

package/src/pi/execute.test.ts

@@ -150,44 +150,49 @@ test("edit on a line that changed externally → anchor mismatch", async () => {
 		const text = "a\nb\nc\n";
 		await writeFile(f, text);
 		await writeFile(f, "a\nBCHANGED\nc\n"); // line 2 changed
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: h(text, 2), body: ["x"] }],
-		});
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /anchor|re-read/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: h(text, 2), body: ["x"] }],
+			}),
+			/anchor|re-read/i,
+		);
 	});
 });
 
 test("edit execute: no read before edit → anchor verification fails", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\nb\n");
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
-		});
-		assert.equal(r.isError, true);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
+			}),
+			/anchor|re-read/i,
+		);
 	});
 });
 
-test("edit execute: empty edits → isError", async () => {
+test("edit execute: empty edits → throws", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
-		const r: any = await call(makeEditOverride(dir), { path: "f.txt", edits: [] });
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /empty|missing/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), { path: "f.txt", edits: [] }),
+			/empty|missing/i,
+		);
 	});
 });
 
-test("edit execute: malformed op (replace without body) → isError", async () => {
+test("edit execute: malformed op (replace without body) → throws", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: { line: 1, hash: "XX" } }],
-		});
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /body/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: { line: 1, hash: "XX" } }],
+			}),
+			/body/i,
+		);
 	});
 });
 
@@ -247,13 +252,21 @@ test("edit error: renderResult renders the error line without throwing", async (
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		const edit = makeEditOverride(dir);
-		const r: any = await call(edit, {
+		let thrown: any;
+		await call(edit, {
 			path: "f.txt",
 			edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
+		}).catch((e: any) => {
+			thrown = e;
 		});
-		assert.equal(r.isError, true);
-		// @ts-ignore
-		const comp: any = edit.renderResult({ content: r.content, details: r.details }, { isPartial: false, expanded: false }, stubTheme, { isError: r.isError ?? false });
+		assert.ok(thrown, "expected the edit to throw");
+		// @ts-ignore — simulate the framework handing the thrown message to renderResult
+		const comp: any = edit.renderResult(
+			{ content: [{ type: "text", text: thrown.message }] },
+			{ isPartial: false, expanded: false },
+			stubTheme,
+			{ isError: true },
+		);
 		assert.ok(typeof comp?.text === "string");
 	});
 });

package/src/pi/grep-tool.ts

@@ -33,6 +33,7 @@ import { hashFileLines } from "../core/hash.ts";
 import { splitLines } from "../core/lines.ts";
 import { getState } from "./state.ts";
 import { canonicalPath } from "./read-tool.ts";
+import { parseHashline } from "./render.ts";
 
 const DEFAULT_LIMIT = 100;
 /** Max chars per result line for display (mirrors pi's truncate.ts; not exported there). */
@@ -65,30 +66,48 @@ interface RawMatch {
 
 /**
  * Convert the anchored grep output (grouped, `LINE#HASH│`) into a human-readable
- * form for the TUI: drop the hash, keep file headers and line numbers. The model
- * still receives the anchored `content` text; this only affects what the user sees.
+ * form for the TUI: drop the hash, keep file headers and line numbers. Within each
+ * file group, the common leading whitespace shared by all matched lines is folded
+ * into a single marker (›) so deep, repeated indentation doesn't eat display width;
+ * each line's indentation relative to that common base is preserved. The model still
+ * receives the anchored `content` text verbatim — this only affects what the user sees.
  */
+function countLeading(s: string): number {
+	const m = s.match(/^[ \t]*/);
+	return m ? m[0].length : 0;
+}
+
 function toDisplayLines(raw: string, theme: any): string[] {
 	const out: string[] = [];
-	for (const line of raw.split("\n")) {
-		// anchored line first: "lineNo#HASH│content" → "   lineNo: content"
-		const a = line.match(/^(\d+)#[A-Za-z0-9]+│(.*)$/);
-		if (a) {
-			out.push(theme.fg("dim", `   ${a[1]}:`) + theme.fg("toolOutput", ` ${a[2]}`));
-			continue;
-		}
-		// file header: "path · N match(es)" → path accent, count dim
+	const lines = raw.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
 		const h = line.match(/^(.+?) · (\d+ match(?:es)?)$/);
 		if (h) {
 			out.push(theme.fg("success", h[1]) + theme.fg("dim", ` · ${h[2]}`));
+			// collect the anchor lines in this file group
+			const group: { lineNo: string; content: string }[] = [];
+			let j = i + 1;
+			while (j < lines.length) {
+				const a = parseHashline(lines[j]);
+				if (!a) break;
+				group.push({ lineNo: a.lineNo, content: a.content });
+				j++;
+			}
+			// common base = min leading whitespace across the group; fold it into a marker
+			const base = group.length ? Math.min(...group.map((g) => countLeading(g.content))) : 0;
+			const marker = base > 0 ? theme.fg("dim", "›") + " " : "";
+			for (const g of group) {
+				const body = g.content.slice(base);
+				out.push(theme.fg("dim", `   ${g.lineNo}: `) + marker + theme.fg("toolOutput", body));
+			}
+			i = j;
 			continue;
 		}
-		// truncation notice block "[...]"
-		if (line.startsWith("[")) {
-			out.push(theme.fg("warning", line));
-			continue;
-		}
-		out.push(theme.fg("toolOutput", line));
+		if (line.startsWith("[")) out.push(theme.fg("warning", line));
+		else out.push(theme.fg("toolOutput", line));
+		i++;
 	}
 	return out;
 }

package/src/pi/read-tool.ts

@@ -9,13 +9,15 @@
  * @module pi-hashline-edit/pi
  */
 
-import { createReadTool } from "@earendil-works/pi-coding-agent";
+import { createReadTool, getLanguageFromPath, highlightCode } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { hashFileLines } from "../core/hash.ts";
 import { splitLines } from "../core/lines.ts";
 import { getState } from "./state.ts";
+import { parseHashline } from "./render.ts";
 
 const MAX_LINES = 2000;
 const MAX_BYTES = 256 * 1024;
@@ -37,6 +39,70 @@ function expandTilde(p: string): string {
 	return p;
 }
 
+/** Offset/limit range suffix for the read call line, e.g. `:50-99` (mirrors pi core's read tool). */
+function formatReadLineRange(args: any, theme: any): string {
+	if (args?.offset === undefined && args?.limit === undefined) return "";
+	const start = args.offset ?? 1;
+	const end = args.limit !== undefined ? start + args.limit - 1 : "";
+	return theme.fg("warning", `:${start}${end ? `-${end}` : ""}`);
+}
+
+/**
+ * Render the expanded read body for the TUI: color the header, strip the
+ * `LINE#HASH│` prefix from every anchor line to `   N: content`, and
+ * syntax-highlight the code block by the file's language (falls back to a
+ * single `toolOutput` color when the language is unknown or the highlight
+ * line count diverges). Trailing notices (e.g. truncation) are shown in
+ * `warning`.
+ */
+function renderReadBody(raw: string, path: string, theme: any): string {
+	const lines = raw.split("\n");
+	if (lines.length === 0) return "";
+	const out: string[] = [];
+
+	// Header: "<path> · <N> lines" optionally followed by " (from line <offset>)".
+	let bodyStart = 0;
+	const h = lines[0].match(/^(.+?) · (\d+ lines(?: \(from line \d+\))?)$/);
+	if (h) {
+		out.push(theme.fg("success", h[1]) + theme.fg("dim", ` · ${h[2]}`));
+		bodyStart = 1;
+	}
+
+	// Collect anchor rows (full content); the first non-anchor line begins the tail.
+	const lineNos: string[] = [];
+	const codeContents: string[] = [];
+	let tailStart = lines.length;
+	for (let i = bodyStart; i < lines.length; i++) {
+		const row = parseHashline(lines[i]);
+		if (!row) {
+			tailStart = i;
+			break;
+		}
+		lineNos.push(row.lineNo);
+		codeContents.push(row.content);
+	}
+
+	// Syntax-highlight the whole block so multi-line constructs stay correct.
+	const detabbed = codeContents.map((l) => l.replace(/\t/g, "   "));
+	const lang = getLanguageFromPath(path);
+	let rendered: string[];
+	if (lang) {
+		const hl = highlightCode(detabbed.join("\n"), lang);
+		// Guard against highlighters that reshape line count: fall back to plain.
+		rendered = hl.length === detabbed.length ? hl : detabbed.map((l) => theme.fg("toolOutput", l));
+	} else {
+		rendered = detabbed.map((l) => theme.fg("toolOutput", l));
+	}
+	for (let i = 0; i < rendered.length && i < lineNos.length; i++) {
+		out.push(theme.fg("dim", `   ${lineNos[i]}: `) + rendered[i]);
+	}
+
+	for (let i = tailStart; i < lines.length; i++) {
+		out.push(theme.fg("warning", lines[i]));
+	}
+	return out.join("\n");
+}
+
 /** Build the read override (a ToolDefinition fragment for registerTool). */
 export function makeReadOverride(cwd: string) {
 	const builtin = createReadTool(cwd);
@@ -52,6 +118,29 @@ export function makeReadOverride(cwd: string) {
 			"Pass `path`; optionally `offset` (1-indexed start line) and `limit` (max lines). Prefer read over cat/sed for files you intend to edit.",
 		],
 		parameters: builtin.parameters,
+		renderShell: "default" as const,
+
+		renderCall(args: any, theme: any) {
+			const pathDisplay = String(args?.path ?? "");
+			let text = theme.fg("toolTitle", theme.bold("read")) + " " + theme.fg("accent", pathDisplay);
+			const range = formatReadLineRange(args, theme);
+			if (range) text += range;
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result: any, { isPartial, expanded }: any, theme: any, context: any) {
+			if (isPartial) return new Text(theme.fg("warning", "Reading…"), 0, 0);
+			const content = result.content?.[0];
+			if (context?.isError) {
+				const t = content?.type === "text" ? content.text.split("\n")[0] : "Error";
+				return new Text(theme.fg("error", t), 0, 0);
+			}
+			// Collapsed (not expanded): show nothing — the call line carries the
+			// title, matching the built-in read's fold behavior.
+			if (!expanded) return new Text("", 0, 0);
+			const raw = content?.type === "text" ? content.text : "";
+			return new Text(renderReadBody(raw, String(context?.args?.path ?? ""), theme), 0, 0);
+		},
 
 		async execute(toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any) {
 			// Not enabled OR user cancelled → delegate to the built-in (builtin handles abort itself)

package/src/pi/render.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared anchor-parsing helper for the hashline-aware tool renderers.
+ *
+ * The model-facing `content` text uses the `LINE#HASH│content` anchor format so
+ * an anchor can be copied straight into an edit op. The user-facing TUI
+ * renderers (read, grep) strip that prefix back to a clean `   N: content` form.
+ * Parsing the anchor format in one place keeps read and grep in sync.
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+const HASHLINE_RE = /^(\d+)#[A-Za-z0-9]+│(.*)$/;
+
+export interface HashlineRow {
+	/** Line number as written in the anchor (string form). */
+	lineNo: string;
+	/** Line content with the `LINE#HASH│` prefix removed. */
+	content: string;
+}
+
+/**
+ * Parse a `LINE#HASH│content` anchor line.
+ *
+ * @returns the row, or `null` for non-anchor lines (headers, notices, free
+ *   text) so callers can fall through to their own formatting.
+ */
+export function parseHashline(line: string): HashlineRow | null {
+	const m = line.match(HASHLINE_RE);
+	return m ? { lineNo: m[1], content: m[2] } : null;
+}

package/src/pi/replace-tool.ts

@@ -0,0 +1,304 @@
+/**
+ * `replace`: powerful bulk text replacement — literal substring (replaceAll) or
+ * full JavaScript regex with capture-group substitution.
+ *
+ * Distinct from the anchor-verified `edit`. `replace` is **location-blind**:
+ * it matches `find` everywhere across the whole file and substitutes every
+ * occurrence. Use it for renames and pattern-based transforms that would
+ * otherwise need many individual edits. For a single surgical, verified change,
+ * prefer `edit`.
+ *
+ * - Literal mode (`regex` false): `find` is a substring, matched verbatim;
+ *   `replace` is inserted as-is (no `$` expansion).
+ * - Regex mode (`regex` true): `find` is a JS pattern source; `replace` supports
+ *   `$1`, `$2`, `$&`, etc.
+ * - `flags` adds regex flags in either mode; `g` is always forced so every
+ *   occurrence is replaced. `i` (case-insensitive), `m` (per-line ^/$),
+ *   `s` (dotall), `u` (unicode) all work.
+ *
+ * Concurrency: read-modify-write is wrapped in {@link withFileMutationQueue}
+ * (shared with `edit`), so a `replace` and an `edit` on the same file never
+ * interleave. AbortSignal is honored after read / before write.
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import {
+	generateDiffString,
+	generateUnifiedPatch,
+	withFileMutationQueue,
+	type EditToolDetails,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { readFile, writeFile } from "node:fs/promises";
+import { hashFileLines, splitLines } from "../core/index.ts";
+import { getState } from "./state.ts";
+import { canonicalPath } from "./read-tool.ts";
+
+/** Cap on updated-anchor lines returned inline (bounds token cost for large spans). */
+const MAX_ANCHOR_LINES = 40;
+/** Default safety cap on match count (errors before writing if exceeded). */
+const DEFAULT_MAX_MATCHES = 2000;
+/** Valid JavaScript regular-expression flag characters (ES2023+, incl. hasIndices `d`). */
+const VALID_FLAGS = new Set(["g", "i", "m", "s", "u", "y", "d"]);
+
+const replaceSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+	find: Type.String({
+		description:
+			"Text to find. Literal substring when `regex` is false/omitted; a JavaScript regex pattern source when `regex` is true.",
+	}),
+	replace: Type.String({
+		description:
+			"Replacement text. Literal mode: inserted verbatim (no $ expansion). Regex mode: supports $1, $2, $&, $`, $' etc.",
+	}),
+	regex: Type.Optional(
+		Type.Boolean({
+			description:
+				"Treat `find` as a JavaScript regex pattern source (default false = literal substring, all occurrences replaced).",
+		}),
+	),
+	flags: Type.Optional(
+		Type.String({
+			description:
+				"Regex flags appended in BOTH modes ('g' is always forced so every occurrence is replaced). Default ''. Common: 'i' (case-insensitive), 'm' (^/$ per line), 's' (dotall, . matches \\n), 'u' (unicode).",
+		}),
+	),
+	maxMatches: Type.Optional(
+		Type.Number({
+			description: `Safety cap: errors before writing if more matches than this (default ${DEFAULT_MAX_MATCHES}). Raise for deliberate bulk transforms.`,
+		}),
+	),
+});
+
+type ReplaceParams = Static<typeof replaceSchema>;
+
+/** Escape regex metacharacters so a literal string is matched verbatim. */
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Build the matcher. `find` is escaped in literal mode; `flags` (validated) get
+ * `g` forced so all occurrences replace. Construction errors (bad pattern /
+ * conflicting flags such as `g`+`y`) surface as a friendly message rather than
+ * a raw `SyntaxError`.
+ */
+function buildRegex(find: string, isRegex: boolean, flagsRaw: string | undefined): RegExp {
+	for (const c of flagsRaw ?? "") {
+		if (!VALID_FLAGS.has(c)) throw new Error(`invalid regex flag '${c}' (valid: g i m s u y d)`);
+	}
+	const set = new Set((flagsRaw ?? "").split(""));
+	set.add("g");
+	const flagStr = [...set].join("");
+	const source = isRegex ? find : escapeRegex(find);
+	try {
+		return new RegExp(source, flagStr);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`invalid regex /${source}/${flagStr}: ${msg}`);
+	}
+}
+
+/**
+ * First-to-last differing line span (0-based, inclusive) in the NEW line array —
+ * a contiguous superset that contains every changed line. Computed by stripping
+ * the common prefix and suffix, so it is O(n) regardless of file size (no LCS
+ * DP). `null` when the text is unchanged. Used only to bound the anchor report.
+ */
+function changedSpan(oldLines: readonly string[], newLines: readonly string[]): { start: number; end: number } | null {
+	const n = Math.min(oldLines.length, newLines.length);
+	let prefix = 0;
+	while (prefix < n && oldLines[prefix] === newLines[prefix]) prefix++;
+	// same length and fully equal → no change
+	if (oldLines.length === newLines.length && prefix === oldLines.length) return null;
+	let oldSuffix = 0;
+	let newSuffix = 0;
+	while (
+		oldSuffix < oldLines.length - prefix &&
+		newSuffix < newLines.length - prefix &&
+		oldLines[oldLines.length - 1 - oldSuffix] === newLines[newLines.length - 1 - newSuffix]
+	) {
+		oldSuffix++;
+		newSuffix++;
+	}
+	const start = prefix;
+	const end = newLines.length - 1 - newSuffix; // inclusive, 0-based, in new
+	return end < start ? null : { start, end };
+}
+
+/** Format fresh `LINE#HASH│content` anchors for a contiguous span of the new file, capped. */
+function formatSpanAnchors(newLines: readonly string[], span: { start: number; end: number }, hashLen: number): string {
+	const hashes = hashFileLines(newLines, hashLen);
+	const rows: string[] = [];
+	for (let i = span.start; i <= span.end; i++) rows.push(`${i + 1}#${hashes[i]}│${newLines[i]}`);
+	const shown = rows.length > MAX_ANCHOR_LINES ? rows.slice(0, MAX_ANCHOR_LINES) : rows;
+	const more = rows.length > MAX_ANCHOR_LINES ? `\n… (${rows.length - MAX_ANCHOR_LINES} more; re-read for full anchors)` : "";
+	return `\nUpdated anchors (changed region):\n${shown.join("\n")}${more}`;
+}
+
+/** Truncate a string for one-line display, folding newlines into a marker. */
+function show(s: string, n = 30): string {
+	const folded = s.replace(/\n/g, "⏎");
+	return folded.length > n ? folded.slice(0, n) + "…" : folded;
+}
+
+export function makeReplaceTool(cwd: string) {
+	return {
+		name: "replace" as const,
+		label: "replace",
+		description:
+			"Bulk text replacement with regex support. Replaces ALL occurrences of `find` with `replace` across the whole file — for renames and pattern-based transforms that would need many individual edits. Location-blind (unverified): prefer `edit` for surgical, anchor-verified changes.",
+		promptSnippet: "Replace all occurrences of a string/regex across a file (bulk + regex; returns diff and fresh anchors)",
+		promptGuidelines: [
+			"Pass `path`, `find`, `replace`. ALL occurrences are replaced (not just the first).",
+			"`regex: true` treats `find` as a JS regex pattern; capture groups are usable in `replace` via $1, $2, $&. Default false = literal substring (replace text inserted verbatim, no $ expansion).",
+			"`flags` adds regex flags ('g' is always forced so every occurrence is replaced). Common: 'i' (case-insensitive), 'm' (^/$ per line), 's' (dotall, . matches \\n), 'u' (unicode). Applies in both modes.",
+			"`maxMatches` caps the match count (default 2000) — errors before writing if exceeded; raise it for deliberate bulk transforms.",
+			"Returns a diff plus fresh anchors for the changed region; chain edits, or re-read if you need the whole file's anchors.",
+			"0 matches is an error. This is a location-blind bulk tool — for one verified change use `edit` instead.",
+		],
+		parameters: replaceSchema,
+		renderShell: "default" as const,
+
+		renderCall(args: ReplaceParams, theme: any) {
+			let text = theme.fg("toolTitle", theme.bold("replace "));
+			text += theme.fg("accent", args.path);
+			const mode = args.regex ? "regex" : "lit";
+			const f = args.flags ? `/${args.flags}` : "";
+			text += theme.fg("dim", ` — ${mode}${f} "${show(args.find)}" → "${show(args.replace)}"`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result: any, { isPartial, expanded }: any, theme: any, context: any) {
+			if (isPartial) return new Text(theme.fg("warning", "Replacing…"), 0, 0);
+			const content = result.content?.[0];
+			if (context.isError) {
+				const t = content?.type === "text" ? content.text.split("\n")[0] : "Error";
+				return new Text(theme.fg("error", t), 0, 0);
+			}
+			const diff: string | undefined = result.details?.diff;
+			if (!diff) {
+				// No net diff: show only the summary line — content.text also carries
+				// `Updated anchors` (hashline) for the model.
+				const t = content?.type === "text" ? content.text.split("\n")[0] : "Replaced";
+				return new Text(theme.fg("success", t), 0, 0);
+			}
+			// details.diff is pi-format (+N/-N/<space>N content); color by leading char
+			const allLines = diff.split("\n");
+			const shown = expanded ? allLines : allLines.slice(0, 24);
+			const body = shown
+				.map((line: string) => {
+					if (line.startsWith("+")) return theme.fg("success", line);
+					if (line.startsWith("-")) return theme.fg("error", line);
+					return theme.fg("dim", line);
+				})
+				.join("\n");
+			const more = !expanded && allLines.length > 24 ? `\n${theme.fg("dim", `… (${allLines.length - 24} more)`)}` : "";
+			return new Text(body + more, 0, 0);
+		},
+
+		async execute(toolCallId: string, params: ReplaceParams, signal: AbortSignal | undefined, onUpdate: any) {
+			const state = getState();
+			// Gated by the same `enabled` switch as read/grep/edit — they delegate to the
+			// built-ins when disabled; replace has no built-in counterpart, so it refuses.
+			if (!state.config.enabled)
+				throw new Error(
+					"Replace is unavailable: hashlineEdit is disabled. Set hashlineEdit.enabled = true to use it.",
+				);
+			const path = params.path;
+			const absPath = canonicalPath(cwd, path);
+
+			// withFileMutationQueue serializes read-modify-write for the same file,
+			// shared with `edit` — a replace and an edit on the same file never interleave.
+			return await withFileMutationQueue(absPath, () => runReplace(absPath, path, params, state.config.hashLen, signal));
+		},
+	};
+}
+
+async function runReplace(
+	absPath: string,
+	displayPath: string,
+	params: ReplaceParams,
+	hashLen: number,
+	signal: AbortSignal | undefined,
+) {
+	const { find, replace } = params;
+	const isRegex = params.regex === true;
+	const maxMatches = params.maxMatches ?? DEFAULT_MAX_MATCHES;
+
+	if (find === "") throw new Error(`Replace ${displayPath}: \`find\` is empty.`);
+
+	let currentText: string;
+	try {
+		currentText = (await readFile(absPath)).toString("utf-8");
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`Error reading ${displayPath}: ${msg}`);
+	}
+	// honor cancel after read: if aborted, don't proceed to match/replace; the file stays untouched
+	if (signal?.aborted) throw new Error(`Replace ${displayPath} aborted before apply.`);
+
+	let regex: RegExp;
+	try {
+		regex = buildRegex(find, isRegex, params.flags);
+	} catch (e) {
+		throw new Error(`Replace ${displayPath}: ${e instanceof Error ? e.message : String(e)}`);
+	}
+
+	// Count matches with an early guard so a runaway pattern (e.g. an empty-match
+	// regex) can't produce a catastrophic write. matchAll does not mutate the
+	// regex's lastIndex (it clones internally), so the subsequent `replace` is safe.
+	let count = 0;
+	for (const _ of currentText.matchAll(regex)) {
+		count++;
+		if (count > maxMatches) {
+			throw new Error(
+				`Replace ${displayPath}: ${count}+ matches exceed \`maxMatches\` (${maxMatches}). Raise \`maxMatches\` if intentional, or narrow \`find\`.`,
+			);
+		}
+	}
+	if (count === 0) {
+		const shown = isRegex ? `/${find}/` : JSON.stringify(find);
+		throw new Error(`Replace ${displayPath}: no matches for ${shown}.`);
+	}
+
+	// Literal mode uses a function replacement so `$` in `replace` stays literal;
+	// regex mode passes the string so $1/$& etc. expand.
+	// Literal mode uses a function replacement so `$` in `replace` stays literal;
+	// regex mode passes the string so $1/$& etc. expand.
+	const newText = isRegex ? currentText.replace(regex, replace) : currentText.replace(regex, () => replace);
+	const changed = newText !== currentText;
+
+	// honor cancel before write: if aborted, don't touch the disk
+	if (signal?.aborted) throw new Error(`Replace ${displayPath} aborted before write.`);
+
+	if (changed) {
+		try {
+			await writeFile(absPath, newText);
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			throw new Error(`Error writing ${displayPath}: ${msg}`);
+		}
+	}
+
+	const { diff, firstChangedLine } = generateDiffString(currentText, newText);
+	const details: EditToolDetails = {
+		diff,
+		patch: generateUnifiedPatch(displayPath, currentText, newText),
+		firstChangedLine,
+	};
+
+	const oldLines = splitLines(currentText);
+	const newLines = splitLines(newText);
+	const span = changed ? changedSpan(oldLines, newLines) : null;
+	const anchors = span ? formatSpanAnchors(newLines, span, hashLen) : "";
+
+	const matchWord = `match${count !== 1 ? "es" : ""}`;
+	const note = changed ? `${count} ${matchWord}` : `${count} ${matchWord}, no net change`;
+	return {
+		content: [{ type: "text" as const, text: `Replaced ${displayPath} (${note}).${anchors}` }],
+		details,
+	};
+}

package/src/pi/replace.test.ts

@@ -0,0 +1,283 @@
+/**
+ * pi integration tests for the `replace` tool: literal replaceAll, regex with
+ * capture groups, flags, the maxMatches guard, 0-match / invalid-pattern
+ * failures (signaled by throwing — pi's failure contract), diff + fresh-anchor
+ * return, and chaining a hashline `edit` on an anchor returned by `replace`.
+ *
+ * Failures are signaled by throwing (see edit-tool.ts); tests use assert.rejects.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { makeReplaceTool } from "./replace-tool.ts";
+import { makeEditOverride } from "./edit-tool.ts";
+import { getState } from "./state.ts";
+
+async function withDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+	const dir = await mkdtemp(join(tmpdir(), "hl-replace-"));
+	try {
+		return await fn(dir);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+const call = (tool: any, params: any) => tool.execute("0", params, undefined, undefined);
+
+/** Extract a `LINE#HASH` anchor for `line` from a result text block. */
+function anchorLine(block: string, line: number) {
+	const m = new RegExp(`^${line}#([0-9A-Z]+)│`, "m").exec(block);
+	if (!m) throw new Error(`line ${line} anchor not found in block`);
+	return { line, hash: m[1] };
+}
+
+const stubTheme = { fg: (_k: string, s: string) => s, bold: (s: string) => s };
+
+test("replace literal: replaces all occurrences", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "foo bar foo baz foo\n");
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "foo", replace: "qux" });
+		assert.equal(r.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "qux bar qux baz qux\n");
+		assert.match(r.content[0].text, /3 matches/);
+	});
+});
+
+test("replace literal: $ in replacement stays literal (no expansion)", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "cost: $5 here\n");
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "$5", replace: "$10" });
+		assert.equal(r.isError, undefined);
+		// literal mode: "$10" inserted verbatim, NOT interpreted as group-10 + "0"
+		assert.equal(await readFile(f, "utf-8"), "cost: $10 here\n");
+	});
+});
+
+test("replace literal: case-insensitive via flags", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "Foo fOo FOO\n");
+		await call(makeReplaceTool(dir), { path: "f.txt", find: "foo", replace: "x", flags: "i" });
+		assert.equal(await readFile(f, "utf-8"), "x x x\n");
+	});
+});
+
+test("replace regex: capture groups in replacement", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "name: alice\nname: bob\n");
+		await call(makeReplaceTool(dir), {
+			path: "f.txt",
+			find: "name: (\\w+)",
+			replace: "user: $1",
+			regex: true,
+		});
+		assert.equal(await readFile(f, "utf-8"), "user: alice\nuser: bob\n");
+	});
+});
+
+test("replace regex: multiline flag matches line-anchored pattern", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		// without `m`, ^a$ wouldn't match (a isn't at end of string); with `m` it does
+		await call(makeReplaceTool(dir), { path: "f.txt", find: "^a$", replace: "A", regex: true, flags: "m" });
+		assert.equal(await readFile(f, "utf-8"), "A\nb\nc\n");
+	});
+});
+
+test("replace regex: dotall flag makes . match newlines", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\n");
+		// a.b only matches across the newline with the `s` (dotall) flag
+		await call(makeReplaceTool(dir), { path: "f.txt", find: "a.b", replace: "X", regex: true, flags: "s" });
+		assert.equal(await readFile(f, "utf-8"), "X\n");
+	});
+});
+
+test("replace: 0 matches throws", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\n");
+		await assert.rejects(
+			call(makeReplaceTool(dir), { path: "f.txt", find: "zzz", replace: "y" }),
+			/no matches/,
+		);
+		assert.equal(await readFile(f, "utf-8"), "a\nb\n", "file untouched on 0-match failure");
+	});
+});
+
+test("replace: empty find throws", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		await assert.rejects(
+			call(makeReplaceTool(dir), { path: "f.txt", find: "", replace: "x" }),
+			/`find` is empty/,
+		);
+	});
+});
+
+test("replace: maxMatches guard throws before writing", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a".repeat(20) + "\n");
+		await assert.rejects(
+			call(makeReplaceTool(dir), { path: "f.txt", find: "a", replace: "b", maxMatches: 5 }),
+			/exceed `maxMatches`/,
+		);
+		assert.equal(await readFile(f, "utf-8"), "a".repeat(20) + "\n", "file untouched when guard trips");
+	});
+});
+
+test("replace: invalid regex throws a friendly message", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		await assert.rejects(
+			call(makeReplaceTool(dir), { path: "f.txt", find: "(unclosed", replace: "x", regex: true }),
+			/invalid regex/,
+		);
+	});
+});
+
+test("replace: invalid flag char throws", async () => {
+	await withDir(async (dir) => {
+		await writeFile(join(dir, "f.txt"), "a\n");
+		await assert.rejects(
+			call(makeReplaceTool(dir), { path: "f.txt", find: "a", replace: "x", flags: "z" }),
+			/invalid regex flag/,
+		);
+	});
+});
+
+test("replace: count-but-no-net-change does not rewrite and reports it", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "xx\n");
+		// $& = whole match = "x", so the text is unchanged despite 2 matches
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "x", replace: "$&", regex: true });
+		assert.equal(r.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "xx\n");
+		assert.match(r.content[0].text, /no net change/);
+	});
+});
+
+test("replace: returns details.diff (string) + patch + firstChangedLine", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "b", replace: "B" });
+		assert.equal(typeof r.details.diff, "string");
+		assert.equal(typeof r.details.patch, "string");
+		assert.equal(typeof r.details.firstChangedLine, "number");
+	});
+});
+
+test("replace: returns fresh anchors for the changed region", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "b", replace: "B" });
+		const out: string = r.content[0].text;
+		assert.match(out, /Updated anchors/);
+		// line 2 now holds "B"; its anchor must be present and correct
+		const a2 = anchorLine(out, 2);
+		assert.ok(a2.hash.length >= 2);
+	});
+});
+
+test("replace: changed-region anchor chains a subsequent hashline edit without a re-read", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "old old old\n");
+		const replace = makeReplaceTool(dir);
+		const r1: any = await call(replace, { path: "f.txt", find: "old", replace: "new" });
+		const out: string = r1.content[0].text;
+		// line 1 is the changed line; chain an edit on its returned anchor
+		const a1 = anchorLine(out, 1);
+		const edit = makeEditOverride(dir);
+		const r2: any = await call(edit, {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: a1, body: ["NEW NEW NEW"] }],
+		});
+		assert.equal(r2.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "NEW NEW NEW\n");
+	});
+});
+
+test("replace: multiline replacement (changes line count) still reports a correct span", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		// replace "b" with two lines → line count grows; changed region must cover the insertion
+		const r: any = await call(makeReplaceTool(dir), { path: "f.txt", find: "b", replace: "B1\nB2" });
+		assert.equal(await readFile(f, "utf-8"), "a\nB1\nB2\nc\n");
+		const out: string = r.content[0].text;
+		// the two inserted/changed lines (2 and 3) should both be anchored
+		assert.doesNotThrow(() => anchorLine(out, 2));
+		assert.doesNotThrow(() => anchorLine(out, 3));
+	});
+});
+
+test("replace renderResult: renders the diff without throwing", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\nc\n");
+		const tool = makeReplaceTool(dir);
+		const r: any = await call(tool, { path: "f.txt", find: "b", replace: "B" });
+		// @ts-ignore — drive the renderer with a stub theme
+		const comp: any = tool.renderResult(
+			{ content: r.content, details: r.details },
+			{ isPartial: false, expanded: true },
+			stubTheme,
+			{ isError: r.isError ?? false },
+		);
+		assert.ok(typeof comp?.text === "string");
+		assert.ok(comp.text.includes("B"), "rendered diff should contain the new content");
+	});
+});
+
+test("replace renderResult: renders the error line without throwing", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\n");
+		const tool = makeReplaceTool(dir);
+		let thrown: any;
+		const r: any = await call(tool, { path: "f.txt", find: "zzz", replace: "y" }).catch((e: any) => {
+			thrown = e;
+			return null;
+		});
+		assert.ok(thrown, "expected the call to throw");
+		// @ts-ignore — simulate how the framework hands the thrown message to renderResult
+		const comp: any = tool.renderResult(
+			{ content: [{ type: "text", text: thrown.message }] },
+			{ isPartial: false, expanded: false },
+			stubTheme,
+			{ isError: true },
+		);
+		assert.ok(typeof comp?.text === "string");
+	});
+});
+
+test("replace: refuses and leaves the file untouched when hashlineEdit is disabled", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "a\nb\na\n");
+		const state = getState();
+		const saved = state.config;
+		state.config = { ...saved, enabled: false };
+		try {
+			await assert.rejects(
+				call(makeReplaceTool(dir), { path: "f.txt", find: "a", replace: "b" }),
+				/disabled/,
+			);
+			assert.equal(await readFile(f, "utf-8"), "a\nb\na\n", "file untouched when disabled");
+		} finally {
+			state.config = saved;
+		}
+	});
+});