@shanepadgett/tau-agent 0.33.1 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.33.1",
+	"version": "0.35.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -35,10 +35,10 @@
 	],
 	"dependencies": {
 		"@ast-grep/wasm": "0.45.0",
-		"@shanepadgett/tau-tui": "0.33.1",
+		"@shanepadgett/tau-tui": "0.35.0",
 		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
-		"smol-toml": "1.7.0",
+		"smol-toml": "1.7.1",
 		"web-tree-sitter": "0.26.11"
 	},
 	"peerDependencies": {

package/schemas/tau.schema.json

@@ -12,6 +12,42 @@
 		"extensions": {
 			"type": "object",
 			"properties": {
+				"bashApproval": {
+					"type": "object",
+					"properties": {
+						"enabled": {
+							"type": "boolean",
+							"default": true,
+							"description": "Enable bash command review and approval."
+						},
+						"autoApprove": {
+							"type": "boolean",
+							"default": true,
+							"description": "Run reviewer-approved commands without human confirmation."
+						}
+					},
+					"additionalProperties": false
+				},
+				"checkpoint": {
+					"type": "object",
+					"required": [
+						"checkpointTokenLimit"
+					],
+					"properties": {
+						"showToolRows": {
+							"type": "boolean",
+							"default": false,
+							"description": "Show checkpoint and injected-file rows in the TUI for debugging."
+						},
+						"checkpointTokenLimit": {
+							"type": "integer",
+							"minimum": 1,
+							"default": 150000,
+							"description": "Context-token ceiling before a checkpoint is required."
+						}
+					},
+					"additionalProperties": false
+				},
 				"context": {
 					"type": "object",
 					"properties": {
@@ -240,10 +276,10 @@
 							"default": true,
 							"description": "Add the lazy-senior-dev build ethos to Tau's system prompt."
 						},
-						"caveman": {
+						"simplified": {
 							"type": "boolean",
 							"default": true,
-							"description": "Add the terse communication style to Tau's system prompt."
+							"description": "Add Simplified Technical English and small-chunk explanations to Tau's system prompt."
 						}
 					},
 					"additionalProperties": false
@@ -262,39 +298,6 @@
 						}
 					},
 					"additionalProperties": false
-				},
-				"workingMemory": {
-					"type": "object",
-					"properties": {
-						"enabled": {
-							"type": "boolean",
-							"default": true,
-							"description": "Enable working-memory checkpoints."
-						},
-						"nudgeEveryTokens": {
-							"type": "integer",
-							"default": 40000,
-							"minimum": 1,
-							"description": "Active-context token interval between advisory working-memory reminders."
-						},
-						"nudgeInstructions": {
-							"type": "array",
-							"items": {
-								"type": "string",
-								"minLength": 1,
-								"maxLength": 2000
-							},
-							"default": [
-								"Reassess working memory. Continue coherent exploration when its evidence remains useful; otherwise prune known dead ends, obsolete outputs, and other context with no expected value.",
-								"Context is materially larger. Prune stale or bulky irrelevant evidence when safe, but keep active working evidence that would otherwise need to be reread.",
-								"Strongly reassess before more broad work. Remove accumulated waste and carry useful information at cheapest sufficient fidelity without scrubbing the active working set."
-							],
-							"minItems": 1,
-							"maxItems": 5,
-							"description": "Ordered advisory working-memory instructions. Later reminders repeat final instruction."
-						}
-					},
-					"additionalProperties": false
 				}
 			},
 			"additionalProperties": true,

package/shared/bounded-text-result.ts

@@ -63,6 +63,7 @@ export class BoundedTextResultBuilder {
 		this.strategy = strategy;
 	}
 
+	// fallow-ignore-next-line unused-class-member -- head/tail strategy API; callers use completeBlocks today
 	async append(text: string): Promise<void> {
 		if (this.strategy === "completeBlocks") throw new Error("Complete-block results require appendBlock");
 		this.requireOpen();

package/shared/checkpoint-visibility.ts

@@ -0,0 +1,9 @@
+let showCheckpointRows = false;
+
+export function setCheckpointRowsVisible(visible: boolean): void {
+	showCheckpointRows = visible;
+}
+
+export function areCheckpointRowsVisible(): boolean {
+	return showCheckpointRows;
+}

package/shared/events.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ModelEffort } from "./model-effort.ts";
-import type { OutlineInjectionRequest, OutlineInjectionResponse } from "./outline-injection.js";
 import type { ToolRowVisualState } from "./tool-row-state.js";
+import type { FileInjectionRequest, PreparedFileInjection } from "../src/file-injection/index.ts";
 
 export type TauAgentEvents = {
 	"tau:agent.blocked": {
@@ -31,16 +31,14 @@ export type TauAgentEvents = {
 			snapshotRanges?: Array<{ startLine: number; endLine: number }>;
 		}>;
 	};
-	"tau:autoread.requested": {
-		source: string;
-		title?: string;
-		cwd: string;
-		batchId: string;
-		files: Array<{ path: string }>;
+	/** @internal Runtime-scoped discovery for deferred tool groups. */
+	"tau:deferred-tool-group.request": {
+		accept(group: { id: string; description: string; toolNames: readonly string[] }): void;
 	};
-	"tau:outline-injection.requested": {
-		request: OutlineInjectionRequest;
-		accept(response: Promise<OutlineInjectionResponse>): void;
+	/** @internal Runtime-scoped request for Explore-owned file preparation. */
+	"tau:file-injection.prepare": {
+		request: FileInjectionRequest;
+		accept(preparation: Promise<PreparedFileInjection[]>): void;
 	};
 	"tau:footer-item": {
 		id: string;
@@ -105,6 +103,25 @@ export function onTauEvent<Name extends keyof TauAgentEvents>(
 	owner: string,
 	name: Name,
 	handler: TauEventHandler<Name>,
+): () => void {
+	return subscribeToTauEvent(pi, owner, name, handler, false);
+}
+
+export function onTauEventImmediately<Name extends keyof TauAgentEvents>(
+	pi: TauEventAPI,
+	owner: string,
+	name: Name,
+	handler: TauEventHandler<Name>,
+): () => void {
+	return subscribeToTauEvent(pi, owner, name, handler, true);
+}
+
+function subscribeToTauEvent<Name extends keyof TauAgentEvents>(
+	pi: TauEventAPI,
+	owner: string,
+	name: Name,
+	handler: TauEventHandler<Name>,
+	attachImmediately: boolean,
 ): () => void {
 	if (owner.length === 0) throw new Error("Tau event owner is required.");
 
@@ -135,6 +152,7 @@ export function onTauEvent<Name extends keyof TauAgentEvents>(
 	}
 
 	subscriptions.set(name, subscription);
+	if (attachImmediately) attach();
 	pi.on("session_start", attach);
 	pi.on("session_shutdown", detach);
 	return subscription.stop;

package/shared/isolated-session.ts

@@ -32,6 +32,61 @@ export interface IsolatedSessionResource {
 	dispose(): Promise<void>;
 }
 
+type ModelAuth = Awaited<ReturnType<ExtensionContext["modelRegistry"]["getApiKeyAndHeaders"]>>;
+
+async function tryPreferredModel(
+	ctx: ExtensionContext,
+	preferredModel: string,
+	onWarning?: (warning: string) => void,
+): Promise<{ model: SelectedModel; auth: ModelAuth } | undefined> {
+	const separator = preferredModel.indexOf("/");
+	const configured = ctx.modelRegistry.find(preferredModel.slice(0, separator), preferredModel.slice(separator + 1));
+	if (!configured) {
+		onWarning?.(`model ${preferredModel} is unavailable; using parent model`);
+		return undefined;
+	}
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configured);
+	if (!auth.ok) {
+		onWarning?.(`model ${preferredModel} is unavailable: ${auth.error}; using parent model`);
+		return undefined;
+	}
+	return { model: configured, auth };
+}
+
+function thinkingSupported(
+	model: SelectedModel | undefined,
+	preferred: IsolatedSessionThinkingLevel,
+): preferred is IsolatedSessionThinkingLevel {
+	const mapped = model?.thinkingLevelMap?.[preferred];
+	if (!model?.reasoning || mapped === null) return false;
+	if ((preferred === "xhigh" || preferred === "max") && mapped === undefined) return false;
+	return true;
+}
+
+function resolveThinkingLevel(
+	model: SelectedModel | undefined,
+	parentThinkingLevel: IsolatedSessionThinkingLevel,
+	preferredThinkingLevel: IsolatedSessionThinkingLevel | undefined,
+	allowPreferred: boolean,
+	onWarning?: (warning: string) => void,
+): IsolatedSessionThinkingLevel {
+	if (!preferredThinkingLevel || !allowPreferred) return parentThinkingLevel;
+	if (thinkingSupported(model, preferredThinkingLevel)) return preferredThinkingLevel;
+	onWarning?.(`thinking ${preferredThinkingLevel} is unavailable for the selected model; using parent thinking`);
+	return parentThinkingLevel;
+}
+
+function runtimeApiKeyFor(
+	ctx: ExtensionContext,
+	model: SelectedModel,
+	provider: SelectedProvider,
+	auth: ModelAuth,
+): string | undefined {
+	if (!auth.ok) return undefined;
+	if (!(auth.apiKey && provider.auth.apiKey && !ctx.modelRegistry.isUsingOAuth(model))) return undefined;
+	return auth.apiKey;
+}
+
 export async function resolveIsolatedSessionModel(options: {
 	label: string;
 	preferredModel: string | undefined;
@@ -44,37 +99,25 @@ export async function resolveIsolatedSessionModel(options: {
 }): Promise<Pick<IsolatedSessionInputs, "model" | "provider" | "runtimeApiKey" | "thinkingLevel">> {
 	const { ctx, signal, onWarning } = options;
 	let model = ctx.model;
-	let thinkingLevel = options.parentThinkingLevel;
+	let selectedAuth: ModelAuth | undefined;
 	let preferredModelSelected = false;
-	let selectedAuth: Awaited<ReturnType<ExtensionContext["modelRegistry"]["getApiKeyAndHeaders"]>> | undefined;
+
 	if (options.preferredModel) {
-		const separator = options.preferredModel.indexOf("/");
-		const configured = ctx.modelRegistry.find(
-			options.preferredModel.slice(0, separator),
-			options.preferredModel.slice(separator + 1),
-		);
-		if (!configured) onWarning?.(`model ${options.preferredModel} is unavailable; using parent model`);
-		else {
-			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configured);
-			if (!auth.ok) onWarning?.(`model ${options.preferredModel} is unavailable: ${auth.error}; using parent model`);
-			else {
-				model = configured;
-				selectedAuth = auth;
-				preferredModelSelected = true;
-			}
+		const preferred = await tryPreferredModel(ctx, options.preferredModel, onWarning);
+		if (preferred) {
+			model = preferred.model;
+			selectedAuth = preferred.auth;
+			preferredModelSelected = true;
 		}
 	}
-	if (options.preferredThinkingLevel && (preferredModelSelected || options.usePreferredThinkingAfterModelFallback)) {
-		const preferred = options.preferredThinkingLevel;
-		const mapped = model?.thinkingLevelMap?.[preferred];
-		const unsupported =
-			!model?.reasoning ||
-			mapped === null ||
-			((preferred === "xhigh" || preferred === "max") && mapped === undefined);
-		if (unsupported)
-			onWarning?.(`thinking ${preferred} is unavailable for the selected model; using parent thinking`);
-		else thinkingLevel = preferred;
-	}
+
+	const thinkingLevel = resolveThinkingLevel(
+		model,
+		options.parentThinkingLevel,
+		options.preferredThinkingLevel,
+		preferredModelSelected || options.usePreferredThinkingAfterModelFallback,
+		onWarning,
+	);
 	if (!model) throw new Error(`${options.label} startup failed: parent has no model`);
 	const auth = selectedAuth ?? (await ctx.modelRegistry.getApiKeyAndHeaders(model));
 	if (!auth.ok) throw new Error(`${options.label} startup failed: ${auth.error}`);
@@ -84,8 +127,7 @@ export async function resolveIsolatedSessionModel(options: {
 	return {
 		model,
 		provider,
-		runtimeApiKey:
-			auth.apiKey && provider.auth.apiKey && !ctx.modelRegistry.isUsingOAuth(model) ? auth.apiKey : undefined,
+		runtimeApiKey: runtimeApiKeyFor(ctx, model, provider, auth),
 		thinkingLevel,
 	};
 }
@@ -100,7 +142,7 @@ export async function createIsolatedSessionResource(
 		const modelRuntime = await ModelRuntime.create();
 		modelRuntime.registerNativeProvider(inputs.provider);
 		if (inputs.runtimeApiKey !== undefined)
-			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey, { allowNetwork: false });
+			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey, { signal });
 		if (signal.aborted) throw new Error(`${inputs.label} startup aborted`);
 		const resourceLoader = new DefaultResourceLoader({
 			cwd: inputs.cwd,

package/shared/model-effort.ts

@@ -3,7 +3,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resolveCandidates } from "./model-fallback/index.ts";
 import type { ModelCandidate } from "./model-fallback/types.ts";
 
-export type ModelEffort = "low" | "medium" | "high";
+export type ModelEffort = "quick" | "standard" | "deep";
 
 interface ModelPreference {
 	model: string;
@@ -24,43 +24,38 @@ export interface EffortProviderCandidates {
 	}>;
 }
 
+export interface EffortCandidateOptions {
+	includeParentModel: boolean;
+	preferredProvider?: string;
+}
+
 const MODEL_PREFERENCES: Record<ModelEffort, readonly ProviderPreference[]> = {
-	low: [
+	quick: [
 		{
 			provider: "openai-codex",
-			models: [
-				{ model: "gpt-5.6-luna", reasoning: "high" },
-				{ model: "gpt-5.5", reasoning: "low" },
-			],
+			models: [{ model: "gpt-5.6-luna", reasoning: "medium" }],
 		},
 		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "medium" }] },
 		{ provider: "anthropic", models: [{ model: "claude-haiku-4-5", reasoning: "high" }] },
 	],
-	medium: [
+	standard: [
 		{
 			provider: "openai-codex",
-			models: [
-				{ model: "gpt-5.6-terra", reasoning: "high" },
-				{ model: "gpt-5.5", reasoning: "medium" },
-			],
+			models: [{ model: "gpt-5.6-luna", reasoning: "max" }],
 		},
 		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "high" }] },
 		{ provider: "anthropic", models: [{ model: "claude-sonnet-5", reasoning: "high" }] },
 	],
-	high: [
+	deep: [
 		{
 			provider: "openai-codex",
-			models: [
-				{ model: "gpt-5.6-sol", reasoning: "high" },
-				{ model: "gpt-5.5", reasoning: "high" },
-			],
+			models: [{ model: "gpt-5.6-sol", reasoning: "high" }],
 		},
-		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "high" }] },
 		{
 			provider: "anthropic",
 			models: [
 				{ model: "claude-opus-5", reasoning: "high" },
-				{ model: "claude-opus-4-8", reasoning: "high" },
+				{ model: "claude-fable-5", reasoning: "low" },
 			],
 		},
 	],
@@ -72,7 +67,7 @@ export function effortForSelection(
 	reasoning: string | undefined,
 ): ModelEffort | undefined {
 	if (!provider || !model || !reasoning) return undefined;
-	for (const effort of ["high", "medium", "low"] as const) {
+	for (const effort of ["deep", "standard", "quick"] as const) {
 		const preference = MODEL_PREFERENCES[effort].find((item) => item.provider === provider);
 		if (preference?.models.some((item) => item.model === model && item.reasoning === reasoning)) return effort;
 	}
@@ -104,13 +99,19 @@ export function resolveEffortProviders(
 export function resolveEffortCandidates(
 	ctx: Pick<ExtensionContext, "modelRegistry" | "model" | "cwd" | "isProjectTrusted">,
 	effort: ModelEffort,
-	includeParentModel: boolean,
+	options: EffortCandidateOptions,
 ): Promise<ModelCandidate[]> {
+	const preferences = options.preferredProvider
+		? [
+				...MODEL_PREFERENCES[effort].filter(({ provider }) => provider === options.preferredProvider),
+				...MODEL_PREFERENCES[effort].filter(({ provider }) => provider !== options.preferredProvider),
+			]
+		: MODEL_PREFERENCES[effort];
 	return resolveCandidates(
 		ctx,
-		MODEL_PREFERENCES[effort].flatMap((preference) =>
+		preferences.flatMap((preference) =>
 			preference.models.map((model) => ({ provider: preference.provider, ...model })),
 		),
-		includeParentModel,
+		options.includeParentModel,
 	);
 }

package/shared/model-fallback/index.ts

@@ -98,6 +98,20 @@ export async function generateToolValidated<T>(
 	);
 }
 
+async function noteCandidateFailure(
+	ctx: GenerationContext,
+	options: ModelFallbackOptions | undefined,
+	label: string,
+	message: string,
+	hasMore: boolean,
+): Promise<void> {
+	if (!hasMore) return;
+	await options?.onStatus?.(`Model failed (${label}); trying next model`);
+	if (options?.notifyOnFallback ?? false) {
+		ctx.ui.notify(`Model failed (${label}): ${message}\nTrying next model.`, "info");
+	}
+}
+
 async function withModelFallback<T>(
 	ctx: GenerationContext,
 	candidates: readonly ModelCandidate[],
@@ -106,13 +120,11 @@ async function withModelFallback<T>(
 ): Promise<T> {
 	const failures: string[] = [];
 	const statusKey = options?.statusKey;
-	const notifyOnFallback = options?.notifyOnFallback ?? false;
 
 	for (const [index, candidate] of candidates.entries()) {
 		const label = `${candidate.model.provider}/${candidate.model.id}`;
 		if (statusKey) ctx.ui.setStatus(statusKey, `generating (${label})`);
 		await options?.onStatus?.(`Generating with ${label}`);
-
 		try {
 			return await request(candidate);
 		} catch (error) {
@@ -120,16 +132,42 @@ async function withModelFallback<T>(
 			if (shouldCooldownProvider(error)) await markProviderUnavailable(candidate.model.provider);
 			const message = errorText(error);
 			failures.push(`- ${label}: ${message}`);
-			if (index < candidates.length - 1) await options?.onStatus?.(`Model failed (${label}); trying next model`);
-			if (index < candidates.length - 1 && notifyOnFallback) {
-				ctx.ui.notify(`Model failed (${label}): ${message}\nTrying next model.`, "info");
-			}
+			await noteCandidateFailure(ctx, options, label, message, index < candidates.length - 1);
 		}
 	}
 
 	throw new Error(["Model generation failed for all candidates:", ...failures].join("\n"));
 }
 
+function throwUnlessRetryableStopError(response: AssistantMessage, attempt: number, maxAttempts: number): void {
+	if (response.stopReason !== "error") return;
+	const error = new Error(response.errorMessage || "model returned an error");
+	if (attempt < maxAttempts && !shouldCooldownProvider(error)) return;
+	throw error;
+}
+
+function pushCorrection(
+	messages: Message[],
+	error: Error,
+	output: string,
+	correctionPrompt: (error: Error, output: string) => string,
+): void {
+	messages.push({
+		role: "user",
+		content: [{ type: "text", text: correctionPrompt(error, truncAt(output, 4_000)) }],
+		timestamp: Date.now(),
+	});
+}
+
+function shouldRetryValidation(
+	error: unknown,
+	attempt: number,
+	maxAttempts: number,
+	correctionPrompt: ((error: Error, output: string) => string) | undefined,
+): error is Error {
+	return error instanceof Error && attempt < maxAttempts && correctionPrompt !== undefined;
+}
+
 async function requestValidated<T>(
 	ctx: GenerationContext,
 	candidate: ModelCandidate,
@@ -137,37 +175,36 @@ async function requestValidated<T>(
 	validate: (text: string) => T,
 	correctionPrompt?: (error: Error, text: string) => string,
 ): Promise<T> {
-	const userMessage: Message = { role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() };
-	const messages: Message[] = [userMessage];
+	const messages: Message[] = [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }];
 	const sessionId = randomUUID();
 
 	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
 		const response = await completeCandidate(ctx, candidate, messages, sessionId);
 		const text = responseText(response);
-		if (response.stopReason === "error") {
-			const error = new Error(response.errorMessage || "model returned an error");
-			if (attempt < MAX_ATTEMPTS && !shouldCooldownProvider(error)) continue;
-			throw error;
-		}
-
 		try {
+			throwUnlessRetryableStopError(response, attempt, MAX_ATTEMPTS);
+			if (response.stopReason === "error") continue;
 			return validate(text);
 		} catch (error) {
-			if (!(error instanceof Error) || attempt >= MAX_ATTEMPTS) throw error;
-			if (!correctionPrompt) throw error;
-
+			if (!shouldRetryValidation(error, attempt, MAX_ATTEMPTS, correctionPrompt) || !correctionPrompt) {
+				throw error;
+			}
 			if (text) messages.push({ ...response, content: [{ type: "text", text }] });
-			messages.push({
-				role: "user",
-				content: [{ type: "text", text: correctionPrompt(error, truncAt(text, 4_000)) }],
-				timestamp: Date.now(),
-			});
+			pushCorrection(messages, error, text, correctionPrompt);
 		}
 	}
 
 	throw new Error("Model generation failed.");
 }
 
+function validateSingleToolCall(tool: Tool, toolCalls: readonly { name: string; arguments: unknown }[]): unknown {
+	if (toolCalls.length !== 1) throw new Error(`Model must call ${tool.name} exactly once.`);
+	const toolCall = toolCalls[0];
+	if (!toolCall) throw new Error(`Model must call ${tool.name}.`);
+	if (toolCall.name !== tool.name) throw new Error(`Model called ${toolCall.name}; expected ${tool.name}.`);
+	return toolCall.arguments;
+}
+
 async function requestToolValidated<T>(
 	ctx: GenerationContext,
 	candidate: ModelCandidate,
@@ -185,27 +222,15 @@ async function requestToolValidated<T>(
 		const text = responseText(response);
 		const toolCalls = response.content.flatMap((part) => (part.type === "toolCall" ? [part] : []));
 		const output = text || formatToolCalls(toolCalls);
-		if (response.stopReason === "error") {
-			const error = new Error(response.errorMessage || "model returned an error");
-			if (attempt < maxAttempts && !shouldCooldownProvider(error)) continue;
-			throw error;
-		}
-
 		try {
-			if (toolCalls.length !== 1) throw new Error(`Model must call ${tool.name} exactly once.`);
-			const [toolCall] = toolCalls;
-			if (!toolCall) throw new Error(`Model must call ${tool.name}.`);
-			if (toolCall.name !== tool.name) throw new Error(`Model called ${toolCall.name}; expected ${tool.name}.`);
-			return validate(toolCall.arguments);
+			throwUnlessRetryableStopError(response, attempt, maxAttempts);
+			if (response.stopReason === "error") continue;
+			return validate(validateSingleToolCall(tool, toolCalls));
 		} catch (error) {
-			if (!(error instanceof Error) || attempt >= maxAttempts) throw error;
-			if (!correctionPrompt) throw error;
-
-			messages.push({
-				role: "user",
-				content: [{ type: "text", text: correctionPrompt(error, truncAt(output, 4_000)) }],
-				timestamp: Date.now(),
-			});
+			if (!shouldRetryValidation(error, attempt, maxAttempts, correctionPrompt) || !correctionPrompt) {
+				throw error;
+			}
+			pushCorrection(messages, error, output, correctionPrompt);
 		}
 	}