@shanepadgett/tau-agent 0.26.0 → 0.27.0

package/extensions/explore/ast-tools.ts

@@ -1,35 +1,56 @@
-import {
-	DEFAULT_MAX_BYTES,
-	DEFAULT_MAX_LINES,
-	defineTool,
-	formatSize,
-	keyHint,
-	truncateHead,
-	type Theme,
-} from "@earendil-works/pi-coding-agent";
+import { defineTool, formatSize, keyHint, type Theme } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
-import { stat } from "node:fs/promises";
-import { basename, extname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
 import { Type } from "typebox";
+import {
+	BoundedTextResultBuilder,
+	truncateBoundedHead,
+	type BoundedTextOverflowDetails,
+} from "../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../shared/temporary-output-store.ts";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
+import { applyExactSourceMutations, type ApplyPatchSummary } from "../patch/executor.ts";
+import {
+	AST_LANGUAGE_REGISTRY,
+	astLanguageForPath,
+	formatAstLanguageLabels,
+	requireAstLanguageForPath,
+	type AstLanguage,
+} from "./ast-languages.ts";
+import type { OrientationState } from "./orientation-state.ts";
 import { formatPathForDisplay, resolveExplorePath, stripLeadingAt } from "./path-display.ts";
-import type {
-	AstClient,
-	AstLanguage,
-	OutlineEntry,
-	OutlineFileResult,
-	SourceRange,
-	OutlineTarget,
-	OutlineTargetResult,
-	SymbolBatchResult,
-	SymbolView,
+import {
+	AstWorkerError,
+	type ApiCandidate,
+	type ApiDeclarationKind,
+	type ApiDiscoveryResult,
+	type ApiQuery,
+	type ApiSurfaceFilter,
+	type AstSearchResult,
+	type AstClient,
+	type EditOperation,
+	type EditPlanResult,
+	type OutlineEntry,
+	type OutlineFileResult,
+	type SourceRange,
+	type OutlineTarget,
+	type OutlineTargetResult,
+	type RecursiveOutlineSummary,
+	type RelationshipOperation,
+	type RelationshipResult,
+	type SymbolBatchResult,
+	type SymbolView,
 } from "./ast-worker.ts";
 
+const supportedLanguageLabels = formatAstLanguageLabels(AST_LANGUAGE_REGISTRY, "or");
+
 const outlineParams = Type.Object(
 	{
 		path: Type.String({
-			description: "TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, or Markdown source file or directory",
+			description: `${supportedLanguageLabels} source file or directory`,
 		}),
 		includePrivate: Type.Optional(Type.Boolean({ description: "Include private declarations and members" })),
 		includeDocs: Type.Optional(
@@ -41,6 +62,9 @@ const outlineParams = Type.Object(
 				description: "Exact top-level or member declaration names",
 			}),
 		),
+		recursive: Type.Optional(
+			Type.Boolean({ description: "Recursively outline every supported source file below a directory" }),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -50,9 +74,8 @@ const symbolParams = Type.Object(
 			minItems: 1,
 			description: "Numeric locators shown in parentheses by outline",
 		}),
-		view: StringEnum(["signature", "declaration", "declarationWithImports"] as const, {
-			description:
-				"Source view to retrieve; TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown support selective views",
+		view: StringEnum(["signature", "signatureWithDocs", "declaration", "declarationWithImports"] as const, {
+			description: `Source view to retrieve: signature omits docs and bodies; signatureWithDocs adds attached docs; declaration returns exact source; declarationWithImports adds required imports. ${supportedLanguageLabels} support selective views`,
 		}),
 		contextLines: Type.Optional(
 			Type.Integer({ minimum: 0, description: "Lines of source context before and after each declaration" }),
@@ -60,15 +83,169 @@ const symbolParams = Type.Object(
 	},
 	{ additionalProperties: false },
 );
+const apiDeclarationKinds = [
+	"module",
+	"namespace",
+	"package",
+	"class",
+	"method",
+	"property",
+	"field",
+	"constructor",
+	"enum",
+	"interface",
+	"function",
+	"variable",
+	"constant",
+	"object",
+	"enumMember",
+	"struct",
+	"event",
+	"operator",
+	"typeParameter",
+	"heading",
+] as const satisfies readonly ApiDeclarationKind[];
+const apiDiscoverParams = Type.Object(
+	{
+		path: Type.String({ description: "Repository, package, or subtree directory" }),
+		query: Type.Union([
+			Type.Object(
+				{ kind: Type.Literal("exactName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{ kind: Type.Literal("prefixName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{ kind: Type.Literal("substringName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("fuzzyName"),
+					name: Type.String({ minLength: 1 }),
+					maxCandidates: Type.Integer({ minimum: 1, maximum: 10_000 }),
+					maxWork: Type.Integer({ minimum: 1, maximum: 1_000_000 }),
+				},
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("declarationKind"),
+					declarationKind: StringEnum(apiDeclarationKinds),
+				},
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("documentation"),
+					terms: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+					maxCandidates: Type.Integer({ minimum: 1, maximum: 10_000 }),
+					maxWork: Type.Integer({ minimum: 1, maximum: 1_000_000 }),
+				},
+				{ additionalProperties: false },
+			),
+		]),
+		surface: StringEnum(["all", "public", "private", "sourceExport", "packageSurface"] as const, {
+			description: "Declaration or export surface to search",
+		}),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+	},
+	{ additionalProperties: false },
+);
+const astSearchParams = Type.Object(
+	{
+		path: Type.String({ description: "Supported source file, repository, package, or subtree" }),
+		pattern: Type.String({ minLength: 1, maxLength: 16 * 1024, description: "ast-grep code pattern" }),
+		language: Type.Optional(
+			StringEnum(
+				["typeScript", "tsx", "odin", "go", "rust", "cSharp", "java", "kotlin", "swift", "markdown"] as const,
+				{ description: "Explicit pattern and target language; required for directory targets" },
+			),
+		),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+	},
+	{ additionalProperties: false },
+);
+const relationshipParams = Type.Object(
+	{
+		path: Type.String({ description: "Repository, package, or subtree directory" }),
+		locator: Type.Integer({ minimum: 1, description: "Numeric declaration locator" }),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+	},
+	{ additionalProperties: false },
+);
+const replaceDeclarationParams = Type.Object(
+	{
+		locator: Type.Integer({ minimum: 1, description: "Numeric declaration locator" }),
+		source: Type.String({
+			minLength: 1,
+			description: "One complete replacement declaration or Markdown heading section",
+		}),
+	},
+	{ additionalProperties: false },
+);
+const replaceBodyParams = Type.Object(
+	{
+		locator: Type.Integer({ minimum: 1, description: "Numeric declaration locator" }),
+		body: Type.String({
+			minLength: 1,
+			description: "Complete replacement for the adapter-provided code body or Markdown section content",
+		}),
+	},
+	{ additionalProperties: false },
+);
+const insertDeclarationParams = Type.Object(
+	{
+		locator: Type.Integer({ minimum: 1, description: "Numeric declaration locator" }),
+		position: StringEnum(["before", "after"] as const),
+		source: Type.String({ minLength: 1, description: "One complete declaration to insert" }),
+	},
+	{ additionalProperties: false },
+);
+const renameDeclarationParams = Type.Object(
+	{
+		locator: Type.Integer({ minimum: 1, description: "Numeric declaration locator" }),
+		newName: Type.String({ minLength: 1, description: "One identifier in the target language" }),
+		scope: Type.Union([
+			Type.Object({ kind: Type.Literal("file") }, { additionalProperties: false }),
+			Type.Object(
+				{ kind: Type.Literal("repository"), path: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+		]),
+		includeInferred: Type.Boolean({
+			description: "Update inferred references as well as exact references",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+interface LocatorEditResult {
+	plan: EditPlanResult;
+	mutation: ApplyPatchSummary;
+	invalidatedLocatorIds: number[];
+	freshLocatorIds: number[];
+	verificationDiagnostics: string[];
+}
 
 interface AstToolDetails {
-	kind: "outline" | "symbol";
-	result: OutlineTargetResult | SymbolBatchResult;
+	kind: "outline" | "symbol" | "apiDiscover" | "astSearch" | "relationship" | "locatorEdit";
+	result:
+		| OutlineTargetResult
+		| SymbolBatchResult
+		| ApiDiscoveryResult
+		| AstSearchResult
+		| RelationshipResult
+		| LocatorEditResult
+		| { path: string; summary: RecursiveOutlineSummary; visibleFiles: string[] };
 	declarationCount: number;
 	sourceBytes: number;
 	returnedBytes: number;
 	avoidedBytes: number;
 	truncated: boolean;
+	overflow: BoundedTextOverflowDetails | undefined;
 }
 
 interface LocatorRecord {
@@ -81,9 +258,21 @@ interface LocatorRecord {
 	generation: number;
 }
 
-type OutlineArgs = { path: string; includePrivate?: boolean; includeDocs?: boolean; names?: string[] };
+type OutlineArgs = {
+	path: string;
+	includePrivate?: boolean;
+	includeDocs?: boolean;
+	names?: string[];
+	recursive?: boolean;
+};
 
-export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
+export function createAstTools(
+	client: AstClient,
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	orientation: OrientationState,
+	emitMutation: (toolCallId: string, cwd: string, summary: ApplyPatchSummary) => void,
+) {
 	const locators = new Map<number, LocatorRecord>();
 	let nextLocator = 1;
 
@@ -93,14 +282,15 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		declarationCount: number,
 		kind: AstToolDetails["kind"],
 		result: OutlineTargetResult | SymbolBatchResult,
-	): { text: string; details: AstToolDetails } {
-		const truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	): { text: string; visibleText: string; details: AstToolDetails } {
+		const truncation = truncateBoundedHead(text);
 		const returned = truncation.truncated
 			? `${truncation.content}\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)})]`
 			: truncation.content;
 		const returnedBytes = Buffer.byteLength(returned);
 		return {
 			text: returned,
+			visibleText: truncation.content,
 			details: {
 				kind,
 				result,
@@ -109,18 +299,23 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				returnedBytes,
 				avoidedBytes: Math.max(0, sourceBytes - returnedBytes),
 				truncated: truncation.truncated,
+				overflow: undefined,
 			},
 		};
 	}
 
 	function locator(entry: OutlineEntry, path: string): number {
 		if (!entry.locator) throw new Error(`Structural outline row ${entry.name} has no symbol locator`);
+		return registerLocator(entry.locator, path, entry.name);
+	}
+
+	function registerLocator(token: string, path: string, name: string): number {
 		const id = nextLocator++;
 		const record = {
 			id,
-			token: entry.locator,
+			token,
 			path: resolve(path),
-			name: entry.name,
+			name,
 			stale: false,
 			declarationRetrieved: false,
 			generation: client.getGeneration(),
@@ -129,6 +324,44 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		return id;
 	}
 
+	function editableLocator(id: number): LocatorRecord {
+		const record = locators.get(id);
+		if (!record) throw new Error(`Unknown declaration locator: ${id}. Run outline or api_discover again.`);
+		if (record.stale || record.generation !== client.getGeneration()) {
+			throw new Error(`Declaration locator ${id} is stale. Run outline or api_discover again.`);
+		}
+		return record;
+	}
+
+	function renderApiCandidate(candidate: ApiCandidate, id: number, cwd: string): string {
+		const lines = [
+			`${formatPathForDisplay(candidate.definingFile, cwd)}:${displayLineRange(candidate.range)}(${id}): ${candidate.name} — ${candidate.symbolType}`,
+			...candidate.signature
+				.trim()
+				.split("\n")
+				.map((line) => `  ${line}`),
+		];
+		const surface: string[] = [];
+		if (candidate.visibility !== "public") surface.push(`visibility=${candidate.visibility}`);
+		if (candidate.sourceExport !== "yes") surface.push(`sourceExport=${candidate.sourceExport}`);
+		if (candidate.packageSurface !== "yes") surface.push(`packageSurface=${candidate.packageSurface}`);
+		if (candidate.internalOnly !== "no") surface.push(`internalOnly=${candidate.internalOnly}`);
+		if (surface.length > 0) lines.push(`  surface: ${surface.join(", ")}`);
+		if (candidate.callerAccess) {
+			lines.push(
+				`  caller: ${candidate.callerAccess.importStatement} use ${candidate.callerAccess.accessExpression}`,
+			);
+		}
+		if (candidate.reExportChain.length > 1) lines.push(`  re-exports: ${candidate.reExportChain.join(" -> ")}`);
+		if (candidate.provenance !== "exact" || candidate.certainty !== "certain" || candidate.certaintyReason) {
+			const resolution = [`provenance=${candidate.provenance}`, `parse=${candidate.certainty}`];
+			if (candidate.certaintyReason) resolution.push(candidate.certaintyReason);
+			lines.push(`  resolution: ${resolution.join(", ")}`);
+		}
+		if (candidate.uncertainty) lines.push(`  uncertainty: ${candidate.uncertainty}`);
+		return lines.join("\n");
+	}
+
 	function renderEntry(
 		entry: OutlineEntry,
 		path: string,
@@ -313,11 +546,7 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 	}
 
 	function renderOutlineFile(file: OutlineFileResult, cwd: string, includeHeader: boolean): string[] {
-		const lines = includeHeader
-			? [
-					`${formatPathForDisplay(file.path, cwd)} (${file.language}, ${file.lineCount} lines, ${formatSize(file.byteLength)})`,
-				]
-			: [];
+		const lines = includeHeader ? [formatPathForDisplay(file.path, cwd)] : [];
 		if (file.diagnostics.errorNodes > 0 || file.diagnostics.missingNodes > 0) {
 			lines.push(
 				`warning: parser recovered with ${file.diagnostics.errorNodes} ERROR and ${file.diagnostics.missingNodes} MISSING nodes`,
@@ -465,34 +694,195 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		name: "outline",
 		label: "outline",
 		description:
-			"Inspect public declarations in one supported source file or non-recursive package directory without returning implementation bodies. Parenthesized numbers are locators for symbol.",
+			"Inspect declarations in one supported source file, one non-recursive package directory, or a recursive mixed-language subtree without returning implementation bodies. Parenthesized numbers are locators for symbol.",
 		promptSnippet: "Inspect public declarations and get symbol locators without reading implementation bodies",
 		promptGuidelines: [
-			"Use a public package outline first to discover reusable APIs; add exact names when likely symbols are known.",
-			"Set includePrivate when internal implementation discovery is needed.",
-			"Leave includeDocs off for routine exploration; enable it when documentation comments are needed.",
+			"Set recursive=true to orient an unfamiliar repository or subtree across supported languages.",
+			"Leave includePrivate off for surface discovery; enable it only for targeted internal implementation work.",
+			"Leave includeDocs off when names and signatures answer the question; enable it only when documentation comments matter.",
 			"Treat each parenthesized number after a line range as that declaration's symbol locator.",
+			"Use symbol(signatureWithDocs) only when one selected contract needs its attached documentation.",
 			"Use symbol with several locators when complete declaration source is needed.",
 		],
 		parameters: outlineParams,
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const path = resolveExplorePath(ctx.cwd, params.path);
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const path = await realpath(resolveExplorePath(ctx.cwd, params.path));
 			const metadata = await stat(path);
+			if (params.recursive) {
+				if (!metadata.isDirectory()) throw new Error("recursive outline requires a directory target");
+				const names = params.names ?? [];
+				const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+				const filesByPath = new Map<
+					string,
+					{ file: OutlineFileResult; locatorIds: number[]; renderedBytes: number }
+				>();
+				const allLocatorIds = new Set<number>();
+				const fatalFallbacks: Array<{
+					path: string;
+					fingerprint: string;
+					message: string;
+					code: "outlineFailed" | "resultFrameTooLarge";
+				}> = [];
+				let declarationCount = 0;
+				try {
+					const summary = await client.outlineRecursive(
+						path,
+						params.includePrivate ?? false,
+						params.includeDocs ?? false,
+						names,
+						{
+							async onFile(_relativePath, file) {
+								const firstLocator = nextLocator;
+								const block = renderOutlineFile(file, ctx.cwd, true).join("\n");
+								const fileLocatorIds = Array.from(
+									{ length: nextLocator - firstLocator },
+									(_, index) => firstLocator + index,
+								);
+								filesByPath.set(file.path, {
+									file,
+									locatorIds: fileLocatorIds,
+									renderedBytes: Buffer.byteLength(block),
+								});
+								for (const id of fileLocatorIds) allLocatorIds.add(id);
+								declarationCount += file.items.reduce(
+									(count, item) => count + (item.rowKind === "declaration" ? 1 + item.members.length : 0),
+									0,
+								);
+								await builder.appendBlock(file.path, formatPathForDisplay(file.path, ctx.cwd), block);
+							},
+							async onDiagnostic(diagnostic) {
+								if (
+									(diagnostic.code === "outlineFailed" || diagnostic.code === "resultFrameTooLarge") &&
+									diagnostic.sourceFingerprint
+								) {
+									fatalFallbacks.push({
+										path: resolve(path, diagnostic.relativePath),
+										fingerprint: diagnostic.sourceFingerprint,
+										message: diagnostic.message,
+										code: diagnostic.code,
+									});
+								}
+								const language = diagnostic.language ? ` (${diagnostic.language})` : "";
+								await builder.appendBlock(
+									undefined,
+									diagnostic.relativePath,
+									`diagnostic: ${diagnostic.relativePath}${language} [${diagnostic.code}]: ${diagnostic.message}`,
+								);
+							},
+						},
+						signal,
+					);
+					const exceptionLines = exceptionSummaryLines([
+						...(summary.failedFiles > 0 ||
+						summary.unreadableFiles > 0 ||
+						summary.oversizedFiles > 0 ||
+						summary.parserDegradedFiles > 0
+							? [
+									`exceptions: ${summary.failedFiles} failed, ${summary.unreadableFiles} unreadable, ${summary.oversizedFiles} oversized, parser degraded ${summary.parserDegradedFiles}`,
+								]
+							: []),
+						...limitReachedLine([
+							...(summary.fileLimitReached ? ["file count"] : []),
+							...(summary.sourceByteLimitReached ? ["source bytes"] : []),
+							...(summary.depthLimitReached ? ["depth"] : []),
+							...(summary.elapsedLimitReached ? ["elapsed time"] : []),
+						]),
+					]);
+					if (exceptionLines) await builder.appendRequiredBlock("recursive outline exceptions", exceptionLines);
+					const bounded = await builder.finish();
+					if (!bounded.overflow.fullOutputComplete) {
+						const visible = new Set(bounded.visibleUnitIds);
+						for (const [file, { locatorIds: ids }] of filesByPath) {
+							if (visible.has(file)) continue;
+							for (const id of ids) locators.delete(id);
+						}
+					}
+					const returnedBytes = Buffer.byteLength(bounded.content);
+					orientation.recordAttempts(
+						[...filesByPath.values()].map((record) => ({
+							path: record.file.path,
+							toolCallId,
+							fingerprint: record.file.sourceFingerprint,
+							kind: "directOutline",
+							sourceBytesDeflected: Math.max(0, record.file.byteLength - record.renderedBytes),
+						})),
+					);
+					for (const fallback of fatalFallbacks) {
+						orientation.recordFatal({
+							...fallback,
+							includePrivate: params.includePrivate ?? false,
+							names,
+						});
+					}
+					if (bounded.overflow.temporaryPath) {
+						orientation.recordTemporaryOutput(bounded.overflow.temporaryPath);
+					}
+					orientation.recordOutlineTelemetry(toolCallId, {
+						workerInputBytes: summary.totalByteLength,
+						completeRenderedBytes: bounded.overflow.totalBytes,
+						modelVisibleAstBytes: returnedBytes,
+						temporaryOutputBytes: bounded.overflow.temporaryPath ? bounded.overflow.totalBytes : 0,
+					});
+					return {
+						content: [{ type: "text", text: bounded.content }],
+						details: {
+							kind: "outline",
+							result: { path, summary, visibleFiles: bounded.visibleUnitIds },
+							declarationCount,
+							sourceBytes: summary.totalByteLength,
+							returnedBytes,
+							avoidedBytes: Math.max(0, summary.totalByteLength - returnedBytes),
+							truncated: bounded.overflow.truncated,
+							overflow: bounded.overflow,
+						},
+					};
+				} catch (error) {
+					await builder.abort();
+					for (const id of allLocatorIds) locators.delete(id);
+					throw error;
+				}
+			}
 			const target: OutlineTarget = metadata.isDirectory()
 				? { kind: "directory", path }
-				: { kind: "file", path, language: languageForPath(path) };
+				: { kind: "file", path, language: requireAstLanguageForPath(path) };
 			const names = params.names ?? [];
-			const result = await client.outline(
-				target,
-				params.includePrivate ?? false,
-				params.includeDocs ?? false,
-				names,
-				signal,
-			);
-			const lines = result.files.flatMap((file, index) => [
-				...(index === 0 ? [] : [""]),
-				...renderOutlineFile(file, ctx.cwd, result.files.length > 1),
-			]);
+			let result: OutlineTargetResult;
+			try {
+				result = await client.outline(
+					target,
+					params.includePrivate ?? false,
+					params.includeDocs ?? false,
+					names,
+					signal,
+				);
+			} catch (error) {
+				if (
+					target.kind === "file" &&
+					error instanceof AstWorkerError &&
+					(error.code === "outline_failed" || error.code === "response_too_large") &&
+					error.sourceFingerprint
+				) {
+					orientation.recordFatal({
+						path,
+						fingerprint: error.sourceFingerprint,
+						includePrivate: params.includePrivate ?? false,
+						names,
+						code: error.code,
+						message: error.message,
+					});
+				}
+				throw error;
+			}
+			const renderedFiles = result.files.map((file) => {
+				const firstLocator = nextLocator;
+				const text = renderOutlineFile(file, ctx.cwd, result.files.length > 1).join("\n");
+				return {
+					file,
+					text,
+					locatorIds: Array.from({ length: nextLocator - firstLocator }, (_, index) => firstLocator + index),
+				};
+			});
+			const lines = renderedFiles.flatMap((file, index) => [...(index === 0 ? [] : [""]), file.text]);
 			const declarationCount = result.files.reduce(
 				(count, file) =>
 					count +
@@ -503,7 +893,26 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				0,
 			);
 			if (declarationCount === 0) lines.push(names.length > 0 ? "No matching declarations" : "No declarations");
-			const output = compact(lines.join("\n"), result.totalByteLength, declarationCount, "outline", result);
+			const completeText = lines.join("\n");
+			const output = compact(completeText, result.totalByteLength, declarationCount, "outline", result);
+			orientation.recordAttempts(
+				renderedFiles.map((rendered) => {
+					const renderedBytes = Buffer.byteLength(rendered.text);
+					return {
+						path: rendered.file.path,
+						toolCallId,
+						fingerprint: rendered.file.sourceFingerprint,
+						kind: "directOutline" as const,
+						sourceBytesDeflected: Math.max(0, rendered.file.byteLength - renderedBytes),
+					};
+				}),
+			);
+			orientation.recordOutlineTelemetry(toolCallId, {
+				workerInputBytes: result.totalByteLength,
+				completeRenderedBytes: Buffer.byteLength(completeText),
+				modelVisibleAstBytes: output.details.returnedBytes,
+				temporaryOutputBytes: 0,
+			});
 			return { content: [{ type: "text", text: output.text }], details: output.details };
 		},
 		renderCall(args, theme, context) {
@@ -531,10 +940,10 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		name: "symbol",
 		label: "symbol",
 		description:
-			"Return exact declaration source for one or more numeric outline locators, with optional surrounding lines; stale locators fail atomically.",
-		promptSnippet: "Retrieve exact declaration source for several outline locators",
+			"Return signatures, documented signatures, exact declarations, or declarations with required imports for numeric outline locators; stale locators fail atomically.",
+		promptSnippet: "Retrieve signatures or exact declarations for several outline locators",
 		parameters: symbolParams,
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			if (params.contextLines !== undefined && params.view !== "declaration") {
 				throw new Error("contextLines is supported only with view=declaration");
 			}
@@ -553,6 +962,15 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				params.contextLines ?? 0,
 				signal,
 			);
+			orientation.recordAttempts(
+				result.declarations.map((declaration) => ({
+					path: declaration.path,
+					fingerprint: declaration.sourceFingerprint,
+					kind: "symbol" as const,
+					toolCallId,
+					sourceBytesDeflected: 0,
+				})),
+			);
 			const requestedByToken = new Map<string, LocatorRecord[]>();
 			for (const record of records) {
 				const requested = requestedByToken.get(record.token);
@@ -572,6 +990,12 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				lines.push(
 					...(includePaths ? [formatPathForDisplay(block.path, ctx.cwd)] : []),
 					`${lineRange}(${represented.map((record) => record.id).join(",")}): ${represented.map((record) => record.name).join(", ")}`,
+					...block.declarationIndexes.flatMap((index) => {
+						const declaration = result.declarations[index];
+						if (!declaration) return [];
+						const ids = (requestedByToken.get(declaration.locator) ?? []).map((record) => record.id).join(",");
+						return declaration.diagnostics.map((diagnostic) => `warning (${ids}): ${diagnostic}`);
+					}),
 					block.source,
 				);
 			}
@@ -605,22 +1029,747 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		},
 	});
 
+	async function executeLocatorEdit(
+		toolCallId: string,
+		locatorId: number,
+		edit: EditOperation,
+		signal: AbortSignal | undefined,
+		cwd: string,
+	): Promise<{ content: Array<{ type: "text"; text: string }>; details: AstToolDetails }> {
+		const record = editableLocator(locatorId);
+		const plan = await client.planEdit(record.token, edit, signal);
+		const mutation = await applyExactSourceMutations(cwd, plan.files, signal);
+		if (mutation.changes.length === 0) {
+			const message = mutation.failures.map((failure) => failure.message).join("; ") || "No files changed.";
+			throw new Error(`Locator edit failed: ${message}`);
+		}
+
+		const changedPaths = new Set(mutation.changes.map((change) => resolve(cwd, change.path)));
+		const invalidatedLocatorIds: number[] = [];
+		for (const candidate of locators.values()) {
+			if (changedPaths.has(candidate.path) && !candidate.stale) {
+				candidate.stale = true;
+				invalidatedLocatorIds.push(candidate.id);
+			}
+		}
+		orientation.invalidate([...changedPaths]);
+		emitMutation(toolCallId, cwd, mutation);
+
+		const verificationDiagnostics: string[] = [];
+		const verifiedTokens = new Set<string>();
+		if (mutation.status === "completed") {
+			for (const filePlan of plan.files) {
+				try {
+					const reparsed = await client.outline(
+						{ kind: "file", path: filePlan.path, language: requireAstLanguageForPath(filePlan.path) },
+						true,
+						false,
+						[],
+						signal,
+					);
+					const file = reparsed.files[0];
+					if (!file || file.sourceFingerprint !== sourceFingerprintForPlan(filePlan.source)) {
+						verificationDiagnostics.push(`${filePlan.path}: post-mutation fingerprint did not match the plan`);
+						continue;
+					}
+					if (file.diagnostics.errorNodes > 0 || file.diagnostics.missingNodes > 0) {
+						verificationDiagnostics.push(
+							`${filePlan.path}: parser recovered with ${file.diagnostics.errorNodes} ERROR and ${file.diagnostics.missingNodes} MISSING nodes`,
+						);
+						continue;
+					}
+					for (const item of file.items) {
+						if (item.certainty === "certain" && item.locator) verifiedTokens.add(item.locator);
+						for (const member of item.members) {
+							if (member.certainty === "certain" && member.locator) verifiedTokens.add(member.locator);
+						}
+					}
+				} catch (error) {
+					verificationDiagnostics.push(
+						`${filePlan.path}: post-mutation reparse failed: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+		}
+		const freshLocatorIds = plan.freshLocators
+			.filter((fresh) => verifiedTokens.has(fresh.locator))
+			.map((fresh) => registerLocator(fresh.locator, fresh.path, fresh.name));
+		const freshTargetId = freshLocatorIds[0];
+
+		const lines = [
+			`changed: ${mutation.changes.map((change) => change.path).join(", ")}`,
+			`invalidated locators: ${invalidatedLocatorIds.join(", ") || "none"}; fresh locators: ${freshLocatorIds.map((id) => `(${id})`).join(", ") || "none"}; skipped impacts: ${plan.skippedImpacts.length}; status: ${mutation.status}`,
+		];
+		for (const skipped of plan.skippedImpacts) {
+			const candidateIds = skipped.candidateLocators.flatMap((token, candidateIndex) => {
+				if (token === record.token && freshTargetId !== undefined) return [freshTargetId];
+				const existing = [...locators.values()].find((candidate) => candidate.token === token && !candidate.stale);
+				if (existing) return [existing.id];
+				const candidatePath = skipped.candidatePaths[candidateIndex];
+				return candidatePath && !changedPaths.has(resolve(candidatePath))
+					? [registerLocator(token, candidatePath, "rename candidate")]
+					: [];
+			});
+			lines.push(
+				`skipped: ${formatPathForDisplay(skipped.path, cwd)}:${displayLineRange(skipped.range)} [${skipped.reason}]${candidateIds.length > 0 ? ` candidates ${candidateIds.map((id) => `(${id})`).join(", ")}` : ""}`,
+			);
+		}
+		for (const diagnostic of verificationDiagnostics) lines.push(`warning: ${diagnostic}`);
+		const text = lines.join("\n");
+		const sourceBytes = plan.files.reduce((total, file) => total + Buffer.byteLength(file.source), 0);
+		const returnedBytes = Buffer.byteLength(text);
+		return {
+			content: [{ type: "text", text }],
+			details: {
+				kind: "locatorEdit",
+				result: { plan, mutation, invalidatedLocatorIds, freshLocatorIds, verificationDiagnostics },
+				declarationCount: freshLocatorIds.length,
+				sourceBytes,
+				returnedBytes,
+				avoidedBytes: Math.max(0, sourceBytes - returnedBytes),
+				truncated: false,
+				overflow: undefined,
+			},
+		};
+	}
+
+	const replaceDeclaration = defineTool<typeof replaceDeclarationParams, AstToolDetails>({
+		name: "replace_declaration",
+		label: "replace_declaration",
+		description:
+			"Replace one complete declaration through its stale-safe numeric locator. Code must parse as one declaration in the current parent container. A Markdown heading locator replaces the heading and its entire section, including deeper subsections, and requires one root heading at the same depth.",
+		promptSnippet: "Replace one complete declaration by structural locator",
+		parameters: replaceDeclarationParams,
+		executionMode: "sequential",
+		execute(toolCallId, params, signal, _onUpdate, ctx) {
+			return executeLocatorEdit(
+				toolCallId,
+				params.locator,
+				{ kind: "replaceDeclaration", source: params.source },
+				signal,
+				ctx.cwd,
+			);
+		},
+		renderCall(args, theme, context) {
+			return locatorEditCall("replace_declaration", args.locator, locators, rowState, theme, context);
+		},
+		renderResult(result, options, theme, context) {
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const replaceBody = defineTool<typeof replaceBodyParams, AstToolDetails>({
+		name: "replace_body",
+		label: "replace_body",
+		description:
+			"Replace exactly the reliable adapter-provided body range while preserving its signature and attached metadata. For a Markdown heading locator, preserve the heading and replace its section content; nested headings must be deeper than the selected heading.",
+		promptSnippet: "Replace one executable body by structural locator",
+		parameters: replaceBodyParams,
+		executionMode: "sequential",
+		execute(toolCallId, params, signal, _onUpdate, ctx) {
+			return executeLocatorEdit(
+				toolCallId,
+				params.locator,
+				{ kind: "replaceBody", body: params.body },
+				signal,
+				ctx.cwd,
+			);
+		},
+		renderCall(args, theme, context) {
+			return locatorEditCall("replace_body", args.locator, locators, rowState, theme, context);
+		},
+		renderResult(result, options, theme, context) {
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const insertDeclaration = defineTool<typeof insertDeclarationParams, AstToolDetails>({
+		name: "insert_declaration",
+		label: "insert_declaration",
+		description:
+			"Insert exactly one declaration immediately before or after a declaration locator in its current parent container.",
+		promptSnippet: "Insert one declaration adjacent to a structural locator",
+		parameters: insertDeclarationParams,
+		executionMode: "sequential",
+		execute(toolCallId, params, signal, _onUpdate, ctx) {
+			return executeLocatorEdit(
+				toolCallId,
+				params.locator,
+				{ kind: "insertDeclaration", position: params.position, source: params.source },
+				signal,
+				ctx.cwd,
+			);
+		},
+		renderCall(args, theme, context) {
+			return locatorEditCall("insert_declaration", args.locator, locators, rowState, theme, context, args.position);
+		},
+		renderResult(result, options, theme, context) {
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const renameDeclaration = defineTool<typeof renameDeclarationParams, AstToolDetails>({
+		name: "rename_declaration",
+		label: "rename_declaration",
+		description:
+			"Rename one declaration and exact references within an explicit file or repository scope. Inferred references require includeInferred=true; ambiguous references remain unchanged.",
+		promptSnippet: "Rename one declaration through stale-safe structural identity",
+		parameters: renameDeclarationParams,
+		executionMode: "sequential",
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const scope =
+				params.scope.kind === "repository"
+					? { kind: "repository" as const, path: await realpath(resolveExplorePath(ctx.cwd, params.scope.path)) }
+					: { kind: "file" as const };
+			return executeLocatorEdit(
+				toolCallId,
+				params.locator,
+				{ kind: "renameDeclaration", newName: params.newName, scope, includeInferred: params.includeInferred },
+				signal,
+				ctx.cwd,
+			);
+		},
+		renderCall(args, theme, context) {
+			return locatorEditCall(
+				"rename_declaration",
+				args.locator,
+				locators,
+				rowState,
+				theme,
+				context,
+				`${args.newName} ${args.scope.kind}${args.includeInferred ? " inferred" : ""}`,
+			);
+		},
+		renderResult(result, options, theme, context) {
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const apiDiscover = defineTool<typeof apiDiscoverParams, AstToolDetails>({
+		name: "api_discover",
+		label: "api_discover",
+		description:
+			"Discover declarations and supported caller import paths across a canonical repository, package, or subtree without returning implementation bodies. Results include numeric symbol locators.",
+		promptSnippet: "Find reusable declarations and caller import paths across a repository or subtree",
+		promptGuidelines: [
+			"Use api_discover when reuse intent is known but the declaration path or exact name is not.",
+			"Choose exactly one query kind and keep fuzzy or documentation work limits narrow.",
+			"Use packageSurface when the caller needs a supported public import path.",
+			"Treat a clear candidate signature as sufficient; retrieve a selected locator with symbol only when its contract or implementation needs closer inspection.",
+		],
+		parameters: apiDiscoverParams,
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const path = await realpath(resolveExplorePath(ctx.cwd, params.path));
+			if (!(await stat(path)).isDirectory()) throw new Error("api_discover requires a directory scope");
+			const result = await client.discoverApi(
+				path,
+				params.query as ApiQuery,
+				params.surface as ApiSurfaceFilter,
+				params.resultLimit,
+				signal,
+			);
+			orientation.recordAttempts(
+				result.candidates.map((candidate) => ({
+					path: candidate.definingFile,
+					fingerprint: candidate.sourceFingerprint,
+					kind: "apiCandidate" as const,
+					toolCallId,
+					sourceBytesDeflected: 0,
+				})),
+			);
+			const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+			const locatorByUnit = new Map<string, number>();
+			try {
+				for (const [index, candidate] of result.candidates.entries()) {
+					const id = registerLocator(candidate.locator, candidate.definingFile, candidate.name);
+					const unit = `${candidate.definingFile}:${candidate.range.startByte}:${index}`;
+					locatorByUnit.set(unit, id);
+					await builder.appendBlock(unit, candidate.name, renderApiCandidate(candidate, id, ctx.cwd));
+				}
+				if (result.candidates.length === 0)
+					await builder.appendRequiredBlock("no matches", "No matching declarations");
+				const summary = result.summary;
+				const exceptionLines = exceptionSummaryLines([
+					...(summary.omittedCandidates > 0
+						? [`${summary.omittedCandidates} candidates omitted (result limit ${summary.resultLimit})`]
+						: []),
+					...(summary.resolutionDiagnostics > 0
+						? [`resolution diagnostics: ${summary.resolutionDiagnostics}`]
+						: []),
+					...limitReachedLine([
+						...(summary.candidateLimitReached ? ["query candidates"] : []),
+						...(summary.workLimitReached ? ["query work"] : []),
+						...(summary.fileLimitReached ? ["files"] : []),
+						...(summary.sourceByteLimitReached ? ["source bytes"] : []),
+						...(summary.depthLimitReached ? ["depth"] : []),
+						...(summary.elapsedLimitReached ? ["elapsed time"] : []),
+					]),
+				]);
+				if (exceptionLines) await builder.appendRequiredBlock("API discovery exceptions", exceptionLines);
+				const bounded = await builder.finish();
+				if (!bounded.overflow.fullOutputComplete) {
+					const visible = new Set(bounded.visibleUnitIds);
+					for (const [unit, id] of locatorByUnit) if (!visible.has(unit)) locators.delete(id);
+				}
+				if (bounded.overflow.temporaryPath) orientation.recordTemporaryOutput(bounded.overflow.temporaryPath);
+				const returnedBytes = Buffer.byteLength(bounded.content);
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						kind: "apiDiscover",
+						result,
+						declarationCount: result.candidates.length,
+						sourceBytes: summary.totalSourceBytes,
+						returnedBytes,
+						avoidedBytes: Math.max(0, summary.totalSourceBytes - returnedBytes),
+						truncated: bounded.overflow.truncated,
+						overflow: bounded.overflow,
+					},
+				};
+			} catch (error) {
+				await builder.abort();
+				for (const id of locatorByUnit.values()) locators.delete(id);
+				throw error;
+			}
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const query = formatApiQuery(args.query as ApiQuery);
+			const component =
+				(context.lastComponent as AstCallComponent | undefined) ??
+				new AstCallComponent(
+					rowState,
+					context.toolCallId,
+					"api_discover",
+					[stripLeadingAt(args.path)],
+					[`[${query} ${args.surface} limit=${args.resultLimit}]`],
+					theme,
+				);
+			component.set([stripLeadingAt(args.path)], [`[${query} ${args.surface} limit=${args.resultLimit}]`], theme);
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const astSearch = defineTool<typeof astSearchParams, AstToolDetails>({
+		name: "ast_search",
+		label: "ast_search",
+		description:
+			"Search one canonical source file, repository, package, or subtree with an ast-grep code pattern. Returns bounded deterministic matches, metavariable bindings, parser certainty, and numeric locators for exact source or enclosing scopes.",
+		promptSnippet: "Search repository code shapes with ast-grep patterns and retrievable locators",
+		promptGuidelines: [
+			"Use ast_search for code shapes; use grep for literal text.",
+			"Pass language for repository, package, and subtree targets. Supported files can infer it.",
+			"Use $NAME and $$$NAME metavariables. Keep resultLimit narrow, then retrieve selected numeric locators with symbol(declaration).",
+		],
+		parameters: astSearchParams,
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const path = await realpath(resolveExplorePath(ctx.cwd, params.path));
+			const metadata = await stat(path);
+			const inferred = metadata.isFile() ? astLanguageForPath(path) : undefined;
+			if (metadata.isFile() && !inferred) throw new Error(`Unsupported ast_search file type: ${path}`);
+			if (metadata.isDirectory() && !params.language) {
+				throw new Error("ast_search requires language for repository, package, and subtree targets");
+			}
+			if (inferred && params.language && inferred !== params.language) {
+				throw new Error(`ast_search language ${params.language} does not match ${inferred} target ${path}`);
+			}
+			const language = params.language ?? inferred;
+			if (!language) throw new Error("ast_search could not infer a language; pass language explicitly");
+			const result = await client.search(path, language, params.pattern, params.resultLimit, signal);
+			orientation.recordAttempts([
+				...(metadata.isFile() && result.targetSourceFingerprint
+					? [
+							{
+								path,
+								fingerprint: result.targetSourceFingerprint,
+								kind: "structuralMatch" as const,
+								toolCallId,
+								sourceBytesDeflected: 0,
+							},
+						]
+					: []),
+				...result.matches.map((match) => ({
+					path: metadata.isDirectory() ? resolve(path, match.relativePath) : path,
+					fingerprint: match.sourceFingerprint,
+					kind: "structuralMatch" as const,
+					toolCallId,
+					sourceBytesDeflected: 0,
+				})),
+			]);
+			const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+			const locatorByUnit = new Map<string, number[]>();
+			try {
+				for (const [index, match] of result.matches.entries()) {
+					const sourcePath = metadata.isDirectory() ? resolve(path, match.relativePath) : path;
+					const matchId = registerLocator(match.locator, sourcePath, `match ${match.relativePath}`);
+					const ids = [matchId];
+					const unit = `${match.relativePath}:${match.range.startByte}:${index}`;
+					const lines = [
+						`${match.relativePath}:${displayLineRange(match.range)}(${matchId}) [${match.language}, ${match.certainty}]`,
+						...match.preview.split("\n").map((line) => `  ${line}`),
+					];
+					if (match.previewTruncated) lines.push("  [preview truncated]");
+					for (const binding of match.bindings) {
+						const values = binding.values.map((value) => JSON.stringify(value.preview)).join(", ");
+						lines.push(`  $${binding.name} = ${values}${binding.valuesTruncated ? ", …" : ""}`);
+					}
+					if (match.bindingsTruncated) lines.push("  [bindings truncated]");
+					if (match.certaintyReason) lines.push(`  uncertainty: ${match.certaintyReason}`);
+					if (match.enclosingScope) {
+						const scopeId = registerLocator(
+							match.enclosingScope.locator,
+							sourcePath,
+							match.enclosingScope.astKind,
+						);
+						ids.push(scopeId);
+						lines.push(
+							`  enclosing ${displayLineRange(match.enclosingScope.range)}(${scopeId}): ${match.enclosingScope.astKind}`,
+						);
+					}
+					locatorByUnit.set(unit, ids);
+					await builder.appendBlock(unit, match.relativePath, lines.join("\n"));
+				}
+				if (result.matches.length === 0) await builder.appendRequiredBlock("no matches", "No structural matches");
+				for (const [index, diagnostic] of result.diagnostics.entries()) {
+					await builder.appendBlock(
+						undefined,
+						`diagnostic-${index}`,
+						`diagnostic: ${diagnostic.relativePath} [${diagnostic.code}]: ${diagnostic.message}`,
+					);
+				}
+				const summary = result.summary;
+				const exceptionLines = exceptionSummaryLines([
+					...(summary.matchesFound > summary.matchesReturned
+						? [
+								`${summary.matchesFound - summary.matchesReturned} matches omitted (result limit ${summary.resultLimit})`,
+							]
+						: []),
+					...(summary.unreadableFiles > 0 ||
+					summary.oversizedFiles > 0 ||
+					summary.failedFiles > 0 ||
+					summary.parserDegradedFiles > 0 ||
+					summary.diagnosticsOmitted > 0
+						? [
+								`exceptions: ${summary.unreadableFiles} unreadable, ${summary.oversizedFiles} oversized, ${summary.failedFiles} failed, parser degraded ${summary.parserDegradedFiles}, diagnostics omitted ${summary.diagnosticsOmitted}`,
+							]
+						: []),
+					...limitReachedLine([
+						...(summary.resultLimitReached ? ["results"] : []),
+						...(summary.fileLimitReached ? ["files"] : []),
+						...(summary.sourceByteLimitReached ? ["source bytes"] : []),
+						...(summary.depthLimitReached ? ["depth"] : []),
+						...(summary.elapsedLimitReached ? ["elapsed time"] : []),
+					]),
+				]);
+				if (exceptionLines) await builder.appendRequiredBlock("structural search exceptions", exceptionLines);
+				const bounded = await builder.finish();
+				if (!bounded.overflow.fullOutputComplete) {
+					const visible = new Set(bounded.visibleUnitIds);
+					for (const [unit, ids] of locatorByUnit) {
+						if (!visible.has(unit)) for (const id of ids) locators.delete(id);
+					}
+				}
+				if (bounded.overflow.temporaryPath) orientation.recordTemporaryOutput(bounded.overflow.temporaryPath);
+				const returnedBytes = Buffer.byteLength(bounded.content);
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						kind: "astSearch",
+						result,
+						declarationCount: summary.matchesReturned,
+						sourceBytes: summary.sourceBytes,
+						returnedBytes,
+						avoidedBytes: Math.max(0, summary.sourceBytes - returnedBytes),
+						truncated: bounded.overflow.truncated,
+						overflow: bounded.overflow,
+					},
+				};
+			} catch (error) {
+				await builder.abort();
+				for (const ids of locatorByUnit.values()) for (const id of ids) locators.delete(id);
+				throw error;
+			}
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const options = `[${args.language ?? "infer"} limit=${args.resultLimit}]`;
+			const component =
+				(context.lastComponent as AstCallComponent | undefined) ??
+				new AstCallComponent(
+					rowState,
+					context.toolCallId,
+					"ast_search",
+					[stripLeadingAt(args.path)],
+					[options],
+					theme,
+				);
+			component.set([stripLeadingAt(args.path)], [options], theme);
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	function relationshipTool(name: RelationshipOperation, description: string, guideline: string) {
+		return defineTool<typeof relationshipParams, AstToolDetails>({
+			name,
+			label: name,
+			description,
+			promptSnippet: description,
+			promptGuidelines: [guideline, "Inspect ambiguous candidate locators before selecting an edit target."],
+			parameters: relationshipParams,
+			async execute(toolCallId, params, signal, _onUpdate, ctx) {
+				const path = await realpath(resolveExplorePath(ctx.cwd, params.path));
+				if (!(await stat(path)).isDirectory()) throw new Error(`${name} requires a directory scope`);
+				const record = locators.get(params.locator);
+				if (!record)
+					throw new Error(`Unknown declaration locator: ${params.locator}. Run outline or api_discover again.`);
+				if (record.stale || record.generation !== client.getGeneration()) {
+					throw new Error(`Declaration locator ${params.locator} is stale. Run outline or api_discover again.`);
+				}
+				const result = await client.relationships(path, record.token, name, params.resultLimit, signal);
+				orientation.recordAttempts(
+					result.relationships.flatMap((relationship) => [
+						{
+							path: resolve(path, relationship.relativePath),
+							fingerprint: relationship.sourceFingerprint,
+							kind: "relationshipLocation" as const,
+							toolCallId,
+							sourceBytesDeflected: 0,
+						},
+						{
+							path: relationship.targetPath,
+							fingerprint: relationship.targetSourceFingerprint,
+							kind: "relationshipLocation" as const,
+							toolCallId,
+							sourceBytesDeflected: 0,
+						},
+						...relationship.candidatePaths.flatMap((candidatePath, index) => {
+							const fingerprint = relationship.candidateSourceFingerprints[index];
+							return fingerprint
+								? [
+										{
+											path: candidatePath,
+											fingerprint,
+											kind: "relationshipLocation" as const,
+											toolCallId,
+											sourceBytesDeflected: 0,
+										},
+									]
+								: [];
+						}),
+						{
+							path: resolve(path, relationship.relativePath),
+							fingerprint: relationship.enclosingScope.sourceFingerprint,
+							kind: "relationshipScope" as const,
+							toolCallId,
+							sourceBytesDeflected: 0,
+						},
+					]),
+				);
+				const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+				const locatorByUnit = new Map<string, number[]>();
+				try {
+					for (const [index, relationship] of result.relationships.entries()) {
+						const sourcePath = resolve(path, relationship.relativePath);
+						const targetId =
+							relationship.targetLocator === record.token
+								? record.id
+								: registerLocator(
+										relationship.targetLocator,
+										relationship.targetPath,
+										`${relationship.relationshipKind} target`,
+									);
+						const candidateIds = relationship.candidateLocators.map((token, candidateIndex) =>
+							token === record.token
+								? record.id
+								: registerLocator(
+										token,
+										relationship.candidatePaths[candidateIndex] ?? relationship.targetPath,
+										"relationship candidate",
+									),
+						);
+						const scopeId = registerLocator(
+							relationship.enclosingScope.locator,
+							sourcePath,
+							relationship.enclosingScope.qualifiedIdentity,
+						);
+						const ids = [targetId, ...candidateIds, scopeId];
+						const unit = `${relationship.relativePath}:${relationship.range.startByte}:${index}`;
+						locatorByUnit.set(unit, ids);
+						const kind =
+							relationship.classification === "production"
+								? relationship.relationshipKind
+								: `${relationship.relationshipKind}, ${relationship.classification}`;
+						const certainty = relationship.certainty === "exact" ? "" : `, ${relationship.certainty}`;
+						const lines = [
+							`${relationship.relativePath}:${displayLineRange(relationship.range)}(${scopeId}) [${kind}${certainty}]`,
+							...relationship.sitePreview.split("\n").map((line) => `  ${line}`),
+						];
+						if (relationship.sitePreviewTruncated) lines.push("  [preview truncated]");
+						if (relationship.certainty === "ambiguous") {
+							lines.push(
+								`  candidates: ${candidateIds.map((id) => `(${id})`).join(", ")}${relationship.competingCandidatesOmitted ? `; ${relationship.competingCandidatesOmitted} omitted` : ""}`,
+							);
+						}
+						if (relationship.certaintyReason) lines.push(`  uncertainty: ${relationship.certaintyReason}`);
+						if (targetId !== record.id) lines.push(`  target (${targetId})`);
+						await builder.appendBlock(unit, relationship.relativePath, lines.join("\n"));
+					}
+					if (result.relationships.length === 0)
+						await builder.appendRequiredBlock("no relationships", `No direct ${name} found`);
+					const summary = result.summary;
+					const exceptionLines = exceptionSummaryLines([
+						...(summary.relationshipsFound > summary.relationshipsReturned
+							? [
+									`${summary.relationshipsFound - summary.relationshipsReturned} relationships omitted (result limit ${summary.resultLimit})`,
+								]
+							: []),
+						...(summary.ambiguousRelationships > 0 ? [`${summary.ambiguousRelationships} ambiguous`] : []),
+						...(summary.parserDegradedFiles > 0 || summary.diagnostics > 0
+							? [
+									`exceptions: parser degraded ${summary.parserDegradedFiles}, diagnostics ${summary.diagnostics}`,
+								]
+							: []),
+						...limitReachedLine([
+							...(summary.resultLimitReached ? ["results"] : []),
+							...(summary.fileLimitReached ? ["files"] : []),
+							...(summary.sourceByteLimitReached ? ["source bytes"] : []),
+							...(summary.depthLimitReached ? ["depth"] : []),
+							...(summary.elapsedLimitReached ? ["elapsed time"] : []),
+						]),
+					]);
+					if (exceptionLines) await builder.appendRequiredBlock("relationship exceptions", exceptionLines);
+					const bounded = await builder.finish();
+					if (!bounded.overflow.fullOutputComplete) {
+						const visible = new Set(bounded.visibleUnitIds);
+						for (const [unit, ids] of locatorByUnit)
+							if (!visible.has(unit)) for (const id of ids) if (id !== record.id) locators.delete(id);
+					}
+					if (bounded.overflow.temporaryPath) orientation.recordTemporaryOutput(bounded.overflow.temporaryPath);
+					const returnedBytes = Buffer.byteLength(bounded.content);
+					return {
+						content: [{ type: "text", text: bounded.content }],
+						details: {
+							kind: "relationship",
+							result,
+							declarationCount: summary.relationshipsReturned,
+							sourceBytes: summary.sourceBytes,
+							returnedBytes,
+							avoidedBytes: Math.max(0, summary.sourceBytes - returnedBytes),
+							truncated: bounded.overflow.truncated,
+							overflow: bounded.overflow,
+						},
+					};
+				} catch (error) {
+					await builder.abort();
+					for (const ids of locatorByUnit.values())
+						for (const id of ids) if (id !== record.id) locators.delete(id);
+					throw error;
+				}
+			},
+			renderCall(args, theme, context) {
+				rowState.watch(context.toolCallId, context.invalidate);
+				const component =
+					(context.lastComponent as AstCallComponent | undefined) ??
+					new AstCallComponent(
+						rowState,
+						context.toolCallId,
+						name,
+						[stripLeadingAt(args.path)],
+						[`[${args.locator} limit=${args.resultLimit}]`],
+						theme,
+					);
+				component.set([stripLeadingAt(args.path)], [`[${args.locator} limit=${args.resultLimit}]`], theme);
+				return component;
+			},
+			renderResult(result, options, theme, context) {
+				rowState.watch(context.toolCallId, context.invalidate);
+				return renderAstResult(result, options.expanded, theme, context);
+			},
+		});
+	}
+
+	const references = relationshipTool(
+		"references",
+		"Find direct references and type usages for a declaration locator.",
+		"Use references to inspect direct repository usage and re-exports.",
+	);
+	const callers = relationshipTool(
+		"callers",
+		"Find direct callers for a declaration locator.",
+		"Use callers for syntactic call sites; inferred dispatch is labelled.",
+	);
+	const callees = relationshipTool(
+		"callees",
+		"Find direct callees inside a declaration locator.",
+		"Use callees to inspect direct dependencies of one executable scope.",
+	);
+	const implementations = relationshipTool(
+		"implementations",
+		"Find implementations and overrides for a declaration locator.",
+		"Use implementations for syntactic inheritance and conservative same-name overrides.",
+	);
+	const tests = relationshipTool(
+		"tests",
+		"Find directly affected tests for a declaration locator.",
+		"Use tests after selecting a change target, or earlier when the task starts from test behavior or a failure.",
+	);
+
 	return {
 		outline,
 		symbol,
+		replace_declaration: replaceDeclaration,
+		replace_body: replaceBody,
+		insert_declaration: insertDeclaration,
+		rename_declaration: renameDeclaration,
+		api_discover: apiDiscover,
+		ast_search: astSearch,
+		references,
+		callers,
+		callees,
+		implementations,
+		tests,
 		clear() {
 			locators.clear();
 			nextLocator = 1;
+			orientation.clear();
+		},
+		resetForTree() {
+			locators.clear();
+			nextLocator = 1;
+			orientation.resetGate();
 		},
 		invalidate(paths: readonly string[]) {
 			const changed = new Set(paths.map((path) => resolve(path)));
 			for (const record of locators.values()) {
 				if (changed.has(record.path)) record.stale = true;
 			}
+			orientation.invalidate(paths);
 		},
 	};
 }
 
+function formatApiQuery(query: ApiQuery): string {
+	switch (query.kind) {
+		case "exactName":
+		case "prefixName":
+		case "substringName":
+		case "fuzzyName":
+			return `${query.kind}=${query.name}`;
+		case "declarationKind":
+			return `kind=${query.declarationKind}`;
+		case "documentation":
+			return `docs=${query.terms.join(",")}`;
+	}
+}
+
 function displayLineRange(range: SourceRange): string {
 	const endLine =
 		range.endByte > range.startByte && range.end.column === 0
@@ -643,7 +1792,14 @@ function renderAstResult(
 	const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
 	if (!expanded && !context.isError) {
 		const declarationCount = details?.declarationCount ?? 0;
-		const noun = declarationCount === 1 ? "declaration" : "declarations";
+		const noun =
+			details?.kind === "locatorEdit"
+				? declarationCount === 1
+					? "fresh locator"
+					: "fresh locators"
+				: declarationCount === 1
+					? "declaration"
+					: "declarations";
 		const byteSummary = details
 			? `, ${formatSize(details.returnedBytes)} returned, ${formatSize(details.avoidedBytes)} avoided`
 			: "";
@@ -740,7 +1896,11 @@ function truncateLeft(text: string, width: number): string {
 }
 
 function outlineOptionVariants(args: OutlineArgs): string[] {
-	const fixed = [...(args.includePrivate ? ["private"] : []), ...(args.includeDocs ? ["docs"] : [])];
+	const fixed = [
+		...(args.recursive ? ["recursive"] : []),
+		...(args.includePrivate ? ["private"] : []),
+		...(args.includeDocs ? ["docs"] : []),
+	];
 	const names = args.names ?? [];
 	if (names.length === 0) return [fixed.length > 0 ? `[${fixed.join(" ")}]` : ""];
 
@@ -796,33 +1956,39 @@ function symbolTargetVariants(ids: readonly number[], locators: ReadonlyMap<numb
 	return variants;
 }
 
-function languageForPath(path: string): AstLanguage {
-	switch (extname(path).toLowerCase()) {
-		case ".ts":
-			return "typeScript";
-		case ".tsx":
-			return "tsx";
-		case ".odin":
-			return "odin";
-		case ".go":
-			return "go";
-		case ".rs":
-			return "rust";
-		case ".cs":
-			return "cSharp";
-		case ".java":
-			return "java";
-		case ".kt":
-		case ".ktm":
-		case ".kts":
-			return "kotlin";
-		case ".swift":
-			return "swift";
-		case ".md":
-		case ".markdown":
-		case ".mdown":
-			return "markdown";
-		default:
-			throw new Error(`Unsupported outline file type: ${extname(path) || "no extension"}`);
-	}
+function sourceFingerprintForPlan(source: string): string {
+	return `sha256:${createHash("sha256").update(source, "utf8").digest("hex")}`;
+}
+
+function locatorEditCall(
+	tool: string,
+	id: number,
+	locators: ReadonlyMap<number, LocatorRecord>,
+	rowState: ToolRowStateStore,
+	theme: Theme,
+	context: {
+		toolCallId: string;
+		invalidate: () => void;
+		lastComponent?: Component;
+	},
+	option = "",
+): Component {
+	rowState.watch(context.toolCallId, context.invalidate);
+	const record = locators.get(id);
+	const targets = record ? [`${record.name}@${basename(record.path)}`, String(id)] : [String(id)];
+	const options = [option ? `[${option}]` : ""];
+	const component =
+		(context.lastComponent as AstCallComponent | undefined) ??
+		new AstCallComponent(rowState, context.toolCallId, tool, targets, options, theme);
+	component.set(targets, options, theme);
+	return component;
+}
+
+function exceptionSummaryLines(parts: string[]): string | undefined {
+	const lines = parts.filter((part) => part.length > 0);
+	return lines.length > 0 ? lines.join("\n") : undefined;
+}
+
+function limitReachedLine(limits: string[]): string[] {
+	return limits.length > 0 ? [`limits reached: ${limits.join(", ")}`] : [];
 }