@khanhicetea/pi-better-tool 0.2.3 → 0.2.5

package/README.md

@@ -3,7 +3,8 @@
 Context-aware tools for the [Pi coding agent](https://github.com/earendil-works/pi-mono):
 
 - **`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_symbol`** reads a whole function, method, class, or type by containing line or exact name. Its required `mode` makes symbol reads and outline listings explicit.
+- **`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
@@ -25,25 +26,25 @@ The root `package.json` also registers the extension. After local changes, use `
 After grep identifies a location:
 
 ```json
-{"path":"src/server.ts","line":142}
+{"path":"src/server.ts","mode":"symbol","line":142}
 ```
 
 Call `read_symbol` with an exact name instead:
 
 ```json
-{"path":"src/server.ts","symbol":"Server.handleRequest"}
+{"path":"src/server.ts","mode":"symbol","symbol":"Server.handleRequest"}
 ```
 
 Get the enclosing class or function:
 
 ```json
-{"path":"src/server.ts","line":142,"parent":1}
+{"path":"src/server.ts","mode":"symbol","line":142,"parent":1}
 ```
 
 Discover names and ranges without reading every body:
 
 ```json
-{"path":"src/server.ts"}
+{"path":"src/server.ts","mode":"outline"}
 ```
 
 ### Arguments
@@ -51,6 +52,7 @@ Discover names and ranges without reading every body:
 | Argument | Meaning |
 | --- | --- |
 | `path` | Local relative/absolute path; supports `@path`, `~/path`, and file URLs. |
+| `mode` | Required: `symbol` reads one declaration and requires `symbol` or `line`; `outline` only lists names and ranges. |
 | `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. |
@@ -59,7 +61,7 @@ Discover names and ranges without reading every body:
 | `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. |
 
-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.
+Set `mode` to `outline` 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.
 
 ### Languages and boundaries
 
@@ -95,6 +97,18 @@ Limits:
 
 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.
 
+## Read imports before editing them
+
+Call `read_code_imports` with a source path:
+
+```json
+{"path":"src/server.ts"}
+```
+
+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.
+
+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.
+
 ## Recover from an edit failure in the next call
 
 The `edit` input remains:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@khanhicetea/pi-better-tool",
-	"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",
+	"version": "0.2.5",
+	"description": "Context-aware tools for pi: safe edits, syntax-aware symbol reads, and raw source import-zone reads",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -19,6 +19,7 @@
 		"edit",
 		"read",
 		"symbols",
+		"imports",
 		"tree-sitter",
 		"tools"
 	],

package/src/diagnostics.ts

@@ -147,7 +147,7 @@ export function formatEditFailure(opts: FormatFailureOptions): string {
 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_symbol ${JSON.stringify({ path, mode: "symbol", line: start })} for the enclosing symbol; or ${read} for exact line context.`
 		: `Next context call: ${read}.`;
 }
 
@@ -456,7 +456,7 @@ function formatNotFound(opts: FormatFailureOptions, oldText: string): string {
 	} 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));
+		lines.push(languageForPath(opts.path) ? `Next context call: read_symbol ${JSON.stringify({ path: opts.path, mode: "outline" })} to locate the intended symbol without guessing line ranges.` : nextContextCall(opts.path, 1));
 	}
 
 	if (causes.length > 0) {

package/src/index.ts

@@ -1,16 +1,20 @@
 /**
  * pi-better-tool — better built-in tools for the pi coding agent.
  *
- * Ships a safe edit override and a separate syntax-aware source reader:
+ * 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";
 
@@ -34,4 +38,5 @@ export type { AnalyzeOptions, EditFailure, EditOp, EditAnalysis } from "./apply.
 export default function (pi: ExtensionAPI) {
 	registerBetterEditTool(pi);
 	registerReadSymbolTool(pi);
+	registerReadCodeImportsTool(pi);
 }

package/src/read-code-imports.ts

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { basename, extname } from "node:path";
+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";
+
+export const readCodeImportsSchema = Type.Object({
+	path: Type.String({ minLength: 1, maxLength: 4096, description: "Local source file path (relative, absolute, @path, ~/path, or file URL)." }),
+});
+export type ReadCodeImportsInput = Static<typeof readCodeImportsSchema>;
+
+type ImportLanguage = "javascript" | "python" | "go" | "rust" | "c" | "csharp" | "java" | "kotlin" | "php" | "ruby" | "swift" | "shell";
+interface LineRange { start: number; end: number }
+export interface ReadCodeImportsResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		language: ImportLanguage;
+		snapshot: string;
+		found: boolean;
+		visible?: { startLine: number; endLine: number };
+	};
+}
+
+const MAX_OUTPUT_BYTES = 48 * 1024;
+const MAX_OUTPUT_LINES = 1950;
+const EXTENSIONS: Record<string, ImportLanguage> = {
+	".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+	".ts": "javascript", ".tsx": "javascript", ".mts": "javascript", ".cts": "javascript",
+	".py": "python", ".pyi": "python", ".go": "go", ".rs": "rust",
+	".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".cxx": "c", ".hpp": "c", ".m": "c", ".mm": "c",
+	".cs": "csharp", ".java": "java", ".kt": "kotlin", ".kts": "kotlin", ".php": "php",
+	".rb": "ruby", ".swift": "swift", ".sh": "shell", ".bash": "shell", ".zsh": "shell", ".fish": "shell",
+};
+
+function importLanguage(path: string): ImportLanguage | undefined {
+	const name = basename(path).toLowerCase();
+	if (name === "gemfile" || name === "rakefile") return "ruby";
+	return EXTENSIONS[extname(name)];
+}
+
+function isImportStart(line: string, language: ImportLanguage): boolean {
+	switch (language) {
+		case "javascript": return /^(?:import(?:\s|["'])|export\s+(?:type\s+)?(?:\*|\{)[\s\S]*\bfrom\b)/.test(line);
+		case "python": return /^(?:from\s+[\w.]+\s+import\b|import\s+[\w.])/.test(line);
+		case "go": return /^import(?:\s|\()/.test(line);
+		case "rust": return /^(?:(?:pub(?:\([^)]*\))?\s+)?use\b|extern\s+crate\b)/.test(line);
+		case "c": return /^\s*#\s*(?:include|import)\b/.test(line);
+		case "csharp": return /^(?:(?:global\s+)?using\b|extern\s+alias\b)/.test(line);
+		case "java": case "kotlin": return /^import\b/.test(line);
+		case "php": return /^(?:use\b|(?:require|include)(?:_once)?\b)/.test(line);
+		case "ruby": return /^(?:require|require_relative|load)\b/.test(line);
+		case "swift": return /^(?:@\w+(?:\([^)]*\))?\s+)?import\b/.test(line);
+		case "shell": return /^(?:source\b|\.\s+\S)/.test(line);
+	}
+}
+
+function statementEnd(lines: string[], start: number, language: ImportLanguage): number {
+	if (language === "go" && /^import\s*\(/.test(lines[start])) {
+		for (let index = start; index < lines.length; index++) if (/^\s*\)/.test(lines[index])) return index;
+		return start;
+	}
+	if (language === "python") {
+		let depth = 0;
+		for (let index = start; index < lines.length; index++) {
+			const code = lines[index].replace(/#.*$/, "");
+			depth += (code.match(/[([{]/g) ?? []).length - (code.match(/[)\]}]/g) ?? []).length;
+			if (depth <= 0 && !/\\\s*$/.test(code)) return index;
+		}
+		return start;
+	}
+	if (language === "javascript") {
+		for (let index = start; index < lines.length; index++) {
+			const code = lines[index].replace(/\/\/.*$/, "").trimEnd();
+			if (/;\s*$/.test(code) || /(?:from\s+)?["'][^"']+["']\s*(?:(?:with|assert)\s*\{.*\})?\s*$/.test(code)) return index;
+		}
+		return start;
+	}
+	if (language === "rust" || language === "csharp" || language === "java" || language === "kotlin" || language === "php") {
+		for (let index = start; index < lines.length; index++) if (/;\s*(?:\/\/.*)?$/.test(lines[index])) return index;
+		return start;
+	}
+	if (language === "c") {
+		let index = start;
+		while (index + 1 < lines.length && /\\\s*$/.test(lines[index])) index++;
+		return index;
+	}
+	return start;
+}
+
+function isTrivia(line: string): boolean {
+	return /^\s*(?:$|\/\/|\/\*|\*|#(?!\s*(?:include|import)\b)|<!--|-->|\{\/\*)/.test(line);
+}
+
+function findImportZone(lines: string[], language: ImportLanguage): LineRange | undefined {
+	const statements: LineRange[] = [];
+	for (let index = 0; index < lines.length; index++) {
+		if (!isImportStart(lines[index], language)) continue;
+		const end = statementEnd(lines, index, language);
+		statements.push({ start: index, end });
+		index = end;
+	}
+	if (!statements.length) return undefined;
+	const zone = { ...statements[0] };
+	for (const statement of statements.slice(1)) {
+		if (!lines.slice(zone.end + 1, statement.start).every(isTrivia)) break;
+		zone.end = statement.end;
+	}
+	return zone;
+}
+
+export function validateReadCodeImportsInput(input: ReadCodeImportsInput): void {
+	if (!input || typeof input.path !== "string" || !input.path.length || input.path.length > 4096) throw new Error("read_code_imports requires a non-empty path of at most 4096 characters.");
+}
+
+export function buildCodeImportsRead(input: ReadCodeImportsInput, content: string): ReadCodeImportsResult {
+	validateReadCodeImportsInput(input);
+	const language = importLanguage(resolveToolPath(input.path, "/"));
+	if (!language) throw new Error("Unsupported source type. read_code_imports supports JavaScript/TypeScript, Python, Go, Rust, C/C++, C#, Java, Kotlin, PHP, Ruby, Swift, and shell source files. Use read for this file.");
+	const lines = content.split("\n");
+	const zone = findImportZone(lines, language);
+	const snapshot = createHash("sha256").update(content).digest("hex");
+	const header = `Source ${JSON.stringify(input.path)} (${lines.length} lines). Snapshot sha256:${snapshot}`;
+	if (!zone) return { content: [{ type: "text", text: `${header}\nNo dependency import statements found.` }], details: { language, snapshot, found: false } };
+	const snippet = lines.slice(zone.start, zone.end + 1).join("\n");
+	const fence = fenceFor(snippet);
+	const text = `${header}\nImport zone: file lines ${zone.start + 1}-${zone.end + 1}. Raw source lines; regex-detected, not resolved.\n\n${fence}\n${snippet}\n${fence}`;
+	if (Buffer.byteLength(text, "utf8") > MAX_OUTPUT_BYTES || text.split("\n").length > MAX_OUTPUT_LINES) throw new Error(`The complete import zone exceeds the 48 KiB / 1,950-line output limit (lines ${zone.start + 1}-${zone.end + 1}). Use read with an explicit offset/limit.`);
+	return { content: [{ type: "text", text }], details: { language, snapshot, found: true, visible: { startLine: zone.start + 1, endLine: zone.end + 1 } } };
+}
+
+export async function executeReadCodeImports(input: ReadCodeImportsInput, signal: AbortSignal | undefined, ctx: Pick<ExtensionContext, "cwd">): Promise<ReadCodeImportsResult> {
+	validateReadCodeImportsInput(input);
+	const path = resolveToolPath(input.path, ctx.cwd);
+	let content: string;
+	try { content = await readSource(path, signal, "read_code_imports"); }
+	catch (error) { signal?.throwIfAborted(); throw new Error(boundCompleteOutput(await sourceReadError(path, error, "read_code_imports"))); }
+	try { return buildCodeImportsRead(input, content); }
+	catch (error) { throw new Error(boundCompleteOutput(error instanceof Error ? error.message : String(error))); }
+}
+
+export function registerReadCodeImportsTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read_code_imports", label: "read_code_imports",
+		description: "Read the dependency import zone from a common-language source file as exact raw lines. Uses bounded regex-based detection for imports/includes/use/require statements, preserves comments and blank lines between adjacent imports, and reports the file range and snapshot. It does not resolve dependencies or replace read for arbitrary ranges.",
+		promptSnippet: "Read a source file's raw dependency import zone",
+		promptGuidelines: [
+			"When preparing an edit that adds code which uses a dependency, use read_code_imports if you are not sure whether the required import already exists.",
+			"When the target code also needs inspection, batch read_code_imports with that independent code read; inspect both results before making the dependent edit.",
+			"Treat read_code_imports output as regex-detected source text; inspect more context when conditional or generated imports can affect the edit.",
+			"Use the raw lines from read_code_imports to decide whether an import edit is needed, then include all required import and code changes in one edit call when possible.",
+		],
+		parameters: readCodeImportsSchema,
+		async execute(_id, input, signal, _onUpdate, ctx) { return executeReadCodeImports(input, signal, ctx); },
+	});
+}

package/src/read-symbol.ts

@@ -9,15 +9,18 @@ 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." })),
+	mode: Type.Union([Type.Literal("symbol"), Type.Literal("outline")], { description: 'Required operation. Use "symbol" to read one declaration (and provide symbol or line); use "outline" only to list declaration names and ranges.' }),
+	line: Type.Optional(Type.Integer({ minimum: 1, description: 'With mode="symbol", 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." })),
+	symbol: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: 'With mode="symbol", the exact symbol name or qualified name, for example Server.run. A symbol or line selector is required in symbol mode.' })),
 	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)." })),
+	context: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Extra whole lines before and after the selected symbol (default 0, max 20)." })),
 	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>;
+type RegisteredReadSymbolInput = Static<typeof readSymbolSchema>;
+/** mode stays optional here so stored calls from releases before explicit modes remain verifiable. */
+export type ReadSymbolInput = Omit<RegisteredReadSymbolInput, "mode"> & { mode?: RegisteredReadSymbolInput["mode"] };
 
 export interface VisibleSource {
 	startLine: number;
@@ -48,12 +51,15 @@ export function validateReadSymbolInput(input: ReadSymbolInput): void {
 		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.mode !== undefined && input.mode !== "symbol" && input.mode !== "outline") throw new Error('read_symbol mode must be "symbol" or "outline".');
 	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.");
+	if (input.mode === "symbol" && input.line === undefined && input.symbol === undefined) throw new Error('read_symbol mode="symbol" requires a symbol name or containing line.');
+	if (input.mode === "outline" && (input.line !== undefined || input.symbol !== undefined || input.parent !== undefined || input.context !== undefined)) throw new Error('read_symbol mode="outline" does not accept symbol, line, parent, or context.');
+	if ((input.parent || input.context) && input.line === undefined && input.symbol === undefined) throw new Error("read_symbol parent/context requires a line or symbol selector.");
 }
 
 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 })}`;
+	return `- ${label(symbol.qualifiedName)} (${symbol.kind}), lines ${symbol.startLine}-${symbol.endLine}. ${callText({ path, mode: "symbol", 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. */
@@ -99,7 +105,7 @@ function selectSymbol(input: ReadSymbolInput, symbols: SourceSymbol[]): SourceSy
 			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 })}.`,
+			`Next: choose a candidate call above, or list the outline with ${callText({ path: input.path, mode: "outline" })}.`,
 		].join("\n"));
 	}
 	let selected = matches[0];
@@ -133,7 +139,7 @@ export async function buildSymbolRead(input: ReadSymbolInput, content: string, s
 	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) {
+	if (input.mode === "outline" || (input.mode === undefined && 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[] = [];
@@ -201,11 +207,12 @@ export async function executeReadSymbol(input: ReadSymbolInput, signal: AbortSig
 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",
+		description: `Read a complete function, method, class, or type from a local source file. Always set mode: use mode="symbol" with an exact symbol name or containing line; use mode="outline" only to list names and ranges. Supports ${SUPPORTED_LANGUAGES}. 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 one whole source symbol by line/name; set mode=outline only to list declarations",
 		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.",
+			"Always set read_symbol mode. Use mode=\"symbol\" with a symbol name or containing line to read source; mode=\"outline\" only lists declarations and does not read their bodies.",
+			"Use read_symbol with mode=\"symbol\", 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 mode=\"symbol\" and symbol for an exact name or qualified name. 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,

package/src/source-file.ts

@@ -5,7 +5,7 @@ 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> {
+export async function readSource(path: string, signal?: AbortSignal, toolName = "read_symbol"): Promise<string> {
 	signal?.throwIfAborted();
 	const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
 	try {
@@ -21,7 +21,7 @@ export async function readSource(path: string, signal?: AbortSignal): Promise<st
 			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.");
+		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 ${toolName}.`);
 		const bytes = buffer.subarray(0, length);
 		let content: string;
 		try { content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
@@ -35,7 +35,7 @@ export async function readSource(path: string, signal?: AbortSignal): Promise<st
 }
 
 /** Only inspect a bounded number of siblings; never perform a hidden repo scan. */
-export async function sourceReadError(path: string, error: unknown): Promise<string> {
+export async function sourceReadError(path: string, error: unknown, toolName = "read_symbol"): 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}`];
@@ -52,9 +52,11 @@ export async function sourceReadError(path: string, error: unknown): Promise<str
 		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.");
+		lines.push(`Verify the path and retry ${toolName}; 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.");
+	} else lines.push(toolName === "read_symbol"
+		? "Use read for ordinary text, images, or bounded line ranges; no symbol boundaries were returned."
+		: "Use read for ordinary text, images, or bounded line ranges; no import lines were returned.");
 	return lines.join("\n");
 }