@khanhicetea/pi-better-tool 0.2.2 → 0.2.4

package/README.md

@@ -1,16 +1,11 @@
 # pi-better-tool
 
-Better built-in tools for the [pi coding agent](https://github.com/earendil-works/pi-mono) — starting with an `edit` override that turns many failed edits into recoverable ones.
+Context-aware tools for the [Pi coding agent](https://github.com/earendil-works/pi-mono):
 
-## Why
-
-Pi's built-in `edit` requires every `edits[].oldText` to identify one non-overlapping region. When matching fails, this override returns bounded context that can make the next action safer:
-
-- **Ambiguous literal match after a bounded read** — selects an occurrence only when exactly one tracked literal occurrence is fully contained in the newest verified stored-context `read` of the same file.
-- **Other ambiguous matches** — reports bounded occurrence ranges and whole-line prefix/suffix expansions that are unique under edit matching.
-- **Text not found** — reports a bounded closest-region comparison. It gives direct-retry wording only when the exact candidate is unique, sufficiently similar, and meaningfully better than a distinct runner-up.
-
-Low-confidence, competing, stale, oversized, or omitted candidates tell the model to read the referenced range instead of retrying blindly.
+- **`edit`** replaces the built-in edit tool. Failures explain what failed, what was not written, and what to do next.
+- **`read_symbol`** reads a whole function, method, class, or type by containing line or exact name. With only a path, it gets a symbol outline.
+- **`read_code_imports`** reads the first dependency import zone as exact raw source lines, including comments and blank lines between adjacent imports.
+- **`read` stays unchanged** for ordinary text, images, and explicit line ranges.
 
 ## Install
 
@@ -18,127 +13,170 @@ Low-confidence, competing, stale, oversized, or omitted candidates tell the mode
 pi install npm:@khanhicetea/pi-better-tool
 ```
 
-For local development from this monorepo:
+From this monorepo:
 
 ```bash
 pi install /absolute/path/to/pi-kit/packages/pi-better-tool
 ```
 
-It is also registered in the root `package.json` under `pi.extensions`.
+The root `package.json` also registers the extension. After local changes, use `/reload` in Pi to load the new tool definition. After upgrading to a release that adds grammar packages, restart Pi once: ast-grep’s native language registry cannot be extended by `/reload` in an already-running process.
 
-## Example: ambiguous oldText
+## Read the symbol, not guessed line windows
 
-````text
-Found 2 occurrences of the text in dup.go. The text must be unique. Please provide more context to make it unique.
+After grep identifies a location:
 
-Occurrences:
-  1. lines 2-3
-  2. lines 6-7
+```json
+{"path":"src/server.ts","line":142}
+```
 
-Disambiguated oldText candidates are shown below when they fit safely. A fenced snippet can be reused exactly; an omitted snippet must be read from its referenced range first:
+Call `read_symbol` with an exact name instead:
 
-Occurrence 1 (lines 2-3) — minimum context: 0 lines before, 1 line after:
+```json
+{"path":"src/server.ts","symbol":"Server.handleRequest"}
 ```
-	log()
-}
 
-func second() {
-```
+Get the enclosing class or function:
 
-Tip: only fenced snippets explicitly presented as retryable should be copied into oldText.
+```json
+{"path":"src/server.ts","line":142,"parent":1}
+```
 
-No changes were written — the file was not modified.
-````
+Discover names and ranges without reading every body:
 
-## Example: competing closest matches
+```json
+{"path":"src/server.ts"}
+```
 
-````text
-Could not find the exact text in handlers.ts. The old text must match exactly including all whitespace and newlines.
+### Arguments
 
-Closest match in the file: lines 10-12 (~91% line similarity).
-...
-Candidate file content at lines 10-12 is not safe for a direct retry (a distinct candidate at lines 30-32 has a similar heuristic score (~90%)). Read and verify this range before editing.
-```
-function firstHandler() {
-	work();
-}
-```
+| Argument | Meaning |
+| --- | --- |
+| `path` | Local relative/absolute path; supports `@path`, `~/path`, and file URLs. |
+| `line` | 1-based file line. Select the innermost declaration containing it. |
+| `column` | Optional 1-based UTF-16 column with `line`, to distinguish same-line symbols. |
+| `symbol` | Exact, case-sensitive name or qualified name such as `Server.run`. Combine with `line` for duplicate names. |
+| `parent` | Move outward through enclosing declarations; default 0, maximum 20. |
+| `context` | Extra whole lines before/after the declaration; default 0, maximum 20. |
+| `offset` | 1-based position **within the selection**, not a file line. For an outline, the entry position. |
+| `limit` | Maximum source lines (default 1000) or outline entries (default 50); maximum 1800. |
 
-No changes were written — the file was not modified.
-````
+Omit both `line` and `symbol` for an outline. Named selection never silently chooses the first duplicate. Line selection never silently chooses between same-line siblings. Candidate lists include concrete calls with names and positions.
 
-Similarity scores are heuristics, not probabilities.
+### Languages and boundaries
 
-## Behavior and compatibility
+Syntax parsing uses Tree-sitter through `@ast-grep/napi`, not indentation or brace-counting guesses:
 
-The normal matching path follows Pi's built-in edit implementation:
+- JavaScript, JSX, TypeScript, TSX, and their module extensions
+- Bash-compatible shell scripts (`.sh`, `.bash`, `.zsh`, and related extensions)
+- C and C++ (including common header and CUDA/Arduino extensions)
+- C# and Java
+- Kotlin
+- PHP
+- Python and `.pyi`
+- Ruby (including `Gemfile` and `Rakefile`)
+- Rust
+- Swift
 
-- exact match first, then fuzzy fallback for trailing whitespace, smart quotes, dashes, Unicode compatibility forms, and Unicode spaces
-- uniqueness checked in fuzzy-normalized space
-- all edits matched against the original content rather than applied incrementally
-- overlap and no-change detection
-- CRLF restoration and UTF-8 BOM preservation
-- built-in-compatible success details (`details.diff`, `details.patch`, and `details.firstChangedLine`)
-- no custom renderers, so Pi's built-in edit renderer is inherited
+The reader handles named declarations, nested functions, JS/TS arrow functions and methods, Python decorators, Rust attributes, and containing classes/types. It includes export/declaration wrappers when applicable. It returns **whole source lines**, so a line can also contain adjacent code. It does not resolve imports, references, overload implementations, macros, or runtime bindings. Leading standalone comments are not automatically attached to a declaration.
 
-Intentional safety/compatibility differences are:
+Incomplete syntax, unsupported languages, unavailable parsers, and locations without declarations do not produce guessed symbol boundaries. Failures give a bounded source preview or candidate list and concrete next-call arguments. Missing paths include a bounded list of nearby files when the parent directory is accessible.
 
-- 1–100 edits are accepted per call; empty batches are rejected by the public schema
-- empty and fuzzy-normalized-empty `oldText` values are rejected
-- invalid UTF-8 and NUL-containing files are rejected rather than silently transcoded
-- conservative stored-read-based selection may resolve repeated literal text
-- self-overlapping string occurrences retain Pi's non-overlapping counting policy
+### Output and pagination
 
-The argument compatibility shim accepts `edits` as an array, JSON string, single edit object, or legacy top-level `oldText`/`newText`. Preparation is pure and idempotent.
+Results identify the selected symbol, enclosing names, full declaration range, displayed file range, and a SHA-256 source snapshot. Source appears in an unnumbered fenced block, so line-number prefixes cannot accidentally enter `oldText`.
 
-### Read-evidence boundary
+Large selections return a whole-line page, explicitly marked **partial**, with the complete next `read_symbol` arguments. Follow that continuation instead of calculating file offsets. Each call reads a fresh snapshot; do not combine pages whose snapshot hashes differ.
 
-Read evidence is taken from Pi's active, compaction-aware **stored session context**. Retained-tail messages are handled when the host exposes them. The newest same-file read must have a matching successful result and reproduce built-in read formatting for the current LF-normalized content. Missing, failed, malformed, or stale newest evidence blocks fallback to older intent.
+Limits:
 
-This is not proof of the final provider payload: another extension may remove messages in a `context` hook or rewrite the provider request. CRLF read output is intentionally compared after LF normalization, so this guarantee is content/format verification rather than literal byte identity. BOM-bearing read output is conservatively rejected because edit matching strips the BOM. Fuzzy/Unicode-equivalent ambiguity and highly repetitive files also fail closed.
+- Source analysis: 2 MiB UTF-8, 100,000 syntax nodes, 10,000 declarations, 1,024 characters per qualified symbol name.
+- Complete read output: 48 KiB / 1,950 lines, including metadata and fences.
+- No clipped copyable source lines or broken fences. A line too large to display gets preview/read guidance instead.
+- Invalid UTF-8, NUL-containing input, and non-regular files are rejected.
 
-### Local filesystem and commit guarantees
+Parser packages are runtime dependencies. Common platforms use prebuilt native binaries. If a grammar is unavailable on a platform, the tool gives read guidance; it never runs repository code, installs a compiler, or builds a grammar during a tool call. The edit tool can still work without loading symbol parsers.
 
-This override uses local Node.js filesystem operations. It does **not** inherit an SSH, container, sandbox, or other custom edit backend.
+## Read imports before editing them
 
-All replacements are analyzed before writing, so a matching/overlap/no-change/diagnostic failure starts no write. Immediately before writing, the tool performs a best-effort content and file-identity recheck to catch many external modifications.
+Call `read_code_imports` with a source path:
 
-The final write is still an in-place filesystem overwrite:
+```json
+{"path":"src/server.ts"}
+```
 
-- it is not a cross-process lock or race-free compare-and-swap
-- it is not rollback- or crash-safe filesystem atomicity
-- another process can modify the file after the pre-write check
-- a rejected write may leave the file unchanged, partially written, or fully written; inspect it before retrying
+The tool uses bounded regular-expression detection and returns the first contiguous import zone in an unnumbered source fence. It supports JavaScript/TypeScript, Python, Go, Rust, C/C++, C#, Java, Kotlin, PHP, Ruby, Swift, and shell files. It recognizes each language's common `import`, `include`, `use`, `require`, or `source` form, including common multiline forms.
 
-A resolved write is the tool's commit boundary. The extension returns the committed result rather than throwing a post-write cancellation error. A host may still suppress result delivery when cancelling the surrounding tool run; cancellation cannot roll back a completed filesystem write. Temporary-file/rename replacement is deliberately not used because it can replace symlinks, break hard-link semantics, or alter metadata without a carefully defined cross-platform policy.
+The result includes the exact file-line range and a SHA-256 snapshot. Comments and blank lines between adjacent imports remain in the raw output. The zone stops when code separates later import statements. The tool does not resolve dependencies, execute code, or claim syntax-level accuracy. Use `read` when conditional imports, generated files, uncommon macros, or unsupported syntax need more context.
 
-### Output and resource bounds
+## Recover from an edit failure in the next call
 
-Diagnostic text is kept below Pi's 50 KB / 2,000-line tool-output limits. Markdown snippets are added atomically so a fence is never cut; oversized snippets are omitted with read guidance. Success expansion is skipped for oversized files. Closest-match work has explicit query, line, and operation budgets and falls back to concise read guidance when exhausted.
+The `edit` input remains:
 
-`details.diff` and `details.patch` remain complete for renderer compatibility and are not blindly truncated as diagnostic text.
+```json
+{
+  "path": "src/server.ts",
+  "edits": [
+    { "oldText": "exact current text", "newText": "replacement text" }
+  ]
+}
+```
 
-## Host compatibility
+All entries match the **original file**, not the output of earlier entries. Matching/overlap failures apply none of the batch. Fix the reported entries and resubmit the **complete batch**.
 
-Pi's packaging guidance requires wildcard peer dependencies for Pi core packages. This package follows that guidance rather than bundling Pi. Version 0.2.1 is typechecked and tested against `@earendil-works/pi-coding-agent` 0.82.1; host upgrades should run the read-format, exported-helper, renderer-shape, and session-context compatibility tests.
+| Failure | Returned context |
+| --- | --- |
+| Repeated `oldText` | Occurrence ranges, bounded unique anchor expansions, and concrete context-read calls. |
+| Text not found | Closest-region comparison with original whitespace, likely causes, and exact retry text only when unique and clearly better than competing candidates. |
+| Overlapping entries | Both ranges plus a unique merged source anchor when it fits. Apply both intended changes to one `newText`. |
+| Empty anchor | Explain insertion anchoring and give a context-read call. |
+| No change | Explain that the output is identical; do not repeat the same call. |
+| Replacement already appears | Report its locations as a clue, not proof that the intended change is complete. |
 
-## Development
+A failed batch starts with, for example:
 
-```bash
-npm run check     # typecheck + tests
-npm test          # vitest only
+```text
+[edit failure: not-found]
+Batch status: 0/2 replacements written. Fix edits[1] and resubmit the complete batch against the original file; no earlier replacement was applied.
 ```
 
-## Publishing
+Only snippets explicitly presented as retryable may be copied directly into `oldText`. Low-confidence, competing, stale, oversized, or omitted candidates require verification. Suggested `read_symbol` calls get the enclosing source declaration without another search for its boundary. Similarity scores are heuristics, not probabilities.
 
-From the repository root:
+### Verified read evidence
+
+For repeated **literal** text, edit can select an occurrence only when exactly one tracked occurrence is fully contained in the newest verified same-file read result in Pi's active, compaction-aware **stored session context**.
+
+Both readers participate:
+
+- Built-in `read`: reproduce its current LF-normalized output and truncation format.
+- `read_symbol`: regenerate the result from the original arguments and current source. Snapshot, selection, envelope, and displayed source must all agree. Result `details` alone are never trusted.
+
+Only displayed source is evidence. Outline entries, unseen parts of partial symbols, and omitted final newline separators are not. The newest same-file failed, missing, malformed, or stale result blocks fallback to an older read. Retained-tail compaction messages are supported when the host exposes them. Canonical paths support symlink aliases.
+
+This verifies stored context, not the final provider payload: other extensions can remove messages or rewrite requests. Built-in BOM-bearing read output remains conservatively rejected; `read_symbol` deliberately strips a UTF-8 BOM and normalizes CRLF before parsing and snapshotting. Fuzzy-equivalent ambiguity and highly repetitive files fail closed.
+
+## Edit safety and compatibility
+
+The matching engine preserves exact-first/fuzzy-fallback behavior, fuzzy-space uniqueness, original-file batch matching, overlap/no-change checks, CRLF restoration, and UTF-8 BOM preservation. Success details keep Pi's `diff`, `patch`, and `firstChangedLine` shape; the built-in edit renderer is inherited.
+
+Intentional safeguards include 1–100 replacements per call, rejection of empty/fuzzy-empty anchors, and rejection of invalid UTF-8 or NUL-containing files. Self-overlapping strings retain Pi's non-overlapping occurrence-counting policy. The pure compatibility shim accepts array, JSON-string, single-object, and legacy top-level edit arguments.
+
+Both tools use the **local filesystem**. They do not inherit an SSH, container, or sandbox backend. File mutations use Pi's shared mutation queue. Immediately before writing, edit rechecks file identity and content to catch many external changes.
+
+The final write remains an **in-place overwrite**, not a cross-process lock, race-free compare-and-swap, or crash-safe atomic transaction. Another process can change a file after the check. A rejected write may leave the file unchanged, partially written, or fully written: inspect it before retrying. A resolved write is the commit boundary; later cancellation cannot roll it back. In-place writes preserve existing symlink/hard-link semantics.
+
+Edit diagnostics stay below Pi's 50 KiB / 2,000-line limits. Snippets are omitted atomically when needed, and similarity work is bounded. Renderer `details.diff` and `details.patch` remain complete rather than being blindly truncated.
+
+## Development
+
+Tested against `@earendil-works/pi-coding-agent` 0.82.1. Pi/typebox peer dependencies remain wildcard ranges, as Pi's packaging guidance requires. Re-run the read-format, session-evidence, and renderer compatibility tests on host upgrades.
 
 ```bash
-npm run check --workspace=@khanhicetea/pi-better-tool
-npm pack --dry-run --workspace=@khanhicetea/pi-better-tool
-npm publish --workspace=@khanhicetea/pi-better-tool
+npm run check --workspace @khanhicetea/pi-better-tool
+npm pack --dry-run --workspace @khanhicetea/pi-better-tool
 ```
 
+Tests cover existing edit behavior, recovery round-trips, syntax boundaries across languages, nested/duplicate symbols, pagination, encoding/size failures, cancellation, and read-to-edit evidence.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@khanhicetea/pi-better-tool",
-	"version": "0.2.2",
-	"description": "Better built-in tools for pi: an edit tool override that returns recovery context (closest match + disambiguation snippets) instead of bare failures",
+	"version": "0.2.4",
+	"description": "Context-aware tools for pi: safe edits, syntax-aware symbol reads, and raw source import-zone reads",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -13,8 +13,21 @@
 	"bugs": {
 		"url": "https://github.com/khanhicetea/pi-kit/issues"
 	},
-	"keywords": ["pi-package", "pi-extension", "edit", "tools"],
-	"files": ["src", "README.md", "LICENSE"],
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"edit",
+		"read",
+		"symbols",
+		"imports",
+		"tree-sitter",
+		"tools"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
 	"scripts": {
 		"test": "vitest run",
 		"typecheck": "tsc --noEmit",
@@ -33,12 +46,29 @@
 		"vitest": "^3.2.0"
 	},
 	"pi": {
-		"extensions": ["./src/index.ts"]
+		"extensions": [
+			"./src/index.ts"
+		]
 	},
 	"engines": {
 		"node": ">=20"
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"dependencies": {
+		"@ast-grep/lang-bash": "0.0.8",
+		"@ast-grep/lang-c": "0.0.6",
+		"@ast-grep/lang-cpp": "0.0.6",
+		"@ast-grep/lang-csharp": "0.0.6",
+		"@ast-grep/lang-go": "0.0.6",
+		"@ast-grep/lang-java": "0.0.7",
+		"@ast-grep/lang-kotlin": "0.0.7",
+		"@ast-grep/lang-php": "0.0.7",
+		"@ast-grep/lang-python": "0.0.6",
+		"@ast-grep/lang-ruby": "0.0.7",
+		"@ast-grep/lang-rust": "0.0.7",
+		"@ast-grep/lang-swift": "0.0.8",
+		"@ast-grep/napi": "0.45.3"
 	}
 }

package/src/diagnostics.ts

@@ -13,6 +13,7 @@
 
 import type { EditFailure, EditOp, LineRange } from "./apply.ts";
 import { normalizeEdits } from "./apply.ts";
+import { languageForPath } from "./symbols.ts";
 import { findClosestRegion, lineSimilarity, probeMatchCauses } from "./similarity.ts";
 import {
 	countFuzzyOccurrences,
@@ -134,7 +135,20 @@ export function formatAutoDisambiguationSuccess(
 }
 
 export function formatEditFailure(opts: FormatFailureOptions): string {
-	return boundCompleteOutput(formatEditFailureUnbounded(opts));
+	const { failure, edits } = opts;
+	const target = "editIndex" in failure ? `edits[${failure.editIndex}]` : failure.kind === "overlap" ? `edits[${failure.firstEditIndex}] and edits[${failure.secondEditIndex}]` : "the replacement text";
+	const batch = edits.length > 1
+		? `Batch status: 0/${edits.length} replacements written. Fix ${target} and resubmit the complete batch against the original file; no earlier replacement was applied.`
+		: "Write status: no changes were written by this call.";
+	return boundCompleteOutput(`[edit failure: ${failure.kind}]\n${batch}\n\n${formatEditFailureUnbounded(opts)}`);
+}
+
+/** Concrete next arguments prevent another call just to discover boundaries. */
+function nextContextCall(path: string, start: number, end = start): string {
+	const read = `read ${JSON.stringify({ path, offset: Math.max(1, start - 3), limit: Math.min(1800, end - start + 7) })}`;
+	return languageForPath(path)
+		? `Next context call: read_symbol ${JSON.stringify({ path, line: start })} for the enclosing symbol; or ${read} for exact line context.`
+		: `Next context call: ${read}.`;
 }
 
 function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
@@ -143,9 +157,7 @@ function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
 
 	switch (failure.kind) {
 		case "empty-old-text": {
-			return total === 1
-				? `oldText must not be empty in ${path}.`
-				: `edits[${failure.editIndex}].oldText must not be empty in ${path}.`;
+			return `${total === 1 ? "oldText" : `edits[${failure.editIndex}].oldText`} must not be empty in ${path}. Copy non-empty source text as the anchor; for insertion, retain that anchor in newText.\n${nextContextCall(path, 1)}`;
 		}
 
 		case "not-found": {
@@ -175,13 +187,19 @@ function formatEditFailureUnbounded(opts: FormatFailureOptions): string {
 
 		case "overlap": {
 			const { firstEditIndex, secondEditIndex, firstRange, secondRange } = failure;
-			return `edits[${firstEditIndex}] and edits[${secondEditIndex}] overlap in ${path} (edits[${firstEditIndex}] covers lines ${firstRange.start}-${firstRange.end}, edits[${secondEditIndex}] covers lines ${secondRange.start}-${secondRange.end}). Merge them into one edit or target disjoint regions.`;
+			const start = Math.min(firstRange.start, secondRange.start);
+			const end = Math.max(firstRange.end, secondRange.end);
+			const head = `edits[${firstEditIndex}] and edits[${secondEditIndex}] overlap in ${path} (edits[${firstEditIndex}] covers lines ${firstRange.start}-${firstRange.end}, edits[${secondEditIndex}] covers lines ${secondRange.start}-${secondRange.end}). Merge them into one edit or target disjoint regions.`;
+			const expansion = normalizedContent.length <= MAX_CONTENT_FOR_DIAGNOSTICS
+				? findMinimalUniqueExpansion(normalizedContent, normalizeForFuzzyMatch(normalizedContent), getLineSpans(normalizedContent), { start, end }) : null;
+			if (expansion && isSnippetRenderable(expansion.text)) {
+				return `${head}\n\nRetryable merged oldText at lines ${expansion.startLine}-${expansion.endLine}. Apply BOTH intended changes to this snippet in one newText; do not concatenate the previous replacements.\n${renderSnippet(expansion.text).join("\n")}`;
+			}
+			return `${head}\nMerged source snippet omitted or not unique. ${nextContextCall(path, start, end)}`;
 		}
 
 		case "no-change": {
-			return total === 1
-				? `No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`
-				: `No changes made to ${path}. The replacements produced identical content.`;
+			return `No changes made to ${path}. The replacement${total === 1 ? "" : "s"} produced identical content. Do not repeat the same call. If the intended change is already present, stop; otherwise change newText so it differs from the matched source.`;
 		}
 	}
 }
@@ -204,6 +222,7 @@ function formatAmbiguous(opts: FormatFailureOptions, failure: Extract<EditFailur
 	listed.forEach((offset, i) => {
 		const range = rangeFromOffset(fuzzySpans, offset, fuzzyOld.length);
 		lines.push(`  ${i + 1}. ${describeLines(range.start, range.end)}`);
+		lines.push(`     ${nextContextCall(opts.path, range.start, range.end)}`);
 	});
 	if (failure.occurrenceCount > listed.length) {
 		lines.push(`  … and ${failure.occurrenceCount - listed.length} more`);
@@ -345,6 +364,14 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 	const causes = probeMatchCauses(normalizedContent, oldText);
 
 	const lines: string[] = [];
+	const edit = "editIndex" in opts.failure ? normalizeEdits(opts.edits)[opts.failure.editIndex] : undefined;
+	if (edit?.newText && edit.newText !== oldText) {
+		const offsets = findAllOccurrences(normalizedContent, edit.newText, 4);
+		if (offsets.length) {
+			const spans = getLineSpans(normalizedContent);
+			lines.push(`Replacement text already appears at ${offsets.map((offset) => { const range = rangeFromOffset(spans, offset, edit.newText.length); return describeLines(range.start, range.end); }).join(", ")} (up to 4 shown). The change may already be applied; verify intent before choosing another target.`, "");
+		}
+	}
 	if (closest) {
 		lines.push(
 			`Closest match in the file: ${describeLines(closest.startLine, closest.endLine)} (~${Math.round(closest.score * 100)}% line similarity${closest.truncated ? `, compared against the first ${closest.totalOldLines} lines of your oldText` : ""}).`,
@@ -422,11 +449,14 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 				`Candidate file content at ${describeLines(closest.startLine, closest.endLine)} is not safe for a direct retry (${reasons.join("; ")}). Read and verify this range before editing.`,
 			);
 			if (safelyRenderable) lines.push(...renderSnippet(uniqueCandidate ?? candidate));
+			lines.push(nextContextCall(opts.path, closest.startLine, closest.endLine));
+			if (closest.competitor && competitorGap < MIN_DIRECT_RETRY_GAP) lines.push(nextContextCall(opts.path, closest.competitor.startLine, closest.competitor.endLine));
 		}
 
 	} else {
 		lines.push("No reliable similar region was found within the bounded diagnostic search.");
 		lines.push("If you expected this text to exist, read the file around the expected location and retry.");
+		lines.push(languageForPath(opts.path) ? `Next context call: read_symbol ${JSON.stringify({ path: opts.path })} to locate the intended symbol without guessing line ranges.` : nextContextCall(opts.path, 1));
 	}
 
 	if (causes.length > 0) {
@@ -449,7 +479,7 @@ function truncateLine(line: string): string {
  * Enforce the complete output budget without ever cutting a generated fenced
  * snippet. Oversized snippets are omitted atomically and clearly marked.
  */
-function boundCompleteOutput(message: string): string {
+export function boundCompleteOutput(message: string): string {
 	const source = message.split("\n");
 	const output: string[] = [];
 	let bytes = 0;

package/src/index.ts

@@ -1,14 +1,22 @@
 /**
  * pi-better-tool — better built-in tools for the pi coding agent.
  *
- * Currently ships one override:
- * - `edit` — built-in-compatible exact replacement with richer recovery
- *   context and conservative read-based resolution when a recent verified
- *   read contains exactly one of several literal occurrences.
+ * Ships a safe edit override and focused source readers:
+ * - `edit` — exact replacement with actionable recovery context.
+ * - `read_symbol` — whole symbols by containing line or exact name.
+ * - `read_code_imports` — raw dependency import zones for common languages.
+ * Built-in `read` remains available for text, images, and explicit line ranges.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerBetterEditTool } from "./tool.ts";
+import { registerReadSymbolTool } from "./read-symbol.ts";
+import { registerReadCodeImportsTool } from "./read-code-imports.ts";
+
+export { buildCodeImportsRead, executeReadCodeImports, registerReadCodeImportsTool, readCodeImportsSchema, validateReadCodeImportsInput } from "./read-code-imports.ts";
+export type { ReadCodeImportsInput, ReadCodeImportsResult } from "./read-code-imports.ts";
+export { executeReadSymbol, registerReadSymbolTool, readSymbolSchema } from "./read-symbol.ts";
+export type { ReadSymbolInput, ReadSymbolResult } from "./read-symbol.ts";
 
 export { registerBetterEditTool, executeBetterEdit, prepareEditArguments, betterEditSchema } from "./tool.ts";
 export type {
@@ -29,4 +37,6 @@ export type { AnalyzeOptions, EditFailure, EditOp, EditAnalysis } from "./apply.
 
 export default function (pi: ExtensionAPI) {
 	registerBetterEditTool(pi);
+	registerReadSymbolTool(pi);
+	registerReadCodeImportsTool(pi);
 }

package/src/paths.ts

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** Match Pi's built-in path normalization for all local tools in this package. */
+export function resolveToolPath(input: string, cwd: string): string {
+	let path = input.replace(UNICODE_SPACES, " ");
+	if (path.startsWith("@")) path = path.slice(1);
+	if (process.platform === "win32" && path.startsWith("/") && !path.startsWith("//") && !path.includes("\\")) {
+		const match = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+		if (match) path = `${match[1].toUpperCase()}:\\${match[2]?.replaceAll("/", "\\") ?? ""}`;
+	}
+	if (path === "~") path = homedir();
+	else if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) path = join(homedir(), path.slice(2));
+	if (/^file:\/\//.test(path)) path = fileURLToPath(path);
+	return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}