@shanepadgett/tau-agent 0.33.1 → 0.34.0

package/extensions/explore/{ast/read → read}/hook.ts

@@ -1,11 +1,16 @@
 import type { ExtensionAPI, ReadToolDetails } from "@earendil-works/pi-coding-agent";
-import { loadTauExtensionSettings } from "../../../../shared/settings/load.ts";
-import exploreSettings from "../../settings.ts";
-import { resolveExplorePath } from "../../traverse.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatOutlineFile } from "../format/outline.ts";
-import { outlinePath } from "../queries/outline.ts";
-import { formatLargeReadOutline, readCallKind, shouldOutlineFullRead, type ExploreReadSettings } from "./policy.ts";
+import { loadTauExtensionSettings } from "../../../shared/settings/load.ts";
+import exploreSettings from "../settings.ts";
+import { resolveExplorePath } from "../../../src/ast/traverse.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatOutlineFile } from "../../../src/ast/format/outline.ts";
+import { outlinePath } from "../../../src/ast/queries/outline.ts";
+import {
+	formatLargeReadOutline,
+	readCallKind,
+	shouldOutlineFullRead,
+	type ExploreReadSettings,
+} from "../../../src/ast/read-policy.ts";
 
 type ReadOverlayResult = {
 	content: Array<{ type: "text"; text: string }>;

package/extensions/explore/{ast/tools → tools}/ast-search.ts

@@ -1,37 +1,35 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
-import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
+import { BoundedTextResultBuilder } from "../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
 import {
 	formatAstSearchEmpty,
 	formatAstSearchFile,
 	formatAstSearchFooters,
 	groupAstSearchByFile,
-} from "../format/ast-search.ts";
-import { astSearch } from "../queries/ast-search.ts";
-import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+} from "../../../src/ast/format/ast-search.ts";
+import { astSearch } from "../../../src/ast/queries/ast-search.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
 
 const PATTERN_MAX_BYTES = 16 * 1024;
 
 const astSearchParams = Type.Object(
 	{
-		path: Type.String({ description: "File or directory to search" }),
+		path: Type.String({ description: "File or directory" }),
 		pattern: Type.String({
 			minLength: 1,
 			maxLength: PATTERN_MAX_BYTES,
-			description:
-				"ast-grep pattern (e.g. 'console.log($ARG)', 'foo($$$ARGS)', 'if ($COND) { $$$BODY }'). $NAME binds one node; $$$NAME binds a sibling sequence.",
+			description: "ast-grep pattern (max 16KiB). $NAME = node, $$$NAME = sequence, $_ = anonymous",
 		}),
 		language: Type.Optional(
 			Type.String({
-				description:
-					"Engine-registered language id (typescript, tsx, go, rust, c_sharp, java, kotlin, swift, odin). Required for directories; must match file extension when both given.",
+				description: "Registered id: typescript, tsx, go, rust, c_sharp, java, kotlin, swift",
 			}),
 		),
-		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max matches (1–100)" }),
 	},
 	{ additionalProperties: false },
 );
@@ -64,13 +62,11 @@ export function createAstSearchTool(
 		name: "ast_search",
 		label: "ast_search",
 		description:
-			"Find code shapes with ast-grep patterns in one file or a tree. Use $NAME for one node and $$$NAME for sibling sequences (e.g. console.log($ARG), foo($$$ARGS)). Search only — no writes. Prefer over grep when structure matters.",
-		promptSnippet: "Structural pattern search with ast-grep metavariables",
+			"ast-grep structural search on one file or a directory. $NAME = node, $$$NAME = sequence, $_ = anonymous. Directory targets require language. Search only.",
+		promptSnippet: "ast-grep structural pattern search",
 		promptGuidelines: [
-			"Use ast_search for code shapes; harness grep for literal text.",
-			"Pass language for directory targets (required). On a file, language is optional when the extension maps to a registered search language.",
-			"Patterns follow ast-grep rules: $NAME one node, $$$NAME sequence, $_ anonymous. Keep resultLimit tight.",
-			"No rewrite/write path — edits go through harness patch/edit/write.",
+			"Shapes here; literal text with harness grep.",
+			"language required for directories; on a file, omit when extension maps the language.",
 		],
 		parameters: astSearchParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/extensions/explore/{ast/tools → tools}/context.ts

@@ -1,27 +1,25 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
-import { loadTauExtensionSettings } from "../../../../shared/settings/load.ts";
-import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import exploreSettings from "../../settings.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { contextSectionBlocks, formatContextResult } from "../format/context.ts";
-import type { ExploreFileGraph } from "../graph/file-graph.ts";
-import { queryContext } from "../queries/context.ts";
-import { stripLeadingAt } from "../../traverse.ts";
+import { BoundedTextResultBuilder } from "../../../shared/bounded-text-result.ts";
+import { loadTauExtensionSettings } from "../../../shared/settings/load.ts";
+import type { TemporaryOutputStore } from "../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import exploreSettings from "../settings.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { contextSectionBlocks, formatContextResult } from "../../../src/ast/format/context.ts";
+import type { ExploreFileGraph } from "../../../src/ast/graph/file-graph.ts";
+import { queryContext } from "../../../src/ast/queries/context.ts";
+import { stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+import { targetParams } from "./target-params.ts";
 
 const contextParams = Type.Object(
 	{
-		path: Type.String({ description: "Directory scope (repo/package/subtree)" }),
-		targetPath: Type.Optional(Type.String({ description: "Defining file when known" })),
-		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
-		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line to pin one candidate" })),
+		...targetParams,
 		budget: Type.Optional(
 			Type.Integer({
 				minimum: 1,
-				description: "Token pack budget (default from explore.context.defaultBudgetTokens)",
+				description: "Token budget (default from settings)",
 			}),
 		),
 	},
@@ -38,14 +36,9 @@ export function createContextTool(
 		name: "context",
 		label: "context",
 		description:
-			"Budgeted pack to understand one symbol in one call: target body, nearby callees/callers or type members/implementors. Raise budget if truncated. Use impact for full blast radius.",
-		promptSnippet: "Budgeted read pack for one symbol",
-		promptGuidelines: [
-			"Use when you need bodies/signatures around one symbol under a token budget.",
-			"Raise budget if entries are signature-only or truncated.",
-			"Use impact for full dependents list; context is a sample pack.",
-			"Callable and type targets only.",
-		],
+			"Budgeted pack for one callable/type: target body/signature plus nearby related decls. Default budget explore.context.defaultBudgetTokens (8000) when omitted. Sample, not full dependents — use impact for that. Soft-errors as text.",
+		promptSnippet: "Budgeted pack around one symbol",
+		promptGuidelines: ["Raise budget if entries are signature-only or footer says truncated."],
 		parameters: contextParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const engine = engineFor(ctx.cwd);

package/extensions/explore/{ast/tools → tools}/deps.ts

@@ -1,18 +1,18 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatDepsEmpty, formatDepsResult } from "../format/deps.ts";
-import type { ExploreFileGraph } from "../graph/file-graph.ts";
-import { stripLeadingAt } from "../../traverse.ts";
+import { truncateBoundedHead } from "../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatDepsEmpty, formatDepsResult } from "../../../src/ast/format/deps.ts";
+import type { ExploreFileGraph } from "../../../src/ast/graph/file-graph.ts";
+import { stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
 
 const depsParams = Type.Object(
 	{
 		path: Type.String({ description: "Source file" }),
-		depth: Type.Optional(Type.Integer({ minimum: 1, description: "Traversal depth (default 1)" })),
-		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max dependent entries to return" }),
+		depth: Type.Optional(Type.Integer({ minimum: 1, description: "BFS depth (default 1)" })),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max entries (1–100)" }),
 	},
 	{ additionalProperties: false },
 );
@@ -26,13 +26,9 @@ export function createDepsTool(
 		name: "deps",
 		label: "deps",
 		description:
-			"File-level: what this file imports/depends on. Depth > 1 walks the internal import graph (BFS). External packages are listed last.",
-		promptSnippet: "List file imports and dependencies",
-		promptGuidelines: [
-			"Use for file-level dependency orientation, not symbol callees.",
-			"Increase depth only when transitive internal imports matter.",
-			"Tighten resultLimit when output is large.",
-		],
+			"File-level imports for one source file. depth>1 = BFS through internal imports. External packages listed last. Not symbol callees.",
+		promptSnippet: "File imports / dependency graph",
+		promptGuidelines: ["Raise depth only for transitive internal imports; tighten resultLimit if noisy."],
 		parameters: depsParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const engine = engineFor(ctx.cwd);

package/extensions/explore/{ast/tools → tools}/discover.ts

@@ -1,19 +1,19 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
-import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { DeclKind } from "../ir.ts";
+import { BoundedTextResultBuilder } from "../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { DeclKind } from "../../../src/ast/ir.ts";
 import {
 	formatDiscoverEmpty,
 	formatDiscoverFile,
 	formatDiscoverFooters,
 	groupDiscoverByFile,
-} from "../format/discover.ts";
-import { discover, type DiscoverQuery, type DiscoverSurface } from "../queries/discover.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+} from "../../../src/ast/format/discover.ts";
+import { discover, type DiscoverQuery, type DiscoverSurface } from "../../../src/ast/queries/discover.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type ExploreToolDetails } from "./render.ts";
 
 const declarationKinds = [
@@ -43,7 +43,7 @@ const declarationKinds = [
 
 const discoverParams = Type.Object(
 	{
-		path: Type.String({ description: "Repository, package, or subtree directory" }),
+		path: Type.String({ description: "Directory scope" }),
 		query: Type.Union([
 			Type.Object(
 				{ kind: Type.Literal("exactName"), name: Type.String({ minLength: 1 }) },
@@ -84,9 +84,9 @@ const discoverParams = Type.Object(
 			),
 		]),
 		surface: StringEnum(["all", "public", "private", "sourceExport", "packageSurface"] as const, {
-			description: "Declaration or export surface to search",
+			description: "all | public | private | sourceExport | packageSurface",
 		}),
-		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max candidates (1–100)" }),
 	},
 	{ additionalProperties: false },
 );
@@ -134,13 +134,11 @@ export function createDiscoverTool(
 		name: "discover",
 		label: "discover",
 		description:
-			"Find reusable declarations across a repository, package, or subtree by name, kind, or documentation. Signatures only — no bodies. Prefer package/public surfaces when looking for imports.",
-		promptSnippet: "Find reusable declarations across a repo/package/subtree when path is unknown",
+			"Find decls by name/kind/docs when path is unknown. Signatures only. One query kind per call. surface selects visibility/export set; packageSurface needs a language with that capability (TS/TSX here) and a nearby package.",
+		promptSnippet: "Find decls by name/kind/docs across a tree",
 		promptGuidelines: [
-			"Use discover when reuse intent is known but the declaration path or exact name is not.",
-			"Choose exactly one query kind. Keep fuzzy or documentation work limits narrow.",
-			"Use packageSurface when the caller needs a supported public import path (languages with packageSurface capability).",
-			"Follow up with show using path+name(+line) when a candidate needs closer inspection.",
+			"Prefer public/packageSurface when looking for imports; follow hits with show.",
+			"Keep fuzzyName / documentation maxCandidates and maxWork tight.",
 		],
 		parameters: discoverParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/extensions/explore/{ast/tools → tools}/impact.ts

@@ -1,32 +1,35 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
-import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatImpactResult, impactSectionBlocks } from "../format/impact.ts";
-import type { ExploreFileGraph } from "../graph/file-graph.ts";
-import { IMPACT_DEPTH_DEFAULT, IMPACT_DEPTH_MAX, queryImpact, type ImpactMode } from "../queries/impact.ts";
-import { stripLeadingAt } from "../../traverse.ts";
+import { BoundedTextResultBuilder } from "../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatImpactResult, impactSectionBlocks } from "../../../src/ast/format/impact.ts";
+import type { ExploreFileGraph } from "../../../src/ast/graph/file-graph.ts";
+import {
+	IMPACT_DEPTH_DEFAULT,
+	IMPACT_DEPTH_MAX,
+	queryImpact,
+	type ImpactMode,
+} from "../../../src/ast/queries/impact.ts";
+import { stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+import { targetParams } from "./target-params.ts";
 
 const impactParams = Type.Object(
 	{
-		path: Type.String({ description: "Directory scope (repo/package/subtree)" }),
-		targetPath: Type.Optional(Type.String({ description: "Defining file when known" })),
-		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
-		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line to pin one candidate" })),
+		...targetParams,
 		depth: Type.Optional(
 			Type.Integer({
 				minimum: 1,
 				maximum: IMPACT_DEPTH_MAX,
-				description: `File-transitive reverse depth (default ${IMPACT_DEPTH_DEFAULT}, max ${IMPACT_DEPTH_MAX}). Symbol hops are always 1.`,
+				description: `Reverse file BFS depth (default ${IMPACT_DEPTH_DEFAULT}, max ${IMPACT_DEPTH_MAX})`,
 			}),
 		),
 		mode: Type.Optional(
 			StringEnum(["all", "deps", "dependents"] as const, {
-				description: "all = both sides; deps = callees+imports; dependents = callers+importers+transitive",
+				description: "all | deps | dependents",
 			}),
 		),
 	},
@@ -43,15 +46,9 @@ export function createImpactTool(
 		name: "impact",
 		label: "impact",
 		description:
-			"One-call blast radius for a symbol: callees, callers, file imports, file importers, transitive file dependents. Narrow path scope. depth is file-transitive only.",
-		promptSnippet: "Blast radius before a non-trivial edit",
-		promptGuidelines: [
-			"Use before a non-trivial edit to see symbol and nearby file dependents.",
-			"Narrow path scope — whole-repo impact is not the goal.",
-			"depth applies only to reverse file dependents (not multi-hop symbol callers).",
-			"mode=deps for outbound only; mode=dependents for inbound only.",
-			"Callable and type targets only.",
-		],
+			"Blast radius for one callable/type: callees, callers, file imports/importers, transitive file dependents. path is narrow directory scope. depth (default 2, max 5) is file reverse-BFS only; symbol hops stay 1. mode=all|deps|dependents. Soft-errors and notes as text.",
+		promptSnippet: "Symbol + file blast radius",
+		promptGuidelines: ["Run before non-trivial edits; keep path narrow — not whole-repo."],
 		parameters: impactParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const engine = engineFor(ctx.cwd);

package/extensions/explore/{ast/tools → tools}/outline.ts

@@ -1,34 +1,33 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
-import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatOutlineBudgetFooter, formatOutlineEmpty, formatOutlineFile } from "../format/outline.ts";
-import { outlinePath, outlineRecursive, type OutlineFileView, type OutlineOptions } from "../queries/outline.ts";
-import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+import { BoundedTextResultBuilder } from "../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatOutlineBudgetFooter, formatOutlineEmpty, formatOutlineFile } from "../../../src/ast/format/outline.ts";
+import {
+	outlinePath,
+	outlineRecursive,
+	type OutlineFileView,
+	type OutlineOptions,
+} from "../../../src/ast/queries/outline.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type ExploreToolDetails } from "./render.ts";
 
 const outlineParams = Type.Object(
 	{
 		path: Type.String({
-			description: "Supported source file, package directory, or subtree",
+			description: "File, package dir, or subtree",
 		}),
-		includePrivate: Type.Optional(
-			Type.Boolean({ description: "Include private declarations and members (default false)" }),
-		),
-		includeDocs: Type.Optional(
-			Type.Boolean({ description: "Include attached documentation comments (default false)" }),
-		),
+		includePrivate: Type.Optional(Type.Boolean({ description: "Include non-public decls (default false)" })),
+		includeDocs: Type.Optional(Type.Boolean({ description: "Include attached docs (default false)" })),
 		names: Type.Optional(
 			Type.Array(Type.String({ minLength: 1 }), {
 				minItems: 1,
-				description: "Exact declaration name or qualifiedName filters",
+				description: "Exact name / qualifiedName filter",
 			}),
 		),
-		recursive: Type.Optional(
-			Type.Boolean({ description: "Recursively outline every supported source file below a directory" }),
-		),
+		recursive: Type.Optional(Type.Boolean({ description: "Walk whole subtree" })),
 	},
 	{ additionalProperties: false },
 );
@@ -100,13 +99,11 @@ export function createOutlineTool(
 		name: "outline",
 		label: "outline",
 		description:
-			"Inspect declarations in one supported source file, one non-recursive package directory, or a recursive mixed-language subtree without returning implementation bodies. Line ranges support follow-up show or ranged read.",
-		promptSnippet: "Inspect declarations and structure without reading implementation bodies",
+			"Declaration map for one file, one package dir, or a recursive subtree. Signatures and ranges only — no bodies. Private/docs off by default. Recursive walks every supported language under path.",
+		promptSnippet: "Declaration map without bodies",
 		promptGuidelines: [
-			"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.",
-			"Use show with path+name (and optional line) when exact signature or declaration source is needed.",
+			"recursive=true for unfamiliar trees; single path otherwise.",
+			"includePrivate / includeDocs only when surface names are not enough.",
 		],
 		parameters: outlineParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/extensions/explore/{ast/tools → tools}/relationships.ts

@@ -1,21 +1,19 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatRelationshipResult } from "../format/relationships.ts";
-import type { ExploreFileGraph } from "../graph/file-graph.ts";
-import { queryRelationships, type RelationshipOp } from "../graph/relationships.ts";
-import { stripLeadingAt } from "../../traverse.ts";
+import { truncateBoundedHead } from "../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatRelationshipResult } from "../../../src/ast/format/relationships.ts";
+import type { ExploreFileGraph } from "../../../src/ast/graph/file-graph.ts";
+import { queryRelationships, type RelationshipOp } from "../../../src/ast/graph/relationships.ts";
+import { stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+import { targetParams } from "./target-params.ts";
 
 const relationshipParams = Type.Object(
 	{
-		path: Type.String({ description: "Directory scope (repo/package/subtree)" }),
-		targetPath: Type.Optional(Type.String({ description: "Defining file when known" })),
-		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
-		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line to pin one candidate" })),
-		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max sites to return" }),
+		...targetParams,
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max sites (1–100)" }),
 	},
 	{ additionalProperties: false },
 );
@@ -92,12 +90,11 @@ export function createCallersTool(
 ) {
 	return createRelationshipTool(
 		"callers",
-		"Syntactic call sites of a declaration. For types: constructions and implementors.",
-		"Find callers of a symbol",
+		"Inbound syntactic sites for one decl (calls/constructs/implementors for types). Scope is a directory. Ambiguous name → candidate list, not sites. Soft-errors return as text.",
+		"Inbound call/construct sites",
 		[
-			"Use after selecting a change target when inbound uses affect the plan.",
-			"Disambiguate with targetPath or line when the name is common.",
-			"Treat ambiguous sites as non-actionable until tightened.",
+			"Disambiguate with targetPath or line before acting on hits.",
+			"Respect certainty: exact silent; inferred/ambiguous labeled; ambiguous not actionable.",
 		],
 		rowState,
 		engineFor,
@@ -112,9 +109,9 @@ export function createCalleesTool(
 ) {
 	return createRelationshipTool(
 		"callees",
-		"Direct callees inside a declaration body. For types: ancestor types from heritage.",
-		"Find callees of a symbol",
-		["Direct only — no depth parameter.", "Use to skim outbound dependencies before editing a body."],
+		"Direct outbound sites inside one decl body (heritage ancestors for types). One hop only. Same resolve/soft-error protocol as callers.",
+		"Direct callees / heritage",
+		[],
 		rowState,
 		engineFor,
 		graphFor,
@@ -128,12 +125,9 @@ export function createReferencesTool(
 ) {
 	return createRelationshipTool(
 		"references",
-		"Direct references: calls, constructions, imports, and heritage mentions of a declaration.",
-		"Find references to a symbol",
-		[
-			"Includes import and re-export-style bindings when classified.",
-			"Not a full IDE rename set — respect certainty labels.",
-		],
+		"Direct references: calls, constructs, imports/re-exports, heritage mentions. Not a full rename set. Same resolve/soft-error protocol as callers.",
+		"Direct references to a symbol",
+		["Certainty labels are incomplete for rename — verify before bulk edit."],
 		rowState,
 		engineFor,
 		graphFor,
@@ -147,12 +141,9 @@ export function createImplementationsTool(
 ) {
 	return createRelationshipTool(
 		"implementations",
-		"Syntactic inheritance/implementation sites and conservative same-name overrides.",
-		"Find implementations of a type or method",
-		[
-			"For types: heritage clauses naming the target.",
-			"For methods: same-name methods on types that extend/implement the owner (conservative).",
-		],
+		"Heritage implementors of a type, or same-name methods on extending types (conservative). Same resolve/soft-error protocol as callers.",
+		"Implementors / overrides",
+		["Method matches are name-based on subtype owners — not semantic override resolution."],
 		rowState,
 		engineFor,
 		graphFor,

package/extensions/explore/{ast/tools → tools}/render.ts

@@ -1,6 +1,6 @@
 import { formatSize, keyHint, type Theme } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
-import { formatToolRowTitle, type ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../../shared/tool-row-state.ts";
 
 export type ExploreToolDetails = {
 	declarationCount: number;

package/extensions/explore/{ast/tools → tools}/reverse-deps.ts

@@ -1,18 +1,18 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
-import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
-import type { ExploreEngine } from "../engine.ts";
-import { formatDepsResult, formatReverseDepsEmpty } from "../format/deps.ts";
-import type { ExploreFileGraph } from "../graph/file-graph.ts";
-import { stripLeadingAt } from "../../traverse.ts";
+import { truncateBoundedHead } from "../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../../../src/ast/engine.ts";
+import { formatDepsResult, formatReverseDepsEmpty } from "../../../src/ast/format/deps.ts";
+import type { ExploreFileGraph } from "../../../src/ast/graph/file-graph.ts";
+import { stripLeadingAt } from "../../../src/ast/traverse.ts";
 import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
 
 const reverseDepsParams = Type.Object(
 	{
 		path: Type.String({ description: "Source file" }),
-		depth: Type.Optional(Type.Integer({ minimum: 1, description: "Traversal depth (default 1)" })),
-		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max importer entries to return" }),
+		depth: Type.Optional(Type.Integer({ minimum: 1, description: "BFS depth (default 1)" })),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max importers (1–100)" }),
 	},
 	{ additionalProperties: false },
 );
@@ -26,13 +26,9 @@ export function createReverseDepsTool(
 		name: "reverse_deps",
 		label: "reverse_deps",
 		description:
-			"File-level: who imports this file within the inferred project scope. Depth > 1 walks transitive importers (BFS).",
-		promptSnippet: "List files that import this file",
-		promptGuidelines: [
-			"Use for file-level reverse dependencies, not symbol callers.",
-			"Scope is session cwd when the file is under it, else nearest git root.",
-			"Tighten resultLimit on large packages.",
-		],
+			"File-level importers of one source file in project scope (cwd if under it, else nearest git root). depth>1 = transitive BFS. Not symbol callers.",
+		promptSnippet: "Who imports this file",
+		promptGuidelines: ["Tighten resultLimit on large packages."],
 		parameters: reverseDepsParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const engine = engineFor(ctx.cwd);