@shanepadgett/tau-agent 0.28.1 → 0.29.0

package/docs/subagents.md

@@ -82,7 +82,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
+- `review` — nuclear, architecture-first review for necessity, reuse, ownership, duplication, and simplification; runtime correctness is secondary
 - `scout` — tiered, AST-first local discovery of files, symbols, data flow, constraints, and unknowns without changing anything
 - `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

@@ -472,7 +472,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/explore/README.md

@@ -6,7 +6,7 @@ Pi keeps ordinary filesystem tools (`ls`, `find`, `grep`, `read`). Explore adds
 
 ## Large `read` / autoread
 
-When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a registered source file (including Markdown) above `explore.read.structureThresholdLines` (default 200) returns an **outline** — declarations or headings — not the full body. Use ranged `read` (`offset`/`limit`, capped by `explore.read.maxRangeLines`) or `show` for bodies and sections. Small files and unregistered paths stay ordinary Pi full text. Set `explore.read.enabled` to `false` to turn the overlay off.
+When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a registered source file (including Markdown) above `explore.read.structureThresholdLines` (default 200) returns an **outline** — declarations or headings — not the full body. Use ranged `read` (`offset`/`limit`) or `show` for bodies and sections. Small files and unregistered paths stay ordinary Pi full text. Set `explore.read.enabled` to `false` to turn the overlay off.
 
 ## Tools
 

package/extensions/explore/ast/read/hook.ts

@@ -5,14 +5,7 @@ import { resolveExplorePath } from "../../traverse.ts";
 import type { ExploreEngine } from "../engine.ts";
 import { formatOutlineFile } from "../format/outline.ts";
 import { outlinePath } from "../queries/outline.ts";
-import {
-	countLines,
-	formatLargeReadOutline,
-	rangedReadOverLimitMessage,
-	readCallKind,
-	shouldOutlineFullRead,
-	type ExploreReadSettings,
-} from "./policy.ts";
+import { formatLargeReadOutline, readCallKind, shouldOutlineFullRead, type ExploreReadSettings } from "./policy.ts";
 
 type ReadOverlayResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -47,9 +40,7 @@ export function registerReadOutlineHook(pi: ExtensionAPI, engineFor: (cwd: strin
 		if (engine.registry.adapterForPath(absolutePath) === undefined) return;
 
 		const kind = readCallKind(event.input);
-		if (kind === "ranged") {
-			return enforceRangedLimit(event.input, event.content, readSettings.maxRangeLines);
-		}
+		if (kind === "ranged") return;
 
 		return substituteLargeFullRead({
 			engine,
@@ -96,30 +87,7 @@ async function substituteLargeFullRead(options: {
 	}
 }
 
-function enforceRangedLimit(
-	input: Record<string, unknown>,
-	content: ReadonlyArray<{ type: string; text?: string }>,
-	maxRangeLines: number,
-): ReadOverlayResult | undefined {
-	const limit = typeof input.limit === "number" && Number.isFinite(input.limit) ? input.limit : undefined;
-	const returnedLines = countLines(textFromContent(content));
-	const message = rangedReadOverLimitMessage({ limit, returnedLines, maxRangeLines });
-	if (message === undefined) return undefined;
-	return {
-		content: [{ type: "text", text: message }],
-		isError: true,
-	};
-}
-
 function readPathInput(input: Record<string, unknown>): string | undefined {
 	const path = input.path;
 	return typeof path === "string" && path.length > 0 ? path : undefined;
 }
-
-function textFromContent(content: ReadonlyArray<{ type: string; text?: string }>): string {
-	const parts: string[] = [];
-	for (const part of content) {
-		if (part.type === "text" && typeof part.text === "string") parts.push(part.text);
-	}
-	return parts.join("\n");
-}

package/extensions/explore/ast/read/policy.ts

@@ -1,28 +1,12 @@
 export type ExploreReadSettings = {
 	enabled: boolean;
 	structureThresholdLines: number;
-	maxRangeLines: number;
 };
 
 export type ReadCallKind = "full" | "ranged";
 
 const LARGE_READ_OUTLINE_INSTRUCTION = "large file: use ranged read or show for bodies";
 
-/** Newline-based line count (empty string → 0). */
-export function countLines(text: string): number {
-	if (text.length === 0) return 0;
-	let count = 1;
-	for (let i = 0; i < text.length; i += 1) {
-		const code = text.charCodeAt(i);
-		if (code === 10) count += 1;
-		else if (code === 13) {
-			count += 1;
-			if (text.charCodeAt(i + 1) === 10) i += 1;
-		}
-	}
-	return count;
-}
-
 export function readCallKind(input: { offset?: unknown; limit?: unknown }): ReadCallKind {
 	const hasOffset = typeof input.offset === "number" && Number.isFinite(input.offset);
 	const hasLimit = typeof input.limit === "number" && Number.isFinite(input.limit);
@@ -33,22 +17,6 @@ export function shouldOutlineFullRead(lineCount: number, structureThresholdLines
 	return lineCount > structureThresholdLines;
 }
 
-/** Hard-error message when a ranged read exceeds maxRangeLines; undefined when allowed. */
-export function rangedReadOverLimitMessage(options: {
-	limit: number | undefined;
-	returnedLines: number;
-	maxRangeLines: number;
-}): string | undefined {
-	const { limit, returnedLines, maxRangeLines } = options;
-	if (typeof limit === "number" && limit > maxRangeLines) {
-		return `Range limit ${limit} exceeds explore.read.maxRangeLines (${maxRangeLines}). Shrink limit and retry.`;
-	}
-	if (returnedLines > maxRangeLines) {
-		return `Ranged read returned ${returnedLines} lines; max is explore.read.maxRangeLines (${maxRangeLines}). Set a smaller limit and retry.`;
-	}
-	return undefined;
-}
-
 export function formatLargeReadOutline(outlineText: string): string {
 	if (outlineText.length === 0) return LARGE_READ_OUTLINE_INSTRUCTION;
 	return `${outlineText}\n${LARGE_READ_OUTLINE_INSTRUCTION}`;

package/extensions/explore/index.ts

@@ -21,6 +21,7 @@ import {
 import { createReverseDepsTool } from "./ast/tools/reverse-deps.ts";
 import { createShowTool } from "./ast/tools/show.ts";
 import { registerExploreGuidance } from "./guidance.ts";
+import { registerExploreOutlineInjection } from "./outline-injection.ts";
 import { registerExploreAutoread } from "./read/autoread.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
@@ -61,6 +62,7 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 	pi.registerTool(createContextTool(rowState, temporaryOutput, engineFor, graphFor));
 	registerReadOutlineHook(pi, engineFor);
 	registerExploreAutoread(pi, rowState, engineFor);
+	registerExploreOutlineInjection(pi, rowState, temporaryOutput, engineFor);
 	registerExploreGuidance(pi, engineFor);
 
 	pi.on("session_start", async (_event, ctx) => {

package/extensions/explore/outline-injection.ts

@@ -0,0 +1,151 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Marker } from "@shanepadgett/tau-tui";
+import { BoundedTextResultBuilder } from "../../shared/bounded-text-result.ts";
+import {
+	registerOutlineInjectionProvider,
+	type OutlineInjectionDetails,
+	type PreparedOutlineInjection,
+} from "../../shared/outline-injection.ts";
+import type { TemporaryOutputStore } from "../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "./ast/engine.ts";
+import { formatOutlineEmpty, formatOutlineFile } from "./ast/format/outline.ts";
+import { outlinePath } from "./ast/queries/outline.ts";
+import { formatPathForDisplay, stripLeadingAt } from "./traverse.ts";
+
+const OPTIONS = { includePrivate: false, includeDocs: false, names: [] as readonly string[] };
+
+export function registerExploreOutlineInjection(
+	pi: ExtensionAPI,
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+): void {
+	registerOutlineInjectionProvider(pi, async (request) => {
+		const messages: PreparedOutlineInjection[] = [];
+		const warnings: string[] = [];
+		const engine = engineFor(request.cwd);
+		for (let index = 0; index < request.paths.length; index += 1) {
+			const path = stripLeadingAt(request.paths[index] ?? "");
+			assertCurrent(request.signal, request.isLifecycleCurrent);
+			try {
+				const abort = request.signal ?? new AbortController().signal;
+				const result = await outlinePath(engine, path, OPTIONS, abort);
+				if (result.mode !== "file") throw new Error("Working-memory outlines require a file path");
+				const body =
+					result.file.rows.length === 0
+						? formatOutlineEmpty(OPTIONS.names)
+						: formatOutlineFile(result.file, engine.cwd, false);
+				const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+				let content: string;
+				try {
+					await builder.appendBlock(
+						result.file.path,
+						formatPathForDisplay(result.file.path, engine.cwd),
+						`${path}\n${body}`,
+					);
+					assertCurrent(request.signal, request.isLifecycleCurrent);
+					content = (await builder.finish()).content;
+				} catch (error) {
+					await builder.abort();
+					throw error;
+				}
+				messages.push({
+					customType: "tau.explore.outline" as const,
+					content,
+					display: true as const,
+					details: {
+						v: 1 as const,
+						rowId: `${request.batchId}:${index}`,
+						path,
+						cwd: request.cwd,
+						batchId: request.batchId,
+					},
+				});
+			} catch (error) {
+				if (request.signal?.aborted || !request.isLifecycleCurrent()) throw error;
+				warnings.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return { messages, warnings };
+	});
+
+	pi.registerMessageRenderer<OutlineInjectionDetails>("tau.explore.outline", (message, options, theme) => {
+		const details = parseDetails(message.details);
+		if (!details) return undefined;
+		return new OutlineMessageComponent(
+			rowState,
+			details.rowId,
+			details.path,
+			typeof message.content === "string" ? message.content : "",
+			options.expanded,
+			theme,
+		);
+	});
+}
+
+function assertCurrent(signal: AbortSignal | undefined, isLifecycleCurrent: () => boolean): void {
+	signal?.throwIfAborted();
+	if (!isLifecycleCurrent()) throw new Error("Outline preparation crossed a session lifecycle boundary");
+}
+
+function parseDetails(value: unknown): OutlineInjectionDetails | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const details = value as Record<string, unknown>;
+	if (
+		details.v !== 1 ||
+		typeof details.rowId !== "string" ||
+		typeof details.path !== "string" ||
+		typeof details.cwd !== "string" ||
+		typeof details.batchId !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		v: 1,
+		rowId: details.rowId,
+		path: details.path,
+		cwd: details.cwd,
+		batchId: details.batchId,
+	};
+}
+
+class OutlineMessageComponent {
+	private readonly rowState: ToolRowStateStore;
+	private readonly rowId: string;
+	private readonly path: string;
+	private readonly content: string;
+	private readonly expanded: boolean;
+	private readonly theme: Theme;
+
+	constructor(
+		rowState: ToolRowStateStore,
+		rowId: string,
+		path: string,
+		content: string,
+		expanded: boolean,
+		theme: Theme,
+	) {
+		this.rowState = rowState;
+		this.rowId = rowId;
+		this.path = path;
+		this.content = content;
+		this.expanded = expanded;
+		this.theme = theme;
+		this.rowState.watch(this.rowId, () => this.invalidate());
+	}
+
+	render(width: number): string[] {
+		const marker = new Marker({
+			theme: this.theme,
+			state: this.rowState.get(this.rowId) === "pruned" ? "warning" : "complete",
+			label: "outline",
+			parts: [this.path],
+		}).render(width);
+		if (!this.expanded) return marker;
+		return [...marker, ...new Text(this.theme.fg("dim", this.content), 1, 0).render(width)];
+	}
+
+	invalidate(): void {}
+}

package/extensions/explore/settings.ts

@@ -10,7 +10,6 @@ export default defineTauExtensionSettings({
 		read: {
 			enabled: true as boolean,
 			structureThresholdLines: 200 as number,
-			maxRangeLines: 200 as number,
 		},
 	},
 	schema: Type.Object(
@@ -47,13 +46,6 @@ export default defineTauExtensionSettings({
 									"Registered source at or under this line count may be full-read. Above it, full read model-visible result is outline only.",
 							}),
 						),
-						maxRangeLines: Type.Optional(
-							Type.Integer({
-								default: 200,
-								minimum: 1,
-								description: "Maximum lines returned by one ranged read on registered source.",
-							}),
-						),
 					},
 					{ additionalProperties: false },
 				),

package/extensions/runtime-context/README.md

@@ -1,5 +1,5 @@
 # Runtime Context
 
-Supplies Tau with the current local date and an initial root directory snapshot as hidden session context. The snapshot remains fixed until the extension runtime restarts, while the date updates when the local day changes.
+Supplies Tau with current local date and initial root directory snapshot in each agent run's system prompt. Snapshot remains fixed until extension runtime restarts, while date updates when local day changes.
 
 After changing this extension, run `/reload` before testing the new behavior.

package/extensions/runtime-context/index.ts

@@ -1,22 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-	fingerprintRuntimeSnapshot,
-	formatLocalDateKey,
 	formatLocalDisplayDate,
 	formatRuntimeContextMessage,
 	freezeRuntimeContext,
 	type RuntimeContext,
 } from "./context.ts";
 
-const RUNTIME_CONTEXT_TYPE = "tau.runtime-context";
-
-interface RuntimeContextMessageDetails {
-	version: 1;
-	dateKey: string;
-	snapshotHash: string;
-	includesSnapshot: boolean;
-}
-
 export default function runtimeContextExtension(pi: ExtensionAPI): void {
 	let runtimeContext: RuntimeContext | undefined;
 
@@ -24,61 +13,9 @@ export default function runtimeContextExtension(pi: ExtensionAPI): void {
 		runtimeContext = freezeRuntimeContext(ctx.cwd);
 	});
 
-	pi.on("before_agent_start", (_event, ctx) => {
+	pi.on("before_agent_start", (event, ctx) => {
 		runtimeContext ??= freezeRuntimeContext(ctx.cwd);
-		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;
-		}
-
-		if (hasDate && hasSnapshot) return undefined;
-		const includeSnapshot = !hasSnapshot;
-		return {
-			message: {
-				customType: RUNTIME_CONTEXT_TYPE,
-				content: formatRuntimeContextMessage(
-					formatLocalDisplayDate(now),
-					includeSnapshot ? runtimeContext.rootSnapshot : undefined,
-				),
-				display: false,
-				details: {
-					version: 1,
-					dateKey,
-					snapshotHash,
-					includesSnapshot: includeSnapshot,
-				} satisfies RuntimeContextMessageDetails,
-			},
-		};
+		const content = formatRuntimeContextMessage(formatLocalDisplayDate(new Date()), runtimeContext.rootSnapshot);
+		return { systemPrompt: `${event.systemPrompt}\n\n${content}` };
 	});
 }
-
-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/subagent/agents/review.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Perform an adversarial, read-only review for correctness, runtime risks, duplication, and over- or under-engineering
+description: Perform a nuclear, architecture-first review for necessity, reuse, ownership, duplication, and simplification; runtime correctness is secondary
 tools:
   - read
   - bash
@@ -26,43 +26,50 @@ model: openai-codex/gpt-5.6-sol
 thinking: high
 ---
 
-Stay inside delegated change. Answer two questions:
+Stay centered on delegated change, but inspect enough surrounding code to find correct ownership and existing reuse. Every review is a nuclear review of codebase health. A caller may narrow changed behavior under review; it cannot reduce review to runtime correctness.
 
-1. Is runtime behavior correct?
-2. Is this the simplest implementation of requested behavior?
+Answer in this order:
 
-Find concrete failures or needless complexity. Report. Stop. No mutations, unrelated review, or broad concern inventory.
+1. Should this code exist? Is every added behavior requested and necessary?
+2. Does repository code, stdlib, platform, or an installed dependency already solve it?
+3. Is logic owned by right layer and fixed at shared root rather than patched at one symptom or caller?
+4. Does change leave codebase smaller and more coherent than other credible implementations?
+5. Is runtime behavior correct?
+
+Find concrete architectural damage, missed simplifications, and failures. Report. Stop. No mutations, unrelated repository archaeology, or broad concern inventory.
 
 ## Evidence ladder
 
-Use cheapest evidence that settles each question. Escalate only when answer could change verdict.
+Use cheapest evidence that settles each tier. Escalate only when answer could change verdict.
 
 1. **Supplied context** — Treat current line-numbered task files as authoritative this turn.
 2. **Paths and literals** — Use read-only `bash` (`ls`, `find`, `rg`/`grep`) for narrow path discovery, exact text, registrations, and unsupported formats. Use ranged `read` when formatting or source context matters.
-3. **Structure and reuse** — Default to `outline`. Use `discover` only when changed code may duplicate an existing repository API but name or path is unknown. Use `ast_search` for a concrete risky or duplicated source shape.
+3. **Structure, ownership, and reuse** — Default to `outline`. Use `discover` when changed code may duplicate an existing repository API but name or path is unknown. Use `ast_search` for a concrete duplicated shape, parallel concept, misplaced responsibility, or risky source shape.
 4. **Exact declarations** — Use `show` with path + name (+ line when needed). Retrieve only contract, body, imports, or nearby lines needed for verdict.
-5. **Runtime relationships** — Use `callers`, `callees`, `references`, or `implementations` after selecting a declaration. Use `deps`/`reverse_deps` for file imports. Use `impact` for full blast radius and `context` for one bounded declaration pack.
+5. **Relationships and runtime** — Use `callers`, `callees`, `references`, or `implementations` after selecting a declaration. Use `deps`/`reverse_deps` for file ownership and imports. Use `impact` for full blast radius and `context` for one bounded declaration pack.
 
 Keep roots and result limits narrow. Structural evidence proves bounded syntax, not dynamic dispatch. Preserve inferred and ambiguous labels.
 
 ## Review procedure
 
-1. Extract requested behavior, changed scope, and repository constraints from task and supplied files.
-2. Inspect changed declarations. Form only actionable runtime and simplicity questions.
-3. Runtime: follow shortest relevant path through callers, state transitions, boundaries, and error handling. Check realistic sequences, not theoretical branch inventory.
-4. Simplicity: identify wrappers, helpers, option bags, duplicated logic, or staged abstractions that can disappear without changing requested behavior. Report only material reductions in concepts or ownership.
-5. Inspect surrounding code only to confirm suspected failure, contract mismatch, missed caller, or existing simpler API.
-6. Stop when both questions have evidence-backed answers.
+Run every tier in order, even when caller asks only for runtime review:
+
+1. **Necessity and scope** — Extract requested behavior and repository constraints. Identify speculative behavior, bonus surfaces, configuration, or staging that can disappear.
+2. **Reuse** — Search for existing helpers, types, components, patterns, stdlib, platform features, and installed dependencies before accepting new code.
+3. **Ownership and architecture** — Check whether change belongs in current layer, fixes shared root, preserves one source of truth, and avoids parallel concepts. Follow callers and sibling paths when needed to detect a local symptom patch.
+4. **Codebase health** — Look for duplication, fragmented ownership, wrappers, option bags, helpers, files, types, and abstractions whose removal materially reduces concepts. Consider a focused refactor when local patch deepens bad structure.
+5. **Runtime correctness** — Spend remaining effort on shortest realistic path through state transitions, boundaries, error handling, and affected callers. Avoid theoretical branch inventory.
+6. Stop when every tier has enough evidence for verdict.
 
-Treat implementation as untrusted. Reject speculation, personal style preferences, and complexity complaints without concrete cost. Do not modify files.
+Treat every added concept as guilty until evidence justifies it. Reject speculation, personal style preferences, and architecture complaints without concrete ownership, maintenance, duplication, or change-cost impact. Do not modify files.
 
 ## Output
 
-List findings first, ordered by severity. Each finding needs:
+List architectural findings first, then runtime findings. Order each group by severity. Each finding needs:
 
 - severity and direct title;
 - exact file, line range, and declaration when one exists;
-- runtime failure mechanism or concrete complexity cost;
+- failure mechanism or concrete architectural cost;
 - smallest credible fix direction.
 
-Then list only unresolved questions that materially affect runtime correctness. No findings: say runtime appears correct and implementation is already simplest credible version. Briefly name inspected scope. No preamble, search log, broad summary, or repeated evidence.
+Then list only unresolved questions that materially affect verdict. No findings: say architecture, reuse, and scope look healthy, implementation is simplest credible version, and runtime appears correct. Briefly name inspected scope. No preamble, search log, broad summary, or repeated evidence.

package/extensions/subagent/agents/scout.md

@@ -16,6 +16,7 @@ tools:
   - implementations
   - impact
   - context
+  - working_memory
 names:
   - Pathfinder
   - Trailblazer
@@ -43,6 +44,15 @@ Use cheapest source that proves each claim. Skip steps when task supplies exact
 
 Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels. Do not turn ambiguous sites into claimed impact.
 
+## Exploration discipline
+
+- Narrow each call around one unanswered claim. Prefer structural summaries and signatures over full source, and batch only independent questions whose results stay small.
+- Let each result reduce the search space. Do not fan out across every plausible path, repeat evidence through another tool, or use tools merely to increase coverage.
+- Keep a short mental set of proven facts, live unknowns, and candidate paths. Drop rejected branches as soon as evidence rules them out.
+- During long or branching work, use `working_memory` when stale evidence would burden the next phase: after ruling out branches, after finishing a distinct phase, before switching to a materially different search, or when reminded to reassess.
+- At a checkpoint, keep decisive or expensive evidence, carry active file structure as outlines when bodies are no longer needed, and defer known paths only when a clear condition would make them relevant. Continuation should preserve task, proven constraints, live unknowns, and next search step.
+- Do not checkpoint a small search or prune coherent evidence still needed for the current line of reasoning.
+
 ## Search procedure
 
 1. Extract target, question, scope, and requested output shape.

package/extensions/tau-help/help.md

@@ -34,9 +34,9 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync (optional nudge). Escape cancels a running manual sync. When `sync.automation` is on, the coding agent can also run the `context-sync` subagent after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is the master switch for command, automation, and validation auto-run. Entry `files` are autoread; entry `anchors` are unloaded navigation paths. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
-## context-pruning
+## working-memory
 
-Gives the agent `context_prune` for creating a hard context checkpoint after broad exploration converges. Everything before the checkpoint leaves future model input unless the agent retains an exact tool exchange or carries a file forward as a fresh snapshot. File snapshot failures are reported without blocking the checkpoint. Deferred files remain as a small conditional note. Context markers use an ordered instruction ladder that escalates from informational guidance to pruning before further tool work. Run `/prune` with no arguments to request a checkpoint manually. Session history remains unchanged, and checkpoints, markers, and pruned-row state follow the active branch.
+Gives agent `working_memory` for selective hard checkpoints. Model-only references identify useful conversation evidence and complete tool exchanges. Requested source files return as structural outlines, while deferred files remain cheap conditional reminders. Everything else before checkpoint leaves future model input without changing saved session. Advisory reminders begin at 40k active-context tokens. Run `/prune` to request reassessment manually.
 
 ## explore
 

package/extensions/working-memory/README.md

@@ -0,0 +1,9 @@
+# Working Memory
+
+Working Memory gives agent selective checkpoints without changing saved conversation.
+
+`working_memory` keeps referenced conversation evidence and complete tool exchanges, carries requested source files as structural outlines, and records deferred files as conditional reminders. Everything else before checkpoint leaves future model context.
+
+Automatic reminders begin at 40,000 active-context tokens and remain advisory. Run `/prune` to request reassessment manually.
+
+Settings live under `extensions.workingMemory`.