@shanepadgett/tau-agent 0.4.0 → 0.5.0

package/docs/subagents.md

@@ -9,7 +9,7 @@ Tau's `subagent` tool delegates one focused task to an isolated child Pi session
 | **User (global)** | `~/.pi/agent/tau/agents/*.md` | You want the agent in every project |
 | **Project** | nearest trusted `.pi/tau/agents/*.md` | Repo-specific helpers |
 
-Precedence: **project overrides user**, which overrides Tau's built-ins (`scout`, `web-research`). Duplicate names in one scope are invalid.
+Precedence: **project overrides user**, which overrides Tau's built-ins (`scout`, `context-maintenance`, `web-research`). Duplicate names in one scope are invalid.
 
 ## Definition format
 
@@ -46,12 +46,14 @@ Named tools and configured models must exist in the normally loaded child Pi env
 
 - Children use the parent's cwd and inherit model/thinking unless the definition overrides them.
 - Children do not receive the parent conversation.
+- Children load only the extensions that own their declared tools. Unrelated extension hooks do not run in child sessions.
 - At most four children run at once; extra calls wait in order.
 - Returned text is capped (50 KB / 2,000 lines); full truncated output is saved to a private temp file.
 
 ## Built-ins
 
 - `scout` — local exploration with `read`, `grep`, `find`, `ls`
+- `context-maintenance` — repository context reconciliation with interactive user approval
 - `web-research` — `websearch`, `codesearch`, `webfetch`
 
 Ask Tau to delegate, or let it call `subagent` with an agent name and task.

package/extensions/context/README.md

@@ -0,0 +1,20 @@
+# Context
+
+Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
+
+Use `/context` to select entries and inject their files through Tau autoread. Use `/context-manage <idea>` to start an isolated maintenance agent that researches the catalog, presents proposed operations for approval, accepts feedback, and applies only selected operations.
+
+```toml
+name = "Player"
+description = "Player-owned gameplay systems"
+
+[input]
+description = "Input mapping and command handling"
+files = ["src/player/input.ts"]
+
+[movement]
+description = "Player locomotion and collision"
+files = ["src/player/movement.ts"]
+```
+
+For example, `.pi/contexts/gameplay/player.toml` appears in the `gameplay` tab as the `Player` concept with `input` and `movement` entries.

package/extensions/context/definitions.ts

@@ -0,0 +1,258 @@
+import { access, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { parse, stringify } from "smol-toml";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+export interface ContextEntry {
+	id: string;
+	tab: string;
+	concept: string;
+	conceptName: string;
+	conceptDescription: string;
+	name: string;
+	description: string;
+	files: string[];
+	path: string;
+}
+
+export interface ContextProposal {
+	tab: string;
+	concept: string;
+	conceptName: string;
+	conceptDescription: string;
+	entry: string;
+	description: string;
+	files: string[];
+}
+
+export type ContextOperation =
+	| (ContextProposal & { id: string; kind: "create"; reason: string })
+	| {
+			id: string;
+			kind: "add-files" | "remove-files";
+			tab: string;
+			concept: string;
+			entry: string;
+			files: string[];
+			reason: string;
+	  }
+	| {
+			id: string;
+			kind: "replace-file";
+			tab: string;
+			concept: string;
+			entry: string;
+			from: string;
+			to: string;
+			reason: string;
+	  };
+
+export async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function findProjectRoot(cwd: string): Promise<string> {
+	const home = resolve(homedir());
+	let current = resolve(cwd);
+	let gitRoot: string | undefined;
+	while (true) {
+		if (await pathExists(join(current, ".pi", "contexts"))) return current;
+		if (!gitRoot && (await pathExists(join(current, ".git")))) gitRoot = current;
+		const parent = dirname(current);
+		if (parent === current || current === home) break;
+		current = parent;
+	}
+	return gitRoot ?? resolve(cwd);
+}
+
+export function validSlug(value: string, label: string): string {
+	const slug = value.trim();
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`${label} must use lowercase kebab-case: ${value}`);
+	return slug;
+}
+
+export function normalizeProjectPath(root: string, input: string): string {
+	const absolute = resolve(root, input.trim().replace(/^@/, ""));
+	const path = relative(root, absolute).split(sep).join("/");
+	if (!path || path === "." || path === ".." || path.startsWith("../"))
+		throw new Error(`Path must stay inside project: ${input}`);
+	return path;
+}
+
+function sortedUnique(values: readonly string[]): string[] {
+	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+
+export async function requireFiles(root: string, inputs: readonly string[]): Promise<string[]> {
+	const files = sortedUnique(inputs.map((input) => normalizeProjectPath(root, input)));
+	for (const file of files) {
+		try {
+			if (!(await stat(join(root, file))).isFile()) throw new Error();
+		} catch {
+			throw new Error(`Context file does not exist: ${file}`);
+		}
+	}
+	return files;
+}
+
+export async function loadContextEntries(root: string): Promise<ContextEntry[]> {
+	const contextsRoot = join(root, ".pi", "contexts");
+	if (!(await pathExists(contextsRoot))) return [];
+	const tabs = (await readdir(contextsRoot, { withFileTypes: true }))
+		.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+		.sort((a, b) => a.name.localeCompare(b.name));
+	const result: ContextEntry[] = [];
+	for (const tabEntry of tabs) {
+		const tab = validSlug(tabEntry.name, "Context tab");
+		const files = (await readdir(join(contextsRoot, tab), { withFileTypes: true }))
+			.filter((entry) => entry.isFile() && extname(entry.name) === ".toml")
+			.sort((a, b) => a.name.localeCompare(b.name));
+		for (const file of files) {
+			const path = join(contextsRoot, tab, file.name);
+			const concept = validSlug(basename(file.name, ".toml"), "Context concept");
+			const raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
+			const conceptName = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : concept;
+			const conceptDescription = typeof raw.description === "string" ? raw.description.trim() : "";
+			for (const [name, value] of Object.entries(raw)) {
+				if (name === "name" || name === "description") continue;
+				if (!value || typeof value !== "object" || Array.isArray(value))
+					throw new Error(`Invalid context entry: ${path} [${name}]`);
+				const record = value as Record<string, unknown>;
+				if (
+					typeof record.description !== "string" ||
+					!record.description.trim() ||
+					!Array.isArray(record.files) ||
+					record.files.length === 0 ||
+					record.files.some((item) => typeof item !== "string")
+				)
+					throw new Error(`Invalid context entry: ${path} [${name}]`);
+				const entry = validSlug(name, "Context entry");
+				result.push({
+					id: `${tab}/${concept}/${entry}`,
+					tab,
+					concept,
+					conceptName,
+					conceptDescription,
+					name: entry,
+					description: record.description.trim(),
+					files: sortedUnique((record.files as string[]).map((item) => normalizeProjectPath(root, item))),
+					path,
+				});
+			}
+		}
+	}
+	return result;
+}
+
+export async function writeContextEntry(root: string, proposal: ContextProposal, replace: boolean): Promise<void> {
+	const tab = validSlug(proposal.tab, "Context tab");
+	const concept = validSlug(proposal.concept, "Context concept");
+	const entry = validSlug(proposal.entry, "Context entry");
+	const conceptName = proposal.conceptName.trim();
+	const description = proposal.description.trim();
+	if (!conceptName) throw new Error("Context concept name is required");
+	if (!description) throw new Error("Context entry description is required");
+	const files = await requireFiles(root, proposal.files);
+	const path = join(root, ".pi", "contexts", tab, `${concept}.toml`);
+	await withFileMutationQueue(path, async () => {
+		let raw: Record<string, unknown> = {};
+		if (await pathExists(path)) raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
+		if (!replace && raw[entry] !== undefined)
+			throw new Error(`Context entry already exists: ${tab}/${concept}/${entry}`);
+		if (raw.name === undefined) raw.name = conceptName;
+		if (raw.description === undefined) raw.description = proposal.conceptDescription.trim();
+		raw[entry] = { description, files };
+		await mkdir(dirname(path), { recursive: true });
+		const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+		await writeFile(temporary, stringify(raw), "utf8");
+		await rename(temporary, path);
+	});
+}
+
+export async function updateContextFiles(
+	root: string,
+	tabInput: string,
+	conceptInput: string,
+	entryInput: string,
+	paths: readonly string[],
+	action: "add" | "remove",
+): Promise<string[]> {
+	const tab = validSlug(tabInput, "Context tab");
+	const concept = validSlug(conceptInput, "Context concept");
+	const entry = validSlug(entryInput, "Context entry");
+	const current = (await loadContextEntries(root)).find((item) => item.id === `${tab}/${concept}/${entry}`);
+	if (!current) throw new Error(`Unknown context entry: ${tab}/${concept}/${entry}`);
+	const changed =
+		action === "add" ? await requireFiles(root, paths) : paths.map((path) => normalizeProjectPath(root, path));
+	const changedSet = new Set(changed);
+	const files =
+		action === "add" ? [...current.files, ...changed] : current.files.filter((file) => !changedSet.has(file));
+	if (files.length === 0) throw new Error("Context entries must contain at least one file");
+	await writeContextEntry(
+		root,
+		{
+			tab,
+			concept,
+			conceptName: current.conceptName,
+			conceptDescription: current.conceptDescription,
+			entry,
+			description: current.description,
+			files,
+		},
+		true,
+	);
+	return sortedUnique(changed);
+}
+
+export async function replaceContextFile(
+	root: string,
+	tab: string,
+	concept: string,
+	entry: string,
+	fromInput: string,
+	toInput: string,
+): Promise<void> {
+	const from = normalizeProjectPath(root, fromInput);
+	const [to] = await requireFiles(root, [toInput]);
+	const current = (await loadContextEntries(root)).find((item) => item.id === `${tab}/${concept}/${entry}`);
+	if (!current) throw new Error(`Unknown context entry: ${tab}/${concept}/${entry}`);
+	if (!current.files.includes(from)) throw new Error(`Context entry does not contain: ${from}`);
+	await writeContextEntry(
+		root,
+		{
+			tab: current.tab,
+			concept: current.concept,
+			conceptName: current.conceptName,
+			conceptDescription: current.conceptDescription,
+			entry: current.name,
+			description: current.description,
+			files: current.files.map((file) => (file === from ? to : file)),
+		},
+		true,
+	);
+}
+
+export async function applyContextOperation(root: string, operation: ContextOperation): Promise<void> {
+	if (operation.kind === "create") {
+		await writeContextEntry(root, operation, false);
+		return;
+	}
+	if (operation.kind === "replace-file") {
+		await replaceContextFile(root, operation.tab, operation.concept, operation.entry, operation.from, operation.to);
+		return;
+	}
+	await updateContextFiles(
+		root,
+		operation.tab,
+		operation.concept,
+		operation.entry,
+		operation.files,
+		operation.kind === "add-files" ? "add" : "remove",
+	);
+}

package/extensions/context/index.ts

@@ -0,0 +1,476 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { emitTauEvent } from "../../shared/events.ts";
+import { createInjectedContext } from "../../shared/injected-context.ts";
+import { discoverAgents } from "../subagent/agents.ts";
+import { extensionPathsForTools, runSubagent } from "../subagent/run.ts";
+import { ContextPanel, ProposalPanel, type ProposalReviewDecision } from "./panel.ts";
+import {
+	applyContextOperation,
+	findProjectRoot,
+	loadContextEntries,
+	normalizeProjectPath,
+	pathExists,
+	requireFiles,
+	updateContextFiles,
+	validSlug,
+	writeContextEntry,
+	type ContextEntry,
+	type ContextOperation,
+} from "./definitions.ts";
+
+const identityParams = Type.Object(
+	{ tab: Type.String(), concept: Type.String(), entry: Type.String() },
+	{ additionalProperties: false },
+);
+const membershipParams = Type.Object(
+	{
+		tab: Type.String(),
+		concept: Type.String(),
+		entry: Type.String(),
+		paths: Type.Array(Type.String(), { minItems: 1 }),
+	},
+	{ additionalProperties: false },
+);
+const createParams = Type.Object(
+	{
+		tab: Type.String(),
+		concept: Type.String(),
+		conceptName: Type.String(),
+		conceptDescription: Type.String(),
+		entry: Type.String(),
+		description: Type.String(),
+		paths: Type.Array(Type.String(), { minItems: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+const operationIdentity = {
+	id: Type.String({ minLength: 1 }),
+	tab: Type.String(),
+	concept: Type.String(),
+	entry: Type.String(),
+	reason: Type.String({ minLength: 1 }),
+};
+const reviewParams = Type.Object(
+	{
+		operations: Type.Array(
+			Type.Union([
+				Type.Object({
+					...operationIdentity,
+					kind: Type.Literal("create"),
+					conceptName: Type.String(),
+					conceptDescription: Type.String(),
+					description: Type.String(),
+					files: Type.Array(Type.String(), { minItems: 1 }),
+				}),
+				Type.Object({
+					...operationIdentity,
+					kind: Type.Union([Type.Literal("add-files"), Type.Literal("remove-files")]),
+					files: Type.Array(Type.String(), { minItems: 1 }),
+				}),
+				Type.Object({
+					...operationIdentity,
+					kind: Type.Literal("replace-file"),
+					from: Type.String(),
+					to: Type.String(),
+				}),
+			]),
+			{ minItems: 1 },
+		),
+	},
+	{ additionalProperties: false },
+);
+
+function result(value: unknown) {
+	return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value };
+}
+
+let reviewQueue = Promise.resolve();
+
+async function withReviewLock<T>(task: () => Promise<T>): Promise<T> {
+	const previous = reviewQueue;
+	let release = () => {};
+	reviewQueue = new Promise<void>((resolve) => {
+		release = resolve;
+	});
+	await previous;
+	try {
+		return await task();
+	} finally {
+		release();
+	}
+}
+
+function parseChangedFiles(raw: string): Array<{ path: string; status: string; renamedFrom?: string }> {
+	const fields = raw.split("\0").filter(Boolean);
+	const changes: Array<{ path: string; status: string; renamedFrom?: string }> = [];
+	for (let index = 0; index < fields.length; index += 1) {
+		const field = fields[index];
+		if (!field) continue;
+		const status = field.slice(0, 2);
+		const path = field.slice(3);
+		if (status.includes("R") || status.includes("C")) {
+			const renamedFrom = fields[index + 1];
+			if (renamedFrom) index += 1;
+			changes.push({ path, status, ...(renamedFrom ? { renamedFrom } : {}) });
+		} else changes.push({ path, status });
+	}
+	return changes;
+}
+
+async function validateContextOperations(
+	root: string,
+	operations: readonly ContextOperation[],
+): Promise<ContextOperation[]> {
+	const entries = await loadContextEntries(root);
+	const ids = new Set(entries.map((entry) => entry.id));
+	const normalized: ContextOperation[] = [];
+	for (const operation of operations) {
+		const id = operation.id.trim();
+		const reason = operation.reason.trim();
+		if (!id) throw new Error("Context operation id is required");
+		if (!reason) throw new Error(`Context operation reason is required: ${id}`);
+		const tab = validSlug(operation.tab, "Context tab");
+		const concept = validSlug(operation.concept, "Context concept");
+		const entry = validSlug(operation.entry, "Context entry");
+		const contextId = `${tab}/${concept}/${entry}`;
+		if (operation.kind === "create") {
+			if (ids.has(contextId)) throw new Error(`Context entry already exists: ${contextId}`);
+			if (!operation.conceptName.trim()) throw new Error(`Context concept name is required: ${id}`);
+			if (!operation.description.trim()) throw new Error(`Context entry description is required: ${id}`);
+			ids.add(contextId);
+			normalized.push({
+				...operation,
+				id,
+				reason,
+				tab,
+				concept,
+				entry,
+				conceptName: operation.conceptName.trim(),
+				conceptDescription: operation.conceptDescription.trim(),
+				description: operation.description.trim(),
+				files: await requireFiles(root, operation.files),
+			});
+			continue;
+		}
+		const current = entries.find((item) => item.id === contextId);
+		if (!current) throw new Error(`Unknown context entry: ${contextId}`);
+		if (operation.kind === "replace-file") {
+			const from = normalizeProjectPath(root, operation.from);
+			if (!current.files.includes(from)) throw new Error(`Context entry does not contain: ${from}`);
+			const [to] = await requireFiles(root, [operation.to]);
+			normalized.push({ ...operation, id, reason, tab, concept, entry, from, to });
+			continue;
+		}
+		const files =
+			operation.kind === "add-files"
+				? await requireFiles(root, operation.files)
+				: operation.files.map((path) => normalizeProjectPath(root, path));
+		if (operation.kind === "remove-files" && current.files.filter((path) => !files.includes(path)).length === 0)
+			throw new Error(`Context operation would empty entry: ${contextId}`);
+		if (operation.kind === "remove-files") {
+			const unknown = files.find((path) => !current.files.includes(path));
+			if (unknown) throw new Error(`Context entry does not contain: ${unknown}`);
+		}
+		normalized.push({ ...operation, id, reason, tab, concept, entry, files });
+	}
+	return normalized;
+}
+
+async function maintain(pi: ExtensionAPI, ctx: ExtensionCommandContext, root: string, request: string): Promise<void> {
+	const discovery = await discoverAgents(root, ctx.isProjectTrusted());
+	const definition = discovery.agents.get("context-maintenance");
+	if (!definition) throw new Error("Built-in context-maintenance subagent is unavailable");
+	const existing = await loadContextEntries(root);
+	const controller = new AbortController();
+	const response = await runSubagent({
+		definition,
+		extensionPaths: extensionPathsForTools(pi, definition.tools),
+		task: `Maintain repository context for this request:\n${request}\n\nExisting entries:\n${JSON.stringify(
+			existing.map(({ id, description, files }) => ({ id, description, files })),
+			null,
+			2,
+		)}`,
+		ctx,
+		thinkingLevel: pi.getThinkingLevel(),
+		signal: controller.signal,
+	});
+	if (response.details.status !== "completed") throw new Error(response.content);
+}
+
+export default function contextExtension(pi: ExtensionAPI): void {
+	let active: ContextEntry[] = [];
+
+	pi.registerCommand("context", {
+		description: "Select repository context entries and inject their files",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui" || !ctx.isProjectTrusted()) {
+				ctx.ui.notify("/context requires a trusted TUI project", "warning");
+				return;
+			}
+			await ctx.waitForIdle();
+			const root = await findProjectRoot(ctx.cwd);
+			const entries = await loadContextEntries(root);
+			const firstEntry = entries[0];
+			if (!firstEntry) {
+				ctx.ui.notify(`No context entries found in ${join(root, ".pi", "contexts")}`, "warning");
+				return;
+			}
+			const selected = await ctx.ui.custom<ContextEntry[] | undefined>(
+				(tui, theme, _keys, done) => new ContextPanel(tui, theme, entries, done),
+				{
+					overlay: true,
+					overlayOptions: {
+						anchor: "top-center",
+						width: "70%",
+						minWidth: 64,
+						maxHeight: "80%",
+						margin: 2,
+					},
+				},
+			);
+			if (!selected?.length) return;
+			active = selected;
+			pi.appendEntry("tau.context-selection", { ids: selected.map((entry) => entry.id) });
+			const files = [...new Set(selected.flatMap((entry) => entry.files))].sort();
+			pi.sendMessage(
+				createInjectedContext(
+					"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.",
+					{ source: "context", title: "Project context" },
+				),
+			);
+			emitTauEvent(pi, "tau:autoread.requested", {
+				source: "context",
+				title: "Project context",
+				cwd: root,
+				batchId: randomUUID(),
+				files: files.map((path) => ({ path })),
+			});
+		},
+	});
+
+	pi.registerCommand("context-manage", {
+		description: "Research, review, and maintain repository context entries",
+		handler: async (args, ctx) => {
+			if (!args.trim()) {
+				ctx.ui.notify("Usage: /context-manage <context idea>", "warning");
+				return;
+			}
+			if (ctx.mode !== "tui" || !ctx.isProjectTrusted()) {
+				ctx.ui.notify("/context-manage requires a trusted TUI project", "warning");
+				return;
+			}
+			await ctx.waitForIdle();
+			const root = await findProjectRoot(ctx.cwd);
+			ctx.ui.setStatus("context-manage", "maintaining contexts");
+			try {
+				await maintain(pi, ctx, root, args.trim());
+			} catch (error) {
+				ctx.ui.notify(
+					`Context maintenance failed: ${error instanceof Error ? error.message : String(error)}`,
+					"error",
+				);
+				return;
+			} finally {
+				ctx.ui.setStatus("context-manage", undefined);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "context_changes",
+		label: "Context Changes",
+		description: "Report uncommitted repository paths for context maintenance.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, signal, _update, ctx) {
+			if (!ctx.isProjectTrusted()) throw new Error("Context changes require a trusted project");
+			const rootResult = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: ctx.cwd, signal });
+			if (rootResult.code !== 0) throw new Error("No Git repository found");
+			const root = rootResult.stdout.trim();
+			const status = await pi.exec("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], {
+				cwd: root,
+				signal,
+			});
+			if (status.code !== 0) throw new Error(status.stderr.trim() || "Unable to read Git status");
+			return result({ root, changes: parseChangedFiles(status.stdout) });
+		},
+	});
+	pi.registerTool({
+		name: "context_review",
+		label: "Context Review",
+		description: "Present context maintenance operations for user approval and apply only selected operations.",
+		parameters: reviewParams,
+		executionMode: "sequential",
+		async execute(_id, params, _signal, _update, ctx) {
+			if (ctx.mode !== "tui" || !ctx.hasUI) throw new Error("Context review requires TUI mode");
+			if (!ctx.isProjectTrusted()) throw new Error("Context review requires a trusted project");
+			const rawOperations = params.operations as ContextOperation[];
+			if (new Set(rawOperations.map((operation) => operation.id)).size !== rawOperations.length)
+				throw new Error("Context operation ids must be unique");
+			const root = await findProjectRoot(ctx.cwd);
+			const operations = await validateContextOperations(root, rawOperations);
+			if (new Set(operations.map((operation) => operation.id)).size !== operations.length)
+				throw new Error("Context operation ids must be unique after trimming");
+			ctx.ui.setWorkingVisible(false);
+			try {
+				return await withReviewLock(async () => {
+					const decision = await ctx.ui.custom<ProposalReviewDecision>(
+						(tui, theme, _keys, done) => new ProposalPanel(tui, theme, operations, done),
+					);
+					if (decision.kind === "rejected") return result(decision);
+					if (decision.kind === "feedback") {
+						const feedback = await ctx.ui.editor(
+							decision.scope === "batch" ? "Context proposal feedback" : `Feedback for ${decision.operationId}`,
+							"",
+						);
+						return result(
+							feedback?.trim()
+								? { ...decision, text: feedback.trim() }
+								: { kind: "rejected", reason: "Feedback cancelled" },
+						);
+					}
+					for (const operation of decision.operations) await applyContextOperation(root, operation);
+					return result({
+						kind: "applied" as const,
+						operationIds: decision.operations.map((operation) => operation.id),
+					});
+				});
+			} finally {
+				ctx.ui.setWorkingVisible(true);
+			}
+		},
+	});
+	pi.registerTool({
+		name: "context_list",
+		label: "Context List",
+		description: "List repository context tabs, concepts, entries, and file counts.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			return result(
+				(await loadContextEntries(root)).map(({ id, description, files }) => ({
+					id,
+					description,
+					fileCount: files.length,
+				})),
+			);
+		},
+	});
+	pi.registerTool({
+		name: "context_get",
+		label: "Context Get",
+		description: "Get one repository context entry and its files.",
+		parameters: identityParams,
+		async execute(_id, params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			const id = `${params.tab}/${params.concept}/${params.entry}`;
+			const entry = (await loadContextEntries(root)).find((item) => item.id === id);
+			if (!entry) throw new Error(`Unknown context entry: ${id}`);
+			return result(entry);
+		},
+	});
+	pi.registerTool({
+		name: "context_create",
+		label: "Context Create",
+		description: "Create one validated repository context entry.",
+		parameters: createParams,
+		async execute(_id, params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			await writeContextEntry(root, { ...params, files: params.paths }, false);
+			return result({ created: `${params.tab}/${params.concept}/${params.entry}` });
+		},
+	});
+	pi.registerTool({
+		name: "context_add_files",
+		label: "Context Add Files",
+		description: "Add existing project files to one context entry.",
+		parameters: membershipParams,
+		async execute(_id, params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			return result({
+				added: await updateContextFiles(root, params.tab, params.concept, params.entry, params.paths, "add"),
+			});
+		},
+	});
+	pi.registerTool({
+		name: "context_remove_files",
+		label: "Context Remove Files",
+		description: "Remove project files from one context entry.",
+		parameters: membershipParams,
+		async execute(_id, params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			return result({
+				removed: await updateContextFiles(root, params.tab, params.concept, params.entry, params.paths, "remove"),
+			});
+		},
+	});
+	pi.registerTool({
+		name: "context_check",
+		label: "Context Check",
+		description: "Report context memberships and existence for exact project paths.",
+		parameters: Type.Object({ paths: Type.Array(Type.String(), { minItems: 1 }) }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			const entries = await loadContextEntries(root);
+			return result(
+				await Promise.all(
+					params.paths.map(async (input) => {
+						const path = normalizeProjectPath(root, input);
+						return {
+							path,
+							exists: await pathExists(join(root, path)),
+							memberships: entries.filter((entry) => entry.files.includes(path)).map((entry) => entry.id),
+						};
+					}),
+				),
+			);
+		},
+	});
+	pi.registerTool({
+		name: "context_audit",
+		label: "Context Audit",
+		description: "Report context paths that no longer exist.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, _signal, _update, ctx) {
+			const root = await findProjectRoot(ctx.cwd);
+			const entries = await loadContextEntries(root);
+			const stale = (
+				await Promise.all(
+					entries.flatMap((entry) =>
+						entry.files.map(async (path) =>
+							(await pathExists(join(root, path))) ? undefined : { entry: entry.id, path },
+						),
+					),
+				)
+			).filter((item) => item !== undefined);
+			return result({ stale });
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const root = await findProjectRoot(ctx.cwd);
+		const entries = await loadContextEntries(root);
+		let selectionData: unknown;
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "custom" && entry.customType === "tau.context-selection") selectionData = entry.data;
+		}
+		const ids =
+			typeof selectionData === "object" &&
+			selectionData !== null &&
+			"ids" in selectionData &&
+			Array.isArray(selectionData.ids)
+				? selectionData.ids.filter((id: unknown): id is string => typeof id === "string")
+				: [];
+		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,
+	);
+}

package/extensions/context/panel.ts

@@ -0,0 +1,237 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, getKeybindings, Key, matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { bindingHint, rawHint, SelectableList, Tabs, ToolPanel, type ToolPanelConfig } from "@shanepadgett/tau-tui";
+import type { ContextEntry, ContextOperation } from "./definitions.ts";
+
+type SelectableEntry = ContextEntry & { id: string };
+
+export class ContextPanel implements Component {
+	private readonly tui: TUI;
+	private readonly theme: Theme;
+	private readonly tabs: Tabs;
+	private readonly panel: ToolPanel;
+	private readonly config: ToolPanelConfig;
+	private readonly lists = new Map<string, SelectableList<SelectableEntry>>();
+	private readonly selected = new Map<string, readonly SelectableEntry[]>();
+	private readonly done: (result: ContextEntry[] | undefined) => void;
+	private current: ContextEntry;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		entries: readonly ContextEntry[],
+		done: (result: ContextEntry[] | undefined) => void,
+	) {
+		const firstEntry = entries[0];
+		if (!firstEntry) throw new Error("Context panel requires at least one entry");
+		this.tui = tui;
+		this.theme = theme;
+		this.done = done;
+		this.current = firstEntry;
+		const tabNames = [...new Set(entries.map((entry) => entry.tab))].sort();
+		this.tabs = new Tabs(
+			theme,
+			tabNames.map((tab) => {
+				const items = entries.filter((entry) => entry.tab === tab);
+				const list = new SelectableList(theme, {
+					items,
+					emptyMessage: "No context entries.",
+					selection: { kind: "multi" },
+					filter: { searchText: (item) => `${item.conceptName} ${item.name} ${item.description}` },
+					actions: [],
+					maxVisible: 10,
+					renderItem: (item, state, width) => [
+						truncateToWidth(
+							`${state.active ? theme.bold(item.conceptName) : item.conceptName} · ${item.name}  ${theme.fg("dim", item.description)}`,
+							width,
+							"…",
+						),
+					],
+					onResult: () => {},
+					onSelectionChange: (value) => {
+						this.selected.set(tab, value);
+						this.sync();
+					},
+				});
+				this.lists.set(tab, list);
+				return { id: tab, label: tab, count: items.length, body: list, getKeyHints: () => list.getKeyHints() };
+			}),
+			tabNames[0] ?? "",
+		);
+		this.config = {
+			title: "Project context",
+			secondary: this.secondary(),
+			body: this.body(),
+			footer: { kind: "hints", hints: this.hints() },
+			border: "box",
+		};
+		this.panel = new ToolPanel(theme, this.config);
+	}
+
+	handleInput(data: string): void {
+		const list = this.activeList();
+		if (!list?.isFilterFocused()) {
+			const keys = getKeybindings();
+			if (matchesKey(data, Key.ctrl("c"))) {
+				for (const [tab, tabList] of this.lists) {
+					tabList.setSelectedIds([]);
+					this.selected.set(tab, []);
+				}
+				this.sync();
+				return;
+			}
+			if (keys.matches(data, "tui.select.confirm")) {
+				this.done([...this.selected.values()].flatMap((items) => [...items]));
+				return;
+			}
+			if (keys.matches(data, "tui.select.cancel")) {
+				this.done(undefined);
+				return;
+			}
+		}
+		this.tabs.handleInput(data);
+		this.current = this.activeList()?.getCurrentItem() ?? this.current;
+		this.sync();
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+
+	private activeList(): SelectableList<SelectableEntry> | undefined {
+		return this.lists.get(this.tabs.getActiveId());
+	}
+	private body(): Component {
+		return {
+			render: (width) => [
+				...this.tabs.render(width),
+				"",
+				...this.current.files.map((file) => truncateToWidth(this.theme.fg("muted", `• ${file}`), width, "…")),
+			],
+			invalidate: () => this.tabs.invalidate(),
+		};
+	}
+	private secondary(): string {
+		return `${[...this.selected.values()].reduce((sum, items) => sum + items.length, 0)} selected`;
+	}
+	private hints() {
+		const list = this.activeList();
+		return list?.isFilterFocused()
+			? list.getKeyHints()
+			: [
+					...this.tabs.getKeyHints(),
+					rawHint("ctrl+c", "clear all"),
+					bindingHint("tui.select.confirm", "inject"),
+					bindingHint("tui.select.cancel", "cancel"),
+				];
+	}
+	private sync(): void {
+		this.config.secondary = this.secondary();
+		this.config.footer = { kind: "hints", hints: this.hints() };
+		this.tui.requestRender();
+	}
+}
+
+export type ProposalReviewDecision =
+	| { kind: "approve"; operations: ContextOperation[] }
+	| { kind: "feedback"; scope: "batch"; selectedIds: string[] }
+	| { kind: "feedback"; scope: "operation"; operationId: string; selectedIds: string[] }
+	| { kind: "rejected" };
+
+export class ProposalPanel implements Component {
+	private readonly list: SelectableList<ContextOperation>;
+	private readonly panel: ToolPanel;
+	private readonly done: (result: ProposalReviewDecision) => void;
+	private selected: readonly ContextOperation[] = [];
+	private current: ContextOperation;
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		proposals: readonly ContextOperation[],
+		done: (result: ProposalReviewDecision) => void,
+	) {
+		const first = proposals[0];
+		if (!first) throw new Error("Proposal panel requires at least one operation");
+		this.done = done;
+		this.current = first;
+		const items = [...proposals];
+		this.list = new SelectableList(theme, {
+			items,
+			emptyMessage: "No proposals.",
+			selection: { kind: "multi", primaryLabel: "apply selected" },
+			actions: [],
+			cancelLabel: "cancel",
+			maxVisible: 12,
+			renderItem: (item, _state, width) => [
+				truncateToWidth(
+					`${theme.fg("accent", item.kind)} · ${item.tab}/${item.concept}/${item.entry}  ${theme.fg("dim", item.reason)}`,
+					width,
+					"…",
+				),
+			],
+			onResult: (result) =>
+				done(
+					result.kind === "primary" && result.items.length > 0
+						? { kind: "approve", operations: [...result.items] }
+						: { kind: "rejected" },
+				),
+			onSelectionChange: (selected) => {
+				this.selected = selected;
+				tui.requestRender();
+			},
+		});
+		this.list.setSelectedIds(items.map((item) => item.id));
+		this.selected = items;
+		this.panel = new ToolPanel(theme, {
+			title: "Maintain contexts",
+			secondary: "Review proposed operations",
+			body: {
+				render: (width) => [
+					...this.list.render(width),
+					"",
+					...operationPaths(this.current).map((path) =>
+						truncateToWidth(theme.fg("muted", `• ${path}`), width, "…"),
+					),
+				],
+				invalidate: () => this.list.invalidate(),
+			},
+			footer: {
+				kind: "hints",
+				hints: [
+					...this.list.getKeyHints(),
+					rawHint("ctrl+b", "batch feedback"),
+					rawHint("ctrl+i", "item feedback"),
+				],
+			},
+		});
+	}
+	handleInput(data: string): void {
+		if (!this.list.isFilterFocused()) {
+			const selectedIds = this.selected.map((item) => item.id);
+			if (matchesKey(data, Key.ctrl("b"))) {
+				this.done({ kind: "feedback", scope: "batch", selectedIds });
+				return;
+			}
+			if (matchesKey(data, Key.ctrl("i"))) {
+				const current = this.list.getCurrentItem();
+				if (current) this.done({ kind: "feedback", scope: "operation", operationId: current.id, selectedIds });
+				return;
+			}
+		}
+		this.list.handleInput(data);
+		this.current = this.list.getCurrentItem() ?? this.current;
+	}
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}
+
+function operationPaths(operation: ContextOperation): string[] {
+	return operation.kind === "replace-file" ? [`${operation.from} → ${operation.to}`] : operation.files;
+}

package/extensions/subagent/README.md

@@ -4,12 +4,13 @@ Subagent delegates one focused task to an isolated child Pi session. It keeps th
 
 Agent definitions can override the parent model and thinking level. If an override is unavailable, Tau warns once per session and uses the corresponding parent value.
 
-Tau includes two read-only agents:
+Tau includes three built-in agents:
 
 - `scout` explores local files and code with `read`, `grep`, `find`, and `ls`.
+- `context-maintenance` reconciles reusable repository context entries and requests approval before updates.
 - `web-research` researches web and code sources with `websearch`, `codesearch`, and `webfetch`.
 
-Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. When a child must inspect another repository, put its exact absolute path in the delegated task.
+Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. Tau loads only the extensions that own a child's declared tools, so unrelated extension hooks do not run in child sessions. When a child must inspect another repository, put its exact absolute path in the delegated task.
 
 ## Agent definitions
 

package/extensions/subagent/agents/context-maintenance.md

@@ -0,0 +1,23 @@
+---
+name: context-maintenance
+description: Reconcile repository context definitions after meaningful scope changes, with user approval before every update
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - context_list
+  - context_get
+  - context_check
+  - context_audit
+  - context_changes
+  - context_review
+model: openai-codex/gpt-5.6-luna
+thinking: high
+---
+
+Maintain the repository context catalog. Research only the changed or requested scopes. Existing entries should stay small, reusable, and useful for future work. Prefer updating an existing entry over creating a near-duplicate. Do not create one entry per file.
+
+Use context_changes when the task does not provide exact changed paths. Use context_list, context_get, context_check, and context_audit to understand the current catalog. Call context_review with concrete proposed operations. That tool owns user approval and applies only selected operations.
+
+If context_review returns feedback, revise the affected proposal or batch and call context_review again. If it returns rejected, stop. Never claim an operation was applied unless context_review reports it applied. Finish with only a short applied/rejected summary.

package/extensions/subagent/agents.ts

@@ -126,6 +126,10 @@ async function loadScope(
 		const reason = error instanceof Error ? error.message : "directory unavailable";
 		return new Map([
 			["scout", [{ path: directory, name: "scout", reason: `packaged agents unavailable: ${reason}` }]],
+			[
+				"context-maintenance",
+				[{ path: directory, name: "context-maintenance", reason: `packaged agents unavailable: ${reason}` }],
+			],
 			[
 				"web-research",
 				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],

package/extensions/subagent/index.ts

@@ -3,7 +3,7 @@ import { Type } from "typebox";
 import { createToolRowStateStore } from "../../shared/tool-row-state.js";
 import { discoverAgents, type AgentDiscovery } from "./agents.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
-import { FifoGate, runSubagent, type SubagentDetails } from "./run.ts";
+import { extensionPathsForTools, FifoGate, runSubagent, type SubagentDetails } from "./run.ts";
 
 const params = Type.Object(
 	{ agent: Type.String({ minLength: 1 }), task: Type.String({ minLength: 1 }) },
@@ -137,6 +137,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					}
 					const result = await runSubagent({
 						definition,
+						extensionPaths: extensionPathsForTools(pi, definition.tools),
 						task,
 						ctx,
 						thinkingLevel,

package/extensions/subagent/run.ts

@@ -6,11 +6,14 @@ import {
 	createAgentSession,
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
+	DefaultResourceLoader,
 	formatSize,
+	getAgentDir,
 	SessionManager,
 	truncateHead,
 	type AgentSession,
 	type AgentSessionEvent,
+	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentDefinition } from "./agents.ts";
@@ -18,6 +21,25 @@ import type { AgentDefinition } from "./agents.ts";
 const PREVIEW_LIMIT = 600;
 const VALUE_LIMIT = 180;
 
+const CHILD_UI_BLOCKED_METHODS = new Set([
+	"setEditorComponent",
+	"setFooter",
+	"setStatus",
+	"setTitle",
+	"setWidget",
+	"setWorkingIndicator",
+]);
+
+function childUiContext(ui: ExtensionContext["ui"]): ExtensionContext["ui"] {
+	return new Proxy(ui, {
+		get(target, property, receiver) {
+			if (typeof property === "string" && CHILD_UI_BLOCKED_METHODS.has(property)) return () => undefined;
+			const value = Reflect.get(target, property, receiver) as unknown;
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
 export interface SubagentAction {
 	tool: string;
 	summary: string;
@@ -58,6 +80,19 @@ export interface SubagentDetails {
 	};
 }
 
+export function extensionPathsForTools(pi: ExtensionAPI, tools: readonly string[]): string[] {
+	const selected = new Set(tools);
+	return [
+		...new Set(
+			pi
+				.getAllTools()
+				.filter((tool) => selected.has(tool.name))
+				.map((tool) => tool.sourceInfo.path)
+				.filter((path) => path.length > 0 && !path.startsWith("<")),
+		),
+	].sort();
+}
+
 export class FifoGate {
 	private active = 0;
 	private readonly waiters: Array<{
@@ -125,6 +160,7 @@ function assistants(session: AgentSession): AssistantMessage[] {
 
 export async function runSubagent(options: {
 	definition: AgentDefinition;
+	extensionPaths: readonly string[];
 	task: string;
 	ctx: ExtensionContext;
 	thinkingLevel: string;
@@ -132,7 +168,16 @@ export async function runSubagent(options: {
 	onUpdate?: (details: SubagentDetails) => void | Promise<void>;
 	onWarning?: (warning: string) => void;
 }): Promise<{ content: string; details: SubagentDetails }> {
-	const { definition, task, ctx, thinkingLevel: parentThinkingLevel, signal, onUpdate, onWarning } = options;
+	const {
+		definition,
+		extensionPaths,
+		task,
+		ctx,
+		thinkingLevel: parentThinkingLevel,
+		signal,
+		onUpdate,
+		onWarning,
+	} = options;
 	const started = Date.now();
 	let model = ctx.model;
 	let thinkingLevel = parentThinkingLevel;
@@ -193,6 +238,13 @@ export async function runSubagent(options: {
 		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
 		if (!auth.ok) throw new Error(`Agent ${definition.name} startup failed: ${auth.error}`);
 		if (signal.aborted) throw new Error(`Agent ${definition.name} startup aborted`);
+		const resourceLoader = new DefaultResourceLoader({
+			cwd: ctx.cwd,
+			agentDir: getAgentDir(),
+			noExtensions: true,
+			additionalExtensionPaths: [...extensionPaths],
+		});
+		await resourceLoader.reload();
 		const created = await createAgentSession({
 			cwd: ctx.cwd,
 			model,
@@ -200,10 +252,13 @@ export async function runSubagent(options: {
 			modelRegistry: ctx.modelRegistry,
 			tools: definition.tools,
 			excludeTools: ["subagent"],
+			resourceLoader,
 			sessionManager: SessionManager.inMemory(ctx.cwd),
 		});
 		session = created.session;
-		await session.bindExtensions({ mode: "print" });
+		await session.bindExtensions(
+			ctx.mode === "tui" && ctx.hasUI ? { mode: "tui", uiContext: childUiContext(ctx.ui) } : { mode: "print" },
+		);
 		const active = session.getActiveToolNames().sort();
 		const expected = [...definition.tools].sort();
 		if (active.join("\0") !== expected.join("\0") || active.includes("subagent")) {

package/extensions/tau-help/help.md

@@ -26,6 +26,10 @@ Adds `/clear-screen` to clear terminal output without changing the session.
 
 Adds `/commit` for semantic commit grouping, review, and committing selected repository changes.
 
+## context
+
+Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-manage <idea>` to run interactive, approval-based catalog maintenance. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+
 ## explore
 
 Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. They produce smaller model payloads and readable tool rows. `read` includes focused line ranges; `grep`, `find`, and `ls` keep discovery output compact so the agent spends fewer tokens rereading directory and search results.
@@ -80,7 +84,7 @@ Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed draf
 
 ## subagent
 
-Gives Tau a subagent delegation tool for isolated, focused work. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in `scout` and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
+Gives Tau a subagent delegation tool for isolated, focused work. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in `scout`, `context-maintenance`, and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
 
 ## tau-help
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,8 +28,9 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.4.0",
-		"@toon-format/toon": "2.3.0"
+		"@shanepadgett/tau-tui": "0.5.0",
+		"@toon-format/toon": "2.3.0",
+		"smol-toml": "1.4.2"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/shared/injected-context.ts

@@ -3,7 +3,7 @@ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 export const INJECTED_CONTEXT_TYPE = "tau.injected-context";
 
 export interface InjectedContextDetails {
-	source: "review" | "tau-context";
+	source: "review" | "context";
 	title?: string;
 }
 
@@ -61,7 +61,7 @@ export function getBranchInjectedContexts(entries: readonly SessionEntry[]): Inj
 function readDetails(value: unknown): InjectedContextDetails | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const record = value as Record<string, unknown>;
-	if (record.source !== "review" && record.source !== "tau-context") return undefined;
+	if (record.source !== "review" && record.source !== "context") return undefined;
 	return {
 		source: record.source,
 		...(typeof record.title === "string" ? { title: record.title } : {}),