pi-hashline-edit-pro 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # 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-editing workflow. **Strict semantics** — no silent relocation, no autocorrection, no fuzzy fallback. **Higher-entropy anchors** — `#`-prefixed 4-character content hashes over a 64-character URL-safe base64 alphabet (24 bits / 16 777 216 buckets) so birthday-paradox collisions are effectively zero in any realistic file.
+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-editing workflow. **Strict semantics** — no silent relocation, no autocorrection, no fuzzy fallback. **Higher-entropy anchors** — 4-character content hashes over a 64-character URL-safe base64 alphabet (24 bits / 16 777 216 buckets) so birthday-paradox collisions are effectively zero in any realistic file.
 
 This is a 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 compounding ways: a 4-character hash length and an occurrence-aware discriminator that makes identical content at different positions hash to different values.
 
@@ -29,7 +29,7 @@ pi install /path/to/pi-hashline-edit-pro
 
 ### `read` — tagged line output
 
-Text files are returned with a `#HASH:content` prefix on every line. The line number is no longer part of the wire format — only the `#`-prefixed 4-character hash followed by the line content. Example output for the source below; the hashes are the real xxHash-derived values for the file content shown:
+Text files are returned with a `HASH│content` prefix on every line. The line number is no longer part of the wire format — only the 4-character hash followed by the `│` separator and the line content. Example output for the source below; the hashes are the real xxHash-derived values for the file content shown:
 
 ```js
 function hello() {
@@ -40,12 +40,12 @@ function hello() {
 would be returned as:
 
 ```text
-#0qH3:function hello() {
-#szJr:  console.log("world");
-#_zlP:}
+0qH3│function hello() {
+szJr│  console.log("world");
+_zlP│}
 ```
 
-- `HASH` — `#`-prefixed 4-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `#aB3x`).
+- `HASH` — 4-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3x`).
 
 Optional parameters:
 
@@ -56,13 +56,13 @@ Images (JPEG, PNG, GIF, WebP) are passed through as attachments and do not parti
 
 ### `edit` — hash-anchored modifications
 
-Edits use the `#HASH:content` anchors from `read` output to target lines precisely:
+Edits use the `HASH│content` anchors from `read` output to target lines precisely:
 
 ```json
 {
   "path": "src/main.ts",
   "edits": [
-    { "op": "replace", "start": "#ve7o", "end": "#ve7o", "lines": ["  console.log('hashline');"] }
+    { "op": "replace", "start": "ve7o", "end": "ve7o", "lines": ["  console.log('hashline');"] }
   ]
 }
 ```
@@ -80,32 +80,33 @@ All edits in a single call validate against the same pre-edit snapshot and apply
 
 ### Chained edits
 
-After a successful edit, the result text contains an `--- Anchors ---` block with fresh `#HASH:content` references for the changed region. These can be used directly in the next `edit` call on the same file without a full re-read, provided the next edit targets the same or nearby lines. For distant changes, use `read` first.
+After a successful edit, the result text contains an `--- Anchors ---` block with fresh `HASH│content` references for the changed region. These can be used directly in the next `edit` call on the same file without a full re-read, provided the next edit targets the same or nearby lines. For distant changes, use `read` first.
 
 ### Auto-read after write
 
-After a successful `write`, the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `#HASH:content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
+After a successful `write`, the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH│content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
 
 1. `write` a file → result includes hashline anchors
 2. `edit` using those anchors directly
 
 For large files (>2000 lines), the auto-read output is truncated with a pagination hint. Use `read` with `offset` to see more.
+
 ### Diff for the host
 
-The post-edit diff (with `+`/`-` markers and new `#HASH:content` anchors) is exposed to the host UI via `details.diff`. It is intentionally **not** in the LLM-visible text — the model only needs the fresh anchors in `text` to chain follow-up edits, and re-emitting the diff would cost extra tokens.
+The post-edit diff (with `+`/`-` markers and new `HASH│content` anchors) is exposed to the host UI via `details.diff`. It is intentionally **not** in the LLM-visible text — the model only needs the fresh anchors in `text` to chain follow-up edits, and re-emitting the diff would cost extra tokens.
 
 ## Design Decisions
 
-- **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes fresh `>>> #HASH:content` lines for the affected region; the model copies the HASH portion and retries.
+- **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error includes fresh `>>> HASH│content` lines for the affected region; the model copies the HASH portion and retries.
 - **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 `+#HASH:` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `#HASH:` content (the first 6 chars of a `lines` entry looking like `#` + 4 base64 chars + `:`) is also rejected with `[E_BARE_HASH_PREFIX]` — issue #24. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output; the model should rephrase the line (quote it, escape the colon, or use a different identifier shape) and retry.
+- **Strict patch content.** If `lines` contains `+HASH│` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH│` content (the first 5 chars of a `lines` entry looking like 4 base64 chars + `│`) is also rejected with `[E_BARE_HASH_PREFIX]` — issue #24. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output; the model should rephrase the line (quote it, escape the separator, or use a different identifier shape) and retry.
 - **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect and `op: "replace_text"` are rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{op:"replace", start:"<HASH>", end:"<HASH>", lines:[...]}` (or `append`/`prepend` with `pos`).
 - **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.
 
 ## Hashing
 
-Hashes are computed with [xxhashjs](https://github.com/pierrec/js-xxhash) (xxHash32), then mapped to a `#`-prefixed 4-character string from the URL-safe base64 alphabet `A-Za-z0-9-_` — 64 distinct characters, 6 bits per position, **24 bits of entropy per anchor**.
+Hashes are computed with [xxhashjs](https://github.com/pierrec/js-xxhash) (xxHash32), then mapped to a 4-character string from the URL-safe base64 alphabet `A-Za-z0-9-_` — 64 distinct characters, 6 bits per position, **24 bits of entropy per anchor**.
 
 The alphabet is sized for an LLM consumer. The model tokenizes — it doesn't squint at pixel glyphs — so the human-readability heuristics used by smaller hand-curated alphabets (no G/L/I/O because they look like digits, no vowels so the hash doesn't accidentally spell a word, no hex digits so it can't be confused with `0xFF`) don't apply. The full 64 chars give maximum entropy per character, with case and digits included.
 
@@ -120,7 +121,7 @@ The runtime always precomputes the full per-line hash array for a file via `comp
 
 ### Trade-off: the bare-prefix detector
 
-With the `#` prefix format, the bare-prefix detector regex `^\s*#[A-Za-z0-9_-]{4}:` is highly specific — it only matches lines starting with `#` followed by exactly 4 base64 chars and `:`. This eliminates false positives from common code patterns like `init:`, `data:`, `else:`, etc. that plagued the old 4-char-only detector. 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_-]{4}│` is highly specific — it only matches lines starting with exactly 4 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.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Strict hashline read/edit tool override for pi-coding-agent with hash-anchored edits (4-char, 24-bit)",
   "repository": {
     "type": "git",

package/prompts/edit-snippet.md

@@ -1 +1 @@
-Edit a text file via #HASH anchors from read
+Edit a text file via HASH anchors from read

package/prompts/edit.md

@@ -1,8 +1,8 @@
-Patch a text file using `#HASH` anchors copied verbatim from `read`.
+Patch a text file using `HASH` anchors copied verbatim from `read`.
 
 Put all operations on one file in a single `edit` call. Stack every region into the `edits` 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, so you do not adjust anchors for line-number shifts between edits in the same call.
 
-Anchors are `#` + 4 characters (e.g. `#aB3x`), alphabet `A-Za-z0-9-_`. The wire format for `start`/`end`/`pos` is the anchor only — no line number, no trailing content, no line content.
+Anchors are 4 characters (e.g. `aB3x`), alphabet `A-Za-z0-9-_`. The wire format for `start`/`end`/`pos` is the anchor only — no line number, no trailing content, no line content.
 
 Ops:
 - `replace` — replace the inclusive range `start`..`end`. Both anchors are required. Single line: `start = end`. To delete a range, use `lines: []`. Do NOT use the `pos` field on `replace`; use `start`.
@@ -14,14 +14,14 @@ Examples:
 1. Single line replace:
 ```json
 { "path": "src/main.ts", "edits": [
-  { "op": "replace", "start": "#MQXV", "end": "#MQXV", "lines": ["const x = 1;"] }
+  { "op": "replace", "start": "MQXV", "end": "MQXV", "lines": ["const x = 1;"] }
 ] }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
 { "path": "src/main.ts", "edits": [
-  { "op": "replace", "start": "#ZPMQ", "end": "#VRWS", "lines": [
+  { "op": "replace", "start": "ZPMQ", "end": "VRWS", "lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
@@ -32,27 +32,27 @@ Examples:
 3. Multiple regions in one call (delete two non-adjacent ranges, insert before a third anchor):
 ```json
 { "path": "src/server.ts", "edits": [
-  { "op": "replace", "start": "#aB3x", "end": "#xY7q", "lines": [] },
-  { "op": "replace", "start": "#MQXV", "end": "#ZPMQ", "lines": [] },
-  { "op": "prepend", "pos": "#VRWS", "lines": ["// inserted before VRWS"] }
+  { "op": "replace", "start": "aB3x", "end": "xY7q", "lines": [] },
+  { "op": "replace", "start": "MQXV", "end": "ZPMQ", "lines": [] },
+  { "op": "prepend", "pos": "VRWS", "lines": ["// inserted before VRWS"] }
 ] }
 ```
 
 Rules:
 - `replace` requires both `start` and `end`. A single-line replace is `start=X, end=X`. To replace more than one line, set `end` to a different line's anchor.
-- `start`, `end`, `pos` are HASH anchors only (e.g. `#aB3x`). Other forms are rejected with `[E_BAD_REF]`.
-- `lines` is literal file content. No `#HASH:` prefix, no leading `+`/`-` (those are read/diff metadata, not file content). Lines starting with `#` + 4 base64 chars + `:` are checked; if detected, the edit is rejected with `[E_BARE_HASH_PREFIX]`. For `.py` files, this becomes a `[W_BARE_HASH_PREFIX]` warning instead (Python syntax like `else:`, `except:` triggers the detector).
+- `start`, `end`, `pos` are HASH anchors only (e.g. `aB3x`). Other forms are rejected with `[E_BAD_REF]`.
+- `lines` is literal file content. No `HASH│` prefix, no leading `+`/`-` (those are read/diff metadata, not file content). Lines starting with 4 base64 chars + `│` are checked; if detected, the edit is rejected with `[E_BARE_HASH_PREFIX]`. For `.py` files, this becomes a `[W_BARE_HASH_PREFIX]` warning instead (Python syntax like `else:`, `except:` triggers the detector).
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if: two `replace` ranges overlap; two `append`/`prepend` target the same insertion boundary (e.g. two EOF appends on a newline-terminated file); or an `append`/`prepend` falls inside a `replace` range in the same call. Fix: merge into one, use different boundaries, or split into a follow-up `edit` call.
 - If `lines` matches the current content byte-for-byte, the edit is classified as `Classification: noop` (file unchanged, not an error).
 
-On success (`changed` mode, default), the response text contains an `--- Anchors ---` block with fresh `#HASH:content` for the changed region (2 lines of context, capped at ~12 lines / 50 KB). Use those for nearby follow-up edits instead of re-reading. If the response says `Anchors omitted; use read for subsequent edits`, the region was too large — call `read` again. For distant follow-ups, or on any error, call `read` again. `full` and `ranges` modes put previews in `details`; the model only needs what's in the text.
+On success (`changed` mode, default), the response text contains an `--- Anchors ---` block with fresh `HASH│content` for the changed region (2 lines of context, capped at ~12 lines / 50 KB). Use those for nearby follow-up edits instead of re-reading. If the response says `Anchors omitted; use read for subsequent edits`, the region was too large — call `read` again. For distant follow-ups, or on any error, call `read` again. `full` and `ranges` modes put previews in `details`; the model only needs what's in the text.
 
-Errors are text starting with a bracketed code (e.g. `[E_BAD_SHAPE]`, `[E_STALE_ANCHOR]`, `[E_BAD_OP]`, `[E_INVALID_PATCH]`, `[E_LEGACY_SHAPE]`, `[E_EDIT_CONFLICT]`, `[E_BAD_REF]`, `[E_AMBIGUOUS_ANCHOR]`, `[E_BARE_HASH_PREFIX]`, `[E_WOULD_EMPTY]`). The message tells you what to retry; stale-anchor errors include `>>> #HASH:content` lines, ready to copy.
+Errors are text starting with a bracketed code (e.g. `[E_BAD_SHAPE]`, `[E_STALE_ANCHOR]`, `[E_BAD_OP]`, `[E_INVALID_PATCH]`, `[E_LEGACY_SHAPE]`, `[E_EDIT_CONFLICT]`, `[E_BAD_REF]`, `[E_AMBIGUOUS_ANCHOR]`, `[E_BARE_HASH_PREFIX]`, `[E_WOULD_EMPTY]`). The message tells you what to retry; stale-anchor errors include `>>> HASH│content` lines, ready to copy.
 
 The legacy `oldText`/`newText` shape (top-level or as `op: "replace_text"`) is rejected with `[E_LEGACY_SHAPE]`. Use hash-anchored edits instead.
 
 Auto-read after write:
-- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with `#HASH:content` for the written file.
+- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with `HASH│content` for the written file.
 - Use those anchors directly for `edit` calls without a separate `read`.
 - This enables a seamless write → edit workflow with no extra tool calls.

package/prompts/read-guidelines.md

@@ -1,3 +1,3 @@
 - Use read before edit when you do not have current HASH anchors for the file.
-- Copy exactly the HASH (the `#` + 4 characters before the `:`); never include the `:` or line content in `pos`/`end`.
-- A HASH always starts with `#`; the body may contain `-` as a normal alphabet character.
+- Copy exactly the HASH (the 4 characters before the `│`); never include the `│` or line content in `pos`/`end`.
+- A HASH may contain `-` as a normal alphabet character.

package/prompts/read-snippet.md

@@ -1 +1 @@
-Read a text file with #HASH:content anchors for edit (copy the #HASH into `start`/`end`/`pos`)
+Read a text file with HASH│content anchors for edit (copy the HASH into `start`/`end`/`pos`)

package/prompts/read.md

@@ -1,12 +1,12 @@
-Read a text file. Each line is returned as `#HASH:content`. The HASH starts with `#` followed by 4 base64 characters before the first `:`; the content after is the line verbatim. Pass the HASH (e.g. `#aB3x`) into `edit`'s `start`/`end` (for `replace`) or `pos` (for `append`/`prepend`) — never include the line content.
+Read a text file. Each line is returned as `HASH│content`. The HASH is 4 base64 characters; the content after the `│` separator is the line verbatim. Pass the HASH (e.g. `aB3x`) into `edit`'s `start`/`end` (for `replace`) or `pos` (for `append`/`prepend`) — never include the line content.
 
 HASH shape:
-- 5 characters total: `#` prefix + 4 characters from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `#aB3x`, `#4yN-`, `#-qkl`).
+- 4 characters from the URL-safe base64 alphabet `A-Za-z0-9-_` (e.g. `aB3x`, `4yN-`, `-qkl`).
 - The line number is not part of the wire format. Anchor by HASH, never by reading a line number off the rendered output.
 
 HASH → edit:
-- Copy the full 5-character HASH (including the `#` prefix). Use that HASH as `start` or `end` (for `replace`) or `pos` (for `append`/`prepend`) in the next `edit` call.
-- Do not include the `:`, the line content, or surrounding whitespace. The wire format for `start`/`end`/`pos` is the HASH only.
+- Copy the full 4-character HASH. Use that HASH as `start` or `end` (for `replace`) or `pos` (for `append`/`prepend`) in the next `edit` call.
+- Do not include the `│`, the line content, or surrounding whitespace. The wire format for `start`/`end`/`pos` is the HASH only.
 
 Pagination:
 - Large files return a truncated preview with a `nextOffset` line. Call `read` again with `offset=nextOffset` to continue.
@@ -14,15 +14,15 @@ Pagination:
 - Empty files return an advisory suggesting `prepend`/`append` instead of a synthetic anchor.
 
 Error recovery:
-- `[E_STALE_ANCHOR]` — the file changed since your last read. The error includes fresh `>>> #HASH:content` lines; copy the HASH portion (the `#` + 4 chars before `:`) and retry.
-- `[E_BAD_REF]` — malformed HASH. Re-read and try again with a valid HASH anchor (e.g. `#aB3x`).
+- `[E_STALE_ANCHOR]` — the file changed since your last read. The error includes fresh `>>> HASH│content` lines; copy the HASH portion (the 4 chars before `│`) and retry.
+- `[E_BAD_REF]` — malformed HASH. Re-read and try again with a valid HASH anchor (e.g. `aB3x`).
 
 File kinds:
-- Text files are returned as `#HASH:content` lines.
+- Text files are returned as `HASH│content` lines.
 - Images (JPEG, PNG, GIF, WebP) are returned as visual attachments; the HASH-line protocol does not apply.
 - Binary files and directories are rejected with a descriptive error.
 
 Auto-read after write:
-- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with `#HASH:content` for the written file.
+- After a successful `write`, the result includes a `--- Auto-read (hashline anchors) ---` block with `HASH│content` for the written file.
 - Use those anchors directly for `edit` calls without a separate `read`.
 - The auto-read output follows the same format and rules as `read` output.

package/src/edit-diff.ts

@@ -4,7 +4,6 @@ import {
   ANCHOR_LENGTH,
 } from "./hashline";
 
-// ─── Line ending normalization ──────────────────────────────────────────
 
 export function detectLineEnding(content: string): "\r\n" | "\n" {
   const crlfIdx = content.indexOf("\r\n");
@@ -30,7 +29,6 @@ export function stripBom(content: string): { bom: string; text: string } {
     : { bom: "", text: content };
 }
 
-// ─── Diff generation ────────────────────────────────────────────────────
 
 function formatDiffPreviewLine(
   prefix: " " | "+" | "-",
@@ -38,12 +36,9 @@ function formatDiffPreviewLine(
   hash: string | undefined,
 ): string {
   if (hash === undefined) {
-    // Removed lines have no hash, but they still need column alignment with
-    // the hash-prefixed lines (` HASH:`, `+HASH:`). Pad with `HASH_LENGTH`
-    // spaces so the `:` lines up in the same column.
-    return `${prefix}${" ".repeat(ANCHOR_LENGTH)}:${line}`;
+    return `${prefix}${" ".repeat(ANCHOR_LENGTH)}│${line}`;
   }
-  return `${prefix}${hash}:${line}`;
+  return `${prefix}${hash}│${line}`;
 }
 
 export function generateDiffString(

package/src/edit-normalize.ts

@@ -1,29 +1,6 @@
-/**
- * Single normalization layer that maps the dialects a model may emit onto the
- * canonical hashline edit request before validation runs.
- *
- * The only dialect we still absorb is the `file_path` → `path` alias and the
- * JSON-stringified `edits` array. Pi's native legacy `oldText`/`newText`
- * shape (whether top-level or as `op: "replace_text"`) is no longer
- * supported: the hashline protocol requires hash-anchored edits, and the
- * legacy text-matching path is what produces the
- * `[E_NO_MATCH] replace_text found no exact unique match` failure mode the
- * model hits on whitespace/Unicode drift. Any model that still emits the
- * legacy shape is rejected with a clear error in `assertEditItem` /
- * `assertEditRequest` so it learns the correct shape on the next turn.
- *
- * This runs as the tool's `prepareArguments` hook, which Pi executes before AJV
- * schema validation and before `execute()`. The output is plain enumerable data
- * (an `edits` array), so Pi's `structuredClone` of prepareArguments output keeps
- * every field.
- */
 
 import { isRecord, hasOwn } from "./utils";
 
-/**
- * Parse `edits` when a model serializes it as a JSON string instead of an array
- * (observed with some models, mirrors Pi's built-in edit handling).
- */
 function coerceEditsArray(edits: unknown): unknown {
 	if (typeof edits !== "string") {
 		return edits;
@@ -37,12 +14,6 @@ function coerceEditsArray(edits: unknown): unknown {
 }
 
 
-/**
- * Normalize a raw edit-tool request into the canonical hashline shape.
- *
- * Returns the input unchanged when it is not an object, so malformed payloads
- * still reach validation and surface a precise error there.
- */
 export function normalizeEditRequest(input: unknown): unknown {
 	if (!isRecord(input)) {
 		return input;

package/src/edit-response.ts

@@ -1,14 +1,3 @@
-/**
- * Edit response builders.
- *
- * Pulled out of `src/edit.ts` execute() so each returnMode branch
- * (noop / full / ranges / changed) is independently testable and the
- * top-level execute path stays narrative.
- *
- * No behaviour change: outputs are byte-identical to the previous inline
- * implementation. The only additive surface is `details.metrics` (Phase 2 C
- * — observability for hosts; the LLM-visible text is unchanged).
- */
 
 import { generateDiffString } from "./edit-diff";
 import {
@@ -18,10 +7,6 @@ import {
 } from "./hashline";
 import { formatHashlineReadPreview } from "./read";
 
-// Local shape — pi-coding-agent does not export a public `ToolResult`. The
-// builders return `details` as `any` so callers can keep their own per-tool
-// details type without re-asserting it here. This file intentionally does
-// not import the agent's tool-result type to stay decoupled from internals.
 type ToolResult = {
 	content: Array<{ type: "text"; text: string }>;
 	isError?: boolean;
@@ -30,7 +15,6 @@ type ToolResult = {
 
 const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
 
-// ─── Public types ───────────────────────────────────────────────────────
 
 export type ReturnMode = "changed" | "full" | "ranges";
 
@@ -52,14 +36,6 @@ export type FullContentPreview = {
 	nextOffset?: number;
 };
 
-/**
- * Host-visible, opt-in observability surface (Phase 2 C). The LLM never sees
- * this — it lives in `details` only. Hosts can use it for dashboards,
- * adoption metrics, or regression alarms (e.g. "noop rate spiking").
- *
- * snake_case is intentional: most observability backends prefer it and
- * avoiding camelCase saves a transform on the host side.
- */
 export type EditMetrics = {
 	edits_attempted: number;
 	edits_noop: number;
@@ -194,7 +170,7 @@ function truncateOutlineEntry(text: string, max = 88): string {
 function collectOutlineEntries(previewText: string): string[] {
 	const structural: string[] = [];
 	for (const line of previewText.split("\n")) {
-		const match = line.match(/^\s*#([A-Za-z0-9_\-]{4}):(.*)$/);
+		const match = line.match(/^\s*([A-Za-z0-9_\-]{4})│(.*)$/);
 		if (!match) continue;
 		const content = match[2]!.trim();
 		if (content.length === 0) continue;
@@ -250,7 +226,7 @@ function formatRequestedRangePreviews(
 			},
 			precomputedHashes,
 		);
-		const hasReturnedLines = /^\s*#[A-Za-z0-9_\-]{4}:/m.test(preview.text);
+		const hasReturnedLines = /^\s*[A-Za-z0-9_\-]{4}│/m.test(preview.text);
 		const actualEnd = hasReturnedLines
 			? preview.nextOffset !== undefined
 				? preview.nextOffset - 1

package/src/edit.ts

@@ -61,7 +61,7 @@ function stringEnumSchema<const Values extends readonly string[]>(
 
 const hashlineEditLinesSchema = Type.Array(Type.String(), {
 	description:
-		"replacement content, one array entry per line, no HASH: prefix",
+		"replacement content, one array entry per line, no HASH| prefix",
 });
 
 const returnRangeSchema = Type.Object(
@@ -92,19 +92,19 @@ const hashlineEditItemSchema = Type.Object(
 		start: Type.Optional(
 			Type.String({
 				description:
-					"required range-start anchor for op \"replace\" (hash anchor like \"#aB3x\" copied from read output); no content may follow the anchor",
+					"required range-start anchor for op \"replace\" (hash anchor like \"aB3x\" copied from read output); no content may follow the anchor",
 			}),
 		),
 		end: Type.Optional(
 			Type.String({
 				description:
-					"required range-end anchor for op \"replace\" (hash anchor like \"#aB3x\"). To replace a single line, set start = end = the line's anchor",
+					"required range-end anchor for op \"replace\" (hash anchor like \"aB3x\"). To replace a single line, set start = end = the line's anchor",
 			}),
 		),
 		pos: Type.Optional(
 			Type.String({
 				description:
-					"anchor for op \"append\" or \"prepend\" (hash anchor like \"#aB3x\"). Omit for file-boundary insertion (EOF/BOF).",
+					"anchor for op \"append\" or \"prepend\" (hash anchor like \"aB3x\"). Omit for file-boundary insertion (EOF/BOF).",				
 			}),
 		),
 		lines: Type.Optional(hashlineEditLinesSchema),
@@ -127,11 +127,6 @@ export const hashlineEditToolSchema = Type.Object(
 		edits: Type.Optional(
 			Type.Array(hashlineEditItemSchema, { description: "edits over $path" }),
 		),
-		// File-path alias and JSON-stringified edits are still absorbed by
-		// normalizeEditRequest in the prepareArguments hook, which runs before
-		// this schema is validated. The legacy native top-level oldText/newText
-		// dialect is NOT folded — it is rejected outright with [E_LEGACY_SHAPE]
-		// in assertEditRequest, so it never reaches the schema validator.
 	},
 	{ additionalProperties: false },
 );
@@ -205,15 +200,6 @@ const EDIT_PROMPT_SNIPPET = readFileSync(
 
 const ROOT_KEYS = new Set(["path", "returnMode", "returnRanges", "edits"]);
 
-// Validates the canonical edit request envelope after normalizeEditRequest has
-// converged any model dialects. Per-edit structural validation is delegated to
-// resolveEditAnchors (src/hashline.ts), which is the single source of truth for
-// edit-item shape + op constraints. This function validates only the root-level
-// request fields: path, returnMode, returnRanges, and that edits is an array.
-//
-// Intentional overlap with the published TypeBox schema: pi normally runs AJV
-// validation before execute(), but that can be disabled in environments without
-// runtime code generation support, so the semantic checks here are the backstop.
 export function assertEditRequest(
 	request: unknown,
 ): asserts request is EditRequestParams {
@@ -221,12 +207,6 @@ export function assertEditRequest(
 		throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
 	}
 
-	// The legacy native top-level oldText/newText dialect (with or without the
-	// snake_case aliases) is no longer supported. Hash-anchored edits are the
-	// only path — the legacy shape is what produces
-	// `[E_NO_MATCH] replace_text found no exact unique match` on real-world
-	// whitespace/Unicode drift. Reject early with a clear error so the model
-	// learns the right shape on the next turn.
 	for (const legacyKey of ["oldText", "newText", "old_text", "new_text"]) {
 		if (hasOwn(request, legacyKey)) {
 			throw new Error(
@@ -310,16 +290,8 @@ export function assertEditRequest(
 		);
 	}
 
-	// Per-edit validation lives in resolveEditAnchors — the single source of
-	// truth for edit-item shape, op constraints, and anchor parsing.
 }
 
-/**
- * Shared edit pipeline: normalize, validate, read file, resolve anchors,
- * and apply edits. Both `computeEditPreview` (dry-run) and `execute()`
- * (real) call this; the access mode parameter controls whether the file
- * must be writable.
- */
 async function executeEditPipeline(
 	request: unknown,
 	cwd: string,
@@ -392,10 +364,6 @@ async function executeEditPipeline(
 	const originalEnding = detectLineEnding(rawContent);
 	const originalNormalized = normalizeToLF(rawContent);
 
-	// Pre-compute hashes for the original file once. The same array is passed
-	// into applyHashlineEdits so validation and the stale-anchor retry block
-	// agree on what each line's hash is, and so we can return updated
-	// occurrence-aware anchors in the response without recomputing.
 	const originalHashes = computeLineHashes(originalNormalized);
 
 	const resolved = resolveEditAnchors(toolEdits);
@@ -458,16 +426,8 @@ const editToolDefinition: EditToolDefinition = {
 	description: EDIT_DESC,
 	parameters: hashlineEditToolSchema,
 	promptSnippet: EDIT_PROMPT_SNIPPET,
-	// Converge model dialects (JSON-string edits, file_path alias) onto the
-	// canonical hashline shape before Pi validates and before execute(). The
-	// legacy top-level oldText/newText dialect is NOT folded — it is rejected
-	// outright with [E_LEGACY_SHAPE] in assertEditRequest. See
-	// src/edit-normalize.ts.
 	prepareArguments: (args: unknown) =>
 		normalizeEditRequest(args) as EditRequestParams,
-	// Force the default tool shell (Box with pending/success/error background) so
-	// we don't inherit renderShell: "self" from the built-in edit tool of the
-	// same name, which would drop the shared background color block.
 	renderShell: "default",
 	renderCall(args, theme, context) {
 		const previewInput = getRenderablePreviewInput(args);
@@ -588,8 +548,6 @@ const editToolDefinition: EditToolDefinition = {
 	},
 
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		// normalizeEditRequest is re-applied here so execute does not depend on
-		// prepareArguments having run. Idempotent on canonical input.
 		const normalized = normalizeEditRequest(params);
 		assertEditRequest(normalized);
 		const normalizedParams = normalized;
@@ -667,10 +625,6 @@ const editToolDefinition: EditToolDefinition = {
 				requestedReturnRanges,
 				originalNormalized,
 				result,
-				// Hash the post-edit file once. The result builders will use
-				// these for the per-line anchors in the full / ranges / changed
-				// response blocks; computing once here is cheaper than letting
-				// each builder recompute.
 				resultHashes: computeLineHashes(result),
 				warnings,
 				snapshotId: updatedSnapshotId,