@shanepadgett/tau-agent 0.22.1 → 0.24.0

package/docs/subagents.md

@@ -26,7 +26,7 @@ Paths may be relative to the parent's current working directory or absolute. Tau
 | **User (global)** | `~/.pi/agent/tau/agents/*.md` | You want the agent in every project |
 | **Project** | nearest trusted `.pi/tau/agents/*.md` | Repo-specific helpers |
 
-Precedence: **project overrides user**, which overrides Tau's built-ins (`review`, `web-research`). Duplicate names in one scope are invalid.
+Precedence: **project overrides user**, which overrides Tau's built-ins (`review`, `scout`, `web-research`). Duplicate names in one scope are invalid.
 
 ## Definition format
 
@@ -83,6 +83,7 @@ Tau assigns one display name to each fresh child and keeps it for follow-up turn
 ## Built-ins
 
 - `review` — adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
+- `scout` — find local files, symbols, data flow, constraints, and unknowns without changing anything
 - `web-research` — `websearch`, `codesearch`, `webfetch`
 - `context-sync` — maps meaningful uncommitted work into `.pi/contexts`. Offered to the coding agent when `extensions.context.sync.enabled` and `sync.automation` are true. Manual `/context-sync` remains when sync is enabled with `automation` false. Validation can auto-run it when `validation.enabled` and `sync.enabled`
 

package/extensions/explore/README.md

@@ -2,8 +2,19 @@
 
 Explore is Tau's first-party filesystem exploration extension.
 
-It exists so agents can inspect paths, discover files, search text, and read file contents with compact model payloads and readable tool rows. Autoread establishes complete-file knowledge while that source remains in active context. Later reads can return an unchanged marker or a smaller diff instead of resending the file.
+It exists so agents can inspect paths, discover files, search text, inspect declarations in supported source languages, and read exact source with compact model payloads and readable tool rows. Autoread establishes complete-file knowledge while that source remains in active context. Later reads can return an unchanged marker or a smaller diff instead of resending the file.
 
 When the source baseline is no longer available, such as after compaction or a cold subagent resume, `read` safely returns the current full source.
 
-Agents invoke it with `ls`, `find`, `grep`, and `read`. Users run `/read-stats` to see estimated token and cost savings for the session.
+Agents invoke it with `ls`, `find`, `grep`, `outline`, `symbol`, and `read`. `outline` returns public declaration signatures and parenthesized numeric locators for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, and Swift files. It also accepts a package directory, which inspects supported files directly inside it. Exact-name filters narrow the result, while `includePrivate` exposes internal declarations. `symbol` accepts those numbers to retrieve several exact declarations in one call, can add bounded surrounding lines, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
+
+Installed packages support `outline` and `symbol` on Apple Silicon Macs. They include the worker, so users do not need Rust or Cargo. On other platforms, the rest of Explore remains available and AST tools report the platform limit when invoked.
+
+Use the cheapest useful step:
+
+1. Outline a package directory to discover its public API.
+2. Add exact names when likely declarations are known.
+3. Set `includePrivate` when implementation work needs internals.
+4. Send several locators to `symbol` for complete declarations.
+5. Add context lines when the edit needs nearby source.
+6. Use ranged or whole-file `read` for cross-cutting logic, exact formatting, or parser gaps.

package/extensions/explore/ast-tools.ts

@@ -0,0 +1,483 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	defineTool,
+	formatSize,
+	keyHint,
+	truncateHead,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+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 { Type } from "typebox";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
+import { formatPathForDisplay, resolveExplorePath, stripLeadingAt } from "./path-display.ts";
+import type {
+	AstClient,
+	AstLanguage,
+	OutlineEntry,
+	OutlineFileResult,
+	OutlineTarget,
+	OutlineTargetResult,
+	SymbolBatchResult,
+} from "./ast-worker.ts";
+
+const outlineParams = Type.Object(
+	{
+		path: Type.String({
+			description: "TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, or Swift source file or directory",
+		}),
+		includePrivate: Type.Optional(Type.Boolean({ description: "Include private declarations and members" })),
+		names: Type.Optional(
+			Type.Array(Type.String(), {
+				minItems: 1,
+				description: "Exact top-level or member declaration names",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+const symbolParams = Type.Object(
+	{
+		locators: Type.Array(Type.Integer({ minimum: 1 }), {
+			minItems: 1,
+			description: "Numeric locators shown in parentheses by outline",
+		}),
+		contextLines: Type.Optional(
+			Type.Integer({ minimum: 0, description: "Lines of source context before and after each declaration" }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+interface AstToolDetails {
+	kind: "outline" | "symbol";
+	result: OutlineTargetResult | SymbolBatchResult;
+	declarationCount: number;
+	sourceBytes: number;
+	returnedBytes: number;
+	avoidedBytes: number;
+	truncated: boolean;
+}
+
+interface LocatorRecord {
+	id: number;
+	token: string;
+	path: string;
+	name: string;
+	stale: boolean;
+}
+
+type OutlineArgs = { path: string; includePrivate?: boolean; names?: string[] };
+
+export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
+	const locators = new Map<number, LocatorRecord>();
+	let nextLocator = 1;
+
+	function compact(
+		text: string,
+		sourceBytes: number,
+		declarationCount: number,
+		kind: AstToolDetails["kind"],
+		result: OutlineTargetResult | SymbolBatchResult,
+	): { text: string; details: AstToolDetails } {
+		const truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+		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,
+			details: {
+				kind,
+				result,
+				declarationCount,
+				sourceBytes,
+				returnedBytes,
+				avoidedBytes: Math.max(0, sourceBytes - returnedBytes),
+				truncated: truncation.truncated,
+			},
+		};
+	}
+
+	function locator(entry: OutlineEntry, path: string): number {
+		const id = nextLocator++;
+		const record = { id, token: entry.locator, path: resolve(path), name: entry.name, stale: false };
+		locators.set(id, record);
+		return id;
+	}
+
+	function renderEntry(entry: OutlineEntry, path: string, language: AstLanguage, indent: string): string {
+		const lines =
+			entry.range.start.line === entry.range.end.line
+				? `${entry.range.start.line + 1}`
+				: `${entry.range.start.line + 1}-${entry.range.end.line + 1}`;
+		let signature = entry.signature.replace(/\s+/g, " ").trim();
+		if (language === "odin") {
+			signature = signature
+				.replace(/\s*([(),:])\s*/g, "$1")
+				.replace(/\s*->\s*/g, "->")
+				.replace(/\s*:=\s*/g, ":=")
+				.replace(/\s*\{\s*$/, "");
+		}
+		const label = signature && signature.includes(entry.name) ? signature : `${entry.name} ${signature}`.trim();
+		return `${indent}${lines}(${locator(entry, path)}): ${label}`;
+	}
+
+	function renderOutlineFile(file: OutlineFileResult, cwd: string): string[] {
+		const lines = [
+			`${formatPathForDisplay(file.path, cwd)} (${file.language}, ${file.lineCount} lines, ${formatSize(file.byteLength)})`,
+		];
+		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`,
+			);
+		}
+		const declarations = file.items.filter((item) => !item.isImport);
+		const groups = new Map<string, typeof declarations>();
+		for (const item of declarations) {
+			const visibility = item.isExported ? "public" : "private";
+			const key = `${visibility} ${item.symbolType}`;
+			const group = groups.get(key);
+			if (group) group.push(item);
+			else groups.set(key, [item]);
+		}
+		for (const [label, items] of groups) {
+			lines.push("", label);
+			for (const item of items) {
+				lines.push(renderEntry(item, file.path, file.language, ""));
+				for (const member of item.members) {
+					lines.push(renderEntry(member, file.path, file.language, "  "));
+				}
+			}
+		}
+		return lines;
+	}
+
+	const outline = defineTool<typeof outlineParams, AstToolDetails>({
+		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.",
+		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.",
+			"Treat each parenthesized number after a line range as that declaration's symbol locator.",
+			"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);
+			const metadata = await stat(path);
+			const target: OutlineTarget = metadata.isDirectory()
+				? { kind: "directory", path }
+				: { kind: "file", path, language: languageForPath(path) };
+			const names = params.names ?? [];
+			const result = await client.outline(target, params.includePrivate ?? false, names, signal);
+			const lines = result.files.flatMap((file, index) => [
+				...(index === 0 ? [] : [""]),
+				...renderOutlineFile(file, ctx.cwd),
+			]);
+			const declarationCount = result.files.reduce(
+				(count, file) =>
+					count +
+					file.items.reduce((fileCount, item) => fileCount + (item.isImport ? 0 : 1 + item.members.length), 0),
+				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);
+			return { content: [{ type: "text", text: output.text }], details: output.details };
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const component =
+				(context.lastComponent as AstCallComponent | undefined) ??
+				new AstCallComponent(
+					rowState,
+					context.toolCallId,
+					"outline",
+					[stripLeadingAt(args.path)],
+					outlineOptionVariants(args),
+					theme,
+				);
+			component.set([stripLeadingAt(args.path)], outlineOptionVariants(args), theme);
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	const symbol = defineTool<typeof symbolParams, AstToolDetails>({
+		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",
+		parameters: symbolParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const records = params.locators.map((id) => {
+				const record = locators.get(id);
+				if (!record) throw new Error(`Unknown symbol locator: ${id}. Run outline again.`);
+				if (record.stale) throw new Error(`Symbol locator ${id} is stale. Run outline again.`);
+				return record;
+			});
+			const result = await client.symbol(
+				[...new Set(records.map((record) => record.token))],
+				params.contextLines ?? 0,
+				signal,
+			);
+			const requestedByToken = new Map(records.map((record) => [record.token, record]));
+			const lines: string[] = [];
+			for (const [blockIndex, block] of result.blocks.entries()) {
+				if (blockIndex > 0) lines.push("");
+				const represented = block.declarationIndexes.flatMap((index) => {
+					const declaration = result.declarations[index];
+					const record = declaration ? requestedByToken.get(declaration.locator) : undefined;
+					return record ? [record] : [];
+				});
+				const range = block.returnedRange;
+				const lineRange =
+					range.start.line === range.end.line
+						? `${range.start.line + 1}`
+						: `${range.start.line + 1}-${range.end.line + 1}`;
+				lines.push(
+					formatPathForDisplay(block.path, ctx.cwd),
+					`${lineRange}(${represented.map((record) => record.id).join(",")}): ${represented.map((record) => record.name).join(", ")}`,
+					block.source,
+				);
+			}
+			const sourceBytes = result.blocks.reduce((count, block) => count + Buffer.byteLength(block.source), 0);
+			const output = compact(lines.join("\n"), sourceBytes, result.declarations.length, "symbol", result);
+			return { content: [{ type: "text", text: output.text }], details: output.details };
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = symbolTargetVariants(args.locators, locators);
+			const component =
+				(context.lastComponent as AstCallComponent | undefined) ??
+				new AstCallComponent(
+					rowState,
+					context.toolCallId,
+					"symbol",
+					targets,
+					[args.contextLines === undefined ? "" : `[context=${args.contextLines}]`],
+					theme,
+				);
+			component.set(targets, [args.contextLines === undefined ? "" : `[context=${args.contextLines}]`], theme);
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderAstResult(result, options.expanded, theme, context);
+		},
+	});
+
+	return {
+		outline,
+		symbol,
+		clear() {
+			locators.clear();
+			nextLocator = 1;
+		},
+		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;
+			}
+		},
+	};
+}
+
+function renderAstResult(
+	result: { content: Array<{ type: string; text?: string }>; details?: AstToolDetails },
+	expanded: boolean,
+	theme: Theme,
+	context: { lastComponent?: Component; isError: boolean },
+): Text {
+	const details = result.details;
+	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 byteSummary = details
+			? `, ${formatSize(details.returnedBytes)} returned, ${formatSize(details.avoidedBytes)} avoided`
+			: "";
+		text.setText(
+			theme.fg("muted", `${declarationCount} ${noun}${byteSummary} (`) +
+				keyHint("app.tools.expand", "to expand") +
+				theme.fg("muted", ")"),
+		);
+		return text;
+	}
+
+	const output = result.content
+		.filter((item): item is { type: string; text: string } => item.type === "text" && typeof item.text === "string")
+		.map((item) => item.text)
+		.join("\n");
+	text.setText(
+		output
+			? output
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n")
+			: "",
+	);
+	return text;
+}
+
+class AstCallComponent implements Component {
+	private readonly rowState: ToolRowStateStore;
+	private readonly rowId: string;
+	private readonly tool: string;
+	private targetVariants: string[];
+	private optionVariants: string[];
+	private theme: Theme;
+
+	constructor(
+		rowState: ToolRowStateStore,
+		rowId: string,
+		tool: string,
+		targetVariants: string[],
+		optionVariants: string[],
+		theme: Theme,
+	) {
+		this.rowState = rowState;
+		this.rowId = rowId;
+		this.tool = tool;
+		this.targetVariants = targetVariants;
+		this.optionVariants = optionVariants;
+		this.theme = theme;
+	}
+
+	set(targetVariants: string[], optionVariants: string[], theme: Theme): void {
+		this.targetVariants = targetVariants;
+		this.optionVariants = optionVariants;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (width <= 0) return [];
+		const prefixWidth = visibleWidth(`${this.tool} → `);
+		const shortestTarget = this.targetVariants.at(-1) ?? "";
+		const minimumTargetWidth = Math.min(12, visibleWidth(shortestTarget));
+		const options =
+			this.optionVariants.find(
+				(candidate) => prefixWidth + minimumTargetWidth + (candidate ? visibleWidth(candidate) + 1 : 0) <= width,
+			) ??
+			this.optionVariants.at(-1) ??
+			"";
+		const optionsWidth = options ? visibleWidth(options) + 1 : 0;
+		const targetWidth = Math.max(1, width - prefixWidth - optionsWidth);
+		const target = this.targetVariants.find((candidate) => visibleWidth(candidate) <= targetWidth) ?? shortestTarget;
+		const displayTarget = truncateLeft(target, targetWidth);
+		const line =
+			formatToolRowTitle(this.rowState, this.rowId, this.tool, this.theme) +
+			this.theme.fg("toolOutput", " → ") +
+			this.theme.fg("accent", displayTarget) +
+			(options ? ` ${this.theme.fg("muted", options)}` : "");
+		return [truncateToWidth(line, width, "")];
+	}
+
+	invalidate(): void {}
+}
+
+function truncateLeft(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(text) <= width) return text;
+	if (width === 1) return "…";
+
+	let suffix = "";
+	for (const character of Array.from(text).reverse()) {
+		if (visibleWidth(`…${character}${suffix}`) > width) break;
+		suffix = character + suffix;
+	}
+	return `…${suffix}`;
+}
+
+function outlineOptionVariants(args: OutlineArgs): string[] {
+	const fixed = args.includePrivate ? ["private"] : [];
+	const names = args.names ?? [];
+	if (names.length === 0) return [fixed.length > 0 ? `[${fixed.join(" ")}]` : ""];
+
+	const variants = [];
+	for (let shown = names.length; shown >= 1; shown -= 1) {
+		const omitted = names.length - shown;
+		const namesText = omitted > 0 ? `${names.slice(0, shown).join(",")},+${omitted}` : names.join(",");
+		variants.push(`[${[...fixed, `names=${namesText}`].join(" ")}]`);
+	}
+	variants.push(`[${[...fixed, `names=${names.length}`].join(" ")}]`);
+	return variants;
+}
+
+function symbolTargetVariants(ids: readonly number[], locators: ReadonlyMap<number, LocatorRecord>): string[] {
+	const records: LocatorRecord[] = [];
+	for (const id of new Set(ids)) {
+		const record = locators.get(id);
+		if (!record) return [ids.join(",")];
+		records.push(record);
+	}
+	const first = records[0];
+	if (!first) return ["symbols"];
+
+	const fileCount = new Set(records.map((record) => record.path)).size;
+	const variants: string[] = [];
+	if (fileCount === 1) {
+		const file = basename(first.path);
+		for (let shown = records.length; shown >= 1; shown -= 1) {
+			const omitted = records.length - shown;
+			const suffix = omitted > 0 ? `,+${omitted}` : "";
+			variants.push(
+				`${file}: ${records
+					.slice(0, shown)
+					.map((record) => record.name)
+					.join(",")}${suffix}`,
+			);
+		}
+		variants.push(`${file}: ${records.length} symbols`);
+		return variants;
+	}
+
+	for (let shown = records.length; shown >= 1; shown -= 1) {
+		const omitted = records.length - shown;
+		const suffix = omitted > 0 ? `,+${omitted}` : "";
+		variants.push(
+			`${records
+				.slice(0, shown)
+				.map((record) => `${record.name}@${basename(record.path)}`)
+				.join(",")}${suffix}`,
+		);
+	}
+	variants.push(`${records.length} symbols in ${fileCount} files`);
+	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";
+		default:
+			throw new Error(`Unsupported outline file type: ${extname(path) || "no extension"}`);
+	}
+}

package/extensions/explore/ast-worker.ts

@@ -0,0 +1,317 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type AstLanguage = "typeScript" | "tsx" | "odin" | "go" | "rust" | "cSharp" | "java" | "kotlin" | "swift";
+
+export type OutlineTarget = { kind: "file"; path: string; language: AstLanguage } | { kind: "directory"; path: string };
+
+export interface SourcePosition {
+	line: number;
+	column: number;
+}
+
+export interface SourceRange {
+	startByte: number;
+	endByte: number;
+	start: SourcePosition;
+	end: SourcePosition;
+}
+
+export interface OutlineEntry {
+	role: "item" | "member";
+	symbolType: string;
+	name: string;
+	range: SourceRange;
+	signature: string;
+	astKind: string;
+	locator: string;
+}
+
+export interface OutlineItem extends OutlineEntry {
+	isImport: boolean;
+	isExported: boolean;
+	members: Array<OutlineEntry & { isPublic: boolean }>;
+}
+
+export interface OutlineFileResult {
+	path: string;
+	language: AstLanguage;
+	sourceFingerprint: string;
+	byteLength: number;
+	lineCount: number;
+	diagnostics: { errorNodes: number; missingNodes: number };
+	items: OutlineItem[];
+}
+
+export interface OutlineTargetResult {
+	path: string;
+	files: OutlineFileResult[];
+	totalByteLength: number;
+	totalLineCount: number;
+}
+
+export interface SymbolDeclaration {
+	locator: string;
+	path: string;
+	language: AstLanguage;
+	sourceFingerprint: string;
+	declarationRange: SourceRange;
+}
+
+export interface SymbolBlock {
+	path: string;
+	returnedRange: SourceRange;
+	declarationIndexes: number[];
+	source: string;
+}
+
+export interface SymbolBatchResult {
+	declarations: SymbolDeclaration[];
+	blocks: SymbolBlock[];
+}
+
+export interface AstClient {
+	outline(
+		target: OutlineTarget,
+		includePrivate: boolean,
+		names: string[],
+		signal: AbortSignal | undefined,
+	): Promise<OutlineTargetResult>;
+	symbol(locators: string[], contextLines: number, signal: AbortSignal | undefined): Promise<SymbolBatchResult>;
+	shutdown(): Promise<void>;
+}
+
+type WorkerRequestPayload =
+	| { operation: "handshake" }
+	| { operation: "outline"; target: OutlineTarget; includePrivate: boolean; names: string[] }
+	| { operation: "symbol"; locators: string[]; contextLines: number };
+
+interface WorkerResponse {
+	requestId: number;
+	protocolVersion: number;
+	success: boolean;
+	result?: Record<string, unknown>;
+	error?: { code?: string; message?: string };
+}
+
+interface PendingRequest {
+	resolve(value: Record<string, unknown>): void;
+	reject(error: Error): void;
+	removeAbortListener(): void;
+}
+
+const PROTOCOL_VERSION = 2;
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const STDERR_BYTES = 16 * 1024;
+
+export type AstWorkerResolution = { command: string } | { error: Error };
+
+export function resolveAstWorkerCommand(
+	packageRoot: string,
+	platform: NodeJS.Platform,
+	arch: string,
+): AstWorkerResolution {
+	const packagedCommand = join(packageRoot, "native-bin", "darwin-arm64", "tau-ast");
+	if (platform === "darwin" && arch === "arm64" && existsSync(packagedCommand)) return { command: packagedCommand };
+
+	const sourceRoot = join(packageRoot, "native", "tau-ast");
+	if (existsSync(join(sourceRoot, "Cargo.toml")))
+		return { command: join(sourceRoot, "target", "release", `tau-ast${platform === "win32" ? ".exe" : ""}`) };
+
+	if (platform === "darwin" && arch === "arm64")
+		return {
+			error: new Error(
+				"tau-ast is missing from this @shanepadgett/tau-agent installation. Reinstall the package before using outline or symbol.",
+			),
+		};
+	return {
+		error: new Error(
+			`Packaged AST tools currently require an Apple Silicon Mac (darwin-arm64); this host is ${platform}-${arch}.`,
+		),
+	};
+}
+
+export class AstWorkerClient implements AstClient {
+	private readonly command: string | undefined;
+	private readonly args: readonly string[];
+	private child: ChildProcessWithoutNullStreams | undefined;
+	private startPromise: Promise<void> | undefined;
+	private pending = new Map<number, PendingRequest>();
+	private nextRequestId = 1;
+	private incoming = Buffer.alloc(0);
+	private stderr = "";
+
+	constructor(command: string | undefined = undefined, args: readonly string[] = []) {
+		this.command = command;
+		this.args = args;
+	}
+
+	async outline(
+		target: OutlineTarget,
+		includePrivate: boolean,
+		names: string[],
+		signal: AbortSignal | undefined,
+	): Promise<OutlineTargetResult> {
+		const result = await this.request({ operation: "outline", target, includePrivate, names }, signal);
+		if (result.kind !== "outline") throw new Error("tau-ast returned the wrong result for outline");
+		return result as unknown as OutlineTargetResult;
+	}
+
+	async symbol(locators: string[], contextLines: number, signal: AbortSignal | undefined): Promise<SymbolBatchResult> {
+		const result = await this.request({ operation: "symbol", locators, contextLines }, signal);
+		if (result.kind !== "symbol") throw new Error("tau-ast returned the wrong result for symbol");
+		return result as unknown as SymbolBatchResult;
+	}
+
+	async shutdown(): Promise<void> {
+		const child = this.child;
+		if (!child) return;
+		this.child = undefined;
+		this.startPromise = undefined;
+		this.rejectPending(new Error("tau-ast worker shut down"));
+		child.stdin.end();
+		if (child.exitCode !== null) return;
+		await Promise.race([
+			new Promise<void>((resolve) => child.once("exit", () => resolve())),
+			new Promise<void>((resolve) => setTimeout(resolve, 250)),
+		]);
+		if (child.exitCode === null) child.kill();
+	}
+
+	private async request(
+		request: WorkerRequestPayload,
+		signal: AbortSignal | undefined,
+	): Promise<Record<string, unknown>> {
+		await this.ensureStarted();
+		return this.send(request, signal);
+	}
+
+	private async ensureStarted(): Promise<void> {
+		if (this.startPromise) {
+			await this.startPromise;
+			return;
+		}
+		if (this.child) return;
+		this.startPromise ??= this.start().finally(() => {
+			this.startPromise = undefined;
+		});
+		await this.startPromise;
+	}
+
+	private async start(): Promise<void> {
+		const resolution = this.command
+			? { command: this.command }
+			: resolveAstWorkerCommand(fileURLToPath(new URL("../../", import.meta.url)), process.platform, process.arch);
+		if ("error" in resolution) throw resolution.error;
+		const child = spawn(resolution.command, this.args, { stdio: ["pipe", "pipe", "pipe"] });
+		this.child = child;
+		this.incoming = Buffer.alloc(0);
+		this.stderr = "";
+		child.stdout.on("data", (chunk: Buffer) => this.receive(child, chunk));
+		child.stderr.on("data", (chunk: Buffer) => {
+			this.stderr = Buffer.from(`${this.stderr}${chunk.toString("utf8")}`)
+				.subarray(-STDERR_BYTES)
+				.toString("utf8");
+		});
+		child.on("error", (error) => this.fail(child, new Error(`Failed to start tau-ast: ${error.message}`)));
+		child.on("exit", (code, signal) => {
+			if (this.child !== child) return;
+			const suffix = this.stderr.trim() ? `: ${this.stderr.trim()}` : "";
+			this.fail(child, new Error(`tau-ast exited (${signal ?? code ?? "unknown"})${suffix}`), false);
+		});
+		try {
+			const result = await this.send({ operation: "handshake" }, undefined);
+			if (result.kind !== "handshake") throw new Error("tau-ast handshake returned the wrong result");
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			this.fail(child, failure);
+			throw failure;
+		}
+	}
+
+	private send(request: WorkerRequestPayload, signal: AbortSignal | undefined): Promise<Record<string, unknown>> {
+		const child = this.child;
+		if (!child) return Promise.reject(new Error("tau-ast worker is not running"));
+		if (signal?.aborted) return Promise.reject(new Error("tau-ast request cancelled"));
+		const requestId = this.nextRequestId++;
+		const payload = Buffer.from(JSON.stringify({ ...request, requestId, protocolVersion: PROTOCOL_VERSION }));
+		const frame = Buffer.allocUnsafe(payload.length + 4);
+		frame.writeUInt32BE(payload.length, 0);
+		payload.copy(frame, 4);
+
+		return new Promise<Record<string, unknown>>((resolve, reject) => {
+			const onAbort = (): void => this.fail(child, new Error("tau-ast request cancelled"));
+			signal?.addEventListener("abort", onAbort, { once: true });
+			this.pending.set(requestId, {
+				resolve,
+				reject,
+				removeAbortListener: () => signal?.removeEventListener("abort", onAbort),
+			});
+			child.stdin.write(frame, (error) => {
+				if (error) this.fail(child, new Error(`Failed to write tau-ast request: ${error.message}`));
+			});
+		});
+	}
+
+	private receive(child: ChildProcessWithoutNullStreams, chunk: Buffer): void {
+		if (this.child !== child) return;
+		this.incoming = Buffer.concat([this.incoming, chunk]);
+		while (this.incoming.length >= 4) {
+			const length = this.incoming.readUInt32BE(0);
+			if (length > MAX_FRAME_BYTES) {
+				this.fail(child, new Error(`tau-ast response frame exceeds ${MAX_FRAME_BYTES} bytes`));
+				return;
+			}
+			if (this.incoming.length < length + 4) return;
+			const payload = this.incoming.subarray(4, length + 4);
+			this.incoming = this.incoming.subarray(length + 4);
+			let response: WorkerResponse;
+			try {
+				response = JSON.parse(payload.toString("utf8")) as WorkerResponse;
+			} catch (error) {
+				this.fail(child, new Error(`tau-ast returned malformed JSON: ${String(error)}`));
+				return;
+			}
+			const pending = this.pending.get(response.requestId);
+			if (!pending) {
+				this.fail(child, new Error(`tau-ast returned unknown request id ${String(response.requestId)}`));
+				return;
+			}
+			this.pending.delete(response.requestId);
+			pending.removeAbortListener();
+			if (response.protocolVersion !== PROTOCOL_VERSION) {
+				const error = new Error(`tau-ast response used protocol ${response.protocolVersion}`);
+				pending.reject(error);
+				this.fail(child, error);
+				return;
+			}
+			if (!response.success) {
+				pending.reject(new Error(response.error?.message ?? response.error?.code ?? "tau-ast request failed"));
+				continue;
+			}
+			if (!response.result || typeof response.result !== "object") {
+				pending.reject(new Error("tau-ast response omitted its result"));
+				continue;
+			}
+			pending.resolve(response.result);
+		}
+	}
+
+	private fail(child: ChildProcessWithoutNullStreams, error: Error, kill = true): void {
+		if (this.child !== child) return;
+		this.child = undefined;
+		this.incoming = Buffer.alloc(0);
+		this.rejectPending(error);
+		if (kill && child.exitCode === null) child.kill();
+	}
+
+	private rejectPending(error: Error): void {
+		for (const request of this.pending.values()) {
+			request.removeAbortListener();
+			request.reject(error);
+		}
+		this.pending.clear();
+	}
+}

package/extensions/explore/index.ts

@@ -1,5 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolve } from "node:path";
+import { onTauEvent } from "../../shared/events.js";
 import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { createAstTools } from "./ast-tools.ts";
+import { AstWorkerClient } from "./ast-worker.ts";
 import { registerAutoread } from "./autoread.ts";
 import { createFindTool } from "./find.ts";
 import { createGrepTool } from "./grep.ts";
@@ -13,7 +17,11 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
 	const readCache = createReadCacheStore();
 	const readSnapshots = createReadSnapshotStore();
+	const astClient = new AstWorkerClient();
+	const ast = createAstTools(astClient, rowState);
 	registerAutoread(pi, rowState);
+	pi.registerTool(ast.outline);
+	pi.registerTool(ast.symbol);
 	pi.registerTool(createLsTool(rowState));
 	pi.registerTool(createFindTool(rowState));
 	pi.registerTool(createGrepTool(rowState));
@@ -31,7 +39,19 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 	pi.on("session_start", () => {
 		rowState.clear();
 		readSnapshots.clear();
+		ast.clear();
+	});
+	onTauEvent(pi, "explore.ast", "tau:file-mutation.applied", (event) => {
+		const paths = event.changes.flatMap((change) => [
+			resolve(event.cwd, change.path),
+			...(change.move ? [resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)] : []),
+		]);
+		ast.invalidate(paths);
 	});
 	pi.on("session_compact", () => readSnapshots.clear());
 	pi.on("session_tree", () => readSnapshots.clear());
+	pi.on("session_shutdown", async () => {
+		ast.clear();
+		await astClient.shutdown();
+	});
 }

package/extensions/publish/index.ts

@@ -10,6 +10,9 @@ const LOCKFILE_PATH = "package-lock.json";
 const WORKFLOW_NAME = "publish.yml";
 const WORKFLOW_WAIT_MS = 10 * 60_000;
 const POLL_INTERVAL_MS = 5_000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const CARGO_BUILD_TIMEOUT_MS = 15 * 60_000;
+const TAU_AST_SCRIPT = "packages/agent/scripts/package-tau-ast.ts";
 
 type Bump = "patch" | "minor" | "major";
 
@@ -65,8 +68,10 @@ async function publish(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<
 	if (!repo) throw new Error("No git repository found.");
 	if (repo.fileCount > 0)
 		throw new Error("Working tree is not clean. Commit or stash every change before publishing.");
-	await run(pi, ctx, "gh", ["auth", "status"], repo.root);
-	await run(pi, ctx, "npm", ["run", "check:package-sources"], repo.root);
+	if (process.platform !== "darwin" || process.arch !== "arm64")
+		throw new Error(`/publish requires darwin-arm64; this host is ${process.platform}-${process.arch}.`);
+	await run(pi, ctx, "gh", ["auth", "status"], repo.root, DEFAULT_COMMAND_TIMEOUT_MS);
+	await run(pi, ctx, "npm", ["run", "check:package-sources"], repo.root, DEFAULT_COMMAND_TIMEOUT_MS);
 
 	const manifests = await loadManifests(repo.root);
 	const currentVersion = sharedVersion(manifests);
@@ -124,10 +129,86 @@ async function completePublish(
 		progress?.update("write package versions");
 		await writeReleaseVersion(root, manifests, version);
 	}
-	progress?.update("npm pack --dry-run @shanepadgett/tau-tui");
-	await run(pi, ctx, "npm", ["pack", "--dry-run", "--workspace", "@shanepadgett/tau-tui"], root);
-	progress?.update("npm pack --dry-run @shanepadgett/tau-agent");
-	await run(pi, ctx, "npm", ["pack", "--dry-run", "--workspace", "@shanepadgett/tau-agent"], root);
+	try {
+		progress?.update("build tau-ast darwin-arm64");
+		await run(
+			pi,
+			ctx,
+			"cargo",
+			[
+				"build",
+				"--release",
+				"--locked",
+				"--target",
+				"aarch64-apple-darwin",
+				"--manifest-path",
+				"packages/agent/native/tau-ast/Cargo.toml",
+			],
+			root,
+			CARGO_BUILD_TIMEOUT_MS,
+		);
+		progress?.update("stage tau-ast");
+		await run(
+			pi,
+			ctx,
+			process.execPath,
+			["--experimental-strip-types", TAU_AST_SCRIPT, "stage"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+		progress?.update("smoke test tau-ast");
+		await run(
+			pi,
+			ctx,
+			process.execPath,
+			["--experimental-strip-types", TAU_AST_SCRIPT, "smoke"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+		progress?.update("npm pack --dry-run @shanepadgett/tau-tui");
+		await run(
+			pi,
+			ctx,
+			"npm",
+			["pack", "--dry-run", "--workspace", "@shanepadgett/tau-tui"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+		progress?.update("npm pack --dry-run @shanepadgett/tau-agent");
+		await run(
+			pi,
+			ctx,
+			"npm",
+			["pack", "--dry-run", "--workspace", "@shanepadgett/tau-agent"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+		progress?.update("verify packed tau-ast");
+		await run(
+			pi,
+			ctx,
+			process.execPath,
+			["--experimental-strip-types", TAU_AST_SCRIPT, "verify-pack"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+	} finally {
+		await run(
+			pi,
+			ctx,
+			process.execPath,
+			["--experimental-strip-types", TAU_AST_SCRIPT, "clean"],
+			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
+		);
+	}
+
+	const trackedNativeFiles = await git.run(["ls-files", "--", "packages/agent/native-bin"], { cwd: root });
+	const stagedNativeFiles = await git.run(["diff", "--cached", "--name-only", "--", "packages/agent/native-bin"], {
+		cwd: root,
+	});
+	if (trackedNativeFiles || stagedNativeFiles)
+		throw new Error("Release blocked: packages/agent/native-bin/ contains tracked or staged files.");
 
 	if (tag) {
 		progress?.update("git add release files");
@@ -225,8 +306,9 @@ async function run(
 	command: string,
 	args: string[],
 	cwd: string,
+	timeout: number,
 ): Promise<string> {
-	const result = await pi.exec(command, args, { cwd, signal: ctx.signal, timeout: 120_000 });
+	const result = await pi.exec(command, args, { cwd, signal: ctx.signal, timeout });
 	if (result.code === 0) return result.stdout.trim();
 	throw new Error([result.stderr, result.stdout].filter(Boolean).join("\n").trim() || `${command} failed`);
 }
@@ -258,6 +340,7 @@ async function monitorWorkflow(
 				"databaseId,status,conclusion,url",
 			],
 			root,
+			DEFAULT_COMMAND_TIMEOUT_MS,
 		);
 		const workflowRun = (JSON.parse(output) as WorkflowRun[])[0];
 		if (workflowRun) {

package/extensions/publish/publish-ui.ts

@@ -4,8 +4,12 @@ import { ToolPanel } from "@shanepadgett/tau-tui";
 
 const RELEASE_STEPS = [
 	"write package versions",
+	"build tau-ast darwin-arm64",
+	"stage tau-ast",
+	"smoke test tau-ast",
 	"npm pack --dry-run @shanepadgett/tau-tui",
 	"npm pack --dry-run @shanepadgett/tau-agent",
+	"verify packed tau-ast",
 	"git add release files",
 	"git commit",
 	"git tag",

package/extensions/subagent/README.md

@@ -9,6 +9,7 @@ Each fresh child also gets a display name from its agent definition. The name st
 Tau includes these built-in agents:
 
 - `review` performs adversarial, read-only code review for correctness, runtime risks, duplication, and over- or under-engineering.
+- `scout` finds local files, symbols, data flow, constraints, and unknowns without changing anything.
 - `web-research` researches web and code sources with `websearch`, `codesearch`, and `webfetch`.
 - `context-sync` maps meaningful uncommitted work into `.pi/contexts`. Agent-driven use is `extensions.context.sync.automation` (requires `sync.enabled`). `/context-sync` is the manual/nudge path when sync is enabled. Validation can auto-run it when validation and sync are enabled.
 

package/extensions/subagent/cmux-dashboard.ts

@@ -71,54 +71,82 @@ function cap(text: string | undefined, limit: number): string {
 	return `${normalized.slice(0, limit - 1)}…`;
 }
 
+function tableCell(text: string, limit: number): string {
+	const compact = cap(text.replace(/\s+/g, " ").trim(), limit);
+	return compact.replaceAll("|", "&#124;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+function quote(text: string): string {
+	return cap(text, 1200)
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.split("\n")
+		.map((line) => `> ${line}`)
+		.join("\n");
+}
+
+function elapsed(durationMs: number): string {
+	if (durationMs < 1000) return "<1s";
+	if (durationMs < 60_000) return `${(durationMs / 1000).toFixed(1)}s`;
+	const minutes = Math.floor(durationMs / 60_000);
+	const seconds = Math.floor((durationMs % 60_000) / 1000);
+	return `${minutes}m ${seconds}s`;
+}
+
+function dashboardState(status: SubagentInvocationSnapshot["status"]): string {
+	switch (status) {
+		case "waiting":
+			return "queued";
+		case "completed":
+			return "done";
+		case "aborted":
+			return "stopped";
+		default:
+			return status;
+	}
+}
+
 export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSnapshot[]): string {
 	const ordered = [...snapshots].sort(
 		(a, b) => a.startedAt - b.startedAt || a.invocationId.localeCompare(b.invocationId),
 	);
-	const activeCount = ordered.filter(
-		(snapshot) => snapshot.status !== "completed" && snapshot.status !== "failed" && snapshot.status !== "aborted",
+	const activeCount = ordered.filter((snapshot) =>
+		["waiting", "starting", "running"].includes(snapshot.status),
 	).length;
-	const lines = [
-		"# Subagent dashboard",
-		"",
-		`Active: ${activeCount} · Completed: ${ordered.length - activeCount}`,
-		"",
-	];
+	const doneCount = ordered.filter((snapshot) => snapshot.status === "completed").length;
+	const failedCount = ordered.filter((snapshot) => snapshot.status === "failed").length;
+	const stoppedCount = ordered.filter((snapshot) => snapshot.status === "aborted").length;
+	const counts = [`${activeCount} active`, `${doneCount} done`];
+	if (failedCount > 0) counts.push(`${failedCount} failed`);
+	if (stoppedCount > 0) counts.push(`${stoppedCount} stopped`);
+	const lines = ["# Subagents", "", counts.join(" · "), ""];
 	if (ordered.length === 0) {
-		lines.push("_No active invocations._", "");
+		lines.push("_No subagents._", "");
 		return lines.join("\n");
 	}
+	lines.push("| Agent | State | Last tool | Calls | Time |", "| --- | --- | --- | ---: | ---: |");
 	for (const details of ordered) {
-		const identity = `${details.displayName} (${details.agent})`;
+		const latest = details.actions.at(-1);
+		const currentTool = details.currentActivity?.match(/^\S+/)?.[0];
+		const lastTool = currentTool ?? latest?.tool ?? "";
 		lines.push(
-			`## ${identity}`,
-			"",
-			`\`${details.status}${details.phase ? ` · ${details.phase}` : ""}\` · inv ${details.invocationId} · tools ${details.toolCalls} · ${(details.durationMs / 1000).toFixed(1)}s`,
-			`model ${details.model} · thinking ${details.thinkingLevel}`,
+			`| ${tableCell(`${details.displayName} (${details.agent})`, 48)} | ${dashboardState(details.status)} | ${tableCell(lastTool, 32) || "—"} | ${details.toolCalls} | ${elapsed(details.durationMs)} |`,
+		);
+	}
+	lines.push("", "## Inputs", "");
+	for (const details of ordered) {
+		lines.push(
+			`### ${tableCell(details.displayName, 80)}`,
 			"",
-			"### Task",
+			`${tableCell(details.agent, 80)} · ${tableCell(details.invocationId, 80)}`,
 			"",
-			cap(details.task, 1200) || "_(empty)_",
+			quote(details.task) || "> _(empty)_",
 		);
-		if (details.currentActivity) {
-			lines.push("", "### Current", "", cap(details.currentActivity, 400));
-		}
-		if (details.actions.length > 0) {
-			lines.push("", "### Actions", "");
-			for (const action of details.actions.slice(-12)) {
-				const mark = action.error ? "!" : "·";
-				lines.push(`- ${mark} ${cap(action.summary, 200)}`);
-			}
-			if (details.omittedActions > 0) {
-				lines.push(`- _${details.omittedActions} earlier actions omitted_`);
-			}
-		}
-		if (details.response) {
-			lines.push("", "### Response", "", cap(details.response, 3000));
-		}
-		if (details.error) {
-			lines.push("", "### Error", "", cap(details.error, 800));
+		if (details.files.length > 0) {
+			lines.push("", "**Files**", "");
+			for (const file of details.files) lines.push(`- ${tableCell(file, 300)}`);
 		}
+		if (details.error) lines.push("", "**Error**", "", quote(details.error));
 		lines.push("");
 	}
 	return lines.join("\n");

package/extensions/subagent/run.ts

@@ -77,6 +77,7 @@ export interface SubagentDetails {
 export interface SubagentInvocationSnapshot extends SubagentDetails {
 	invocationId: string;
 	startedAt: number;
+	files: readonly string[];
 }
 
 export interface SubagentThread {

package/extensions/subagent/runtime.ts

@@ -243,6 +243,7 @@ export class SubagentRuntime {
 			}),
 			invocationId,
 			startedAt,
+			files: [...(options.files ?? [])],
 		};
 		const active: ActiveInvocation = {
 			snapshot: initialSnapshot,
@@ -330,6 +331,7 @@ export class SubagentRuntime {
 				...details,
 				invocationId,
 				startedAt,
+				files: current.snapshot.files,
 				threadId: details.threadId ?? threadId,
 				agent: details.agent || agent,
 				displayName: details.displayName || displayName,

package/extensions/tau-help/help.md

@@ -40,7 +40,7 @@ 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`. They 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.
+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, and Swift files or package directories. Exact-name filters and `includePrivate` narrow or expand that surface. 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.
 
 ## footer
 
@@ -100,7 +100,7 @@ Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed draf
 
 ## subagent
 
-Gives Tau a subagent delegation tool for isolated, focused work. The built-in `review` agent performs adversarial, read-only code reviews; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in agents show the pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after the active cohort finishes.
+Gives Tau a subagent delegation tool for isolated, focused work. The built-in `review` agent performs adversarial, read-only code reviews; `scout` finds local files, symbols, data flow, constraints, and unknowns without changing anything; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in agents show the pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after the active cohort finishes.
 
 ## tau-help
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.22.1",
+	"version": "0.24.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -31,10 +31,11 @@
 		"themes/**/*",
 		"docs/**/*",
 		"schemas/**/*",
+		"native-bin/**/*",
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.22.1",
+		"@shanepadgett/tau-tui": "0.24.0",
 		"@toon-format/toon": "2.3.0",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0"