@shanepadgett/tau-agent 0.28.1 → 0.30.0

package/extensions/explore/README.md

@@ -6,7 +6,7 @@ Pi keeps ordinary filesystem tools (`ls`, `find`, `grep`, `read`). Explore adds
 
 ## Large `read` / autoread
 
-When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a registered source file (including Markdown) above `explore.read.structureThresholdLines` (default 200) returns an **outline** — declarations or headings — not the full body. Use ranged `read` (`offset`/`limit`, capped by `explore.read.maxRangeLines`) or `show` for bodies and sections. Small files and unregistered paths stay ordinary Pi full text. Set `explore.read.enabled` to `false` to turn the overlay off.
+When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a registered source file (including Markdown) above `explore.read.structureThresholdLines` (default 200) returns an **outline** — declarations or headings — not the full body. Use ranged `read` (`offset`/`limit`) or `show` for bodies and sections. Small files and unregistered paths stay ordinary Pi full text. Set `explore.read.enabled` to `false` to turn the overlay off.
 
 ## Tools
 

package/extensions/explore/ast/read/hook.ts

@@ -1,21 +1,15 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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 {
-	countLines,
-	formatLargeReadOutline,
-	rangedReadOverLimitMessage,
-	readCallKind,
-	shouldOutlineFullRead,
-	type ExploreReadSettings,
-} from "./policy.ts";
+import { formatLargeReadOutline, readCallKind, shouldOutlineFullRead, type ExploreReadSettings } from "./policy.ts";
 
 type ReadOverlayResult = {
 	content: Array<{ type: "text"; text: string }>;
+	details: ReadToolDetails;
 	isError: boolean;
 };
 
@@ -47,9 +41,7 @@ export function registerReadOutlineHook(pi: ExtensionAPI, engineFor: (cwd: strin
 		if (engine.registry.adapterForPath(absolutePath) === undefined) return;
 
 		const kind = readCallKind(event.input);
-		if (kind === "ranged") {
-			return enforceRangedLimit(event.input, event.content, readSettings.maxRangeLines);
-		}
+		if (kind === "ranged") return;
 
 		return substituteLargeFullRead({
 			engine,
@@ -89,6 +81,7 @@ async function substituteLargeFullRead(options: {
 			result.file.rows.length === 0 ? "No declarations" : formatOutlineFile(result.file, options.engine.cwd, false);
 		return {
 			content: [{ type: "text", text: formatLargeReadOutline(outlineText) }],
+			details: {},
 			isError: false,
 		};
 	} catch {
@@ -96,30 +89,7 @@ async function substituteLargeFullRead(options: {
 	}
 }
 
-function enforceRangedLimit(
-	input: Record<string, unknown>,
-	content: ReadonlyArray<{ type: string; text?: string }>,
-	maxRangeLines: number,
-): ReadOverlayResult | undefined {
-	const limit = typeof input.limit === "number" && Number.isFinite(input.limit) ? input.limit : undefined;
-	const returnedLines = countLines(textFromContent(content));
-	const message = rangedReadOverLimitMessage({ limit, returnedLines, maxRangeLines });
-	if (message === undefined) return undefined;
-	return {
-		content: [{ type: "text", text: message }],
-		isError: true,
-	};
-}
-
 function readPathInput(input: Record<string, unknown>): string | undefined {
 	const path = input.path;
 	return typeof path === "string" && path.length > 0 ? path : undefined;
 }
-
-function textFromContent(content: ReadonlyArray<{ type: string; text?: string }>): string {
-	const parts: string[] = [];
-	for (const part of content) {
-		if (part.type === "text" && typeof part.text === "string") parts.push(part.text);
-	}
-	return parts.join("\n");
-}

package/extensions/explore/ast/read/policy.ts

@@ -1,28 +1,12 @@
 export type ExploreReadSettings = {
 	enabled: boolean;
 	structureThresholdLines: number;
-	maxRangeLines: number;
 };
 
 export type ReadCallKind = "full" | "ranged";
 
 const LARGE_READ_OUTLINE_INSTRUCTION = "large file: use ranged read or show for bodies";
 
-/** Newline-based line count (empty string → 0). */
-export function countLines(text: string): number {
-	if (text.length === 0) return 0;
-	let count = 1;
-	for (let i = 0; i < text.length; i += 1) {
-		const code = text.charCodeAt(i);
-		if (code === 10) count += 1;
-		else if (code === 13) {
-			count += 1;
-			if (text.charCodeAt(i + 1) === 10) i += 1;
-		}
-	}
-	return count;
-}
-
 export function readCallKind(input: { offset?: unknown; limit?: unknown }): ReadCallKind {
 	const hasOffset = typeof input.offset === "number" && Number.isFinite(input.offset);
 	const hasLimit = typeof input.limit === "number" && Number.isFinite(input.limit);
@@ -33,22 +17,6 @@ export function shouldOutlineFullRead(lineCount: number, structureThresholdLines
 	return lineCount > structureThresholdLines;
 }
 
-/** Hard-error message when a ranged read exceeds maxRangeLines; undefined when allowed. */
-export function rangedReadOverLimitMessage(options: {
-	limit: number | undefined;
-	returnedLines: number;
-	maxRangeLines: number;
-}): string | undefined {
-	const { limit, returnedLines, maxRangeLines } = options;
-	if (typeof limit === "number" && limit > maxRangeLines) {
-		return `Range limit ${limit} exceeds explore.read.maxRangeLines (${maxRangeLines}). Shrink limit and retry.`;
-	}
-	if (returnedLines > maxRangeLines) {
-		return `Ranged read returned ${returnedLines} lines; max is explore.read.maxRangeLines (${maxRangeLines}). Set a smaller limit and retry.`;
-	}
-	return undefined;
-}
-
 export function formatLargeReadOutline(outlineText: string): string {
 	if (outlineText.length === 0) return LARGE_READ_OUTLINE_INSTRUCTION;
 	return `${outlineText}\n${LARGE_READ_OUTLINE_INSTRUCTION}`;

package/extensions/explore/index.ts

@@ -21,6 +21,7 @@ import {
 import { createReverseDepsTool } from "./ast/tools/reverse-deps.ts";
 import { createShowTool } from "./ast/tools/show.ts";
 import { registerExploreGuidance } from "./guidance.ts";
+import { registerExploreOutlineInjection } from "./outline-injection.ts";
 import { registerExploreAutoread } from "./read/autoread.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
@@ -61,6 +62,7 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 	pi.registerTool(createContextTool(rowState, temporaryOutput, engineFor, graphFor));
 	registerReadOutlineHook(pi, engineFor);
 	registerExploreAutoread(pi, rowState, engineFor);
+	registerExploreOutlineInjection(pi, rowState, temporaryOutput, engineFor);
 	registerExploreGuidance(pi, engineFor);
 
 	pi.on("session_start", async (_event, ctx) => {

package/extensions/explore/outline-injection.ts

@@ -0,0 +1,151 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Marker } from "@shanepadgett/tau-tui";
+import { BoundedTextResultBuilder } from "../../shared/bounded-text-result.ts";
+import {
+	registerOutlineInjectionProvider,
+	type OutlineInjectionDetails,
+	type PreparedOutlineInjection,
+} from "../../shared/outline-injection.ts";
+import type { TemporaryOutputStore } from "../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "./ast/engine.ts";
+import { formatOutlineEmpty, formatOutlineFile } from "./ast/format/outline.ts";
+import { outlinePath } from "./ast/queries/outline.ts";
+import { formatPathForDisplay, stripLeadingAt } from "./traverse.ts";
+
+const OPTIONS = { includePrivate: false, includeDocs: false, names: [] as readonly string[] };
+
+export function registerExploreOutlineInjection(
+	pi: ExtensionAPI,
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+): void {
+	registerOutlineInjectionProvider(pi, async (request) => {
+		const messages: PreparedOutlineInjection[] = [];
+		const warnings: string[] = [];
+		const engine = engineFor(request.cwd);
+		for (let index = 0; index < request.paths.length; index += 1) {
+			const path = stripLeadingAt(request.paths[index] ?? "");
+			assertCurrent(request.signal, request.isLifecycleCurrent);
+			try {
+				const abort = request.signal ?? new AbortController().signal;
+				const result = await outlinePath(engine, path, OPTIONS, abort);
+				if (result.mode !== "file") throw new Error("Working-memory outlines require a file path");
+				const body =
+					result.file.rows.length === 0
+						? formatOutlineEmpty(OPTIONS.names)
+						: formatOutlineFile(result.file, engine.cwd, false);
+				const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+				let content: string;
+				try {
+					await builder.appendBlock(
+						result.file.path,
+						formatPathForDisplay(result.file.path, engine.cwd),
+						`${path}\n${body}`,
+					);
+					assertCurrent(request.signal, request.isLifecycleCurrent);
+					content = (await builder.finish()).content;
+				} catch (error) {
+					await builder.abort();
+					throw error;
+				}
+				messages.push({
+					customType: "tau.explore.outline" as const,
+					content,
+					display: true as const,
+					details: {
+						v: 1 as const,
+						rowId: `${request.batchId}:${index}`,
+						path,
+						cwd: request.cwd,
+						batchId: request.batchId,
+					},
+				});
+			} catch (error) {
+				if (request.signal?.aborted || !request.isLifecycleCurrent()) throw error;
+				warnings.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return { messages, warnings };
+	});
+
+	pi.registerMessageRenderer<OutlineInjectionDetails>("tau.explore.outline", (message, options, theme) => {
+		const details = parseDetails(message.details);
+		if (!details) return undefined;
+		return new OutlineMessageComponent(
+			rowState,
+			details.rowId,
+			details.path,
+			typeof message.content === "string" ? message.content : "",
+			options.expanded,
+			theme,
+		);
+	});
+}
+
+function assertCurrent(signal: AbortSignal | undefined, isLifecycleCurrent: () => boolean): void {
+	signal?.throwIfAborted();
+	if (!isLifecycleCurrent()) throw new Error("Outline preparation crossed a session lifecycle boundary");
+}
+
+function parseDetails(value: unknown): OutlineInjectionDetails | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const details = value as Record<string, unknown>;
+	if (
+		details.v !== 1 ||
+		typeof details.rowId !== "string" ||
+		typeof details.path !== "string" ||
+		typeof details.cwd !== "string" ||
+		typeof details.batchId !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		v: 1,
+		rowId: details.rowId,
+		path: details.path,
+		cwd: details.cwd,
+		batchId: details.batchId,
+	};
+}
+
+class OutlineMessageComponent {
+	private readonly rowState: ToolRowStateStore;
+	private readonly rowId: string;
+	private readonly path: string;
+	private readonly content: string;
+	private readonly expanded: boolean;
+	private readonly theme: Theme;
+
+	constructor(
+		rowState: ToolRowStateStore,
+		rowId: string,
+		path: string,
+		content: string,
+		expanded: boolean,
+		theme: Theme,
+	) {
+		this.rowState = rowState;
+		this.rowId = rowId;
+		this.path = path;
+		this.content = content;
+		this.expanded = expanded;
+		this.theme = theme;
+		this.rowState.watch(this.rowId, () => this.invalidate());
+	}
+
+	render(width: number): string[] {
+		const marker = new Marker({
+			theme: this.theme,
+			state: this.rowState.get(this.rowId) === "pruned" ? "warning" : "complete",
+			label: "outline",
+			parts: [this.path],
+		}).render(width);
+		if (!this.expanded) return marker;
+		return [...marker, ...new Text(this.theme.fg("dim", this.content), 1, 0).render(width)];
+	}
+
+	invalidate(): void {}
+}

package/extensions/explore/settings.ts

@@ -10,7 +10,6 @@ export default defineTauExtensionSettings({
 		read: {
 			enabled: true as boolean,
 			structureThresholdLines: 200 as number,
-			maxRangeLines: 200 as number,
 		},
 	},
 	schema: Type.Object(
@@ -47,13 +46,6 @@ export default defineTauExtensionSettings({
 									"Registered source at or under this line count may be full-read. Above it, full read model-visible result is outline only.",
 							}),
 						),
-						maxRangeLines: Type.Optional(
-							Type.Integer({
-								default: 200,
-								minimum: 1,
-								description: "Maximum lines returned by one ranged read on registered source.",
-							}),
-						),
 					},
 					{ additionalProperties: false },
 				),

package/extensions/ideas/browser.ts

@@ -6,17 +6,15 @@ import {
 	type TextRecordSelectPanelConfig,
 	type TextRecordSelectResult,
 } from "@shanepadgett/tau-tui";
+import { errorText } from "../../shared/text.ts";
 import { deleteIdea, type Idea, ideasFilePath, loadIdeas, updateIdea } from "./store.ts";
 
-const CONFIG: Omit<TextRecordSelectPanelConfig, "path"> = {
+const CONFIG: Omit<TextRecordSelectPanelConfig<Idea>, "path" | "destructiveAction"> = {
 	title: "Ideas",
 	emptyMessage: "No ideas yet. Use /ideas <text> to log one.",
 	primaryLabel: "insert",
 	expandActiveItem: true,
-	actions: [
-		{ id: "edit", key: Key.ctrl("e"), hint: rawHint("ctrl+e", "edit") },
-		{ id: "delete", key: Key.ctrl("d"), hint: rawHint("ctrl+d", "delete") },
-	],
+	actions: [{ id: "edit", key: Key.ctrl("e"), hint: rawHint("ctrl+e", "edit") }],
 };
 
 export async function browseIdeas(ctx: ExtensionCommandContext): Promise<Idea | undefined> {
@@ -34,15 +32,6 @@ export async function browseIdeas(ctx: ExtensionCommandContext): Promise<Idea |
 		if (result.kind === "cancel") return undefined;
 		if (result.kind === "primary") return result.item;
 
-		if (result.actionId === "delete") {
-			const ok = await ctx.ui.confirm("Delete idea?", result.item.text);
-			if (ok) {
-				await deleteIdea(ctx.cwd, result.item.id);
-				ctx.ui.notify("Idea deleted.", "info");
-			}
-			continue;
-		}
-
 		// edit: native multiline editor, prefilled with the current text.
 		const edited = await ctx.ui.editor("Edit idea", result.item.text);
 		if (edited == null) continue;
@@ -60,7 +49,29 @@ async function show(
 	ideas: readonly Idea[],
 	path: string,
 ): Promise<TextRecordSelectResult<Idea>> {
-	return ctx.ui.custom<TextRecordSelectResult<Idea>>((_tui, theme, _keybindings, done) =>
-		createTextRecordSelectPanel(theme, ideas, { ...CONFIG, path }, done),
+	return ctx.ui.custom<TextRecordSelectResult<Idea>>((tui, theme, _keybindings, done) =>
+		createTextRecordSelectPanel(
+			tui,
+			theme,
+			ideas,
+			{
+				...CONFIG,
+				path,
+				destructiveAction: {
+					id: "delete",
+					key: Key.ctrl("d"),
+					hint: rawHint("ctrl+d", "delete"),
+					confirmLabel: () => "Delete idea?",
+					runningLabel: "Deleting idea…",
+					onConfirm: async (item) => {
+						const next = await deleteIdea(ctx.cwd, item.id);
+						ctx.ui.notify("Idea deleted.", "info");
+						return next;
+					},
+					onError: (error) => ctx.ui.notify(`Idea delete failed: ${errorText(error)}`, "error"),
+				},
+			},
+			done,
+		),
 	);
 }

package/extensions/review/README.md

@@ -0,0 +1,11 @@
+# Review
+
+Run `/review` to inspect current repository's staged, unstaged, and untracked work in a fresh isolated session. Choose one focused pass:
+
+- `simplify` looks for code and concepts that can disappear or reuse what already exists.
+- `architecture` performs a nuclear maintainability review and accepts substantial redesign when ownership, reuse, or structure is poor.
+- `correctness` checks runtime bugs and failures after architecture is accepted.
+
+Run a mode directly with `/review simplify`, `/review architecture`, or `/review correctness`. Run `/review show` to reopen latest result on current session branch.
+
+Results stay outside parent agent context. In result view, press `a` to send review to agent's next turn or `e` to export Markdown under `.pi/tau/reviews/`.

package/extensions/review/index.ts

@@ -0,0 +1,135 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { createGitRunner, loadRepoStatus } from "../../shared/git.ts";
+import { createInjectedContext } from "../../shared/injected-context.ts";
+import { errorText } from "../../shared/text.ts";
+import {
+	formatReviewMarkdown,
+	isReviewRecord,
+	isReviewMode,
+	REVIEW_ENTRY_TYPE,
+	type ReviewMode,
+	type ReviewRecord,
+} from "./model.ts";
+import { ReviewProgressPanel, ReviewResultPanel, type ReviewResultAction } from "./panel.ts";
+import { runReview } from "./session.ts";
+
+export default function reviewExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("review", {
+		description: "Run or show an isolated simplify, architecture, or correctness review",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui" || !ctx.isProjectTrusted()) {
+				ctx.ui.notify("/review requires a trusted TUI project", "warning");
+				return;
+			}
+			await ctx.waitForIdle();
+			const requested = args.trim().toLowerCase();
+			if (requested === "show") {
+				const latest = latestReview(ctx.sessionManager.getBranch());
+				if (!latest) {
+					ctx.ui.notify("No review exists on this session branch", "warning");
+					return;
+				}
+				await showReview(pi, ctx, latest);
+				return;
+			}
+
+			let mode: ReviewMode | undefined;
+			if (requested) {
+				if (!isReviewMode(requested)) {
+					ctx.ui.notify("Usage: /review [simplify|architecture|correctness|show]", "warning");
+					return;
+				}
+				mode = requested;
+			} else {
+				const selected = await ctx.ui.select("Review mode", ["Simplify", "Architecture", "Correctness"]);
+				if (!selected) return;
+				const normalized = selected.toLowerCase();
+				if (!isReviewMode(normalized)) return;
+				mode = normalized;
+			}
+
+			const status = await loadRepoStatus(createGitRunner(pi, ctx));
+			if (!status) {
+				ctx.ui.notify("/review requires a Git repository", "warning");
+				return;
+			}
+			if (status.fileCount === 0) {
+				ctx.ui.notify("Nothing to review: working tree is clean", "info");
+				return;
+			}
+
+			const controller = new AbortController();
+			const signal = ctx.signal ? AbortSignal.any([controller.signal, ctx.signal]) : controller.signal;
+			let failure: string | undefined;
+			const output = await ctx.ui.custom<ReviewRecord | undefined>((tui, theme, keys, done) => {
+				const panel = new ReviewProgressPanel(tui, theme, mode, keys, () => controller.abort());
+				void runReview({
+					ctx,
+					root: status.root,
+					mode,
+					parentThinkingLevel: pi.getThinkingLevel(),
+					signal,
+					onProgress: (line) => panel.update(line),
+				})
+					.then((result) => done({ ...result, mode, root: status.root, createdAt: new Date().toISOString() }))
+					.catch((error: unknown) => {
+						failure = errorText(error);
+						done(undefined);
+					});
+				return panel;
+			});
+			if (!output) {
+				ctx.ui.notify(
+					signal.aborted ? "Review cancelled" : `Review failed: ${failure ?? "unknown error"}`,
+					signal.aborted ? "info" : "error",
+				);
+				return;
+			}
+			pi.appendEntry(REVIEW_ENTRY_TYPE, output);
+			await showReview(pi, ctx, output);
+		},
+	});
+}
+
+export function latestReview(entries: readonly SessionEntry[]): ReviewRecord | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		if (entry?.type !== "custom" || entry.customType !== REVIEW_ENTRY_TYPE) continue;
+		if (isReviewRecord(entry.data)) return entry.data;
+	}
+	return undefined;
+}
+
+async function showReview(pi: ExtensionAPI, ctx: ExtensionContext, review: ReviewRecord): Promise<void> {
+	const action = await ctx.ui.custom<ReviewResultAction>(
+		(tui, theme, keys, done) => new ReviewResultPanel(tui, theme, keys, review, done),
+		{
+			overlay: true,
+			overlayOptions: { anchor: "top-center", width: "80%", minWidth: 68, maxHeight: "90%", margin: 1 },
+		},
+	);
+	if (action === "send") {
+		try {
+			await pi.sendMessage(
+				createInjectedContext(formatReviewMarkdown(review), { source: "review", title: `${review.mode} review` }),
+				{ triggerTurn: false, deliverAs: "nextTurn" },
+			);
+			ctx.ui.notify("Review queued for agent's next turn", "info");
+		} catch (error) {
+			ctx.ui.notify(`Failed to send review: ${errorText(error)}`, "error");
+		}
+	} else if (action === "export") {
+		try {
+			const directory = join(review.root, ".pi", "tau", "reviews");
+			await mkdir(directory, { recursive: true });
+			const timestamp = review.createdAt.replace(/[^0-9A-Za-z-]/g, "-");
+			const path = join(directory, `${timestamp}-${review.mode}.md`);
+			await writeFile(path, formatReviewMarkdown(review), { encoding: "utf8", mode: 0o600 });
+			ctx.ui.notify(`Review exported to ${path}`, "info");
+		} catch (error) {
+			ctx.ui.notify(`Failed to export review: ${errorText(error)}`, "error");
+		}
+	}
+}

package/extensions/review/model.ts

@@ -0,0 +1,144 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+const MAX_SUMMARY_LENGTH = 2_000;
+const MAX_FINDINGS = 12;
+const MAX_PATH_LENGTH = 400;
+const MAX_LINES_LENGTH = 80;
+const MAX_FINDING_LENGTH = 1_500;
+const REVIEW_MODE_SCHEMA = Type.Union([
+	Type.Literal("simplify"),
+	Type.Literal("architecture"),
+	Type.Literal("correctness"),
+]);
+const REVIEW_FINDING_SCHEMA = Type.Object(
+	{
+		severity: Type.Union([
+			Type.Literal("critical"),
+			Type.Literal("high"),
+			Type.Literal("medium"),
+			Type.Literal("low"),
+		]),
+		path: Type.String({
+			minLength: 1,
+			maxLength: MAX_PATH_LENGTH,
+			description: "Repository-relative file path",
+		}),
+		lines: Type.String({
+			minLength: 1,
+			maxLength: MAX_LINES_LENGTH,
+			description: "Exact line or line range, or N/A when no source line exists",
+		}),
+		finding: Type.String({
+			minLength: 1,
+			maxLength: MAX_FINDING_LENGTH,
+			description: "Failure mechanism or concrete maintenance cost",
+		}),
+		fix: Type.String({
+			minLength: 1,
+			maxLength: MAX_FINDING_LENGTH,
+			description: "Smallest credible fix direction",
+		}),
+	},
+	{ additionalProperties: false },
+);
+const REVIEW_OUTPUT_SCHEMA = Type.Object(
+	{
+		verdict: Type.Union([Type.Literal("pass"), Type.Literal("changes-required")]),
+		summary: Type.String({
+			minLength: 1,
+			maxLength: MAX_SUMMARY_LENGTH,
+			description: "Short, blunt prose verdict",
+		}),
+		findings: Type.Array(REVIEW_FINDING_SCHEMA, { maxItems: MAX_FINDINGS }),
+	},
+	{ additionalProperties: false },
+);
+const REVIEW_RECORD_SCHEMA = Type.Object(
+	{
+		...REVIEW_OUTPUT_SCHEMA.properties,
+		mode: REVIEW_MODE_SCHEMA,
+		root: Type.String({ minLength: 1 }),
+		createdAt: Type.String({ minLength: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+export type ReviewMode = Static<typeof REVIEW_MODE_SCHEMA>;
+export type ReviewOutput = Static<typeof REVIEW_OUTPUT_SCHEMA>;
+export type ReviewRecord = Static<typeof REVIEW_RECORD_SCHEMA>;
+
+export const REVIEW_ENTRY_TYPE = "tau.review.result";
+
+export const REVIEW_RESULT_TOOL = {
+	name: "review_result",
+	description: "Submit final review. This is the only allowed final response.",
+	parameters: REVIEW_OUTPUT_SCHEMA,
+} satisfies Tool;
+
+const MODE_INSTRUCTIONS: Record<ReviewMode, string> = {
+	simplify: [
+		"Delete concepts before improving them.",
+		"Find behavior that was not requested, code the repository or platform already provides, duplicate concepts, needless files, wrappers, helpers, types, options, and branches.",
+		"Judge against the smallest credible implementation. Runtime correctness is out of scope unless a problem directly proves needless complexity.",
+	].join(" "),
+	architecture: [
+		"Assume the current architecture is poor and likely needs substantial rework. Make existing structure prove it should remain.",
+		"Inspect ownership, boundaries, shared roots, reuse, sources of truth, coupling, cohesion, and clean coding patterns.",
+		"Prefer a coherent redesign over preserving a bad local structure. Runtime correctness is secondary and should appear only when it supports an architectural finding.",
+	].join(" "),
+	correctness: [
+		"Architecture is accepted for this pass.",
+		"Look only for concrete runtime bugs, broken state transitions, unsafe boundaries, data loss, error-handling failures, and affected callers.",
+		"Do not report style, simplification, or architecture preferences.",
+	].join(" "),
+};
+
+export function buildReviewPrompt(root: string, mode: ReviewMode): string {
+	return [
+		`Review uncommitted work in ${root}.`,
+		"Inspect staged, unstaged, and untracked changes. Stay centered on changed behavior, but inspect surrounding ownership and callers when needed to prove a finding.",
+		"Do not modify files. Do not report theoretical concerns or personal preferences. Use the cheapest evidence that settles each point.",
+		MODE_INSTRUCTIONS[mode],
+		`Call ${REVIEW_RESULT_TOOL.name} exactly once as the final action. Write no final prose outside that tool call.`,
+		"Order findings by severity. Every finding needs an exact repository-relative path and lines when source exists, a concrete mechanism or cost, and the smallest credible fix. Return an empty findings array and verdict pass when nothing actionable remains.",
+	].join("\n\n");
+}
+
+export function formatReviewMarkdown(review: ReviewRecord): string {
+	const findings = review.findings.length
+		? review.findings.flatMap((finding, index) => [
+				`### ${index + 1}. ${finding.severity.toUpperCase()} — ${finding.path}:${finding.lines}`,
+				"",
+				finding.finding,
+				"",
+				`**Fix:** ${finding.fix}`,
+				"",
+			])
+		: ["No actionable findings.", ""];
+	return [
+		`# ${reviewModeLabel(review.mode)} review`,
+		"",
+		`**Verdict:** ${review.verdict}`,
+		`**Created:** ${review.createdAt}`,
+		"",
+		review.summary,
+		"",
+		"## Findings",
+		"",
+		...findings,
+	].join("\n");
+}
+
+export function isReviewMode(value: string): value is ReviewMode {
+	return Value.Check(REVIEW_MODE_SCHEMA, value);
+}
+
+export function reviewModeLabel(mode: ReviewMode): string {
+	return `${mode.charAt(0).toUpperCase()}${mode.slice(1)}`;
+}
+
+export function isReviewRecord(value: unknown): value is ReviewRecord {
+	return Value.Check(REVIEW_RECORD_SCHEMA, value);
+}