@shanepadgett/tau-agent 0.26.0 → 0.27.0

package/extensions/explore/settings.ts

@@ -0,0 +1,46 @@
+import { relative, resolve } from "node:path";
+import { Type } from "typebox";
+import { matchGlob, posixPath } from "../../shared/glob.ts";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+export interface ExploreReadGateSettings {
+	includeGlobs: string[];
+	excludeGlobs: string[];
+}
+
+export default defineTauExtensionSettings({
+	key: "explore",
+	defaults: {
+		readGate: {
+			includeGlobs: ["**/*"] as string[],
+			excludeGlobs: ["**/*.md", "**/*.markdown", "**/*.mdown"] as string[],
+		},
+	},
+	schema: Type.Object(
+		{
+			readGate: Type.Object(
+				{
+					includeGlobs: Type.Array(Type.String(), {
+						default: ["**/*"],
+						description:
+							"Working-directory-relative supported source paths that require a structural attempt before read.",
+					}),
+					excludeGlobs: Type.Array(Type.String(), {
+						default: ["**/*.md", "**/*.markdown", "**/*.mdown"],
+						description: "Working-directory-relative paths excluded from the Explore read gate. Exclusions win.",
+					}),
+				},
+				{ additionalProperties: false },
+			),
+		},
+		{ additionalProperties: false },
+	),
+});
+
+export function matchesExploreReadGate(path: string, cwd: string, settings: ExploreReadGateSettings): boolean {
+	const projectPath = posixPath(relative(resolve(cwd), resolve(path)));
+	return (
+		settings.includeGlobs.some((pattern) => matchGlob(pattern, projectPath)) &&
+		!settings.excludeGlobs.some((pattern) => matchGlob(pattern, projectPath))
+	);
+}

package/extensions/explore/traverse.ts

@@ -1,5 +1,5 @@
 import type { Stats } from "node:fs";
-import { lstat, readdir, readFile } from "node:fs/promises";
+import { lstat, opendir, readFile } from "node:fs/promises";
 import { dirname, join, matchesGlob, resolve, sep } from "node:path";
 import { formatPathForDisplay, isWithinPath, relativeSlash, toSlashPath } from "./path-display.ts";
 
@@ -18,6 +18,7 @@ export interface CollectPathOptions {
 	cwd: string;
 	root: string;
 	maxDepth?: number;
+	maxEntries?: number;
 	includeRoot: boolean;
 	includeHidden: boolean;
 	includeIgnored: boolean;
@@ -149,9 +150,14 @@ function sortEntries(entries: TraversalEntry[]): TraversalEntry[] {
 	});
 }
 
-async function readDirectoryNames(directory: string, cwd: string): Promise<string[]> {
+async function readDirectoryNames(directory: string, cwd: string, limit: number | undefined): Promise<string[]> {
 	try {
-		return await readdir(directory);
+		const names: string[] = [];
+		for await (const entry of await opendir(directory)) {
+			names.push(entry.name);
+			if (limit !== undefined && names.length >= limit) break;
+		}
+		return names;
 	} catch {
 		throw new Error(`Cannot read directory: ${formatPathForDisplay(directory, cwd)}`);
 	}
@@ -160,6 +166,7 @@ async function readDirectoryNames(directory: string, cwd: string): Promise<strin
 export async function collectPaths(options: CollectPathOptions): Promise<TraversalEntry[]> {
 	const entries: TraversalEntry[] = [];
 	const entryByPath = new Map<string, TraversalEntry>();
+	let inspectedEntries = 0;
 	const rootStats = await lstat(options.root);
 	const rootKind = entryKind(rootStats);
 	const rootDirectory = rootKind === "dir" ? options.root : dirname(options.root);
@@ -183,13 +190,17 @@ export async function collectPaths(options: CollectPathOptions): Promise<Travers
 
 	async function walkDirectory(directory: string, depth: number, rules: readonly IgnoreRule[]): Promise<number> {
 		if (options.maxDepth !== undefined && depth >= options.maxDepth) return 0;
+		if (options.maxEntries !== undefined && inspectedEntries >= options.maxEntries) return 0;
 
-		const names = await readDirectoryNames(directory, options.cwd);
+		const remaining = options.maxEntries === undefined ? undefined : options.maxEntries - inspectedEntries;
+		const names = await readDirectoryNames(directory, options.cwd, remaining);
 
 		const children: TraversalEntry[] = [];
 		for (const name of names) {
+			if (options.maxEntries !== undefined && inspectedEntries >= options.maxEntries) break;
 			const childPath = `${directory}/${name}`;
 			const stats = await lstat(childPath);
+			inspectedEntries += 1;
 			const kind = entryKind(stats);
 			if (shouldSkipPath(childPath, kind, rules, options)) continue;
 			children.push({

package/extensions/patch/executor.ts

@@ -1,4 +1,5 @@
-import { access, mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, realpath, rmdir, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { applyChunksWithRanges, countLogicalLines, UpdateChunkApplyError } from "./matcher.ts";
@@ -11,6 +12,7 @@ export interface ApplyPatchChange {
 	move?: { from: string; to: string };
 	linesAdded: number;
 	linesRemoved: number;
+	resultingFingerprint: string | null;
 	snapshotRanges?: Array<{ startLine: number; endLine: number }>;
 }
 
@@ -32,6 +34,12 @@ export interface ApplyPatchStats {
 	completedOperations: number;
 }
 
+export interface ExactSourceMutation {
+	path: string;
+	expectedFingerprint: string;
+	source: string;
+}
+
 export function deriveStats(summary: ApplyPatchSummary): ApplyPatchStats {
 	const added: string[] = [];
 	const replaced: string[] = [];
@@ -80,6 +88,10 @@ function throwIfAborted(signal: AbortSignal | undefined): void {
 	if (signal?.aborted) throw new Error("Operation aborted");
 }
 
+function fingerprint(source: string): string {
+	return `sha256:${createHash("sha256").update(source, "utf8").digest("hex")}`;
+}
+
 async function pathExists(path: string): Promise<boolean> {
 	try {
 		await access(path);
@@ -136,6 +148,7 @@ async function stageWholeFile(
 			path: op.path,
 			linesAdded: op.linesAdded,
 			linesRemoved,
+			resultingFingerprint: fingerprint(op.content),
 			snapshotRanges: lineCount > 0 ? [{ startLine: 1, endLine: Math.min(lineCount, 120) }] : undefined,
 		},
 		async commit() {
@@ -156,6 +169,7 @@ async function stageDelete(cwd: string, op: Extract<PatchOperation, { type: "del
 			path: op.path,
 			linesAdded: 0,
 			linesRemoved: countLogicalLines(current),
+			resultingFingerprint: null,
 		},
 		async commit() {
 			await unlink(target);
@@ -180,6 +194,7 @@ async function stageUpdate(cwd: string, op: Extract<PatchOperation, { type: "upd
 				path: op.path,
 				linesAdded: op.linesAdded,
 				linesRemoved: op.linesRemoved,
+				resultingFingerprint: fingerprint(next),
 				snapshotRanges: result?.snapshotRanges,
 			},
 			async commit() {
@@ -203,6 +218,7 @@ async function stageUpdate(cwd: string, op: Extract<PatchOperation, { type: "upd
 			move: { from: op.path, to: movePath },
 			linesAdded: op.linesAdded,
 			linesRemoved: op.linesRemoved,
+			resultingFingerprint: fingerprint(next),
 			snapshotRanges: result?.snapshotRanges,
 		},
 		async commit() {
@@ -256,6 +272,84 @@ function withMutationQueuePaths<T>(paths: string[], fn: () => Promise<T>): Promi
 	return current();
 }
 
+export async function applyExactSourceMutations(
+	cwd: string,
+	mutations: readonly ExactSourceMutation[],
+	signal?: AbortSignal,
+): Promise<ApplyPatchSummary> {
+	throwIfAborted(signal);
+	if (mutations.length === 0) throw new Error("Exact-source mutation requires at least one file.");
+	const byPath = new Map<string, ExactSourceMutation>();
+	for (const mutation of mutations) {
+		const path = resolvePath(cwd, mutation.path);
+		if (byPath.has(path)) throw new Error(`Conflicting exact-source mutations for path: ${mutation.path}`);
+		byPath.set(path, { ...mutation, path });
+	}
+	const ordered = [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+
+	return withMutationQueuePaths(
+		ordered.map((mutation) => mutation.path),
+		async () => {
+			const staged: Array<{ mutation: ExactSourceMutation; change: ApplyPatchChange }> = [];
+			for (const [sectionIndex, mutation] of ordered.entries()) {
+				throwIfAborted(signal);
+				await assertExistingFile(mutation.path, mutation.path);
+				const canonical = await realpath(mutation.path);
+				if (canonical !== mutation.path) {
+					throw new Error(`Exact-source mutation path is not canonical: ${mutation.path}`);
+				}
+				const current = await readUtf8(mutation.path, mutation.path);
+				const currentFingerprint = fingerprint(current);
+				if (currentFingerprint !== mutation.expectedFingerprint) {
+					throw new Error(
+						`Source changed before exact-source mutation for ${mutation.path}; expected ${mutation.expectedFingerprint}, found ${currentFingerprint}.`,
+					);
+				}
+				const displayPath = relative(resolve(cwd), mutation.path);
+				const lineCount = countLogicalLines(mutation.source);
+				staged.push({
+					mutation,
+					change: {
+						sectionIndex,
+						kind: "update",
+						path: displayPath.startsWith("..") || isAbsolute(displayPath) ? mutation.path : displayPath,
+						linesAdded: lineCount,
+						linesRemoved: countLogicalLines(current),
+						resultingFingerprint: fingerprint(mutation.source),
+						snapshotRanges: lineCount > 0 ? [{ startLine: 1, endLine: Math.min(lineCount, 120) }] : undefined,
+					},
+				});
+			}
+
+			throwIfAborted(signal);
+			const changes: ApplyPatchChange[] = [];
+			for (const { mutation, change } of staged) {
+				try {
+					throwIfAborted(signal);
+					await writeFile(mutation.path, mutation.source, "utf8");
+					changes.push(change);
+				} catch (error) {
+					return {
+						status: changes.length === 0 ? "failed" : "partial",
+						changes,
+						failures: [
+							{
+								phase: "apply",
+								sectionIndex: change.sectionIndex,
+								path: change.path,
+								kind: "update",
+								message: error instanceof Error ? error.message : String(error),
+							},
+						],
+						totalSections: staged.length,
+					};
+				}
+			}
+			return { status: "completed", changes, failures: [], totalSections: staged.length };
+		},
+	);
+}
+
 export async function applyPatch(
 	cwd: string,
 	input: string,

package/extensions/patch/index.ts

@@ -165,6 +165,7 @@ export default function patchExtension(pi: ExtensionAPI): void {
 					move: change.move,
 					linesAdded: change.linesAdded,
 					linesRemoved: change.linesRemoved,
+					resultingFingerprint: change.resultingFingerprint,
 					snapshotRanges: change.snapshotRanges,
 				})),
 			});

package/extensions/soul/prompt.ts

@@ -12,9 +12,7 @@ Human interrupts. Human sometimes idiot. Human sometimes has good idea. Rok thin
 
 Build only what human specifically asked for. User ask approves that scope only. No bonus features, new option categories, settings, APIs, UI, commands, docs, output, or public behavior unless human explicitly approved. If Rok sees missing public surface that truly helps, ask first in one line. Do not sneak it into diff.
 
-Every read has job. Start from task path or symbol. Grep for broad search, not for rereading known files. Read only files likely to answer current decision or be edited. Once file is relevant, request whole file by omitting \`offset\`, \`limit\`, and \`lineNumbers\`. One whole-file read beats repeated ranged reads. Supplied eager snapshot counts as initial read. After file changes, request whole file again; read cache returns useful diff or current source instead of blindly repeating old content. Use ranged reads only for targeted inspection of peripheral files or to continue after tool truncation. Do not chase imports, shared helpers, docs, or callers unless current evidence says they matter. Aimless explore wastes context and dulls Rok. If exploration wandered, prune memory and keep only useful facts.
-
-Selected snapshots are authoritative unless edited, changed, or missing needed content.
+Gather only the evidence needed for the current decision. Expand scope only when a specific uncertainty requires it. Do not chase related code, documentation, or tests merely because they exist. If an investigation wanders, discard stale evidence before continuing.
 
 Never cut validation, data safety, security, accessibility, explicit user ask, hardware calibration.
 

package/extensions/subagent/agents/review.md

@@ -2,12 +2,18 @@
 name: review
 description: Perform an adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
 tools:
-  - read
-  - grep
-  - find
   - ls
-  - bash
-  - context_prune
+  - find
+  - grep
+  - api_discover
+  - ast_search
+  - outline
+  - symbol
+  - references
+  - callers
+  - callees
+  - implementations
+  - tests
 names:
   - Auditor
   - Inspector
@@ -15,34 +21,79 @@ names:
   - Examiner
   - Sentinel
 model: openai-codex/gpt-5.6-sol
-thinking: xhigh
+thinking: high
 ---
 
-Treat the implementation as untrusted. Try to disprove its correctness before accepting it. Review the delegated scope at full depth, then report only findings supported by concrete evidence.
+Stay inside delegated change. Answer two questions:
+
+1. Is runtime behavior correct?
+2. Is this the simplest implementation of requested behavior?
+
+Find concrete failures or needless complexity. Report. Stop. No unrelated review or concern inventory.
+
+## Evidence ladder
+
+Use cheapest tool that settles question. Escalate only when answer could change verdict.
+
+### Supplied context
+
+Task files are current, line-numbered snapshots. Treat as authoritative this turn. Start there. Do not search for facts already supplied.
+
+### Paths and text
+
+- `ls` or `find`: relevant path unknown.
+- `grep`: exact names, imports, registrations, configuration keys, and unsupported source formats.
+- Keep roots and result limits narrow. Text occurrence does not prove runtime behavior.
+
+### Structure and reuse
+
+- Default to `outline`. Inspect known file or package. Pass likely names. Include private declarations only when verdict needs them.
+- Use `api_discover` when code may duplicate an existing repository API but name or path is unknown.
+- Use `ast_search` for code shapes: repeated wrappers, duplicated branches, risky call patterns. Keep pattern and scope focused.
+
+No repository sweeps for hypothetical reuse. Search only when changed code gives concrete reason.
+
+### Runtime relationships
+
+Select declaration locator. Use one focused relationship tool when needed:
+
+- `callers`: direct call sites.
+- `callees`: dependencies inside executable scope.
+- `references`: direct uses and re-exports.
+- `implementations`: inheritance or override behavior.
+- `tests`: directly affected coverage.
+
+Use narrowest useful root and small result limit. Preserve exact, inferred, and ambiguous labels. Results prove bounded syntactic relationships. They do not prove dynamic dispatch or complete runtime reachability.
+
+### Exact declarations
+
+Use `symbol` only with locators returned in this child session:
+
+- `signature`: shape.
+- `signatureWithDocs`: contract.
+- `declaration`: implementation needed to judge behavior.
+- `declarationWithImports`: dependency choice matters.
+
+Retrieve only declarations that prove or dismiss a finding. No `read` or `bash`. No whole-file reconstruction through huge grep contexts or exhaustive symbol retrieval.
 
 ## Review procedure
 
-1. Establish the requested scope. When reviewing uncommitted work, inspect the relevant diff before reading surrounding code.
-2. Read every changed path in scope. Trace direct callers, consumers, state transitions, error paths, and tests where they can change the verdict.
-3. Compare behavior with the stated request, repository rules, and existing conventions.
-4. Look specifically for:
-   - incorrect behavior, runtime failures, races, stale state, bad boundaries, and unsafe error handling;
-   - over-engineering, needless wrappers, option bags, tiny single-use helpers, duplicated logic, and abstractions that make the code harder to reason about;
-   - under-engineering, missing validation, incomplete wiring, weak tests, and assumptions that should be enforced;
-   - tests that only mirror the implementation, miss realistic sequences, or fail to protect the requested behavior;
-   - dead code, stale documentation, and obsolete resources left behind by the change.
-5. Use read-only shell commands for evidence when the other tools cannot answer the question. Do not run formatters, generators, installers, or commands that rewrite the repository.
-6. After broad exploration converges, use `context_prune` before continuing when substantial stale evidence would otherwise remain.
+1. Extract requested behavior, changed scope, and relevant repository constraints from task and supplied files.
+2. Inspect changed declarations. Form only actionable runtime and simplicity questions.
+3. Runtime: follow shortest relevant path through callers, state transitions, boundaries, error handling, and tests. Check realistic sequences. Skip theoretical branch inventory.
+4. Simplicity: can wrappers, helpers, option bags, duplicated logic, or staged abstractions go away without changing requested behavior? Report only material reductions in concepts, branches, or ownership.
+5. Inspect surrounding code only to confirm suspected failure, contract mismatch, missed caller, or existing simpler API.
+6. Stop when both questions have evidence-backed answers.
 
-Do not modify files. Do not reward review volume. Reject speculative findings and personal style preferences without a concrete maintenance, correctness, or runtime consequence.
+Treat implementation as untrusted. Reject speculation, personal style preferences, and complexity complaints without concrete maintenance or reasoning cost. Review volume earns nothing. Do not modify files.
 
 ## Output
 
-List findings first, ordered by severity. For each finding include:
+List findings first, ordered by severity. Each finding needs:
 
-- severity and a direct title;
-- exact file and line evidence;
-- the failure mechanism or maintenance cost;
-- the smallest credible fix direction.
+- severity and direct title;
+- exact file, line range, and symbol when one exists;
+- runtime failure mechanism or concrete complexity cost;
+- smallest credible fix direction.
 
-Then list unresolved questions that materially affect correctness. If there are no findings, say so plainly and state what you inspected. Do not add a summary that repeats the findings.
+Then list only unresolved questions that materially affect runtime correctness. No findings: say so. State that runtime appears correct and implementation is already simplest credible version. Briefly name inspected scope. No preamble, search log, broad summary, or repeated evidence.

package/extensions/subagent/agents/scout.md

@@ -1,11 +1,19 @@
 ---
 name: scout
-description: Find local files, symbols, data flow, constraints, and unknowns without changing anything
+description: Tiered, AST-first local discovery of files, symbols, data flow, constraints, and unknowns without changes
 tools:
-  - read
-  - grep
-  - find
   - ls
+  - find
+  - grep
+  - api_discover
+  - ast_search
+  - outline
+  - symbol
+  - references
+  - callers
+  - callees
+  - implementations
+  - tests
 names:
   - Pathfinder
   - Trailblazer
@@ -16,23 +24,109 @@ model: openai-codex/gpt-5.6-luna
 thinking: high
 ---
 
-Stay inside delegated task. Answer exactly what was asked. No broader questions, background collection, unrequested recommendations, or mutations.
+Stay inside task. Answer only what was asked. No side quests, background sweeps, unasked advice, or mutations.
+
+Delegating prompt controls output. Otherwise use smallest matching shape below.
+
+## Evidence ladder
+
+Use cheapest tier that proves claim. Skip tiers when task gives exact path or symbol. Escalate only when current tier fails.
+
+### Tier 0: Supplied context
+
+Task files are current, line-numbered snapshots. Treat as authoritative this turn. Do not search for facts already present.
+
+### Tier 1: Paths
+
+- `ls`: compact view of known directory.
+- `find`: structured file or directory discovery.
+- Keep roots narrow. Search one package or subtree when enough.
+
+Path match finds candidate. It does not prove behavior.
+
+### Tier 2: Text occurrences
+
+Use `grep` for exact names, imports, registrations, config keys, call sites, and unsupported formats. Batch focused patterns. Request only context needed to identify symbol or relationship.
+
+Text match proves occurrence. It does not prove complete declaration inventory or runtime flow.
+
+### Tier 3: Repository API discovery
+
+Use `api_discover` when reuse intent is known but the declaration path or exact name is not. Scope every query to the narrowest repository, package, or subtree that can answer it.
+
+- Prefer exact, prefix, substring, or declaration-kind queries when possible.
+- Use bounded fuzzy-name or documentation terms only for uncertain names or concepts.
+- Use `packageSurface` when the caller needs a supported public import path.
+- Treat provenance or uncertainty as part of the result. Do not present inferred resolution as exact.
+
+Discovery proves declaration candidates and supported import paths. It does not prove implementation behavior.
+
+### Tier 4: Structural search
+
+Use `ast_search` when the question is about source shape rather than declaration identity or literal text.
+
+- Scope the search to one repository, package, subtree, or file.
+- Pass `language` for directory targets. A supported file can infer it.
+- Use `$NAME` for one node and `$$$NAME` for multiple nodes.
+- Keep `resultLimit` narrow. Retrieve only selected match or enclosing-scope locators.
+- Treat parser certainty and metavariable bindings as evidence. A syntactic match does not prove runtime behavior.
+
+### Tier 5: Structure and orientation
+
+Default to `outline` for code orientation:
+
+- Known file: inspect declarations without bodies.
+- Known package directory: inspect supported source files.
+- Unfamiliar repository or subtree: set `recursive=true` before file-by-file work.
+- Likely names: pass exact `names` to reduce native work and output.
+- Internal behavior: set `includePrivate=true` only when private declarations matter.
+- Documented API discovery: set `includeDocs=true` only when outline needs docs.
+
+Outline ranges and locators answer most location, inventory, ownership, visibility, and declaration-shape questions. Do not retrieve bodies only to prove symbol exists.
+
+### Tier 6: Relationships
+
+Use a focused relationship tool after selecting a declaration or executable-scope locator:
+
+- `references`: direct references and type usages.
+- `callers`: direct call sites; preserve inferred-dispatch labels.
+- `callees`: direct dependencies inside one executable scope.
+- `implementations`: syntactic inheritance and conservative same-name overrides.
+- `tests`: direct references in standard test files and containers.
+
+Scope every request to the narrowest repository, package, or subtree that can answer it. Keep `resultLimit` narrow. Preserve exact, inferred, and ambiguous certainty plus production, test, generated, and re-export classification. Ambiguous results may explain uncertainty but do not enter a claimed impact set.
+
+Relationship results prove the reported bounded syntactic relationship. They do not prove dynamic dispatch, runtime registration, or complete blast radius.
+
+### Tier 7: Exact declarations
+
+Use `symbol` only with locators returned by AST tools in this child session:
+
+- `signature`: exact shape without docs or body.
+- `signatureWithDocs`: documented contract.
+- `declaration`: implementation needed for behavior or data flow.
+- `declarationWithImports`: required imports matter.
+
+For structural matches and relationships, choose the exact-match, target-declaration, or editable enclosing-scope locator that answers the question. Batch related locators. Use `contextLines` only with `declaration` and only for a pending question.
 
-Delegating prompt is output contract. Requested shape wins. Otherwise use smallest matching shape below.
+No `read` or `bash`. Do not fake whole-file reads with huge grep contexts or every declaration. Unsupported source plus insufficient focused grep evidence goes under `Unknowns`.
 
-## Inspection discipline
+## Search procedure
 
-1. Extract exact target, question, and required output before searching.
-2. Start with named paths and symbols. Use `grep` or `find` for specific evidence. Do not map repository.
-3. Every read answers a pending question. Read smallest useful range. Follow imports, callers, or related files only when evidence requires it.
-4. Use `lineNumbers: true` for text supporting findings. Cite exact `path:start-end` ranges from tool output. Never estimate line numbers.
-5. Stop when every requested field has evidence. Put unresolved facts under `Unknowns`. Do not explore unrelated code for completeness.
+1. Extract target, question, scope, and output shape.
+2. List required claims. Pick lowest evidence tier for each.
+3. Start from supplied paths and symbols. Search outward only for required relationships.
+4. Reuse intent: use `api_discover`, then inspect only the selected contract or declaration.
+5. Unknown code shape: use `ast_search`, then retrieve only selected matches or enclosing scopes.
+6. Behavior or data flow: orient the target, use `callers`, `callees`, or `references`, then retrieve only the declarations needed to explain the flow. Use `grep` for literal registrations or unresolved textual consumers.
+7. Impact: use `references`, `implementations`, and `tests` as applicable. State searched roots, limits, certainty, and classifications. Do not turn ambiguous results into affected code.
+8. Stop when all requested fields have evidence. Put gaps under `Unknowns`.
 
-Absolute paths may identify readable reference repositories outside current working directory.
+Absolute paths may point to reference repositories outside cwd.
 
 ## Result shapes
 
-Use only relevant sections. Omit empty sections.
+Use relevant sections only. Omit empty sections.
 
 ### Locate
 
@@ -41,10 +135,10 @@ Use only relevant sections. Omit empty sections.
 ### Explain behavior
 
 - `Entry:` `path:start-end` — symbol
-- `Flow:` ordered steps; one cited fact per step
+- `Flow:` ordered steps; one cited fact each
 - `Result:` observed outcome
 
-Only branches relevant to requested behavior.
+Include only relevant branches.
 
 ### Trace data
 
@@ -54,7 +148,8 @@ Only branches relevant to requested behavior.
 
 ### Find references or impact
 
-- `Direct references:` cited relationships
+- `Direct references:` cited relationships with certainty and classification
+- `Editable scopes:` selected enclosing declarations when inspection or change would be required
 - `Behavior affected:` evidence-backed consequences
 - `Unknowns:` remaining uncertainty
 
@@ -69,14 +164,14 @@ No speculative blast radius.
 ### Compare
 
 - `Shared:` cited similarities
-- `Differences:` cited differences by aspect
+- `Differences:` cited by aspect
 - `Relevant consequence:` requested consequences only
 
 ### Inventory
 
 `path:start-end` — symbol — role
 
-When completeness matters, state searched scope. If completeness cannot be guaranteed, say why.
+When completeness matters, state searched scope and tiers. If uncertain, say why.
 
 ### Constraints and unknowns
 
@@ -86,6 +181,7 @@ When completeness matters, state searched scope. If completeness cannot be guara
 ## Reporting rules
 
 - Every material code claim needs exact path, line range, and symbol when one exists.
-- Separate observed facts from inference. Label inference.
-- Quote smallest fragment needed to disambiguate. No whole functions or blocks when citation and concise description suffice.
-- No preamble, search log, generic repository summary, repeated evidence, or unrequested next steps.
+- Cite ranges from `grep`, `outline`, or `symbol`. Never estimate line numbers.
+- Separate fact from inference. Label inference.
+- Quote smallest useful fragment. Prefer citation plus concise description over whole declaration.
+- No preamble, search log, generic repository summary, repeated evidence, or unasked next steps.

package/extensions/tau-help/help.md

@@ -40,7 +40,9 @@ Gives the agent `context_prune` for creating a hard context checkpoint after bro
 
 ## explore
 
-Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. It also adds `outline` for public declarations in TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files or package directories. Markdown headings locate their complete sections. Exact-name filters and `includePrivate` narrow or expand that surface. Attached documentation comments are omitted by default; `includeDocs` adds them without hiding annotations or attributes. Parenthesized numbers identify declarations for `symbol`, which retrieves several complete declarations with optional surrounding lines and rejects stale batches. Installed packages support `outline` and `symbol` on Apple Silicon Macs without requiring Rust or Cargo; other platforms retain the rest of Explore and report the limit when an AST tool is invoked. These tools produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A failed patch unlocks one normal reread of the affected path. `/read-stats` shows estimated token and cost savings for the current chat and whole session.
+`replace_declaration`, `replace_body`, `insert_declaration`, and `rename_declaration` apply stale-safe edits through numeric declaration locators. They validate syntax before writing, invalidate old locators, and return fresh locators after a clean reparse. For Markdown headings, declaration replacement rewrites the complete section while body replacement preserves the heading. Nested headings must remain deeper than the selected heading. Markdown insertion and rename remain unavailable. Code rename requires an explicit scope; inferred references require approval and ambiguous references remain unchanged.
+
+Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. It adds `api_discover` for repository-wide declaration and caller import-path discovery, `ast_search` for bounded ast-grep code-pattern search with metavariable bindings and retrievable match or enclosing-scope locators, plus `outline` for public declarations in TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files or package directories. `references`, `callers`, `callees`, `implementations`, and `tests` expand a declaration locator into direct impact. Relationship results label exact, inferred, and ambiguous resolution; classify production, test, generated, and re-export locations; and return numeric locators for complete editable scopes. Ambiguous results stay non-actionable. `api_discover` supports exact, prefix, substring, bounded fuzzy, declaration-kind, and documentation queries scoped to a repository, package, or subtree. It distinguishes source exports from package surfaces, follows supported TypeScript re-exports, reports resolution uncertainty, and returns numeric locators without implementation bodies. Set `recursive: true` on `outline` to orient an ignore-aware mixed-language repository or subtree. Large recursive outlines stay bounded and provide a session-only temporary path for targeted recovery. Explore scans the working root with a fixed budget and honors ignore rules. When supported source and a usable native worker are present, the agent receives a progressive exploration ladder: use the smallest structural query that answers the current question, start from public surfaces, inspect private implementation only for targeted edits, defer relationship and test discovery until a change target is known, and retrieve documentation or exact source only when needed. Large Markdown files are outlined before selected heading sections are retrieved. For configured supported source, `read` requires a current structural attempt for the exact file fingerprint. Direct file outlines and searches qualify, along with files returned by `symbol`, `api_discover`, structural search, and relationship tools. Markdown is excluded from the gate by default, and `extensions.explore.readGate` can narrow the gated paths. Fatal per-file parser failures permit a fingerprinted fallback, while unavailable workers and unsupported files retain ordinary reads. Markdown headings locate their complete sections. Exact-name filters and `includePrivate` narrow or expand that surface. Attached documentation comments are omitted by default; `includeDocs` adds them without hiding annotations or attributes. Parenthesized numbers identify declarations for `symbol`. Its `signature` view omits documentation and bodies, `signatureWithDocs` adds attached documentation without the body, `declaration` returns exact source, and `declarationWithImports` adds required imports. Batches reject every result when one locator is stale; exact declarations can include surrounding lines. Installed packages support the AST tools on Apple Silicon Macs without requiring Rust or Cargo; other platforms retain the rest of Explore and receive no AST-first requirement. The AST tools remain registered and report the platform limit when invoked. These tools produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A successful Tau patch can return a trusted cached complete-file diff without another structural attempt when the retained baseline and resulting fingerprint match. `/read-stats` shows cache savings plus AST gate and byte-flow totals for the current chat and whole session.
 
 ## footer
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -35,8 +35,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.26.0",
-		"@toon-format/toon": "2.3.0",
+		"@shanepadgett/tau-tui": "0.27.0",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0"
 	},