@shanepadgett/tau-agent 0.44.0 → 0.45.0

package/extensions/soul/index.ts

@@ -1,144 +1,68 @@
-import { getCurrentTools, toToolDeclaration } from "@earendil-works/pi-ai";
-import { createHash } from "node:crypto";
-import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { emitTauEvent, onTauEventImmediately } from "../../shared/events.ts";
-import { readPromptValues, renderBaseline, renderUpdate } from "./context.ts";
-import {
-	admittedTools,
-	BASELINE_TYPE,
-	projectPrompt,
-	restorePrompt,
-	UPDATE_TYPE,
-	type SavedBaseline,
-	type SavedUpdate,
-} from "./state.ts";
-import { toolChangeReason } from "./tools.ts";
+import { getDocsPath, getExamplesPath, getReadmePath, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { emitTauEvent } from "../../shared/events.ts";
+import { collectPromptSources } from "../../shared/prompt-contributions.ts";
+import { FIXED_INSTRUCTIONS } from "./prompt.ts";
 
-const CHECKPOINT_TYPE = "tau.soul.prefix";
-interface PrefixCheckpoint {
-	baselineEntryId: string;
-	count: number;
-	hash: string;
-}
+const CAPTURE_TYPE = "tau.soul.capture";
 
-export default function soulExtension(pi: ExtensionAPI): void {
-	let inputs: BuildSystemPromptOptions | null = null;
+const DOCUMENTATION = `Consult Pi or Tau documentation when the request concerns their usage or extension APIs.
+Pi documentation:
+- Main documentation: ${getReadmePath()}
+- Additional docs: ${getDocsPath()}
+- Examples: ${getExamplesPath()}
+- Resolve docs/... and examples/... under those installed paths, not the working directory.
+- Extensions: docs/extensions.md and examples/extensions/; themes: docs/themes.md; skills: docs/skills.md; prompt templates: docs/prompt-templates.md; TUI: docs/tui.md; keybindings: docs/keybindings.md; SDK: docs/sdk.md; providers: docs/custom-provider.md; models: docs/models.md; packages: docs/packages.md; environment: docs/environment-variables.md.
+- Read the relevant documentation and follow related Markdown references before implementing Pi integrations.`;
 
-	pi.on("session_start", () => {
-		inputs = null;
-	});
-	pi.on("session_shutdown", () => {
-		inputs = null;
-	});
-	pi.on("before_agent_start", (event) => {
-		// Keep the shared options reference until all contributors have finished.
-		inputs = event.systemPromptOptions;
-	});
+export default function soulExtension(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", async (event, ctx) => {
+		const options = event.systemPromptOptions;
 
-	onTauEventImmediately(pi, "soul.tools", "tau:prompt.tools.check", ({ ctx, tools, reject }) => {
-		try {
-			const saved = restorePrompt(ctx.sessionManager.getBranch());
-			if (!saved || !ctx.model) return;
-			const previous = admittedTools(saved);
-			// getAllTools exposes schemas but not constrainedSampling. Preserve that
-			// metadata here; the request boundary checks the complete Pi declarations.
-			const reason = toolChangeReason(
-				ctx.model,
-				previous,
-				tools.map((tool) => ({
-					...previous.find((candidate) => candidate.name === tool.name),
-					...tool,
-				})),
-			);
-			if (reason) reject(reason);
-		} catch (error) {
-			reject(String(error));
+		// Sources that refresh on compaction are read once per compaction epoch and saved on the branch.
+		const branch = ctx.sessionManager.getBranch();
+		let epochStart = 0;
+		branch.forEach((entry, index) => {
+			if (entry.type === "compaction") epochStart = index + 1;
+		});
+		let captured: Record<string, string> = {};
+		for (const entry of branch.slice(epochStart)) {
+			if (entry.type === "custom" && entry.customType === CAPTURE_TYPE)
+				captured = entry.data as Record<string, string>;
+		}
+		const sources = collectPromptSources(pi);
+		const missing = sources.filter((source) => source.refresh === "compaction" && !(source.key in captured));
+		if (missing.length > 0) {
+			const read = await Promise.all(missing.map(async (source) => [source.key, await source.read(ctx)] as const));
+			captured = { ...captured, ...Object.fromEntries(read) };
+			pi.appendEntry(CAPTURE_TYPE, captured);
 		}
-	});
 
-	pi.on("context_with_system", async (event, ctx) => {
-		try {
-			if (!inputs) throw new Error("Soul has no loaded prompt inputs.");
-			if (inputs.forceSystemPrompt !== undefined)
-				throw new Error(
-					"A forced system prompt conflicts with Soul. Remove the extension's systemPrompt replacement.",
-				);
-			const branch = ctx.sessionManager.getBranch();
-			const newestFirst = [...branch].reverse();
-			const projection = ctx.sessionManager.buildSessionProjection();
-			const anchor = [...projection.entries].reverse().find((entry) => entry.messages.length > 0);
-			if (!anchor) throw new Error("Soul has no conversation anchor.");
-			const saved = restorePrompt(branch);
-			const active = new Set(pi.getActiveTools());
-			const requested = getCurrentTools(event.messages)
-				.filter((tool) => active.has(tool.name))
-				.map(toToolDeclaration);
-			if (saved && ctx.model) {
-				const reason = toolChangeReason(ctx.model, admittedTools(saved), requested);
-				if (reason) throw new Error(reason);
-			}
-			const values = await readPromptValues(pi, ctx, inputs, saved === null);
-			if (!saved) {
-				pi.appendEntry<SavedBaseline>(BASELINE_TYPE, {
-					version: 1,
-					compactionId: newestFirst.find((entry) => entry.type === "compaction")?.id ?? null,
-					afterEntryId: anchor.sourceEntry.id,
-					text: renderBaseline(inputs, values),
-					values,
-					initialTools: getCurrentTools(event.messages),
-				});
-			} else {
-				const previous = new Map(saved.baseline.values.map((value) => [value.key, value]));
-				for (const update of saved.updates) for (const value of update.data.values) previous.set(value.key, value);
-				const currentKeys = new Set(values.map((value) => value.key));
-				for (const value of previous.values()) {
-					if (value.refresh === "append" && !currentKeys.has(value.key)) values.push({ ...value, text: "" });
-				}
-				const changed = values.filter((value) => previous.get(value.key)?.text !== value.text);
-				const tools = new Map(admittedTools(saved).map((tool) => [tool.name, tool]));
-				const added = requested.some((tool) => !tools.has(tool.name));
-				for (const tool of requested) tools.set(tool.name, tool);
-				if (changed.length > 0 || added)
-					pi.appendEntry<SavedUpdate>(UPDATE_TYPE, {
-						version: 1,
-						baselineEntryId: saved.entryId,
-						afterEntryId: anchor.sourceEntry.id,
-						text: renderUpdate(changed),
-						values: changed,
-						tools: [...tools.values()],
-					});
-			}
-			const admitted = restorePrompt(ctx.sessionManager.getBranch());
-			if (!admitted) throw new Error("Soul failed to save its baseline.");
-			const messages = projectPrompt(event.messages, admitted, ctx);
-			const checkpointEntry = newestFirst.find(
-				(entry) => entry.type === "custom" && entry.customType === CHECKPOINT_TYPE,
-			);
-			const checkpoint = checkpointEntry?.type === "custom" ? (checkpointEntry.data as PrefixCheckpoint) : null;
-			if (checkpoint?.baselineEntryId === admitted.entryId) {
-				const prefix = createHash("sha256")
-					.update(JSON.stringify(messages.slice(0, checkpoint.count)))
-					.digest("hex");
-				if (prefix !== checkpoint.hash)
-					throw new Error("Previously sent conversation content changed. Compact before continuing.");
-			}
-			const hash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
-			if (hash !== checkpoint?.hash)
-				pi.appendEntry<PrefixCheckpoint>(CHECKPOINT_TYPE, {
-					baselineEntryId: admitted.entryId,
-					count: messages.length,
-					hash,
-				});
-			emitTauEvent(pi, "tau:prompt.snapshot", {
-				text: [admitted.baseline.text, ...admitted.updates.map((update) => update.data.text)].join("\n\n"),
-			});
-			return { messages };
-		} catch (error) {
-			ctx.ui.notify(`Soul stopped this request: ${error instanceof Error ? error.message : String(error)}`, "error");
-			ctx.abort();
-			// Pi currently enters the provider with an aborted signal; do not weaken that
-			// cancellation into a fallback prompt. See soul-request-check-findings.md.
-			return undefined;
+		const active = pi.getActiveTools();
+		const guidance = [
+			...new Set([
+				...(active.includes("bash") ? ["Use bash for file operations like ls, rg, find."] : []),
+				...active.flatMap((name) => options.toolGuidelines[name] ?? []),
+				...options.promptGuidelines,
+			]),
+		]
+			.map((rule) => `- ${rule}`)
+			.join("\n");
+
+		const sections = new Map<string, string[]>();
+		const add = (section: string, text: string) => {
+			if (text.trim()) sections.set(section, [...(sections.get(section) ?? []), text]);
+		};
+		add("documentation", DOCUMENTATION);
+		add("tool-guidance", guidance);
+		if (options.customPrompt) add("additional-instructions", options.customPrompt);
+		for (const source of sources) {
+			add(source.section, source.refresh === "append" ? await source.read(ctx) : (captured[source.key] ?? ""));
 		}
+
+		// Pi diffs these sections against the prompt already in the transcript and appends a patch only for
+		// sections whose text changed, so unchanged sections keep the cached prefix.
+		options.customPrompt = FIXED_INSTRUCTIONS;
+		for (const name of [...sections.keys()].sort()) options.sections[name] = (sections.get(name) ?? []).join("\n\n");
+		emitTauEvent(pi, "tau:prompt.snapshot", { text: event.systemPrompt });
 	});
 }

package/extensions/soul/prompt.ts

@@ -9,6 +9,8 @@ Use headings or tables when they improve clarity. In conversational, personal, o
 Use technical terms when they help. Keep paths, commands, API names, and errors exact.
 State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results.
 Give useful facts instead of praise, ceremony, or commentary about following instructions.
+Talk about the user's work, not the machinery directing your behavior. Do not volunteer commentary about system prompts, tool prompts, internal instructions, the harness, or automatic validation. Discuss those mechanisms only when the user asks about them as the subject of the work.
+Finish with the concrete result. Do not hedge completion because silent validation is pending, announce that checks will run or rerun, or explain what happens when you end the turn. When a failure is reported, fix it and describe the correction without narrating the validation process.
 You are a partner, and the user expects you to act like one.
 </communication>
 

package/extensions/tau-help/help.md

@@ -32,6 +32,10 @@ Records private prompt-cache fingerprints without storing prompt content. Run `/
 
 Adds `/clear-screen` to clear terminal output without changing the session.
 
+## codex-priority
+
+Requests Codex priority processing (Fast mode) for every `gpt-6-luna` request on the `openai-codex` provider, including the agent loop, compaction, tool approval, auto-naming, commit, and handoff. It has no command or setting. Cost uses OpenAI's 2.5x Fast mode rate for GPT-6 models. Do not run another extension that overlays `openai-codex` or sets `service_tier`.
+
 ## commit
 
 Adds `/commit` for semantic commit grouping, review, and committing selected repository changes.
@@ -40,6 +44,10 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 Adds `/cost-report` to build an HTML spend report from local session usage. Pick a time frame (past 7 days, current week, current month, year to date, or a specific month) and scope (current project or all sessions). Tau scans sessions, writes under `~/.pi/tau/cost-reports/`, opens the file, and notifies with the path. Empty windows warn without writing a file.
 
+## compaction
+
+Writes compaction summaries (automatic, `/compact`, and overflow recovery) with a cheaper model from the same provider as the session, so Opus, GPT-6.1 Sol, and Astra sessions do not pay their own rates to summarize themselves. Summaries never cross providers, and a notice names the model that wrote each one. When no cheaper model fits, Pi's default compaction runs.
+
 ## context
 
 Adds `/context` to browse and inject reusable repository work scopes from `.pi/contexts`. Selecting entries injects them once into the conversation: `read` paths as complete files, `show` targets as current declaration slices, `outline` paths as Explore structures, and one hidden note listing `references` plus instructions to treat the injected material as current. Run `/context` again to inject more. Edit catalog files by hand when work scopes change. Domain folders are `NN_slug` tabs (ordered by the two-digit prefix; UI shows the slug), TOML files are concepts, and TOML sections are selectable entries.
@@ -106,7 +114,7 @@ Runs configured commands while keeping their output out of agent context when th
 
 ## soul
 
-Supplies Tau's communication, discussion, planning, execution, and coding instructions. Saves a prompt baseline across turns, reload, and resume; refreshes it after successful compaction. Operational changes arrive as saved context updates without rewriting earlier instructions. Tool groups that cannot load without changing the cached prefix wait for successful compaction.
+Supplies Tau's communication, discussion, planning, execution, and coding instructions, plus tool guidance and context from other Tau extensions. The date and directory snapshot stay fixed until successful compaction. Other changes, such as an edited `AGENTS.md` after `/reload`, arrive as appended updates without rewriting earlier instructions.
 
 ## stash
 
@@ -126,7 +134,7 @@ Reviews agent `bash` and `script_runner` requests before they run. Common read-o
 
 ## tool-loader
 
-Progressively exposes registered specialist tool groups through `load_tools`. Tau registers `web`, `image`, and `appshot`; project or global package extensions can add groups with `registerDeferredToolGroup()` from `@shanepadgett/tau-agent`. Compatible models load tools without replacing the cached prefix. Otherwise, requested groups are queued until successful compaction; loading never triggers compaction automatically.
+Keeps specialist tool groups out of every request as deferred tools and lets the agent load them with Pi's `tool_search`. Tau registers `web`, `image`, and `appshot`; project or global package extensions can add groups with `registerDeferredToolGroup()` from `@shanepadgett/tau-agent`. All models can load tools. Compatible models preserve the cached prefix; other models can incur a cache miss when tools are activated. Loading never triggers compaction.
 
 ## web
 

package/extensions/tool-approval/README.md

@@ -2,13 +2,13 @@
 
 Reviews agent `bash` and `script_runner` requests before they run.
 
-Common read-only bash commands skip review and run immediately. Other bash and every `script_runner` request go to a separate reviewer. When the agent requests several tools at once, Tau reviews up to three requests concurrently, with one model review focused on each request. Tau uses the reviewer model for the current provider, then the current chat model if that reviewer is unavailable or fails. If a reviewer model is unavailable or fails, Tau notifies and tries the next one. The reviewer returns a validated decision and one concise paragraph that explains the request.
+Common read-only bash commands skip review and run immediately. Other bash and every `script_runner` request go to a separate reviewer. For a `script_runner` retry with `scriptId` and edits, Tau reconstructs the full resulting script before review and runs that exact source after approval. A retry with missing or invalid stored source is blocked. When the agent requests several tools at once, Tau reviews up to three requests concurrently, with one model review focused on each request. Tau uses the reviewer model for the current provider, then the current chat model if that reviewer is unavailable or fails. If a reviewer model is unavailable or fails, Tau notifies and tries the next one. The reviewer returns a validated decision and one concise paragraph that explains the request.
 
 With `autoApprove` enabled, reviewer-approved requests run without another confirmation. Tau shows a user-only marker with the reviewer model after those auto-approvals. Common read-only bash that skips review does not get a marker. Routine local development work should be approved, including requests that modify project files or run scripts. The reviewer asks for human approval only when it finds a concrete destructive, system, production, privileged, or security-sensitive effect.
 
-When approval is required, Tau shows one paragraph that explains the effect and risk without repeating the request. If several requests need approval, their confirmation windows open one at a time. If the reviewer fails or returns a malformed decision, Tau asks for direct human approval instead of running it automatically. Tau also sends an attention notification when the approval window opens.
+When approval is required, Tau shows one paragraph that explains the effect and risk without repeating the request. For `script_runner`, human confirmation also shows the complete script that will run. If several requests need approval, their confirmation windows open one at a time. If the reviewer fails or returns a malformed decision, Tau asks for direct human approval instead of running it automatically. Tau also sends an attention notification when the approval window opens.
 
-In the terminal approval panel, move between Approve and Reject, press `n` to add a note to the highlighted choice, then press Enter to choose. Enter saves an edited note before choosing; Escape cancels note editing or blocks the request from the choice list. A rejection note tells the agent why the request was blocked. An approval note reaches the agent with the tool result; it does not change the request being approved. To ask for a different request, reject it with a note. Long notes are truncated. RPC clients use the standard confirmation dialog without notes.
+In the terminal approval panel, move between Approve and Reject, press `j` or `k` to scroll a script, press `n` to add a note to the highlighted choice, then press Enter to choose. Enter saves an edited note before choosing; Escape cancels note editing or blocks the request from the choice list. A rejection note tells the agent why the request was blocked. An approval note reaches the agent with the tool result; it does not change the request being approved. To ask for a different request, reject it with a note. Long notes are truncated. RPC clients use the standard confirmation dialog without notes.
 
 Configure under `extensions.toolApproval`:
 

package/extensions/tool-approval/index.ts

@@ -1,4 +1,4 @@
-import type { ThinkingLevel, Tool } from "@earendil-works/pi-ai";
+import type { Tool } from "@earendil-works/pi-ai";
 import {
 	isToolCallEventType,
 	type ExtensionAPI,
@@ -8,7 +8,10 @@ import {
 import { Marker } from "@shanepadgett/tau-tui";
 import { Type } from "typebox";
 import { emitAgentBlocked } from "../../shared/agent-blocked.ts";
-import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { emitTauEvent } from "../../shared/events.ts";
+import { generateToolValidated } from "../../shared/model-fallback/index.ts";
+import { resolveEffortCandidates } from "../../shared/model-effort.ts";
+import type { ScriptSourceStore } from "../../shared/script-source.ts";
 import { errorText, truncAt } from "../../shared/text.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { isAllowlistedBash } from "./allowlist.ts";
@@ -57,15 +60,6 @@ const REVIEW_TOOL = {
 	parameters: REVIEW_SCHEMA,
 } satisfies Tool;
 
-const REVIEW_MODELS: ReadonlyArray<{ provider: string; model: string; reasoning: ThinkingLevel }> = [
-	{ provider: "openai", model: "gpt-6-luna", reasoning: "medium" },
-	{ provider: "openai-codex", model: "gpt-6-luna", reasoning: "medium" },
-	{ provider: "anthropic", model: "claude-sonnet-5", reasoning: "medium" },
-	{ provider: "xai", model: "grok-4.5", reasoning: "low" },
-	{ provider: "openrouter", model: "deepseek/deepseek-v4.1-flash", reasoning: "high" },
-	{ provider: "opencode-go", model: "deepseek-v4.1-flash", reasoning: "high" },
-];
-
 type ToolReview =
 	| { decision: "approved"; summary: string }
 	| { decision: "requires_user_approval"; summary: string; reason: string };
@@ -112,10 +106,16 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 	async function requestToolApproval(
 		ctx: ExtensionContext,
 		toolCallId: string,
-		toolName: ApprovalToolName,
+		request: ToolApprovalRequest,
 		title: string,
 		body: string,
 	): Promise<{ block: true; reason: string } | undefined> {
+		const toolName = request.toolName;
+		const source =
+			toolName === "script_runner" && typeof request.input.script === "string" ? request.input.script : undefined;
+		if (toolName === "script_runner" && source === undefined) {
+			return block("script_runner source is unavailable for manual approval");
+		}
 		if (!ctx.hasUI) return block(`${toolLabel(toolName)} needs confirmation, but interactive UI is unavailable`);
 		try {
 			emitAgentBlocked(pi, {
@@ -124,11 +124,14 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 				source: "tool-approval.review",
 			});
 			if (ctx.mode !== "tui") {
-				const confirmed = await ctx.ui.confirm(title, body);
+				const confirmed = await ctx.ui.confirm(
+					title,
+					source === undefined ? body : `${body}\n\nFull script:\n${source}`,
+				);
 				return confirmed ? undefined : block(`${toolLabel(toolName)} rejected by user`);
 			}
 			const answer = await ctx.ui.custom<ApprovalAnswer | undefined>(
-				(tui, theme, keys, done) => new ToolApprovalPanel(tui, theme, keys, title, body, done),
+				(tui, theme, keys, done) => new ToolApprovalPanel(tui, theme, keys, title, body, source, done),
 			);
 			if (!answer) return block(`${toolLabel(toolName)} approval cancelled by user`);
 			const note = truncAt(answer.note, 800);
@@ -147,6 +150,7 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 	pi.on("session_start", async (_event, ctx) => {
 		batchReviews = undefined;
 		pendingNotes.clear();
+		scriptSourceStoreFrom(pi)?.clearApprovals();
 		await refreshSettings(ctx);
 	});
 
@@ -161,6 +165,17 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 			return block(`tool approval settings failed to load: ${truncAt(message, 600)}`);
 		}
 		if (!settings.enabled) return undefined;
+		const scriptStore = scriptSourceStoreFrom(pi);
+		if (request.toolName === "script_runner") {
+			try {
+				if (!scriptStore) return block("script_runner source store is unavailable for review");
+				const { source } = scriptStore.resolve(request.input);
+				request.input.script = source;
+				delete request.input.edits;
+			} catch (error) {
+				return block(`script_runner source could not be reviewed: ${errorText(error)}`);
+			}
+		}
 
 		if (request.toolName === "bash") {
 			const command = request.input.command;
@@ -174,7 +189,7 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 
 		ctx.ui.setStatus(STATUS_KEY, `reviewing ${toolLabel(request.toolName)}`);
 		try {
-			batchReviews ??= await reviewAssistantRequests(ctx, event, request);
+			batchReviews ??= await reviewAssistantRequests(ctx, event, request, scriptStore);
 			if (ctx.signal?.aborted) return block("Tool review cancelled");
 			const cached = batchReviews.get(event.toolCallId);
 			batchReviews.delete(event.toolCallId);
@@ -188,41 +203,51 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 			}
 			if (ctx.signal?.aborted) return block("Tool review cancelled");
 			const { review, provider, model } = result;
+			let rejected: { block: true; reason: string } | undefined;
 			if (review.decision === "requires_user_approval") {
-				return requestToolApproval(
+				rejected = await requestToolApproval(
 					ctx,
 					event.toolCallId,
-					request.toolName,
+					request,
 					`Approve high-impact ${toolLabel(request.toolName)}?`,
 					formatApproval(review.summary, review.reason),
 				);
-			}
-			if (settings.autoApprove) {
+			} else if (settings.autoApprove) {
 				pi.appendEntry<AutoApprovedMarker>(AUTO_APPROVED_TYPE, {
 					toolName: request.toolName,
 					provider,
 					model,
 				});
-				return undefined;
+			} else {
+				rejected = await requestToolApproval(
+					ctx,
+					event.toolCallId,
+					request,
+					`Run reviewed ${toolLabel(request.toolName)}?`,
+					formatApproval(review.summary, "Automatic approval is disabled."),
+				);
 			}
-			return requestToolApproval(
-				ctx,
-				event.toolCallId,
-				request.toolName,
-				`Run reviewed ${toolLabel(request.toolName)}?`,
-				formatApproval(review.summary, "Automatic approval is disabled."),
-			);
+			if (!rejected && request.toolName === "script_runner") {
+				if (!scriptStore) return block("script_runner source store is unavailable for approval");
+				scriptStore.approve(event.toolCallId, request.input);
+			}
+			return rejected;
 		} catch (error) {
 			if (ctx.signal?.aborted) return block("Tool review cancelled");
 			const message = singleLine(errorText(error));
 			ctx.ui.notify(`Tool review failed; manual approval required: ${truncAt(message, 600)}`, "warning");
-			return requestToolApproval(
+			const rejected = await requestToolApproval(
 				ctx,
 				event.toolCallId,
-				request.toolName,
+				request,
 				`Automatic ${toolLabel(request.toolName)} review failed. Continue?`,
-				`The automatic review failed, so Tau could not summarize this ${toolLabel(request.toolName)}. Approve it only if you understand the request shown above.`,
+				`The automatic review failed, so Tau could not summarize this ${toolLabel(request.toolName)}. Approve it only if you understand ${request.toolName === "script_runner" ? "the full script below" : "the request shown above"}.`,
 			);
+			if (!rejected && request.toolName === "script_runner") {
+				if (!scriptStore) return block("script_runner source store is unavailable for approval");
+				scriptStore.approve(event.toolCallId, request.input);
+			}
+			return rejected;
 		} finally {
 			ctx.ui.setStatus(STATUS_KEY, undefined);
 		}
@@ -250,15 +275,29 @@ export default function toolApprovalExtension(pi: ExtensionAPI): void {
 	pi.on("agent_end", () => {
 		batchReviews = undefined;
 		pendingNotes.clear();
+		scriptSourceStoreFrom(pi)?.clearApprovals();
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {
 		batchReviews = undefined;
 		pendingNotes.clear();
+		scriptSourceStoreFrom(pi)?.clearApprovals();
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 }
 
+function scriptSourceStoreFrom(pi: ExtensionAPI): ScriptSourceStore | undefined {
+	let store: ScriptSourceStore | undefined;
+	let count = 0;
+	emitTauEvent(pi, "tau:script-runner.source-store", {
+		accept(candidate) {
+			store = candidate;
+			count++;
+		},
+	});
+	return count === 1 ? store : undefined;
+}
+
 function approvalRequest(event: ToolCallEvent): ToolApprovalRequest | undefined {
 	if (isToolCallEventType("bash", event)) return { toolName: "bash", input: event.input };
 	if (isToolCallEventType<"script_runner", Record<string, unknown>>("script_runner", event)) {
@@ -284,6 +323,7 @@ async function reviewAssistantRequests(
 	ctx: ExtensionContext,
 	event: ToolCallEvent,
 	currentRequest: ToolApprovalRequest,
+	scriptStore: ScriptSourceStore | undefined,
 ): Promise<Map<string, CachedReview>> {
 	const reviews = new Map<string, CachedReview>();
 	const assistant = ctx.sessionManager
@@ -308,6 +348,17 @@ async function reviewAssistantRequests(
 			const command = request.input.command;
 			if (typeof command !== "string" || !command.trim() || isAllowlistedBash(command)) return [];
 		}
+		if (request.toolName === "script_runner" && part.id !== event.toolCallId) {
+			if (!scriptStore) return [];
+			try {
+				const { source } = scriptStore.resolve(request.input);
+				request.input = { ...request.input, script: source };
+				delete request.input.edits;
+			} catch {
+				// The sibling's own validated tool call will reject invalid or missing source.
+				return [];
+			}
+		}
 		return [{ toolCallId: part.id, request, requestJson: JSON.stringify(request) }];
 	});
 
@@ -324,23 +375,11 @@ async function reviewAssistantRequests(
 
 async function reviewToolRequest(ctx: ExtensionContext, request: ToolApprovalRequest): Promise<ToolReviewResult> {
 	const requestJson = JSON.stringify(request);
-	const reviewer = REVIEW_MODELS.find((item) => item.provider === ctx.model?.provider);
-	const preferred = reviewer ? [reviewer] : [];
-	if (ctx.model) {
-		preferred.push({
-			provider: ctx.model.provider,
-			model: ctx.model.id,
-			reasoning: "medium",
-		});
-	}
-	const candidates = await resolveCandidates(ctx, preferred, false);
-	const wanted = preferred[0];
-	if (
-		wanted &&
-		!candidates.some((item) => item.model.provider === wanted.provider && item.model.id === wanted.model)
-	) {
-		ctx.ui.notify(`Tool review skipped ${wanted.provider}/${wanted.model}; trying next model.`, "info");
-	}
+	// Requests contain shell commands and scripts, so only the session's own provider reviews them.
+	const provider = ctx.model?.provider;
+	const candidates = (
+		await resolveEffortCandidates(ctx, "quick", { includeParentModel: true, preferredProvider: provider })
+	).filter((candidate) => candidate.model.provider === provider);
 	const { value, candidate } = await generateToolValidated(
 		ctx,
 		candidates,

package/extensions/tool-approval/panel.ts

@@ -15,6 +15,7 @@ import {
 	pushSavedNote,
 	rawHint,
 	renderNoteEditor,
+	ScrollableMarkdown,
 	ToolPanel,
 	type ToolPanelConfig,
 	wrapWithPrefix,
@@ -34,6 +35,7 @@ export class ToolApprovalPanel implements Component, Focusable {
 	private readonly noteEditor: Editor;
 	private readonly panelConfig: ToolPanelConfig;
 	private readonly panel: ToolPanel;
+	private readonly sourceView: ScrollableMarkdown | undefined;
 	private readonly notes: Record<ApprovalChoice, string> = { approve: "", reject: "" };
 	private choice: ApprovalChoice = "approve";
 	private editing = false;
@@ -45,6 +47,7 @@ export class ToolApprovalPanel implements Component, Focusable {
 		keys: KeybindingsManager,
 		title: string,
 		body: string,
+		scriptSource: string | undefined,
 		done: (answer: ApprovalAnswer | undefined) => void,
 	) {
 		this.tui = tui;
@@ -56,11 +59,16 @@ export class ToolApprovalPanel implements Component, Focusable {
 			this.notes[this.choice] = value.trim();
 			this.closeNote();
 		};
+		if (scriptSource !== undefined) {
+			const fenceLength = (scriptSource.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length + 1), 3);
+			const fence = "`".repeat(fenceLength);
+			this.sourceView = new ScrollableMarkdown(tui, `${fence}\n${scriptSource}\n${fence}`, 14);
+		}
 		this.panelConfig = {
 			title,
 			secondary: "Approve runs this request as shown. To change it, reject with a note.",
 			header: [body],
-			body: { render: (width) => this.renderChoices(width), invalidate: () => {} },
+			body: { render: (width) => this.renderChoices(width), invalidate: () => this.sourceView?.invalidate() },
 			footer: { kind: "hints", hints: this.hints() },
 		};
 		this.panel = new ToolPanel(theme, this.panelConfig);
@@ -90,7 +98,9 @@ export class ToolApprovalPanel implements Component, Focusable {
 			this.done(undefined);
 			return;
 		}
-		if (this.keys.matches(data, "tui.select.up") || this.keys.matches(data, "tui.select.down")) {
+		if (this.sourceView && (data === "j" || data === "k")) {
+			this.sourceView.scroll(data === "j" ? 1 : -1);
+		} else if (this.keys.matches(data, "tui.select.up") || this.keys.matches(data, "tui.select.down")) {
 			this.choice = this.choice === "approve" ? "reject" : "approve";
 		} else if (data === "n") {
 			this.editing = true;
@@ -113,6 +123,9 @@ export class ToolApprovalPanel implements Component, Focusable {
 
 	private renderChoices(width: number): string[] {
 		const lines: string[] = [];
+		if (this.sourceView) {
+			lines.push(this.theme.fg("muted", "Complete script:"), ...this.sourceView.render(width), "");
+		}
 		for (const choice of ["approve", "reject"] as const) {
 			const selected = choice === this.choice;
 			const prefix = selected ? this.theme.fg("accent", "→ ") : "  ";
@@ -140,6 +153,7 @@ export class ToolApprovalPanel implements Component, Focusable {
 			? [bindingHint("tui.input.submit", "save"), bindingHint("tui.select.cancel", "cancel note")]
 			: [
 					bindingsHint(["tui.select.up", "tui.select.down"], "move"),
+					...(this.sourceView ? [rawHint("j/k", "scroll script")] : []),
 					bindingHint("tui.select.confirm", "choose"),
 					rawHint("n", "note"),
 					bindingHint("tui.select.cancel", "block"),

package/extensions/tool-loader/README.md

@@ -1,15 +1,15 @@
 # Tool Loader
 
-Tau progressively exposes registered specialist tool groups. Most coding turns do not need web, image, macOS application, or application-specific schemas, so Pi can load those tools later without discarding supported provider cache prefixes.
+Tau registers specialist tool groups as deferred tools so their schemas stay out of every request. Most coding turns do not need web, image, macOS application, or application-specific schemas. The agent finds and loads them with Pi's built-in `tool_search` tool, which Tau keeps active whenever deferred tools exist.
 
-The agent normally calls `load_tools` itself. Tau's built-in groups are:
+Tau's built-in groups are:
 
 - `web` for public web and implementation research
 - `image` for raster image generation and editing
 - `appshot` for macOS window discovery, capture, and activation
 
-Project and global package extensions can add groups with `registerDeferredToolGroup()` from `@shanepadgett/tau-agent`. The group description is included in the loader catalog so the agent can select it when a task needs that capability.
+Project and global package extensions can add groups with `registerDeferredToolGroup()` from `@shanepadgett/tau-agent`. The group id and description become the tool namespace shown to the agent.
 
-Supported models load new groups without replacing the cached prompt prefix. If the selected model cannot do that, the group is queued for activation after successful compaction. The loader reports this and does not compact automatically.
+Loaded tools are recorded in the session and stay available on that branch. All models can discover and load deferred tools. Supported models preserve the cached prompt prefix; other models, including Grok and opencode-go, can incur a cache miss when tools are activated. Tau does not compact automatically.
 
-After changing this extension during development, run `/reload` before testing.
+Pi's built-in `tool_search` extension must be enabled. After changing this extension during development, run `/reload` before testing.