pi-readseek 0.5.19 → 0.6.1

package/README.md

@@ -23,8 +23,8 @@ npm install --save-dev @jarkkojs/readseek
 
 ## Tools
 
-- **readSeek_read:** reads text files with `LINE:HASH` anchors; images can
-  include local OCR, captions, and object text.
+- **readSeek_read:** reads text with `LINE:HASH` anchors; images and PDFs can
+  be returned as base64 or analyzed locally.
 - **readSeek_edit:** edits existing text files using fresh `LINE:HASH` anchors.
 - **readSeek_grep:** searches text and returns edit-ready anchors.
 - **readSeek_search:** searches code by structural AST pattern.
@@ -49,7 +49,7 @@ optional (defaults shown):
 {
   "readseek": {
     "replacedTools": [],
-    "imageMode": "force",
+    "imageMode": "auto",
     "syntaxValidation": "warn",
     "timeoutMs": 120000,
     "grep": {
@@ -63,10 +63,9 @@ optional (defaults shown):
 - **replacedTools:** built-in tool names to replace with their `readSeek_*` equivalents.
   Valid values are `"read"`, `"edit"`, `"write"`, and `"grep"`. For a
   readseek-only file surface, use `["read", "edit", "write", "grep"]`.
-- **imageMode:** image OCR/caption/object analysis in `readSeek_read`: `"force"`
-  (or its alias `"on"`) always runs it, `"off"` returns only the image
-  attachment, and `"auto"` runs it only when the active model does not support
-  native image input.
+- **imageMode:** `"auto"` exposes `none`, `ocr`, `caption`, and `objects`;
+  `"on"` omits `none`; `"off"` skips image/PDF files. Omitting `image` also
+  skips visual files.
 - **syntaxValidation:** pre-write syntax-regression check in `readSeek_edit`:
   `"warn"` writes with a warning, `"block"` aborts without writing, `"off"`
   skips the check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.5.19",
+  "version": "0.6.1",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,7 +39,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.5.19",
+    "@jarkkojs/readseek": "^0.6.1",
     "diff": "^8.0.3",
     "xxhash-wasm": "^1.1.0"
   },

package/prompts/def.md

@@ -1,17 +1,14 @@
-Find structural symbol definitions. Calls `readseek def` which searches
-for the definition of a named symbol across a file or directory.
+Find structural definitions by qualified or unqualified name across a file or
+directory.
 
 ## Parameters
 
-- `path` (optional): File or directory to search (default: ".").
-- `name`: Qualified or unqualified symbol name.
-- `lang` (optional): Language override.
-- `cached` (optional): Search tracked/indexed files in a Git repository.
-- `others` (optional): Search untracked files.
-- `ignored` (optional): Include ignored untracked files.
+- `path` — file or directory, default `.`.
+- `name` — qualified or unqualified symbol name.
+- `lang` — language override.
+- `cached`, `others`, `ignored` — Git file selection; `ignored` requires `others`.
 
 ## When to use
 
-- After a `readSeek_hover` call, use the qualified symbol name to jump to its definition.
-- When the user asks "where is X defined?".
-- To find a function/class/type definition by its qualified name.
+- After `readSeek_hover`, use its qualified symbol name.
+- When asked where a function, class, or type is defined.

package/prompts/edit.md

@@ -1,6 +1,6 @@
-Surgically edit existing text files. Prefer hash-verified anchors from fresh `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write` output; copy `LINE:HASH` anchors exactly.
-
-`readSeek_edit` requires the target file to have been anchored earlier in the current session. If you get `file-not-read`, run `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write` first.
+Edit existing text files with fresh `LINE:HASH` anchors from `readSeek_read`,
+`readSeek_grep`, `readSeek_search`, or `readSeek_write`. The file must have
+been anchored in this session; on `file-not-read`, read or search it first.
 
 ## Variants
 
@@ -9,12 +9,11 @@ Surgically edit existing text files. Prefer hash-verified anchors from fresh `re
 | `set_line` | Replace or delete one line | 1 |
 | `replace_lines` | Replace or delete one contiguous range | 2 |
 | `insert_after` | Insert after an existing line | 1 |
-| `replace_symbol` | Replace one function/class/method/interface/type/enum/etc. | 0 (`symbol`) |
-| `replace` | Exact string replacement escape hatch; one match by default, all with `all: true` | 0 |
-
-Set `new_text` (or `replace_lines.new_text`) to `""` to delete anchored line(s). For an intentionally blank line, use `"\n"` or whitespace content, not `""`.
+| `replace_symbol` | Replace one mapped symbol | 0 (`symbol`) |
+| `replace` | Exact string replacement; one match unless `all: true` | 0 |
 
-Prefer `set_line`, `replace_lines`, and `insert_after`: they verify that the file still matches the anchored content. Use `replace` only when anchors are impractical, such as repeated text across many unrelated lines.
+Set `new_text` to `""` to delete lines; use `"\n"` for a blank line. Prefer
+anchored variants. Use `replace` only when anchors are impractical.
 
 ## Input shape
 
@@ -31,92 +30,41 @@ Prefer `set_line`, `replace_lines`, and `insert_after`: they verify that the fil
 }
 ```
 
-Use only the needed variant(s); the example shows all shapes for reference. Each `edits[]` entry must contain exactly one variant key. `new_text` / `new_body` is plain file content — no hash prefixes or diff markers.
+Use only needed variants. Each `edits[]` entry has exactly one key. `new_text`
+and `new_body` are plain file content, not diffs or hashlines.
 
 ## Exact and fuzzy replacement
 
-`replace` is exact-only by default. Missing `old_text` fails with `text-not-found`.
-
-Wrap string replacements as `{ "replace": { "old_text": "...", "new_text": "..." } }`; a bare top-level `{ old_text, new_text }` inside `edits[]` is rejected with guidance.
-
-`fuzzy: true` is a narrow fallback after exact matching fails. It normalizes whitespace and confusable Unicode such as smart hyphens; it is **not** approximate, Levenshtein, or semantic matching. Fuzzy successes return a warning.
+`replace` is exact by default; missing text fails. `fuzzy: true` only normalizes
+whitespace and confusable Unicode after exact matching fails. Verify warned fuzzy
+matches before continuing.
 
 ## `replace_symbol`
 
-Use `replace_symbol` when you want to replace one whole mapped symbol without line anchors. Query symbols like `readSeek_read({ symbol })`: `Name`, `Class.method`, or `Name@<line>`.
-
-Rules:
-
-- Use an exact name, dotted path, or `@<line>`. If `readSeek_read({ symbol })` returned a fuzzy match, confirm the exact symbol first.
-- Supported for TypeScript, JavaScript, Rust, and Java. For other languages, use anchored edits.
-- `new_body` must not be empty or whitespace-only.
-- Write `new_body` without extra leading indentation; `readSeek_edit` re-indents it to match the original symbol.
-- If `new_body` appears to declare a different symbol name, the edit still applies but returns a `name-mismatch` warning.
-- Do not combine `replace_symbol` with anchored edits that touch the same lines. Duplicate or overlapping `replace_symbol` ranges are rejected.
+Use `replace_symbol` for one whole mapped `Name`, `Class.method`, or
+`Name@<line>` in TypeScript, JavaScript, Rust, or Java. `new_body` must be
+non-empty and unindented. Confirm fuzzy symbol matches first; do not overlap it
+with anchored edits.
 
 ## Stale anchors
 
-If anchors no longer match, `readSeek_edit` fails with `hash-mismatch` and shows nearby current lines. Lines marked `>>>` include updated anchors:
+On `hash-mismatch`, nearby lines marked `>>>` include fresh anchors:
 
 ```text
 >>> 41:b34|  const renamed = 3;
 ```
 
-Copy the updated `LINE:HASH` and retry. If the target moved farther away, re-run `readSeek_read`, `readSeek_grep`, `readSeek_search`, or `readSeek_write` for fresh anchors.
-
-If `readSeek_edit` auto-relocates an anchor, read the warning and verify that the edit landed in the intended place.
+Retry with those anchors, or read/search again. Verify any auto-relocation warning.
 
 ## Validation and warnings
 
-- All edits are checked before writing; if a hard validation fails, nothing is written.
-- Anchored edits are applied bottom-up so line numbers stay stable.
-- `no-op` means the requested edit matched the current file already or produced identical content.
-- Whitespace-only warnings mean formatting changed but behavior probably did not.
-- A `replace`-only success may remind you to prefer anchored edits next time.
-
-Syntax validation runs before writing when supported:
-
-- Supported: Rust, C++, C headers, Java.
-- Default `warn`: write succeeds, but warnings include `syntax-regression: lines X-Y`.
-- `block`: aborts without writing.
-- `off`: skips validation.
-- The `readseek.syntaxValidation` setting can change the default mode.
-
-Existing syntax errors are tolerated; warnings are for newly introduced parser errors.
+All edits validate before writing; hard failures write nothing. Anchored edits run
+bottom-up. `no-op` means no change. Syntax validation for Rust, C++, C headers,
+and Java follows `readseek.syntaxValidation`: `warn` (default), `block`, or `off`.
+It reports only newly introduced parser errors.
 
 ## Optional post-edit verification
 
-`postEditVerify: true` opts into read-back verification for this call. It is off by default. When enabled, `readSeek_edit` writes normally, then reads the file back and compares persisted content to the intended content, including BOM and original line endings. This is not syntax validation.
-
-## Diff data contract
-
-Successful `readSeek_edit` results include:
-
-- `details.diff` and `details.readSeekValue.diff`: compact human-readable hashline diff strings.
-- `details.patch`: standard unified diff with file and hunk headers.
-- `details.diffData` and `details.readSeekValue.diffData`: stable structured diff data.
-
-`diffData` shape:
-
-```ts
-type DiffData = {
-  version: 1;
-  entries: Array<
-    | { kind: "context"; oldLine: number; newLine: number; text: string }
-    | { kind: "add"; newLine: number; text: string }
-    | { kind: "remove"; oldLine: number; text: string }
-    | { kind: "meta"; text: string }
-  >;
-  stats: { added: number; removed: number; context: number };
-  language?: string;
-  blockRanges?: Array<{ kind: "add" | "remove"; startLine: number; endLine: number }>;
-  inlineDiffs?: Array<{
-    removeLineIndex: number;
-    addLineIndex: number;
-    removeSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
-    addSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
-  }>;
-};
-```
-
-For compact one-line hashline diffs, `details.diff` remains compact while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.
+`postEditVerify: true` reads back the written file and compares the persisted
+content, including BOM and line endings. Results provide a compact hashline diff,
+a unified patch, and structured `details.diffData`.

package/prompts/hover.md

@@ -1,15 +1,11 @@
-Use `readSeek_hover` to identify the identifier and enclosing symbol at a cursor
-position. Calls `readseek identify` with the file content sent via stdin
-so unsaved editor content is included.
+Identify the identifier and enclosing symbol at a cursor. Unsaved editor content
+is included.
 
 ## Parameters
 
-- `path` (required): File path.
-- `line` (required): One-based cursor line.
-- `column` (optional): One-based cursor byte column.
+- `path`, `line` — required file path and one-based cursor line.
+- `column` — optional one-based cursor byte column.
 
 ## When to use
 
-- Before a `readSeek_rename`, to confirm the identifier under the cursor.
-- Before a go-to-definition, to get the qualified symbol name.
-- To inspect what symbol a specific line belongs to.
+- Before rename or go-to-definition, or to identify a line's enclosing symbol.

package/prompts/read.md

@@ -1,21 +1,22 @@
-Read files through readseek. Text output uses `LINE:HASH|content` anchors that can be copied directly into `readSeek_edit`; supported images return attachments and may append OCR/caption/object text depending on `readseek.imageMode`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
+Read files through readseek. Text results use `LINE:HASH|content` anchors for `readSeek_edit`. Images and PDFs require an explicit available `image` mode; omitting it skips them. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}.
 
 ## Choose the right read
 
-- Normal read: inspect a whole small file or a targeted `offset` / `limit` range.
-- `map: true`: append a structural map for navigation before reading more code.
-- `symbol: "Name"`: read one function, class, method, interface, type, enum, or similar symbol.
-- `bundle: "local"`: with `symbol`, include direct same-file local support when readseek can identify it.
+- Normal read: a small file or an `offset` / `limit` range.
+- `map: true`: append a structural map.
+- `symbol: "Name"`: read one mapped symbol.
+- `bundle: "local"`: include direct same-file support for a symbol.
 
 ## Parameters
 
 - `path` — file path.
-- `offset` / `limit` — positive line numbers; `offset` is 1-indexed.
-- `map` — append the full-file structural map; cannot combine with `symbol` or `bundle`.
-- `symbol` — symbol query; supports `Class.method`, package-relative Java names, and `Name@<line>` disambiguation; cannot combine with `offset` / `limit`.
-- `bundle` — only `"local"`; requires `symbol` and cannot combine with `map`.
+- `offset` / `limit` — positive lines; `offset` is 1-indexed.
+- `map` — full-file map; incompatible with `symbol` or `bundle`.
+- `symbol` — `Name`, `Class.method`, or `Name@<line>`; incompatible with `offset` / `limit`.
+- `bundle` — only `"local"`; requires `symbol` and excludes `map`.
+- `image` — an exposed image/PDF mode.
 
-When a full-file read is truncated, readseek appends a structural map automatically when available. Use map line ranges for follow-up `readSeek_read({ offset, limit })` calls.
+Truncated full-file reads append a map when available. Use its ranges for follow-up reads.
 
 ## Symbol examples
 
@@ -29,13 +30,13 @@ When a full-file read is truncated, readseek appends a structural map automatica
 
 ## Symbol resolution
 
-`@<line>` only applies as a trailing suffix like `Foo.bar@42`; names such as `foo@bar` are ordinary queries. Resolution order: containing range → nearest symbol starting at/after the requested line → nearest symbol above it.
+`@<line>` is only a trailing suffix, as in `Foo.bar@42`; `foo@bar` is an ordinary name. Resolution prefers the containing range, then the nearest symbol at or after the line, then one above it.
 
 Result behavior:
 
-- **Found**: returns only the symbol range with `[Symbol: name (kind), lines X-Y of Z]`.
-- **Ambiguous**: lists candidates and retry hints such as `name@<startLine>`.
-- **Fuzzy**: returns the best camelCase/substring match with a warning; verify before editing from those anchors.
-- **Not found** or **unmappable**: falls back to normal read with a warning and, when available, symbol suggestions.
+- **Found:** the symbol range.
+- **Ambiguous:** candidates and `name@<startLine>` retry hints.
+- **Fuzzy:** a warned best match; verify before editing.
+- **Not found/unmappable:** normal read with a warning and suggestions when available.
 
 Hash anchors from normal, symbol, and bundled reads are valid for `readSeek_edit` until the file changes.

package/prompts/refs.md

@@ -1,10 +1,11 @@
-Find binding-accurate references to an identifier with readseek. Use it when you need every place a name is used — before renaming, deleting, or changing a symbol — and plain text search would be too broad. Results are grouped by file with edit-ready hashline anchors and the enclosing symbol for each reference.
+Find identifier references before renaming, deleting, or changing a symbol when
+text search is too broad. Results include edit-ready anchors and enclosing symbols.
 
 ## Parameters
 
 - `name` — identifier to find references for.
 - `path` — file or directory, default cwd.
-- `lang` — language hint; set it when syntax is ambiguous, extensionless, or generated.
+- `lang` — language hint for ambiguous, extensionless, or generated code.
 - `scope` — restrict results to the binding under `line`/`column` in a single file. Requires `line`.
 - `line` — one-based cursor line, used with `scope`.
 - `column` — one-based cursor byte column, used with `scope`.
@@ -14,10 +15,13 @@ Find binding-accurate references to an identifier with readseek. Use it when you
 
 ## Scope
 
-Without `scope`, references match by identifier name across the target. With `scope` plus `line` (and optionally `column`), results are limited to the specific binding under that cursor in a single file, so shadowed or unrelated same-named identifiers are excluded.
+Without `scope`, references match by name. With `scope` and `line` (optionally
+`column`), results are limited to the cursor binding in one file and exclude
+shadows.
 
 ## Git selection
 
-When searching a directory inside a Git repository, readseek defaults to tracked/indexed files plus untracked non-ignored files. Use `cached`, `others`, and `ignored` to narrow or expand that selection. `ignored` requires `others`.
+In Git repositories, directory search includes tracked/indexed and untracked
+non-ignored files. `ignored` requires `others`.
 
 Use `readSeek_grep` for plain text, `readSeek_search` for code shape, and `readSeek_refs` for identifier usage.

package/prompts/rename.md

@@ -1,27 +1,18 @@
-Use `readSeek_rename` to rename an identifier (variable, function, type, etc.) with
-binding accuracy. The tool calls `readseek rename` which resolves the
-lexical binding under the cursor and renames every occurrence that binds
-to the same declaration.
+Rename an identifier with binding accuracy. The cursor binding is resolved and
+only occurrences of that declaration are changed.
 
 ## Parameters
 
-- `path` (required): File holding the binding to rename (a single regular file).
-- `line` (required): One-based cursor line of the binding to rename.
-- `column` (optional): One-based cursor byte column of the binding.
-- `to` (required): New name for the binding. Must be a plain identifier.
-- `workspace` (optional): When true, expands the rename across the project
-  root. The cursor file remains binding-accurate; other files are matched
-  by name (free uses only, local shadows excluded).
-- `apply` (optional, default true): When true, writes the edits to disk
-  after verifying line hashes. When false, returns the plan only.
+- `path`, `line`, `to` — required file, one-based cursor line, and plain new name.
+- `column` — optional one-based cursor byte column.
+- `workspace` — expand across the project; local shadows in other files are excluded.
+- `apply` — default `true`; set `false` to return only the verified plan.
 
 ## When to use
 
-- The user asks to rename a symbol (function, variable, class, etc.).
-- The cursor position (line, optionally column) is known from an identify
-  call or from the user's editor context.
+- Use when the user requests a symbol rename and the cursor is known.
 
 ## When not to use
 
-- For search-and-replace across files, use `readSeek_grep` or `readSeek_search`.
-- For refactoring that requires adding/removing parameters, use `readSeek_edit`.
+- Use `readSeek_grep`/`readSeek_search` for broad replacement and
+  `readSeek_edit` for other refactors.

package/prompts/sg.md

@@ -1,9 +1,11 @@
-Search code with readseek AST patterns. Use it when text search is too broad or brittle and the query depends on syntax: calls, imports, declarations, JSX, object fields, control flow, and similar code shapes. Results are grouped by file with edit-ready hashline anchors.
+Search code with AST patterns when text search is too broad. Use it for calls,
+imports, declarations, JSX, object fields, and control flow. Results include
+edit-ready anchors.
 
 ## Parameters
 
 - `pattern` — ast-grep-style pattern to match.
-- `lang` — language hint; set it when syntax is ambiguous, extensionless, generated, or TSX/JSX-like.
+- `lang` — language hint for ambiguous, extensionless, generated, or JSX-like code.
 - `path` — file or directory, default cwd.
 - `cached` — in a Git repository, search tracked/indexed files.
 - `others` — in a Git repository, search untracked files.
@@ -16,7 +18,8 @@ Search code with readseek AST patterns. Use it when text search is too broad or
 - `$$$ARGS` matches zero or more sibling nodes. Use it for function args, body statements, object fields, JSX children, etc.
 - Reusing a metavariable name requires every occurrence to match the same source text.
 
-Patterns are parsed as code, not text. Formatting is mostly ignored, but syntax must be valid for the selected language. Include punctuation that the language grammar requires.
+Patterns are code, not text: formatting is mostly ignored, but syntax and required
+punctuation must be valid for the selected language.
 
 ## Examples
 
@@ -27,14 +30,10 @@ Patterns are parsed as code, not text. Formatting is mostly ignored, but syntax
 - `<$TAG $$$ATTRS>$$$CHILDREN</$TAG>` — JSX/TSX elements.
 - `if ($COND) { $$$BODY }` — control-flow blocks.
 
-## Languages
-
-Useful `lang` values include `assembly`, `bash`, `c`, `cpp`, `csharp`, `css`, `dockerfile`, `gdscript`, `go`, `html`, `java`, `javascript`, `json`, `jsx`, `just`, `kconfig`, `latex`, `lua`, `make`, `markdown`, `meson`, `nix`, `perl`, `php`, `puppet`, `python`, `riscv`, `ruby`, `rust`, `sql`, `swift`, `toml`, `tsx`, `typescript`, `typst`, `xml`, `yaml`, `zig`, and `unknown`.
-
-`unknown` forces text-only handling and is not useful for parser-backed search.
-
 ## Git selection
 
-When searching a directory inside a Git repository, readseek defaults to tracked/indexed files plus untracked non-ignored files. Use `cached`, `others`, and `ignored` to narrow or expand that selection. `ignored` requires `others`.
+In Git repositories, directory search includes tracked/indexed and untracked
+non-ignored files. Use `cached`, `others`, and `ignored` to choose; `ignored`
+requires `others`.
 
 Use `readSeek_grep` for plain text and `readSeek_search` for structure.

package/prompts/write.md

@@ -1,46 +1,21 @@
-Create or overwrite a whole file and return `LINE:HASH` anchors for immediate follow-up `readSeek_edit` calls.
+Create or replace a whole file and return `LINE:HASH` anchors for follow-up edits.
 
 ## Use / avoid
 
-Use `readSeek_write` for new files, generated files, or intentional full-file replacement. For small changes or appends to an existing file, run `readSeek_read` or `readSeek_search` first and use `readSeek_edit` (`insert_after` for appends).
+Use it for new, generated, or intentionally replaced files. For small changes or
+appends, read/search first and use `readSeek_edit`.
 
-Existing files are overwritten without confirmation. Binary-looking content can be written, but hashlines are not generated, so there are no anchors for `readSeek_edit`.
+Existing files are overwritten without confirmation. Binary-looking content gets
+no anchors.
 
 ## Parameters
 
-- `path` — relative or absolute file path.
+- `path` — file path.
 - `content` — complete file contents.
-- `map` — optional; append a structural map when possible. Map generation is best-effort and does not make the write fail.
+- `map` — append a best-effort structural map.
 
 ## Output
 
-Successful text writes return `LINE:HASH|content`. Display hashlines escape control characters for safe rendering. Visible output is capped at 2000 lines or 50 KB, but full anchors remain available in `readSeekValue`.
-
-## Diff data contract
-
-Successful text `readSeek_write` results include additive final `details.diff`, `details.readSeekValue.diff`, `details.diffData`, and `details.readSeekValue.diffData` fields. String diff fields remain the backward-compatible human-readable fallback.
-
-`diffData` is a stable versioned contract:
-
-```ts
-type DiffData = {
-  version: 1;
-  entries: Array<
-    | { kind: "context"; oldLine: number; newLine: number; text: string }
-    | { kind: "add"; newLine: number; text: string }
-    | { kind: "remove"; oldLine: number; text: string }
-    | { kind: "meta"; text: string }
-  >;
-  stats: { added: number; removed: number; context: number };
-  language?: string;
-  blockRanges?: Array<{ kind: "add" | "remove"; startLine: number; endLine: number }>;
-  inlineDiffs?: Array<{
-    removeLineIndex: number;
-    addLineIndex: number;
-    removeSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
-    addSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
-  }>;
-};
-```
-
-For compact one-line hashline diffs, `details.diff` remains compact while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.
+Text writes return `LINE:HASH|content`. Visible output is capped at 2000 lines or
+50 KB; full anchors remain in `readSeekValue`. Results also include a compact
+diff, unified patch, and structured `details.diffData`.

package/src/edit.ts

@@ -627,7 +627,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			const { isPartial, isError, expanded, width, context } = resolveRenderResultContext(options, rest);
 
 			if (isPartial) {
-				return renderPendingResult("pending edit", width);
+				return renderPendingResult("pending edit", width, theme);
 			}
 
 			// Extract data from result
@@ -659,16 +659,16 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			let text = "";
 
 			if (info.noOp) {
-				text = summaryLine("no-op");
+				text = summaryLine("no-op", { theme, style: "dim" });
 				if (expanded && info.errorText) text += `\n${theme.fg("error", info.errorText)}`;
 			} else if (info.errorText) {
 				const firstLine = info.errorText.split("\n")[0] || "Error";
-				text = summaryLine(expanded ? info.errorText : firstLine);
+				text = summaryLine(expanded ? info.errorText : firstLine, { theme, style: "error" });
 			} else {
 				const badges: string[] = [`edited +${stats.added} -${stats.removed}`];
 				if (info.semanticBadge) badges.push(info.semanticBadge.replace(/^✓\s*/, ""));
 				if (info.warningsBadge) badges.push(info.warningsBadge);
-				text = summaryLine(badges.join(" • "), { hidden: !!diffData && !expanded });
+				text = summaryLine(badges.join(" • "), { hidden: !!diffData && !expanded, theme, style: "success" });
 				if (expanded && diffData) {
 					return upsertDiffComponent(context.lastComponent, { prefixLines: text.split("\n"), diffData, theme, expanded: true });
 				}

package/src/grep.ts

@@ -19,7 +19,7 @@ import { resolveToCwd } from "./path-utils.js";
 import { throwIfAborted } from "./runtime.js";
 import { formatGrepCallText, formatGrepResultText, GREP_TRUNCATION_THRESHOLD } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkedPathLine, linkToolPath, renderErrorResult, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 import type { FileAnchoredCallback } from "./tool-types.js";
 import { optionalIntOrString, registerReadSeekTool } from "./register-tool.js";
 import { searchPathParam } from "./readseek-params.js";
@@ -554,12 +554,12 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return renderPendingResult("pending grep", width);
+			if (isPartial) return renderPendingResult("pending grep", width, theme);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 
-			if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
+			if (isError || result.isError) return renderErrorResult(textContent, { expanded, width, theme });
 
 			const readSeekValue = (result.details as any)?.readSeekValue as {
 				tool: "grep";
@@ -583,17 +583,21 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 				hasBinaryWarning,
 			});
 
-			if (info.noMatches && !hasBinaryWarning) return new Text(summaryLine("no matches"), 0, 0);
+			if (info.noMatches && !hasBinaryWarning) return new Text(summaryLine("no matches", { theme, style: "dim" }), 0, 0);
 			const matchCount = readSeekValue?.totalMatches ?? 0;
 			const matchWord = matchCount === 1 ? "match" : "matches";
-			let text = summaryLine(`${matchCount} ${matchWord} returned`, { hidden: !!textContent && !expanded });
+			let text = summaryLine(`${matchCount} ${matchWord} returned`, {
+				hidden: !!textContent && !expanded,
+				theme,
+				style: "success",
+			});
 			for (const badge of info.badges) text += theme.fg(badge.startsWith("⚠") ? "warning" : "dim", `  ${badge}`);
 			if (expanded && readSeekValue?.records) {
 				const fileCounts = new Map<string, number>();
 				for (const r of readSeekValue.records) if (r.path && r.kind === "match") fileCounts.set(r.path, (fileCounts.get(r.path) ?? 0) + 1);
 				for (const [filePath, count] of [...fileCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 20)) {
 					const display = path.relative(cwd, filePath) || filePath;
-					text += "\n" + theme.fg("dim", `  ${display} (${count})`);
+					text += `\n${linkedPathLine(theme, filePath, display, cwd, ` (${count})`, width)}`;
 				}
 				if (fileCounts.size > 20) text += "\n" + theme.fg("muted", `  … and ${fileCounts.size - 20} more files`);
 			}

package/src/hover.ts

@@ -11,7 +11,7 @@ import { formatFsError } from "./fs-error.js";
 import { classifyReadSeekFailure, readSeekIdentify } from "./readseek-client.js";
 import { filePathParam, registerReadSeekTool } from "./register-tool.js";
 
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderErrorResult, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 
 const HOVER_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/hover.md", import.meta.url),
@@ -112,18 +112,26 @@ export function registerHoverTool(pi: ExtensionAPI) {
 			return new Text(clampLineToWidth(text, context.width), 0, 0);
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-			const { isPartial, isError, width } = resolveRenderResultContext(options, rest);
+			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return renderPendingResult("pending hover", width);
+			if (isPartial) return renderPendingResult("pending hover", width, theme);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 
 			if (isError || result.isError) {
-			return new Text(textContent || "hover failed", 0, 0);
+				return renderErrorResult(textContent, { expanded, width, fallback: "hover failed", theme });
 			}
 
-		return new Text(textContent.split("\n")[0] || "", 0, 0);
+			const output = (result.details as any)?.readSeekValue?.output;
+			const label = output?.identifier?.text
+				? `identified ${output.identifier.text}`
+				: output?.symbol?.name
+					? `symbol ${output.symbol.name}`
+					: "identified cursor";
+			let text = summaryLine(label, { hidden: !!textContent && !expanded, theme, style: "success" });
+			if (expanded && textContent) text += `\n${textContent}`;
+			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},
 	});
 }

package/src/read.ts

@@ -2,7 +2,6 @@ import { readFile as fsReadFile } from "node:fs/promises";
 
 import type { ExtensionAPI, ToolRenderResultOptions, AgentToolResult } from "@earendil-works/pi-coding-agent";
 import {
-	createReadTool,
 	truncateHead,
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
@@ -26,7 +25,7 @@ import { buildReadOutput } from "./read-output.js";
 
 import { buildLocalBundle } from "./read-local-bundle.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
-import { readSeekRead, readSeekDetect, readSeekImage, type ReadSeekDetection } from "./readseek-client.js";
+import { readSeekRead, readSeekDetect, readSeekImage, readSeekPdf, readSeekPreparedImage, type ReadSeekDetection, type ReadSeekPdfOutput } from "./readseek-client.js";
 import { formatReadCallText, formatReadResultText } from "./read-render-helpers.js";
 import { resolveReadSeekImageMode } from "./readseek-settings.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, renderToolLabel, resolveRenderResultContext, summaryLine, wrapReadHashlinesForWidthCached } from "./tui-render-utils.js";
@@ -41,6 +40,7 @@ interface ReadParams {
 	symbol?: string;
 	map?: boolean;
 	bundle?: string;
+	image?: "none" | "ocr" | "caption" | "objects";
 }
 
 interface ReadToolOptions {
@@ -55,8 +55,6 @@ export interface ExecuteReadOptions {
 	onUpdate: any;
 	cwd: string;
 	onSuccessfulRead?: FileAnchoredCallback;
-	/** Whether the active model accepts image input natively. Used when imageMode is auto. */
-	modelSupportsImages?: boolean;
 }
 
 function hasReadAnchors(result: AgentToolResult<any>): boolean {
@@ -82,8 +80,32 @@ function formatImageAnalysis(detection: ReadSeekDetection): string | undefined {
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
 
+function formatPdfAnalysis(pdf: ReadSeekPdfOutput): string {
+	const sections = [pdf.markdown.trimEnd()];
+	for (const image of pdf.images) {
+		const details: string[] = [];
+		const ocr = image.ocr?.trim();
+		if (ocr) details.push(`OCR text:\n${ocr}`);
+		const caption = image.caption?.trim();
+		if (caption) details.push(`Caption:\n${caption}`);
+		if (image.objects?.length) {
+			const lines = image.objects.map((object) => `- ${object.label} [${object.bbox.join(", ")}]`);
+			details.push(`Detected objects:\n${lines.join("\n")}`);
+		}
+		if (details.length > 0) sections.push(`PDF page ${image.page} image:\n${details.join("\n\n")}`);
+	}
+	return sections.filter(Boolean).join("\n\n");
+}
+
+function skippedVisualFile(path: string): AgentToolResult<any> {
+	return {
+		content: [{ type: "text", text: `[Skipped image/PDF: ${path}; no image mode selected]` }],
+		details: {},
+	};
+}
+
 export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolResult<any>> {
-	const { toolCallId, params, signal, onUpdate, cwd, onSuccessfulRead } = opts;
+	const { params, signal, cwd, onSuccessfulRead } = opts;
 	await ensureHashInit();
 	const rawParams = params as ReadParams;
 	const offset = coerceObviousBase10Int(rawParams.offset, "offset");
@@ -165,41 +187,82 @@ export async function executeRead(opts: ExecuteReadOptions): Promise<AgentToolRe
 	}
 
 	const hasBinaryContent = looksLikeBinary(rawBuffer);
-	if (hasBinaryContent) {
+	const hasPdfHeader = rawBuffer.subarray(0, 1024).includes(Buffer.from("%PDF-"));
+	if (hasBinaryContent || ext === "pdf" || hasPdfHeader) {
 		let detection: ReadSeekDetection | undefined;
 		try {
 			detection = await readSeekDetect(absolutePath, { signal });
 		} catch {
+			return buildToolErrorResult("read", "read-error", `Visual file detection failed for ${absolutePath}.`, {
+				path: rawParams.path,
+			});
+		}
+		if (!detection) {
+			return buildToolErrorResult("read", "read-error", `Visual file detection returned no data for ${absolutePath}.`, {
+				path: rawParams.path,
+			});
 		}
-		if (detection?.kind === "image") {
-			const builtinRead = createReadTool(cwd);
-			const builtinResult = await builtinRead.execute(toolCallId, p, signal, onUpdate);
+		if (detection.kind === "image" || detection.type === "application/pdf") {
 			const imageMode = resolveReadSeekImageMode();
-			const shouldRunVision = imageMode === "force" || (imageMode === "auto" && !opts.modelSupportsImages);
-			if (!shouldRunVision) return succeed(builtinResult);
+			if (imageMode === "off" || p.image === undefined) {
+				return skippedVisualFile(rawParams.path);
+			}
+			if (imageMode === "on" && p.image === "none") {
+				return buildToolErrorResult("read", "invalid-params-combo", 'image="none" is only available when imageMode is "auto".', {
+					path: rawParams.path,
+				});
+			}
+			if (p.image === "none") {
+				try {
+					if (detection.kind === "pdf") {
+						const pdf = await readSeekPdf(absolutePath, p.image, { signal });
+						const content: AgentToolResult<any>["content"] = [{ type: "text", text: pdf.markdown }];
+						for (const image of pdf.images) {
+							if (image.encoding !== "base64" || image.data === undefined) continue;
+							content.push({ type: "text", text: `[PDF page ${image.page} image]` });
+							content.push({ type: "image", data: image.data, mimeType: image.mime });
+						}
+						return succeed({ content, details: {} });
+					}
+					const image = await readSeekPreparedImage(absolutePath, { signal });
+					return succeed({
+						content: [{ type: "image" as const, data: image.data, mimeType: image.mime }],
+						details: {},
+					});
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return buildToolErrorResult("read", "read-error", `Image preprocessing unavailable: ${message}`, {
+						path: rawParams.path,
+					});
+				}
+			}
 
 			try {
-				const ocrDetection = await readSeekImage(absolutePath, ["ocr", "caption", "objects"], { signal });
-				const imageAnalysis = formatImageAnalysis(ocrDetection);
+				if (detection.kind === "pdf") {
+					const pdf = await readSeekPdf(absolutePath, p.image, { signal });
+					return succeed({
+						content: [{ type: "text" as const, text: formatPdfAnalysis(pdf) }],
+						details: {},
+					});
+				}
+				const analysis = await readSeekImage(absolutePath, [p.image], { signal });
+				const imageAnalysis = formatImageAnalysis(analysis);
 				if (imageAnalysis) {
 					return succeed({
-						...builtinResult,
-						content: [
-							...(builtinResult.content ?? []),
-							{ type: "text" as const, text: imageAnalysis },
-						],
+						content: [{ type: "text" as const, text: imageAnalysis }],
+						details: {},
 					});
 				}
-			} catch {
-				return succeed({
-					...builtinResult,
-					content: [
-						...(builtinResult.content ?? []),
-						{ type: "text" as const, text: "[Warning: local image analysis unavailable — showing image attachment only]" },
-					],
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				const label = detection.kind === "pdf" ? "PDF" : "Image";
+				return buildToolErrorResult("read", "read-error", `${label} analysis unavailable: ${message}`, {
+					path: rawParams.path,
 				});
 			}
-			return succeed(builtinResult);
+			return buildToolErrorResult("read", "read-error", "Image analysis returned no content.", {
+				path: rawParams.path,
+			});
 		}
 	}
 	throwIfAborted(signal);
@@ -457,6 +520,8 @@ function splitReadSeekLines(text: string): string[] {
 
 export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}) {
 	const name = options.name ?? "readSeek_read";
+	const imageMode = resolveReadSeekImageMode();
+	const imageModes = imageMode === "auto" ? ["none", "ocr", "caption", "objects"] as const : ["ocr", "caption", "objects"] as const;
 	const promptMetadata = defineToolPromptMetadata({
 		promptUrl: new URL("../prompts/read.md", import.meta.url),
 		promptSnippet: "Read files or images with anchors, maps, symbols, and OCR",
@@ -467,7 +532,12 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		label: "Read",
 		description: promptMetadata.description,
 		promptSnippet: promptMetadata.promptSnippet,
-		promptGuidelines: promptMetadata.promptGuidelines,
+		promptGuidelines: [
+			...promptMetadata.promptGuidelines,
+			imageMode === "off"
+				? "Image and PDF reads are disabled."
+				: `For an image or PDF, explicitly choose image: ${imageModes.join(", ")}; omitting image skips the file.`,
+		],
 		parameters: Type.Object({
 			path: filePathParam(),
 			offset: optionalIntOrString("Start line (1-indexed)"),
@@ -479,6 +549,13 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 					description: "Include same-file local support",
 				}),
 			),
+			...(imageMode === "off"
+				? {}
+				: {
+						image: Type.Optional(Type.Union(imageModes.map((mode) => Type.Literal(mode)), {
+							description: `Image/PDF mode: ${imageModes.join(", ")}. Must be selected explicitly.`,
+						})),
+					}),
 		}),
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			return executeRead({
@@ -488,7 +565,6 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 				onUpdate,
 				cwd: ctx.cwd,
 				onSuccessfulRead: options.onSuccessfulRead,
-				modelSupportsImages: ctx.model?.input.includes("image") ?? false,
 			});
 		},
 		renderCall(args: any, theme: any, ...rest: any[]) {
@@ -509,20 +585,28 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
 			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
-			if (isPartial) return renderPendingResult("pending read", width);
+			if (isPartial) return renderPendingResult("pending read", width, theme);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
 			if (isError || result.isError) {
 				const firstLine = textContent.split("\n")[0] || "Error";
 				const errorText = expanded ? (textContent || firstLine) : firstLine;
-				return new Text(clampLinesToWidth([summaryLine(errorText)], width).join("\n"), 0, 0);
+				return new Text(clampLinesToWidth([summaryLine(errorText, { theme, style: "error" })], width).join("\n"), 0, 0);
 			}
 
 			const readSeekValue = (result.details as any)?.readSeekValue as { range: { startLine: number; endLine: number; totalLines: number }; truncation: any; symbol: any; map: any; warnings: ReadSeekWarning[] } | undefined;
 			if (!readSeekValue) {
 				const lines = textContent.split("\n").filter(Boolean).length || textContent.split("\n").length;
-				return new Text(summaryLine(`loaded ${lines} ${lines === 1 ? "line" : "lines"}`, { hidden: !!textContent && !expanded }), 0, 0);
+				return new Text(
+					summaryLine(`loaded ${lines} ${lines === 1 ? "line" : "lines"}`, {
+						hidden: !!textContent && !expanded,
+						theme,
+						style: "success",
+					}),
+					0,
+					0,
+				);
 			}
 
 			const info = formatReadResultText({ range: readSeekValue.range, truncation: readSeekValue.truncation, symbol: readSeekValue.symbol, map: readSeekValue.map, warnings: readSeekValue.warnings });
@@ -532,7 +616,7 @@ export function registerReadTool(pi: ExtensionAPI, options: ReadToolOptions = {}
 			if (info.symbolBadge) summaryParts.push(info.symbolBadge);
 			for (const badge of info.badges) summaryParts.push(badge);
 			const summary = summaryParts.join(" • ");
-			let text = summaryLine(summary, { hidden: !!textContent && !expanded });
+			let text = summaryLine(summary, { hidden: !!textContent && !expanded, theme, style: "success" });
 			if (expanded && textContent) text += "\n" + wrapReadHashlinesForWidthCached(content, textContent, width);
 			return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
 		},

package/src/readseek-client.ts

@@ -118,6 +118,32 @@ export interface ReadSeekDetectedObject {
 
 export type ReadSeekImageMode = "ocr" | "caption" | "objects";
 
+export interface ReadSeekPreparedImage {
+	mime: string;
+	encoding: "base64";
+	data: string;
+}
+
+export interface ReadSeekPdfImage {
+	page: number;
+	width: number;
+	height: number;
+	mime: string;
+	mode: "none" | ReadSeekImageMode;
+	encoding?: "base64";
+	data?: string;
+	ocr?: ReadSeekOcrText;
+	caption?: string;
+	objects?: ReadSeekDetectedObject[];
+}
+
+export interface ReadSeekPdfOutput {
+	format: "pdf";
+	pages: number;
+	markdown: string;
+	images: ReadSeekPdfImage[];
+}
+
 export type ReadSeekDetection =
 	| {
 			kind: "source";
@@ -138,6 +164,8 @@ export type ReadSeekDetection =
 			width: number;
 			height: number;
 			animated: boolean;
+			encoding?: "base64";
+			data?: string;
 			ocr?: ReadSeekOcrText;
 			caption?: string;
 			objects?: ReadSeekDetectedObject[];
@@ -147,6 +175,14 @@ export type ReadSeekDetection =
 			type: string;
 			file: string;
 			mime?: string;
+		}
+	| {
+			kind: "pdf";
+			type: "application/pdf";
+			file: string;
+			mime?: string;
+			format: "pdf";
+			pages: number;
 		};
 
 type ReadSeekImageDetection = Extract<ReadSeekDetection, { kind: "image" }>;
@@ -219,6 +255,7 @@ function readSeekPackageDir(): string {
 
 const READSEEK_PLATFORM_PACKAGES: Record<string, string> = {
 	"darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
+	"linux-arm64": "@jarkkojs/readseek-linux-arm64",
 	"linux-x64": "@jarkkojs/readseek-linux-x64",
 	"win32-x64": "@jarkkojs/readseek-win32-x64",
 };
@@ -725,7 +762,18 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 	// carry `format`/`width`/`height`/`animated`; source detections carry
 	// `language`. Text and binary are byte-identical on the wire and collapse
 	// to the text variant.
-	if (output.format !== undefined || output.width !== undefined || output.height !== undefined) {
+	if (type === "application/pdf") {
+		if (output.format !== "pdf") throw new Error("invalid readseek PDF format");
+		return {
+			kind: "pdf",
+			type,
+			file,
+			mime,
+			format: output.format,
+			pages: requireNumber(output.pages, "pages"),
+		};
+	}
+	if (output.width !== undefined || output.height !== undefined) {
 		return {
 			kind: "image",
 			type,
@@ -735,6 +783,8 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 			width: requireNumber(output.width, "width"),
 			height: requireNumber(output.height, "height"),
 			animated: requireBoolean(output.animated, "animated"),
+			encoding: output.encoding === undefined ? undefined : parseImageEncoding(output.encoding),
+			data: output.data === undefined ? undefined : requireString(output.data, "data"),
 			ocr: parseOcrText(output.ocr),
 			caption: optionalString(output.caption, "caption"),
 			objects: parseDetectedObjects(output.objects),
@@ -755,6 +805,11 @@ function parseDetectOutput(value: unknown): ReadSeekDetection {
 	return { kind: "text", type, file, mime };
 }
 
+function parseImageEncoding(value: unknown): "base64" {
+	if (value === "base64") return value;
+	throw new Error("invalid image encoding");
+}
+
 export async function readSeekDetect(
 	filePath: string,
 	options: { signal?: AbortSignal } = {},
@@ -799,6 +854,58 @@ export async function readSeekImage(
 	throw new Error(`readseek returned no image analysis for ${filePath}`);
 }
 
+export async function readSeekPreparedImage(
+	filePath: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadSeekPreparedImage> {
+	const output = parseDetectOutput(await runReadSeek(["read", "--image", "none", filePath], { signal: options.signal }));
+	if (output.kind !== "image" || output.encoding !== "base64" || output.data === undefined || output.mime === undefined) {
+		throw new Error(`readseek returned no prepared image for ${filePath}`);
+	}
+	return { mime: output.mime, encoding: output.encoding, data: output.data };
+}
+
+function parsePdfImage(value: unknown): ReadSeekPdfImage {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek PDF image");
+	const image = value as Record<string, unknown>;
+	const mode = requireString(image.mode, "PDF image.mode");
+	if (mode !== "none" && mode !== "ocr" && mode !== "caption" && mode !== "objects") {
+		throw new Error("invalid readseek PDF image.mode");
+	}
+	return {
+		page: requireNumber(image.page, "PDF image.page"),
+		width: requireNumber(image.width, "PDF image.width"),
+		height: requireNumber(image.height, "PDF image.height"),
+		mime: requireString(image.mime, "PDF image.mime"),
+		mode,
+		encoding: image.encoding === undefined ? undefined : parseImageEncoding(image.encoding),
+		data: optionalString(image.data, "PDF image.data"),
+		ocr: parseOcrText(image.ocr),
+		caption: optionalString(image.caption, "PDF image.caption"),
+		objects: parseDetectedObjects(image.objects),
+	};
+}
+
+function parsePdfOutput(value: unknown): ReadSeekPdfOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek PDF output");
+	const output = value as Record<string, unknown>;
+	if (output.format !== "pdf" || !Array.isArray(output.images)) throw new Error("invalid readseek PDF output");
+	return {
+		format: output.format,
+		pages: requireNumber(output.pages, "PDF pages"),
+		markdown: requireString(output.markdown, "PDF markdown"),
+		images: output.images.map(parsePdfImage),
+	};
+}
+
+export async function readSeekPdf(
+	filePath: string,
+	mode: "none" | ReadSeekImageMode,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadSeekPdfOutput> {
+	return parsePdfOutput(await runReadSeek(["read", "--image", mode, filePath], { signal: options.signal }));
+}
+
 // --- Rename ---
 
 export interface RenameConflict {

package/src/readseek-settings.ts

@@ -2,7 +2,7 @@ import { readFileSync, statSync, type Stats } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-export type ReadSeekImageAnalysisMode = "force" | "off" | "auto";
+export type ReadSeekImageAnalysisMode = "on" | "off" | "auto";
 export type ReadSeekSyntaxValidationMode = "warn" | "block" | "off";
 interface ReadSeekGrepSettings {
   maxLines?: number;
@@ -106,8 +106,7 @@ function readImageMode(
 ): ReadSeekImageAnalysisMode | undefined {
   if (!("imageMode" in raw)) return undefined;
   const val = raw.imageMode;
-  if (val === "on") return "force";
-  if (val === "force" || val === "off" || val === "auto") return val;
+  if (val === "on" || val === "off" || val === "auto") return val;
   warnings.push(invalid(source, "readseek.imageMode"));
   return undefined;
 }
@@ -252,7 +251,7 @@ export function resolveReadSeekJsonSettings(): ReadSeekSettingsResult {
 }
 
 export function resolveReadSeekImageMode(): ReadSeekImageAnalysisMode {
-  return resolveReadSeekJsonSettings().settings.imageMode ?? "force";
+  return resolveReadSeekJsonSettings().settings.imageMode ?? "auto";
 }
 
 export function resolveReadSeekSyntaxValidation(): ReadSeekSyntaxValidationMode | undefined {

package/src/rename.ts

@@ -9,7 +9,7 @@ import { resolveToCwd } from "./path-utils.js";
 import { classifyReadSeekFailure, readSeekRename, type RenameOutput } from "./readseek-client.js";
 import { filePathParam, registerReadSeekTool } from "./register-tool.js";
 
-import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import { clampLineToWidth, clampLinesToWidth, linkedPathLine, linkToolPath, renderErrorResult, renderPendingResult, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
 
 const RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/rename.md", import.meta.url),
@@ -121,16 +121,15 @@ export function registerRenameTool(pi: ExtensionAPI) {
 			const context = rest[0] ?? {};
 			const cwd = context.cwd ?? process.cwd();
 			const displayPath = typeof args?.path === "string" ? args.path : "?";
-			const oldName = typeof args?.to === "string" ? "" : "";
 			let text = theme.fg("toolTitle", theme.bold("rename"));
 			text += ` ${linkToolPath(theme.fg("accent", displayPath), displayPath, cwd)}`;
 			if (args?.to) text += theme.fg("dim", ` → ${args.to}`);
 			return new Text(clampLineToWidth(text, context.width), 0, 0);
 		},
 		renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
-			const { isPartial, isError, expanded, width } = resolveRenderResultContext(options, rest);
+			const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-			if (isPartial) return renderPendingResult("pending rename", width);
+			if (isPartial) return renderPendingResult("pending rename", width, theme);
 
 			const content = result.content?.[0];
 			const textContent = content?.type === "text" ? content.text : "";
@@ -138,21 +137,29 @@ export function registerRenameTool(pi: ExtensionAPI) {
 			const output = readSeekValue?.output as RenameOutput | undefined;
 
 			if (isError || result.isError) {
-			return new Text(textContent || "rename failed", 0, 0);
+				return renderErrorResult(textContent, { expanded, width, fallback: "rename failed", theme });
 			}
 
-		let text = summaryLine(
-			output?.applied
+			const outputs = output ? [output, ...output.others] : [];
+			const editCount = outputs.reduce((total, file) => total + file.edits.length, 0);
+			const conflictCount = outputs.reduce((total, file) => total + file.conflicts.length, 0);
+			const fileCount = outputs.length;
+			const action = output?.applied
 				? `renamed ${output.old_name} → ${output.new_name}`
-				: `rename plan for ${output?.old_name ?? "?"} → ${output?.new_name ?? "?"} (dry-run)`,
-		);
+				: `rename plan for ${output?.old_name ?? "?"} → ${output?.new_name ?? "?"} (dry-run)`;
+			const details = output
+				? ` • ${editCount} ${editCount === 1 ? "edit" : "edits"} in ${fileCount} ${fileCount === 1 ? "file" : "files"}`
+				: "";
+			const conflicts = conflictCount > 0 ? ` • ${conflictCount} ${conflictCount === 1 ? "conflict" : "conflicts"}` : "";
+			let text = summaryLine(`${action}${details}${conflicts}`, {
+				theme,
+				style: conflictCount > 0 ? "warning" : "success",
+			});
 
 			if (expanded && output) {
-				const files = new Set<string>();
-				files.add(output.file);
-				for (const o of output.others) files.add(o.file);
-				for (const f of files) {
-					text += `\n  ${f}`;
+				for (const file of outputs) {
+					const display = path.relative(cwd, file.file) || file.file;
+					text += `\n${linkedPathLine(theme, file.file, display, cwd, ` (${file.edits.length} edits)`, width)}`;
 				}
 			}
 

package/src/tool-prompt-metadata.ts

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
 const COMPACT_DESCRIPTIONS: Record<string, string> = {
-  "read.md": "Read text files/images by path; text has LINE:HASH anchors, images return the attachment plus OCR text, a caption, and detected objects.",
+  "read.md": "Read text files, images, or PDFs by path; text has LINE:HASH anchors and visual files require an explicit image mode.",
   "edit.md": "Edit existing text files using fresh LINE:HASH anchors from readSeek_read, readSeek_grep, readSeek_search, or readSeek_write.",
   "grep.md": "Search file contents; non-summary results include LINE:HASH anchors for edits.",
 
@@ -38,7 +38,7 @@ const REPLACEABLE_TOOL_GUIDELINES: Record<string, { readSeekName: string; builtI
 const COMPACT_GUIDELINES: Record<string, string[]> = {
   "read.md": [
     "Use readSeek_read map or symbol mode before pulling large code files into context.",
-    "Use readSeek_read for images; it returns the image attachment plus OCR text, a caption, and detected objects.",
+    "For images and PDFs, explicitly choose one of the image modes exposed by readSeek_read.",
   ],
   "edit.md": [
     "With readSeek_edit, prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical.",

package/src/tui-render-utils.ts

@@ -28,12 +28,30 @@ export function linkToolPath(styledText: string, rawPath: string, cwd: string):
   }
 }
 
+export function linkedPathLine(
+  theme: RendererTheme,
+  rawPath: string,
+  displayPath: string,
+  cwd: string,
+  suffix: string,
+  width: number | undefined,
+): string {
+  const pathWidth = width === undefined ? undefined : Math.max(1, width - 2 - visibleWidth(suffix));
+  const visiblePath = pathWidth === undefined ? displayPath : truncateToWidth(displayPath, pathWidth);
+  const linkedPath = linkToolPath(theme.fg("dim", visiblePath), rawPath, cwd);
+  return `  ${linkedPath}${theme.fg("dim", suffix)}`;
+}
+
 export function appendExpandHint(text: string, hidden: boolean): string {
   return hidden ? `${text}${EXPAND_HINT}` : text;
 }
 
-export function summaryLine(summary: string, options: { hidden?: boolean } = {}): string {
-  return appendExpandHint(`${SUMMARY_PREFIX} ${summary}`, !!options.hidden);
+export function summaryLine(
+  summary: string,
+  options: { hidden?: boolean; theme?: RendererTheme; style?: string } = {},
+): string {
+  const prefix = options.theme ? options.theme.fg(options.style ?? "dim", SUMMARY_PREFIX) : SUMMARY_PREFIX;
+  return appendExpandHint(`${prefix} ${summary}`, !!options.hidden);
 }
 
 export function isRendererExpanded(options?: { expanded?: boolean }, context?: { expanded?: boolean }): boolean {
@@ -172,8 +190,8 @@ export function wrapReadHashlinesForWidthCached(
 /**
  * Render the `isPartial` placeholder line shared by every tool's `renderResult`.
  */
-export function renderPendingResult(pendingLabel: string, width: number | undefined): Text {
-  return new Text(clampLinesToWidth([summaryLine(pendingLabel)], width).join("\n"), 0, 0);
+export function renderPendingResult(pendingLabel: string, width: number | undefined, theme?: RendererTheme): Text {
+  return new Text(clampLinesToWidth([summaryLine(pendingLabel, { theme, style: "muted" })], width).join("\n"), 0, 0);
 }
 
 /**
@@ -183,11 +201,15 @@ export function renderPendingResult(pendingLabel: string, width: number | undefi
  */
 export function renderErrorResult(
   textContent: string,
-  options: { expanded: boolean; width: number | undefined; fallback?: string },
+  options: { expanded: boolean; width: number | undefined; fallback?: string; theme?: RendererTheme },
 ): Text {
   const firstLine = textContent.split("\n")[0] || (options.fallback ?? "Error");
   const body = options.expanded && textContent ? textContent : firstLine;
-  return new Text(clampLinesToWidth(summaryLine(body).split("\n"), options.width).join("\n"), 0, 0);
+  return new Text(
+    clampLinesToWidth(summaryLine(body, { theme: options.theme, style: "error" }).split("\n"), options.width).join("\n"),
+    0,
+    0,
+  );
 }
 
 export interface AnchoredFilesLabels {
@@ -232,27 +254,31 @@ export function renderAnchoredFilesResult(
 ): Text {
   const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
 
-  if (isPartial) return renderPendingResult(labels.pendingLabel, width);
+  if (isPartial) return renderPendingResult(labels.pendingLabel, width, theme);
 
   const content = result.content?.[0];
   const textContent = content?.type === "text" ? content.text : "";
-  if (isError || result.isError) return renderErrorResult(textContent, { expanded, width });
+  if (isError || result.isError) return renderErrorResult(textContent, { expanded, width, theme });
 
   const readSeekValue = (result.details as any)?.readSeekValue as
     | { files: Array<{ path: string; lines: any[] }> }
     | undefined;
   const files = readSeekValue?.files ?? [];
-  if (files.length === 0) return new Text(summaryLine(labels.emptyLabel), 0, 0);
+  if (files.length === 0) return new Text(summaryLine(labels.emptyLabel, { theme, style: "dim" }), 0, 0);
 
   const fileCount = files.length;
   const total = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
   const unitWord = total === 1 ? labels.unitSingular : labels.unitPlural;
   const fileWord = fileCount === 1 ? "file" : "files";
-  let text = summaryLine(`${total} ${unitWord} in ${fileCount} ${fileWord}`, { hidden: !expanded });
+  let text = summaryLine(`${total} ${unitWord} in ${fileCount} ${fileWord}`, {
+    hidden: !expanded,
+    theme,
+    style: "success",
+  });
   if (expanded) {
     for (const file of files.slice(0, 20)) {
       const display = relative(cwd, file.path) || file.path;
-      text += "\n" + theme.fg("dim", `  ${display} (${file.lines.length})`);
+      text += `\n${linkedPathLine(theme, file.path, display, cwd, ` (${file.lines.length})`, width)}`;
     }
     if (files.length > 20) text += "\n" + theme.fg("muted", `  … and ${files.length - 20} more files`);
   }

package/src/write.ts

@@ -322,11 +322,11 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
     },
     renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
       const { isPartial, expanded, width, context } = resolveRenderResultContext(options, rest);
-      if (isPartial) return renderPendingResult("pending write", width);
+      if (isPartial) return renderPendingResult("pending write", width, theme);
       const details = result.details ?? {};
       const output = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (result.isError || details.readSeekValue?.ok === false) {
-        return renderErrorResult(output, { expanded, width, fallback: "write failed" });
+        return renderErrorResult(output, { expanded, width, fallback: "write failed", theme });
       }
       const diffData = details.diffData;
       const state = details.writeState === "overwritten" ? "overwritten" : "created";
@@ -336,7 +336,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       if (state === "created") {
         const readSeekLines = (details.readSeekValue?.lines ?? []) as Array<{ raw: string }>;
         const hasContent = readSeekLines.length > 0;
-        const header = summaryLine(state, { hidden: hasContent && !expanded });
+        const header = summaryLine(state, { hidden: hasContent && !expanded, theme, style: "success" });
         const lines = header.split("\n");
         if (expanded && hasContent) {
           const content = readSeekLines.map((l) => l.raw).join("\n");
@@ -346,7 +346,7 @@ export function registerWriteTool(pi: ExtensionAPI, options: WriteToolOptions =
       }
       // Overwrite: the old vs new comparison still carries signal — keep the diff UI.
       const hasExpandableDiff = !!diffData;
-      let text = summaryLine(state, { hidden: hasExpandableDiff && !expanded });
+      let text = summaryLine(state, { hidden: hasExpandableDiff && !expanded, theme, style: "success" });
       if (expanded && hasExpandableDiff) {
         return upsertDiffComponent(context.lastComponent, { prefixLines: text.split("\n"), diffData, theme, expanded: true });
       }