@jerryan/pi-hashline-edit 0.7.3 → 0.7.4

package/README.md

@@ -15,7 +15,7 @@ This is a fork of the original [pi-hashline-edit](https://github.com/earendil-wo
 - **Single edit shape.** One entry type: `{ range: [start, end], lines: [...] }`. No `op` field, no `append`/`prepend`/`replace_text` ops, no `after`/`before`. The tuple enforces explicit endpoint anchors, eliminating the common "forgot `end`" failure mode.
 - **Standard hex hash alphabet.** `0-9 A-F` instead of `ZPMQVRWSNKTXJBYH`. Hex pairs are more likely to be single tokens.
 - **Symmetric boundary-duplication detection.** Runtime warnings catch duplicated boundary lines on both sides of a replacement, not just trailing.
-- **`read` raw mode.** `raw: true` returns plain text without `LINE#HASH:` anchors, for reads that don't plan to edit.
+- **`read` raw mode.** `raw: true` returns plain text without `LINE#HASH│` anchors, for reads that don't plan to edit.
 - **Inline FNV-1a hashing.** Replaces `xxhashjs` dependency. Always incorporates line index.
 - **Minimal prompt surface.** Prompt text describes what the model needs to use the tool; return-format documentation and error catalogues are omitted.
 - **No legacy compatibility.** The `{ oldText, newText }` substring-replace format is not accepted. The schema is hashline-only.

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "@jerryan/pi-hashline-edit",
-  "version": "0.7.3",
-  "description": "Hashline read/edit tool override for pi-coding-agent",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/JerryAZR/pi-hashline-edit.git"
-  },
-  "author": "JerryAZR",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "coding-agent",
-    "extension",
-    "hashline"
-  ],
-  "license": "MIT",
-  "files": [
-    "index.ts",
-    "src",
-    "prompts",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "dependencies": {
-    "diff": "^8.0.2",
-    "file-type": "^21.3.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@types/node": "^22.0.0",
-    "ajv": "^8.20.0",
-    "vitest": "^3.0.0"
-  }
-}
+{
+  "name": "@jerryan/pi-hashline-edit",
+  "version": "0.7.4",
+  "description": "Hashline read/edit tool override for pi-coding-agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JerryAZR/pi-hashline-edit.git"
+  },
+  "author": "JerryAZR",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "hashline"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "tool-descriptions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "diff": "^8.0.2",
+    "file-type": "^21.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@types/node": "^22.0.0",
+    "ajv": "^8.20.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/edit-response.ts

@@ -6,6 +6,7 @@
  */
 
 import { generateDiffString } from "./edit-diff";
+import { PACKAGE_INFO } from "./package-info";
 
 // ─── Public types ───────────────────────────────────────────────────────
 
@@ -117,6 +118,7 @@ export function buildNoopResponse(input: NoopResponseInput): ToolResult {
       snapshotId,
       classification: "noop" as const,
       metrics,
+      package: PACKAGE_INFO,
     },
   };
 }
@@ -149,6 +151,7 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
       diff: diffResult.diff,
       snapshotId,
       metrics,
+      package: PACKAGE_INFO,
     },
   };
 }

package/src/edit.ts

@@ -68,15 +68,16 @@ type HashlineEditToolDetails = {
   snapshotId?: string;
   classification?: "noop";
   metrics?: EditMetrics;
+  package: { name: string; version: string };
 };
 
 const EDIT_DESC = readFileSync(
-  new URL("../prompts/edit.md", import.meta.url),
+  new URL("../tool-descriptions/edit.md", import.meta.url),
   "utf-8",
 ).trim();
 
 const EDIT_PROMPT_SNIPPET = readFileSync(
-  new URL("../prompts/edit-snippet.md", import.meta.url),
+  new URL("../tool-descriptions/edit-snippet.md", import.meta.url),
   "utf-8",
 ).trim();
 
@@ -269,12 +270,12 @@ export async function computeEditPreview(
     }
     if (file.kind === "image") {
       return {
-        error: `Path is an image file: ${path}. Hashline edit only supports UTF-8 text files.`,
+        error: `Path is an image file: ${path}. Hashline edit only supports text files.`,
       };
     }
     if (file.kind === "binary") {
       return {
-        error: `Path is a binary file: ${path} (${file.description}). Hashline edit only supports UTF-8 text files.`,
+        error: `Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
       };
     }
 
@@ -453,12 +454,12 @@ const editToolDefinition: EditToolDefinition = {
       }
       if (file.kind === "image") {
         throw new Error(
-          `Path is an image file: ${path}. Hashline edit only supports UTF-8 text files.`,
+          `Path is an image file: ${path}. Hashline edit only supports text files.`,
         );
       }
       if (file.kind === "binary") {
         throw new Error(
-          `Path is a binary file: ${path} (${file.description}). Hashline edit only supports UTF-8 text files.`,
+          `Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`,
         );
       }
 

package/src/file-kind.ts

@@ -36,27 +36,6 @@ function hasNullByte(buffer: Uint8Array): boolean {
   return buffer.includes(0);
 }
 
-function decodeUtf8Chunk(decoder: TextDecoder, buffer: Uint8Array): string | null {
-  try {
-    return decoder.decode(buffer, { stream: true });
-  } catch (error: unknown) {
-    if (error instanceof TypeError) {
-      return null;
-    }
-    throw error;
-  }
-}
-
-function finishUtf8(decoder: TextDecoder): string | null {
-  try {
-    return decoder.decode();
-  } catch (error: unknown) {
-    if (error instanceof TypeError) {
-      return null;
-    }
-    throw error;
-  }
-}
 
 export async function loadFileKindAndText(filePath: string): Promise<LoadedFile> {
   const pathStat = await fsStat(filePath);
@@ -96,16 +75,12 @@ export async function loadFileKindAndText(filePath: string): Promise<LoadedFile>
       };
     }
 
-    const decoder = new TextDecoder("utf-8", { fatal: true });
-    const parts: string[] = [];
-    const sampleText = decodeUtf8Chunk(decoder, sample);
-    if (sampleText === null) {
-      return {
-        kind: "binary",
-        description: "invalid UTF-8",
-      };
-    }
-    parts.push(sampleText);
+    // Non-fatal decode, matching pi's built-in tools: invalid UTF-8 becomes
+    // U+FFFD rather than rejecting the file. The null-byte guard above is the
+    // only signal we treat as binary, so non-UTF-8 text (CP1251, GBK, …) reads
+    // instead of forcing the model to bypass hashline with raw shell edits.
+    const decoder = new TextDecoder("utf-8");
+    const parts: string[] = [decoder.decode(sample, { stream: true })];
 
     let position = bytesRead;
     while (true) {
@@ -126,25 +101,13 @@ export async function loadFileKindAndText(filePath: string): Promise<LoadedFile>
           description: "null bytes detected",
         };
       }
-      const chunkText = decodeUtf8Chunk(decoder, chunk);
-      if (chunkText === null) {
-        return {
-          kind: "binary",
-          description: "invalid UTF-8",
-        };
-      }
-      parts.push(chunkText);
+      parts.push(decoder.decode(chunk, { stream: true }));
       position += chunkBytesRead;
     }
 
-    const tail = finishUtf8(decoder);
-    if (tail === null) {
-      return {
-        kind: "binary",
-        description: "invalid UTF-8",
-      };
-    }
-    parts.push(tail);
+    parts.push(decoder.decode());
+
+    return { kind: "text", text: parts.join("") };
 
     return { kind: "text", text: parts.join("") };
   } finally {

package/src/package-info.ts

@@ -0,0 +1,4 @@
+export const PACKAGE_INFO = {
+  name: "@jerryan/pi-hashline-edit",
+  version: "0.7.4",
+};

package/src/read.ts

@@ -1,230 +1,241 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  createReadTool,
-  formatSize,
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
-  truncateHead,
-  type TruncationResult,
-} from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { readFileSync } from "fs";
-import { access as fsAccess, readdir as fsReaddir } from "fs/promises";
-import { constants } from "fs";
-import { normalizeToLF, stripBom } from "./edit-diff";
-import { loadFileKindAndText } from "./file-kind";
-import { formatHashlineRegion } from "./hashline";
-import { resolveToCwd } from "./path-utils";
-import { throwIfAborted } from "./runtime";
-import { getFileSnapshot } from "./snapshot";
-
-const READ_DESC = readFileSync(
-  new URL("../prompts/read.md", import.meta.url),
-  "utf-8",
-)
-  .replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
-  .replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
-  .trim();
-
-const READ_PROMPT_SNIPPET = readFileSync(
-  new URL("../prompts/read-snippet.md", import.meta.url),
-  "utf-8",
-).trim();
-
-const READ_PROMPT_GUIDELINES = readFileSync(
-  new URL("../prompts/read-guidelines.md", import.meta.url),
-  "utf-8",
-)
-  .split("\n")
-  .map((line) => line.trim())
-  .filter((line) => line.startsWith("- "))
-  .map((line) => line.slice(2));
-
-function normalizePositiveInteger(
-  value: number | undefined,
-  name: "offset" | "limit",
-): number | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`Read request field "${name}" must be a positive integer.`);
-  }
-
-  return value;
-}
-
-function getPreviewLines(text: string): string[] {
-  if (text.length === 0) {
-    return [];
-  }
-
-  const lines = text.split("\n");
-  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
-}
-
-export function formatHashlineReadPreview(
-  text: string,
-  options: { offset?: number; limit?: number; raw?: boolean },
-): { text: string; truncation?: TruncationResult; nextOffset?: number } {
-  const allLines = getPreviewLines(text);
-  const totalLines = allLines.length;
-  const startLine = normalizePositiveInteger(options.offset, "offset") ?? 1;
-  if (totalLines === 0) {
-    if (startLine === 1) {
-      return {
-        text: "File is empty. Use edit with prepend or append and omit pos to insert content.",
-      };
-    }
-
-    return {
-      text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit with prepend or append and omit pos to insert content.`,
-    };
-  }
-
-  if (startLine > totalLines) {
-    return {
-      text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
-    };
-  }
-
-  const limit = normalizePositiveInteger(options.limit, "limit");
-  const endIdx = limit
-    ? Math.min(startLine - 1 + limit, totalLines)
-    : totalLines;
-  const selected = allLines.slice(startLine - 1, endIdx);
-  const formatted = options.raw ? selected.join("\n") : formatHashlineRegion(selected, startLine);
-
-  const truncation = truncateHead(formatted);
-  if (truncation.firstLineExceedsLimit) {
-    return {
-      text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}.${options.raw ? "" : " Hashline output requires full lines; cannot compute hashes for a truncated preview."}]`,
-
-      truncation,
-    };
-  }
-
-  let preview = truncation.content;
-  let nextOffset: number | undefined;
-  if (truncation.truncated) {
-    const endLineDisplay = startLine + truncation.outputLines - 1;
-    nextOffset = endLineDisplay + 1;
-    if (truncation.truncatedBy === "lines") {
-      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
-    } else {
-      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
-    }
-  } else if (endIdx < totalLines) {
-    nextOffset = endIdx + 1;
-    preview += `\n\n[Showing lines ${startLine}-${endIdx} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
-  }
-
-  return {
-    text: preview,
-    truncation: truncation.truncated ? truncation : undefined,
-    ...(nextOffset !== undefined ? { nextOffset } : {}),
-  };
-}
-
-export function registerReadTool(pi: ExtensionAPI): void {
-  pi.registerTool({
-    name: "read",
-    label: "Read",
-    description: READ_DESC,
-    promptSnippet: READ_PROMPT_SNIPPET,
-    promptGuidelines: READ_PROMPT_GUIDELINES,
-    parameters: Type.Object({
-      path: Type.String({
-        description: "Path to the file to read (relative or absolute)",
-      }),
-      offset: Type.Optional(
-        Type.Integer({
-          minimum: 1,
-          description: "Line number to start reading from (1-indexed)",
-        }),
-      ),
-      limit: Type.Optional(
-        Type.Integer({
-          minimum: 1,
-          description: "Maximum number of lines to read",
-        }),
-      ),
-      raw: Type.Optional(
-        Type.Boolean({
-          description: "Return raw text without LINE#HASH anchors, saving tokens. Don't use if you plan to edit this file.",
-        }),
-      ),
-    }),
-
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const rawPath = params.path;
-      const absolutePath = resolveToCwd(rawPath, ctx.cwd);
-
-      throwIfAborted(signal);
-      try {
-        await fsAccess(absolutePath, constants.R_OK);
-      } catch (error: unknown) {
-        const code = error instanceof Error
-          ? (error as NodeJS.ErrnoException).code
-          : undefined;
-        if (code === "ENOENT") {
-          throw new Error(`File not found: ${rawPath}`);
-        }
-        if (code === "EACCES" || code === "EPERM") {
-          throw new Error(`File is not readable: ${rawPath}`);
-        }
-        throw new Error(`Cannot access file: ${rawPath}`);
-      }
-
-      throwIfAborted(signal);
-      const file = await loadFileKindAndText(absolutePath);
-      if (file.kind === "directory") {
-        const entries = await fsReaddir(absolutePath);
-        const listing = entries
-          .slice(0, 50)
-          .map((name) => `  ${name}`)
-          .join("\n");
-        const cap = entries.length > 50 ? `\n  ... and ${entries.length - 50} more` : "";
-        throw new Error(
-          `Path is a directory: ${rawPath}\n${listing}${cap}\n\nUse ls to explore further or read a specific file.`,
-        );
-      }
-
-      if (file.kind === "binary") {
-        throw new Error(`Path is a binary file: ${rawPath} (${file.description}). Read only supports UTF-8 text files and supported images.`);
-      }
-
-      if (file.kind === "image") {
-        const builtinRead = createReadTool(ctx.cwd);
-        return builtinRead.execute(_toolCallId, params, signal, _onUpdate, ctx);
-      }
-
-      throwIfAborted(signal);
-      const normalized = normalizeToLF(stripBom(file.text).text);
-      const preview = formatHashlineReadPreview(normalized, {
-        offset: params.offset,
-        limit: params.limit,
-        raw: params.raw,
-      });
-      const snapshot = await getFileSnapshot(absolutePath);
-
-      return {
-        content: [{ type: "text", text: preview.text }],
-        details: {
-          truncation: preview.truncation,
-          // snapshotId remains in details for host UI (e.g. "file changed since
-          // last view"). It is NOT echoed in text — the LLM no longer needs it.
-          snapshotId: snapshot.snapshotId,
-          ...(preview.nextOffset !== undefined ? { nextOffset: preview.nextOffset } : {}),
-          // Phase 2 C — host-only observability. Truncated reads usually mean
-          // a follow-up read with `offset = next_offset` is coming.
-          metrics: {
-            truncated: !!preview.truncation,
-            ...(preview.nextOffset !== undefined ? { next_offset: preview.nextOffset } : {}),
-          },
-        },
-      };
-    },
-  });
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createReadTool,
+  formatSize,
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { readFileSync } from "fs";
+import { access as fsAccess, readdir as fsReaddir } from "fs/promises";
+import { constants } from "fs";
+import { normalizeToLF, stripBom } from "./edit-diff";
+import { loadFileKindAndText } from "./file-kind";
+import { formatHashlineRegion } from "./hashline";
+import { resolveToCwd } from "./path-utils";
+import { throwIfAborted } from "./runtime";
+import { getFileSnapshot } from "./snapshot";
+import { PACKAGE_INFO } from "./package-info";
+
+const READ_DESC = readFileSync(
+  new URL("../tool-descriptions/read.md", import.meta.url),
+  "utf-8",
+)
+  .replaceAll("{{DEFAULT_MAX_LINES}}", String(DEFAULT_MAX_LINES))
+  .replaceAll("{{DEFAULT_MAX_BYTES}}", formatSize(DEFAULT_MAX_BYTES))
+  .trim();
+
+const READ_PROMPT_SNIPPET = readFileSync(
+  new URL("../tool-descriptions/read-snippet.md", import.meta.url),
+  "utf-8",
+).trim();
+
+const READ_PROMPT_GUIDELINES = readFileSync(
+  new URL("../tool-descriptions/read-guidelines.md", import.meta.url),
+  "utf-8",
+)
+  .split("\n")
+  .map((line) => line.trim())
+  .filter((line) => line.startsWith("- "))
+  .map((line) => line.slice(2));
+
+function normalizePositiveInteger(
+  value: number | undefined,
+  name: "offset" | "limit",
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Read request field "${name}" must be a positive integer.`);
+  }
+
+  return value;
+}
+
+function getPreviewLines(text: string): string[] {
+  if (text.length === 0) {
+    return [];
+  }
+
+  const lines = text.split("\n");
+  return text.endsWith("\n") ? lines.slice(0, -1) : lines;
+}
+
+export function formatHashlineReadPreview(
+  text: string,
+  options: { offset?: number; limit?: number; raw?: boolean },
+): { text: string; truncation?: TruncationResult; nextOffset?: number } {
+  const allLines = getPreviewLines(text);
+  const totalLines = allLines.length;
+  const startLine = normalizePositiveInteger(options.offset, "offset") ?? 1;
+  if (totalLines === 0) {
+    if (startLine === 1) {
+      return {
+        text: "File is empty. Use edit with prepend or append and omit pos to insert content.",
+      };
+    }
+
+    return {
+      text: `Offset ${startLine} is beyond end of file (0 lines total). The file is empty. Use edit with prepend or append and omit pos to insert content.`,
+    };
+  }
+
+  if (startLine > totalLines) {
+    return {
+      text: `Offset ${startLine} is beyond end of file (${totalLines} lines total). Use offset=1 to read from the start, or offset=${totalLines} to read the last line.`,
+    };
+  }
+
+  const limit = normalizePositiveInteger(options.limit, "limit");
+  const endIdx = limit
+    ? Math.min(startLine - 1 + limit, totalLines)
+    : totalLines;
+  const selected = allLines.slice(startLine - 1, endIdx);
+  const formatted = options.raw ? selected.join("\n") : formatHashlineRegion(selected, startLine);
+
+  const truncation = truncateHead(formatted);
+  if (truncation.firstLineExceedsLimit) {
+    return {
+      text: `[Line ${startLine} exceeds ${formatSize(truncation.maxBytes)}.${options.raw ? "" : " Hashline output requires full lines; cannot compute hashes for a truncated preview."}]`,
+
+      truncation,
+    };
+  }
+
+  let preview = truncation.content;
+  let nextOffset: number | undefined;
+  if (truncation.truncated) {
+    const endLineDisplay = startLine + truncation.outputLines - 1;
+    nextOffset = endLineDisplay + 1;
+    if (truncation.truncatedBy === "lines") {
+      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+    } else {
+      preview += `\n\n[Showing lines ${startLine}-${endLineDisplay} of ${totalLines} (${formatSize(truncation.maxBytes)} limit). Use offset=${nextOffset} to continue.]`;
+    }
+  } else if (endIdx < totalLines) {
+    nextOffset = endIdx + 1;
+    preview += `\n\n[Showing lines ${startLine}-${endIdx} of ${totalLines}. Use offset=${nextOffset} to continue.]`;
+  }
+
+  return {
+    text: preview,
+    truncation: truncation.truncated ? truncation : undefined,
+    ...(nextOffset !== undefined ? { nextOffset } : {}),
+  };
+}
+
+export function registerReadTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "read",
+    label: "Read",
+    description: READ_DESC,
+    promptSnippet: READ_PROMPT_SNIPPET,
+    promptGuidelines: READ_PROMPT_GUIDELINES,
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path to the file to read (relative or absolute)",
+      }),
+      offset: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "Line number to start reading from (1-indexed)",
+        }),
+      ),
+      limit: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "Maximum number of lines to read",
+        }),
+      ),
+      raw: Type.Optional(
+        Type.Boolean({
+          description: "Return raw text without LINE#HASH anchors, saving tokens. Don't use if you plan to edit this file.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const rawPath = params.path;
+      const absolutePath = resolveToCwd(rawPath, ctx.cwd);
+
+      throwIfAborted(signal);
+      try {
+        await fsAccess(absolutePath, constants.R_OK);
+      } catch (error: unknown) {
+        const code = error instanceof Error
+          ? (error as NodeJS.ErrnoException).code
+          : undefined;
+        if (code === "ENOENT") {
+          throw new Error(`File not found: ${rawPath}`);
+        }
+        if (code === "EACCES" || code === "EPERM") {
+          throw new Error(`File is not readable: ${rawPath}`);
+        }
+        throw new Error(`Cannot access file: ${rawPath}`);
+      }
+
+      throwIfAborted(signal);
+      const file = await loadFileKindAndText(absolutePath);
+      if (file.kind === "directory") {
+        const entries = await fsReaddir(absolutePath);
+        const listing = entries
+          .slice(0, 50)
+          .map((name) => `  ${name}`)
+          .join("\n");
+        const cap = entries.length > 50 ? `\n  ... and ${entries.length - 50} more` : "";
+        throw new Error(
+          `Path is a directory: ${rawPath}\n${listing}${cap}\n\nUse ls to explore further or read a specific file.`,
+        );
+      }
+
+      if (file.kind === "binary") {
+        throw new Error(`Path is a binary file: ${rawPath} (${file.description}). Read only supports text files and supported images.`);
+      }
+
+      if (file.kind === "image") {
+        const builtinRead = createReadTool(ctx.cwd);
+        return builtinRead.execute(_toolCallId, params, signal, _onUpdate, ctx);
+      }
+
+      throwIfAborted(signal);
+      const normalized = normalizeToLF(stripBom(file.text).text);
+      const preview = formatHashlineReadPreview(normalized, {
+        offset: params.offset,
+        limit: params.limit,
+        raw: params.raw,
+      });
+      const snapshot = await getFileSnapshot(absolutePath);
+
+      // A U+FFFD anywhere in the decoded text means the file held bytes that
+      // are not valid UTF-8 (CP1251, GBK, …). Editing rewrites the whole file
+      // as UTF-8, so those bytes are lost. Warn once on read — the model can
+      // then iconv the file back afterwards. Detect on the full text, not the
+      // paged slice, so an out-of-view bad byte still surfaces.
+      const previewText = normalized.includes("\uFFFD")
+        ? `${preview.text}\n\n[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]`
+        : preview.text;
+
+      return {
+        content: [{ type: "text", text: previewText }],
+        details: {
+          truncation: preview.truncation,
+          // snapshotId remains in details for host UI (e.g. "file changed since
+          // last view"). It is NOT echoed in text — the LLM no longer needs it.
+          snapshotId: snapshot.snapshotId,
+          ...(preview.nextOffset !== undefined ? { nextOffset: preview.nextOffset } : {}),
+          // Phase 2 C — host-only observability. Truncated reads usually mean
+          // a follow-up read with `offset = next_offset` is coming.
+          metrics: {
+            truncated: !!preview.truncation,
+            ...(preview.nextOffset !== undefined ? { next_offset: preview.nextOffset } : {}),
+          },
+          package: PACKAGE_INFO,
+        },
+      };
+    },
+  });
+}