@oh-my-pi/pi-coding-agent 15.5.6 → 15.5.8

package/src/tools/image-gen.ts

@@ -22,12 +22,14 @@ import * as z from "zod/v4";
 import packageJson from "../../package.json" with { type: "json" };
 import { isAuthenticated, type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
+import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
 import imageGenDescription from "../prompts/tools/image-gen.md" with { type: "text" };
 import { resolveReadPath } from "./path-utils";
 
 const DEFAULT_MODEL = "gemini-3-pro-image-preview";
 const DEFAULT_OPENROUTER_MODEL = "google/gemini-3-pro-image-preview";
 const DEFAULT_ANTIGRAVITY_MODEL = "gemini-3-pro-image";
+const DEFAULT_XAI_IMAGE_MODEL = "grok-imagine-image";
 const IMAGE_TIMEOUT = 3 * 60 * 1000; // 3 minutes
 const MAX_IMAGE_SIZE = 35 * 1024 * 1024;
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
@@ -38,7 +40,9 @@ const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com"
 const IMAGE_SYSTEM_INSTRUCTION =
 	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
 
-type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
+export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+export type ImageProviderPreference = Exclude<ImageProvider, "openai-codex"> | "auto";
+
 interface ImageApiKey {
 	provider: ImageProvider;
 	apiKey: string;
@@ -46,8 +50,13 @@ interface ImageApiKey {
 	model?: Model;
 }
 
+const COMMON_IMAGE_ASPECT_RATIOS = ["1:1", "3:4", "4:3", "9:16", "16:9"] as const;
+const XAI_IMAGE_ASPECT_RATIOS = [...COMMON_IMAGE_ASPECT_RATIOS, "3:2", "2:3"] as const;
+const COMMON_IMAGE_ASPECT_RATIO_SET = new Set<string>(COMMON_IMAGE_ASPECT_RATIOS);
+const IMAGE_PROVIDER_PREFERENCES = new Set<string>(["auto", "antigravity", "gemini", "openai", "openrouter", "xai"]);
+
 const responseModalitySchema = z.enum(["IMAGE", "TEXT"] as const);
-const aspectRatioSchema = z.enum(["1:1", "3:4", "4:3", "9:16", "16:9"] as const).describe("aspect ratio");
+const aspectRatioSchema = z.enum(XAI_IMAGE_ASPECT_RATIOS).describe("aspect ratio");
 const imageSizeSchema = z.enum(["1024x1024", "1536x1024", "1024x1536"] as const).describe("image size");
 
 const inputImageSchema = z
@@ -274,6 +283,36 @@ interface AntigravityRequest {
 	requestId?: string;
 }
 
+interface XAIImageReference {
+	// OpenAI-compat discriminator. Every code example at
+	// docs.x.ai/developers/rest-api-reference/inference/images sends this
+	// alongside `url`; the schema text doesn't strictly require it, but
+	// matching the documented wire format avoids relying on schema-vs-example.
+	readonly type: "image_url";
+	readonly url: string;
+}
+
+interface XAIImageRequestBase {
+	readonly model: string;
+	readonly prompt: string;
+	readonly aspect_ratio: string;
+	readonly resolution: "1k" | "2k";
+	readonly n: number;
+	readonly response_format: "b64_json" | "url";
+}
+
+// xAI image request body. Three shapes:
+//   1. text-only generation                  → POST /v1/images/generations
+//   2. single-source edit (image field)      → POST /v1/images/edits
+//   3. multi-reference edit (images field)   → POST /v1/images/edits
+// `image` and `images` are mutually exclusive per docs.x.ai; the discriminated
+// union enforces that statically. The runtime cap (XAI_MAX_EDIT_IMAGES) bounds
+// the array length, which TypeScript cannot encode without lossy tuple unions.
+type XAIImageRequestBody =
+	| (XAIImageRequestBase & { readonly image?: never; readonly images?: never })
+	| (XAIImageRequestBase & { readonly image: XAIImageReference; readonly images?: never })
+	| (XAIImageRequestBase & { readonly images: readonly XAIImageReference[]; readonly image?: never });
+
 interface AntigravityResponseChunk {
 	response?: {
 		candidates?: Array<{
@@ -391,12 +430,24 @@ function extractOpenRouterImageUrls(message: OpenRouterMessage | undefined): str
 }
 
 /** Preferred provider set via settings (default: auto) */
-let preferredImageProvider: ImageProvider | "auto" = "auto";
+let preferredImageProvider: ImageProviderPreference = "auto";
+
+export function isImageProviderPreference(value: unknown): value is ImageProviderPreference {
+	return typeof value === "string" && IMAGE_PROVIDER_PREFERENCES.has(value);
+}
 
 /** Set the preferred image provider from settings */
-export function setPreferredImageProvider(provider: ImageProvider | "auto"): void {
+export function setPreferredImageProvider(provider: ImageProviderPreference): void {
 	preferredImageProvider = provider;
 }
+function assertImageAspectRatioSupported(provider: ImageProvider, aspectRatio: ImageGenParams["aspect_ratio"]): void {
+	if (!aspectRatio || provider === "xai" || COMMON_IMAGE_ASPECT_RATIO_SET.has(aspectRatio)) {
+		return;
+	}
+	throw new Error(
+		`Aspect ratio ${aspectRatio} is only supported by xAI image generation. Set providers.image to xai or use one of ${COMMON_IMAGE_ASPECT_RATIOS.join(", ")}.`,
+	);
+}
 
 interface ParsedAntigravityCredentials {
 	accessToken: string;
@@ -429,6 +480,17 @@ async function findAntigravityCredentials(modelRegistry: ModelRegistry): Promise
 	};
 }
 
+async function findXAIImageCredentials(modelRegistry?: ModelRegistry): Promise<ImageApiKey | null> {
+	if (modelRegistry) {
+		const creds = await resolveXAIHttpCredentials(modelRegistry);
+		if (creds) return { provider: "xai", apiKey: creds.apiKey };
+		return null;
+	}
+	const apiKey = $env.XAI_API_KEY;
+	if (apiKey) return { provider: "xai", apiKey };
+	return null;
+}
+
 async function findOpenAIHostedImageCredentials(
 	modelRegistry: ModelRegistry | undefined,
 	activeModel: Model | undefined,
@@ -468,9 +530,13 @@ async function findImageApiKey(
 		const openRouterKey = getEnvApiKey("openrouter");
 		if (openRouterKey) return { provider: "openrouter", apiKey: openRouterKey };
 		// Fall through to auto-detect if preferred provider key not found.
+	} else if (preferredImageProvider === "xai") {
+		const xai = await findXAIImageCredentials(modelRegistry);
+		if (xai) return xai;
+		// Fall through to auto-detect if preferred provider key not found.
 	}
 
-	// Auto-detect: GPT hosted image generation, then Antigravity, OpenRouter, Gemini.
+	// Auto-detect: GPT hosted image generation, then Antigravity, xAI, OpenRouter, Gemini.
 	const openAI = await findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
 	if (openAI) return openAI;
 
@@ -479,6 +545,9 @@ async function findImageApiKey(
 		if (antigravity) return antigravity;
 	}
 
+	const xai = await findXAIImageCredentials(modelRegistry);
+	if (xai) return xai;
+
 	const openRouterKey = getEnvApiKey("openrouter");
 	if (openRouterKey) return { provider: "openrouter", apiKey: openRouterKey };
 
@@ -857,6 +926,31 @@ function buildAntigravityRequest(
 	};
 }
 
+// xAI image-edit cap per docs.x.ai (POST /v1/images/edits supports up to 3
+// source images for multi-reference editing).
+const XAI_MAX_EDIT_IMAGES = 3;
+
+// Map the OpenAI-style pixel-size enum (image_size) to xAI's discrete tier.
+// "1024x1024" → "1k"; anything wider (1536x... or ...x1536) → "2k". Absent
+// image_size defaults to "1k", matching hermes-agent's DEFAULT_RESOLUTION
+// (plugins/image_gen/xai/__init__.py:71).
+function resolveXAIResolution(imageSize: string | undefined): "1k" | "2k" {
+	if (!imageSize || imageSize === "1024x1024") return "1k";
+	return "2k";
+}
+
+// Build the discriminated edit body. Caller must ensure images.length is in
+// [1, XAI_MAX_EDIT_IMAGES]; the bound check fires earlier in execute().
+function buildXAIEditPayload(base: XAIImageRequestBase, images: readonly InlineImageData[]): XAIImageRequestBody {
+	const refs: readonly XAIImageReference[] = images.map(img => ({
+		type: "image_url",
+		url: toDataUrl(img),
+	}));
+	const [first, ...rest] = refs;
+	if (first === undefined) return base; // unreachable: caller checked images.length > 0
+	return rest.length === 0 ? { ...base, image: first } : { ...base, images: refs };
+}
+
 interface AntigravitySseResult {
 	images: InlineImageData[];
 	text: string[];
@@ -910,7 +1004,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 			const apiKey = await findImageApiKey(ctx.modelRegistry, ctx.model, sessionId);
 			if (!apiKey) {
 				throw new Error(
-					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity, or set OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
+					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity or xAI Grok OAuth, or set XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
 				);
 			}
 
@@ -922,8 +1016,11 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 						? DEFAULT_ANTIGRAVITY_MODEL
 						: provider === "openrouter"
 							? DEFAULT_OPENROUTER_MODEL
-							: DEFAULT_MODEL;
+							: provider === "xai"
+								? DEFAULT_XAI_IMAGE_MODEL
+								: DEFAULT_MODEL;
 			const resolvedModel = provider === "openrouter" ? resolveOpenRouterModel(model) : model;
+			assertImageAspectRatioSupported(provider, params.aspect_ratio);
 			const cwd = ctx.sessionManager.getCwd();
 
 			const resolvedImages: InlineImageData[] = [];
@@ -1059,6 +1156,107 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 				};
 			}
 
+			if (provider === "xai") {
+				if (!ctx.modelRegistry) {
+					throw new Error("Missing modelRegistry for xAI image generation");
+				}
+				const xaiCreds = await resolveXAIHttpCredentials(ctx.modelRegistry, resolvedModel);
+				if (!xaiCreds) {
+					throw new Error(
+						"No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok Subscription) or set XAI_API_KEY.",
+					);
+				}
+
+				const prompt = assemblePrompt(params);
+				const aspectRatio = params.aspect_ratio ?? "1:1";
+				const xaiResolution = resolveXAIResolution(params.image_size);
+
+				const isEdit = resolvedImages.length > 0;
+				if (isEdit && resolvedImages.length > XAI_MAX_EDIT_IMAGES) {
+					throw new Error(
+						`xAI image edits accept up to ${XAI_MAX_EDIT_IMAGES} reference images; got ${resolvedImages.length}.`,
+					);
+				}
+
+				const xaiBaseBody: XAIImageRequestBase = {
+					model: resolvedModel,
+					prompt,
+					aspect_ratio: aspectRatio,
+					resolution: xaiResolution,
+					n: 1,
+					response_format: "b64_json",
+				};
+				const xaiBody: XAIImageRequestBody = isEdit
+					? buildXAIEditPayload(xaiBaseBody, resolvedImages)
+					: xaiBaseBody;
+				const xaiEndpoint = isEdit ? "/images/edits" : "/images/generations";
+
+				const xaiResponse = await fetch(`${xaiCreds.baseURL}${xaiEndpoint}`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${xaiCreds.apiKey}`,
+						"Content-Type": "application/json",
+						"User-Agent": ohMyPiXAIUserAgent(),
+					},
+					body: JSON.stringify(xaiBody),
+					signal: requestSignal,
+				});
+
+				const xaiRawText = await xaiResponse.text();
+				if (!xaiResponse.ok) {
+					let message = xaiRawText;
+					try {
+						const parsedErr = JSON.parse(xaiRawText) as { error?: { message?: string } };
+						message = parsedErr.error?.message ?? message;
+					} catch {
+						// Keep raw text.
+					}
+					throw new Error(`xAI image request failed (${xaiResponse.status}): ${message}`);
+				}
+
+				const xaiData = JSON.parse(xaiRawText) as {
+					data?: Array<{ b64_json?: string; url?: string }>;
+				};
+				const xaiInlineImages: InlineImageData[] = [];
+				for (const entry of xaiData.data ?? []) {
+					if (entry.b64_json) {
+						const bytes = Buffer.from(entry.b64_json, "base64");
+						const mimeType = parseImageMetadata(bytes)?.mimeType ?? "image/png";
+						xaiInlineImages.push({ data: entry.b64_json, mimeType });
+					} else if (entry.url) {
+						xaiInlineImages.push(await loadImageFromUrl(entry.url, requestSignal));
+					}
+				}
+
+				if (xaiInlineImages.length === 0) {
+					return {
+						content: [{ type: "text", text: "No image data returned." }],
+						details: {
+							provider,
+							model: resolvedModel,
+							imageCount: 0,
+							imagePaths: [],
+							images: [],
+						},
+					};
+				}
+
+				const xaiImagePaths = await saveImagesToTemp(xaiInlineImages);
+
+				return {
+					content: [
+						{ type: "text", text: buildResponseSummary(provider, resolvedModel, xaiImagePaths, undefined) },
+					],
+					details: {
+						provider,
+						model: resolvedModel,
+						imageCount: xaiInlineImages.length,
+						imagePaths: xaiImagePaths,
+						images: xaiInlineImages,
+					},
+				};
+			}
+
 			if (provider === "openrouter") {
 				const prompt = assemblePrompt(params);
 				const contentParts: OpenRouterContentPart[] = [{ type: "text", text: prompt }];

package/src/tools/index.ts

@@ -92,6 +92,7 @@ export * from "./search";
 export * from "./search-tool-bm25";
 export * from "./ssh";
 export * from "./todo-write";
+export * from "./tts";
 export * from "./write";
 export * from "./yield";
 

package/src/tools/match-line-format.ts

@@ -3,8 +3,8 @@
  *
  * Matched lines are prefixed with `*`; context lines are prefixed with a single
  * space so line numbers align in column. In hashline mode the line uses the
- * editable `LINE:content` shape under a file-hash header; in plain mode it keeps
- * the legacy `LINE|content` display-only shape. Line numbers are never padded.
+ * editable `LINE:content` shape under a snapshot-tag header; in plain mode it
+ * keeps the legacy `LINE|content` display-only shape. Line numbers are never padded.
  */
 export function formatMatchLine(
 	lineNumber: number,

package/src/tools/path-utils.ts

@@ -28,6 +28,7 @@ const INTERNAL_SCHEMES_WITH_SELECTORS: Record<string, true> = {
 	pr: true,
 	rule: true,
 	skill: true,
+	vault: true,
 };
 // Schemes whose resource URIs are server-defined and may legitimately end
 // with selector-shaped tails (e.g. `:raw`, `:conflicts`, `:1-50`, `/:raw`).
@@ -45,6 +46,7 @@ const TOP_LEVEL_INTERNAL_URL_PREFIXES = [
 	"rule://",
 	"local://",
 	"mcp://",
+	"vault://",
 ] as const;
 
 function normalizeUnicodeSpaces(str: string): string {

package/src/tools/plan-mode-guard.ts

@@ -1,10 +1,13 @@
 import * as path from "node:path";
-import { resolveLocalUrlToPath } from "../internal-urls";
+import { resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
 import { ToolError } from "./tool-errors";
 
+const VAULT_SCHEME_PREFIX = "vault:";
 const LOCAL_SCHEME_PREFIX = "local:";
+const PLAN_ALIAS_FILE = "PLAN.md";
+const LOCAL_PLAN_ALIAS = "local://PLAN.md";
 
 function resolveRawPath(session: ToolSession, targetPath: string): string {
 	const normalized = normalizeLocalScheme(targetPath);
@@ -15,18 +18,27 @@ function resolveRawPath(session: ToolSession, targetPath: string): string {
 		});
 	}
 
+	if (normalized.startsWith(VAULT_SCHEME_PREFIX)) {
+		return resolveVaultUrlToPath(normalized);
+	}
+
 	return resolveToCwd(normalized, session.cwd);
 }
 
+function isPlanAliasTarget(session: ToolSession, targetPath: string, resolved: string): boolean {
+	const normalized = normalizeLocalScheme(targetPath);
+	if (normalized === LOCAL_PLAN_ALIAS) return true;
+	return resolved === resolveToCwd(PLAN_ALIAS_FILE, session.cwd);
+}
+
 /**
  * Resolve a write/edit target to its absolute filesystem path.
  *
- * In plan mode, transparently redirects targets whose basename matches the
- * plan file's basename (e.g. a bare `PLAN.md` or `./PLAN.md`) to the canonical
- * plan file location at `state.planFilePath`. This lets `write` and `edit`
- * accept the unqualified plan filename and have the change land at the
- * session-scoped `local://PLAN.md` artifact instead of a stray cwd-relative
- * file the plan-mode guard would otherwise reject.
+ * In plan mode, transparently redirects `PLAN.md` aliases and targets whose
+ * basename matches the plan file's basename to the canonical plan file
+ * location at `state.planFilePath`. This lets `write` and `edit` accept the
+ * habitual plan filename after approval even when the active artifact has a
+ * titled path such as `local://APPROVED.md`.
  *
  * Outside plan mode (or when the basename does not match) this is a no-op.
  */
@@ -38,6 +50,7 @@ export function resolvePlanPath(session: ToolSession, targetPath: string): strin
 
 	const planResolved = resolveRawPath(session, state.planFilePath);
 	if (resolved === planResolved) return resolved;
+	if (isPlanAliasTarget(session, targetPath, resolved)) return planResolved;
 	if (path.basename(resolved) !== path.basename(planResolved)) return resolved;
 
 	return planResolved;

package/src/tools/read.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { computeFileHash, formatHashlineHeader, formatNumberedLine, formatNumberedLines } from "@oh-my-pi/hashline";
+import { formatHashlineHeader, formatNumberedLine, formatNumberedLines } from "@oh-my-pi/hashline";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { glob, type SummaryResult, summarizeCode } from "@oh-my-pi/pi-natives";
@@ -118,39 +118,50 @@ function prependLineNumbers(text: string, startNum: number): string {
 
 interface HashlineHeaderContext {
 	header: string;
-	fileHash: string;
-	fullText: string;
+	tag: string;
+	fullText?: string;
 }
 
-function buildHashlineHeaderContext(displayPath: string, fullText: string): HashlineHeaderContext {
+function recordFullHashlineContext(
+	session: ToolSession,
+	absolutePath: string | undefined,
+	displayPath: string,
+	fullText: string,
+): HashlineHeaderContext | undefined {
+	if (!absolutePath || !path.isAbsolute(absolutePath)) return undefined;
 	const normalized = normalizeToLF(fullText);
-	const fileHash = computeFileHash(normalized);
+	const tag = getFileSnapshotStore(session).recordContiguous(absolutePath, 1, normalized.split("\n"), {
+		fullText: normalized,
+	});
 	return {
-		header: formatHashlineHeader(displayPath, fileHash),
-		fileHash,
+		header: formatHashlineHeader(displayPath, tag),
+		tag,
 		fullText: normalized,
 	};
 }
 
-async function readHashlineHeaderContext(absolutePath: string, cwd: string): Promise<HashlineHeaderContext> {
+async function readHashlineHeaderContext(
+	session: ToolSession,
+	absolutePath: string,
+	cwd: string,
+): Promise<HashlineHeaderContext> {
 	const fullText = await Bun.file(absolutePath).text();
-	return buildHashlineHeaderContext(formatPathRelativeToCwd(absolutePath, cwd), fullText);
+	const context = recordFullHashlineContext(
+		session,
+		absolutePath,
+		formatPathRelativeToCwd(absolutePath, cwd),
+		fullText,
+	);
+	if (!context) throw new ToolError(`Cannot record hashline snapshot for non-absolute path: ${absolutePath}`);
+	return context;
 }
 
-function prependHashlineHeader(text: string, context: HashlineHeaderContext | undefined): string {
-	return context ? `${context.header}\n${text}` : text;
+function hashlineHeaderContext(displayPath: string, tag: string): HashlineHeaderContext {
+	return { header: formatHashlineHeader(displayPath, tag), tag };
 }
 
-function recordHashlineSnapshot(
-	session: ToolSession,
-	absolutePath: string | undefined,
-	context: HashlineHeaderContext | undefined,
-): void {
-	if (!context || !absolutePath || !path.isAbsolute(absolutePath)) return;
-	getFileSnapshotStore(session).recordContiguous(absolutePath, 1, context.fullText.split("\n"), {
-		fullText: context.fullText,
-		fileHash: context.fileHash,
-	});
+function prependHashlineHeader(text: string, context: HashlineHeaderContext | undefined): string {
+	return context ? `${context.header}\n${text}` : text;
 }
 
 function formatTextWithMode(
@@ -841,9 +852,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
 		const hashContext =
 			shouldAddHashLines && options.sourcePath
-				? buildHashlineHeaderContext(formatPathRelativeToCwd(options.sourcePath, this.session.cwd), text)
+				? recordFullHashlineContext(
+						this.session,
+						options.sourcePath,
+						formatPathRelativeToCwd(options.sourcePath, this.session.cwd),
+						text,
+					)
 				: undefined;
-		recordHashlineSnapshot(this.session, options.sourcePath, hashContext);
 		let emittedHashlineHeader = false;
 		const formatText = (content: string, startNum: number): string => {
 			details.displayContent = { text: content, startLine: startNum };
@@ -934,9 +949,13 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const shouldAddLineNumbers = shouldAddHashLines ? false : displayMode.lineNumbers;
 		const hashContext =
 			shouldAddHashLines && options.sourcePath
-				? buildHashlineHeaderContext(formatPathRelativeToCwd(options.sourcePath, this.session.cwd), text)
+				? recordFullHashlineContext(
+						this.session,
+						options.sourcePath,
+						formatPathRelativeToCwd(options.sourcePath, this.session.cwd),
+						text,
+					)
 				: undefined;
-		recordHashlineSnapshot(this.session, options.sourcePath, hashContext);
 		let emittedHashlineHeader = false;
 
 		const resultBuilder = toolResult(details);
@@ -1014,11 +1033,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 		const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
-		const hashContext = shouldAddHashLines
-			? await readHashlineHeaderContext(absolutePath, this.session.cwd)
-			: undefined;
-		recordHashlineSnapshot(this.session, absolutePath, hashContext);
-		let emittedHashlineHeader = false;
+		const sparseSnapshotEntries: Array<readonly [number, string]> = [];
 		const maxColumns = resolveOutputMaxColumns(this.session.settings);
 
 		const blocks: string[] = [];
@@ -1058,22 +1073,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				}
 			}
 
-			if (collectedLines.length > 0) {
-				getFileSnapshotStore(this.session).recordContiguous(
-					absolutePath,
-					range.startLine,
-					collectedLines,
-					hashContext ? { fullText: hashContext.fullText, fileHash: hashContext.fileHash } : {},
-				);
+			for (let index = 0; index < collectedLines.length; index++) {
+				sparseSnapshotEntries.push([range.startLine + index, collectedLines[index]]);
 			}
 
 			const blockText = collectedLines.join("\n");
-			const formatted = formatTextWithMode(blockText, range.startLine, shouldAddHashLines, shouldAddLineNumbers);
-			blocks.push(hashContext && !emittedHashlineHeader ? prependHashlineHeader(formatted, hashContext) : formatted);
-			if (hashContext) emittedHashlineHeader = true;
+			blocks.push(formatTextWithMode(blockText, range.startLine, shouldAddHashLines, shouldAddLineNumbers));
 		}
 
 		let outputText = blocks.join("\n\n…\n\n");
+		if (shouldAddHashLines && sparseSnapshotEntries.length > 0 && outputText) {
+			const tag = getFileSnapshotStore(this.session).recordSparse(absolutePath, sparseSnapshotEntries);
+			outputText = `${formatHashlineHeader(formatPathRelativeToCwd(absolutePath, this.session.cwd), tag)}\n${outputText}`;
+		}
 		if (notices.length > 0) {
 			outputText = outputText ? `${outputText}\n${notices.join("\n")}` : notices.join("\n");
 		}
@@ -1726,9 +1738,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						renderedSummary.elidedLines,
 					);
 					const summaryHashContext = displayMode.hashLines
-						? await readHashlineHeaderContext(absolutePath, this.session.cwd)
+						? await readHashlineHeaderContext(this.session, absolutePath, this.session.cwd)
 						: undefined;
-					recordHashlineSnapshot(this.session, absolutePath, summaryHashContext);
 					const bodyText = footer ? `${renderedSummary.text}\n\n${footer}` : renderedSummary.text;
 					const modelText = prependHashlineHeader(bodyText, summaryHashContext);
 					details = {
@@ -1875,17 +1886,19 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 					const shouldAddHashLines = !rawSelector && displayMode.hashLines;
 					const shouldAddLineNumbers = rawSelector ? false : shouldAddHashLines ? false : displayMode.lineNumbers;
-					const hashContext = shouldAddHashLines
-						? await readHashlineHeaderContext(absolutePath, this.session.cwd)
-						: undefined;
-
-					if (collectedLines.length > 0 && !firstLineExceedsLimit) {
-						getFileSnapshotStore(this.session).recordContiguous(
-							absolutePath,
-							startLineDisplay,
-							collectedLines,
-							hashContext ? { fullText: hashContext.fullText, fileHash: hashContext.fileHash } : {},
-						);
+					let hashContext: HashlineHeaderContext | undefined;
+					if (shouldAddHashLines && collectedLines.length > 0 && !firstLineExceedsLimit) {
+						const store = getFileSnapshotStore(this.session);
+						const tag =
+							offset === undefined && limit === undefined && !wasTruncated && columnTruncated === 0
+								? (() => {
+										const normalized = normalizeToLF(selectedContent);
+										return store.recordContiguous(absolutePath, 1, normalized.split("\n"), {
+											fullText: normalized,
+										});
+									})()
+								: store.recordContiguous(absolutePath, startLineDisplay, collectedLines);
+						hashContext = hashlineHeaderContext(formatPathRelativeToCwd(absolutePath, this.session.cwd), tag);
 					}
 
 					let capturedDisplayContent: { text: string; startLine: number } | undefined;
@@ -2031,9 +2044,11 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 		const rawText = region.lines.join("\n");
 		const hashContext = shouldAddHashLines
-			? await readHashlineHeaderContext(entry.absolutePath, this.session.cwd)
+			? hashlineHeaderContext(
+					formatPathRelativeToCwd(entry.absolutePath, this.session.cwd),
+					getFileSnapshotStore(this.session).recordContiguous(entry.absolutePath, region.startLine, region.lines),
+				)
 			: undefined;
-		recordHashlineSnapshot(this.session, entry.absolutePath, hashContext);
 		const formattedBody = formatTextWithMode(rawText, region.startLine, shouldAddHashLines, shouldAddLineNumbers);
 		const formattedText = prependHashlineHeader(formattedBody, hashContext);
 

package/src/tools/render-utils.ts

@@ -469,7 +469,22 @@ export function truncateDiffByHunk(
 	diffText: string,
 	maxHunks: number,
 	maxLines: number,
+	options?: { fromTail?: boolean },
 ): { text: string; hiddenHunks: number; hiddenLines: number } {
+	if (options?.fromTail) {
+		// Streaming previews want to track the tail of the diff as new hunks
+		// arrive. Reversing the line buffer reuses the head-mode logic without
+		// duplicating the segment-budget bookkeeping: hunk runs survive
+		// reversal (a continuous `+`/`-` block stays contiguous) and so do the
+		// per-line `+`/`-` markers, so getDiffStats yields identical counts.
+		const reversed = (diffText ?? "").split("\n").reverse().join("\n");
+		const result = truncateDiffByHunk(reversed, maxHunks, maxLines);
+		return {
+			text: result.text.split("\n").reverse().join("\n"),
+			hiddenHunks: result.hiddenHunks,
+			hiddenLines: result.hiddenLines,
+		};
+	}
 	const lines = diffText ? diffText.split("\n") : [];
 	const totalStats = getDiffStats(diffText);