@shanepadgett/tau-agent 0.28.1 → 0.30.0

package/docs/context.md

@@ -1,6 +1,6 @@
 # Context management
 
-Tau uses `.pi/contexts` as a reusable map of the repository. A selected context gives an agent the primary files for a work scope and points it toward related files without loading everything.
+Tau uses `.pi/contexts` as a reusable map of the repository. A selected context supplies a small bootstrap projection for a work scope and points toward related files without loading everything.
 
 ## Structure
 
@@ -23,13 +23,15 @@ description = "Checkout calculation and order submission"
 
 [orchestration]
 description = "Building and submitting a checkout order"
-files = ["src/checkout/order.ts", "src/checkout/service.ts"]
-anchors = ["test/checkout/service.test.ts", "src/payments/client.ts"]
+read = []
+outline = ["src/checkout/order.ts", "src/checkout/service.ts"]
+references = ["test/checkout/service.test.ts", "src/payments/client.ts"]
 
 [discounts]
 description = "Applying coupons and account discounts"
-files = ["src/checkout/discounts.ts"]
-anchors = ["test/checkout/discounts.test.ts"]
+read = []
+outline = ["src/checkout/discounts.ts"]
+references = ["test/checkout/discounts.test.ts"]
 ```
 
 Saved as `.pi/contexts/commerce/checkout.toml`, these entries have the IDs `commerce/checkout/orchestration` and `commerce/checkout/discounts`.
@@ -48,12 +50,15 @@ Keep entries focused. Names such as `misc`, `shared`, and `other` hide missing b
 
 Catalog durable code, configuration, tests, standards, and long-lived documentation. Leave scratch files, working plans, interviews, generated output, and rough ideas out of the catalog.
 
-## Choose files and anchors
+## Choose loading modes
 
-- `files` are eagerly read when the entry is selected. Include primary files that are usually required for that scope.
-- `anchors` are shown to the agent as unloaded navigation paths. Use them for related tests, callers, shared dependencies, or documentation that is useful only for some tasks.
+- `read` supplies exact complete file contents. Reserve it for instructions, small authoritative specifications, and other files whose exact wording is routinely needed.
+- `outline` supplies current structural outlines through Explore. Use it for recurring source entry points.
+- `references` supplies unloaded navigation paths. This should be the default for durable code, tests, callers, shared dependencies, and secondary documentation.
 
-Keep the eager set small enough to read on every selection. Keep each path's loading class consistent across the catalog. If selected entries classify the same path differently, eager loading wins.
+Every entry declares all three arrays, including empty arrays. Keep `read` and `outline` small because Tau rebuilds them before model calls. Keep each path's loading mode consistent across the catalog. When selected entries disagree, precedence is `read`, then `outline`, then `references`.
+
+`/context` persists selected entry IDs as branch-local session state. It does not append file contents to conversation history. Before each model call Tau resolves those IDs against the current catalog, reads current `read` files, refreshes changed outlines, and adds one ephemeral projection. Reopening `/context` replaces the active selection. Clear all selections and confirm to remove the projection.
 
 ## Maintain the map
 

package/docs/subagents.md

@@ -5,7 +5,7 @@ Tau's `subagent` tool delegates one focused task to an isolated child Pi session
 Each fresh call returns a thread ID. Continue that thread when feedback or follow-up work depends on the child's prior reads and reasoning:
 
 ```text
-subagent({ agent: "review", task: "Review configuration loading" })
+subagent({ agent: "scout", task: "Trace configuration loading" })
 subagent({ thread: "thread-1", task: "Now check whether this proposed fix covers every caller" })
 ```
 
@@ -14,7 +14,7 @@ Retained threads keep their complete child conversation for five minutes after t
 If the relevant files are already known, autoread them into a fresh or retained child turn:
 
 ```text
-subagent({ agent: "review", task: "Review the runtime change", files: ["src/runtime.ts", "test/runtime.test.ts"] })
+subagent({ agent: "scout", task: "Trace the runtime change", files: ["src/runtime.ts", "test/runtime.test.ts"] })
 ```
 
 Paths may be relative to the parent's current working directory or absolute. Tau reads current, line-numbered snapshots when the turn starts. Unreadable files produce failed context entries without stopping the child. Keep the list focused because complete snapshots consume the child's context window.
@@ -26,7 +26,7 @@ Paths may be relative to the parent's current working directory or absolute. Tau
 | **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 (`review`, `scout`, `web-research`). Duplicate names in one scope are invalid.
+Precedence: **project overrides user**, which overrides Tau's built-ins (`scout`, `web-research`). Duplicate names in one scope are invalid.
 
 ## Definition format
 
@@ -68,6 +68,9 @@ Tau assigns one display name to each fresh child and keeps it for follow-up turn
 
 ## Runtime rules
 
+- Run `/agents` to enable or disable agents for the current session branch. Press Space to stage each toggle, then Enter to apply the changes. Session choices do not change Tau settings.
+- Set `extensions.subagent.disabled` to an array of agent names for persistent global or project-level disabling. Agents disabled this way appear as `disabled by Tau settings` in `/agents` and cannot be enabled there.
+- Disabled agents are omitted from the parent's available-agent list and cannot start or continue a retained thread.
 - Children use the parent's cwd and inherit model/thinking unless the definition overrides them.
 - Children do not receive the parent conversation.
 - Calls can include `files` to autoread line-numbered snapshots into that child turn.
@@ -82,8 +85,7 @@ Tau assigns one display name to each fresh child and keeps it for follow-up turn
 
 ## Built-ins
 
-- `review` — adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
-- `scout` — tiered, AST-first local discovery of files, symbols, data flow, constraints, and unknowns without changing anything
+- `scout` — substantial multi-hop local code lookup that would chew parent context; paths, declarations, imports, references, call edges; facts only. Skip small digs
 - `web-research` — `websearch`, `codesearch`, `webfetch`
 - `context-sync` — maps meaningful uncommitted work into `.pi/contexts`. Offered to the coding agent when `extensions.context.sync.enabled` and `sync.automation` are true. Manual `/context-sync` remains when sync is enabled with `automation` false. Validation can auto-run it when `validation.enabled` and `sync.enabled`
 

package/extensions/cache-diagnostics/index.ts

@@ -415,10 +415,9 @@ export default function cacheDiagnosticsExtension(pi: ExtensionAPI): void {
 			event.message.stopReason !== "error" &&
 			event.message.stopReason !== "aborted" &&
 			(attempt.responseStatus === undefined || (attempt.responseStatus >= 200 && attempt.responseStatus < 300));
-		const missedTokens =
-			baselinePromoted && attempt.request.previousExactPrefix
-				? Math.max(0, Math.min(attempt.request.previousPromptTokens, promptTokens) - usage.cacheRead)
-				: 0;
+		const missedTokens = baselinePromoted
+			? Math.max(0, Math.min(attempt.request.previousPromptTokens, promptTokens) - usage.cacheRead)
+			: 0;
 		const cacheMiss = baselinePromoted && cacheActivitySeen && missedTokens > CACHE_NOISE_FLOOR;
 		const result: ResultRecord = {
 			kind: "result",
@@ -472,7 +471,7 @@ export default function cacheDiagnosticsExtension(pi: ExtensionAPI): void {
 	);
 	pi.on("session_tree", () => addMarker("session-tree"));
 	pi.on("tool_execution_end", (event) => {
-		if (event.toolName !== "context_prune" && event.toolName !== "load_tools") return;
+		if (event.toolName !== "working_memory" && event.toolName !== "load_tools") return;
 		return addMarker("cache-affecting-tool", { tool: event.toolName, isError: event.isError });
 	});
 }

package/extensions/context/README.md

@@ -4,7 +4,7 @@ Context stores reusable repository work scopes in `.pi/contexts`. Folder names b
 
 See [Context management](../../docs/context.md) for catalog structure and taxonomy guidance.
 
-Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed.
+Use `/context` to set active entries for the current session branch. Tau stores only the selected entry IDs. Before each model call it rebuilds one ephemeral projection from current files, so repeated selections do not accumulate snapshots in conversation history. Open `/context`, press `Ctrl+C`, then confirm to clear active context.
 
 After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.
 
@@ -37,12 +37,15 @@ description = "Player-owned gameplay systems"
 
 [input]
 description = "Input mapping and command handling"
-files = ["src/player/input.ts"]
+read = []
+outline = ["src/player/input.ts"]
+references = []
 
 [movement]
 description = "Player locomotion and collision"
-files = ["src/player/movement.ts"]
-anchors = ["src/runtime/fetch-handler.ts"]
+read = []
+outline = ["src/player/movement.ts"]
+references = ["src/runtime/fetch-handler.ts"]
 ```
 
-For example, `.pi/contexts/gameplay/player.toml` appears in the `gameplay` tab as the `Player` concept with `input` and `movement` entries. When `movement` is selected, Tau autoreads `src/player/movement.ts` and lists `src/runtime/fetch-handler.ts` as an unloaded anchor. If one selected entry marks a path as a file and another marks it as an anchor, autoread wins.
+Every entry must declare all three loading arrays. `read` supplies exact complete contents, `outline` asks Explore for current structural outlines, and `references` lists unloaded paths. If selected entries classify the same path differently, precedence is `read`, then `outline`, then `references`.

package/extensions/context/definitions.ts

@@ -12,8 +12,9 @@ export interface ContextEntry {
 	conceptDescription: string;
 	name: string;
 	description: string;
-	files: string[];
-	anchors: string[];
+	read: string[];
+	outline: string[];
+	references: string[];
 	path: string;
 }
 
@@ -37,7 +38,7 @@ const CONTEXT_IGNORED_FILENAMES = new Set([
 	"uv.lock",
 	"yarn.lock",
 ]);
-const CONTEXT_ENTRY_FIELDS = new Set(["description", "files", "anchors"]);
+const CONTEXT_ENTRY_FIELDS = new Set(["description", "read", "outline", "references"]);
 
 export function isContextEligiblePath(path: string, ignoreGlobs: readonly string[] = []): boolean {
 	return (
@@ -45,6 +46,8 @@ export function isContextEligiblePath(path: string, ignoreGlobs: readonly string
 		!CONTEXT_IGNORED_FILENAMES.has(basename(path)) &&
 		!ignoreGlobs.some((glob) => matchGlob(glob, path)) &&
 		path !== ".pi/tau/ideas.jsonl" &&
+		path !== ".pi/tau/reviews" &&
+		!path.startsWith(".pi/tau/reviews/") &&
 		path !== ".working" &&
 		!path.startsWith(".working/") &&
 		path !== ".pi/contexts" &&
@@ -99,8 +102,8 @@ function sortedUnique(values: readonly string[]): string[] {
 	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
 
-export function contextEntryPaths(entry: Pick<ContextEntry, "files" | "anchors">): string[] {
-	return sortedUnique([...entry.files, ...entry.anchors]);
+export function contextEntryPaths(entry: Pick<ContextEntry, "read" | "outline" | "references">): string[] {
+	return sortedUnique([...entry.read, ...entry.outline, ...entry.references]);
 }
 
 export async function loadContextEntries(root: string): Promise<ContextEntry[]> {
@@ -128,22 +131,29 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 				const record = value as Record<string, unknown>;
 				const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
 				if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
-				const anchors = record.anchors ?? [];
 				if (
 					typeof record.description !== "string" ||
 					!record.description.trim() ||
-					!Array.isArray(record.files) ||
-					record.files.some((item) => typeof item !== "string") ||
-					!Array.isArray(anchors) ||
-					anchors.some((item) => typeof item !== "string") ||
-					(record.files.length === 0 && anchors.length === 0)
+					!Array.isArray(record.read) ||
+					record.read.some((item) => typeof item !== "string") ||
+					!Array.isArray(record.outline) ||
+					record.outline.some((item) => typeof item !== "string") ||
+					!Array.isArray(record.references) ||
+					record.references.some((item) => typeof item !== "string") ||
+					(record.read.length === 0 && record.outline.length === 0 && record.references.length === 0)
 				)
 					throw new Error(`Invalid context entry: ${path} [${name}]`);
 				const entry = validSlug(name, "Context entry");
-				const entryFiles = sortedUnique((record.files as string[]).map((item) => normalizeProjectPath(root, item)));
-				const entryAnchors = sortedUnique((anchors as string[]).map((item) => normalizeProjectPath(root, item)));
-				const overlap = entryFiles.find((item) => entryAnchors.includes(item));
-				if (overlap) throw new Error(`Context path cannot be both file and anchor: ${path} [${name}] ${overlap}`);
+				const entryRead = sortedUnique((record.read as string[]).map((item) => normalizeProjectPath(root, item)));
+				const entryOutline = sortedUnique(
+					(record.outline as string[]).map((item) => normalizeProjectPath(root, item)),
+				);
+				const entryReferences = sortedUnique(
+					(record.references as string[]).map((item) => normalizeProjectPath(root, item)),
+				);
+				const classified = [...entryRead, ...entryOutline, ...entryReferences];
+				const overlap = classified.find((item, index) => classified.indexOf(item) !== index);
+				if (overlap) throw new Error(`Context path has multiple loading modes: ${path} [${name}] ${overlap}`);
 				result.push({
 					id: `${tab}/${concept}/${entry}`,
 					tab,
@@ -152,8 +162,9 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 					conceptDescription,
 					name: entry,
 					description: record.description.trim(),
-					files: entryFiles,
-					anchors: entryAnchors,
+					read: entryRead,
+					outline: entryOutline,
+					references: entryReferences,
 					path,
 				});
 			}

package/extensions/context/evidence.ts

@@ -299,7 +299,7 @@ function formatOverview(evidence: SyncEvidence): string {
 		"2. Concept (toml): reuse, new, split, or merge?",
 		"3. Entry (section): update, new, split, delete, or move?",
 		"4. Bloat: any touched scope now a junk drawer?",
-		"5. Membership: files/anchors under winners only. Preserve existing read vs anchor class.",
+		"5. Membership: read/outline/references under winners only. Preserve existing loading mode.",
 		"",
 		"Edit only files under .pi/contexts/. Use patch. Do not use bash.",
 		"Every eligible changed non-deleted file must belong to at least one entry. Remove every stale catalog path.",
@@ -346,8 +346,9 @@ function formatCatalog(evidence: SyncEvidence): string {
 				conceptDescription: entry.conceptDescription,
 				entry: entry.name,
 				description: entry.description,
-				files: entry.files,
-				anchors: entry.anchors,
+				read: entry.read,
+				outline: entry.outline,
+				references: entry.references,
 				missing: contextEntryPaths(entry).filter((path) => evidence.missingPaths.has(path)),
 				path: entry.path,
 			})),

package/extensions/context/index.ts

@@ -1,15 +1,20 @@
-import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getKeybindings } from "@earendil-works/pi-tui";
-import { emitTauEvent } from "../../shared/events.ts";
 import { createGitRunner, loadRepoStatus } from "../../shared/git.ts";
-import { createInjectedContext } from "../../shared/injected-context.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { ContextPanel, ContextSyncStatusPanel } from "./panel.ts";
 import { findProjectRoot, loadContextEntries, type ContextEntry } from "./definitions.ts";
 import { hideContextSyncEvidenceTool, registerContextSyncEvidenceTool } from "./evidence.ts";
+import {
+	buildContextProjection,
+	contextProjectionKey,
+	contextProjectionMessage,
+	removeLegacyContextMessages,
+	selectContextEntries,
+} from "./projection.ts";
 import contextSettings from "./settings.ts";
+import { CONTEXT_SELECTION_TYPE, createContextSelectionState, replayContextSelection } from "./state.ts";
 import { runContextSync } from "./sync.ts";
 import { formatContextValidationFailure, validateContextCatalog } from "./validation.ts";
 
@@ -17,6 +22,8 @@ export default function contextExtension(pi: ExtensionAPI): void {
 	let settings = contextSettings.defaults;
 	let lastValidationFailure: string | undefined;
 	let syncCommandRegistered = false;
+	let lifecycleGeneration = 0;
+	let projectionCache: { key: string; content: string } | undefined;
 
 	registerContextSyncEvidenceTool(pi);
 
@@ -79,7 +86,7 @@ export default function contextExtension(pi: ExtensionAPI): void {
 	};
 
 	pi.registerCommand("context", {
-		description: "Select repository context entries and inject their files",
+		description: "Select active repository context entries",
 		handler: async (_args, ctx) => {
 			if (ctx.mode !== "tui" || !ctx.isProjectTrusted()) {
 				ctx.ui.notify("/context requires a trusted TUI project", "warning");
@@ -92,44 +99,21 @@ export default function contextExtension(pi: ExtensionAPI): void {
 				ctx.ui.notify(`No context entries found in ${join(root, ".pi", "contexts")}`, "warning");
 				return;
 			}
+			const active = replayContextSelection(ctx.sessionManager.getBranch()).entryIds;
 			const selected = await ctx.ui.custom<ContextEntry[] | undefined>(
-				(tui, theme, _keys, done) => new ContextPanel(tui, theme, entries, done),
+				(tui, theme, _keys, done) => new ContextPanel(tui, theme, entries, active, done),
 				{
 					overlay: true,
 					overlayOptions: { anchor: "top-center", width: "70%", minWidth: 64, maxHeight: "80%", margin: 2 },
 				},
 			);
-			if (!selected?.length) return;
-			const files = [...new Set(selected.flatMap((entry) => entry.files))].sort();
-			const fileSet = new Set(files);
-			const anchors = [...new Set(selected.flatMap((entry) => entry.anchors))]
-				.filter((path) => !fileSet.has(path))
-				.sort();
-			pi.sendMessage(
-				createInjectedContext(
-					[
-						"Selected repository context:",
-						...selected.map((entry) => `- ${entry.id}: ${entry.description}`),
-						"",
-						"Eager snapshots supplied through autoread:",
-						...(files.length ? files.map((path) => `- ${path}`) : ["(none)"]),
-						"",
-						"Lazy navigation anchors whose contents have not been loaded:",
-						...(anchors.length ? anchors.map((path) => `- ${path}`) : ["(none)"]),
-						"",
-						"Treat eager snapshots as authoritative current project context. Do not reread them or search for coverage around them. Inspect only the anchors needed for the request, using grep or bounded reads. Explore elsewhere only when the request or concrete evidence requires missing information.",
-					].join("\n"),
-					{ source: "context", title: "Project context" },
-				),
+			if (selected === undefined) return;
+			pi.appendEntry(CONTEXT_SELECTION_TYPE, createContextSelectionState(selected.map((entry) => entry.id)));
+			projectionCache = undefined;
+			ctx.ui.notify(
+				selected.length ? `${selected.length} context entries active` : "Active context cleared",
+				"info",
 			);
-			if (files.length)
-				emitTauEvent(pi, "tau:autoread.requested", {
-					source: "context",
-					title: "Project context",
-					cwd: root,
-					batchId: randomUUID(),
-					files: files.map((path) => ({ path })),
-				});
 		},
 	});
 
@@ -137,8 +121,34 @@ export default function contextExtension(pi: ExtensionAPI): void {
 	if (settings.sync.enabled) registerContextSyncCommand();
 
 	pi.on("session_start", async (_event, ctx) => {
+		lifecycleGeneration += 1;
+		projectionCache = undefined;
 		await refreshSettings(ctx);
 	});
+	pi.on("context", async (event, ctx) => {
+		const messages = removeLegacyContextMessages(event.messages);
+		if (!ctx.isProjectTrusted()) return { messages };
+		const entryIds = replayContextSelection(ctx.sessionManager.getBranch()).entryIds;
+		if (entryIds.length === 0) return { messages };
+		const generation = lifecycleGeneration;
+		const root = await findProjectRoot(ctx.cwd);
+		const selection = selectContextEntries(await loadContextEntries(root), entryIds);
+		const key = await contextProjectionKey(root, selection, ctx.signal, () => generation === lifecycleGeneration);
+		if (generation !== lifecycleGeneration) return { messages };
+		if (projectionCache?.key !== key) {
+			projectionCache = {
+				key,
+				content: await buildContextProjection(
+					pi,
+					root,
+					selection,
+					ctx.signal,
+					() => generation === lifecycleGeneration,
+				),
+			};
+		}
+		return { messages: [contextProjectionMessage(projectionCache.content), ...messages] };
+	});
 	pi.on("agent_start", async (_event, ctx) => {
 		await refreshSettings(ctx);
 	});
@@ -202,6 +212,18 @@ export default function contextExtension(pi: ExtensionAPI): void {
 			ctx.ui.notify(`Context validation failed: ${error instanceof Error ? error.message : String(error)}`, "error");
 		}
 	});
+	pi.on("session_tree", () => {
+		lifecycleGeneration += 1;
+		projectionCache = undefined;
+	});
+	pi.on("session_compact", () => {
+		lifecycleGeneration += 1;
+		projectionCache = undefined;
+	});
+	pi.on("session_shutdown", () => {
+		lifecycleGeneration += 1;
+		projectionCache = undefined;
+	});
 }
 
 function showContextSyncWidget(ctx: ExtensionContext): { update(status: string): void; clear(): void } {

package/extensions/context/panel.ts

@@ -21,6 +21,7 @@ export class ContextPanel implements Component {
 		tui: TUI,
 		theme: Theme,
 		entries: readonly ContextEntry[],
+		activeEntryIds: readonly string[],
 		done: (result: ContextEntry[] | undefined) => void,
 	) {
 		const firstEntry = entries[0];
@@ -67,6 +68,8 @@ export class ContextPanel implements Component {
 			border: "box",
 		};
 		this.panel = new ToolPanel(theme, this.config);
+		for (const [tab, list] of this.lists)
+			list.setSelectedIds(activeEntryIds.filter((id) => id.startsWith(`${tab}/`)));
 	}
 
 	handleInput(data: string): void {
@@ -141,10 +144,7 @@ export class ContextPanel implements Component {
 					...(range ? [truncateToWidth(range, width, "…")] : []),
 					...visible.map(({ kind, path }) =>
 						truncateToWidth(
-							this.theme.fg(
-								kind === "read" ? "muted" : "dim",
-								`${kind === "read" ? "read" : "anchor"} • ${path}`,
-							),
+							this.theme.fg(kind === "reference" ? "dim" : "muted", `${kind} • ${path}`),
 							width,
 							"…",
 						),
@@ -154,10 +154,11 @@ export class ContextPanel implements Component {
 			invalidate: () => this.tabs.invalidate(),
 		};
 	}
-	private currentPaths(): Array<{ kind: "read" | "anchor"; path: string }> {
+	private currentPaths(): Array<{ kind: "read" | "outline" | "reference"; path: string }> {
 		return [
-			...this.current.files.map((path) => ({ kind: "read" as const, path })),
-			...this.current.anchors.map((path) => ({ kind: "anchor" as const, path })),
+			...this.current.read.map((path) => ({ kind: "read" as const, path })),
+			...this.current.outline.map((path) => ({ kind: "outline" as const, path })),
+			...this.current.references.map((path) => ({ kind: "reference" as const, path })),
 		];
 	}
 	private pathPageSize(tabLines = this.tabs.render(this.tui.terminal.columns).length): number {
@@ -167,7 +168,7 @@ export class ContextPanel implements Component {
 		return this.currentPaths().length > pageSize ? Math.max(1, pageSize - 1) : pageSize;
 	}
 	private secondary(): string {
-		return `${[...this.selected.values()].reduce((sum, items) => sum + items.length, 0)} selected · ${this.current.files.length} read · ${this.current.anchors.length} anchors`;
+		return `${[...this.selected.values()].reduce((sum, items) => sum + items.length, 0)} selected · ${this.current.read.length} read · ${this.current.outline.length} outline · ${this.current.references.length} references`;
 	}
 	private hints() {
 		const list = this.activeList();
@@ -177,7 +178,7 @@ export class ContextPanel implements Component {
 					...this.tabs.getKeyHints(),
 					...(this.currentPaths().length > this.pathPageSize() ? [rawHint("option+↑/↓", "scroll paths")] : []),
 					rawHint("ctrl+c", "clear all"),
-					bindingHint("tui.select.confirm", "inject"),
+					bindingHint("tui.select.confirm", "activate"),
 					bindingHint("tui.select.cancel", "cancel"),
 				];
 	}

package/extensions/context/projection.ts

@@ -0,0 +1,141 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ContextEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	CONTEXT_PROJECTION_TYPE,
+	isContextProjectionMessage,
+	isLegacyContextMessage,
+} from "../../shared/context-messages.ts";
+import { requestOutlineInjections } from "../../shared/outline-injection.ts";
+import type { ContextEntry } from "./definitions.ts";
+
+type ContextMessage = ContextEvent["messages"][number];
+
+export { CONTEXT_PROJECTION_TYPE } from "../../shared/context-messages.ts";
+
+export interface SelectedContext {
+	entries: ContextEntry[];
+	missingEntryIds: string[];
+	read: string[];
+	outline: string[];
+	references: string[];
+}
+
+export function selectContextEntries(entries: readonly ContextEntry[], entryIds: readonly string[]): SelectedContext {
+	const byId = new Map(entries.map((entry) => [entry.id, entry]));
+	const selected = entryIds.flatMap((id) => {
+		const entry = byId.get(id);
+		return entry ? [entry] : [];
+	});
+	const read = new Set(selected.flatMap((entry) => entry.read));
+	const outline = new Set(selected.flatMap((entry) => entry.outline).filter((path) => !read.has(path)));
+	const references = new Set(
+		selected.flatMap((entry) => entry.references).filter((path) => !read.has(path) && !outline.has(path)),
+	);
+	return {
+		entries: selected,
+		missingEntryIds: entryIds.filter((id) => !byId.has(id)),
+		read: [...read].sort((left, right) => left.localeCompare(right)),
+		outline: [...outline].sort((left, right) => left.localeCompare(right)),
+		references: [...references].sort((left, right) => left.localeCompare(right)),
+	};
+}
+
+export async function contextProjectionKey(
+	root: string,
+	selection: SelectedContext,
+	signal: AbortSignal | undefined,
+	isLifecycleCurrent: () => boolean,
+): Promise<string> {
+	const paths = [...selection.read, ...selection.outline];
+	const files: Array<[string, string]> = [];
+	for (const path of paths) {
+		signal?.throwIfAborted();
+		if (!isLifecycleCurrent()) throw new Error("Context projection crossed a session lifecycle boundary");
+		try {
+			const hash = createHash("sha256");
+			for await (const chunk of createReadStream(resolve(root, path), { signal })) {
+				if (!isLifecycleCurrent()) throw new Error("Context projection crossed a session lifecycle boundary");
+				hash.update(chunk);
+			}
+			files.push([path, hash.digest("hex")]);
+		} catch (error) {
+			if (signal?.aborted || !isLifecycleCurrent()) throw error;
+			files.push([path, "missing"]);
+		}
+	}
+	return JSON.stringify({
+		entries: selection.entries.map((entry) => [entry.id, entry.description]),
+		missingEntryIds: selection.missingEntryIds,
+		read: selection.read,
+		outline: selection.outline,
+		references: selection.references,
+		files,
+	});
+}
+
+export async function buildContextProjection(
+	pi: Pick<ExtensionAPI, "events">,
+	root: string,
+	selection: SelectedContext,
+	signal: AbortSignal | undefined,
+	isLifecycleCurrent: () => boolean,
+): Promise<string> {
+	const warnings = selection.missingEntryIds.map((id) => `${id}: selected entry no longer exists`);
+	const reads: Array<{ path: string; content: string }> = [];
+	for (const path of selection.read) {
+		signal?.throwIfAborted();
+		if (!isLifecycleCurrent()) throw new Error("Context projection crossed a session lifecycle boundary");
+		try {
+			reads.push({ path, content: await readFile(resolve(root, path), "utf8") });
+		} catch (error) {
+			warnings.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	const outlined = await requestOutlineInjections(pi, {
+		cwd: root,
+		batchId: randomUUID(),
+		paths: selection.outline,
+		signal,
+		isLifecycleCurrent,
+	});
+	warnings.push(...outlined.warnings);
+	if (!isLifecycleCurrent()) throw new Error("Context projection crossed a session lifecycle boundary");
+	return [
+		"Active repository context (ephemeral; rebuilt from the current branch selection before each model call):",
+		...selection.entries.map((entry) => `- ${entry.id}: ${entry.description}`),
+		...(selection.missingEntryIds.length ? selection.missingEntryIds.map((id) => `- ${id}: unavailable`) : []),
+		"",
+		"Complete current file contents:",
+		...(reads.length
+			? reads.flatMap(({ path, content }) => [`<read path=${JSON.stringify(path)}>`, content, "</read>"])
+			: ["(none)"]),
+		"",
+		"Current structural outlines:",
+		...(outlined.messages.length
+			? outlined.messages.flatMap((message) => ["<outline>", message.content, "</outline>"])
+			: ["(none)"]),
+		"",
+		"Unloaded references:",
+		...(selection.references.length ? selection.references.map((path) => `- ${path}`) : ["(none)"]),
+		...(warnings.length ? ["", "Projection warnings:", ...warnings.map((warning) => `- ${warning}`)] : []),
+		"",
+		"Treat complete reads and outlines as current snapshots. Inspect unloaded references only when the request or concrete evidence requires them. Explore elsewhere only for missing information.",
+	].join("\n");
+}
+
+export function contextProjectionMessage(content: string): ContextMessage {
+	return {
+		role: "custom",
+		customType: CONTEXT_PROJECTION_TYPE,
+		content,
+		display: false,
+		timestamp: Date.now(),
+	};
+}
+
+export function removeLegacyContextMessages(messages: readonly ContextMessage[]): ContextMessage[] {
+	return messages.filter((message) => !isContextProjectionMessage(message) && !isLegacyContextMessage(message));
+}

package/extensions/context/state.ts

@@ -0,0 +1,30 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const CONTEXT_SELECTION_TYPE = "tau.context.selection";
+
+export interface ContextSelectionStateV1 {
+	v: 1;
+	entryIds: string[];
+}
+
+export function createContextSelectionState(entryIds: readonly string[]): ContextSelectionStateV1 {
+	return { v: 1, entryIds: [...new Set(entryIds)].sort((left, right) => left.localeCompare(right)) };
+}
+
+export function replayContextSelection(branch: readonly SessionEntry[]): ContextSelectionStateV1 {
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index];
+		if (entry?.type !== "custom" || entry.customType !== CONTEXT_SELECTION_TYPE) continue;
+		const state = parseContextSelectionState(entry.data);
+		if (state) return state;
+	}
+	return createContextSelectionState([]);
+}
+
+function parseContextSelectionState(value: unknown): ContextSelectionStateV1 | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	if (record.v !== 1 || !Array.isArray(record.entryIds) || record.entryIds.some((id) => typeof id !== "string"))
+		return undefined;
+	return createContextSelectionState(record.entryIds as string[]);
+}