@wahack/pi-coding-agent 15.11.0

package/src/edit/file-snapshot-store.ts

@@ -0,0 +1,91 @@
+/**
+ * Session-bound file snapshot store.
+ *
+ * Used by `read` and `search` to record exactly what the model saw, and by
+ * the hashline patcher to verify or recover from stale section tags (file
+ * changed externally between read and edit, or a prior in-session edit
+ * advanced the tag). The store is the {@link InMemorySnapshotStore}
+ * from `@oh-my-pi/hashline`; the only coding-agent-specific concern here
+ * is wiring it onto the per-session owner object.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { InMemorySnapshotStore } from "@oh-my-pi/hashline";
+import { normalizeToLF } from "./normalize";
+
+/**
+ * Upper bound on the file size we snapshot. A section tag is a content hash of
+ * the *whole* file, so minting one means holding the full normalized text in
+ * the store. Files above this cap emit no `[path#tag]` header — line-anchored
+ * editing of multi-megabyte files is out of scope under the full-content model.
+ */
+export const SNAPSHOT_MAX_BYTES = 4 * 1024 * 1024;
+
+interface FileSnapshotStoreOwner {
+	fileSnapshotStore?: InMemorySnapshotStore;
+}
+
+/**
+ * Look up (or lazily create) the file snapshot store attached to a session.
+ * Storage lives on `session.fileSnapshotStore` so it ages out exactly with
+ * the session itself.
+ */
+export function getFileSnapshotStore(session: FileSnapshotStoreOwner): InMemorySnapshotStore {
+	if (!session.fileSnapshotStore) session.fileSnapshotStore = new InMemorySnapshotStore();
+	return session.fileSnapshotStore;
+}
+
+/**
+ * Canonicalize an absolute path into the stable key the snapshot store uses.
+ *
+ * Different code paths reach the snapshot store via different path forms:
+ * `read local://foo.md` records under the file's `fs.realpath` (the local
+ * protocol handler resolves symlinks); a subsequent `edit` may address the
+ * same artifact via `local://foo.md`, whose resolver does NOT realpath, or
+ * via the absolute path returned in the `[path#tag]` header. macOS adds the
+ * same hazard at the working-tree level (`/tmp/...` vs `/private/tmp/...`).
+ * Collapsing every key through `realpath` makes those forms fuse onto one
+ * snapshot entry, so a freshly-minted tag is never rejected as stale just
+ * because the lookup spelled the same file differently.
+ *
+ * Non-existent paths (new-file writes) fall back to a realpath of the parent
+ * directory + basename, then to the input. This keeps creates and updates on
+ * the same canonical key.
+ */
+export function canonicalSnapshotKey(absolutePath: string): string {
+	try {
+		return fs.realpathSync.native(absolutePath);
+	} catch {
+		try {
+			const parent = fs.realpathSync.native(path.dirname(absolutePath));
+			return path.join(parent, path.basename(absolutePath));
+		} catch {
+			return absolutePath;
+		}
+	}
+}
+
+/**
+ * Read the full text of `absolutePath` (within {@link SNAPSHOT_MAX_BYTES}),
+ * record it as a version snapshot, and return its content-hash tag. Returns
+ * `undefined` when the file exceeds the cap or cannot be read — callers then
+ * omit the section header so the model never sees a tag it can't anchor against.
+ *
+ * Producers that only displayed a slice of the file (range reads, search hits)
+ * use this to mint a whole-file tag: the displayed lines stay partial, but the
+ * tag fingerprints the entire file so a follow-up edit anchored at any line
+ * validates whenever the live file is byte-identical to what was read.
+ */
+export async function recordFileSnapshot(
+	session: FileSnapshotStoreOwner,
+	absolutePath: string,
+): Promise<string | undefined> {
+	try {
+		const file = Bun.file(absolutePath);
+		if (file.size > SNAPSHOT_MAX_BYTES) return undefined;
+		const normalized = normalizeToLF(await file.text());
+		return getFileSnapshotStore(session).record(canonicalSnapshotKey(absolutePath), normalized);
+	} catch {
+		return undefined;
+	}
+}

package/src/edit/hashline/block-resolver.ts

@@ -0,0 +1,33 @@
+/**
+ * Tree-sitter-backed {@link BlockResolver} for the hashline `replace block N:`
+ * operator. Bridges the pure hashline seam to the native `blockRangeAt`
+ * primitive in `@oh-my-pi/pi-natives`, which infers the language from the file
+ * path and returns the 1-indexed line span of the syntactic block beginning on
+ * the requested line (or `null` when none can be resolved).
+ */
+import type { BlockResolver } from "@oh-my-pi/hashline";
+import { blockRangeAt } from './stubs/natives/index.ts';
+
+/**
+ * `blockRangeAt` runs a full synchronous tree-sitter parse of `text` per
+ * call, and streaming previews re-resolve the same (text, line) every
+ * streamed chunk. Memoize by content: identical text + line always yields the
+ * same span. FIFO-bounded; hashing the text is orders of magnitude cheaper
+ * than re-parsing it.
+ */
+const resolutionCache = new Map<string, { start: number; end: number } | null>();
+const RESOLUTION_CACHE_MAX = 512;
+
+export const nativeBlockResolver: BlockResolver = ({ path, text, line }) => {
+	const key = `${Bun.hash(text).toString(36)}:${text.length}:${line}:${path}`;
+	const cached = resolutionCache.get(key);
+	if (cached !== undefined) return cached;
+	const range = blockRangeAt({ code: text, path, line });
+	const result = range ? { start: range.startLine, end: range.endLine } : null;
+	if (resolutionCache.size >= RESOLUTION_CACHE_MAX) {
+		const oldest = resolutionCache.keys().next().value;
+		if (oldest !== undefined) resolutionCache.delete(oldest);
+	}
+	resolutionCache.set(key, result);
+	return result;
+};

package/src/edit/hashline/diff.ts

@@ -0,0 +1,290 @@
+/**
+ * Read-only hashline diff preview helpers used by the streaming edit
+ * renderer. Reads the target file, parses + applies the section's edits in
+ * memory (no FS write, no LSP writethrough), then hands the before/after
+ * pair to {@link generateDiffString} so the renderer can show the diff
+ * while the tool call is still streaming.
+ *
+ * Uses the same snapshot-tag semantics as the apply path: a live content-hash
+ * match is accepted even when the tag was minted by a source that did not keep
+ * history, and stale tags recover through the session snapshot store when possible.
+ */
+import {
+	type ApplyResult,
+	applyEdits,
+	type Cursor,
+	computeFileHash,
+	type Edit,
+	Patch as HashlinePatch,
+	hasBlockEdit,
+	MismatchError,
+	missingSnapshotTagMessage,
+	normalizeToLF,
+	type Patch,
+	type PatchSection,
+	parsePatchStreaming,
+	Recovery,
+	resolveBlockEdits,
+	type SnapshotStore,
+	stripBom,
+} from "@oh-my-pi/hashline";
+import { resolveToCwd } from "../../tools/path-utils";
+import { generateDiffString } from "../diff";
+import { readEditFileText } from "../read-file";
+import { nativeBlockResolver } from "./block-resolver";
+
+export interface HashlineDiffOptions {
+	/**
+	 * Use the streaming-tolerant applier ({@link PatchSection.applyPartialTo})
+	 * so trailing in-flight ops do not throw or emit phantom edits. Streaming
+	 * preview path only.
+	 */
+	streaming?: boolean;
+	/**
+	 * Skip snapshot-tag validation. Streaming previews use this so transient
+	 * stale/missing tags do not flash re-read errors while the model is still
+	 * authoring input; the final apply path still validates through Patcher.
+	 */
+	skipHashValidation?: boolean;
+}
+
+async function readSectionText(absolutePath: string, sectionPath: string): Promise<string> {
+	try {
+		return await readEditFileText(absolutePath, sectionPath);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(message || `Unable to read ${sectionPath}`);
+	}
+}
+
+/**
+ * Streaming previews recompute on every streamed chunk; re-reading the target
+ * file from disk each tick dominates the cost on large files. Cache the raw
+ * section text keyed by mtime+size so any on-disk change invalidates
+ * naturally. Used by the streaming path only — the args-complete pass always
+ * reads fresh.
+ */
+const streamingTextCache = new Map<string, { mtimeMs: number; size: number; rawContent: string }>();
+const STREAMING_TEXT_CACHE_MAX = 8;
+
+async function readSectionTextCached(absolutePath: string, sectionPath: string): Promise<string> {
+	let stamp: { mtimeMs: number; size: number } | undefined;
+	try {
+		const stat = await Bun.file(absolutePath).stat();
+		stamp = { mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		stamp = undefined;
+	}
+	if (stamp) {
+		const cached = streamingTextCache.get(absolutePath);
+		if (cached && cached.mtimeMs === stamp.mtimeMs && cached.size === stamp.size) return cached.rawContent;
+	}
+	const rawContent = await readSectionText(absolutePath, sectionPath);
+	if (stamp) {
+		if (streamingTextCache.size >= STREAMING_TEXT_CACHE_MAX && !streamingTextCache.has(absolutePath)) {
+			const oldest = streamingTextCache.keys().next().value;
+			if (oldest !== undefined) streamingTextCache.delete(oldest);
+		}
+		streamingTextCache.set(absolutePath, { mtimeMs: stamp.mtimeMs, size: stamp.size, rawContent });
+	}
+	return rawContent;
+}
+
+function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
+	return edits.some(edit => {
+		if (edit.kind === "delete") return true;
+		if (edit.kind === "block") return true;
+		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
+	});
+}
+
+function createMismatchError(
+	section: PatchSection,
+	absolutePath: string,
+	normalized: string,
+	snapshots: SnapshotStore,
+	expected: string,
+): MismatchError {
+	return new MismatchError({
+		path: section.path,
+		expectedFileHash: expected,
+		actualFileHash: computeFileHash(normalized),
+		fileLines: normalized.split("\n"),
+		anchorLines: section.collectAnchorLines(),
+		hashRecognized: snapshots.byHash(absolutePath, expected) !== null,
+	});
+}
+
+function parsePreviewEdits(section: PatchSection, streaming: boolean | undefined): readonly Edit[] {
+	return streaming ? parsePatchStreaming(section.diff).edits : section.edits;
+}
+
+function resolvePreviewEdits(args: {
+	section: PatchSection;
+	absolutePath: string;
+	normalized: string;
+	snapshots: SnapshotStore;
+	expected: string | undefined;
+	liveMatches: boolean;
+	edits: readonly Edit[];
+}): readonly Edit[] {
+	const { section, absolutePath, normalized, snapshots, expected, liveMatches, edits } = args;
+	if (!hasBlockEdit(edits)) return edits;
+	const baseText = expected === undefined || liveMatches ? normalized : snapshots.byHash(absolutePath, expected)?.text;
+	if (baseText === undefined) {
+		throw createMismatchError(section, absolutePath, normalized, snapshots, expected ?? "");
+	}
+	return resolveBlockEdits(edits, baseText, section.path, nativeBlockResolver, { onUnresolved: "throw" });
+}
+
+function applyPreviewEdits(args: {
+	section: PatchSection;
+	absolutePath: string;
+	normalized: string;
+	snapshots: SnapshotStore;
+	options: HashlineDiffOptions;
+}): ApplyResult {
+	const { section, absolutePath, normalized, snapshots, options } = args;
+	const expected = section.fileHash;
+	if (!options.skipHashValidation && expected === undefined) {
+		throw new Error(missingSnapshotTagMessage(section.path));
+	}
+	const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
+	const edits = parsePreviewEdits(section, options.streaming);
+	const resolved = resolvePreviewEdits({ section, absolutePath, normalized, snapshots, expected, liveMatches, edits });
+	if (options.skipHashValidation || expected === undefined || liveMatches) return applyEdits(normalized, resolved);
+	if (!hasAnchorScopedEdit(resolved)) return applyEdits(normalized, resolved);
+
+	const recovered = new Recovery(snapshots).tryRecover({
+		path: absolutePath,
+		currentText: normalized,
+		fileHash: expected,
+		edits: resolved,
+	});
+	if (recovered) return recovered;
+	throw createMismatchError(section, absolutePath, normalized, snapshots, expected);
+}
+
+/**
+ * Map an insert cursor to the 1-indexed line where its payload lands, used to
+ * number the `+` rows of a streaming preview. Deliberately approximate: it
+ * ignores line shifts introduced by sibling ops, because the args-complete
+ * pass renumbers everything through the real unified diff.
+ */
+function insertCursorLine(cursor: Cursor, fileLineCount: number): number {
+	switch (cursor.kind) {
+		case "bof":
+			return 1;
+		case "eof":
+			return fileLineCount + 1;
+		case "before_anchor":
+			return cursor.anchor.line;
+		case "after_anchor":
+			return cursor.anchor.line + 1;
+	}
+}
+
+/**
+ * Build a streaming diff preview by emitting, per op in patch order, the
+ * removed file lines followed by the op's `+` payload rows — never a whole-file
+ * Myers re-diff. {@link generateDiffString} re-aligns the in-flight payload
+ * against the removed block on every streamed chunk (it greedily matches shared
+ * `}`/blank/`return` rows), so additions jump between hunks and the tail window
+ * the renderer pins stutters tick to tick. Natural order keeps the removed
+ * block fixed and grows the payload monotonically at the bottom so the streamed
+ * cursor stays put. Mirrors the apply_patch streaming strategy; the
+ * args-complete pass still produces the real unified diff.
+ */
+function buildStreamingSectionDiff(
+	section: PatchSection,
+	normalized: string,
+): { diff: string; firstChangedLine: number | undefined } | { error: string } {
+	const { edits } = parsePatchStreaming(section.diff);
+	const resolved = resolveBlockEdits(edits, normalized, section.path, nativeBlockResolver, { onUnresolved: "drop" });
+	if (resolved.length === 0) return { error: `No changes would be made to ${section.path}.` };
+
+	const fileLines = normalized.split("\n");
+	const rows: string[] = [];
+	let firstChangedLine: number | undefined;
+
+	// Every edit emitted from one op header carries that header's patch line
+	// number and the edits sit contiguously (a replace lays down its replacement
+	// inserts then its range deletes; block ops expand to the same shape). Group
+	// on that boundary so each op stays intact and ordered.
+	for (let i = 0; i < resolved.length; ) {
+		const opLine = resolved[i].lineNum;
+		const deletes: number[] = [];
+		const inserts: string[] = [];
+		let insertBase: number | undefined;
+		while (i < resolved.length && resolved[i].lineNum === opLine) {
+			const edit = resolved[i];
+			if (edit.kind === "delete") deletes.push(edit.anchor.line);
+			else if (edit.kind === "insert") {
+				insertBase ??= insertCursorLine(edit.cursor, fileLines.length);
+				inserts.push(edit.text);
+			}
+			i++;
+		}
+		// Removed lines first (a fixed block), payload second (grows at the
+		// bottom = the streamed cursor).
+		deletes.sort((a, b) => a - b);
+		for (const line of deletes) {
+			firstChangedLine ??= line;
+			const content = line >= 1 && line <= fileLines.length ? fileLines[line - 1] : "";
+			rows.push(`-${line}|${content}`);
+		}
+		let newLine = insertBase ?? deletes[0] ?? 1;
+		for (const text of inserts) {
+			firstChangedLine ??= newLine;
+			rows.push(`+${newLine}|${text}`);
+			newLine++;
+		}
+	}
+
+	if (rows.length === 0) return { error: `No changes would be made to ${section.path}.` };
+	return { diff: rows.join("\n"), firstChangedLine };
+}
+
+export async function computeHashlineSectionDiff(
+	section: PatchSection,
+	cwd: string,
+	snapshots: SnapshotStore,
+	options: HashlineDiffOptions = {},
+): Promise<{ diff: string; firstChangedLine: number | undefined } | { error: string }> {
+	try {
+		const absolutePath = resolveToCwd(section.path, cwd);
+		const rawContent = options.streaming
+			? await readSectionTextCached(absolutePath, section.path)
+			: await readSectionText(absolutePath, section.path);
+		const { text: content } = stripBom(rawContent);
+		const normalized = normalizeToLF(content);
+		// Streaming favors a stable, monotonic preview over an exact unified
+		// diff: feed the in-flight ops through the natural-order builder so the
+		// streamed cursor stays pinned to the bottom. The args-complete pass
+		// (`streaming` unset) falls through to the real Myers diff below.
+		if (options.streaming) return buildStreamingSectionDiff(section, normalized);
+		const result = applyPreviewEdits({ section, absolutePath, normalized, snapshots, options });
+		if (normalized === result.text) return { error: `No changes would be made to ${section.path}.` };
+		return generateDiffString(normalized, result.text, undefined, { path: section.path });
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export async function computeHashlineDiff(
+	input: { input: string },
+	cwd: string,
+	snapshots: SnapshotStore,
+	options: HashlineDiffOptions = {},
+): Promise<{ diff: string; firstChangedLine: number | undefined } | { error: string }> {
+	let patch: Patch;
+	try {
+		patch = HashlinePatch.parse(input.input, { cwd });
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+	if (patch.sections.length !== 1) {
+		return { error: "Streaming diff preview supports exactly one hashline section." };
+	}
+	return computeHashlineSectionDiff(patch.sections[0], cwd, snapshots, options);
+}

package/src/edit/hashline/execute.ts

@@ -0,0 +1,242 @@
+/**
+ * Coding-agent runner that drives the hashline {@link Patcher} on behalf of
+ * the `edit` tool. Converts a `{input}` tool-call payload into a
+ * fully-applied patch, wraps the result in the agent's
+ * {@link AgentToolResult} shape, and attaches LSP diagnostics + `outputMeta`
+ * for the renderer.
+ *
+ * Multi-section patches are preflighted up front via {@link Patcher.prepare}
+ * so a partial batch never lands; the commit loop then narrows the LSP
+ * batch's `flush` flag to true only for the final write so diagnostics
+ * round-trip once.
+ */
+import {
+	type BlockResolution,
+	buildCompactDiffPreview,
+	MismatchError as HashlineMismatchError,
+	Patch,
+	Patcher,
+	type PatchSectionResult,
+	type PreparedSection,
+} from "@oh-my-pi/hashline";
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { FileDiagnosticsResult, WritethroughCallback, WritethroughDeferredHandle } from "../../lsp";
+import type { ToolSession } from "../../tools";
+import { outputMeta } from "../../tools/output-meta";
+import { ToolError } from "../../tools/tool-errors";
+import { generateDiffString } from "../diff";
+import { getFileSnapshotStore } from "../file-snapshot-store";
+import type { EditToolDetails, EditToolPerFileResult, LspBatchRequest } from "../renderer";
+import { nativeBlockResolver } from "./block-resolver";
+import { HashlineFilesystem } from "./filesystem";
+import { hashPatchInput, NOOP_HARD_LIMIT, recordNoopEdit, resetNoopEdit } from "./noop-loop-guard";
+import { type HashlineParams, hashlineEditParamsSchema } from "./params";
+
+export interface ExecuteHashlineSingleOptions {
+	session: ToolSession;
+	input: string;
+	signal?: AbortSignal;
+	batchRequest?: LspBatchRequest;
+	writethrough: WritethroughCallback;
+	beginDeferredDiagnosticsForPath: (path: string) => WritethroughDeferredHandle;
+}
+
+function noChangeDiagnostic(path: string): string {
+	// The patch parsed and applied cleanly but produced no change — the
+	// `|literal` body rows matched the file content at the targeted lines
+	// byte-for-byte. The model usually misreads this as "wrong anchor, try
+	// again with a bigger payload" and starts duplicating content; the
+	// message below names the cause directly so the next turn can re-read
+	// instead of expanding the patch.
+	return (
+		`Edits to ${path} parsed and applied cleanly, but produced no change: ` +
+		`your body row(s) are byte-identical to the file at the targeted lines. ` +
+		`The bug is somewhere else — re-read the file before issuing another edit. ` +
+		`Do NOT widen the payload or add lines; verify the anchor first.`
+	);
+}
+
+/**
+ * Escalated diagnostic surfaced once the same payload has no-op'd
+ * {@link NOOP_HARD_LIMIT} times in a row on the same canonical path. Thrown as
+ * a {@link ToolError} so the agent loop sees a tool *failure* — empirically
+ * far more effective at breaking a no-op edit loop than the soft hint alone
+ * (issue #2081 saw 182 byte-identical no-op results in 205 calls before the
+ * user aborted).
+ */
+function noChangeLoopDiagnostic(path: string, count: number): string {
+	return (
+		`STOP. Edits to ${path} have been a byte-identical no-op ${count} times in a row — ` +
+		`the patch body matches the file at the targeted lines and the soft hint did not break the cycle. ` +
+		`Cease re-issuing this payload. Either the intended change is already on disk (move on), ` +
+		`or your anchor is wrong (re-read the file with \`read\` to observe the current line numbers and ` +
+		`tag, then author a different edit). This exact payload will keep being rejected until it changes.`
+	);
+}
+
+function assertUniqueCanonicalPaths(prepared: readonly PreparedSection[]): void {
+	const seen = new Map<string, string>();
+	for (const entry of prepared) {
+		const previous = seen.get(entry.canonicalPath);
+		if (previous !== undefined) {
+			throw new Error(
+				`Multiple hashline sections resolve to the same file (${previous} and ${entry.section.path}). Merge their ops under one header before applying.`,
+			);
+		}
+		seen.set(entry.canonicalPath, entry.section.path);
+	}
+}
+
+function narrowBatchRequest(outer: LspBatchRequest | undefined, isLast: boolean): LspBatchRequest | undefined {
+	if (!outer) return undefined;
+	return { id: outer.id, flush: isLast && outer.flush };
+}
+
+interface RenderedSection {
+	toolResult: AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema>;
+	perFileResult: EditToolPerFileResult;
+}
+
+function formatBlockResolution(resolution: BlockResolution): string {
+	const op =
+		resolution.op === "delete"
+			? "delete block"
+			: resolution.op === "insert_after"
+				? "insert after block"
+				: "replace block";
+	const lines = resolution.end - resolution.start + 1;
+	const span =
+		resolution.start === resolution.end ? `line ${resolution.start}` : `lines ${resolution.start}-${resolution.end}`;
+	const suffix = resolution.op === "insert_after" ? `; body lands after line ${resolution.end}` : "";
+	return `${op} ${resolution.anchorLine} → resolved ${span} (${lines} line${lines === 1 ? "" : "s"})${suffix}`;
+}
+
+function renderSection(result: PatchSectionResult, diagnostics: FileDiagnosticsResult | undefined): RenderedSection {
+	if (result.op === "noop") {
+		const toolResult: AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema> = {
+			content: [{ type: "text", text: noChangeDiagnostic(result.path) }],
+			details: { diff: "", op: "update", meta: outputMeta().get() },
+		};
+		return {
+			toolResult,
+			perFileResult: { path: result.path, diff: "", op: "update" },
+		};
+	}
+
+	const diff = generateDiffString(result.before, result.after, undefined, { path: result.path });
+	const preview = buildCompactDiffPreview(diff.diff);
+	const meta = outputMeta()
+		.diagnostics(diagnostics?.summary ?? "", diagnostics?.messages ?? [])
+		.get();
+
+	const warningsBlock = result.warnings.length > 0 ? `\n\nWarnings:\n${result.warnings.join("\n")}` : "";
+	const previewBlock = preview.preview ? `\n${preview.preview}` : "";
+	const blockBlock =
+		result.blockResolutions && result.blockResolutions.length > 0
+			? `\n${result.blockResolutions.map(formatBlockResolution).join("\n")}`
+			: "";
+	const firstChangedLine = result.firstChangedLine ?? diff.firstChangedLine;
+	return {
+		toolResult: {
+			content: [{ type: "text", text: `${result.header}${blockBlock}${previewBlock}${warningsBlock}` }],
+			details: {
+				diff: diff.diff,
+				firstChangedLine,
+				diagnostics,
+				op: result.op,
+				meta,
+			},
+		},
+		perFileResult: {
+			path: result.path,
+			diff: diff.diff,
+			firstChangedLine,
+			diagnostics,
+			op: result.op,
+		},
+	};
+}
+
+export async function executeHashlineSingle(
+	options: ExecuteHashlineSingleOptions,
+): Promise<AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema>> {
+	const patch = Patch.parse(options.input, { cwd: options.session.cwd });
+	if (patch.sections.length === 0) {
+		throw new Error("No hashline sections found in input.");
+	}
+
+	const fs = new HashlineFilesystem({
+		session: options.session,
+		writethrough: options.writethrough,
+		beginDeferredDiagnosticsForPath: options.beginDeferredDiagnosticsForPath,
+		signal: options.signal,
+		batchRequest: options.batchRequest,
+	});
+	const snapshots = getFileSnapshotStore(options.session);
+	const patcher = new Patcher({ fs, snapshots, blockResolver: nativeBlockResolver });
+
+	// Single-section fast path: prepare, commit, render.
+	const inputHash = hashPatchInput(options.input);
+	if (patch.sections.length === 1) {
+		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, true));
+		const prepared = await patcher.prepare(patch.sections[0]);
+		const sectionResult = await patcher.commit(prepared);
+		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			if (escalate) {
+				throw new ToolError(noChangeLoopDiagnostic(sectionResult.path, count));
+			}
+			return renderSection(sectionResult, undefined).toolResult;
+		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
+		return renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)).toolResult;
+	}
+
+	// Multi-section: prepare every section up front so we fail fast before
+	// any write hits the filesystem.
+	const prepared: PreparedSection[] = [];
+	for (const section of patch.sections) prepared.push(await patcher.prepare(section));
+	assertUniqueCanonicalPaths(prepared);
+	for (const entry of prepared) {
+		if (entry.isNoop) {
+			const { count, escalate } = recordNoopEdit(options.session, entry.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(entry.section.path, count))
+				: new ToolError(noChangeDiagnostic(entry.section.path));
+		}
+	}
+	// Then commit each one, narrowing the LSP batch flush flag to the final
+	// section only. A no-op apply mid-batch is treated as a hard failure —
+	// the model authored anchors that match the current file content.
+	const rendered: RenderedSection[] = [];
+	for (let i = 0; i < prepared.length; i++) {
+		const isLast = i === prepared.length - 1;
+		fs.setBatchRequest(narrowBatchRequest(options.batchRequest, isLast));
+		const sectionResult = await patcher.commit(prepared[i]);
+		if (sectionResult.op === "noop") {
+			const { count, escalate } = recordNoopEdit(options.session, sectionResult.canonicalPath, inputHash);
+			throw escalate
+				? new ToolError(noChangeLoopDiagnostic(sectionResult.path, count))
+				: new ToolError(noChangeDiagnostic(sectionResult.path));
+		}
+		resetNoopEdit(options.session, sectionResult.canonicalPath);
+		rendered.push(renderSection(sectionResult, fs.consumeDiagnostics(sectionResult.path)));
+	}
+
+	return {
+		content: [
+			{
+				type: "text",
+				text: rendered
+					.map(r => r.toolResult.content.map(part => (part.type === "text" ? part.text : "")).join("\n"))
+					.join("\n\n"),
+			},
+		],
+		details: {
+			diff: rendered.map(r => r.toolResult.details?.diff ?? "").join("\n"),
+			perFileResults: rendered.map(r => r.perFileResult),
+		},
+	};
+}
+
+export { HashlineMismatchError, type HashlineParams, hashlineEditParamsSchema };