pi-hashline-edit-pro 0.2.1 → 0.3.1

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** — 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** — `#`-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.
 
 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 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 `#`-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:
 
 ```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` — 4-character content hash from the URL-safe base64 alphabet `A-Za-z0-9-_`.
+- `HASH` — `#`-prefixed 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,11 +80,11 @@ 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
@@ -92,20 +92,20 @@ After a successful `write`, the extension automatically reads the file and appen
 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 5 chars of a `lines` entry looking like a 4-char hash followed by `:`) is also rejected with `[E_BARE_HASH_PREFIX]` — issue #24. When the suspect's prefix happens to match a real file-line hash, the error message flags that as strong evidence the model copied a hash 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 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.
 - **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 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 `#`-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**.
 
 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 +120,7 @@ The runtime always precomputes the full per-line hash array for a file via `comp
 
 ### Trade-off: the bare-prefix detector
 
-With a 64-char alphabet, the regex `^\s*[A-Za-z0-9_-]{4}:` matches a LOT of code (any 4-char identifier followed by `:` — `todo:`, `done:`, `note:`, `init:`). The "did the model accidentally paste a hash into its content?" detector used to fire on a count-based heuristic (too noisy at 64 chars), then on a "strong signal" gate (the prefix matches a real file-line hash) and only warned, then escalated to a strict rejection. Today the first 5 characters of every `lines` entry are checked; if they look like a 4-char hash followed by `:`, the edit is rejected with `[E_BARE_HASH_PREFIX]`. The false-positive cost (rejecting `init:`, `data:`, etc.) is real but small: the model can rephrase the line (quote it, add a leading space, use a different identifier shape) and retry. The false-negative cost (a stray hash in the file) is silent and catastrophic.
+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.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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 bare 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.
 
-Hashes are 4 characters (e.g. `aB3x`), alphabet `A-Za-z0-9-_`. The wire format for `start`/`end`/`pos` is the bare hash only — no line number, no trailing content, no `HASH:content` form.
+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,45 +14,45 @@ 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}`;",
     "}"
-  ] }
+  }
 ] }
 ```
 
 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 hash.
-- `start`, `end`, `pos` are bare 4-character HASH strings only. 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). The first 5 characters of every `lines` entry are checked; if they look like a 4-char hash followed by `:` (after any leading whitespace), 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).
+- `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).
 - 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 4-character HASH (the part before the `:`); never include the `:` or line content in `pos`/`end`.
-- A HASH may start with `-`; that is a normal alphabet character, not a diff-remove marker.
+- 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.

package/prompts/read-snippet.md

@@ -1 +1 @@
-Read a text file with HASH:content anchors for edit (copy the HASH portion 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 is the 4 characters before the first `:`; the content after is the line verbatim. Pass the 4-character HASH into `edit`'s `start`/`end` (for `replace`) or `pos` (for `append`/`prepend`) — never the rendered `HASH:content` form.
+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.
 
 HASH shape:
-- 4 characters (e.g. `aB3x`), from the URL-safe base64 alphabet `A-Za-z0-9-_`. A HASH can start with any of these characters, including `-`. A leading `-` is a normal alphabet char, not a diff-remove marker.
+- 5 characters total: `#` prefix + 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 exactly the 4 characters before the `:`. Use that bare 4-character 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 bare 4-character HASH only.
+- 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.
 
 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 (4 chars before `:`) and retry.
-- `[E_BAD_REF]` — malformed HASH. Re-read and try again with a valid 4-character HASH.
+- `[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

@@ -1,7 +1,7 @@
 import * as Diff from "diff";
 import {
   computeLineHashes,
-  HASH_LENGTH,
+  ANCHOR_LENGTH,
 } from "./hashline";
 
 // ─── Line ending normalization ──────────────────────────────────────────
@@ -41,7 +41,7 @@ function formatDiffPreviewLine(
     // 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(HASH_LENGTH)}:${line}`;
+    return `${prefix}${" ".repeat(ANCHOR_LENGTH)}:${line}`;
   }
   return `${prefix}${hash}:${line}`;
 }

package/src/edit-response.ts

@@ -194,7 +194,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 +250,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

@@ -92,19 +92,19 @@ const hashlineEditItemSchema = Type.Object(
 		start: Type.Optional(
 			Type.String({
 				description:
-					"required range-start anchor for op \"replace\" (bare 4-character HASH copied from read output); no content may follow the hash",
+					"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\" (bare 4-character HASH). To replace a single line, set start = end = the line's hash",
+					"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\" (bare 4-character HASH). 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),

package/src/hashline/apply.ts

@@ -558,7 +558,7 @@ export function computeAffectedLineRange(params: {
 }
 
 /**
- * Format a list of lines as `HASH:content` rows.
+ * Format a list of lines as `#HASH:content` rows.
  *
  * Used by the read tool's preview and the changed-mode anchor block. The
  * hashes must be the precomputed per-line hashes for the file — see

package/src/hashline/hash.ts

@@ -23,6 +23,13 @@ import * as XXH from "xxhashjs";
  */
 export const HASH_LENGTH = 4;
 
+/** Prefix marker for hash anchors. Every anchor starts with `#` so the hash */
+/** format is `#` + HASH_LENGTH base64 chars (e.g. `#aB3x`, `#4yN-`). */
+export const HASH_PREFIX = "#";
+
+/** Total wire-format length of an anchor: prefix + hash body. */
+export const ANCHOR_LENGTH = HASH_PREFIX.length + HASH_LENGTH;
+
 /**
  * URL-safe base64 alphabet: A–Z, a–z, 0–9, `-`, `_`. 64 distinct chars
  * giving 6 bits per hash character. No exclusions, no human-readability
@@ -40,7 +47,7 @@ const HASH_ALPHABET_MASK = (1 << HASH_ALPHABET_BITS) - 1;
 // silently swallows the literal `-`). The `_` is always literal.
 const HASH_ALPHABET_REGEX_SAFE = HASH_ALPHABET.replace(/-/g, "\\-");
 const HASH_ALPHABET_RE = new RegExp(`^[${HASH_ALPHABET_REGEX_SAFE}]+$`);
-export const HASH_CHARS_CLASS = `[${HASH_ALPHABET_REGEX_SAFE}]{${HASH_LENGTH}}`;
+export const HASH_CHARS_CLASS = `${HASH_PREFIX}[${HASH_ALPHABET_REGEX_SAFE}]{${HASH_LENGTH}}`;
 
 /**
  * Encode the top `HASH_LENGTH * 6` bits of a 32-bit hash value as a
@@ -68,7 +75,7 @@ function hashToString(h: number): string {
 					HASH_ALPHABET_MASK
 			]!;
 	}
-	return out;
+	return HASH_PREFIX + out;
 }
 
 /**
@@ -85,16 +92,16 @@ export const HASHLINE_PREFIX_PLUS_RE = new RegExp(
 export const DIFF_MINUS_RE = /^-\s*\d+\s{4}/;
 
 /**
- * Bare hashline prefix: a HASH_LENGTH-char hash followed by ":" with no
- * "LINE#" part (e.g. "KKZ:### heading", "TPN:text", "TJZ:"). Capture
- * group 1 is the hash.
+ * Bare hashline prefix: a `#` + HASH_LENGTH-char hash followed by ":" with
+ * no "LINE#" part (e.g. "#KKZ:### heading", "#TPN:text", "#TJZ:"). Capture
+ * group 1 is the full anchor (including `#` prefix).
  *
  * This is the partial-hash failure mode from issue #24: the model copies a
  * hash it saw in `read` output into the line content but drops the rest
- * of the rendered `HASH:content` form. The first 5 characters of the line
- * (4 alphabet chars + ":") are matched by this regex, then
- * `assertNoBareHashPrefixLines` rejects the edit with `[E_BARE_HASH_PREFIX]`
- * so the model gets actionable feedback instead of a silent correctness bug.
+ * of the rendered `#HASH:content` form. The anchor (prefix + HASH_LENGTH chars
+ * + ":") is matched by this regex, then `assertNoBareHashPrefixLines` rejects
+ * the edit with `[E_BARE_HASH_PREFIX]` so the model gets actionable feedback
+ * instead of a silent correctness bug.
  */
 export const HASHLINE_BARE_PREFIX_RE = new RegExp(`^\\s*(${HASH_CHARS_CLASS}):`);
 
@@ -182,7 +189,9 @@ export function computeLineHash(idx: number, line: string): string {
 
 /** Exported for tests and for downstream tools that want to mirror the format. */
 export const HASH_FORMAT = {
+	prefix: HASH_PREFIX,
 	length: HASH_LENGTH,
+	anchorLength: ANCHOR_LENGTH,
 	bitsPerChar: HASH_ALPHABET_BITS,
 	alphabet: HASH_ALPHABET,
 };

package/src/hashline/index.ts

@@ -6,15 +6,16 @@
  *
  * This fork preserves the strict semantics of the original (no silent
  * relocation, no autocorrection heuristics, no fuzzy fallback) and uses a
- * 4-character hash over a 64-character URL-safe base64 alphabet, giving
+ * `#`-prefixed hash over a 64-character URL-safe base64 alphabet, giving
  * 24 bits of entropy (16 777 216 buckets) per anchor. Birthday-paradox
  * collisions become effectively zero for any realistic file size. The
  * alphabet is sized for an LLM consumer, not a human reader — the model
  * tokenizes, it does not squint at pixel glyphs.
  *
- * Anchor format: a bare hash alone (`aB3x`). The line number is no longer
- * part of the wire format, and no content may follow the hash either. The
- * model never has to type a line number; the runtime resolves each hash to
+ * Anchor format: `#` prefix + 4 base64 chars (e.g. `#aB3x`). The line number
+ * is no longer part of the wire format, and no content may follow the anchor
+ * either. The model never has to type a line number; the runtime resolves each
+ * anchor to a line via the file's precomputed hash array.
  * a line via the file's precomputed hash array.
  *
  * On a hash collision (two different lines happen to have the same hash
@@ -30,6 +31,8 @@
 export {
 	// Hash computation
 	HASH_LENGTH,
+	HASH_PREFIX,
+	ANCHOR_LENGTH,
 	HASH_FORMAT,
 	HASH_CHARS_CLASS,
 	HASHLINE_PREFIX_RE,

package/src/hashline/parse.ts

@@ -6,7 +6,8 @@
  */
 
 import {
-	HASH_LENGTH,
+	ANCHOR_LENGTH,
+	HASH_PREFIX,
 	HASH_ALPHABET_RE,
 	HASH_CHARS_CLASS,
 	HASHLINE_PREFIX_PLUS_RE,
@@ -28,30 +29,32 @@ function diagnoseHashRef(ref: string): string {
 	const trimmed = ref.trim();
 
 	if (!trimmed.length) {
-		return `[E_BAD_REF] Invalid anchor. Expected a bare 4-character hash (e.g. "aB3x").`;
+		return `[E_BAD_REF] Invalid anchor. Expected a hash anchor like "#aB3x" (prefix "#" + 4 base64 chars).`;
 	}
 
 	// Detect the legacy "LINE#HASH" form (5#aB3x, 12#MQ, etc.) so we can
 	// give a clear error pointing at the new format.
 	if (/^\d+\s*#/.test(trimmed)) {
-		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. "aB3x") — no line numbers or trailing content.`;
+		return `[E_BAD_REF] Invalid anchor. Use the hash alone (e.g. "#aB3x") — no line numbers or trailing content.`;
 	}
 
-	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a bare 4-character hash.`;
+	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a hash anchor like "#aB3x".`;
 }
 
 function parseAnchorRef(ref: string): Anchor {
 	const trimmed = ref.trim();
 
-	// Strict: the wire format is a 4-character hash from the URL-safe base64
+	// Strict: the wire format is `#` + 4-character hash from the URL-safe base64
 	// alphabet (A-Za-z0-9-_), copied verbatim from `read` output. The first
-	// character can be `-` (a valid alphabet char), so a hash like `-qkl` is
-	// taken literally. No other form is tolerated: `+`/`-`/`>>>` markers from
-	// diff contexts or stale-anchor retry blocks are rejected. The model must
-	// copy just the 4-character hash with no surrounding characters.
+	// character of the hash body can be `-` (a valid alphabet char), so an anchor
+	// like `#-qkl` is taken literally. No other form is tolerated: `+`/`-`/`>>>`
+	// markers from diff contexts or stale-anchor retry blocks are rejected. The
+	// model must copy just the anchor (prefix + 4 chars) with no surrounding
+	// characters.
 	if (
-		trimmed.length === HASH_LENGTH &&
-		HASH_ALPHABET_RE.test(trimmed)
+		trimmed.length === ANCHOR_LENGTH &&
+		trimmed.startsWith(HASH_PREFIX) &&
+		HASH_ALPHABET_RE.test(trimmed.slice(HASH_PREFIX.length))
 	) {
 		return { hash: trimmed };
 	}
@@ -60,8 +63,8 @@ function parseAnchorRef(ref: string): Anchor {
 }
 
 /**
- * Parse a hash anchor. Accepts `HASH` (e.g. `"aB3x"`) only. The
- * `HASH:content` disambiguator from earlier versions is gone — the hash
+ * Parse a hash anchor. Accepts `#HASH` (e.g. `"#aB3x"`) only. The
+ * `#HASH:content` disambiguator from earlier versions is gone — the anchor
  * is the entire wire format for `pos` and `end`, and no content may
  * follow it.
  *

package/src/hashline/resolve.ts

@@ -7,7 +7,7 @@
  */
 
 import { throwIfAborted } from "../runtime";
-import { HASH_LENGTH, HASHLINE_BARE_PREFIX_RE } from "./hash";
+import { HASHLINE_BARE_PREFIX_RE } from "./hash";
 import { parseHashRef, hashlineParseText, type Anchor } from "./parse";
 
 // ─── Types ──────────────────────────────────────────────────────────────
@@ -88,7 +88,7 @@ export type HashlineToolEdit = {
  *   - `not_found`: no line in the file has this hash
  *   - `ambiguous`: the hash matches multiple lines (the model must
  *     re-read to disambiguate; the runtime does not accept a
- *     `HASH:content` disambiguator on the wire)
+	 *     `#HASH:content` disambiguator on the wire)
  */
 function resolveAnchor(
 	ref: Anchor,
@@ -332,12 +332,12 @@ function maybeWarnSuspiciousUnicodeEscapePlaceholder(
  * `assertNoDisplayPrefixes`, which rejects the unambiguous `+HASH:` form at
  * the parse stage; this catches the bare `HASH:` form (after optional leading
  * whitespace) at the apply stage. The first 5 characters of every `lines`
- * entry are checked: 4 alphabet characters (A–Z, a–z, 0–9, `-`, `_`)
+ * entry are checked: `#` prefix + 4 alphabet characters (A–Z, a–z, 0–9, `-`, `_`)
  * followed by `:`.
  *
- * Bare `HASH:` prefixes in `lines` are almost always a model mistake — the
+ * Bare `#HASH:` prefixes in `lines` are almost always a model mistake — the
  * model copied the hash prefix from a `read` output but dropped the rest of
- * the rendered `HASH:content` form. We reject with `[E_BARE_HASH_PREFIX]`
+ * the rendered `#HASH:content` form. We reject with `[E_BARE_HASH_PREFIX]`
  * rather than warn, because a stray hash in the file content is a silent
  * correctness bug (the line is written verbatim, no autocorrection) and
  * because the cost of a false positive is small: the model can rephrase the
@@ -346,7 +346,7 @@ function maybeWarnSuspiciousUnicodeEscapePlaceholder(
  *
  * The error message lists the offending lines, the suspect hash prefix for
  * each, and whether any of them collide with a real file-line hash. A
- * collision is a strong signal that the model was reading a `HASH:content`
+ * collision is a strong signal that the model was reading a `#HASH:content`
  * line and copied only the prefix.
  */
 export function assertNoBareHashPrefixLines(
@@ -394,7 +394,7 @@ export function assertNoBareHashPrefixLines(
 			: `${matchedCount} match file line hashes — likely a copied hash.`;
 
 	throw new Error(
-		`[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (e.g. ${JSON.stringify(exampleLine)}). ${linesHint} Use literal file content in "lines" — never paste HASH:content from read output.`
+		`[E_BARE_HASH_PREFIX] ${suspects.length} edit line(s) start with a hash-like prefix (e.g. ${JSON.stringify(exampleLine)}). ${linesHint} Use literal file content in "lines" — never paste #HASH:content from read output.`
 	);
 }