opencode-readseek 0.6.13 → 0.7.1

package/README.md

@@ -9,7 +9,7 @@ Add the plugin to `opencode.json`:
 
 ```json
 {
-  "plugin": [["opencode-readseek", { "imageMode": "auto" }]]
+  "plugin": ["opencode-readseek"]
 }
 ```
 
@@ -18,7 +18,8 @@ binary dependency with Bun at startup.
 
 ## Tools
 
-- `readseek_read`: read text with `LINE:HASH` anchors; image/PDF handling is explicit.
+- `readseek_read`: read text with `LINE:HASH` anchors; PDFs select one page by
+  default and accept an explicit page.
 - `readseek_edit`: apply line, range, and insertion edits with fresh `LINE:HASH` anchors.
 - `readseek_write`: create or replace a complete text file.
 - `readseek_grep`: plain-text or regular-expression search with anchored results.
@@ -27,14 +28,28 @@ binary dependency with Bun at startup.
 - `readseek_def`, `readseek_refs`, `readseek_hover`: symbol navigation.
 - `readseek_rename`: apply a verified rename by default; `apply: false` returns a dry-run plan.
 - `readseek_check`: parse diagnostics.
+- `readseek_view`: create or reuse a PDF index, return its overview, or narrow
+  it by page, node, kind, or depth.
 
 The plugin requests OpenCode read, grep, external-directory, and edit permissions
 as needed. File changes invalidate remembered anchors. Compaction context records
 paths with fresh anchors and summaries of pending dry-run rename plans. Text reads
 return at most 2,000 lines by default.
 
+The plugin also instructs OpenCode to prefer ReadSeek's anchored read, edit,
+write, and rename tools over built-in file mutation tools while leaving the
+built-ins available as fallbacks.
+
 ## Configuration
 
+Pass options with OpenCode's plugin tuple form:
+
+```json
+{
+  "plugin": [["opencode-readseek", { "imageMode": "auto" }]]
+}
+```
+
 `imageMode` defaults to `"auto"`: it exposes `none`, `all`, `ocr`, `caption`, and
 `objects`. `"on"` omits `none`; `"off"` skips image/PDF files. Omitting
 `image` also skips visual files.

package/index.ts

@@ -1,15 +1,31 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) Jarkko Sakkinen 2026
 
-import { lstat, mkdir, readFile, readlink, realpath, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, readlink, realpath, stat } from "node:fs/promises";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import path from "node:path";
 
-import { tool, type Plugin, type PluginOptions, type ToolContext } from "@opencode-ai/plugin";
+import { tool, type Plugin, type PluginOptions, type ToolAttachment, type ToolContext } from "@opencode-ai/plugin";
 
 const require = createRequire(import.meta.url);
 const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
 const DEFAULT_READ_LIMIT = 2000;
+const MAX_DOCUMENT_OUTPUT_BYTES = 256 * 1024;
+const MAX_DOCUMENT_OUTPUT_LINES = 2000;
+const EDITING_POLICY = [
+  "ReadSeek editing policy:",
+  "- Prefer readseek_read over built-in file reads when preparing to edit existing text; its LINE:HASH anchors are required by readseek_edit.",
+  "- Prefer readseek_edit for existing text files, readseek_write for whole-file creation or replacement, and readseek_rename for symbol renames.",
+  "- Do not use built-in edit, write, or apply_patch when the corresponding ReadSeek tool can perform the change.",
+  "- Use readseek_check after source edits for a quick syntax check.",
+].join("\n");
+const PREFERRED_TOOL_DESCRIPTIONS: Record<string, string> = {
+  readseek_edit: "Preferred tool for editing existing text files with verified LINE:HASH anchors.",
+  readseek_read: "Preferred file reader when an existing text file may be edited; returns the anchors required by readseek_edit.",
+  readseek_rename: "Preferred tool for renaming code symbols safely across their resolved bindings.",
+  readseek_write: "Preferred tool for creating or replacing a complete text file.",
+};
 const READSEEK_PLATFORM_PACKAGES: Record<string, string> = {
   "darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
   "linux-arm64": "@jarkkojs/readseek-linux-arm64",
@@ -22,15 +38,34 @@ type RenamePlan = {
   files: Set<string>;
 };
 
-type PresentationKind = "read" | "map" | "search" | "grep" | "def" | "refs" | "hover" | "rename" | "edit" | "write" | "check";
+type PresentationKind = "read" | "view" | "map" | "search" | "grep" | "def" | "refs" | "hover" | "rename" | "edit" | "write" | "check";
 
 type Presentation = {
   title: string;
   metadata: Record<string, number>;
 };
 
+type RenderedToolResult = {
+  output: string;
+  attachments?: ToolAttachment[];
+};
+
 type ImagePolicy = "on" | "auto" | "off";
 type ImageMode = "none" | "all" | "ocr" | "caption" | "objects";
+type DocumentNodeKind = "artifact" | "footer" | "header" | "heading" | "marginal_label" | "page" | "page_number" | "paragraph" | "section" | "structural_section";
+
+const DOCUMENT_NODE_KINDS: [DocumentNodeKind, ...DocumentNodeKind[]] = [
+  "artifact",
+  "footer",
+  "header",
+  "heading",
+  "marginal_label",
+  "page",
+  "page_number",
+  "paragraph",
+  "section",
+  "structural_section",
+];
 
 function resolveImagePolicy(options: PluginOptions | undefined): ImagePolicy {
   const value = options?.imageMode;
@@ -45,6 +80,10 @@ function isVisualFile(value: unknown): boolean {
   return typeof output.width === "number" || type === "application/pdf";
 }
 
+function isPdfFile(value: unknown): boolean {
+  return record(value).format === "pdf";
+}
+
 class SessionAnchors {
   #pathsBySession = new Map<string, Set<string>>();
   #renamePlans = new Map<string, RenamePlan>();
@@ -259,24 +298,41 @@ function readSeekBinaryPath(): string {
   return path.join(path.dirname(packageJson), "bin", process.platform === "win32" ? "readseek.exe" : "readseek");
 }
 
-async function runReadSeek(context: ToolContext, args: string[]): Promise<unknown> {
+async function runReadSeekRaw(
+  context: ToolContext,
+  args: string[],
+  options: { cancelable?: boolean } = {},
+): Promise<string> {
   context.abort.throwIfAborted();
-  const child = Bun.spawn([readSeekBinaryPath(), ...args], {
+  const cancelable = options.cancelable !== false;
+  const spawnOptions = {
     cwd: context.directory,
-    killSignal: "SIGKILL",
     maxBuffer: MAX_OUTPUT_BYTES,
-    signal: context.abort,
-    stderr: "pipe",
-    stdout: "pipe",
-  });
+    stderr: "pipe" as const,
+    stdout: "pipe" as const,
+  };
+  const child = Bun.spawn(
+    [readSeekBinaryPath(), ...args],
+    cancelable
+      ? { ...spawnOptions, killSignal: "SIGKILL" as const, signal: context.abort }
+      : spawnOptions,
+  );
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
     child.exited,
   ]);
-  context.abort.throwIfAborted();
+  if (cancelable) context.abort.throwIfAborted();
   if (exitCode !== 0) throw new Error(stderr.trim() || `readseek exited with status ${exitCode}`);
+  return stdout;
+}
 
+async function runReadSeek(
+  context: ToolContext,
+  args: string[],
+  options: { cancelable?: boolean } = {},
+): Promise<unknown> {
+  const stdout = await runReadSeekRaw(context, args, options);
   try {
     return JSON.parse(stdout) as unknown;
   } catch {
@@ -284,6 +340,32 @@ async function runReadSeek(context: ToolContext, args: string[]): Promise<unknow
   }
 }
 
+let readSeekCacheInit: Promise<string> | undefined;
+
+function readSeekCacheDir(): string {
+  const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+  const cacheHome = xdgCacheHome || path.join(homedir(), ".cache");
+  return path.join(cacheHome, "opencode", "readseek");
+}
+
+async function ensureReadSeekCache(context: ToolContext): Promise<string> {
+  const cacheDir = readSeekCacheDir();
+  try {
+    const info = await stat(cacheDir);
+    if (!info.isDirectory()) throw new Error(`readseek cache is not a directory: ${cacheDir}`);
+    return cacheDir;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+
+  readSeekCacheInit ??= runReadSeekRaw(context, ["--readseek-dir", cacheDir, "init"])
+    .then(() => cacheDir)
+    .finally(() => {
+      readSeekCacheInit = undefined;
+    });
+  return readSeekCacheInit;
+}
+
 function render(value: unknown): string {
   return JSON.stringify(value, null, 2);
 }
@@ -310,10 +392,70 @@ type AnchorEdit =
   | { replace_lines: { start_anchor: string; end_anchor: string; new_text: string } }
   | { insert_after: { anchor: string; new_text: string } };
 
+type TextSnapshot = {
+  exists: boolean;
+  content: string;
+};
+
+const fileMutationTails = new Map<string, Promise<void>>();
+const MAX_PERMISSION_DIFF_BYTES = 32 * 1024;
+
+async function withFileMutationQueue<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
+  const key = path.resolve(filePath);
+  const previous = fileMutationTails.get(key);
+  let release = () => {};
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  fileMutationTails.set(key, current);
+  if (previous) await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (fileMutationTails.get(key) === current) fileMutationTails.delete(key);
+  }
+}
+
+function validateAnchorEdits(value: unknown): asserts value is AnchorEdit[] {
+  if (!Array.isArray(value) || value.length === 0) throw new Error("edits must contain at least one edit");
+  const fields = {
+    set_line: ["anchor", "new_text"],
+    replace_lines: ["end_anchor", "new_text", "start_anchor"],
+    insert_after: ["anchor", "new_text"],
+  } as const;
+  for (const [index, item] of value.entries()) {
+    if (!item || typeof item !== "object") throw new Error(`edits[${index}] must be an edit object`);
+    const keys = Object.keys(item);
+    const variant = keys[0] as keyof typeof fields;
+    if (keys.length !== 1 || !Object.hasOwn(fields, variant)) {
+      throw new Error(`edits[${index}] must contain exactly one of: set_line, replace_lines, insert_after`);
+    }
+    const payload = (item as Record<string, unknown>)[variant];
+    if (!payload || typeof payload !== "object") throw new Error(`edits[${index}].${variant} must be an object`);
+    const expectedFields = fields[variant];
+    const actualFields = Object.keys(payload).sort();
+    if (actualFields.length !== expectedFields.length || actualFields.some((field, fieldIndex) => field !== expectedFields[fieldIndex])) {
+      throw new Error(`edits[${index}].${variant} contains invalid fields`);
+    }
+    const values = payload as Record<string, unknown>;
+    for (const field of expectedFields) {
+      if (typeof values[field] !== "string") {
+        throw new Error(`edits[${index}].${variant}.${field} must be a string`);
+      }
+    }
+    for (const field of expectedFields.filter((field) => field.endsWith("anchor"))) {
+      parseAnchor(values[field] as string);
+    }
+  }
+}
+
 function parseAnchor(anchor: string): { line: number; hash: string } {
   const match = /^(\d+):([0-9a-fA-F]{3})$/.exec(anchor.trim());
   if (!match) throw new Error(`invalid LINE:HASH anchor: ${anchor}`);
-  return { line: Number(match[1]), hash: match[2].toLowerCase() };
+  const line = Number(match[1]);
+  if (line === 0) throw new Error(`anchor line must be greater than zero: ${anchor}`);
+  return { line, hash: match[2].toLowerCase() };
 }
 
 function anchorRefs(edit: AnchorEdit): { line: number; hash: string }[] {
@@ -341,11 +483,55 @@ async function verifyAnchors(context: ToolContext, filePath: string, edits: Anch
   }
 }
 
+type EditableLine = {
+  text: string;
+  ending: "\r\n" | "\n" | "\r" | "";
+};
+
+function parseEditableLines(content: string): EditableLine[] {
+  const lines: EditableLine[] = [];
+  let start = 0;
+  for (let index = 0; index < content.length; index++) {
+    const character = content[index];
+    if (character !== "\r" && character !== "\n") continue;
+    const ending = character === "\r" && content[index + 1] === "\n" ? "\r\n" : character;
+    lines.push({ text: content.slice(start, index), ending });
+    if (ending === "\r\n") index++;
+    start = index + 1;
+  }
+  if (start < content.length || content.length === 0) lines.push({ text: content.slice(start), ending: "" });
+  return lines;
+}
+
+function detectLineEnding(lines: EditableLine[]): "\r\n" | "\n" | "\r" {
+  const counts = new Map<"\r\n" | "\n" | "\r", number>([
+    ["\r\n", 0],
+    ["\n", 0],
+    ["\r", 0],
+  ]);
+  for (const line of lines) {
+    if (line.ending !== "") counts.set(line.ending, (counts.get(line.ending) ?? 0) + 1);
+  }
+  let selected: "\r\n" | "\n" | "\r" = "\n";
+  for (const ending of ["\r\n", "\r"] as const) {
+    if ((counts.get(ending) ?? 0) > (counts.get(selected) ?? 0)) selected = ending;
+  }
+  return selected;
+}
+
+function normalizeToLf(content: string): string {
+  return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+function replacementLines(text: string): string[] {
+  if (text === "") return [];
+  return normalizeToLf(text).replace(/\n$/, "").split("\n");
+}
+
 function applyAnchorEdits(content: string, edits: AnchorEdit[]): string {
-  const newline = content.includes("\r\n") ? "\r\n" : "\n";
-  const trailingNewline = content.endsWith("\n");
-  const lines = content.replace(/\r\n/g, "\n").split("\n");
-  if (trailingNewline) lines.pop();
+  const bom = content.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const lines = parseEditableLines(bom ? content.slice(1) : content);
+  const newline = detectLineEnding(lines);
   const planned = edits.map((edit) => {
     if ("set_line" in edit) {
       const { line } = parseAnchor(edit.set_line.anchor);
@@ -372,15 +558,85 @@ function applyAnchorEdits(content: string, edits: AnchorEdit[]): string {
     if (edit.start < 0 || edit.start > lines.length || edit.start + edit.deleteCount > lines.length) {
       throw new Error("anchor line is outside the file");
     }
-    const replacement = edit.text === "" ? [] : edit.text.replace(/\r\n/g, "\n").split("\n");
+    const removed = lines.slice(edit.start, edit.start + edit.deleteCount);
+    const replacement = replacementLines(edit.text).map((text): EditableLine => ({ text, ending: newline }));
+    if (edit.deleteCount === 0 && edit.start === lines.length && replacement.length > 0) {
+      const previous = lines.at(-1);
+      const terminalEnding = previous?.ending ?? "";
+      if (previous?.ending === "") previous.ending = newline;
+      replacement[replacement.length - 1].ending = terminalEnding;
+    } else if (edit.deleteCount > 0) {
+      const terminalEnding = removed.at(-1)?.ending ?? "";
+      if (replacement.length > 0) {
+        replacement[replacement.length - 1].ending = terminalEnding;
+      } else if (edit.start + edit.deleteCount === lines.length && edit.start > 0) {
+        lines[edit.start - 1].ending = terminalEnding;
+      }
+    }
     lines.splice(edit.start, edit.deleteCount, ...replacement);
   }
-  return lines.join(newline) + (trailingNewline ? newline : "");
+  return bom + lines.map((line) => line.text + line.ending).join("");
+}
+
+async function readTextSnapshot(filePath: string): Promise<TextSnapshot> {
+  try {
+    return { exists: true, content: await readFile(filePath, "utf8") };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { exists: false, content: "" };
+    throw error;
+  }
+}
+
+async function writeHandle(handle: Awaited<ReturnType<typeof open>>, content: string): Promise<void> {
+  const data = Buffer.from(content, "utf8");
+  await handle.truncate(0);
+  let offset = 0;
+  while (offset < data.length) {
+    const { bytesWritten } = await handle.write(data, offset, data.length - offset, offset);
+    if (bytesWritten === 0) throw new Error("write made no progress");
+    offset += bytesWritten;
+  }
 }
 
-async function writeText(filePath: string, content: string): Promise<void> {
+async function writeText(filePath: string, expected: TextSnapshot, content: string): Promise<void> {
   await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content, "utf8");
+  if (!expected.exists) {
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await open(filePath, "wx+");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        throw new Error(`refusing to overwrite changed file: ${filePath}`);
+      }
+      throw error;
+    }
+    try {
+      await writeHandle(handle, content);
+    } finally {
+      await handle.close();
+    }
+    return;
+  }
+
+  const pathInfo = await lstat(filePath);
+  if (pathInfo.isSymbolicLink()) throw new Error(`refusing to modify symbolic link: ${filePath}`);
+  const handle = await open(filePath, "r+");
+  try {
+    const handleInfo = await handle.stat();
+    const currentPathInfo = await lstat(filePath);
+    if (
+      currentPathInfo.isSymbolicLink() ||
+      currentPathInfo.dev !== handleInfo.dev ||
+      currentPathInfo.ino !== handleInfo.ino
+    ) {
+      throw new Error(`refusing to overwrite changed file: ${filePath}`);
+    }
+    const current = (await handle.readFile()).toString("utf8");
+    if (current !== expected.content) throw new Error(`refusing to overwrite changed file: ${filePath}`);
+    if (current !== content) await writeHandle(handle, content);
+  } finally {
+    await handle.close();
+  }
 }
 
 function renameFiles(value: unknown): string[] {
@@ -394,9 +650,176 @@ function renameFiles(value: unknown): string[] {
   return files;
 }
 
+function diffLines(content: string): string[] {
+  if (content === "") return [];
+  const lines = normalizeToLf(content).split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+function diffRange(start: number, count: number): string {
+  return count === 0 ? `${start},0` : `${start + 1},${count}`;
+}
+
+function utf8Prefix(value: string, maxBytes: number): string {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length <= maxBytes) return value;
+  let end = maxBytes;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  while (end > 0) {
+    try {
+      return decoder.decode(bytes.subarray(0, end));
+    } catch {
+      end--;
+    }
+  }
+  return "";
+}
+
+function boundDocumentOutput(value: string): string {
+  const lines = value.split("\n");
+  let output = lines.length > MAX_DOCUMENT_OUTPUT_LINES
+    ? lines.slice(0, MAX_DOCUMENT_OUTPUT_LINES).join("\n")
+    : value;
+  const truncated = output !== value || Buffer.byteLength(output, "utf8") > MAX_DOCUMENT_OUTPUT_BYTES;
+  output = utf8Prefix(output, MAX_DOCUMENT_OUTPUT_BYTES);
+  return truncated
+    ? `${output}\n[… document view truncated; narrow it with page, node, kind, or depth]`
+    : output;
+}
+
+function attachmentExtension(mime: string): string {
+  switch (mime) {
+    case "image/gif":
+      return "gif";
+    case "image/jpeg":
+      return "jpg";
+    case "image/png":
+      return "png";
+    case "image/webp":
+      return "webp";
+    default:
+      return "bin";
+  }
+}
+
+function imageAttachment(image: Record<string, unknown>, filename: string): ToolAttachment | undefined {
+  if (image.encoding !== "base64" || typeof image.data !== "string" || typeof image.mime !== "string") {
+    return undefined;
+  }
+  return {
+    type: "file",
+    mime: image.mime,
+    url: `data:${image.mime};base64,${image.data}`,
+    filename: `${filename}.${attachmentExtension(image.mime)}`,
+  };
+}
+
+function formatReadResult(value: unknown): RenderedToolResult {
+  const output = record(value);
+  if (output.format === "pdf") {
+    const attachments: ToolAttachment[] = [];
+    const images = items(output.images).map((value, index) => {
+      const image = record(value);
+      const page = typeof image.page === "number" ? image.page : "unknown";
+      const attachment = imageAttachment(image, `pdf-page-${page}-image-${index + 1}`);
+      if (attachment) attachments.push(attachment);
+      const sanitized = { ...image };
+      delete sanitized.data;
+      delete sanitized.encoding;
+      return sanitized;
+    });
+    return {
+      output: boundDocumentOutput(render({ ...output, images })),
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+  }
+
+  const attachment = imageAttachment(output, "image");
+  if (!attachment) return { output: render(value) };
+  const sanitized = { ...output };
+  delete sanitized.data;
+  delete sanitized.encoding;
+  return { output: render(sanitized), attachments: [attachment] };
+}
+
+function previewDiffLine(prefix: string, line: string): string {
+  const value = `${prefix}${line}`;
+  const maxBytes = 256;
+  if (Buffer.byteLength(value) <= maxBytes) return value;
+  return `${utf8Prefix(value, maxBytes - Buffer.byteLength("…"))}…`;
+}
+
+function sampleDiffLines(lines: string[], start: number, end: number, prefix: string): string[] {
+  const sampleSize = 20;
+  const count = end - start;
+  if (count <= sampleSize * 2) {
+    return lines.slice(start, end).map((line) => previewDiffLine(prefix, line));
+  }
+  return [
+    ...lines.slice(start, start + sampleSize).map((line) => previewDiffLine(prefix, line)),
+    ` ${count - sampleSize * 2} ${prefix === "-" ? "removed" : "added"} lines omitted`,
+    ...lines.slice(end - sampleSize, end).map((line) => previewDiffLine(prefix, line)),
+  ];
+}
+
 function simpleDiff(filePath: string, before: string, after: string): string {
   if (before === after) return "";
-  return `--- ${filePath}\n+++ ${filePath}\n@@ full file @@\n-${before}\n+${after}`;
+  const oldLines = diffLines(before);
+  const newLines = diffLines(after);
+  let prefix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix++;
+  let suffix = 0;
+  while (
+    suffix < oldLines.length - prefix &&
+    suffix < newLines.length - prefix &&
+    oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) suffix++;
+  if (prefix === oldLines.length && prefix === newLines.length) {
+    prefix = Math.max(0, prefix - 1);
+    suffix = 0;
+  }
+
+  const oldChangeEnd = oldLines.length - suffix;
+  const newChangeEnd = newLines.length - suffix;
+  const oldStart = Math.max(0, prefix - 3);
+  const newStart = Math.max(0, prefix - 3);
+  const oldEnd = Math.min(oldLines.length, oldChangeEnd + 3);
+  const newEnd = Math.min(newLines.length, newChangeEnd + 3);
+  const safePath = utf8Prefix(filePath.replace(/[\r\n]/g, ""), 1024);
+  const header = [
+    `--- ${safePath}`,
+    `+++ ${safePath}`,
+    `@@ -${diffRange(oldStart, oldEnd - oldStart)} +${diffRange(newStart, newEnd - newStart)} @@`,
+  ];
+  const fullDiff = [...header];
+  let fullDiffBytes = Buffer.byteLength(header.join("\n"));
+  let complete = true;
+  const ranges: Array<[string[], number, number, string]> = [
+    [oldLines, oldStart, prefix, " "],
+    [oldLines, prefix, oldChangeEnd, "-"],
+    [newLines, prefix, newChangeEnd, "+"],
+    [newLines, newChangeEnd, newEnd, " "],
+  ];
+  outer: for (const [lines, start, end, marker] of ranges) {
+    for (let index = start; index < end; index++) {
+      const lineBytes = 2 + Buffer.byteLength(lines[index]);
+      if (fullDiffBytes + lineBytes > MAX_PERMISSION_DIFF_BYTES) {
+        complete = false;
+        break outer;
+      }
+      fullDiff.push(`${marker}${lines[index]}`);
+      fullDiffBytes += lineBytes;
+    }
+  }
+  if (complete) return fullDiff.join("\n");
+
+  return [
+    ...header,
+    ` diff truncated: ${oldChangeEnd - prefix} removed, ${newChangeEnd - prefix} added lines`,
+    ...sampleDiffLines(oldLines, prefix, oldChangeEnd, "-"),
+    ...sampleDiffLines(newLines, prefix, newChangeEnd, "+"),
+  ].join("\n");
 }
 
 function identifiedName(value: unknown): string | undefined {
@@ -419,6 +842,8 @@ function initialTitle(kind: PresentationKind, args: any): string {
   switch (kind) {
     case "read":
       return `Read ${args.path}`;
+    case "view":
+      return `View ${args.path}`;
     case "map":
       return `Map ${args.path}`;
     case "search":
@@ -461,6 +886,8 @@ function resultPresentation(kind: PresentationKind, args: any, value: unknown):
       }
       break;
     }
+    case "view":
+      return { title: `Viewed ${args.path}`, metadata: {} };
     case "map": {
       const symbols = items(output.symbols).length;
       return { title: `Mapped ${args.path} (${symbols} symbols)`, metadata: { symbols } };
@@ -528,6 +955,7 @@ function readseekTool(
   args: Record<string, any>,
   kind: PresentationKind,
   execute: (args: any, context: ToolContext) => Promise<unknown>,
+  formatResult: (result: unknown) => RenderedToolResult = (result) => ({ output: render(result) }),
 ) {
   return tool({
     description,
@@ -537,7 +965,11 @@ function readseekTool(
       context.metadata({ title });
       const result = await execute(args, context);
       const presentation = resultPresentation(kind, args, result);
-      return { title: presentation.title, output: render(result), metadata: presentation.metadata };
+      return {
+        title: presentation.title,
+        ...formatResult(result),
+        metadata: presentation.metadata,
+      };
     },
   });
 }
@@ -569,6 +1001,7 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
           path: tool.schema.string().describe("Path relative to the project directory"),
           offset: tool.schema.number().int().positive().optional().describe("One-based starting line"),
           limit: tool.schema.number().int().positive().optional().describe(`Maximum number of lines; defaults to ${DEFAULT_READ_LIMIT}`),
+          page: tool.schema.number().int().positive().optional().describe("One-based PDF page; defaults to 1"),
           language: tool.schema.string().optional().describe("Language override when auto-detection is ambiguous"),
           ...(imagePolicy === "off"
             ? {}
@@ -584,20 +1017,55 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
           const image = input.image as ImageMode | undefined;
           if (imagePolicy === "off" && image !== undefined) throw new Error("image and PDF reads are disabled");
           if (imagePolicy === "on" && image === "none") throw new Error('image="none" requires imageMode="auto"');
-          if (image === undefined) {
-            const detection = await runReadSeek(context, ["detect", filePath]);
-            if (isVisualFile(detection)) {
-              return { file: filePath, skipped: true, reason: "image mode not selected" };
-            }
+          const detection = await runReadSeek(context, ["detect", filePath]);
+          const visual = isVisualFile(detection);
+          const pdf = isPdfFile(detection);
+          if (visual && image === undefined) {
+            return { file: filePath, skipped: true, reason: "image mode not selected" };
+          }
+          if (visual && (input.offset !== undefined || input.limit !== undefined)) {
+            throw new Error("offset and limit do not apply to image or PDF reads");
+          }
+          if (visual && input.language !== undefined) {
+            throw new Error("language does not apply to image or PDF reads");
           }
+          if (!pdf && input.page !== undefined) throw new Error("page applies to PDF reads only");
+
           const args = ["read", input.offset === undefined ? filePath : `${filePath}:${input.offset}`];
-          if (image === undefined) {
+          if (!visual) {
             args.push("--end", String((input.offset ?? 1) + ((input.limit as number | undefined) ?? DEFAULT_READ_LIMIT) - 1));
           }
           if (input.language) args.push("--language", input.language as string);
           if (image !== undefined) args.push("--image", image);
+          if (pdf) args.push("--page", String(input.page ?? 1));
           return runReadSeek(context, args);
         },
+        formatReadResult,
+      ),
+      readseek_view: readseekTool(
+        "View the structure or selected content of an indexed PDF. Start with the overview, then narrow by page or node.",
+        {
+          path: tool.schema.string().describe("PDF path relative to the project directory"),
+          node: tool.schema.string().min(1).optional().describe("Node ID to use as the view root"),
+          page: tool.schema.number().int().positive().optional().describe("One-based source page"),
+          kind: tool.schema.enum(DOCUMENT_NODE_KINDS).optional().describe("Node kind filter"),
+          depth: tool.schema.number().int().nonnegative().optional().describe("Maximum depth below selected roots"),
+          outline: tool.schema.boolean().optional().describe("Return outline nodes only"),
+        },
+        "view",
+        async (input, context) => {
+          const filePath = resolvePath(context.directory, input.path as string);
+          await authorizeRead(context, filePath);
+          const cacheDir = await ensureReadSeekCache(context);
+          const args = ["--readseek-dir", cacheDir, "view", filePath];
+          if (input.node) args.push("--node", input.node as string);
+          if (input.page !== undefined) args.push("--page", String(input.page));
+          if (input.kind) args.push("--kind", input.kind as string);
+          if (input.depth !== undefined) args.push("--depth", String(input.depth));
+          optionalFlag(args, input.outline as boolean | undefined, "--outline");
+          return runReadSeekRaw(context, args);
+        },
+        (result) => ({ output: boundDocumentOutput(String(result)) }),
       ),
       readseek_map: readseekTool(
         "List symbols and ranges in a source file. Use to inspect structure without reading the full file.",
@@ -792,17 +1260,12 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
           const plan = await runReadSeek(context, args);
           if (input.apply === false) return plan;
           const files = renameFiles(plan);
-          if (input.workspace) {
-            await context.ask({
-              permission: "edit",
-              patterns: ["**"],
-              always: ["**"],
-              metadata: { filepath: files.join(", "), diff: "" },
-            });
-          } else {
-            await authorizeEdit(context, files);
+          const planHash = record(plan).plan_hash;
+          if (typeof planHash !== "string" || planHash.length === 0) {
+            throw new Error("readseek rename plan did not include a plan hash");
           }
-          return runReadSeek(context, [...args, "--apply"]);
+          await authorizeEdit(context, files);
+          return runReadSeek(context, [...args, "--plan-hash", planHash, "--apply"], { cancelable: false });
         },
       ),
       readseek_edit: readseekTool(
@@ -810,24 +1273,38 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         {
           path: tool.schema.string().describe("Path relative to the project directory"),
           edits: tool.schema.array(tool.schema.union([
-            tool.schema.object({ set_line: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }) }),
-            tool.schema.object({ replace_lines: tool.schema.object({ start_anchor: tool.schema.string(), end_anchor: tool.schema.string(), new_text: tool.schema.string() }) }),
-            tool.schema.object({ insert_after: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }) }),
+            tool.schema.object({
+              set_line: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }).strict(),
+            }).strict(),
+            tool.schema.object({
+              replace_lines: tool.schema.object({
+                start_anchor: tool.schema.string(),
+                end_anchor: tool.schema.string(),
+                new_text: tool.schema.string(),
+              }).strict(),
+            }).strict(),
+            tool.schema.object({
+              insert_after: tool.schema.object({ anchor: tool.schema.string(), new_text: tool.schema.string() }).strict(),
+            }).strict(),
           ])).min(1).describe("Anchored edits to apply"),
         },
         "edit",
         async (input, context) => {
           const filePath = resolvePath(context.directory, input.path as string);
-          await authorizeRead(context, filePath);
-          await rejectSymlinkMutation(filePath);
-          const edits = input.edits as AnchorEdit[];
-          const before = await readFile(filePath, "utf8");
-          await verifyAnchors(context, filePath, edits);
-          const after = applyAnchorEdits(before, edits);
-          await authorizeEdit(context, [filePath], simpleDiff(filePath, before, after), false);
-          if (await readFile(filePath, "utf8") !== before) throw new Error(`refusing to edit changed file: ${filePath}`);
-          if (before !== after) await writeText(filePath, after);
-          return runReadSeek(context, ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)]);
+          validateAnchorEdits(input.edits);
+          return withFileMutationQueue(filePath, async () => {
+            context.abort.throwIfAborted();
+            await authorizeRead(context, filePath);
+            await rejectSymlinkMutation(filePath);
+            const edits = input.edits;
+            const before = await readFile(filePath, "utf8");
+            await verifyAnchors(context, filePath, edits);
+            const after = applyAnchorEdits(before, edits);
+            await authorizeEdit(context, [filePath], simpleDiff(filePath, before, after), false);
+            context.abort.throwIfAborted();
+            if (before !== after) await writeText(filePath, { exists: true, content: before }, after);
+            return runReadSeek(context, ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)], { cancelable: false });
+          });
         },
       ),
       readseek_write: readseekTool(
@@ -840,15 +1317,17 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         async (input, context) => {
           const filePath = resolvePath(context.directory, input.path as string);
           await authorizeExternal(context, filePath);
-          await rejectSymlinkMutation(filePath);
-          const before = await readFile(filePath, "utf8").catch(() => "");
-          const content = input.content as string;
-          if (content.includes("\0")) throw new Error("write content must be text");
-          await authorizeEdit(context, [filePath], simpleDiff(filePath, before, content), false);
-          const current = await readFile(filePath, "utf8").catch(() => "");
-          if (current !== before) throw new Error(`refusing to overwrite changed file: ${filePath}`);
-          if (before !== content) await writeText(filePath, content);
-          return runReadSeek(context, ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)]);
+          return withFileMutationQueue(filePath, async () => {
+            context.abort.throwIfAborted();
+            await rejectSymlinkMutation(filePath);
+            const before = await readTextSnapshot(filePath);
+            const content = input.content as string;
+            if (content.includes("\0")) throw new Error("write content must be text");
+            await authorizeEdit(context, [filePath], simpleDiff(filePath, before.content, content), false);
+            context.abort.throwIfAborted();
+            await writeText(filePath, before, content);
+            return runReadSeek(context, ["read", filePath, "--end", String(DEFAULT_READ_LIMIT)], { cancelable: false });
+          });
         },
       ),
       readseek_check: readseekTool(
@@ -867,6 +1346,13 @@ export const ReadSeekPlugin: Plugin = async (_input, options) => {
         },
       ),
     },
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(EDITING_POLICY);
+    },
+    "tool.definition": async (input, output) => {
+      const preference = PREFERRED_TOOL_DESCRIPTIONS[input.toolID];
+      if (preference) output.description = `${preference} ${output.description}`;
+    },
     event: async ({ event }) => {
       if (event.type === "file.edited" || event.type === "file.watcher.updated") {
         anchors.forget(event.properties.file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-readseek",
-  "version": "0.6.13",
+  "version": "0.7.1",
   "description": "OpenCode plugin for readseek-backed structural code navigation",
   "type": "module",
   "main": "./index.ts",
@@ -30,7 +30,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.6.13",
+    "@jarkkojs/readseek": "^0.7.1",
     "@opencode-ai/plugin": "^1.17.20"
   },
   "devDependencies": {