pi-hashline-edit-pro 0.13.3 → 0.14.0

package/README.md

@@ -1,8 +1,8 @@
 # pi-hashline-edit-pro
 
-A [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) extension that replaces the built-in `read` and `edit` tools with a hash-anchored line-replacing workflow. Strict semantics, no silent relocation, no autocorrection, no fuzzy fallback. 3-character content hashes over a 64-character URL-safe base64 alphabet give 18 bits of entropy per anchor, with perfect hashing (collision resolution) ensuring every line gets a unique anchor.
+A [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) extension that replaces the built-in `read` and `edit` tools with a hash-anchored line-replacing workflow. Strict semantics, no silent relocation, no autocorrection, no fuzzy fallback. Every line gets a unique content hash, so edits stay precise and stale anchors are caught before they reach the file.
 
-Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW. The strict-semantics policy is unchanged. This fork extends the upstream design in two ways: a 3-character hash length with a 64-character alphabet for more entropy, and perfect hashing (collision resolution) that ensures every line in a file gets a unique anchor.
+Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW. The strict-semantics policy is unchanged. This fork extends the upstream design with 3-character hashes and collision resolution for unique per-line anchors.
 
 Every line returned by `read` carries a short content hash. Edits reference those hashes instead of raw text, so the tool can detect stale context and reject outdated changes before they reach the file.
 
@@ -12,8 +12,8 @@ The original uses 2-character hashes of a 16-character alphabet, with the hash b
 
 This fork makes two changes that compound:
 
-1. **Bump hash length to 3 characters** of the 64-char URL-safe base64 alphabet. That gives 18 bits / 262,144 buckets, up from 8 bits / 256 in the upstream.
-2. **Perfect hashing (collision resolution).** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the hash is incremented (using a retry counter: `:R{retry}`) until a unique hash is found. This ensures every line in a file gets a unique anchor, even with the shorter 3-character hash space. Two byte-identical lines (e.g. repeated `import` statements, repeated `}`) get different hashes automatically.
+1. **3-character hash length** over a 64-char URL-safe base64 alphabet (up from 2 characters in the upstream), expanding the hash space from 256 to 262,144 buckets.
+2. **Perfect hashing (collision resolution).** When computing hashes for a file, if a line's base hash collides with an already-assigned hash, the hash is incremented (using a retry counter: `:R{retry}`) until a unique hash is found. This ensures every line gets a unique anchor, even within a 3-character hash space. Two byte-identical lines (e.g. repeated `}` or repeated `import` statements) get different hashes automatically.
 
 ## Installation
 
@@ -49,7 +49,7 @@ szJ│  console.log("world");
 _zl│}
 ```
 
-- `HASH` is a 3-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3`).
+- `HASH` is a 3-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3`). See [Hashing](#hashing) for details.
 
 Optional parameters:
 
@@ -60,7 +60,9 @@ Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not parti
 
 ### `replace` -- hash-anchored modifications
 
-Replaces using the `HASH│content` anchors from `read` output to target lines precisely:
+Replaces using the `HASH│content` anchors from `read` output to target lines precisely. Two modes are available, toggled via `/toggle-replace-mode` (persists across sessions):
+
+**Bulk mode (default):** `hash_range_inclusive` and `content_lines` go inside a `changes` array, supporting multiple edits in one call.
 
 ```json
 {
@@ -71,18 +73,28 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 }
 ```
 
+**Flat mode:** `hash_range_inclusive` and `content_lines` sit at the top level. Only one edit per call.
+
+```json
+{
+  "path": "src/main.ts",
+  "hash_range_inclusive": ["ve7", "ve7"],
+  "content_lines": ["  console.log('hashline');"]
+}
+```
+
 | Field | Description |
 | --- | --- |
 | `hash_range_inclusive` | Inclusive line range `[start_hash, end_hash]` (required). |
 | `content_lines` | Literal replacement content, one string per line (use `[]` to delete the range). |
 
-- **Request structure validation.** The request envelope (`path`, `changes`) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
+- **Request structure validation.** The request envelope (`path`, `changes` in bulk mode; `path`, `hash_range_inclusive`, `content_lines` in flat mode) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_REF]`.
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
-- **Batched atomicity.** All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
+- **Batched atomicity (bulk mode).** All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so the hashes from a single `read` call remain valid across all edits in the batch.
 
 ### Chained edits
 
-After a successful replace, the response text is empty (warnings are still shown if present). To get fresh anchors for follow-up edits, call `read` on the file first. This avoids token overhead from re-displaying content the model already knows.
+After a successful replace, the response confirms with `Successfully replaced in {path}.` (warnings are still shown if present). To get fresh anchors for follow-up edits, call `read` on the file first. This avoids token overhead from re-displaying content the model already knows.
 
 ### Auto-read after write
 
@@ -91,7 +103,7 @@ Auto-read is **disabled by default**. When enabled, after a successful `write` t
 1. `write` a file, result includes hashline anchors
 2. `replace` using those anchors directly
 
-Toggle at runtime with the `/toggle-auto-read` command. The current state persists for the session.
+Toggle at runtime with the `/toggle-auto-read` command. The setting persists across sessions in the config file (`~/.config/pi-hashline-edit-pro/config.json`). Set `PI_HASHLINE_AUTO_READ=1` to enable by default on first run.
 
 For large files (>2000 lines), the auto-read output is truncated with a pagination hint. Use `read` with `offset` to see more.
 
@@ -99,6 +111,26 @@ For large files (>2000 lines), the auto-read output is truncated with a paginati
 
 The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details.diff`. It is intentionally not in the LLM-visible text. The model already knows what it changed and can call `read` for fresh anchors when needed.
 
+### Commands
+
+| Command | Description |
+| --- | --- |
+| `/toggle-replace-mode` | Switch between bulk mode (`changes` array) and flat mode (top-level fields). Persists across sessions. |
+| `/toggle-auto-read` | Toggle automatic hashline anchors after write operations. Persists across sessions. |
+
+### Config file
+
+Settings are stored in `~/.config/pi-hashline-edit-pro/config.json`:
+
+```json
+{
+  "replaceMode": "bulk",
+  "autoRead": false
+}
+```
+
+The file is created automatically when any setting is toggled. Both fields are independent — toggling one never clobbers the other.
+
 ## Design Decisions
 
 - **Stale anchors fail (per-line).** A hash mismatch means that specific line's content changed since the last `read`; the error tells the model to call `read()` to get fresh anchors, then copy the 3-character HASH of the start and end of the range being replaced into `hash_range_inclusive` of the next replace call. Because staleness is per-line, editing or appending lines does **not** invalidate anchors for lines whose content is unchanged — anchors for untouched regions stay valid across edits to other regions.
@@ -107,6 +139,7 @@ The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details
 - **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 - **Boundary duplication warnings.** When the last line of a replacement matches the next surviving line (or the first line matches the preceding one), a warning is emitted. This catches a common LLM pattern where closing delimiters like `}`, `});`, or `} else {` are accidentally duplicated. The warning is a short header followed by a hashline-anchored window: the duplicated pair plus 2 lines of context before and after, shown as plain `HASH│content` rows with post-edit hashes. Seeing the duplication in context (rather than just being told a hash) is what prompts the model to act on it — and since the hashes are current and staleness is per-line, the model can remove the duplicate in one follow-up `replace` without re-reading. No autocorrection is applied — the duplicate stays in the file and the model decides whether to remove it. Raw line comparison (not trimmed) avoids false positives when indentation differs.
+- **Flat mode normalization.** When flat mode is active, the tool's `execute` function wraps the top-level `hash_range_inclusive` and `content_lines` into a single-element `changes` array internally, then runs the same pipeline as bulk mode. The `normReq` function in `replace-normalize.ts` also handles flat format directly, so any code path that normalizes input (e.g. `compPreview`) works with both formats.
 
 ## Hashing
 
@@ -122,7 +155,7 @@ The runtime always precomputes the full per-line hash array for a file via `line
 
 ### Bare-prefix detector
 
-With the `│` delimiter format, the bare-prefix detector regex `^\s*[A-Za-z0-9_\-]{3}│` is highly specific. It only matches lines starting with exactly 3 base64 chars and `│`. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
+With the `│` delimiter format, the bare-prefix detector regex `^\s*[A-Za-z0-9_\-]{3}│` is highly specific. It only matches lines starting with a hash-like prefix. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. The detector rejects edit lines matching this pattern with `[E_BARE_HASH_PREFIX]` to prevent the model from accidentally pasting hash anchors into file content.
 
 ## Development
 
@@ -135,7 +168,7 @@ npm test
 
 Set `PI_HASHLINE_DEBUG=1` to show an "active" notification at session start.
 
-Set `PI_HASHLINE_AUTO_READ=1` to enable auto-read after write by default (can still be toggled at runtime with `/toggle-auto-read`).
+Set `PI_HASHLINE_AUTO_READ=1` to enable auto-read after write by default on first run (can still be toggled at runtime with `/toggle-auto-read`; the setting persists across sessions once toggled).
 
 ## Credits
 

package/index.ts

@@ -3,33 +3,76 @@ import { readFile } from "fs/promises";
 import { join, isAbsolute } from "path";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
+import { regReplaceFlat } from "./src/replace-flat";
 import { regRead, fmtReadPreview } from "./src/read";
 import { toLF, stripBOM } from "./src/replace-diff";
 import { visLines } from "./src/utils";
 import { AUTO_READ_MAX } from "./src/constants";
+import {
+  readReplaceMode,
+  toggleReplaceMode,
+  readAutoRead,
+  toggleAutoRead,
+} from "./src/config";
 
 export default function (pi: ExtensionAPI): void {
   regRead(pi);
+
+  // 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);
 
   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;
+  let autoRead = autoReadValue === "1" || autoReadValue === "true";
 
   pi.on("session_start", async (_event, ctx) => {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
     await initHasher();
+
+    // Re-register the replace tool according to the persisted mode
+    const mode = await readReplaceMode();
+    if (mode === "flat") {
+      regReplaceFlat(pi);
+    } else {
+      regReplace(pi);
+    }
+
+    // Read the persisted auto-read setting (overrides env var default)
+    autoRead = await readAutoRead();
+
     if (debugValue === "1" || debugValue === "true") {
-      ctx.ui.notify("Hashline Edit mode active", "info");
+      ctx.ui.notify(`Hashline Edit mode active (${mode} replace)`, "info");
     }
   });
 
-  const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
-  let autoRead = autoReadValue === "1" || autoReadValue === "true";
+  pi.registerCommand("toggle-replace-mode", {
+    description: "Toggle replace tool between bulk (changes array) and flat (single edit at top level) mode",
+    handler: async (_args, ctx) => {
+      const mode = await toggleReplaceMode();
+      // Re-register the tool with the new mode
+      if (mode === "flat") {
+        regReplaceFlat(pi);
+      } else {
+        regReplace(pi);
+      }
+      ctx.ui.notify(`Replace mode switched to: ${mode}`, "info");
+    },
+  });
 
   pi.registerCommand("toggle-auto-read", {
     description: "Toggle automatic hashline anchors after write operations",
     handler: async (_args, ctx) => {
-      autoRead = !autoRead;
+      autoRead = await toggleAutoRead();
+      // Re-register the tool so prompts reflect the new auto-read setting
+      const mode = await readReplaceMode();
+      if (mode === "flat") {
+        regReplaceFlat(pi);
+      } else {
+        regReplace(pi);
+      }
       const state = autoRead ? "enabled" : "disabled";
       ctx.ui.notify(`Auto-read after write: ${state}`, "info");
     },
@@ -63,5 +106,4 @@ export default function (pi: ExtensionAPI): void {
       console.error("Auto-read after write failed:", error);
     }
   });
-
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.13.3",
+  "version": "0.14.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-guidelines.md

@@ -0,0 +1,4 @@
+- Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
+- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
+- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
+- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.

package/prompts/replace-bulk-snippet.md

@@ -0,0 +1 @@
+Replace lines in a text file via HASH anchors from read, batching all changes to a file in one call

package/prompts/replace-bulk.md

@@ -0,0 +1,130 @@
+Replace lines in a text file using HASH anchors from `read`.
+
+Put all operations on one file in a single `replace` call. Stack every region into the `changes` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot.
+
+How to use:
+
+1. Call `read` to get HASH anchors:
+```
+read({ path: "src/main.ts" })
+```
+
+2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
+```json
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+] }
+```
+
+Examples:
+
+1. Single line replace:
+```json
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+] }
+```
+
+2. Range replace (3 lines → 3 new lines):
+```json
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
+    "function greet(name) {",
+    "  return `Hello, ${name}`;",
+    "}"
+  ] }
+] }
+```
+
+3. Multiple regions in one call (delete two non-adjacent ranges):
+```json
+{ "path": "src/server.ts", "changes": [
+  { "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] },
+  { "hash_range_inclusive": ["MQX", "ZPM"], "content_lines": [] }
+] }
+```
+
+4. Append after the last line (include the old last line so the new line is added after it):
+```json
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+] }
+```
+
+5. Seed content into an empty file (replace the single empty-line hash returned by read):
+```json
+{ "path": "src/main.ts", "changes": [
+  { "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+] }
+```
+
+⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
+
+Wrong:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
+```
+
+Right:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
+```
+
+`hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
+
+⚠️ Common mistake: `hash_range_inclusive` is only the 3-character HASH, not the full `HASH│content` line.
+
+Wrong:
+```json
+{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
+```
+
+Right:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
+```
+
+Rules:
+- `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
+- To delete a range, use `content_lines: []`.
+- `hash_range_inclusive` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
+- `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix. A line that happens to start with `+` or `-` is written as-is; the only rejected form is the diff preview's `+HASH│…` row (see `[E_INVALID_PATCH]`).
+- Don't add `""` for spacing unless you actually want a new blank line.
+- 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}}
+
+⚠️ 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:
+```
+function greet() {
+  const x = 1;
+  return x;
+}
+```
+A model might write:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
+```
+This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
+
+Right: Only include the new lines that belong in the range:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
+```
+The `}` on line 4 is outside the range and stays in place.
+
+Error recovery:
+- `[E_STALE_ANCHOR]` — the anchored line's content changed since the last read. Call `read` to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into `hash_range_inclusive` and retry. (Staleness is per-line: editing or appending lines does not invalidate anchors for lines whose content is unchanged, so anchors for untouched regions stay valid across edits.)
+- `[E_BAD_REF]` — malformed HASH. Re-read and try again.
+- `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
+- `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
+- `[E_EDIT_CONFLICT]` — two changes overlap on the same line range. Make changes non-overlapping.
+- `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
+- `[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.

package/prompts/replace-flat-guidelines.md

@@ -0,0 +1,4 @@
+- Use `replace` with HASH anchors for all file changes. Only one edit per call (flat mode — no `changes` array).
+- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
+- On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
+- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.

package/prompts/replace-flat-snippet.md

@@ -0,0 +1 @@
+Replace lines in a text file via HASH anchors from read, one edit per call (flat mode)

package/prompts/replace-flat.md

@@ -0,0 +1,113 @@
+Replace lines in a text file using HASH anchors from `read`. Only one edit per call (no bulk `changes` array — `hash_range_inclusive` and `content_lines` sit at the top level).
+
+How to use:
+
+1. Call `read` to get HASH anchors:
+```
+read({ path: "src/main.ts" })
+```
+
+2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+```
+
+Examples:
+
+1. Single line replace:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+```
+
+2. Range replace (3 lines → 3 new lines):
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
+  "function greet(name) {",
+  "  return `Hello, ${name}`;",
+  "}"
+] }
+```
+
+3. Delete a range:
+```json
+{ "path": "src/server.ts", "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] }
+```
+
+4. Append after the last line (include the old last line so the new line is added after it):
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+```
+
+5. Seed content into an empty file (replace the single empty-line hash returned by read):
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+```
+
+⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
+
+Wrong:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["F4T│import { x } from \"./x\";"] }
+```
+
+Right:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": ["import { x } from \"./x\";"] }
+```
+
+`hash_range_inclusive` uses the hash anchor. `content_lines` uses literal file content only — the same text that appears after the `│` in `read` output.
+
+⚠️ Common mistake: `hash_range_inclusive` is only the 3-character HASH, not the full `HASH│content` line.
+
+Wrong:
+```json
+{ "hash_range_inclusive": ["F4T│import { x } from \"./x\";", "F4T│import { x } from \"./x\";"], "content_lines": [...] }
+```
+
+Right:
+```json
+{ "hash_range_inclusive": ["F4T", "F4T"], "content_lines": [...] }
+```
+
+Rules:
+- `hash_range_inclusive` is a pair `[start, end]`. A single-line replace is `hash_range_inclusive: ["X", "X"]`.
+- To delete a range, use `content_lines: []`.
+- `hash_range_inclusive` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
+- `content_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix. A line that happens to start with `+` or `-` is written as-is; the only rejected form is the diff preview's `+HASH│…` row (see `[E_INVALID_PATCH]`).
+- Don't add `""` for spacing unless you actually want a new blank line.
+- 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}}
+
+⚠️ 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:
+```
+function greet() {
+  const x = 1;
+  return x;
+}
+```
+A model might write:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;", "}"] }
+```
+This produces `function greet() {\n  const y = 2;\n  return y;\n}\n}` — the `}` appears twice because it was already on line 4 (outside the range) AND in `content_lines`.
+
+Right: Only include the new lines that belong in the range:
+```json
+{ "hash_range_inclusive": ["X", "Y"], "content_lines": ["  const y = 2;", "  return y;"] }
+```
+The `}` on line 4 is outside the range and stays in place.
+
+Error recovery:
+- `[E_STALE_ANCHOR]` — the anchored line's content changed since the last read. Call `read` to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into `hash_range_inclusive` and retry. (Staleness is per-line: editing or appending lines does not invalidate anchors for lines whose content is unchanged, so anchors for untouched regions stay valid across edits.)
+- `[E_BAD_REF]` — malformed HASH. Re-read and try again.
+- `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
+- `[E_BAD_SHAPE]` — malformed request or change item (missing fields, wrong types, unknown fields).
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` or `old_text`/`new_text` format detected. Use `{hash_range_inclusive, content_lines}` instead.
+- `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
+- `[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.

package/prompts/replace-guidelines.md

@@ -1,4 +1,5 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
-- After a successful `replace`, the response text is empty (warnings only). Call `read` to get fresh anchors for follow-up edits.
+- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
-- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
+- `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
+- Two modes are available: bulk (default, uses `changes` array) and flat (top-level `hash_range_inclusive`/`content_lines`). Toggle with `/toggle-replace-mode`.

package/prompts/replace-snippet.md

@@ -1 +1 @@
-Replace lines in a text file via HASH anchors from read, batching all changes to a file in one call
+Replace lines in a text file via HASH anchors from read, batching all changes to a file in one call. Supports bulk mode (changes array) and flat mode (top-level fields), toggled via /toggle-replace-mode.

package/prompts/replace.md

@@ -1,5 +1,13 @@
 Replace lines in a text file using HASH anchors from `read`.
 
+Two modes are available, toggled via `/toggle-replace-mode` (persists across sessions):
+
+**Bulk mode (default):** `hash_range_inclusive` and `content_lines` go inside a `changes` array, supporting multiple edits in one call.
+
+**Flat mode:** `hash_range_inclusive` and `content_lines` sit at the top level. Only one edit per call.
+
+---
+
 Put all operations on one file in a single `replace` call. Stack every region into the `changes` array, even when they are far apart. Anchors within one call must all come from the same pre-edit read; the runtime applies them atomically against that one snapshot.
 
 How to use:
@@ -10,33 +18,58 @@ read({ path: "src/main.ts" })
 ```
 
 2. Copy the 3-character HASH (before `│`) into `hash_range_inclusive`:
+
+**Bulk mode:**
 ```json
 { "path": "src/main.ts", "changes": [
   { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
 ] }
 ```
 
+**Flat mode:**
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 99;"] }
+```
+
 Examples:
 
 1. Single line replace:
+
+Bulk:
 ```json
 { "path": "src/main.ts", "changes": [
   { "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
 ] }
 ```
 
+Flat:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["MQX", "MQX"], "content_lines": ["const x = 1;"] }
+```
+
 2. Range replace (3 lines → 3 new lines):
+
+Bulk:
 ```json
 { "path": "src/main.ts", "changes": [
   { "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
-  }
+  ] }
+] }
+```
+
+Flat:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "VRW"], "content_lines": [
+  "function greet(name) {",
+  "  return `Hello, ${name}`;",
+  "}"
 ] }
 ```
 
-3. Multiple regions in one call (delete two non-adjacent ranges):
+3. Multiple regions in one call (bulk mode only — flat mode supports one edit per call):
 ```json
 { "path": "src/server.ts", "changes": [
   { "hash_range_inclusive": ["aB3", "xY7"], "content_lines": [] },
@@ -46,20 +79,32 @@ Examples:
 
 4. Append after the last line (include the old last line so the new line is added after it):
 
+Bulk:
 ```json
 { "path": "src/main.ts", "changes": [
   { "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
 ] }
 ```
 
+Flat:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["ZPM", "ZPM"], "content_lines": ["old last line", "new line"] }
+```
+
 5. Seed content into an empty file (replace the single empty-line hash returned by read):
 
+Bulk:
 ```json
 { "path": "src/main.ts", "changes": [
   { "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
 ] }
 ```
 
+Flat:
+```json
+{ "path": "src/main.ts", "hash_range_inclusive": ["aB3", "aB3"], "content_lines": ["first line", "second line"] }
+```
+
 ⚠️ Common mistake: do not copy the `HASH│` prefix into `content_lines`.
 
 Wrong:
@@ -96,7 +141,7 @@ 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). Call `read` to get fresh anchors for follow-up edits.
+On success, the response text is empty (or contains only 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.
 
@@ -129,4 +174,4 @@ Error recovery:
 - `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
 - `[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.
+- `[E_WOULD_EMPTY]` — edit would empty a non-empty file.