pi-hashline-edit-pro 6.4.7 → 6.4.8

package/README.md

@@ -422,7 +422,7 @@ When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFI
 
 All eight tools return machine-readable metadata in `details` alongside the model-visible text.
 
-All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. For `read`, `text` is the raw file content of the served window and `lines` carries the anchored rows, so a script parses the file without anchor prefixes. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
+All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. In a codemode session `tools.read()` resolves to the file's text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }`, where `text` is the raw file content of the served window and `lines` carries the anchored rows. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
 
 `read` returns `{ kind: "read", path, text, lines, totalLines, startLine, nextOffset, truncated, blockedByLongLine, hadUtf8DecodeErrors, notices }`, where `text` is the raw file content of the served window (no anchors, no footers) and each entry of `lines` is `{ line, text, anchor, rendered }` for a row that was served (`text` there is what was shown, so an oversized line appears as its marker while keeping its anchor). `notices` carries non-file notes such as the UTF-8 rewrite note and `[W_ANCHOR_RECLAIMED]`. An image read returns `{ type: "image", data, mimeType, note }`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "6.4.7",
+  "version": "6.4.8",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",
@@ -61,15 +61,15 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^10.9.1",
-    "typebox": "^1.3.7",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^24.19.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "typebox": "^1.4.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
   },
   "allowScripts": {
     "@google/genai@1.52.0": true,

package/src/anchor-registry.ts

@@ -6,8 +6,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { sessionClaimsDir } from "./paths";
 import { contentChecksum } from "./hashline/hasher";
 import { ANCHOR_COUNT, anchorAt } from "./hashline/alphabet";
-import { HASH_PROBE_STRIDE } from "./hashline/hash";
-import { errCode, isRec, splitLines } from "./utils";
+import { HASH_PROBE_STRIDE, MAX_HASH_LINES } from "./hashline/hash";
+import { assertLineCount, errCode, isRec, splitLines, spliceAll } from "./utils";
 import * as Diff from "diff";
 import { lineChecksum } from "./hashline";
 import { getAllocatedState, persistSnapshot, type HashStore } from "./hash-store";
@@ -46,6 +46,7 @@ interface OwnedAnchorMap {
 }
 
 interface AnchorMintedSet {
+  readonly size: number;
   has(anchor: string): boolean;
   add(anchor: string): unknown;
   [Symbol.iterator](): IterableIterator<string>;
@@ -125,9 +126,12 @@ class ShadowOwnedMap implements OwnedAnchorMap {
 class ShadowMintedSet implements AnchorMintedSet {
   private readonly parent: AnchorMintedSet;
   private readonly added = new Set<string>();
+  private extra = 0;
+  private parentSize: number;
 
   constructor(parent: AnchorMintedSet) {
     this.parent = parent;
+    this.parentSize = parent.size;
   }
 
   has(anchor: string): boolean {
@@ -135,10 +139,22 @@ class ShadowMintedSet implements AnchorMintedSet {
   }
 
   add(anchor: string): this {
+    if (!this.added.has(anchor) && !this.parent.has(anchor)) this.extra += 1;
     this.added.add(anchor);
     return this;
   }
 
+  get size(): number {
+    if (this.parent.size !== this.parentSize) {
+      this.parentSize = this.parent.size;
+      this.extra = 0;
+      for (const anchor of this.added) {
+        if (!this.parent.has(anchor)) this.extra += 1;
+      }
+    }
+    return this.parentSize + this.extra;
+  }
+
   *[Symbol.iterator](): IterableIterator<string> {
     yield* this.parent;
     for (const anchor of this.added) {
@@ -555,16 +571,19 @@ export function reclaimAnchorSpace(state: SessionState, protectPath?: string): s
 
 export function mintAnchor(state: SessionState, protectPath?: string): string {
   for (;;) {
-    for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
-      state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
-      const candidate = anchorAt(state.probe);
-      if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
-        return candidate;
+    if (state.everMinted.size < ANCHOR_COUNT) {
+      for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
+        state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
+        const candidate = anchorAt(state.probe);
+        if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
+          return candidate;
+        }
       }
     }
     for (let step = 1; step <= ANCHOR_COUNT; step++) {
       const candidate = anchorAt((state.probe + step) % ANCHOR_COUNT);
       if (!state.owned.has(candidate)) {
+        state.probe = (state.probe + step) % ANCHOR_COUNT;
         for (const served of state.served.values()) served.delete(candidate);
         return candidate;
       }
@@ -861,7 +880,7 @@ export function alignOwnershipWithSpans(
       state.everMinted.add(settled[k]!);
       state.owned.set(settled[k]!, { path, checksum: newChecksums[start + k]! });
     }
-    anchors.splice(start, spanLength, ...settled);
+    spliceAll(anchors, start, spanLength, settled);
     offset += span.replacementCount - spanLength;
   }
   const rows: [string, string][] = minted.map((m) => [m.anchor, m.checksum]);
@@ -963,8 +982,9 @@ export async function allocateFileAnchors(
   ensureRegistry();
   const registry = current();
   const shadow = options?.shadow === true;
-  if (!shadow && registry) touchPath(registry, path);
   const lines = splitLines(content);
+  assertLineCount(lines.length, path, MAX_HASH_LINES);
+  if (!shadow && registry) touchPath(registry, path);
   const checksums = lines.map(lineChecksum);
   if (options?.previous?.spans) {
     const prevChecksums = splitLines(options.previous.content).map(lineChecksum);
@@ -1058,6 +1078,10 @@ export function resetRegistryForTests(): void {
   registries.clear();
 }
 
+export function lastUsedAtForTests(path: string): number | undefined {
+  return current()?.lastUsedAt.get(path);
+}
+
 async function readSidecarWindow(sidecar: string): Promise<{ text: string; filled: boolean }> {
   const handle = await open(sidecar, "r");
   const buffer = Buffer.alloc(SIDECAR_HEADER_BYTES);

package/src/batch.ts

@@ -28,7 +28,7 @@ import { saveUndo } from "./replace-undo";
 import { buildChanged, buildNoop, type RMetrics, type TResult } from "./replace-response";
 import { toEditVerb, withStructuredText, type EditStructured } from "./structured";
 import { serveRows, servedHashesFromDiff } from "./served";
-import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines } from "./utils";
+import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines, spliceAll } from "./utils";
 
 export interface PlannedMember {
   batchKey: number;
@@ -793,7 +793,7 @@ function composeBatchLines(baseContent: string, pieces: BatchPiece[]): string {
   const lines = splitLines(baseContent);
   const baseLineCount = lines.length;
   const descending = [...pieces].sort((a, b) => b.start - a.start);
-  for (const piece of descending) lines.splice(piece.start - 1, piece.end - piece.start + 1, ...piece.newLines);
+  for (const piece of descending) spliceAll(lines, piece.start - 1, piece.end - piece.start + 1, piece.newLines);
   let composed = lines.join("\n");
   if (lines.length > 0 && (baseContent.endsWith("\n") || lines[lines.length - 1] === "")) {
     composed += "\n";

package/src/copy-move.ts

@@ -23,7 +23,7 @@ import { formatAnchorReclaimNotice, servedForPath, takeReclaimedPaths, withAncho
 import { batchMemberFor, batchServedFor, ensureBatchBase, executeBatchMember, noteBatchFailure, pendingBatchMemberFor, registerBatchPlanner, type BatchBase, type BatchMemberPlanner, type PlannedMember } from "./batch";
 import { loadP, loadGuidelines } from "./prompts";
 import { assertTransferReq, normReq, type TransferReq } from "./payload-contract";
-import { abortIf, assertByteLimit, isRec, splitLines } from "./utils";
+import { abortIf, anchorCarryIndex, assertByteLimit, isRec, splitLines } from "./utils";
 import { toDisplayPath } from "./paths";
 import { getDiffContextLines } from "./config";
 import { resolveInCwd, writeAtomic } from "./fs-write";
@@ -145,7 +145,7 @@ export function buildTransferEdit(input: {
           : [...sourceLines, fileLines[anchorLine - 1]!],
       },
       foldedAnchorLines: 1,
-      anchorCarry: refs.direction === "after" ? 0 : sourceLines.length,
+      anchorCarry: anchorCarryIndex(refs.direction, sourceLines.length),
       endingOverrides: refs.direction === "after"
         ? [undefined, ...sourceEndings]
         : [...sourceEndings, undefined],
@@ -319,14 +319,14 @@ async function prepareCrossTransfer(input: {
       ? offsetEndings(1, sourceEndings)
       : sourceEndings;
   if (kind === "copy") {
-    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), endingOverrides };
+    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), endingOverrides };
   }
   const sourceEdit: HTEdit = {
     remove_from: sourcePreload.fileHashes[sourceStart - 1]!,
     remove_to: sourcePreload.fileHashes[sourceEnd - 1]!,
     text: [],
   };
-  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), sourceEdit, endingOverrides };
+  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), sourceEdit, endingOverrides };
 }
 
 function pairEntry(pipe: PipelineResult, separators: LineEnding[] | undefined): UndoEntry {
@@ -584,6 +584,7 @@ async function executeCrossFile(
       signal,
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") {
       return commitEdit(destinationPipe, {
@@ -827,6 +828,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
         served: plan.servedOverride,
         endingOverrides: plan.endingOverrides,
         signal,
+        ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
       });
       return previewFromPipe(pipe);
     }
@@ -837,6 +839,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
       signal,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") return previewFromPipe(destinationPipe);
     const sourcePipe = await execPipeline(sourcePath, prepared.sourceEdit!, cwd, {
@@ -1017,6 +1020,7 @@ export function buildTransferToolDef(kind: TransferKind, flags: EditToolFlags =
               preloadedNorm: preload,
               served: plan.servedOverride,
               endingOverrides: plan.endingOverrides,
+              ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
             });
             return commitEdit(pipe, {
               path: pipe.path,

package/src/edit-common.ts

@@ -53,10 +53,14 @@ function preferenceGuideline(flags: EditToolFlags): string {
 const SHARED_EDIT_OPS = ["replace", "replace_match", "insert", "copy", "move"];
 const SHARED_PAYLOAD_OPS = ["replace", "replace_match", "insert"];
 const SHARED_DIFF_OPS = ["replace", "replace_match", "insert", "copy", "move", "undo_last_change"];
-const RESULT_CONTRACT_GUIDELINE =
-  'When called from a codemode script, failures resolve to `{ ok: false, kind: "error", error: { code, message } }`; branch on `ok` instead of `try`/`catch`.';
+const SHARED_SCRIPT_OPS = ["read", "replace", "replace_match", "insert", "copy", "move", "grep", "undo_last_change"];
+
+function resultContractGuideline(flags: EditToolFlags): string {
+  const tools = operationNames(SHARED_SCRIPT_OPS, flags);
+  return `${tools}: when called from a codemode script, failures resolve to \`{ ok: false, kind: "error", error: { code, message } }\`; branch on \`ok\` instead of \`try\`/\`catch\`.`;
+}
 const READ_SCRIPT_GUIDELINE =
-  '`read`: a codemode script receives `{ text, lines, notices }`; `text` is the raw file content of the served window and `lines[].anchor` is the editable anchor. An image read resolves to an image block.';
+  '`read` in a codemode script resolves to the file\'s text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }` with the raw file content and `lines[].anchor` for chained edits. An image read resolves to an image block.';
 const GREP_SCRIPT_GUIDELINE =
   '`grep`: a codemode script receives `{ text, results }`; each `results[].lines[]` entry carries the matching line\'s `anchor` and `text`, so a result is editable without a fresh read.';
 function editScriptGuideline(flags: EditToolFlags): string {
@@ -137,7 +141,7 @@ function readGuidelineApplies(guideline: Guideline, flags: EditToolFlags): boole
 
 export function withReadPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const preference = preferenceGuideline(flags);
-  const script = flags.codemode ? [READ_SCRIPT_GUIDELINE, RESULT_CONTRACT_GUIDELINE] : [];
+  const script = flags.codemode ? [READ_SCRIPT_GUIDELINE, resultContractGuideline(flags)] : [];
   const applicable = base.guidelines.filter((guideline) => readGuidelineApplies(guideline, flags));
   if (flags.autoReadAllActive) {
     const rewritten = applicable.filter((guideline) => guideline.id !== READ_REREAD_ID).map((guideline) => guideline.text);

package/src/insert.ts

@@ -12,7 +12,7 @@ import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuidelines } from "./prompts";
 import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
-import { isRec, literalEscapeHints, splitLines } from "./utils";
+import { anchorCarryIndex, isRec, literalEscapeHints, splitLines } from "./utils";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
 import { editResultSchema, withStructuredErrors } from "./structured";
@@ -98,6 +98,11 @@ function insertStripWarning(anchorLine: string | undefined, direction: "before"
   return { label: "text", indexOffset: anchorLine !== undefined && direction === "after" ? -1 : 0 };
 }
 
+function insertAnchorCarry(direction: "before" | "after", editParams: HTEdit, anchorLine: string | undefined): number | undefined {
+  if (anchorLine === undefined) return undefined;
+  return anchorCarryIndex(direction, editParams.text.length - 1);
+}
+
 function planInsertBatchMember(input: BatchPlannerInput): BatchMemberPlan {
   const req = normReq(input.member.args);
   assertInsertReq(req);
@@ -149,6 +154,7 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
       signal,
     });
     const { editParams, anchorLine, contentSeparators } = buildInsertEdit(normalized, preload, ref, targetPath);
+    const anchorCarry = insertAnchorCarry(normalized.direction, editParams, anchorLine);
     const pipe = await execPipeline(targetPath, editParams, cwd, {
       accessMode: constants.R_OK,
       noPersist: true,
@@ -156,6 +162,7 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
       signal,
       stripWarning: insertStripWarning(anchorLine, normalized.direction),
       endingOverrides: contentSeparators,
+      ...(anchorCarry !== undefined ? { anchorCarry } : {}),
     });
     return previewFromPipe(pipe);
   } catch (error: unknown) {
@@ -241,21 +248,21 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
             maxLines: MAX_HASH_LINES,
           });
           const { editParams, anchorLine, contentSeparators } = buildInsertEdit(req, preload, ref, targetPath);
+          const anchorCarry = insertAnchorCarry(req.direction, editParams, anchorLine);
           const pipe = await execPipeline(targetPath, editParams, ctx.cwd, {
             accessMode: constants.R_OK | constants.W_OK,
             signal,
             preloadedNorm: preload,
             stripWarning: insertStripWarning(anchorLine, req.direction),
             endingOverrides: contentSeparators,
+            ...(anchorCarry !== undefined ? { anchorCarry } : {}),
           });
           return commitEdit(pipe, {
             path: pipe.path,
             absolutePath,
             mutationTargetPath,
             editAnchors: [editParams.remove_from, editParams.remove_to],
-            ...(anchorLine === undefined
-              ? {}
-              : { anchorCarry: req.direction === "after" ? 0 : editParams.text.length - 1 }),
+            ...(anchorCarry !== undefined ? { anchorCarry } : {}),
             signal,
             verb: "inserted",
             noopNoun: "Insertion",

package/src/read.ts

@@ -23,7 +23,7 @@ import { withAnchorSession, adoptAnchors, ownerOf, ownersDifferingOnlyByCase, fo
 import { serveRows } from "./served";
 import { snapshotCache } from "./hash-store/cache";
 import { Text } from "@earendil-works/pi-tui";
-import { anchoredLine, readResultSchema, withStructuredErrors, type AnchoredLine, type ReadResult } from "./structured";
+import { anchoredLine, readResultSchema, withStructuredErrors, type AnchoredLine, type ReadResult, type ReadTextResult } from "./structured";
 const R_DESC = loadP("../tool-prompts/read.md");
 const R_SNIPPET = loadP("../tool-prompts/read-snippet.md");
 function readGuide(): Guideline[] {
@@ -241,7 +241,6 @@ function anchorRefOf(args: unknown): { anchor: string; limit: number | undefined
 	const { offset, limit, path } = args;
 	if (typeof offset !== "string" || offset.length === 0 || /^\d+$/.test(offset)) return undefined;
 	const validLimit = typeof limit === "number" && Number.isInteger(limit) && limit >= 1 ? limit : undefined;
-	if (limit !== undefined && validLimit === undefined) return undefined;
 	return { anchor: offset, limit: validLimit, path: typeof path === "string" ? path : undefined };
 }
 
@@ -263,28 +262,79 @@ function anchorLineOf(anchor: string, path: string | undefined, cwd: unknown): n
 	return index < 0 ? undefined : index + 1;
 }
 
+const ANSI_ESC = String.fromCharCode(27);
+const CALL_ANSI_RE = new RegExp(`${ANSI_ESC}\\[[0-9;]*m`, "g");
+const CALL_ANSI_AT_RE = new RegExp(`^${ANSI_ESC}\\[[0-9;]*m`);
+
+function rawIndexForPlainIndex(text: string, plainIndex: number): number {
+	let raw = 0;
+	let plain = 0;
+	while (raw < text.length && plain < plainIndex) {
+		const escape = CALL_ANSI_AT_RE.exec(text.slice(raw));
+		if (escape !== null) {
+			raw += escape[0].length;
+			continue;
+		}
+		raw += 1;
+		plain += 1;
+	}
+	return raw;
+}
+
+export function insertBeforeExpandHint(text: string, suffix: string): string {
+	const plain = text.replace(CALL_ANSI_RE, "");
+	if (!plain.endsWith(" to expand)")) return `${text}${suffix}`;
+	const plainIndex = plain.lastIndexOf(" (");
+	const insertAt = plainIndex < 0 ? text.length : rawIndexForPlainIndex(text, plainIndex);
+	return `${text.slice(0, insertAt)}${suffix}${text.slice(insertAt)}`;
+}
+
+function anchorRangeLabel(ref: { anchor: string; limit: number | undefined }, line: number | undefined): string {
+	if (line === undefined) return ref.limit === undefined ? `:${ref.anchor}` : `:${ref.anchor} +${ref.limit}`;
+	return ref.limit === undefined ? `:${line} (${ref.anchor})` : `:${line}-${line + ref.limit - 1} (${ref.anchor})`;
+}
+
 function renderReadCall(args: unknown, theme: any, context: any): Text {
 	const normalized = normalizeReadCallArgs(args);
-	const rendered = builtinReadRenderCall(normalized, theme, context);
 	const ref = anchorRefOf(normalized);
-	if (ref === undefined) return rendered;
-	const marker = `:${ref.anchor}`;
-	const text = (rendered as unknown as { text: string }).text;
-	const index = text.lastIndexOf(marker);
-	if (index < 0) return rendered;
+	if (ref === undefined) return builtinReadRenderCall(normalized, theme, context);
+	const rendered = builtinReadRenderCall(isRec(normalized) ? { ...normalized, offset: undefined, limit: undefined } : normalized, theme, context);
 	const line = anchorLineOf(ref.anchor, ref.path, context?.cwd);
-	if (line === undefined) {
-		if (ref.limit === undefined) return rendered;
-		const suffix = theme.fg("warning", ` +${ref.limit}`);
-		rendered.setText(`${text.slice(0, index + marker.length)}${suffix}${text.slice(index + marker.length)}`);
-		return rendered;
-	}
-	const range = ref.limit === undefined ? `${line}` : `${line}-${line + ref.limit - 1}`;
-	const replacement = theme.fg("warning", `:${range} (${ref.anchor})`);
-	rendered.setText(`${text.slice(0, index)}${replacement}${text.slice(index + marker.length)}`);
+	const suffix = theme.fg("warning", anchorRangeLabel(ref, line));
+	const text = (rendered as unknown as { text: string }).text;
+	rendered.setText(insertBeforeExpandHint(text, suffix));
 	return rendered;
 }
 
+function buildReadToolSchema(codemode: boolean) {
+	return Type.Object({
+		path: Type.String({
+			description: "Path to the file to read (relative or absolute)",
+		}),
+		offset: Type.Optional(
+			Type.Union([
+				Type.Integer({ minimum: 1 }),
+				Type.String(),
+			], { description: "Line number (1-indexed) or a served anchor to start reading from" }),
+		),
+		limit: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				description: "Maximum number of lines to read from offset",
+			}),
+		),
+		...(codemode
+			? {
+					anchors: Type.Optional(
+						Type.Boolean({
+							description: "Return { text, lines, notices } with editable anchors instead of the plain file text to a codemode script",
+						}),
+					),
+				}
+			: {}),
+	});
+}
+
 export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FLAGS): void {
   const prompted = withReadPrompts({ description: R_DESC, snippet: R_SNIPPET, guidelines: readGuide() }, flags);
   pi.registerTool({
@@ -294,23 +344,7 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
     promptSnippet: prompted.snippet,
     promptGuidelines: prompted.guidelines,
 		prepareArguments: makePrepareArguments(),
-		parameters: Type.Object({
-			path: Type.String({
-				description: "Path to the file to read (relative or absolute)",
-			}),
-			offset: Type.Optional(
-				Type.Union([
-					Type.Integer({ minimum: 1 }),
-					Type.String(),
-				], { description: "Line number (1-indexed) or a served anchor to start reading from" }),
-			),
-			limit: Type.Optional(
-				Type.Integer({
-					minimum: 1,
-					description: "Maximum number of lines to read from offset",
-				}),
-			),
-		}),
+		parameters: buildReadToolSchema(flags.codemode),
 		outputSchema: readResultSchema,
 		executionMode: "sequential",
 		renderCall: renderReadCall,
@@ -370,7 +404,7 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 				const servedRawText = preview.anchoredLines.map((row) => fileLines[row.line - 1] ?? "").join("\n");
 				const rawTruncation = servedRawText.length > 0 ? truncateHead(servedRawText, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES }) : undefined;
 
-				const structuredContent: ReadResult = {
+				const readResult: ReadTextResult = {
 					ok: true,
 					kind: "read",
 					path: rawPath,
@@ -384,6 +418,8 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 					hadUtf8DecodeErrors,
 					notices,
 				};
+				const anchorsRequested = isRec(params) && params.anchors === true;
+				const structuredContent: ReadResult = flags.codemode && !anchorsRequested ? readResult.text : readResult;
 				return {
 					content: [{ type: "text", text: previewText }],
 					details: {

package/src/replace-diff.ts

@@ -159,6 +159,40 @@ function placeSpans(
   return placed;
 }
 
+function splitPlacedSpan(
+  span: PlacedSpan,
+  oldLines: string[],
+  newLines: string[],
+  oldHashes: string[],
+  newIndexByHash: ReadonlyMap<string, number>,
+): PlacedSpan[] {
+  if (span.oldStart > span.oldEnd || span.newStart > span.newEnd) return [span];
+  const pairs: Array<[number, number]> = [];
+  let lastNew = span.newStart - 1;
+  for (let oldIdx = span.oldStart; oldIdx <= span.oldEnd; oldIdx++) {
+    const newIdx = newIndexByHash.get(oldHashes[oldIdx]!);
+    if (newIdx === undefined || newIdx < span.newStart || newIdx > span.newEnd || newIdx <= lastNew) continue;
+    if (oldLines[oldIdx] !== newLines[newIdx]) continue;
+    pairs.push([oldIdx, newIdx]);
+    lastNew = newIdx;
+  }
+  if (pairs.length === 0) return [span];
+  const out: PlacedSpan[] = [];
+  let oldCursor = span.oldStart;
+  let newCursor = span.newStart;
+  for (const [oldIdx, newIdx] of pairs) {
+    if (oldCursor <= oldIdx - 1 || newCursor <= newIdx - 1) {
+      out.push({ oldStart: oldCursor, oldEnd: oldIdx - 1, newStart: newCursor, newEnd: newIdx - 1 });
+    }
+    oldCursor = oldIdx + 1;
+    newCursor = newIdx + 1;
+  }
+  if (oldCursor <= span.oldEnd || newCursor <= span.newEnd) {
+    out.push({ oldStart: oldCursor, oldEnd: span.oldEnd, newStart: newCursor, newEnd: span.newEnd });
+  }
+  return out;
+}
+
 function trimPlacedSpans(
   placed: PlacedSpan[],
   oldLines: string[],
@@ -166,22 +200,11 @@ function trimPlacedSpans(
   oldHashes: string[],
   newHashes: string[],
 ): PlacedSpan[] {
+  const newIndexByHash = new Map<string, number>();
+  for (let index = 0; index < newHashes.length; index++) newIndexByHash.set(newHashes[index]!, index);
   const out: PlacedSpan[] = [];
   for (const span of placed) {
-    let oldStart = span.oldStart;
-    let oldEnd = span.oldEnd;
-    let newStart = span.newStart;
-    let newEnd = span.newEnd;
-    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldStart] === newLines[newStart] && oldHashes[oldStart] === newHashes[newStart]) {
-      oldStart += 1;
-      newStart += 1;
-    }
-    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldEnd] === newLines[newEnd] && oldHashes[oldEnd] === newHashes[newEnd]) {
-      oldEnd -= 1;
-      newEnd -= 1;
-    }
-    if (oldStart > oldEnd && newStart > newEnd) continue;
-    out.push({ oldStart, oldEnd, newStart, newEnd });
+    for (const piece of splitPlacedSpan(span, oldLines, newLines, oldHashes, newIndexByHash)) out.push(piece);
   }
   return out;
 }
@@ -364,7 +387,7 @@ export function genDiff(
 ): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number|undefined)[] } {
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
-  if (spans && newContentHashes && oldContentHashes) {
+  if (spans && spans.length > 0 && newContentHashes && oldContentHashes) {
     const anchored = genSpanDiff(oldContent, newContent, contextLines, newContentHashes, oldContentHashes, maxLineBytes, maxBytes, spans);
     if (anchored) {
       const diff = disambiguateDuplicateAnchors(anchored.diff);

package/src/replace.ts

@@ -87,6 +87,7 @@ export interface ExecPipelineOptions {
   stripWarning?: StripWarningLocation;
   endingOverrides?: (LineEnding | undefined)[];
   preserveDeletionSeparators?: boolean;
+  anchorCarry?: number;
 }
 
 export function hashSpan(hashes: string[], from: string, to: string): [number, number] | undefined {
@@ -205,20 +206,22 @@ export async function execPipeline(
   const result = anchorResult.content;
   const isNoop = result === originalNormalized;
 
+  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, effectiveEdit.hash_bounds[0].hash, effectiveEdit.hash_bounds[1].hash, result);
+  if (pipeSpan && options?.anchorCarry !== undefined) pipeSpan.carry = options.anchorCarry;
+  const pipeSpans = pipeSpan ? [pipeSpan] : undefined;
+
   const resultHashes = isNoop
     ? originalHashes
     : await lineHashes(result, absolutePath, {
         content: originalNormalized,
         hashes: originalHashes,
+        ...(pipeSpans ? { spans: pipeSpans } : {}),
       }, hashStore, false, true);
   const warnings = [...editWarnings, ...(anchorResult.warnings ?? [])];
   await throwIfStrictInput(warnings);
   const { totalAddedLines, totalRemovedLines } = countLineChanges(
     effectiveEdit, originalHashes, isNoop,
   );
-
-  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, effectiveEdit.hash_bounds[0].hash, effectiveEdit.hash_bounds[1].hash, result);
-  const pipeSpans = pipeSpan ? [pipeSpan] : undefined;
   return {
     path: displayPath,
     originalNormalized,

package/src/utils.ts

@@ -41,6 +41,24 @@ export function splitLines(text: string): string[] {
   return text.endsWith("\n") ? lines.slice(0, -1) : lines;
 }
 
+export function spliceAll<T>(target: T[], start: number, deleteCount: number, items: readonly T[]): T[] {
+  const rawStart = Number.isNaN(start) ? 0 : Math.trunc(start);
+  const at = rawStart < 0 ? Math.max(target.length + rawStart, 0) : Math.min(rawStart, target.length);
+  const rawCount = Number.isNaN(deleteCount) ? 0 : Math.trunc(deleteCount);
+  const remove = Math.max(0, Math.min(rawCount, target.length - at));
+  const removed = target.slice(at, at + remove);
+  const tail = target.slice(at + remove);
+  const additions: readonly T[] = items === target ? [...items] : items;
+  target.length = at;
+  for (const item of additions) target.push(item);
+  for (const item of tail) target.push(item);
+  return removed;
+}
+
+export function anchorCarryIndex(direction: "after" | "before", lineCount: number): number {
+  return direction === "after" ? 0 : lineCount;
+}
+
 export function visLines(text: string): string[] {
   return text.length === 0 ? [] : splitLines(text);
 }
@@ -194,10 +212,12 @@ export function clipLine(line: string, maxLen = 200): string {
 	const flat = line.replace(/\n/g, "\\n");
 	return flat.length > maxLen ? `${flat.slice(0, maxLen)}...` : flat;
 }
-export function assertLineLimit(content: string, displayPath: string, limit: number): void {
-	const count = splitLines(content).length;
+export function assertLineCount(count: number, displayPath: string, limit: number): void {
 	if (count > limit) throw new Error(formatLineLimit(displayPath, limit, count));
 }
+export function assertLineLimit(content: string, displayPath: string, limit: number): void {
+	assertLineCount(splitLines(content).length, displayPath, limit);
+}
 export function assertByteLimit(content: string, displayPath: string, limit = MAX_BYTES): void {
 	if (Buffer.byteLength(content, "utf-8") > limit) {
 		throw new Error(`[E_FILE_TOO_LARGE] File is too large: ${displayPath} (exceeds the ${limit / (1024 * 1024)}MB size limit). For very large files, use write.`);