@khanhicetea/pi-better-tool 0.2.2 → 0.2.3

package/README.md

@@ -1,16 +1,10 @@
 # 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`** is a new tool. Read a whole function, method, class, or type by containing line or exact name. With only a path, get a symbol outline.
+- **`read` stays unchanged** for ordinary text, images, and explicit line ranges.
 
 ## Install
 
@@ -18,127 +12,158 @@ 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:
+
+```json
+{"path":"src/server.ts","line":142,"parent":1}
 ```
 
-Tip: only fenced snippets explicitly presented as retryable should be copied into oldText.
+Discover names and ranges without reading every body:
 
-No changes were written — the file was not modified.
-````
+```json
+{"path":"src/server.ts"}
+```
 
-## Example: competing closest matches
+### Arguments
 
-````text
-Could not find the exact text in handlers.ts. The old text must match exactly including all whitespace and newlines.
+| 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. |
 
-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();
-}
-```
+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.
 
-No changes were written — the file was not modified.
-````
+### Languages and boundaries
 
-Similarity scores are heuristics, not probabilities.
+Syntax parsing uses Tree-sitter through `@ast-grep/napi`, not indentation or brace-counting guesses:
 
-## Behavior and compatibility
+- 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
 
-The normal matching path follows Pi's built-in edit implementation:
+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.
 
-- 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
+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.
 
-Intentional safety/compatibility differences are:
+### Output and pagination
 
-- 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
+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`.
 
-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.
+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 boundary
+Limits:
 
-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.
+- 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.
 
-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.
+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.
 
-### Local filesystem and commit guarantees
+## Recover from an edit failure in the next call
 
-This override uses local Node.js filesystem operations. It does **not** inherit an SSH, container, sandbox, or other custom edit backend.
+The `edit` input remains:
 
-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.
+```json
+{
+  "path": "src/server.ts",
+  "edits": [
+    { "oldText": "exact current text", "newText": "replacement text" }
+  ]
+}
+```
 
-The final write is still an in-place filesystem overwrite:
+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**.
 
-- 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
+| 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. |
 
-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.
+A failed batch starts with, for example:
 
-### Output and resource bounds
+```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.
+```
 
-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.
+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.
 
-`details.diff` and `details.patch` remain complete for renderer compatibility and are not blindly truncated as diagnostic text.
+### Verified read evidence
 
-## Host compatibility
+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**.
 
-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.
+Both readers participate:
 
-## Development
+- 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.
 
-```bash
-npm run check     # typecheck + tests
-npm test          # vitest only
-```
+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.
 
-## Publishing
+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.
 
-From the repository root:
+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.3",
+	"description": "Context-aware tools for pi: safe edit recovery and syntax-aware read_symbol for whole functions, methods, and classes by line or name",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -13,8 +13,20 @@
 	"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",
+		"tree-sitter",
+		"tools"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
 	"scripts": {
 		"test": "vitest run",
 		"typecheck": "tsc --noEmit",
@@ -33,12 +45,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,18 @@
 /**
  * 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 a separate syntax-aware source reader:
+ * - `edit` — exact replacement with actionable recovery context.
+ * - `read_symbol` — whole symbols by containing line or exact name.
+ * 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";
+
+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 +33,5 @@ export type { AnalyzeOptions, EditFailure, EditOp, EditAnalysis } from "./apply.
 
 export default function (pi: ExtensionAPI) {
 	registerBetterEditTool(pi);
+	registerReadSymbolTool(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);
+}

package/src/read-evidence.ts

@@ -6,6 +6,7 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { normalizeToLF } from "./text.ts";
+import { buildSymbolRead, type ReadSymbolInput } from "./read-symbol.ts";
 
 export interface ReadEvidence {
 	/** 0-based, end-exclusive offsets in LF-normalized, BOM-stripped content. */
@@ -18,6 +19,8 @@ export interface ReadEvidence {
 
 interface ReadCall {
 	id: string;
+	name: "read" | "read_symbol";
+	arguments: Record<string, unknown>;
 	path: string;
 	offset?: number;
 	limit?: number;
@@ -69,11 +72,13 @@ export async function findLatestReadEvidence(
 	for (const message of messages) {
 		if (message.role === "assistant") {
 			for (const item of (message as StoredAssistant).content) {
-				if (item.type !== "toolCall" || item.name !== "read" || typeof item.id !== "string") continue;
+				if (item.type !== "toolCall" || (item.name !== "read" && item.name !== "read_symbol") || typeof item.id !== "string") continue;
 				const args = item.arguments as Record<string, unknown> | undefined;
 				if (!args || typeof args.path !== "string") continue;
 				calls.push({
 					id: item.id,
+					name: item.name,
+					arguments: args,
 					path: args.path,
 					offset: typeof args.offset === "number" ? args.offset : undefined,
 					limit: typeof args.limit === "number" ? args.limit : undefined,
@@ -81,7 +86,7 @@ export async function findLatestReadEvidence(
 			}
 		} else if (message.role === "toolResult") {
 			const result = message as StoredToolResult;
-			if (result.toolName === "read") results.set(result.toolCallId, result);
+			if (result.toolName === "read" || result.toolName === "read_symbol") results.set(result.toolCallId, result);
 		}
 	}
 
@@ -100,7 +105,17 @@ export async function findLatestReadEvidence(
 		// Never fall back to older intent when the newest same-file read is
 		// missing, failed, malformed, or stale.
 		const result = results.get(call.id);
-		if (!result || result.isError) return null;
+		if (!result || result.isError || result.toolName !== call.name) return null;
+		if (call.name === "read_symbol") {
+			if (result.content.length !== 1 || result.content[0].type !== "text") return null;
+			try {
+				// Regenerate from current source and original arguments, not untrusted
+				// details. Snapshot, selector, envelope, and visible bytes must agree.
+				const expected = await buildSymbolRead(call.arguments as ReadSymbolInput, normalizedContent);
+				if (result.content[0].text !== expected.content[0].text) return null;
+				return expected.details.visible ?? null;
+			} catch { return null; }
+		}
 		return evidenceFromBuiltinRead(normalizedContent, call, result.content);
 	}
 	return null;
@@ -155,7 +170,9 @@ export function evidenceFromBuiltinRead(
 	const startLine = startIndex + 1;
 	const endLine = startLine + visibleLines - 1;
 	const startOffset = offsetAtLine(content, startLine);
-	const endOffset = offsetAtLine(content, endLine + 1);
+	// A line-limited/truncated result omits the separator after its final
+	// displayed line. Do not authorize an edit anchor through unseen bytes.
+	const endOffset = startOffset + truncation.content.length;
 	return { startOffset, endOffset, startLine, endLine };
 }
 

package/src/read-symbol.ts

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { boundCompleteOutput, fenceFor } from "./diagnostics.ts";
+import { resolveToolPath } from "./paths.ts";
+import { readSource, sourceReadError } from "./source-file.ts";
+import { indexSymbols, languageForPath, SUPPORTED_LANGUAGES, type SourceSymbol } from "./symbols.ts";
+import { getLineSpans } from "./text.ts";
+
+export const readSymbolSchema = Type.Object({
+	path: Type.String({ minLength: 1, maxLength: 4096, description: "Local source file path (relative, absolute, @path, ~/path, or file URL)." }),
+	line: Type.Optional(Type.Integer({ minimum: 1, description: "Read the innermost symbol containing this 1-based line. Combine with symbol to disambiguate duplicate names." })),
+	column: Type.Optional(Type.Integer({ minimum: 1, description: "Optional 1-based UTF-16 column with line, to distinguish symbols on the same line." })),
+	symbol: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Exact symbol name or qualified name, for example Server.run. Omit both symbol and line to list a symbol outline." })),
+	parent: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Move outward this many enclosing symbols after selection (default 0)." })),
+	context: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Extra whole lines before and after the selected symbol (default 0)." })),
+	offset: Type.Optional(Type.Integer({ minimum: 1, description: "1-based position within the selected symbol/context or outline, not a file line. Use the exact continuation call from a partial result." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 1800, description: "Maximum source lines (default 1000) or outline entries (default 50). Output also has a 48 KiB hard limit." })),
+});
+export type ReadSymbolInput = Static<typeof readSymbolSchema>;
+
+export interface VisibleSource {
+	startLine: number;
+	endLine: number;
+	startOffset: number;
+	endOffset: number;
+}
+export interface ReadSymbolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		mode: "symbol" | "outline";
+		snapshot: string;
+		symbol?: SourceSymbol;
+		visible?: VisibleSource;
+		complete: boolean;
+		nextCall?: ReadSymbolInput;
+	};
+}
+const MAX_OUTPUT_BYTES = 48 * 1024;
+const MAX_OUTPUT_LINES = 1950;
+const label = (text: string) => JSON.stringify(text.length > 300 ? `${text.slice(0, 297)}…` : text);
+const callText = (input: ReadSymbolInput) => `read_symbol ${JSON.stringify(input)}`;
+
+export function validateReadSymbolInput(input: ReadSymbolInput): void {
+	if (!input || typeof input.path !== "string" || !input.path.length || input.path.length > 4096) throw new Error("read_symbol requires a non-empty path of at most 4096 characters.");
+	if (input.symbol !== undefined && (typeof input.symbol !== "string" || !input.symbol.trim() || input.symbol.length > 256)) throw new Error("read_symbol symbol must be a non-empty name of at most 256 characters.");
+	for (const [key, min, max] of [["line", 1, Number.MAX_SAFE_INTEGER], ["column", 1, Number.MAX_SAFE_INTEGER], ["parent", 0, 20], ["context", 0, 20], ["offset", 1, Number.MAX_SAFE_INTEGER], ["limit", 1, 1800]] as const) {
+		const value = input[key];
+		if (value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max)) throw new Error(`read_symbol ${key} must be an integer from ${min} to ${max}.`);
+	}
+	if (input.column !== undefined && input.line === undefined) throw new Error("read_symbol column requires line.");
+	if ((input.parent || input.context) && input.line === undefined && input.symbol === undefined) throw new Error("read_symbol parent/context requires a line or symbol selector; omit them to get an outline.");
+}
+
+function candidateLine(path: string, symbol: SourceSymbol): string {
+	return `- ${label(symbol.qualifiedName)} (${symbol.kind}), lines ${symbol.startLine}-${symbol.endLine}. ${callText({ path, line: symbol.startLine, column: symbol.startColumn, symbol: symbol.qualifiedName.length <= 256 ? symbol.qualifiedName : undefined })}`;
+}
+
+/** Non-copyable preview for failed selection; never presented as a complete symbol. */
+function fallbackContext(input: ReadSymbolInput, content: string, reason: string, atLine = input.line ?? 1): Error {
+	const lines = content.split("\n");
+	const center = Math.min(Math.max(atLine, 1), lines.length);
+	const start = Math.max(1, center - 5);
+	const end = Math.min(lines.length, center + 10);
+	const preview = lines.slice(start - 1, end).map((line, index) => `${start + index}: ${line.length > 240 ? `${line.slice(0, 240)}… [line clipped]` : line}`).join("\n");
+	return new Error(`${reason}\nFile has ${lines.length} lines. Preview only, not a complete symbol or retryable edit snippet:\n${preview}\nNext: read ${JSON.stringify({ path: input.path, offset: start, limit: end - start + 1 })}`);
+}
+
+function inside(symbol: SourceSymbol, line: number, column?: number): boolean {
+	if (line < symbol.startLine || line > symbol.endLine) return false;
+	if (column !== undefined && ((line === symbol.startLine && column < symbol.startColumn) || (line === symbol.endLine && column >= symbol.endColumn))) return false;
+	return true;
+}
+
+function selectSymbol(input: ReadSymbolInput, symbols: SourceSymbol[]): SourceSymbol {
+	let matches = symbols.filter((symbol) =>
+		(input.symbol === undefined || symbol.name === input.symbol || symbol.qualifiedName === input.symbol) &&
+		(input.line === undefined || inside(symbol, input.line, input.column)),
+	);
+	if (input.symbol === undefined) {
+		// Keep innermost declarations, but never choose arbitrarily between siblings.
+		const matched = new Set(matches);
+		const ancestors = new Set<SourceSymbol>();
+		// Parents precede children in the index. Propagate once in reverse,
+		// rather than walking every ancestor chain in deeply nested source.
+		for (let index = symbols.length - 1; index >= 0; index--) {
+			const symbol = symbols[index];
+			if (symbol.parent !== undefined && (matched.has(symbol) || ancestors.has(symbol))) ancestors.add(symbols[symbol.parent]);
+		}
+		matches = matches.filter((symbol) => !ancestors.has(symbol));
+	}
+	if (matches.length !== 1) {
+		const candidates = matches.length ? matches : [...symbols].sort((a, b) => {
+			if (input.line !== undefined) return Math.abs(a.startLine - input.line) - Math.abs(b.startLine - input.line);
+			const query = input.symbol?.toLowerCase() ?? "";
+			return Number(b.qualifiedName.toLowerCase().includes(query)) - Number(a.qualifiedName.toLowerCase().includes(query));
+		});
+		throw new Error([
+			matches.length ? `Ambiguous symbol selection: ${matches.length} candidates. No symbol was selected.` : "No matching symbol. Names are exact and case-sensitive; no nearby symbol was selected automatically.",
+			...candidates.slice(0, 8).map((symbol) => candidateLine(input.path, symbol)),
+			...(candidates.length > 8 ? [`${candidates.length - 8} more candidates omitted.`] : []),
+			`Next: choose a candidate call above, or list the outline with ${callText({ path: input.path })}.`,
+		].join("\n"));
+	}
+	let selected = matches[0];
+	for (let depth = 0; depth < (input.parent ?? 0); depth++) {
+		if (selected.parent === undefined) throw new Error(`No enclosing symbol at parent=${input.parent}. Outermost available: ${candidateLine(input.path, selected)}\nRetry with a smaller parent value.`);
+		selected = symbols[selected.parent];
+	}
+	return selected;
+}
+
+function fits(text: string): boolean {
+	return Buffer.byteLength(text, "utf8") <= MAX_OUTPUT_BYTES && text.split("\n").length <= MAX_OUTPUT_LINES;
+}
+
+/** Pure snapshot-to-result path, also used to verify stored read evidence. */
+export async function buildSymbolRead(input: ReadSymbolInput, content: string, signal?: AbortSignal): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const lines = content.split("\n");
+	if (input.line !== undefined && input.line > lines.length) throw fallbackContext(input, content, `line=${input.line} is beyond EOF. Valid lines: 1-${lines.length}.`);
+	if (input.column !== undefined && input.column > lines[input.line! - 1].length + 1) throw fallbackContext(input, content, `column=${input.column} is outside line ${input.line}.`);
+	const parserPath = resolveToolPath(input.path, "/");
+	if (!languageForPath(parserPath)) throw fallbackContext(input, content, `Unsupported source type. read_symbol supports ${SUPPORTED_LANGUAGES}. Use read for this file.`);
+	let index: Awaited<ReturnType<typeof indexSymbols>>;
+	try { index = await indexSymbols(parserPath, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw fallbackContext(input, content, `Symbol parser unavailable or analysis limit reached: ${error instanceof Error ? error.message.slice(0, 500) : "unknown parser error"}. Use read instead.`);
+	}
+	signal?.throwIfAborted();
+	if (index.errorLine !== undefined) throw fallbackContext(input, content, `Syntax error or incomplete syntax near line ${index.errorLine}; complete symbol boundaries are not reliable.`, input.line ?? index.errorLine);
+	const snapshot = createHash("sha256").update(content).digest("hex");
+	const header = `Source ${label(input.path)} (${lines.length} lines). Snapshot sha256:${snapshot}`;
+	const offset = input.offset ?? 1;
+	if (input.line === undefined && input.symbol === undefined) {
+		const total = index.symbols.length;
+		if (offset > Math.max(1, total)) throw new Error(`Outline offset=${offset} is beyond ${total} entries. Next: ${callText({ ...input, offset: Math.max(1, total - 49) })}`);
+		const entries: string[] = [];
+		let cursor = offset - 1;
+		for (; cursor < Math.min(total, offset - 1 + (input.limit ?? 50)); cursor++) {
+			const entry = candidateLine(input.path, index.symbols[cursor]);
+			if (!fits(`${header}\n${entries.join("\n")}\n${entry}\n${" ".repeat(6000)}`)) break;
+			entries.push(entry);
+		}
+		const nextCall = cursor < total ? { ...input, offset: cursor + 1 } : undefined;
+		const text = `${header}\nSymbol outline: ${total} declarations, ${entries.length} shown.${total === 0 ? " No symbols found; use read for source text." : ""}\n${entries.join("\n")}${nextCall ? `\nMore entries. Next: ${callText(nextCall)}` : ""}`;
+		return { content: [{ type: "text", text }], details: { mode: "outline", snapshot, complete: !nextCall, nextCall } };
+	}
+	if (!index.symbols.length) throw fallbackContext(input, content, "No symbol declarations found in this file.");
+	const selected = selectSymbol(input, index.symbols);
+	const start = Math.max(1, selected.startLine - (input.context ?? 0));
+	const end = Math.min(lines.length, selected.endLine + (input.context ?? 0));
+	const count = end - start + 1;
+	if (offset > count) throw new Error(`Symbol ${label(selected.qualifiedName)} spans lines ${selected.startLine}-${selected.endLine}; selected region has ${count} lines. offset=${offset} is outside it. Next: ${callText({ ...input, offset: 1 })}`);
+	const firstLine = start + offset - 1;
+	let lastLine = Math.min(end, firstLine + (input.limit ?? 1000) - 1);
+	const parents: string[] = [];
+	let parent = selected.parent;
+	while (parent !== undefined && parents.length < 20) { parents.unshift(label(index.symbols[parent].qualifiedName)); parent = index.symbols[parent].parent; }
+	const prefix = `${header}\nSymbol ${label(selected.qualifiedName)} (${selected.kind}), lines ${selected.startLine}-${selected.endLine}.${parents.length ? `\nEnclosing: ${parents.join(" > ")}` : ""}`;
+	let text = "";
+	let snippet = "";
+	let nextCall: ReadSymbolInput | undefined;
+	// Whole-line pages only. Account for fences, metadata, and continuation JSON.
+	while (lastLine >= firstLine) {
+		snippet = lines.slice(firstLine - 1, lastLine).join("\n");
+		const fence = fenceFor(snippet);
+		nextCall = lastLine < end ? { ...input, offset: lastLine - start + 2 } : undefined;
+		text = `${prefix}\nShowing file lines ${firstLine}-${lastLine} of selected lines ${start}-${end}. ${firstLine === start && lastLine === end ? "Complete selection." : "Partial selection; do not treat this page as the whole symbol."}\n\n${fence}\n${snippet}\n${fence}${nextCall ? `\n\nNext: ${callText(nextCall)}` : ""}`;
+		if (fits(text)) break;
+		// Remove a proportional chunk first; small pages shrink one line at a time.
+		lastLine -= Math.max(1, Math.floor((lastLine - firstLine + 1) / 4));
+	}
+	if (lastLine < firstLine) throw fallbackContext(input, content, `File line ${firstLine} cannot fit as a complete line in the 48 KiB output budget. No partial edit snippet was returned.`, firstLine);
+	const spans = getLineSpans(content);
+	const startOffset = spans[firstLine - 1]?.start ?? content.length;
+	return {
+		content: [{ type: "text", text }],
+		details: {
+			mode: "symbol", snapshot, symbol: selected,
+			visible: { startLine: firstLine, endLine: lastLine, startOffset, endOffset: startOffset + snippet.length },
+			complete: firstLine === start && lastLine === end, nextCall,
+		},
+	};
+}
+
+export async function executeReadSymbol(input: ReadSymbolInput, signal: AbortSignal | undefined, ctx: Pick<ExtensionContext, "cwd">): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const path = resolveToolPath(input.path, ctx.cwd);
+	let content: string;
+	try { content = await readSource(path, signal); }
+	catch (error) { signal?.throwIfAborted(); throw new Error(boundCompleteOutput(await sourceReadError(path, error))); }
+	try { return await buildSymbolRead(input, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw new Error(boundCompleteOutput(error instanceof Error ? error.message : String(error)));
+	}
+}
+
+export function registerReadSymbolTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read_symbol", label: "read_symbol",
+		description: `Read a complete function, method, class, or type from a local source file by containing line or exact symbol name. Supports ${SUPPORTED_LANGUAGES}. With path only, lists a symbol outline. Includes enclosing names, exact source ranges, and actionable failure context. Output is bounded to 48 KiB/1950 lines; partial results include an exact continuation call. Does not replace read for ordinary text or images.`,
+		promptSnippet: "Read whole source symbols by line/name, or list a file's symbol outline",
+		promptGuidelines: [
+			"Use read_symbol with path and line after grep/edit identifies a code location, instead of guessing successive read offsets to find the function boundary.",
+			"Use read_symbol with symbol for an exact name or qualified name; use path alone for an outline. Use parent to include an enclosing function or class.",
+			"For read_symbol partial output, use the supplied continuation arguments. offset is relative to the selection, not a file line. Only displayed source is evidence for edit.",
+		],
+		parameters: readSymbolSchema,
+		async execute(_id, input, signal, _onUpdate, ctx) { return executeReadSymbol(input, signal, ctx); },
+	});
+}

package/src/source-file.ts

@@ -0,0 +1,60 @@
+import { constants } from "node:fs";
+import { open, opendir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { MAX_SOURCE_BYTES } from "./symbols.ts";
+import { normalizeToLF, splitBom } from "./text.ts";
+
+/** Bounded local source read; no silent decoding loss and no special files. */
+export async function readSource(path: string, signal?: AbortSignal): Promise<string> {
+	signal?.throwIfAborted();
+	const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) throw new Error("The path is not a regular source file.");
+		if (stat.size > MAX_SOURCE_BYTES) throw new Error("Source exceeds the 2 MiB symbol analysis limit; use read with offset/limit.");
+		const buffer = Buffer.alloc(Math.min(stat.size + 1, MAX_SOURCE_BYTES + 1));
+		let length = 0;
+		while (length < buffer.length) {
+			signal?.throwIfAborted();
+			const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+			if (!bytesRead) break;
+			length += bytesRead;
+		}
+		const after = await handle.stat();
+		if (length !== stat.size || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs) throw new Error("The source changed during the read; retry read_symbol.");
+		const bytes = buffer.subarray(0, length);
+		let content: string;
+		try { content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+		catch { throw new Error("The source is not valid UTF-8; convert its encoding before symbol parsing."); }
+		if (bytes.includes(0)) throw new Error("The source contains NUL bytes; binary/UTF-16 input is not supported.");
+		signal?.throwIfAborted();
+		return splitBom(normalizeToLF(content)).text;
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Only inspect a bounded number of siblings; never perform a hidden repo scan. */
+export async function sourceReadError(path: string, error: unknown): Promise<string> {
+	const code = (error as NodeJS.ErrnoException)?.code;
+	const message = error instanceof Error ? error.message.slice(0, 1000) : String(error).slice(0, 1000);
+	const lines = [`Could not read source ${JSON.stringify(path)}: ${message}`];
+	if (code === "ENOENT" || code === "ENOTDIR") {
+		const names: string[] = [];
+		try {
+			const directory = await opendir(dirname(path));
+			let inspected = 0;
+			for await (const entry of directory) {
+				if (entry.isFile()) names.push(entry.name);
+				if (++inspected >= 100) break;
+			}
+		} catch { /* Parent may also be missing or inaccessible. */ }
+		const stem = basename(path).split(".")[0].toLowerCase();
+		names.sort((a, b) => Number(b.toLowerCase().includes(stem)) - Number(a.toLowerCase().includes(stem)) || a.localeCompare(b));
+		if (names.length) lines.push("Nearby file candidates (bounded listing, not automatic path corrections):", ...names.slice(0, 8).map((name) => `  ${JSON.stringify(join(dirname(path), name))}`));
+		lines.push("Verify the path and retry read_symbol; use find/ls if the parent path is wrong.");
+	} else if (code === "EACCES" || code === "EPERM") {
+		lines.push("Check file permissions. Do not retry the same call until access changes.");
+	} else lines.push("Use read for ordinary text, images, or bounded line ranges; no symbol boundaries were returned.");
+	return lines.join("\n");
+}

package/src/symbols.ts

@@ -0,0 +1,228 @@
+import { basename, extname } from "node:path";
+import type { SgNode } from "@ast-grep/napi";
+
+export const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+const MAX_NODES = 100_000;
+const MAX_SYMBOLS = 10_000;
+
+const LANGUAGES: Record<string, string> = {
+	".js": "JavaScript", ".jsx": "Tsx", ".mjs": "JavaScript", ".cjs": "JavaScript",
+	".ts": "TypeScript", ".tsx": "Tsx", ".mts": "TypeScript", ".cts": "TypeScript",
+	".py": "python", ".pyi": "python", ".go": "go", ".rs": "rust",
+	".bash": "bash", ".bats": "bash", ".command": "bash", ".ksh": "bash", ".sh": "bash", ".zsh": "bash",
+	".c": "c", ".h": "c", ".cc": "cpp", ".cp": "cpp", ".cpp": "cpp", ".cxx": "cpp", ".c++": "cpp", ".cu": "cpp", ".hh": "cpp", ".hpp": "cpp", ".hxx": "cpp", ".ino": "cpp",
+	".cs": "csharp", ".java": "java", ".kt": "kotlin", ".ktm": "kotlin", ".kts": "kotlin",
+	".php": "php", ".phtml": "php", ".rb": "ruby", ".rbw": "ruby", ".rake": "ruby", ".gemspec": "ruby", ".swift": "swift",
+};
+const FILENAMES: Record<string, string> = { Gemfile: "ruby", Rakefile: "ruby" };
+export const SUPPORTED_LANGUAGES = "Bash, C, C++, C#, Java, JavaScript/JSX, TypeScript/TSX, Kotlin, PHP, Python, Ruby, Rust, Swift, and Go";
+export function languageForPath(path: string): string | undefined {
+	return LANGUAGES[extname(path).toLowerCase()] ?? FILENAMES[basename(path)];
+}
+
+export interface SourceSymbol {
+	name: string;
+	qualifiedName: string;
+	kind: string;
+	startLine: number;
+	endLine: number;
+	/** 1-based UTF-16 columns, end-exclusive. */
+	startColumn: number;
+	endColumn: number;
+	parent?: number;
+}
+
+export interface SymbolIndex {
+	symbols: SourceSymbol[];
+	/** Never claim complete symbol boundaries for a malformed tree. */
+	errorLine?: number;
+}
+
+type Parser = typeof import("@ast-grep/napi");
+type DynamicLanguageModule = { default: import("@ast-grep/napi").DynamicLangRegistrations[string] };
+
+// Native dynamic language registration is process-wide. Keep only parser setup
+// across /reload, never project content or session evidence. ast-grep initializes
+// its registry only once, so upgrading from a smaller grammar set requires a Pi
+// restart before the newly shipped grammars can be registered.
+const parserKey = Symbol.for("pi-better-tool.parser.0.45.3.v2");
+const parserState = globalThis as typeof globalThis & { [parserKey]?: Promise<Parser> };
+const DYNAMIC_LANGUAGE_MODULES: ReadonlyArray<readonly [string, () => Promise<DynamicLanguageModule>]> = [
+	["bash", () => import("@ast-grep/lang-bash")],
+	["c", () => import("@ast-grep/lang-c")],
+	["cpp", () => import("@ast-grep/lang-cpp")],
+	["csharp", () => import("@ast-grep/lang-csharp")],
+	["java", () => import("@ast-grep/lang-java")],
+	["kotlin", () => import("@ast-grep/lang-kotlin")],
+	["php", () => import("@ast-grep/lang-php")],
+	["python", () => import("@ast-grep/lang-python")],
+	["ruby", () => import("@ast-grep/lang-ruby")],
+	["rust", () => import("@ast-grep/lang-rust")],
+	["swift", () => import("@ast-grep/lang-swift")],
+	["go", () => import("@ast-grep/lang-go")],
+];
+async function loadParser(): Promise<Parser> {
+	return parserState[parserKey] ??= (async () => {
+		const api = await import("@ast-grep/napi");
+		const languages: import("@ast-grep/napi").DynamicLangRegistrations = {};
+		const modules = await Promise.allSettled(DYNAMIC_LANGUAGE_MODULES.map(([, load]) => load()));
+		for (const [index, [name]] of DYNAMIC_LANGUAGE_MODULES.entries()) {
+			const module = modules[index];
+			if (module.status !== "fulfilled") continue;
+			try {
+				// Resolve lazy prebuild getters here. One unavailable grammar must
+				// not prevent the built-in JS/TS parsers from working.
+				languages[name] = { ...module.value.default };
+			} catch { /* Report unavailable language at parse time. */ }
+		}
+		try {
+			if (Object.keys(languages).length) api.registerDynamicLanguage(languages);
+		} catch { /* An incompatible native grammar must not disable built-in JS/TS. */ }
+		return api;
+	})();
+}
+
+const JS_DECLARATIONS = [
+	"function_declaration", "generator_function_declaration", "function_expression", "generator_function", "arrow_function",
+	"method_definition", "class_declaration", "abstract_class_declaration", "class",
+	"interface_declaration", "type_alias_declaration", "enum_declaration", "internal_module",
+	"function_signature", "method_signature", "abstract_method_signature",
+];
+const DECLARATIONS_BY_LANGUAGE: Record<string, ReadonlySet<string>> = {
+	JavaScript: new Set(JS_DECLARATIONS), TypeScript: new Set(JS_DECLARATIONS), Tsx: new Set(JS_DECLARATIONS),
+	python: new Set(["function_definition", "class_definition"]),
+	go: new Set(["function_declaration", "method_declaration", "type_spec", "func_literal"]),
+	rust: new Set(["function_item", "function_signature_item", "struct_item", "enum_item", "trait_item", "impl_item", "mod_item", "type_item", "closure_expression"]),
+	bash: new Set(["function_definition"]),
+	c: new Set(["function_definition", "struct_specifier", "union_specifier", "enum_specifier", "type_definition"]),
+	cpp: new Set(["function_definition", "class_specifier", "struct_specifier", "union_specifier", "enum_specifier", "namespace_definition", "alias_declaration"]),
+	csharp: new Set(["namespace_declaration", "file_scoped_namespace_declaration", "class_declaration", "struct_declaration", "interface_declaration", "enum_declaration", "record_declaration", "delegate_declaration", "method_declaration", "constructor_declaration", "destructor_declaration", "local_function_statement"]),
+	java: new Set(["class_declaration", "interface_declaration", "enum_declaration", "annotation_type_declaration", "record_declaration", "method_declaration", "constructor_declaration", "compact_constructor_declaration"]),
+	kotlin: new Set(["class_declaration", "object_declaration", "function_declaration", "secondary_constructor"]),
+	php: new Set(["class_declaration", "interface_declaration", "trait_declaration", "enum_declaration", "function_definition", "method_declaration"]),
+	ruby: new Set(["class", "module", "method", "singleton_method"]),
+	swift: new Set(["class_declaration", "protocol_declaration", "struct_declaration", "enum_declaration", "extension_declaration", "actor_declaration", "function_declaration", "initializer_declaration", "deinitializer_declaration"]),
+};
+const ANONYMOUS_FUNCTIONS = new Set(["arrow_function", "function_expression", "generator_function", "func_literal", "closure_expression"]);
+const BINDINGS = new Set(["variable_declarator", "pair", "public_field_definition", "field_definition", "assignment", "let_declaration"]);
+const LIFECYCLE_NAMES: Record<string, string> = {
+	constructor_declaration: "constructor", compact_constructor_declaration: "constructor", secondary_constructor: "constructor",
+	destructor_declaration: "destructor", initializer_declaration: "init", deinitializer_declaration: "deinit",
+};
+const NAME_KINDS_BY_LANGUAGE: Record<string, readonly string[]> = {
+	c: ["identifier", "field_identifier", "type_identifier"],
+	cpp: ["identifier", "field_identifier", "type_identifier", "namespace_identifier", "operator_name"],
+	kotlin: ["simple_identifier", "type_identifier"],
+	swift: ["simple_identifier", "type_identifier"],
+};
+
+function firstNamedText(node: SgNode, kinds: readonly string[]): string | undefined {
+	if (kinds.includes(String(node.kind()))) return node.text();
+	for (const kind of kinds) {
+		const found = node.find({ rule: { kind } });
+		if (found) return found.text();
+	}
+	return undefined;
+}
+
+function nameForNode(node: SgNode, language: string): string | undefined {
+	const directName = node.field("name")?.text();
+	if (directName) return directName;
+	const lifecycleName = LIFECYCLE_NAMES[String(node.kind())];
+	if (lifecycleName) return lifecycleName;
+	// Kotlin classes/objects use type_identifier while functions use
+	// simple_identifier. Searching for the latter first would accidentally take
+	// a nested method name as the enclosing class name.
+	const kinds = language === "kotlin"
+		? (node.kind() === "function_declaration" ? ["simple_identifier"] : ["type_identifier"])
+		: NAME_KINDS_BY_LANGUAGE[language];
+	if (!kinds) return undefined;
+	const declarator = node.field("declarator");
+	return (declarator && firstNamedText(declarator, kinds)) ?? firstNamedText(node, kinds);
+}
+
+function isDeclaration(node: SgNode, language: string): boolean {
+	if (!DECLARATIONS_BY_LANGUAGE[language]?.has(String(node.kind()))) return false;
+	// A typedef that wraps a named C struct/union/enum is one declaration. Keep
+	// the outer typedef's full range instead of emitting a duplicate child name.
+	return !(language === "c" && ["struct_specifier", "union_specifier", "enum_specifier"].includes(String(node.kind())) && node.parent()?.kind() === "type_definition");
+}
+
+function describeNode(node: SgNode, language: string): { name: string; start: SgNode; end: SgNode } {
+	let start = node;
+	let end = node;
+	let name = nameForNode(node, language);
+	const parent = node.parent();
+	if (ANONYMOUS_FUNCTIONS.has(String(node.kind())) && parent && BINDINGS.has(String(parent.kind()))) {
+		name = parent.field("name")?.text() ?? parent.field("key")?.text() ?? parent.field("left")?.text() ?? parent.field("pattern")?.text() ?? name;
+		start = end = parent;
+		const declaration = parent.parent();
+		if (declaration && ["lexical_declaration", "variable_declaration"].includes(String(declaration.kind())) &&
+			declaration.children().filter((child) => child.kind() === "variable_declarator").length === 1) {
+			start = end = declaration;
+		}
+	}
+	if (node.kind() === "impl_item") name = node.field("type")?.text();
+	if (node.kind() === "method_declaration") {
+		const receiver = node.field("receiver")?.find({ rule: { kind: "type_identifier" } })?.text();
+		if (receiver && name) name = `${receiver}.${name}`;
+	}
+	const wrapper = start.parent();
+	if (wrapper && ["export_statement", "decorated_definition"].includes(String(wrapper.kind()))) start = end = wrapper;
+	// Rust attributes are siblings, not part of the declaration node.
+	let previous = start.prev();
+	while (previous?.kind() === "attribute_item") {
+		start = previous;
+		previous = previous.prev();
+	}
+	return { name: name ?? `<anonymous@${node.range().start.line + 1}:${node.range().start.column + 1}>`, start, end };
+}
+
+/** Parse syntax, not regex/braces. No repository code, config, or shell runs. */
+export async function indexSymbols(path: string, content: string, signal?: AbortSignal): Promise<SymbolIndex> {
+	signal?.throwIfAborted();
+	if (Buffer.byteLength(content, "utf8") > MAX_SOURCE_BYTES) throw new Error("Source exceeds the 2 MiB symbol analysis limit.");
+	const language = languageForPath(path);
+	if (!language) throw new Error(`Unsupported source type. Symbol parsing supports ${SUPPORTED_LANGUAGES}.`);
+	const api = await loadParser();
+	signal?.throwIfAborted();
+	const root = (await api.parseAsync(language, content)).root();
+	signal?.throwIfAborted();
+	const symbols: SourceSymbol[] = [];
+	const stack: Array<{ node: SgNode; parent?: number }> = [{ node: root }];
+	let visited = 0;
+	let errorLine: number | undefined;
+	while (stack.length) {
+		if (++visited > MAX_NODES || symbols.length > MAX_SYMBOLS) throw new Error("Source exceeds the symbol traversal budget; use a bounded read instead.");
+		const { node, parent } = stack.pop()!;
+		const range = node.range();
+		if (node.kind() === "ERROR" || (node.isLeaf() && node.id() !== root.id() && range.start.index === range.end.index)) {
+			errorLine ??= range.start.line + 1;
+		}
+		let enclosing = parent;
+		if (isDeclaration(node, language)) {
+			const described = describeNode(node, language);
+			const start = described.start.range().start;
+			const end = described.end.range().end;
+			const owner = parent === undefined ? undefined : symbols[parent];
+			const qualifiedName = owner ? `${owner.qualifiedName}.${described.name}` : described.name;
+			if (qualifiedName.length > 1024) throw new Error("Source exceeds the 1024-character qualified symbol name budget; use a bounded read instead.");
+			enclosing = symbols.length;
+			symbols.push({
+				name: described.name,
+				qualifiedName,
+				kind: String(node.kind()), startLine: start.line + 1,
+				endLine: end.line + (end.column === 0 ? 0 : 1),
+				startColumn: start.column + 1, endColumn: end.column + 1, parent,
+			});
+		}
+		const children = node.children();
+		for (let index = children.length - 1; index >= 0; index--) stack.push({ node: children[index], parent: enclosing });
+		// Give cancellation a chance during large traversals.
+		if (visited % 2048 === 0) {
+			await new Promise<void>((resolve) => setImmediate(resolve));
+			signal?.throwIfAborted();
+		}
+	}
+	return { symbols, errorLine };
+}

package/src/tool.ts

@@ -31,9 +31,7 @@ import {
 	stat as fsStat,
 	writeFile as fsWriteFile,
 } from "node:fs/promises";
-import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveToolPath as resolveToCwd } from "./paths.ts";
 import { type Static, Type } from "typebox";
 import { analyzeEdits, applyAnalysis, fuzzyFindText, normalizeEdits, type EditOp } from "./apply.ts";
 import {
@@ -72,31 +70,6 @@ export const betterEditSchema = Type.Object({
 
 export type BetterEditInput = Static<typeof betterEditSchema>;
 
-const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
-
-/** Match pi's built-in path normalization for tool arguments. */
-function normalizeToolPath(input: 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 === "~") return homedir();
-	if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
-		return join(homedir(), path.slice(2));
-	}
-	if (/^file:\/\//.test(path)) return fileURLToPath(path);
-	return path;
-}
-
-function resolveToCwd(filePath: string, cwd: string): string {
-	const path = normalizeToolPath(filePath);
-	return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
-}
-
 function isSingleEditInput(value: unknown): value is { oldText: string; newText: string } {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
 		return false;
@@ -391,7 +364,8 @@ export function registerBetterEditTool(pi: ExtensionAPI, options: BetterEditExec
 			"When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls.",
 			"In edit, each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits; merge nearby changes into one edit.",
 			"Keep edit edits[].oldText as small as possible while still being unique in the file; do not pad with large unchanged regions.",
-			"When edit safely auto-disambiguates repeated text from the latest verified stored-context read, its success message lists bounded remaining candidates for an optional follow-up edit.",
+			"When edit safely auto-disambiguates repeated text from the latest verified stored-context read or read_symbol result, its success message lists bounded remaining candidates for an optional follow-up edit.",
+			"An edit matching failure applies none of the batch. Fix the reported entries and resubmit the complete batch, not only the failed replacement. Use suggested read_symbol calls when you need the whole enclosing function.",
 			"When edit fails, reuse only a fenced snippet explicitly marked retryable. If edit reports low confidence, competing candidates, omitted output, stale evidence, or a write that may have modified the file, read the referenced file/range before retrying.",
 		],
 		parameters: betterEditSchema,