@shanepadgett/tau-agent 0.20.1 → 0.21.0

package/extensions/context-pruning/render.ts

@@ -1,7 +1,7 @@
 import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { Marker } from "@shanepadgett/tau-tui";
-import { parseContextPruneDetailsV1 } from "../../shared/context-pruning-state.ts";
+import { parseContextPruneDetailsV2 } from "../../shared/context-pruning-state.ts";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.ts";
 import type { ContextPruneInput } from "./prune.ts";
 
@@ -10,22 +10,48 @@ const MAX_EXPANDED_LINE_CHARACTERS = 240;
 const MAX_EXPANDED_TEXT_CHARACTERS = 3_000;
 const MAX_WARNING_CHARACTERS = 1_000;
 
-export interface ContextPruningNudgeDetailsV1 {
-	v: 1;
-	kind: "automatic" | "manual";
-	percent: number | null;
-	boundary: number | null;
-	pressure: boolean;
-	anchorToolCallId: string | null;
-	growthBaselinePercent: number | null;
-}
+export type ContextPruningNudgeDetailsV2 =
+	| {
+			v: 2;
+			kind: "automatic";
+			percent: number;
+			boundary: number;
+			reminder: number;
+			tier: number;
+			tierCount: number;
+			tierFloor: number;
+			anchorToolCallId: string | null;
+			growthBaselinePercent: number;
+	  }
+	| {
+			v: 2;
+			kind: "manual";
+			percent: null;
+			boundary: null;
+			reminder: null;
+			tier: null;
+			tierCount: null;
+			tierFloor: null;
+			anchorToolCallId: string | null;
+			growthBaselinePercent: null;
+	  };
 
-export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPruningNudgeDetailsV1 | undefined {
+export function parseContextPruningNudgeDetailsV2(value: unknown): ContextPruningNudgeDetailsV2 | undefined {
 	if (!isRecord(value)) return undefined;
-	const keys = ["v", "kind", "percent", "boundary", "pressure", "anchorToolCallId", "growthBaselinePercent"];
+	const keys = [
+		"v",
+		"kind",
+		"percent",
+		"boundary",
+		"reminder",
+		"tier",
+		"tierCount",
+		"tierFloor",
+		"anchorToolCallId",
+		"growthBaselinePercent",
+	];
 	if (Object.keys(value).length !== keys.length || !keys.every((key) => Object.hasOwn(value, key))) return undefined;
-	if (value.v !== 1 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
-	if (typeof value.pressure !== "boolean") return undefined;
+	if (value.v !== 2 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
 	if (
 		value.anchorToolCallId !== null &&
 		(typeof value.anchorToolCallId !== "string" || value.anchorToolCallId.length === 0)
@@ -33,14 +59,25 @@ export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPrunin
 		return undefined;
 	}
 	if (value.kind === "manual") {
-		if (value.percent !== null || value.boundary !== null || value.growthBaselinePercent !== null || value.pressure)
+		if (
+			value.percent !== null ||
+			value.boundary !== null ||
+			value.reminder !== null ||
+			value.tier !== null ||
+			value.tierCount !== null ||
+			value.tierFloor !== null ||
+			value.growthBaselinePercent !== null
+		)
 			return undefined;
 		return {
-			v: 1,
+			v: 2,
 			kind: "manual",
 			percent: null,
 			boundary: null,
-			pressure: false,
+			reminder: null,
+			tier: null,
+			tierCount: null,
+			tierFloor: null,
 			anchorToolCallId: value.anchorToolCallId,
 			growthBaselinePercent: null,
 		};
@@ -48,25 +85,39 @@ export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPrunin
 	if (
 		!isPercent(value.percent) ||
 		!isBoundary(value.boundary) ||
+		!isReminder(value.reminder) ||
+		!isTier(value.tier) ||
+		!isTier(value.tierCount) ||
+		!isTierFloor(value.tierFloor) ||
 		!isPercent(value.growthBaselinePercent) ||
 		value.boundary > value.percent ||
-		value.growthBaselinePercent > value.percent
+		value.boundary <= value.growthBaselinePercent ||
+		value.tier > value.tierCount ||
+		value.tierFloor > value.tierCount ||
+		value.tier !== Math.max(Math.min(value.reminder, value.tierCount), value.tierFloor) ||
+		(value.anchorToolCallId === null && value.growthBaselinePercent !== 0)
 	) {
 		return undefined;
 	}
+	const interval = (value.boundary - value.growthBaselinePercent) / value.reminder;
+	if (!Number.isInteger(interval) || interval < 1 || interval > 100 || value.percent - value.boundary >= interval)
+		return undefined;
 	return {
-		v: 1,
+		v: 2,
 		kind: "automatic",
 		percent: value.percent,
 		boundary: value.boundary,
-		pressure: value.pressure,
+		reminder: value.reminder,
+		tier: value.tier,
+		tierCount: value.tierCount,
+		tierFloor: value.tierFloor,
 		anchorToolCallId: value.anchorToolCallId,
 		growthBaselinePercent: value.growthBaselinePercent,
 	};
 }
 
 export function renderContextPruningNudge(details: unknown, theme: Theme): Marker | undefined {
-	const parsed = parseContextPruningNudgeDetailsV1(details);
+	const parsed = parseContextPruningNudgeDetailsV2(details);
 	if (!parsed) return undefined;
 	return new Marker({
 		theme,
@@ -75,7 +126,14 @@ export function renderContextPruningNudge(details: unknown, theme: Theme): Marke
 		parts:
 			parsed.kind === "manual"
 				? ["Prune requested."]
-				: [`${parsed.percent}%`, ...(parsed.pressure ? ["Prune suggested."] : [])],
+				: [
+						`${parsed.percent}%`,
+						...(parsed.tier === parsed.tierCount
+							? ["Prune now."]
+							: parsed.tier > 1
+								? ["Prune soon."]
+								: []),
+					],
 	});
 }
 
@@ -108,7 +166,7 @@ export function renderContextPruneResult(
 	lastComponent: unknown,
 ): Text {
 	const component = lastComponent instanceof Text ? lastComponent : new Text("", 0, 0);
-	const details = parseContextPruneDetailsV1(result.details);
+	const details = parseContextPruneDetailsV2(result.details);
 	if (!details) {
 		component.setText(
 			theme.fg(
@@ -118,27 +176,21 @@ export function renderContextPruneResult(
 		);
 		return component;
 	}
-	if (details.status === "skipped") {
-		component.setText(
-			theme.fg("warning", boundedText(firstResultText(result) || "Prune skipped", MAX_WARNING_CHARACTERS)),
-		);
-		return component;
-	}
-
-	const pruned = details.newlyPrunedToolCallIds.length + details.newlyPrunedAutoreadRowIds.length;
+	const pruned = details.prunedToolCallIds.length + details.prunedAutoreadRowIds.length;
 	const retained = details.retainedToolCallIds.length + details.retainedAutoreadRowIds.length;
 	let text = theme.fg(
-		"success",
-		`Pruned ${pruned} · retained ${retained} · refreshed ${details.refreshedFiles.length} · deferred ${details.deferredFiles.length}`,
+		details.warnings.length === 0 ? "success" : "warning",
+		`Checkpoint · pruned ${pruned} · retained ${retained} · refreshed ${details.refreshedFiles.length} · deferred ${details.deferredFiles.length}${details.warnings.length === 0 ? "" : ` · warnings ${details.warnings.length}`}`,
 	);
 	if (expanded) {
 		const lines = [
-			...details.newlyPrunedToolCallIds.map((id) => `pruned tool: ${id}`),
-			...details.newlyPrunedAutoreadRowIds.map((id) => `pruned autoread: ${id}`),
+			...details.prunedToolCallIds.map((id) => `pruned tool: ${id}`),
+			...details.prunedAutoreadRowIds.map((id) => `pruned autoread: ${id}`),
 			...details.retainedToolCallIds.map((id) => `retained tool: ${id}`),
 			...details.retainedAutoreadRowIds.map((id) => `retained autoread: ${id}`),
 			...details.refreshedFiles.map((file) => `refreshed: ${file.path} (${file.rowId})`),
 			...details.deferredFiles.map((file) => `deferred: ${file.path} — ${file.reason}; when ${file.relevantWhen}`),
+			...details.warnings.map((warning) => `warning: ${warning}`),
 		];
 		const shown = lines.slice(0, MAX_EXPANDED_ITEMS).map((line) => boundedText(line, MAX_EXPANDED_LINE_CHARACTERS));
 		if (lines.length > shown.length) shown.push(`… ${lines.length - shown.length} more`);
@@ -174,6 +226,18 @@ function isBoundary(value: unknown): value is number {
 	return isPercent(value) && value > 0;
 }
 
+function isReminder(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100;
+}
+
+function isTier(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 5;
+}
+
+function isTierFloor(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 5;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/extensions/context-pruning/settings.ts

@@ -1,13 +1,18 @@
 import { Type } from "typebox";
 import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
 
+const DEFAULT_NUDGE_INSTRUCTIONS: [string, ...string[]] = [
+	"No prune is required yet unless broad exploration has converged or substantial evidence is already irrelevant. Continue coherent work.",
+	"Move toward a pruning point now. Finish the current coherent step, then prune before starting another broad exploration. Managed context is materially increasing model cost.",
+	"Prune now before further tool work. Continuing with stale managed context is wasting money.",
+];
+
 export default defineTauExtensionSettings({
 	key: "contextPruning",
 	defaults: {
 		enabled: true as boolean,
 		nudgeEveryPercent: 20 as number,
-		pressurePercent: 50 as number,
-		minimumReclaimTokens: 8000 as number,
+		nudgeInstructions: DEFAULT_NUDGE_INSTRUCTIONS,
 	},
 	schema: Type.Object(
 		{
@@ -20,19 +25,13 @@ export default defineTauExtensionSettings({
 					description: "Context growth interval between automatic pruning hints.",
 				}),
 			),
-			pressurePercent: Type.Optional(
-				Type.Integer({
-					default: 50,
-					minimum: 1,
-					maximum: 99,
-					description: "Context usage above which pruning hints become urgent.",
-				}),
-			),
-			minimumReclaimTokens: Type.Optional(
-				Type.Integer({
-					default: 8000,
-					minimum: 1,
-					description: "Minimum estimated tokens a prune must reclaim.",
+			nudgeInstructions: Type.Optional(
+				Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), {
+					default: DEFAULT_NUDGE_INSTRUCTIONS,
+					minItems: 1,
+					maxItems: 5,
+					description:
+						"Ordered automatic pruning instructions. Later reminders repeat the final instruction, and the final tier requires an anchor before further tool work.",
 				}),
 			),
 		},

package/extensions/explore/read-cache.ts

@@ -67,6 +67,7 @@ export function createReadCacheStore(): ReadCacheStore {
 			}
 			const pruning = replayContextPruningState(manager.getBranch());
 			const ignoredRowIds = new Set([...pruning.prunedToolCallIds, ...pruning.prunedAutoreadRowIds]);
+			for (const id of pruning.retainedToolCallIds) ignoredRowIds.delete(id);
 			const state = replayReadCache(manager.buildContextEntries(), ctx.cwd, ignoredRowIds);
 			const trust = state.scopeTrust.get(pathKey)?.get(scopeKey);
 			return {
@@ -127,17 +128,21 @@ export function replayReadCache(
 		if (entry.type === "message" && "message" in entry) message = entry.message;
 		else if (entry.type === "custom_message") message = entry;
 		else continue;
-		const parsedMeta = readMetaFromMessage(message);
-		if (parsedMeta) {
-			const rowId = readRowId(message);
-			if (rowId && ignoredRowIds.has(rowId)) continue;
+		const candidates = carriedFileMessages(message);
+		let acceptedCarryForward = false;
+		for (const candidate of candidates ?? [message]) {
+			const parsedMeta = readMetaFromMessage(candidate);
+			if (!parsedMeta) continue;
+			acceptedCarryForward = true;
+			const candidateRowId = readRowId(candidate);
+			if (candidateRowId && ignoredRowIds.has(candidateRowId)) continue;
 			const pathKey = resolve(cwd, parsedMeta.pathKey);
 			const meta = pathKey === parsedMeta.pathKey ? parsedMeta : { ...parsedMeta, pathKey };
-			if (rowId && applyReadMeta(trust, failedPatchRecoveryPaths, message, meta, rowId)) {
+			if (candidateRowId && applyReadMeta(trust, failedPatchRecoveryPaths, candidate, meta, candidateRowId)) {
 				const acceptedTrust = trust.get(meta.pathKey)?.get(meta.scopeKey);
 				if (acceptedTrust) {
 					acceptedRows.push({
-						rowId,
+						rowId: candidateRowId,
 						pathKey: meta.pathKey,
 						scopeKey: meta.scopeKey,
 						meta,
@@ -145,8 +150,8 @@ export function replayReadCache(
 					});
 				}
 			}
-			continue;
 		}
+		if (acceptedCarryForward) continue;
 		for (const path of failedPatchPaths(message, cwd)) failedPatchRecoveryPaths.add(path);
 	}
 	const completeFileChains = new Map<string, CompleteFileDependencyChain>();
@@ -163,6 +168,25 @@ export function replayReadCache(
 	return { scopeTrust: trust, acceptedRows, completeFileChains, failedPatchRecoveryPaths };
 }
 
+function carriedFileMessages(message: unknown): unknown[] | undefined {
+	if (!isRecord(message) || message.role !== "toolResult" || message.toolName !== "context_prune") return undefined;
+	if (!isRecord(message.details) || message.details.v !== 2 || !Array.isArray(message.details.refreshedFiles)) {
+		return undefined;
+	}
+	if (!Array.isArray(message.content)) {
+		return undefined;
+	}
+	const messages: unknown[] = [];
+	for (let index = 0; index < message.details.refreshedFiles.length; index += 1) {
+		const file = message.details.refreshedFiles[index];
+		const part = message.content[index + 1];
+		if (!isRecord(file) || !isRecord(file.autoreadDetails)) continue;
+		if (!isRecord(part) || part.type !== "text" || typeof part.text !== "string") continue;
+		messages.push({ customType: "tau.autoread", content: part.text, details: file.autoreadDetails });
+	}
+	return messages;
+}
+
 function applyReadMeta(
 	trust: Map<string, Map<string, ReadCacheScopeTrust>>,
 	failedPatchRecoveryPaths: Set<string>,

package/extensions/handoff/README.md

@@ -0,0 +1,7 @@
+# Handoff
+
+Start a fresh chat from an idea already understood in the current conversation.
+
+Run `/handoff <goal for the new chat>`. Tau generates a focused opening prompt, starts a new linked session, and asks Tau autoread to preload the relevant project files selected from the current context. The prompt stays in the editor so you can review or change it before submitting.
+
+The original session remains available through Pi's session history. Press Escape while Tau generates the handoff to cancel.

package/extensions/handoff/index.ts

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import {
+	BorderedLoader,
+	buildSessionContext,
+	convertToLlm,
+	type ExtensionAPI,
+	serializeConversation,
+} from "@earendil-works/pi-coding-agent";
+import { prepareAutoreadMessage, type AutoreadDetails } from "../explore/autoread.ts";
+import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { errorText } from "../../shared/text.ts";
+import { buildHandoffRequest, type HandoffDraft, handoffDraftFromToolInput, HANDOFF_TOOL } from "./model.ts";
+
+export default function handoffExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("handoff", {
+		description: "Start a fresh chat with a generated prompt and autoread files",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/handoff requires TUI mode.", "error");
+				return;
+			}
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for the new chat>", "error");
+				return;
+			}
+			await ctx.waitForIdle();
+			const model = ctx.model;
+			if (!model) {
+				ctx.ui.notify("No model selected.", "error");
+				return;
+			}
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+			if (!currentSessionFile) {
+				ctx.ui.notify("The current session must be persisted before handoff.", "error");
+				return;
+			}
+			const messages = buildSessionContext(
+				ctx.sessionManager.getEntries(),
+				ctx.sessionManager.getLeafId(),
+			).messages;
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation context to hand off.", "error");
+				return;
+			}
+
+			let generationError: string | undefined;
+			const draft = await ctx.ui.custom<HandoffDraft | null>((tui, theme, _keys, done) => {
+				const loader = new BorderedLoader(tui, theme, "Generating handoff");
+				loader.onAbort = () => done(null);
+				void (async () => {
+					try {
+						const thinking = pi.getThinkingLevel();
+						const candidates = await resolveCandidates(
+							ctx,
+							[{ provider: model.provider, model: model.id, reasoning: thinking === "off" ? undefined : thinking }],
+							false,
+						);
+						const conversation = serializeConversation(convertToLlm(messages));
+						const result = await generateToolValidated(
+							{ ui: ctx.ui, signal: loader.signal },
+							candidates,
+							buildHandoffRequest(conversation, goal, ctx.cwd),
+							HANDOFF_TOOL,
+							handoffDraftFromToolInput,
+							(error, output) =>
+								[
+									`The handoff failed validation: ${error.message}`,
+									`Call ${HANDOFF_TOOL.name} again with corrected arguments only.`,
+									"Previous response:",
+									output,
+								].join("\n"),
+							{ maxAttempts: 3 },
+						);
+						done(result);
+					} catch (error) {
+						if (!loader.signal.aborted) generationError = errorText(error);
+						done(null);
+					}
+				})();
+				return loader;
+			});
+
+			if (!draft) {
+				ctx.ui.notify(generationError ? `Handoff failed: ${generationError}` : "Handoff cancelled.", generationError ? "error" : "info");
+				return;
+			}
+
+			const batchId = randomUUID();
+			const cwd = ctx.cwd;
+			const result = await ctx.newSession({
+				parentSession: currentSessionFile,
+				setup: async (sessionManager) => {
+					const messages = await Promise.all(
+						draft.files.map(async (path, index) => {
+							const details = {
+								rowId: `${batchId}:${index}`,
+								path,
+								cwd,
+								source: "handoff",
+								batchId,
+							};
+							try {
+								return await prepareAutoreadMessage({
+									...details,
+									signal: undefined,
+									isLifecycleCurrent: () => true,
+								});
+							} catch (error) {
+								const message = errorText(error);
+								return {
+									customType: "tau.autoread" as const,
+									content: `${path}\nAutoread failed: ${message}`,
+									display: true as const,
+									details: { ...details, status: "failed", error: message } satisfies AutoreadDetails,
+								};
+							}
+						}),
+					);
+					for (const message of messages) {
+						sessionManager.appendCustomMessageEntry(
+							message.customType,
+							message.content,
+							message.display,
+							message.details,
+						);
+					}
+				},
+				withSession: async (replacementCtx) => {
+					replacementCtx.ui.setEditorText(draft.prompt);
+					replacementCtx.ui.notify("Handoff ready. Review the draft and submit when ready.", "info");
+				},
+			});
+			if (result.cancelled) {
+				ctx.ui.notify("New session cancelled.", "info");
+			}
+		},
+	});
+}

package/extensions/handoff/model.ts

@@ -0,0 +1,71 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import { posix } from "node:path";
+import { Type } from "typebox";
+
+export interface HandoffDraft {
+	prompt: string;
+	files: string[];
+}
+
+export const HANDOFF_TOOL = {
+	name: "submit_handoff",
+	description: "Submit the prompt and project files for the new chat. This is the only allowed response.",
+	parameters: Type.Object(
+		{
+			prompt: Type.String({ description: "Self-contained opening prompt for the new chat" }),
+			files: Type.Array(
+				Type.String({ description: "Project-relative file path already known from the current conversation" }),
+				{ description: "Focused files Tau should autoread in the new chat" },
+			),
+		},
+		{ additionalProperties: false },
+	),
+} satisfies Tool;
+
+export function buildHandoffRequest(conversation: string, goal: string, cwd: string): string {
+	return [
+		"You prepare a handoff from the current coding chat into a fresh chat.",
+		`Call ${HANDOFF_TOOL.name} exactly once. Write no prose outside the tool call.`,
+		"",
+		"Build the handoff only from the supplied conversation and goal. Do not research, invent findings, or assume file contents that are absent from the conversation.",
+		"The prompt must give the new agent the relevant decisions, progress, constraints, unresolved questions, and exact next task.",
+		"Keep it focused. The selected files will be autoread separately, so summarize why they matter without copying their contents into the prompt.",
+		`Every file must be a path under ${cwd}, relative to that directory, and must already be known from the conversation. Return only files relevant to the goal.`,
+		"Return an empty files array when no known file is clearly relevant.",
+		"",
+		"## Handoff goal",
+		goal,
+		"",
+		"## Current effective conversation",
+		conversation,
+	].join("\n");
+}
+
+export function handoffDraftFromToolInput(input: unknown): HandoffDraft {
+	if (!input || typeof input !== "object") throw new Error("Handoff output must be an object.");
+	const record = input as Record<string, unknown>;
+	if (typeof record.prompt !== "string" || !record.prompt.trim()) {
+		throw new Error("Handoff prompt must be a non-empty string.");
+	}
+	if (!Array.isArray(record.files) || !record.files.every((path) => typeof path === "string")) {
+		throw new Error("Handoff files must be an array of strings.");
+	}
+
+	const files: string[] = [];
+	for (const rawPath of record.files) {
+		const path = posix.normalize(rawPath.trim().replace(/^@/, "").replace(/^\.\//, ""));
+		if (
+			path === "." ||
+			path.startsWith("/") ||
+			/^[a-z]:\//i.test(path) ||
+			path === ".." ||
+			path.startsWith("../") ||
+			path.includes("\\")
+		) {
+			throw new Error(`Handoff file must be a project-relative path: ${rawPath}`);
+		}
+		if (!files.includes(path)) files.push(path);
+	}
+
+	return { prompt: record.prompt.trim(), files };
+}

package/extensions/subagent/index.ts

@@ -145,7 +145,9 @@ Start a fresh thread with \`agent\` and \`task\`. Continue an existing thread wi
 
 Pass \`files\` when exact relevant files are already known. Tau autoreads current line-numbered snapshots into that child turn before it starts.
 
-Delegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
+Delegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.
+
+Review limit: for one user task or coherent implementation batch, call the \`review\` agent at most twice. The first call is the initial review. The only permitted second call is a follow-up in the same retained thread to check fixes from that initial review. Never call \`review\` a third time for the same task. Do not call it for documentation-only work, trivial edits, small localized changes, or micro-adjustments after review; inspect and test those directly.`;
 		return { systemPrompt: `${event.systemPrompt}\n\n${prompt}` };
 	});
 	pi.registerTool(

package/extensions/tau-help/help.md

@@ -36,7 +36,7 @@ Adds `/context` to select reusable repository work scopes from `.pi/contexts`, a
 
 ## context-pruning
 
-Gives the agent `context_prune` for removing substantial stale tool evidence after broad exploration converges. The agent records durable conclusions before creating an anchor, can retain exact exchanges or current file knowledge, and continues the task automatically. Context markers occasionally steer the agent after tool-heavy growth and become more direct under pressure. Run `/prune` with no arguments to request an anchor manually. Session history remains unchanged, and anchors, markers, and pruned-row state follow the active branch.
+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.
 
 ## explore
 
@@ -46,6 +46,10 @@ Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `fi
 
 Adds `/footer` to toggle and refresh Tau’s status footer.
 
+## handoff
+
+Adds `/handoff <goal>` to start a fresh linked session from the current conversation. Tau generates an opening prompt, autoreads the relevant project files it already knows about, and leaves the prompt in the editor for review instead of submitting it.
+
 ## ideas
 
 Adds `/ideas` to log rough ideas or open the ideas browser.

package/package.json

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

package/schemas/tau.schema.json

@@ -68,18 +68,21 @@
 							"maximum": 100,
 							"description": "Context growth interval between automatic pruning hints."
 						},
-						"pressurePercent": {
-							"type": "integer",
-							"default": 50,
-							"minimum": 1,
-							"maximum": 99,
-							"description": "Context usage above which pruning hints become urgent."
-						},
-						"minimumReclaimTokens": {
-							"type": "integer",
-							"default": 8000,
-							"minimum": 1,
-							"description": "Minimum estimated tokens a prune must reclaim."
+						"nudgeInstructions": {
+							"type": "array",
+							"items": {
+								"type": "string",
+								"minLength": 1,
+								"maxLength": 2000
+							},
+							"default": [
+								"No prune is required yet unless broad exploration has converged or substantial evidence is already irrelevant. Continue coherent work.",
+								"Move toward a pruning point now. Finish the current coherent step, then prune before starting another broad exploration. Managed context is materially increasing model cost.",
+								"Prune now before further tool work. Continuing with stale managed context is wasting money."
+							],
+							"minItems": 1,
+							"maxItems": 5,
+							"description": "Ordered automatic pruning instructions. Later reminders repeat the final instruction, and the final tier requires an anchor before further tool work."
 						}
 					},
 					"additionalProperties": false