@shanepadgett/tau-agent 0.7.2 → 0.8.0

package/extensions/appshot/index.ts

@@ -116,11 +116,7 @@ function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
 			name: "list_windows",
 			label: "List Windows",
 			description:
-				"List visible normal macOS windows as compact TOON with window IDs, titles, application identity, process IDs, and bounds. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
-			promptSnippet: "Discover visible macOS application windows and their IDs",
-			promptGuidelines: [
-				"Use list_windows to discover graphical applications and select an exact window before calling screenshot_window.",
-			],
+				"List visible normal macOS windows as compact TOON with window IDs, titles, application identity, process IDs, and bounds. Use list_windows to discover exact window IDs and application PIDs before screenshot_window or activate_app. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
 			parameters: listWindowsSchema,
 			async execute(_toolCallId, _params, signal) {
 				if (process.platform !== "darwin") throw new Error("list_windows is only available on macOS");
@@ -158,9 +154,7 @@ function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
 			name: "screenshot_window",
 			label: "Screenshot Window",
 			description:
-				"Capture one visible macOS window by its list_windows ID, resize it to fit within 1568×1568 pixels, save it as PNG, and inspect the image.",
-			promptSnippet: "Capture and inspect an exact visible macOS window by window ID",
-			promptGuidelines: ["Call list_windows before screenshot_window; pass its exact window_id and a PNG path."],
+				"Capture one visible macOS window by an exact ID returned by list_windows, resize it to fit within 1568×1568 pixels, save it to the required PNG path, and inspect the image. Call list_windows first.",
 			parameters: screenshotWindowSchema,
 			async execute(_toolCallId, params: ScreenshotWindowParams, signal, onUpdate, ctx) {
 				if (process.platform !== "darwin") throw new Error("screenshot_window is only available on macOS");
@@ -219,11 +213,7 @@ function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
 			name: "activate_app",
 			label: "Activate App",
 			description:
-				"Bring a running macOS application and its windows to the foreground by process ID. Use a PID returned by list_windows.",
-			promptSnippet: "Bring a listed macOS application to the foreground by process ID",
-			promptGuidelines: [
-				"Use activate_app only when foregrounding a listed application is needed for visual validation because it changes user focus.",
-			],
+				"Bring a running macOS application and its windows to the foreground by a process ID returned by list_windows. Use only when foregrounding is required for visual validation because activate_app changes user focus.",
 			parameters: activateAppSchema,
 			async execute(_toolCallId, params, signal) {
 				if (process.platform !== "darwin") throw new Error("activate_app is only available on macOS");

package/extensions/context/definitions.ts

@@ -15,6 +15,45 @@ export interface ContextEntry {
 	path: string;
 }
 
+const CONTEXT_IGNORED_FILENAMES = new Set([
+	"bun.lock",
+	"bun.lockb",
+	"Cargo.lock",
+	"composer.lock",
+	"flake.lock",
+	"Gemfile.lock",
+	"go.sum",
+	"mix.lock",
+	"npm-shrinkwrap.json",
+	"package-lock.json",
+	"Package.resolved",
+	"Pipfile.lock",
+	"pnpm-lock.yaml",
+	"Podfile.lock",
+	"poetry.lock",
+	"pubspec.lock",
+	"uv.lock",
+	"yarn.lock",
+]);
+
+export function isContextEligiblePath(path: string): boolean {
+	return (
+		path !== "LICENSE" &&
+		!CONTEXT_IGNORED_FILENAMES.has(basename(path)) &&
+		path !== ".pi/tau/ideas.jsonl" &&
+		path !== ".working" &&
+		!path.startsWith(".working/") &&
+		path !== ".pi/contexts" &&
+		!path.startsWith(".pi/contexts/")
+	);
+}
+
+export function isSensitiveContextPath(path: string): boolean {
+	const name = basename(path);
+	if (name === ".env.example" || name === ".env.sample") return false;
+	return name === ".env" || name.startsWith(".env.") || /\.(?:pem|key|crt|p12|pfx)$/i.test(name);
+}
+
 export async function pathExists(path: string): Promise<boolean> {
 	try {
 		await access(path);

package/extensions/context/index.ts

@@ -5,6 +5,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { emitTauEvent } from "../../shared/events.ts";
 import { createInjectedContext } from "../../shared/injected-context.ts";
+import { registerTauSystemPromptContribution } from "../../shared/system-prompt-contributions.ts";
 import { ContextPanel } from "./panel.ts";
 import { findProjectRoot, loadContextEntries, type ContextEntry } from "./definitions.ts";
 import { runContextSync, type ContextSyncDetails } from "./sync.ts";
@@ -22,6 +23,15 @@ function compactResult(details: ContextSyncDetails) {
 
 export default function contextExtension(pi: ExtensionAPI): void {
 	let active: ContextEntry[] = [];
+	const activeToolExecutions = new Map<string, { toolName: string; done: Promise<void>; complete: () => void }>();
+	const unregisterPrompt = registerTauSystemPromptContribution({
+		id: "context.selected-authority",
+		order: 100,
+		render: () =>
+			active.length
+				? "Treat the autoread files as the authoritative project context and current snapshots. Do not reread them or search for coverage around them. Start work from them immediately. Explore outside them only when the user's request or concrete evidence in those files requires missing code or information."
+				: undefined,
+	});
 
 	pi.registerCommand("context", {
 		description: "Select repository context entries and inject their files",
@@ -94,7 +104,12 @@ export default function contextExtension(pi: ExtensionAPI): void {
 			label: "context_sync",
 			description: "Synchronize repository context from current Git changes.",
 			parameters: contextSyncParams,
-			async execute(_id, _params, _signal, onUpdate, ctx) {
+			async execute(id, _params, _signal, onUpdate, ctx) {
+				await Promise.all(
+					[...activeToolExecutions]
+						.filter(([toolCallId, execution]) => toolCallId !== id && execution.toolName !== "context_sync")
+						.map(([, execution]) => execution.done),
+				);
 				return compactResult(
 					await runContextSync(pi, ctx, (status) =>
 						onUpdate?.({ content: [{ type: "text", text: status }], details: undefined }),
@@ -131,6 +146,20 @@ export default function contextExtension(pi: ExtensionAPI): void {
 		}),
 	);
 
+	pi.on("tool_execution_start", (event) => {
+		let complete = () => {};
+		const done = new Promise<void>((resolve) => {
+			complete = resolve;
+		});
+		activeToolExecutions.set(event.toolCallId, { toolName: event.toolName, done, complete });
+	});
+
+	pi.on("tool_execution_end", (event) => {
+		const execution = activeToolExecutions.get(event.toolCallId);
+		activeToolExecutions.delete(event.toolCallId);
+		execution?.complete();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		const root = await findProjectRoot(ctx.cwd);
 		const entries = await loadContextEntries(root);
@@ -146,11 +175,9 @@ export default function contextExtension(pi: ExtensionAPI): void {
 				: [];
 		active = entries.filter((entry) => ids.includes(entry.id));
 	});
-	pi.on("before_agent_start", (event) =>
-		active.length
-			? {
-					systemPrompt: `${event.systemPrompt}\n\nTreat the autoread files as the authoritative project context and current snapshots. Do not reread them or search for coverage around them. Start work from them immediately. Explore outside them only when the user's request or concrete evidence in those files requires missing code or information.`,
-				}
-			: undefined,
-	);
+	pi.on("session_shutdown", () => {
+		unregisterPrompt();
+		for (const execution of activeToolExecutions.values()) execution.complete();
+		activeToolExecutions.clear();
+	});
 }

package/extensions/context/sync.ts

@@ -9,6 +9,8 @@ import { generateToolValidated, resolveCandidates } from "../../shared/model-fal
 import { truncAt } from "../../shared/text.ts";
 import { XAI_CHAT_MODEL, XAI_PROVIDER } from "../xai/constants.ts";
 import {
+	isContextEligiblePath,
+	isSensitiveContextPath,
 	loadContextEntries,
 	normalizeProjectPath,
 	pathExists,
@@ -130,6 +132,14 @@ export async function runContextSync(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	onStatus?: (status: string) => void | Promise<void>,
+): Promise<ContextSyncDetails> {
+	return withSyncLock(() => runContextSyncLocked(pi, ctx, onStatus));
+}
+
+async function runContextSyncLocked(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	onStatus?: (status: string) => void | Promise<void>,
 ): Promise<ContextSyncDetails> {
 	if (!ctx.isProjectTrusted()) throw new Error("Context sync requires a trusted project");
 	await onStatus?.("Inspecting repository context");
@@ -138,6 +148,7 @@ export async function runContextSync(
 	if (!status) throw new Error("No Git repository found");
 	if (status.fileCount === 0) return noChange("Existing context mappings already fit the changed scope.");
 	const evidence = await collectSyncEvidence(git, status.root);
+	if (evidence.files.length === 0) return noChange("Changed files are outside context catalog scope.");
 	const prompt = buildContextSyncPrompt(evidence);
 	const plan = await generateToolValidated(
 		ctx,
@@ -150,15 +161,13 @@ export async function runContextSync(
 	);
 	if (plan.outcome === "no-change") return noChange(plan.reason);
 	await onStatus?.("Applying context catalog changes");
-	return withSyncLock(async () => {
-		return applyContextSyncPlan(evidence.root, plan, evidence.entries, async () => {
-			const currentEntries = await loadContextEntries(evidence.root);
-			const currentFiles = await collectDirtyFiles(git, evidence.root, currentEntries);
-			if ((await computeWorktreeSignature(git, evidence.root, currentFiles)) !== evidence.worktreeSignature)
-				throw new Error("Repository changed during context sync. Rerun context sync.");
-			if ((await computeCatalogSignature(evidence.root)) !== evidence.catalogSignature)
-				throw new Error("Context catalog changed during context sync. Rerun context sync.");
-		});
+	return applyContextSyncPlan(evidence.root, plan, evidence.entries, async () => {
+		const currentEntries = await loadContextEntries(evidence.root);
+		const currentFiles = await collectDirtyFiles(git, evidence.root, currentEntries);
+		if ((await computeWorktreeSignature(git, evidence.root, currentFiles)) !== evidence.worktreeSignature)
+			throw new Error("Repository changed during context sync. Rerun context sync.");
+		if ((await computeCatalogSignature(evidence.root)) !== evidence.catalogSignature)
+			throw new Error("Context catalog changed during context sync. Rerun context sync.");
 	});
 }
 
@@ -197,6 +206,7 @@ async function collectSyncEvidence(git: GitRunner, root: string): Promise<SyncEv
 		root,
 		files.filter((file) => dirtyExisting.has(file.path)),
 	);
+	for (const path of dependencies) if (!isContextEligiblePath(path)) dependencies.delete(path);
 	const affectedIds = new Set<string>();
 	for (const entry of entries) {
 		if (
@@ -211,7 +221,9 @@ async function collectSyncEvidence(git: GitRunner, root: string): Promise<SyncEv
 	const missingPaths = new Set<string>();
 	for (const entry of entries)
 		for (const path of entry.files) if (!(await isFile(join(root, path)))) missingPaths.add(path);
-	const siblingFiles = siblingEntries.flatMap((entry) => entry.files).filter((path) => !missingPaths.has(path));
+	const siblingFiles = siblingEntries
+		.flatMap((entry) => entry.files)
+		.filter((path) => !missingPaths.has(path) && isContextEligiblePath(path));
 	const eligibleFiles = new Set([...dirtyExisting, ...dependencies, ...siblingFiles]);
 	const structuralPreviews = new Map<string, string>();
 	for (const path of [...new Set(siblingFiles)].sort()) {
@@ -282,7 +294,21 @@ async function collectDirtyFiles(
 			index++;
 		}
 	}
-	const sorted = parsed.sort((a, b) => a.path.localeCompare(b.path));
+	const sensitive = parsed.filter(
+		(file) =>
+			file.kind !== "deleted" &&
+			(isSensitiveContextPath(file.path) || (file.oldPath !== undefined && isSensitiveContextPath(file.oldPath))),
+	);
+	if (sensitive.length > 0)
+		throw new Error(
+			`Sensitive files cannot be inspected by context sync:\n${sensitive.map((file) => `- ${file.path}`).join("\n")}`,
+		);
+	const sorted = parsed
+		.filter(
+			(file) =>
+				isContextEligiblePath(file.path) || (file.oldPath !== undefined && isContextEligiblePath(file.oldPath)),
+		)
+		.sort((a, b) => a.path.localeCompare(b.path));
 	const result: SyncDirtyFile[] = [];
 	for (let offset = 0; offset < sorted.length; offset += EVIDENCE_CONCURRENCY) {
 		result.push(
@@ -627,16 +653,16 @@ export async function applyContextSyncPlan(
 	for (const path of paths) originals.set(path, (await pathExists(path)) ? await readFile(path) : undefined);
 	const temporaryFiles = new Map<string, string>();
 	try {
-		for (const path of paths) {
-			const output = outputs.get(path);
-			if (output === undefined) continue;
-			await mkdir(dirname(path), { recursive: true });
-			const temporary = `${path}.${process.pid}.${Date.now()}.${temporaryFiles.size}.tmp`;
-			await writeFile(temporary, output, "utf8");
-			temporaryFiles.set(path, temporary);
-		}
 		await acquireMutationQueues(lockPaths, async () => {
 			await verifyFreshness?.();
+			for (const path of paths) {
+				const output = outputs.get(path);
+				if (output === undefined) continue;
+				await mkdir(dirname(path), { recursive: true });
+				const temporary = `${path}.${process.pid}.${Date.now()}.${temporaryFiles.size}.tmp`;
+				await writeFile(temporary, output, "utf8");
+				temporaryFiles.set(path, temporary);
+			}
 			const changed: string[] = [];
 			try {
 				for (const path of paths) {

package/extensions/image-gen/index.ts

@@ -41,14 +41,7 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
 			name: "image_gen",
 			label: "Image Generation",
 			description:
-				"Generate a new raster image from a prompt, or edit one to three local raster images. Uses the xAI Grok subscription OAuth login, saves the result under Tau's external image store unless an explicit path is provided, and returns the image for inspection.",
-			promptSnippet: "Generate or edit raster images with Grok Imagine",
-			promptGuidelines: [
-				"Use image_gen when the user asks for a generated raster image or an AI edit of local raster images.",
-				"Omit referenced_image_paths when image_gen should create a new image.",
-				"Pass one to three local paths in referenced_image_paths when image_gen should edit or compose existing images.",
-				"Omit path for temporary external storage. Pass path only when the user wants the generated image saved in their repository or another explicit location.",
-			],
+				"Generate a requested raster image or AI-edit existing images with the xAI Grok subscription OAuth login. Omit referenced_image_paths to generate; pass one to three local paths to edit or compose. Omit path to use Tau's external image store; pass path only when the user explicitly requests a repository file or other destination. Returns the image for inspection.",
 			parameters: imageGenSchema,
 			async execute(_toolCallId, params: ImageGenParams, signal, onUpdate, ctx) {
 				signal?.throwIfAborted();

package/extensions/silent-command-runner/index.ts

@@ -4,6 +4,7 @@ import { type ExecResult, type ExtensionAPI, keyText, type Theme } from "@earend
 import { Box, Text } from "@earendil-works/pi-tui";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { resolveProjectRoot } from "../../shared/settings/paths.ts";
+import { registerTauSystemPromptContribution } from "../../shared/system-prompt-contributions.ts";
 import silentCommandRunnerSettings from "./settings.ts";
 
 const MESSAGE_TYPE = "tau:silent-command-runner";
@@ -79,18 +80,17 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	let turnPaths = new Set<string>();
 	let run: Promise<void> | undefined;
 	let abortController: AbortController | undefined;
+	const unregisterPrompt = registerTauSystemPromptContribution({
+		id: "silent-command-runner.instructions",
+		order: 200,
+		render: () =>
+			settings.enabled && settings.commands.length > 0 ? formatSilentCheckPrompt(settings.commands) : undefined,
+	});
 
 	pi.registerMessageRenderer<FailureDetails>(MESSAGE_TYPE, (message, { expanded }, theme) =>
 		renderFailure(asFailureDetails(message.details), expanded, theme),
 	);
 
-	pi.on("before_agent_start", (event) => {
-		if (!settings.enabled || settings.commands.length === 0) return;
-		const prompt = formatSilentCheckPrompt(settings.commands);
-		event.systemPromptOptions.appendSystemPrompt = appendPrompt(event.systemPromptOptions.appendSystemPrompt, prompt);
-		return { systemPrompt: `${event.systemPrompt}\n\n${prompt}` };
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		settings = normalizeSettings(await loadTauExtensionSettings(ctx, silentCommandRunnerSettings));
 		turnStart = Date.now();
@@ -122,6 +122,7 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_shutdown", () => {
+		unregisterPrompt();
 		abortController?.abort();
 		abortController = undefined;
 		run = undefined;
@@ -206,10 +207,6 @@ function formatSilentCheckPrompt(commands: readonly CommandConfig[]): string {
 	].join("\n");
 }
 
-function appendPrompt(current: string | undefined, prompt: string): string {
-	return current ? `${current}\n\n${prompt}` : prompt;
-}
-
 function formatSilentCheckCommand(command: CommandConfig): string {
 	return [
 		`- ${command.name}: ${command.command}`,

package/extensions/soul/README.md

@@ -2,7 +2,7 @@
 
 Soul replaces Pi's default assistant prompt with Rok: caveman voice plus old-code senior judgment.
 
-It keeps the core prompt stable for cache reuse and captures runtime and project context once per session.
+It keeps the core prompt stable for cache reuse. Soul supplies the current local date and the initial root directory snapshot as hidden session context; the working directory and project instructions remain in the system prompt.
 
 Disable it in Tau settings:
 

package/extensions/soul/index.ts

@@ -1,8 +1,26 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
-import { buildRokPrompt, freezeRuntimeContext, type RuntimeContext } from "./prompt.ts";
+import { collectTauSystemPromptContributions } from "../../shared/system-prompt-contributions.ts";
+import {
+	buildRokPrompt,
+	fingerprintRuntimeSnapshot,
+	formatLocalDateKey,
+	formatLocalDisplayDate,
+	formatRuntimeContextMessage,
+	freezeRuntimeContext,
+	type RuntimeContext,
+} from "./prompt.ts";
 import soulSettings from "./settings.ts";
 
+const RUNTIME_CONTEXT_TYPE = "tau.runtime-context";
+
+interface RuntimeContextMessageDetails {
+	version: 1;
+	dateKey: string;
+	snapshotHash: string;
+	includesSnapshot: boolean;
+}
+
 export default function soulExtension(pi: ExtensionAPI): void {
 	let enabled = true;
 	let runtimeContext: RuntimeContext | undefined;
@@ -12,9 +30,72 @@ export default function soulExtension(pi: ExtensionAPI): void {
 		runtimeContext = freezeRuntimeContext(ctx.cwd);
 	});
 
-	pi.on("before_agent_start", (event, ctx) => {
-		if (!enabled) return undefined;
+	pi.on("before_agent_start", async (event, ctx) => {
 		runtimeContext ??= freezeRuntimeContext(ctx.cwd);
-		return { systemPrompt: buildRokPrompt(event.systemPromptOptions, runtimeContext) };
+		// Pi reuses base prompt options, so Tau-owned additions compose here without accumulating mutations.
+		const contributions = await collectTauSystemPromptContributions(event, ctx);
+		const basePrompt = enabled ? buildRokPrompt(event.systemPromptOptions, runtimeContext) : event.systemPrompt;
+		const systemPrompt = [basePrompt, ...contributions].filter((block) => block.trim()).join("\n\n");
+
+		const now = new Date();
+		const dateKey = formatLocalDateKey(now);
+		const snapshotHash = fingerprintRuntimeSnapshot(runtimeContext);
+		let hasDate = false;
+		let hasSnapshot = false;
+		for (const entry of ctx.sessionManager.buildContextEntries()) {
+			const details = runtimeContextDetails(entry);
+			if (!details) continue;
+			if (details.dateKey === dateKey) hasDate = true;
+			if (details.includesSnapshot && details.snapshotHash === snapshotHash) hasSnapshot = true;
+		}
+
+		const includeSnapshot = !hasSnapshot;
+		const message =
+			hasDate && hasSnapshot
+				? undefined
+				: {
+						customType: RUNTIME_CONTEXT_TYPE,
+						content: formatRuntimeContextMessage(
+							formatLocalDisplayDate(now),
+							includeSnapshot ? runtimeContext.rootSnapshot : undefined,
+						),
+						display: false,
+						details: {
+							version: 1,
+							dateKey,
+							snapshotHash,
+							includesSnapshot: includeSnapshot,
+						} satisfies RuntimeContextMessageDetails,
+					};
+
+		if (!enabled && contributions.length === 0 && !message) return undefined;
+		return {
+			...(enabled || contributions.length > 0 ? { systemPrompt } : {}),
+			...(message ? { message } : {}),
+		};
 	});
 }
+
+function runtimeContextDetails(value: unknown): RuntimeContextMessageDetails | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const entry = value as Record<string, unknown>;
+	if (entry.type !== "custom_message" || entry.customType !== RUNTIME_CONTEXT_TYPE || entry.display !== false) {
+		return undefined;
+	}
+	if (!entry.details || typeof entry.details !== "object") return undefined;
+	const details = entry.details as Record<string, unknown>;
+	if (
+		details.version !== 1 ||
+		typeof details.dateKey !== "string" ||
+		typeof details.snapshotHash !== "string" ||
+		typeof details.includesSnapshot !== "boolean"
+	) {
+		return undefined;
+	}
+	return {
+		version: 1,
+		dateKey: details.dateKey,
+		snapshotHash: details.snapshotHash,
+		includesSnapshot: details.includesSnapshot,
+	};
+}

package/extensions/soul/prompt.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -19,7 +20,6 @@ interface SnapshotEntry {
 }
 
 export interface RuntimeContext {
-	date: string;
 	cwd: string;
 	rootSnapshot: readonly string[];
 }
@@ -73,21 +73,50 @@ export function buildRokPrompt(options: BuildSystemPromptOptions, runtimeContext
 }
 
 export function freezeRuntimeContext(cwd: string): RuntimeContext {
-	return { date: formatDate(new Date()), cwd: cwd.replace(/\\/g, "/"), rootSnapshot: listRootSnapshot(cwd) };
+	return { cwd: cwd.replace(/\\/g, "/"), rootSnapshot: listRootSnapshot(cwd) };
 }
 
-function formatDate(date: Date): string {
+export function formatLocalDateKey(date: Date): string {
 	const year = date.getFullYear();
 	const month = String(date.getMonth() + 1).padStart(2, "0");
 	const day = String(date.getDate()).padStart(2, "0");
 	return `${year}-${month}-${day}`;
 }
 
+export function formatLocalDisplayDate(date: Date): string {
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December",
+	];
+	return `${date.getDate()} ${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+
+export function fingerprintRuntimeSnapshot(context: RuntimeContext): string {
+	return createHash("sha256")
+		.update(JSON.stringify({ version: 1, cwd: context.cwd, paths: context.rootSnapshot }))
+		.digest("hex");
+}
+
+export function formatRuntimeContextMessage(displayDate: string, rootSnapshot: readonly string[] | undefined): string {
+	const blocks = [`Current local date: ${displayDate}`];
+	if (rootSnapshot?.length) {
+		blocks.push(`Root directory snapshot (depth 2):\n${rootSnapshot.map((path) => `- ${path}`).join("\n")}`);
+	}
+	return blocks.join("\n");
+}
+
 function formatRuntimeContext(context: RuntimeContext): string {
-	const rootSnapshot = context.rootSnapshot.length
-		? `\nRoot directory snapshot (depth 2):\n${context.rootSnapshot.map((path) => `- ${path}`).join("\n")}`
-		: "";
-	return `Current date: ${context.date}\nCurrent working directory: ${context.cwd}${rootSnapshot}`;
+	return `Current working directory: ${context.cwd}`;
 }
 
 function listRootSnapshot(cwd: string): string[] {

package/extensions/subagent/index.ts

@@ -1,6 +1,7 @@
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { registerTauSystemPromptContribution } from "../../shared/system-prompt-contributions.ts";
 import { discoverAgents, type AgentDiscovery } from "./agents.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
 import { extensionPathsForTools, FifoGate, runSubagent, type SubagentDetails } from "./run.ts";
@@ -33,6 +34,19 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		for (const path of fingerprints.keys()) if (!current.has(path)) fingerprints.delete(path);
 	};
+	const unregisterPrompt = registerTauSystemPromptContribution({
+		id: "subagent.catalog",
+		order: 300,
+		render: async (_event, ctx) => {
+			if (!pi.getActiveTools().includes("subagent")) return undefined;
+			const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
+			warn(discovery, ctx);
+			const lines = [...discovery.agents.values()]
+				.sort((a, b) => a.name.localeCompare(b.name))
+				.map((agent) => `- ${agent.name}: ${agent.description}`);
+			return `## Subagents\nUse \`subagent\` when an available agent matches a focused part of the task.\n\nAvailable agents for this turn:\n${lines.join("\n")}\n\nDelegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
+		},
+	});
 	pi.registerTool(
 		defineTool<typeof params, SubagentDetails>({
 			name: "subagent",
@@ -184,21 +198,6 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			},
 		}),
 	);
-	pi.on("before_agent_start", async (event, ctx) => {
-		if (!pi.getActiveTools().includes("subagent")) return;
-		const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
-		warn(discovery, ctx);
-		const lines = [...discovery.agents.values()]
-			.sort((a, b) => a.name.localeCompare(b.name))
-			.map((agent) => `- ${agent.name}: ${agent.description}`);
-		const prompt = `## Subagents\nUse \`subagent\` when an available agent matches a focused part of the task.\n\nAvailable agents for this turn:\n${lines.join("\n")}\n\nDelegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
-		event.systemPromptOptions.appendSystemPrompt = event.systemPromptOptions.appendSystemPrompt
-			? `${event.systemPromptOptions.appendSystemPrompt}\n\n${prompt}`
-			: prompt;
-		return {
-			systemPrompt: `${event.systemPrompt}\n\n${prompt}`,
-		};
-	});
 	pi.on("tool_result", (event) => {
 		if (event.toolName !== "subagent") return;
 		const details = event.details as SubagentDetails | undefined;
@@ -209,6 +208,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		runtimeWarnings.clear();
 	});
 	pi.on("session_shutdown", () => {
+		unregisterPrompt();
 		for (const controller of controllers) controller.abort();
 		controllers.clear();
 	});

package/extensions/tau-help/help.md

@@ -98,13 +98,17 @@ Adds `/tau-help` to show this guide as rendered Markdown in the chat.
 
 Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup and diagnostics.
 
+## tool-loader
+
+Progressively exposes specialist tools through `load_tools`. Tau normally loads the fixed `web`, `image`, and `appshot` groups itself when needed; supported providers can preserve more prompt-cache reuse.
+
 ## turn-budget
 
 Tracks and limits agent turns to keep work bounded.
 
 ## web
 
-Gives the agent compact `web_search`, `web_fetch`, and `code_search` tools for web and implementation research.
+Gives the agent compact `websearch`, `webfetch`, and `codesearch` tools for web and implementation research.
 
 ## Prompts
 

package/extensions/tool-loader/README.md

@@ -0,0 +1,13 @@
+# Tool Loader
+
+Tau progressively exposes specialist tools. Most coding turns do not need web, image, or macOS application schemas, so Pi can load those tools later without discarding supported provider cache prefixes.
+
+The agent normally calls `load_tools` itself. Users can also ask Tau to load one of these groups:
+
+- `web` for public web and implementation research
+- `image` for raster image generation and editing
+- `appshot` for macOS window discovery, capture, and activation
+
+Supported models optimize prompt caching when a group loads. Other models keep the same functional behavior.
+
+After changing this extension during development, run `/reload` before testing.

package/extensions/tool-loader/index.ts

@@ -0,0 +1,134 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+
+const CAPABILITIES = ["web", "image", "appshot"] as const;
+type Capability = (typeof CAPABILITIES)[number];
+
+const CAPABILITY_TOOLS: Record<Capability, readonly string[]> = {
+	web: ["webfetch", "websearch", "codesearch"],
+	image: ["image_gen"],
+	appshot: ["list_windows", "screenshot_window", "activate_app"],
+};
+const SPECIALIST_TOOLS = CAPABILITIES.flatMap((capability) => CAPABILITY_TOOLS[capability]);
+
+const loadToolsSchema = Type.Object(
+	{
+		capability: StringEnum(CAPABILITIES, {
+			description: "Specialist group to load: web, image, or appshot",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+type LoadToolsParams = Static<typeof loadToolsSchema>;
+
+interface LoadToolsDetails {
+	version: 1;
+	capability: Capability;
+	requestedToolNames: string[];
+	addedToolNames: string[];
+}
+
+export default function toolLoaderExtension(pi: ExtensionAPI): void {
+	let managed = false;
+	let allowedSpecialistNames = new Set<string>();
+
+	pi.registerTool(
+		defineTool<typeof loadToolsSchema, LoadToolsDetails>({
+			name: "load_tools",
+			label: "Load Tools",
+			description:
+				"Load one Tau specialist tool group for the current session. Groups: web for public web and implementation research; image for raster generation and editing; appshot for macOS window discovery, capture, and activation.",
+			promptSnippet: "Load a specialist Tau tool group for web research, image generation, or macOS app inspection",
+			promptGuidelines: [
+				"Use load_tools before attempting a specialist capability whose tools are not currently available.",
+			],
+			parameters: loadToolsSchema,
+			async execute(_toolCallId, params: LoadToolsParams) {
+				const before = pi.getActiveTools();
+				const requested = [...CAPABILITY_TOOLS[params.capability]];
+				const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+				const loadable = requested.filter((name) => registered.has(name) && allowedSpecialistNames.has(name));
+				if (loadable.length === 0) {
+					throw new Error(`No ${params.capability} tools are available in this session's tool configuration.`);
+				}
+				const beforeSet = new Set(before);
+				const next = [...before, ...loadable.filter((name) => !beforeSet.has(name))];
+				pi.setActiveTools(next);
+				const after = pi.getActiveTools();
+				const addedToolNames = after.filter((name) => !beforeSet.has(name));
+				const available = requested.filter((name) => after.includes(name));
+				const unavailable = requested.filter((name) => !after.includes(name));
+				const label = `${params.capability[0]?.toUpperCase()}${params.capability.slice(1)}`;
+				const text =
+					addedToolNames.length > 0
+						? `Loaded ${params.capability} tools: ${addedToolNames.join(", ")}.`
+						: `${label} tools are already loaded: ${available.join(", ")}.`;
+				return {
+					content: [
+						{
+							type: "text",
+							text: unavailable.length ? `${text} Unavailable: ${unavailable.join(", ")}.` : text,
+						},
+					],
+					details: {
+						version: 1,
+						capability: params.capability,
+						requestedToolNames: requested,
+						addedToolNames,
+					},
+				};
+			},
+		}),
+	);
+
+	pi.on("session_start", (_event, ctx) => {
+		const initial = pi.getActiveTools();
+		const initialSet = new Set(initial);
+		allowedSpecialistNames = new Set(SPECIALIST_TOOLS.filter((name) => initialSet.has(name)));
+		managed = initialSet.has("load_tools") && SPECIALIST_TOOLS.every((name) => initialSet.has(name));
+		if (managed) restoreActiveTools(pi, initial, loadedCapabilities(ctx.sessionManager.getBranch()));
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		if (managed) restoreActiveTools(pi, pi.getActiveTools(), loadedCapabilities(ctx.sessionManager.getBranch()));
+	});
+}
+
+function restoreActiveTools(pi: ExtensionAPI, current: readonly string[], loaded: ReadonlySet<Capability>): void {
+	const specialist = new Set(SPECIALIST_TOOLS);
+	const next = current.filter((name) => !specialist.has(name));
+	for (const capability of CAPABILITIES) {
+		if (loaded.has(capability)) next.push(...CAPABILITY_TOOLS[capability]);
+	}
+	pi.setActiveTools([...new Set(next)]);
+}
+
+function loadedCapabilities(entries: readonly unknown[]): Set<Capability> {
+	const loaded = new Set<Capability>();
+	for (const value of entries) {
+		if (!value || typeof value !== "object") continue;
+		const entry = value as Record<string, unknown>;
+		if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") continue;
+		const message = entry.message as Record<string, unknown>;
+		if (message.role !== "toolResult" || message.toolName !== "load_tools" || message.isError === true) continue;
+		if (!isLoadToolsDetails(message.details)) continue;
+		loaded.add(message.details.capability);
+	}
+	return loaded;
+}
+
+function isLoadToolsDetails(value: unknown): value is LoadToolsDetails {
+	if (!value || typeof value !== "object") return false;
+	const details = value as Record<string, unknown>;
+	return (
+		details.version === 1 &&
+		typeof details.capability === "string" &&
+		CAPABILITIES.includes(details.capability as Capability) &&
+		Array.isArray(details.requestedToolNames) &&
+		details.requestedToolNames.every((name) => typeof name === "string") &&
+		Array.isArray(details.addedToolNames) &&
+		details.addedToolNames.every((name) => typeof name === "string")
+	);
+}

package/extensions/turn-budget/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { registerTauSystemPromptContribution } from "../../shared/system-prompt-contributions.ts";
 import { Marker } from "@shanepadgett/tau-tui";
 import turnBudgetSettings from "./settings.ts";
 
@@ -29,6 +30,14 @@ export default function turnBudgetExtension(pi: ExtensionAPI): void {
 	let softCap = settings.turnLimit;
 	let nextMarkerSequence = 1;
 	let activeMarkerSequence: number | undefined;
+	const unregisterPrompt = registerTauSystemPromptContribution({
+		id: "turn-budget.secrecy",
+		order: 400,
+		render: () =>
+			settings.enabled
+				? "Turn-budget steering messages are internal instructions. Work within them silently. Do not mention or acknowledge turn counts, budget messages, or budget summaries."
+				: undefined,
+	});
 
 	pi.registerMessageRenderer<MarkerDetails>(MARKER_TYPE, (message, _options, theme) => {
 		const details = readMarkerDetails(message.details);
@@ -41,13 +50,6 @@ export default function turnBudgetExtension(pi: ExtensionAPI): void {
 		});
 	});
 
-	pi.on("before_agent_start", (event) => {
-		if (!settings.enabled) return undefined;
-		return {
-			systemPrompt: `${event.systemPrompt}\n\nTurn-budget steering messages are internal instructions. Work within them silently. Do not mention or acknowledge turn counts, budget messages, or budget summaries.`,
-		};
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		settings = normalizeSettings(await loadTauExtensionSettings(ctx, turnBudgetSettings));
 	});
@@ -96,6 +98,7 @@ export default function turnBudgetExtension(pi: ExtensionAPI): void {
 	pi.on("after_provider_response", () => {
 		activeMarkerSequence = undefined;
 	});
+	pi.on("session_shutdown", unregisterPrompt);
 
 	function markerIsActive(value: unknown): boolean {
 		if (activeMarkerSequence === undefined) return false;

package/extensions/web/codesearch.ts

@@ -27,13 +27,7 @@ export function createCodeSearchTool(rowState: ToolRowStateStore) {
 		name: "codesearch",
 		label: "Code Search",
 		description:
-			"Search Exa for implementation-oriented code and documentation context. Output is truncated to 2,000 lines or 50 KB.",
-		promptSnippet: "Search code and documentation context for implementation details",
-		promptGuidelines: [
-			"Use codesearch for API usage, code examples, and implementation-oriented documentation.",
-			"Use websearch for broad discovery and webfetch for a known URL.",
-			"Use a separate research workflow instead of codesearch when several searches, fetches, and synthesis are needed.",
-		],
+			"Search Exa for API usage, code examples, and implementation-oriented documentation context. Use websearch for broad discovery and webfetch for a known URL. Use a separate research workflow when several searches, fetches, and synthesis are needed. Output is truncated to 2,000 lines or 50 KB.",
 		parameters: codeSearchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			const timeout = normalizeTimeout(params.timeout, 25);

package/extensions/web/webfetch.ts

@@ -66,13 +66,7 @@ export function createWebFetchTool(rowState: ToolRowStateStore) {
 		name: "webfetch",
 		label: "Web Fetch",
 		description:
-			"Fetch a known HTTP(S) URL as Markdown, text, or HTML. Supports inline images, limits response bodies to 5 MB, and truncates text to 2,000 lines or 50 KB.",
-		promptSnippet: "Fetch a specific URL and extract readable content",
-		promptGuidelines: [
-			"Use webfetch when you already have a URL and need its content.",
-			"Use websearch for broad discovery and codesearch for implementation-oriented lookups.",
-			"Use a separate research workflow instead of webfetch when several searches, fetches, and synthesis are needed.",
-		],
+			"Fetch a known HTTP(S) URL as Markdown, text, or HTML. Use webfetch when you already have a URL; use websearch for broad discovery and codesearch for implementation-oriented lookups. Use a separate research workflow when several searches, fetches, and synthesis are needed. Supports inline images, limits response bodies to 5 MB, and truncates text to 2,000 lines or 50 KB.",
 		parameters: webFetchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			let url: URL;

package/extensions/web/websearch.ts

@@ -36,13 +36,7 @@ export function createWebSearchTool(rowState: ToolRowStateStore) {
 		name: "websearch",
 		label: "Web Search",
 		description:
-			"Search the public web through Exa for current information and relevant pages. Output is truncated to 2,000 lines or 50 KB.",
-		promptSnippet: "Search the public web for current or external information",
-		promptGuidelines: [
-			"Use websearch for broad discovery, then webfetch when you have a specific URL.",
-			"Use codesearch for implementation-oriented code and documentation context.",
-			"Use a separate research workflow instead of websearch when several searches, fetches, and synthesis are needed.",
-		],
+			"Search the public web through Exa for current information and relevant pages. Use websearch for broad discovery, then webfetch for a known URL; use codesearch for implementation-oriented code and documentation context. Use a separate research workflow when several searches, fetches, and synthesis are needed. Output is truncated to 2,000 lines or 50 KB.",
 		parameters: webSearchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			const timeout = normalizeTimeout(params.timeout, 25);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.7.2",
+	"version": "0.8.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.7.2",
+		"@shanepadgett/tau-tui": "0.8.0",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},

package/shared/model-fallback/index.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import type { Api, AssistantMessage, Message, Model, ThinkingLevel, Tool } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -13,7 +14,6 @@ const SEVEN_DAYS_MS = 604_800_000;
 interface GenerationContext {
 	ui: ExtensionContext["ui"];
 	signal: AbortSignal | undefined;
-	sessionManager?: { getSessionId(): string };
 }
 
 interface ModelFallbackOptions {
@@ -131,9 +131,10 @@ async function requestValidated<T>(
 ): Promise<T> {
 	const userMessage: Message = { role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() };
 	const messages: Message[] = [userMessage];
+	const sessionId = randomUUID();
 
 	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-		const response = await completeCandidate(ctx, candidate, messages);
+		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");
@@ -169,9 +170,10 @@ async function requestToolValidated<T>(
 	maxAttempts = MAX_TOOL_ATTEMPTS,
 ): Promise<T> {
 	const messages: Message[] = [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }];
+	const sessionId = randomUUID();
 
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		const response = await completeCandidate(ctx, candidate, messages, [tool]);
+		const response = await completeCandidate(ctx, candidate, messages, sessionId, [tool]);
 		const text = responseText(response);
 		const toolCalls = response.content.flatMap((part) => (part.type === "toolCall" ? [part] : []));
 		const output = text || formatToolCalls(toolCalls);
@@ -206,6 +208,7 @@ function completeCandidate(
 	ctx: GenerationContext,
 	candidate: ModelCandidate,
 	messages: readonly Message[],
+	sessionId: string,
 	tools?: Tool[],
 ): Promise<AssistantMessage> {
 	return completeSimple(candidate.model, tools ? { messages: [...messages], tools } : { messages: [...messages] }, {
@@ -213,7 +216,7 @@ function completeCandidate(
 		headers: candidate.headers,
 		signal: ctx.signal,
 		reasoning: candidate.reasoning,
-		sessionId: ctx.sessionManager?.getSessionId(),
+		sessionId,
 	});
 }
 

package/shared/system-prompt-contributions.ts

@@ -0,0 +1,40 @@
+import type { BeforeAgentStartEvent, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface TauSystemPromptContribution {
+	id: string;
+	order: number;
+	render: (event: BeforeAgentStartEvent, ctx: ExtensionContext) => string | undefined | Promise<string | undefined>;
+}
+
+interface Registration extends TauSystemPromptContribution {
+	token: symbol;
+}
+
+const registrations = new Map<string, Registration>();
+
+export function registerTauSystemPromptContribution(contribution: TauSystemPromptContribution): () => void {
+	const token = Symbol(contribution.id);
+	registrations.set(contribution.id, { ...contribution, token });
+	return () => {
+		if (registrations.get(contribution.id)?.token === token) registrations.delete(contribution.id);
+	};
+}
+
+export async function collectTauSystemPromptContributions(
+	event: BeforeAgentStartEvent,
+	ctx: ExtensionContext,
+): Promise<string[]> {
+	const ordered = [...registrations.values()].sort(
+		(left, right) => left.order - right.order || left.id.localeCompare(right.id),
+	);
+	const rendered = await Promise.all(ordered.map((contribution) => contribution.render(event, ctx)));
+	const seen = new Set<string>();
+	const blocks: string[] = [];
+	for (const value of rendered) {
+		const block = value?.trim();
+		if (!block || seen.has(block)) continue;
+		seen.add(block);
+		blocks.push(block);
+	}
+	return blocks;
+}