@jerryan/pi-hashline-edit 0.7.2 → 0.7.4

package/README.md

@@ -15,7 +15,7 @@ This is a fork of the original [pi-hashline-edit](https://github.com/earendil-wo
 - **Single edit shape.** One entry type: `{ range: [start, end], lines: [...] }`. No `op` field, no `append`/`prepend`/`replace_text` ops, no `after`/`before`. The tuple enforces explicit endpoint anchors, eliminating the common "forgot `end`" failure mode.
 - **Standard hex hash alphabet.** `0-9 A-F` instead of `ZPMQVRWSNKTXJBYH`. Hex pairs are more likely to be single tokens.
 - **Symmetric boundary-duplication detection.** Runtime warnings catch duplicated boundary lines on both sides of a replacement, not just trailing.
-- **`read` raw mode.** `raw: true` returns plain text without `LINE#HASH:` anchors, for reads that don't plan to edit.
+- **`read` raw mode.** `raw: true` returns plain text without `LINE#HASH│` anchors, for reads that don't plan to edit.
 - **Inline FNV-1a hashing.** Replaces `xxhashjs` dependency. Always incorporates line index.
 - **Minimal prompt surface.** Prompt text describes what the model needs to use the tool; return-format documentation and error catalogues are omitted.
 - **No legacy compatibility.** The `{ oldText, newText }` substring-replace format is not accepted. The schema is hashline-only.
@@ -34,12 +34,12 @@ pi install /path/to/pi-hashline-edit
 
 ### `read` — tagged line output
 
-Text files are returned with a `LINE#HASH:` prefix on every line. Line numbers may be left-padded within each returned block so the `#HASH:` columns align:
+Text files are returned with a `LINE#HASH│` prefix on every line. Line numbers may be left-padded within each returned block so the `#HASH│` columns align:
 
 ```text
- 8#A4:function hello() {
- 9#3F:  console.log("world");
-10#B2:}
+ 8#A4│function hello() {
+ 9#3F│  console.log("world");
+10#B2│}
 ```
 
 - `LINE` — 1-indexed line number.
@@ -80,22 +80,22 @@ After a successful edit, the response contains a unified diff where context and
 Each edit result shows a unified diff with hashline-formatted lines:
 
 ```text
- 8#A4:function hello() {
--9   :  console.log("world");
-+9#B1:  console.log("hashline");
-10#B2:}
+ 8#A4│function hello() {
+-9   │  console.log("world");
++9#B1│  console.log("hashline");
+10#B2│}
 ```
 
-- Context lines: ` NN#HH:content` (space prefix)
-- Removed lines: `-NN   :content` (no hash, aligned colon)
-- Added lines: `+NN#HH:content` (hash for new anchors)
+- Context lines: ` NN#HH│content` (space prefix)
+- Removed lines: `-NN   │content` (no hash, aligned separator)
+- Added lines: `+NN#HH│content` (hash for new anchors)
 - Multiple hunks are shown when edits are far apart.
 
 ## Design Decisions
 
 - **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes a snippet with fresh `LINE#HASH` references for the affected lines for immediate retry.
 - **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
-- **Strict patch content.** If `lines` contains `LINE#HASH:` display prefixes or diff `+`/`-` markers, the edit is rejected with `[E_INVALID_PATCH]`. The model must send literal file content; the runtime does not silently strip accidental prefixes.
+- **Strict patch content.** If `lines` contains `LINE#HASH│` display prefixes or diff `+`/`-` markers, the edit is rejected with `[E_INVALID_PATCH]`. The model must send literal file content; the runtime does not silently strip accidental prefixes.
 - **Full-file deletion guardrail.** Edits that would empty a file with more than 50 lines are rejected with `[E_WOULD_EMPTY]`. Small files show the full diff normally; large deletions are almost always mistakes.
 - **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.

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "@jerryan/pi-hashline-edit",
-  "version": "0.7.2",
-  "description": "Hashline read/edit tool override for pi-coding-agent",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/JerryAZR/pi-hashline-edit.git"
-  },
-  "author": "JerryAZR",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "coding-agent",
-    "extension",
-    "hashline"
-  ],
-  "license": "MIT",
-  "files": [
-    "index.ts",
-    "src",
-    "prompts",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "dependencies": {
-    "diff": "^8.0.2",
-    "file-type": "^21.3.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@types/node": "^22.0.0",
-    "ajv": "^8.20.0",
-    "vitest": "^3.0.0"
-  }
-}
+{
+  "name": "@jerryan/pi-hashline-edit",
+  "version": "0.7.4",
+  "description": "Hashline read/edit tool override for pi-coding-agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JerryAZR/pi-hashline-edit.git"
+  },
+  "author": "JerryAZR",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "hashline"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "tool-descriptions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "diff": "^8.0.2",
+    "file-type": "^21.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^22.0.0",
+    "ajv": "^8.20.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/edit-diff.ts

@@ -5,6 +5,8 @@ import {
   FUZZY_DOUBLE_QUOTES_RE,
   FUZZY_SINGLE_QUOTES_RE,
   FUZZY_UNICODE_SPACES_RE,
+  ANCHOR_SEP,
+  CONTENT_SEP,
 } from "./hashline";
 
 // ─── Line ending normalization ──────────────────────────────────────────
@@ -241,8 +243,7 @@ export function generateDiffString(
     newContent.split("\n").length,
   );
   const lineNumWidth = String(maxLineNum).length;
-  const hashPad = " ".repeat(3); // align with `#HH:`
-
+  const hashPad = " ".repeat(ANCHOR_SEP.length + 2); // align with `${ANCHOR_SEP}HH${CONTENT_SEP}`
   const output: string[] = [];
 
   for (let h = 0; h < patch.hunks.length; h++) {
@@ -262,17 +263,17 @@ export function generateDiffString(
 
       if (prefix === "-") {
         const padded = String(oldLineNum).padStart(lineNumWidth, " ");
-        output.push(`-${padded}${hashPad}:${text}`);
+        output.push(`-${padded}${hashPad}${CONTENT_SEP}${text}`);
         oldLineNum++;
       } else if (prefix === "+") {
         const padded = String(newLineNum).padStart(lineNumWidth, " ");
         const hash = computeLineHash(newLineNum, text);
-        output.push(`+${padded}#${hash}:${text}`);
+        output.push(`+${padded}${ANCHOR_SEP}${hash}${CONTENT_SEP}${text}`);
         newLineNum++;
       } else {
         const padded = String(newLineNum).padStart(lineNumWidth, " ");
         const hash = computeLineHash(newLineNum, text);
-        output.push(` ${padded}#${hash}:${text}`);
+        output.push(` ${padded}${ANCHOR_SEP}${hash}${CONTENT_SEP}${text}`);
         oldLineNum++;
         newLineNum++;
       }

package/src/edit-response.ts

@@ -6,6 +6,7 @@
  */
 
 import { generateDiffString } from "./edit-diff";
+import { PACKAGE_INFO } from "./package-info";
 
 // ─── Public types ───────────────────────────────────────────────────────
 
@@ -117,6 +118,7 @@ export function buildNoopResponse(input: NoopResponseInput): ToolResult {
       snapshotId,
       classification: "noop" as const,
       metrics,
+      package: PACKAGE_INFO,
     },
   };
 }
@@ -149,6 +151,7 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
       diff: diffResult.diff,
       snapshotId,
       metrics,
+      package: PACKAGE_INFO,
     },
   };
 }

package/src/edit.ts

@@ -17,6 +17,7 @@ import {
   applyHashlineEdits,
   resolveEditAnchors,
   type HashlineToolEdit,
+  ANCHOR_SEP,
 } from "./hashline";
 import { loadFileKindAndText } from "./file-kind";
 import { resolveToCwd } from "./path-utils";
@@ -29,7 +30,7 @@ const editEntrySchema = Type.Object(
   {
     range: Type.Tuple([Type.String(), Type.String()], {
       description:
-        'LINE#HASH anchor pair [start, end] copied from a recent `read` or `--- Anchors ---` block. Use the same anchor twice for single-line: ["42#A4", "42#A4"].',
+        `LINE${ANCHOR_SEP}HASH anchor pair [start, end] copied from a recent \`read\` or diff output. Use the same anchor twice for single-line: ["42${ANCHOR_SEP}A4", "42${ANCHOR_SEP}A4"].`,
     }),
     lines: Type.Array(Type.String(), {
       description: "New content lines. Use [] to delete.",
@@ -41,7 +42,7 @@ export const hashlineEditToolSchema = Type.Object(
   {
     path: Type.String({ description: "path" }),
     edits: Type.Array(editEntrySchema, {
-      description: "Edits to apply to $path. Each edit replaces the range [start, end] with lines. Use the same anchor twice for single-line; use [] to delete.",
+      description: `Edits to apply to $path. Each edit replaces the range [start, end] with lines. Use the same anchor twice for single-line; use [] to delete.`,
     }),
   },
   { additionalProperties: false },
@@ -67,15 +68,16 @@ type HashlineEditToolDetails = {
   snapshotId?: string;
   classification?: "noop";
   metrics?: EditMetrics;
+  package: { name: string; version: string };
 };
 
 const EDIT_DESC = readFileSync(
-  new URL("../prompts/edit.md", import.meta.url),
+  new URL("../tool-descriptions/edit.md", import.meta.url),
   "utf-8",
 ).trim();
 
 const EDIT_PROMPT_SNIPPET = readFileSync(
-  new URL("../prompts/edit-snippet.md", import.meta.url),
+  new URL("../tool-descriptions/edit-snippet.md", import.meta.url),
   "utf-8",
 ).trim();
 
@@ -268,12 +270,12 @@ export async function computeEditPreview(
     }
     if (file.kind === "image") {
       return {
-        error: `Path is an image file: ${path}. Hashline edit only supports UTF-8 text files.`,
+        error: `Path is an image file: ${path}. Hashline edit only supports text files.`,
       };
     }
     if (file.kind === "binary") {
       return {
-        error: `Path is a binary file: ${path} (${file.description}). Hashline edit only supports UTF-8 text files.`,
+        error: `Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
       };
     }
 
@@ -452,12 +454,12 @@ const editToolDefinition: EditToolDefinition = {
       }
       if (file.kind === "image") {
         throw new Error(
-          `Path is an image file: ${path}. Hashline edit only supports UTF-8 text files.`,
+          `Path is an image file: ${path}. Hashline edit only supports text files.`,
         );
       }
       if (file.kind === "binary") {
         throw new Error(
-          `Path is a binary file: ${path} (${file.description}). Hashline edit only supports UTF-8 text files.`,
+          `Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
         );
       }
 

package/src/file-kind.ts

@@ -36,27 +36,6 @@ function hasNullByte(buffer: Uint8Array): boolean {
   return buffer.includes(0);
 }
 
-function decodeUtf8Chunk(decoder: TextDecoder, buffer: Uint8Array): string | null {
-  try {
-    return decoder.decode(buffer, { stream: true });
-  } catch (error: unknown) {
-    if (error instanceof TypeError) {
-      return null;
-    }
-    throw error;
-  }
-}
-
-function finishUtf8(decoder: TextDecoder): string | null {
-  try {
-    return decoder.decode();
-  } catch (error: unknown) {
-    if (error instanceof TypeError) {
-      return null;
-    }
-    throw error;
-  }
-}
 
 export async function loadFileKindAndText(filePath: string): Promise<LoadedFile> {
   const pathStat = await fsStat(filePath);
@@ -96,16 +75,12 @@ export async function loadFileKindAndText(filePath: string): Promise<LoadedFile>
       };
     }
 
-    const decoder = new TextDecoder("utf-8", { fatal: true });
-    const parts: string[] = [];
-    const sampleText = decodeUtf8Chunk(decoder, sample);
-    if (sampleText === null) {
-      return {
-        kind: "binary",
-        description: "invalid UTF-8",
-      };
-    }
-    parts.push(sampleText);
+    // Non-fatal decode, matching pi's built-in tools: invalid UTF-8 becomes
+    // U+FFFD rather than rejecting the file. The null-byte guard above is the
+    // only signal we treat as binary, so non-UTF-8 text (CP1251, GBK, …) reads
+    // instead of forcing the model to bypass hashline with raw shell edits.
+    const decoder = new TextDecoder("utf-8");
+    const parts: string[] = [decoder.decode(sample, { stream: true })];
 
     let position = bytesRead;
     while (true) {
@@ -126,25 +101,13 @@ export async function loadFileKindAndText(filePath: string): Promise<LoadedFile>
           description: "null bytes detected",
         };
       }
-      const chunkText = decodeUtf8Chunk(decoder, chunk);
-      if (chunkText === null) {
-        return {
-          kind: "binary",
-          description: "invalid UTF-8",
-        };
-      }
-      parts.push(chunkText);
+      parts.push(decoder.decode(chunk, { stream: true }));
       position += chunkBytesRead;
     }
 
-    const tail = finishUtf8(decoder);
-    if (tail === null) {
-      return {
-        kind: "binary",
-        description: "invalid UTF-8",
-      };
-    }
-    parts.push(tail);
+    parts.push(decoder.decode());
+
+    return { kind: "text", text: parts.join("") };
 
     return { kind: "text", text: parts.join("") };
   } finally {

package/src/hashline.ts

@@ -39,6 +39,9 @@ const DICT = Array.from({ length: 256 }, (_, i) => {
   return `${HEX[h]}${HEX[l]}`;
 });
 
+export const ANCHOR_SEP = "#";
+export const CONTENT_SEP = "│";
+
 // FNV-1a 32-bit constants
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
@@ -48,10 +51,10 @@ const FNV_PRIME = 0x01000193;
  * payloads. The runtime no longer strips them — the model must send literal
  * file content. Matching any of these triggers `[E_INVALID_PATCH]`.
  */
-const HASHLINE_PREFIX_RE =
-  /^\s*(?:>>>|>>)?\s*(?:\d+\s*#\s*|#\s*)[0-9A-F]{2}:/;
-const HASHLINE_PREFIX_PLUS_RE =
-  /^\+\s*(?:\d+\s*#\s*|#\s*)[0-9A-F]{2}:/;
+const HASHLINE_PREFIX_RE = new RegExp(
+  `^\\s*(?:>>>|>>)?\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
+const HASHLINE_PREFIX_PLUS_RE = new RegExp(
+  `^\\+\\s*(?:\\d+\\s*${ANCHOR_SEP}\\s*|${ANCHOR_SEP}\\s*)?[0-9A-F]{2}${CONTENT_SEP}`);
 const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
 
 export function computeLineHash(idx: number, line: string): string {
@@ -90,16 +93,16 @@ function diagnoseLineRef(ref: string): string {
   const core = ref.replace(/^\s*[>+-]*\s*/, "").trim();
 
   if (!core.length) {
-    return `[E_BAD_REF] Invalid line reference "${ref}". Expected "LINE#HASH" (e.g. "5#MQ").`;
+    return `[E_BAD_REF] Invalid line reference "${ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
   }
   if (/^\d+\s*$/.test(core)) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash, use "LINE#HASH" from read output (e.g. "5#MQ").`;
+    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash, use "LINE${ANCHOR_SEP}HASH" from read output (e.g. "5${ANCHOR_SEP}MQ").`;
   }
-  if (/^\d+\s*:/.test(core)) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": wrong separator, use "LINE#HASH" instead of "LINE:...".`;
+  if (new RegExp(`^\d+\s*[:${CONTENT_SEP}]`).test(core)) {
+    return `[E_BAD_REF] Invalid line reference "${ref}": wrong separator, use "LINE${ANCHOR_SEP}HASH" instead of "LINE:..." or "LINE${CONTENT_SEP}...".`;
   }
 
-  const hashMatch = core.match(/^(\d+)\s*#\s*([^\s:]+)(?:\s*:.*)?$/);
+  const hashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*([^\s${CONTENT_SEP}]+)(?:\s*${CONTENT_SEP}.*)?$`));
   if (hashMatch) {
     const line = Number.parseInt(hashMatch[1]!, 10);
     const hash = hashMatch[2]!;
@@ -114,16 +117,16 @@ function diagnoseLineRef(ref: string): string {
     }
   }
 
-  const missingHashMatch = core.match(/^(\d+)\s*#\s*$/);
+  const missingHashMatch = core.match(new RegExp(`^(\d+)\s*${ANCHOR_SEP}\s*$`));
   if (missingHashMatch) {
-    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash after "#", use "LINE#HASH" from read output.`;
+    return `[E_BAD_REF] Invalid line reference "${ref}": missing hash after "${ANCHOR_SEP}", use "LINE${ANCHOR_SEP}HASH" from read output.`;
   }
 
-  if (/^0+\s*#/.test(core)) {
+  if (new RegExp(`^0+\s*${ANCHOR_SEP}`).test(core)) {
     return `[E_BAD_REF] Line number must be >= 1, got 0 in "${ref}".`;
   }
 
-  return `[E_BAD_REF] Invalid line reference "${trimmed || ref}". Expected "LINE#HASH" (e.g. "5#MQ").`;
+  return `[E_BAD_REF] Invalid line reference "${trimmed || ref}". Expected "LINE${ANCHOR_SEP}HASH" (e.g. "5${ANCHOR_SEP}MQ").`;
 }
 
 export function parseLineRef(ref: string): { line: number; hash: string } {
@@ -136,7 +139,7 @@ export function parseLineRef(ref: string): { line: number; hash: string } {
 
 function parseAnchorRef(ref: string): Anchor {
   const core = ref.replace(/^\s*[>+-]*\s*/, "").trimEnd();
-  const match = core.match(/^([0-9]+)\s*#\s*([^\s:]+)(?:\s*:(.*))?$/s);
+  const match = core.match(new RegExp(`^([0-9]+)\s*${ANCHOR_SEP}\s*([^\s${CONTENT_SEP}]+)(?:\s*${CONTENT_SEP}(.*))?$`, 's'));
   if (!match) {
     throw new Error(diagnoseLineRef(ref));
   }
@@ -203,9 +206,9 @@ function formatMismatchError(
   const sorted = [...displayLines].sort((a, b) => a - b);
   const maxDisplayLine = sorted[sorted.length - 1] ?? 1;
   const lineNumberWidth = String(maxDisplayLine).length;
-  const anchorList = uniqueMismatches.map((m) => `${m.line}#${m.expected}`).join(", ");
+  const anchorList = uniqueMismatches.map((m) => `${m.line}${ANCHOR_SEP}${m.expected}`).join(", ");
   const out: string[] = [
-    `[E_STALE_ANCHOR] ${uniqueMismatches.length} stale anchor${uniqueMismatches.length > 1 ? "s" : ""}: ${anchorList}. Retry with the >>> LINE#HASH lines below; keep both endpoints for range replaces.`,
+    `[E_STALE_ANCHOR] ${uniqueMismatches.length} stale anchor${uniqueMismatches.length > 1 ? "s" : ""}: ${anchorList}. Retry with the >>> LINE${ANCHOR_SEP}HASH lines below; keep both endpoints for range replaces.`,
     "",
   ];
 
@@ -215,11 +218,11 @@ function formatMismatchError(
     prev = num;
     const content = fileLines[num - 1];
     const hash = computeLineHash(num, content);
-    const prefix = `${String(num).padStart(lineNumberWidth, " ")}#${hash}`;
+    const prefix = `${String(num).padStart(lineNumberWidth, " ")}${ANCHOR_SEP}${hash}`;
     out.push(
       retryLineSet.has(num)
-        ? `>>> ${prefix}:${content}`
-        : `    ${prefix}:${content}`,
+        ? `>>> ${prefix}${CONTENT_SEP}${content}`
+        : `    ${prefix}${CONTENT_SEP}${content}`,
     );
   }
 
@@ -242,7 +245,7 @@ function assertNoDisplayPrefixes(lines: string[]): void {
       DIFF_MINUS_RE.test(line)
     ) {
       throw new Error(
-        `[E_INVALID_PATCH] "lines" must contain literal file content, not rendered "LINE#HASH:" or diff "+/-" prefixes. Offending line: ${JSON.stringify(line)}`,
+        `[E_INVALID_PATCH] "lines" must contain literal file content, not rendered "LINE${ANCHOR_SEP}HASH${CONTENT_SEP}" or diff "+/-" prefixes. Offending line: ${JSON.stringify(line)}`,
       );
     }
   }
@@ -435,15 +438,15 @@ function describeEdit(edit: HashlineEdit): string {
   switch (edit.op) {
     case "replace":
       return edit.end
-        ? `replace ${edit.pos.line}#${edit.pos.hash}-${edit.end.line}#${edit.end.hash}`
-        : `replace ${edit.pos.line}#${edit.pos.hash}`;
+        ? `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}-${edit.end.line}${ANCHOR_SEP}${edit.end.hash}`
+        : `replace ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`;
     case "append":
       return edit.pos
-        ? `append after ${edit.pos.line}#${edit.pos.hash}`
+        ? `append after ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`
         : "append at EOF";
     case "prepend":
       return edit.pos
-        ? `prepend before ${edit.pos.line}#${edit.pos.hash}`
+        ? `prepend before ${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`
         : "prepend at BOF";
     case "replace_text":
       return `replace_text \"${previewText(edit.oldText)}\"`;
@@ -575,7 +578,7 @@ function resolveEditToSpan(
       ) {
         noopEdits.push({
           editIndex: index,
-          loc: `${edit.pos.line}#${edit.pos.hash}`,
+          loc: `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}`,
           currentContent: originalLines.join("\n"),
         });
         return null;
@@ -627,7 +630,7 @@ function resolveEditToSpan(
       if (edit.lines.length === 0) {
         noopEdits.push({
           editIndex: index,
-          loc: edit.pos ? `${edit.pos.line}#${edit.pos.hash}` : "EOF",
+          loc: edit.pos ? `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}` : "EOF",
           currentContent: edit.pos ? fileLines[edit.pos.line - 1] ?? "" : "",
         });
         return null;
@@ -678,7 +681,7 @@ function resolveEditToSpan(
       if (edit.lines.length === 0) {
         noopEdits.push({
           editIndex: index,
-          loc: edit.pos ? `${edit.pos.line}#${edit.pos.hash}` : "BOF",
+          loc: edit.pos ? `${edit.pos.line}${ANCHOR_SEP}${edit.pos.hash}` : "BOF",
           currentContent: edit.pos ? fileLines[edit.pos.line - 1] ?? "" : "",
         });
         return null;
@@ -988,7 +991,7 @@ export function formatHashlineRegion(
     .map((line, index) => {
       const lineNumber = startLine + index;
       const paddedLineNumber = String(lineNumber).padStart(lineNumberWidth, " ");
-      return `${paddedLineNumber}#${computeLineHash(lineNumber, line)}:${line}`;
+      return `${paddedLineNumber}${ANCHOR_SEP}${computeLineHash(lineNumber, line)}${CONTENT_SEP}${line}`;
     })
     .join("\n");
 }

package/src/package-info.ts

@@ -0,0 +1,4 @@
+export const PACKAGE_INFO = {
+  name: "@jerryan/pi-hashline-edit",
+  version: "0.7.4",
+};

package/src/read.ts

@@ -1,230 +1,241 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  createReadTool,
-  formatSize,
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
-  truncateHead,
-  type TruncationResult,
-} from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { readFileSync } from "fs";
-import { access as fsAccess, readdir as fsReaddir } from "fs/promises";
-import { constants } from "fs";
-import { normalizeToLF, stripBom } from "./edit-diff";
-import { loadFileKindAndText } from "./file-kind";
-import { formatHashlineRegion } from "./hashline";
-import { resolveToCwd } from "./path-utils";
-import { throwIfAborted } from "./runtime";
-import { getFileSnapshot } from "./snapshot";
-
-const READ_DESC = readFileSync(
-  new URL("../prompts/read.md", import.meta.url),
-  "utf-8",
-)
-  .replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
-  .replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
-  .trim();
-
-const READ_PROMPT_SNIPPET = readFileSync(
-  new URL("../prompts/read-snippet.md", import.meta.url),
-  "utf-8",
-).trim();
-
-const READ_PROMPT_GUIDELINES = readFileSync(
-  new URL("../prompts/read-guidelines.md", import.meta.url),
-  "utf-8",
-)
-  .split("\n")
-  .map((line) => line.trim())
-  .filter((line) => line.startsWith("- "))
-  .map((line) => line.slice(2));
-
-function normalizePositiveInteger(
-  value: number | undefined,
-  name: "offset" | "limit",
-): number | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`Read request field "${name}" must be a positive integer.`);
-  }
-
-  return value;
-}
-
-function getPreviewLines(text: string): string[] {
-  if (text.length === 0) {
-    return [];
-  }
-
-  const lines = text.split("\n");
-  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
-}
-
-export function formatHashlineReadPreview(
-  text: string,
-  options: { offset?: number; limit?: number; raw?: boolean },
-): { text: string; truncation?: TruncationResult; nextOffset?: number } {
-  const allLines = getPreviewLines(text);
-  const totalLines = allLines.length;
-  const startLine = normalizePositiveInteger(options.offset, "offset") ?? 1;
-  if (totalLines === 0) {
-    if (startLine === 1) {
-      return {
-        text: "File is empty. Use edit with prepend or append and omit pos to insert content.",
-      };
-    }
-
-    return {
-      text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit with prepend or append and omit pos to insert content.`,
-    };
-  }
-
-  if (startLine > totalLines) {
-    return {
-      text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
-    };
-  }
-
-  const limit = normalizePositiveInteger(options.limit, "limit");
-  const endIdx = limit
-    ? Math.min(startLine - 1 + limit, totalLines)
-    : totalLines;
-  const selected = allLines.slice(startLine - 1, endIdx);
-  const formatted = options.raw ? selected.join("\n") : formatHashlineRegion(selected, startLine);
-
-  const truncation = truncateHead(formatted);
-  if (truncation.firstLineExceedsLimit) {
-    return {
-      text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}.${options.raw ? "" : " Hashline output requires full lines; cannot compute hashes for a truncated preview."}]`,
-
-      truncation,
-    };
-  }
-
-  let preview = truncation.content;
-  let nextOffset: number | undefined;
-  if (truncation.truncated) {
-    const endLineDisplay = startLine + truncation.outputLines - 1;
-    nextOffset = endLineDisplay + 1;
-    if (truncation.truncatedBy === "lines") {
-      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
-    } else {
-      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
-    }
-  } else if (endIdx < totalLines) {
-    nextOffset = endIdx + 1;
-    preview += `\n\n[Showing lines ${startLine}-${endIdx} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
-  }
-
-  return {
-    text: preview,
-    truncation: truncation.truncated ? truncation : undefined,
-    ...(nextOffset !== undefined ? { nextOffset } : {}),
-  };
-}
-
-export function registerReadTool(pi: ExtensionAPI): void {
-  pi.registerTool({
-    name: "read",
-    label: "Read",
-    description: READ_DESC,
-    promptSnippet: READ_PROMPT_SNIPPET,
-    promptGuidelines: READ_PROMPT_GUIDELINES,
-    parameters: Type.Object({
-      path: Type.String({
-        description: "Path to the file to read (relative or absolute)",
-      }),
-      offset: Type.Optional(
-        Type.Integer({
-          minimum: 1,
-          description: "Line number to start reading from (1-indexed)",
-        }),
-      ),
-      limit: Type.Optional(
-        Type.Integer({
-          minimum: 1,
-          description: "Maximum number of lines to read",
-        }),
-      ),
-      raw: Type.Optional(
-        Type.Boolean({
-          description: "Return raw text without LINE#HASH anchors, saving tokens. Don't use if you plan to edit this file.",
-        }),
-      ),
-    }),
-
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const rawPath = params.path;
-      const absolutePath = resolveToCwd(rawPath, ctx.cwd);
-
-      throwIfAborted(signal);
-      try {
-        await fsAccess(absolutePath, constants.R_OK);
-      } catch (error: unknown) {
-        const code = error instanceof Error
-          ? (error as NodeJS.ErrnoException).code
-          : undefined;
-        if (code === "ENOENT") {
-          throw new Error(`File not found: ${rawPath}`);
-        }
-        if (code === "EACCES" || code === "EPERM") {
-          throw new Error(`File is not readable: ${rawPath}`);
-        }
-        throw new Error(`Cannot access file: ${rawPath}`);
-      }
-
-      throwIfAborted(signal);
-      const file = await loadFileKindAndText(absolutePath);
-      if (file.kind === "directory") {
-        const entries = await fsReaddir(absolutePath);
-        const listing = entries
-          .slice(0, 50)
-          .map((name) => `  ${name}`)
-          .join("\n");
-        const cap = entries.length > 50 ? `\n  ... and ${entries.length - 50} more` : "";
-        throw new Error(
-          `Path is a directory: ${rawPath}\n${listing}${cap}\n\nUse ls to explore further or read a specific file.`,
-        );
-      }
-
-      if (file.kind === "binary") {
-        throw new Error(`Path is a binary file: ${rawPath} (${file.description}). Read only supports UTF-8 text files and supported images.`);
-      }
-
-      if (file.kind === "image") {
-        const builtinRead = createReadTool(ctx.cwd);
-        return builtinRead.execute(_toolCallId, params, signal, _onUpdate, ctx);
-      }
-
-      throwIfAborted(signal);
-      const normalized = normalizeToLF(stripBom(file.text).text);
-      const preview = formatHashlineReadPreview(normalized, {
-        offset: params.offset,
-        limit: params.limit,
-        raw: params.raw,
-      });
-      const snapshot = await getFileSnapshot(absolutePath);
-
-      return {
-        content: [{ type: "text", text: preview.text }],
-        details: {
-          truncation: preview.truncation,
-          // snapshotId remains in details for host UI (e.g. "file changed since
-          // last view"). It is NOT echoed in text — the LLM no longer needs it.
-          snapshotId: snapshot.snapshotId,
-          ...(preview.nextOffset !== undefined ? { nextOffset: preview.nextOffset } : {}),
-          // Phase 2 C — host-only observability. Truncated reads usually mean
-          // a follow-up read with `offset = next_offset` is coming.
-          metrics: {
-            truncated: !!preview.truncation,
-            ...(preview.nextOffset !== undefined ? { next_offset: preview.nextOffset } : {}),
-          },
-        },
-      };
-    },
-  });
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createReadTool,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { readFileSync } from "fs";
+import { access as fsAccess, readdir as fsReaddir } from "fs/promises";
+import { constants } from "fs";
+import { normalizeToLF, stripBom } from "./edit-diff";
+import { loadFileKindAndText } from "./file-kind";
+import { formatHashlineRegion } from "./hashline";
+import { resolveToCwd } from "./path-utils";
+import { throwIfAborted } from "./runtime";
+import { getFileSnapshot } from "./snapshot";
+import { PACKAGE_INFO } from "./package-info";
+
+const READ_DESC = readFileSync(
+  new URL("../tool-descriptions/read.md", import.meta.url),
+  "utf-8",
+)
+  .replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
+  .replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
+  .trim();
+
+const READ_PROMPT_SNIPPET = readFileSync(
+  new URL("../tool-descriptions/read-snippet.md", import.meta.url),
+  "utf-8",
+).trim();
+
+const READ_PROMPT_GUIDELINES = readFileSync(
+  new URL("../tool-descriptions/read-guidelines.md", import.meta.url),
+  "utf-8",
+)
+  .split("\n")
+  .map((line) => line.trim())
+  .filter((line) => line.startsWith("- "))
+  .map((line) => line.slice(2));
+
+function normalizePositiveInteger(
+  value: number | undefined,
+  name: "offset" | "limit",
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Read request field "${name}" must be a positive integer.`);
+  }
+
+  return value;
+}
+
+function getPreviewLines(text: string): string[] {
+  if (text.length === 0) {
+    return [];
+  }
+
+  const lines = text.split("\n");
+  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+}
+
+export function formatHashlineReadPreview(
+  text: string,
+  options: { offset?: number; limit?: number; raw?: boolean },
+): { text: string; truncation?: TruncationResult; nextOffset?: number } {
+  const allLines = getPreviewLines(text);
+  const totalLines = allLines.length;
+  const startLine = normalizePositiveInteger(options.offset, "offset") ?? 1;
+  if (totalLines === 0) {
+    if (startLine === 1) {
+      return {
+        text: "File is empty. Use edit with prepend or append and omit pos to insert content.",
+      };
+    }
+
+    return {
+      text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit with prepend or append and omit pos to insert content.`,
+    };
+  }
+
+  if (startLine > totalLines) {
+    return {
+      text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
+    };
+  }
+
+  const limit = normalizePositiveInteger(options.limit, "limit");
+  const endIdx = limit
+    ? Math.min(startLine - 1 + limit, totalLines)
+    : totalLines;
+  const selected = allLines.slice(startLine - 1, endIdx);
+  const formatted = options.raw ? selected.join("\n") : formatHashlineRegion(selected, startLine);
+
+  const truncation = truncateHead(formatted);
+  if (truncation.firstLineExceedsLimit) {
+    return {
+      text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}.${options.raw ? "" : " Hashline output requires full lines; cannot compute hashes for a truncated preview."}]`,
+
+      truncation,
+    };
+  }
+
+  let preview = truncation.content;
+  let nextOffset: number | undefined;
+  if (truncation.truncated) {
+    const endLineDisplay = startLine + truncation.outputLines - 1;
+    nextOffset = endLineDisplay + 1;
+    if (truncation.truncatedBy === "lines") {
+      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+    } else {
+      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+    }
+  } else if (endIdx < totalLines) {
+    nextOffset = endIdx + 1;
+    preview += `\n\n[Showing lines ${startLine}-${endIdx} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+  }
+
+  return {
+    text: preview,
+    truncation: truncation.truncated ? truncation : undefined,
+    ...(nextOffset !== undefined ? { nextOffset } : {}),
+  };
+}
+
+export function registerReadTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "read",
+    label: "Read",
+    description: READ_DESC,
+    promptSnippet: READ_PROMPT_SNIPPET,
+    promptGuidelines: READ_PROMPT_GUIDELINES,
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path to the file to read (relative or absolute)",
+      }),
+      offset: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "Line number to start reading from (1-indexed)",
+        }),
+      ),
+      limit: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "Maximum number of lines to read",
+        }),
+      ),
+      raw: Type.Optional(
+        Type.Boolean({
+          description: "Return raw text without LINE#HASH anchors, saving tokens. Don't use if you plan to edit this file.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const rawPath = params.path;
+      const absolutePath = resolveToCwd(rawPath, ctx.cwd);
+
+      throwIfAborted(signal);
+      try {
+        await fsAccess(absolutePath, constants.R_OK);
+      } catch (error: unknown) {
+        const code = error instanceof Error
+          ? (error as NodeJS.ErrnoException).code
+          : undefined;
+        if (code === "ENOENT") {
+          throw new Error(`File not found: ${rawPath}`);
+        }
+        if (code === "EACCES" || code === "EPERM") {
+          throw new Error(`File is not readable: ${rawPath}`);
+        }
+        throw new Error(`Cannot access file: ${rawPath}`);
+      }
+
+      throwIfAborted(signal);
+      const file = await loadFileKindAndText(absolutePath);
+      if (file.kind === "directory") {
+        const entries = await fsReaddir(absolutePath);
+        const listing = entries
+          .slice(0, 50)
+          .map((name) => `  ${name}`)
+          .join("\n");
+        const cap = entries.length > 50 ? `\n  ... and ${entries.length - 50} more` : "";
+        throw new Error(
+          `Path is a directory: ${rawPath}\n${listing}${cap}\n\nUse ls to explore further or read a specific file.`,
+        );
+      }
+
+      if (file.kind === "binary") {
+        throw new Error(`Path is a binary file: ${rawPath} (${file.description}). Read only supports text files and supported images.`);
+      }
+
+      if (file.kind === "image") {
+        const builtinRead = createReadTool(ctx.cwd);
+        return builtinRead.execute(_toolCallId, params, signal, _onUpdate, ctx);
+      }
+
+      throwIfAborted(signal);
+      const normalized = normalizeToLF(stripBom(file.text).text);
+      const preview = formatHashlineReadPreview(normalized, {
+        offset: params.offset,
+        limit: params.limit,
+        raw: params.raw,
+      });
+      const snapshot = await getFileSnapshot(absolutePath);
+
+      // A U+FFFD anywhere in the decoded text means the file held bytes that
+      // are not valid UTF-8 (CP1251, GBK, …). Editing rewrites the whole file
+      // as UTF-8, so those bytes are lost. Warn once on read — the model can
+      // then iconv the file back afterwards. Detect on the full text, not the
+      // paged slice, so an out-of-view bad byte still surfaces.
+      const previewText = normalized.includes("\uFFFD")
+        ? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
+        : preview.text;
+
+      return {
+        content: [{ type: "text", text: previewText }],
+        details: {
+          truncation: preview.truncation,
+          // snapshotId remains in details for host UI (e.g. "file changed since
+          // last view"). It is NOT echoed in text — the LLM no longer needs it.
+          snapshotId: snapshot.snapshotId,
+          ...(preview.nextOffset !== undefined ? { nextOffset: preview.nextOffset } : {}),
+          // Phase 2 C — host-only observability. Truncated reads usually mean
+          // a follow-up read with `offset = next_offset` is coming.
+          metrics: {
+            truncated: !!preview.truncation,
+            ...(preview.nextOffset !== undefined ? { next_offset: preview.nextOffset } : {}),
+          },
+          package: PACKAGE_INFO,
+        },
+      };
+    },
+  });
+}

package/{prompts → tool-descriptions}/edit.md

@@ -9,7 +9,7 @@ Each edit entry replaces an inclusive anchor range:
 - `range` — `[start, end]` pair of LINE#HASH anchors from the most recent `read` or diff output.
   Use the same anchor twice for single-line: `["42#A4", "42#A4"]`.
 - `lines` — new content replacing the range (string array). Use `[]` to delete.
-  Must be literal file content, not LINE#HASH-prefixed output. Match indentation exactly.
+  Must be literal file content, not LINE#HASH│-prefixed output. Match indentation exactly.
 
 Example:
 ```json

package/{prompts → tool-descriptions}/read.md

@@ -1,4 +1,4 @@
-Read a UTF-8 text file or a supported image. Text lines are prefixed `LINE#HASH:content` — copy those anchors verbatim into `edit`.
+Read a UTF-8 text file or a supported image. Text lines are prefixed `LINE#HASH│content` — copy those anchors verbatim into `edit`.
 
 Use `offset` and `limit` to page through. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}; when truncated, the tail of the output tells you the next `offset`.