@shanepadgett/tau-agent 0.20.2 → 0.22.0

package/README.md

@@ -2,6 +2,8 @@
 
 Tau is a custom agentic harness built with Pi extensions: tools, commands, prompts, skills, and themes.
 
+The package also exports programmatic Tau capabilities for trusted Pi extensions. The built-in extensions and public API use the same underlying operations.
+
 ## Install
 
 ```bash
@@ -13,6 +15,22 @@ pi install ./path/to/tau-agent
 pi install ./path/to/tau-agent/packages/agent
 ```
 
+## Programmatic use
+
+Install the package in the extension's project, then import from its root:
+
+```ts
+import { generateImage } from "@shanepadgett/tau-agent";
+
+const image = await generateImage(ctx, {
+  prompt: "A quiet mountain lake",
+  path: "assets/lake.png",
+  signal,
+});
+```
+
+See [Extending Tau Agent](./docs/extending-tau-agent.md) for the supported API.
+
 ## Development
 
 From the monorepo root:

package/docs/extending-tau-agent.md

@@ -1,8 +1,40 @@
 # Extending Tau Agent
 
-Tau Agent is a Pi extension harness. External integration uses Pi's native `pi.events` bus.
+Tau Agent is a Pi extension harness and a programmatic API for trusted Pi extensions.
 
-The caller and Tau Agent must be loaded in the same Pi runtime. External callers use string channel names and documented payloads. They do not import Tau Agent internals.
+Install `@shanepadgett/tau-agent` as a dependency when calling its API. Import only from the package root. Files under `extensions/` and other package paths are private.
+
+## Image generation
+
+`generateImage()` runs the same image-generation pipeline as Tau's `image_gen` tool without opening UI, injecting messages, or starting an agent turn.
+
+```ts
+import { generateImage } from "@shanepadgett/tau-agent";
+
+const result = await generateImage(ctx, {
+  prompt: "A stone archway at sunrise",
+  provider: "openai",
+  path: candidatePath,
+  referencedImagePaths: [perspectivePath, palettePath],
+  signal,
+});
+```
+
+The context must provide `cwd`, `model`, and `modelRegistry`; Pi's `ExtensionContext` and `ExtensionCommandContext` already do. Relative destination and reference paths resolve from `ctx.cwd`.
+
+Fields:
+
+- `prompt`: complete non-empty image prompt.
+- `provider`: optional `"openai"` or `"xai"` override. Without one, Tau follows the active model and falls back when authentication is unavailable.
+- `path`: optional destination. Tau uses its external image store when omitted and never overwrites an explicit destination.
+- `referencedImagePaths`: optional list of up to three local PNG, JPEG, or WebP files. Supplying references selects image editing or composition.
+- `signal`: optional cancellation signal.
+
+The promise resolves after publication with the generated bytes, absolute path, provider, model, operation, MIME type, width, and height. The bytes are the same bytes written to `result.path`, so callers can attach the image without reopening the file. Failures reject with a bounded, sanitized error. Cancellation before publication rejects with the signal's abort reason and removes staged files.
+
+## Events
+
+External event integration uses Pi's native `pi.events` bus. The caller and Tau Agent must be loaded in the same Pi runtime. Event callers use string channel names and documented payloads. They do not import Tau Agent internals.
 
 Only events documented in this file are public. Extensions run trusted in-process; event emitters can ask Tau Agent to do work.
 

package/extensions/context-pruning/README.md

@@ -1,135 +1,39 @@
 # Context Pruning
 
-Context Pruning removes old tool calls and their results from the messages sent to the model. It does not delete them from the saved conversation. Branch switching, transcript review, and normal Pi compaction still see the original records.
+Context Pruning gives the agent direct control over its future model context. It does not delete or rewrite the saved conversation.
 
-The feature can also remove old full-file autoread messages and old private reasoning. User messages, visible assistant prose, branch summaries, compaction summaries, shell records, and unrelated custom messages remain.
+`context_prune` creates a hard checkpoint. Everything before that checkpoint leaves future model input unless the agent explicitly carries it forward. Messages after the checkpoint remain unchanged.
 
-## The important distinction
+Before calling the tool, the agent writes visible prose containing the durable conclusions, user constraints, conditional relevance, and next action that must survive. That prose is part of the checkpoint turn.
 
-Context usage and pruning are separate decisions.
+## Selections
 
-- The context percentage decides when Tau gives the agent a pruning hint.
-- A `context_prune` call decides what old evidence the agent wants to remove or retain.
-- Tau then checks whether that exact removal is safe and whether it saves enough tokens.
+The tool accepts three required lists:
 
-Being at 70% context does not force Tau to apply a prune. With the default settings, 70% is high enough for a pressure hint, but every prune still has to pass the checks below.
+- `keepToolCalls` retains exact earlier tool exchanges by tool-call ID. Parallel calls remain independently selectable: retaining one call does not retain its siblings.
+- `keepFiles` reads each selected file from disk and carries its complete current contents forward as a fresh autoread snapshot. It does not require an earlier complete read.
+- `deferFiles` carries forward a short advisory note explaining why a file is irrelevant now and when to reconsider it.
 
-## What happens when the agent calls `context_prune`
+Duplicate selections are collapsed. A file selected in both `keepFiles` and `deferFiles` is kept. Missing, unreadable, or otherwise unsnapshotable files produce warnings in the successful tool result; they do not block the checkpoint or other file snapshots.
 
-The agent supplies three required lists:
+Context Pruning does not impose a minimum token saving and does not reject a checkpoint because old context has unusual bookkeeping. Pi supplies the current provider context. Tau removes unretained tool calls and their matching results with the same ID, drops other pre-checkpoint messages, and leaves the checkpoint turn and later messages intact.
 
-- `keepFiles`: files whose complete current contents must remain available.
-- `keepToolCalls`: exact earlier tool calls and results that must remain available.
-- `deferFiles`: files that are currently irrelevant but may matter under a stated condition.
+## Automatic and manual requests
 
-Unless retained by one of the first two lists, every complete earlier tool exchange and every autoread currently eligible for pruning is selected for removal. The current `context_prune` call is the anchor: later messages and tool results are unaffected by that anchor.
+Tau checks context growth after tool-using turns and can send progressively stronger private instructions from `nudgeInstructions`. Growth is measured from the first tool-using turn after the latest checkpoint. Branch navigation and compaction reconstruct that baseline from the active branch.
 
-The agent is instructed to put durable conclusions, conditional information, and its next action in visible prose immediately before the call. That prose survives pruning. Tau enforces that `context_prune` is the only tool call in its assistant message, but it does not judge whether the preceding prose is complete or useful.
-
-Tau prepares the result without changing the active context. It estimates the token count before and after the proposed removal, including any replacement file contents and deferred-file note. It applies the prune only when the estimated saving is at least `minimumReclaimTokens`.
-
-After a successful call, Tau removes the selected evidence from future model input. The saved conversation remains unchanged. The tool result records exactly which tool exchanges and autoreads were removed, retained, or refreshed.
-
-## Why a prune is skipped
-
-A skipped prune removes nothing and publishes no deferred-file note or replacement file contents. Tau skips when any of these checks fails:
-
-1. Context Pruning is disabled.
-2. Tau does not have a usable copy of the exact messages most recently sent to the model.
-3. The `context_prune` call is missing from the active branch.
-4. Another tool call appears beside `context_prune` in the same assistant message.
-5. The current model input contains duplicate, mismatched, or orphaned tool records that Tau cannot safely remove. An unmatched call from an explicitly aborted assistant response is discarded and does not block pruning.
-6. A retained tool-call ID is duplicated, missing, or is not a complete exchange in the current model input.
-7. Two selected file paths resolve to the same file, including aliases and symbolic links across `keepFiles` and `deferFiles`.
-8. A retained file does not have an earlier complete-file read, has malformed read evidence, cannot currently be read as UTF-8, or exceeds the 1 MiB complete-file limit.
-9. The estimated saving is below `minimumReclaimTokens`.
-
-Cancellation, a session lifecycle change during preparation, and failures while publishing an already prepared prune are reported as tool failures rather than skipped prunes.
-
-### “The latest provider-context projection is unavailable”
-
-This error uses an internal term. In plain language, Tau did not have a usable copy of the exact message list the model had just received.
-
-Tau normally saves that list while Pi prepares a model turn. Tau clears it on session start, branch changes, compaction, and shutdown. It also refuses to save a list with invalid tool-call/result pairing. If the list is missing or belongs to an earlier session state, `context_prune` stops before checking the agent’s selections or estimating savings.
-
-Pi can save an aborted assistant response that requested a tool but never received a result. Tau discards that abandoned call when preparing later model input. Other unmatched calls and results still fail validation because Tau cannot prove whether their evidence is incomplete.
-
-For example, a row that says `context_prune 29 selections` followed by this error means:
-
-- the agent supplied 29 items across the three selection lists;
-- Tau did not inspect or apply those selections;
-- no old tool calls were removed;
-- the context percentage did not cause the rejection;
-- the current implementation does not reconstruct the missing list during that call.
-
-The response tells the agent not to retry immediately because repeated calls in the same state would usually fail for the same reason. A later model turn should normally give Tau a new list. Repeated occurrences indicate a feature defect or a session history that Tau cannot safely process.
-
-## Retaining files
-
-`keepFiles` preserves complete current file knowledge, not necessarily the original read row.
-
-Each selected file must have been read completely earlier in the current model input. A partial read is insufficient. Tau then reads the file from disk again and chooses the cheaper valid representation:
-
-- Keep an existing complete snapshot when it still matches the file.
-- Keep a baseline plus later read diffs when that chain reconstructs the current file and costs no more than a fresh snapshot.
-- Add one fresh complete snapshot when the earlier evidence is stale, broken, or more expensive.
-
-The entire prune is skipped if any selected file fails. Every retained file must currently exist, be valid UTF-8, and fit within the 1 MiB complete-file snapshot limit. Read the complete file before selecting it for retention.
-
-Paths are resolved from the session working directory. Paths outside it are stored as absolute paths. Existing symbolic links and other aliases are resolved before duplicate checks.
-
-The required `relevance` text explains the agent’s selection. It does not loosen any validation rule.
-
-## Retaining tool exchanges
-
-`keepToolCalls` retains both sides of an earlier exchange: the assistant’s tool call and the matching tool result. The ID must occur exactly once, the tool names must match, and the result must follow the call.
-
-Retention is exact. Selecting one call does not retain nearby calls from the same assistant message. Tau can remove one parallel tool exchange while keeping another, then removes the empty assistant message if no content remains.
-
-The required `relevance` text explains why the exchange matters. Tau does not use that text to infer additional exchanges to retain.
-
-## Deferring files
-
-`deferFiles` does not read or preserve file contents. It adds a hidden advisory note telling the model why each file was deferred and when to reconsider it. The latest successful anchor replaces the previous deferred-file list.
-
-A deferred path may be missing. It still participates in canonical path and duplicate checks. Its `reason` and `relevantWhen` text are passed to the model as written.
-
-## Automatic hints
-
-Tau checks context usage only after a turn that produced at least one tool result. It emits at most one marker for the strongest newly crossed boundary.
-
-With the defaults:
-
-- `nudgeEveryPercent: 20` allows markers after enough context growth to cross 20% intervals.
-- `pressurePercent: 50` makes a marker a pressure hint only when raw usage is greater than 50%.
-
-Below the pressure threshold, the hidden instruction says no prune is required unless broad exploration has converged or substantial evidence is already irrelevant. Above it, the instruction asks the agent to finish the current coherent step and prune when the projected saving is substantial. A hint never calls the tool or bypasses its checks.
-
-After a successful prune, the first later tool-using turn records a new usage baseline and emits no automatic marker. Tau waits for context usage to grow by another `nudgeEveryPercent` from that baseline. The baseline and crossed boundaries are stored with the active branch so compaction and branch navigation do not immediately repeat hints.
-
-The visible marker is compact. The full instruction stays hidden, and the agent is told not to discuss internal context management.
-
-## Manual requests
-
-Run `/prune` with no arguments to ask the agent to create an anchor and continue unfinished work. The command starts an agent turn immediately. It does not force a successful prune or bypass file, tool-pairing, current-message, lifecycle, or minimum-savings checks.
-
-Extra arguments produce `Usage: /prune`. When Context Pruning is disabled, the command reports that state and does not start a prune turn.
-
-Asking the agent to prune in ordinary chat has the same execution boundaries once it calls `context_prune`.
+Run `/prune` with no arguments to ask the agent to create a checkpoint and continue its task immediately.
 
 ## Branches, compaction, and display
 
-Applied anchors belong to the active session branch. Switching branches rebuilds the removed-evidence set, deferred-file list, automatic-hint baseline, and warning-colored rows from that branch’s valid tool results. A skipped or malformed prune result does not become an anchor.
-
-Context Pruning does not cancel or replace Pi’s manual, threshold, or overflow compaction. Compaction clears Tau’s saved model-input list; Tau must receive another model-input event before a later prune can use it.
+Checkpoints belong to the active branch. Switching branches rebuilds the latest checkpoint, deferred-file state, automatic-hint baseline, and warning-colored pruned rows from that branch.
 
-Tau-owned tool rows and autoreads turn warning-colored when their evidence has been pruned. Native Pi rows and fallback rows that do not use Tau’s row-state renderer do not change color. Their evidence is still removed from model input.
+Normal Pi compaction remains independent. When a compaction no longer includes an old checkpoint turn, that checkpoint has nothing left to filter.
 
 ## Settings
 
 Settings live under `extensions.contextPruning` in Tau settings.
 
-- `enabled`: enables the tool, `/prune`, automatic markers, branch replay, context filtering, and pruned-row display. Defaults to `true`.
-- `nudgeEveryPercent`: integer context-growth interval between automatic hints. Allowed range: `1` through `100`. Defaults to `20`.
-- `pressurePercent`: integer usage percentage above which hints use pressure wording. Allowed range: `1` through `99`. Defaults to `50`.
-- `minimumReclaimTokens`: positive integer minimum estimated saving required to apply a prune. Defaults to `8000`.
+- `enabled`: enables the tool, `/prune`, projection, markers, and branch replay. Defaults to `true`.
+- `nudgeEveryPercent`: context-growth interval between automatic hints, from `1` through `100`. Defaults to `20`.
+- `nudgeInstructions`: ordered list of one through five nonempty instructions. Later reminders repeat the final instruction. Defaults to three escalating instructions.

package/extensions/context-pruning/index.ts

@@ -1,6 +1,5 @@
 import {
 	defineTool,
-	type ContextEvent,
 	type ExtensionAPI,
 	type ExtensionContext,
 	type SessionEntry,
@@ -8,7 +7,7 @@ import {
 import {
 	replayContextPruningState,
 	setContextPruningEnabled,
-	type ContextPruneDetailsV1,
+	type ContextPruneDetailsV2,
 } from "../../shared/context-pruning-state.ts";
 import { emitTauEvent, onTauEvent } from "../../shared/events.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
@@ -16,23 +15,16 @@ import { createToolRowStateStore } from "../../shared/tool-row-state.ts";
 import { contextPruneParameters, executeContextPrune } from "./prune.ts";
 import { projectContext } from "./projection.ts";
 import {
-	parseContextPruningNudgeDetailsV1,
+	parseContextPruningNudgeDetailsV2,
 	renderContextPruneCall,
 	renderContextPruneResult,
 	renderContextPruningNudge,
-	type ContextPruningNudgeDetailsV1,
+	type ContextPruningNudgeDetailsV2,
 } from "./render.ts";
 import contextPruningSettings from "./settings.ts";
 
-interface ProjectionCache {
-	generation: number;
-	input: ContextEvent["messages"];
-	stateKey: string;
-	messages: ContextEvent["messages"];
-}
-
 const TOOL_DESCRIPTION =
-	"Create a context anchor after broad exploration converges, after a context-pressure nudge, or when substantial irrelevant tool evidence has accumulated. Do not use after routine tool batches or when expected savings are small. Immediately before calling, state retained conclusions, conditional relevance, and the next action in visible prose. Call context_prune alone in its tool batch.";
+	"Create a hard context checkpoint after broad exploration converges, when a context-pruning nudge directs it, or when stale evidence has accumulated. Everything before the checkpoint is removed from future model context unless selected for retention. Immediately before calling, state durable conclusions, conditional relevance, and the next action in visible prose.";
 const NUDGE_MESSAGE_TYPE = "tau.context-pruning.nudge";
 const NUDGE_BASELINE_ENTRY_TYPE = "tau.context-pruning.nudge-baseline";
 
@@ -40,15 +32,15 @@ interface NudgeState {
 	anchorToolCallId: string | undefined;
 	growthBaselinePercent: number | undefined;
 	highestBoundary: number;
+	highestTier: number;
+	terminalTierReached: boolean;
 }
 
 export default function contextPruningExtension(pi: ExtensionAPI): void {
 	let enabled = false;
 	let lifecycleGeneration = 0;
-	let projectionCache: ProjectionCache | undefined;
-	let minimumReclaimTokens = contextPruningSettings.defaults.minimumReclaimTokens;
 	let nudgeEveryPercent = contextPruningSettings.defaults.nudgeEveryPercent;
-	let pressurePercent = contextPruningSettings.defaults.pressurePercent;
+	let nudgeInstructions = contextPruningSettings.defaults.nudgeInstructions;
 	let toolRegistered = false;
 	let commandRegistered = false;
 	let visualRows = new Set<string>();
@@ -56,9 +48,11 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 		anchorToolCallId: undefined,
 		growthBaselinePercent: 0,
 		highestBoundary: 0,
+		highestTier: 0,
+		terminalTierReached: false,
 	};
 	const rowState = createToolRowStateStore(pi, "context-pruning.tool-row-state");
-	pi.registerMessageRenderer<ContextPruningNudgeDetailsV1>(NUDGE_MESSAGE_TYPE, (message, _options, theme) =>
+	pi.registerMessageRenderer<ContextPruningNudgeDetailsV2>(NUDGE_MESSAGE_TYPE, (message, _options, theme) =>
 		renderContextPruningNudge(message.details, theme),
 	);
 
@@ -76,7 +70,6 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 
 	const clearEphemeralState = () => {
 		lifecycleGeneration += 1;
-		projectionCache = undefined;
 	};
 	const setContextPruneToolActive = (active: boolean) => {
 		if (!toolRegistered) return;
@@ -105,37 +98,32 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 		const settings = await loadTauExtensionSettings(ctx, contextPruningSettings);
 		if (generation !== lifecycleGeneration) return;
 		enabled = settings.enabled;
-		minimumReclaimTokens = settings.minimumReclaimTokens;
 		nudgeEveryPercent = settings.nudgeEveryPercent;
-		pressurePercent = settings.pressurePercent;
+		nudgeInstructions = settings.nudgeInstructions;
 		setContextPruningEnabled(enabled);
 		if (enabled && !toolRegistered) {
 			pi.registerTool(
-				defineTool<typeof contextPruneParameters, ContextPruneDetailsV1>({
+				defineTool<typeof contextPruneParameters, ContextPruneDetailsV2>({
 					name: "context_prune",
 					label: "context_prune",
 					description: TOOL_DESCRIPTION,
 					promptSnippet:
 						"Prune substantial stale tool evidence after stating durable conclusions and the next action",
 					promptGuidelines: [
-						"Use context_prune after broad exploration converges, after a context-pressure nudge, or when substantial irrelevant evidence has accumulated.",
-						"Do not use context_prune after routine tool batches or when expected savings are small.",
-						"Immediately before context_prune, write visible prose with retained conclusions, conditional relevance, and the next action, then call context_prune alone in its tool batch.",
+						"Use context_prune after broad exploration converges, when a context-pruning nudge directs it, or when substantial irrelevant evidence has accumulated.",
+						"A final-tier context-pruning nudge means preserve durable conclusions and prune before further tool work.",
+						"Everything before context_prune leaves future model context unless selected in keepFiles or keepToolCalls, so preserve durable conclusions, user constraints, conditional relevance, and the next action in visible prose immediately before calling it.",
 					],
 					parameters: contextPruneParameters,
 					executionMode: "sequential",
 					async execute(toolCallId, params, signal, _onUpdate, executionContext) {
-						const cache = projectionCache;
 						return executeContextPrune({
-							pi,
 							toolCallId,
 							params,
 							signal,
 							ctx: executionContext,
-							projection: cache && { generation: cache.generation, messages: cache.messages },
+							generation: lifecycleGeneration,
 							currentGeneration: () => lifecycleGeneration,
-							currentEnabled: () => enabled,
-							minimumReclaimTokens,
 						});
 					},
 					renderCall(args, theme, context) {
@@ -170,17 +158,20 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 						commandContext.sessionManager.getBranch(),
 						true,
 					).latestAnchorToolCallId;
-					pi.sendMessage<ContextPruningNudgeDetailsV1>(
+					pi.sendMessage<ContextPruningNudgeDetailsV2>(
 						{
 							customType: NUDGE_MESSAGE_TYPE,
 							content: manualPruneSteeringMessage(),
 							display: true,
 							details: {
-								v: 1,
+								v: 2,
 								kind: "manual",
 								percent: null,
 								boundary: null,
-								pressure: false,
+								reminder: null,
+								tier: null,
+								tierCount: null,
+								tierFloor: null,
 								anchorToolCallId: anchorToolCallId ?? null,
 								growthBaselinePercent: null,
 							},
@@ -207,7 +198,13 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 		enabled = false;
 		setContextPruneToolActive(false);
 		visualRows.clear();
-		nudgeState = { anchorToolCallId: undefined, growthBaselinePercent: 0, highestBoundary: 0 };
+		nudgeState = {
+			anchorToolCallId: undefined,
+			growthBaselinePercent: 0,
+			highestBoundary: 0,
+			highestTier: 0,
+			terminalTierReached: false,
+		};
 		setContextPruningEnabled(false);
 		pushVisualSnapshot();
 	});
@@ -233,61 +230,51 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 			return undefined;
 		}
 		const baseline = nudgeState.growthBaselinePercent ?? 0;
-		if (percent - baseline < nudgeEveryPercent) return undefined;
-		const boundary = Math.floor(percent / nudgeEveryPercent) * nudgeEveryPercent;
+		const reminder = Math.floor((percent - baseline) / nudgeEveryPercent);
+		if (reminder < 1) return undefined;
+		const boundary = baseline + reminder * nudgeEveryPercent;
 		if (boundary <= nudgeState.highestBoundary) return undefined;
-		const pressure = rawPercent > pressurePercent;
-		const details: ContextPruningNudgeDetailsV1 = {
-			v: 1,
+		const tierCount = nudgeInstructions.length;
+		const tierFloor = nudgeState.terminalTierReached ? tierCount : Math.min(nudgeState.highestTier, tierCount);
+		const tier = Math.max(Math.min(reminder, tierCount), tierFloor);
+		const instruction = nudgeInstructions[tier - 1] ?? nudgeInstructions[0];
+		const details: ContextPruningNudgeDetailsV2 = {
+			v: 2,
 			kind: "automatic",
 			percent,
 			boundary,
-			pressure,
+			reminder,
+			tier,
+			tierCount,
+			tierFloor,
 			anchorToolCallId: activeAnchor ?? null,
 			growthBaselinePercent: baseline,
 		};
-		pi.sendMessage<ContextPruningNudgeDetailsV1>(
+		pi.sendMessage<ContextPruningNudgeDetailsV2>(
 			{
 				customType: NUDGE_MESSAGE_TYPE,
-				content: automaticPruneSteeringMessage(pressure),
+				content: automaticPruneSteeringMessage(instruction, tier === tierCount),
 				display: true,
 				details,
 			},
 			{ deliverAs: "steer" },
 		);
 		nudgeState.highestBoundary = boundary;
+		nudgeState.highestTier = Math.max(nudgeState.highestTier, tier);
+		nudgeState.terminalTierReached ||= tier === tierCount;
 		return undefined;
 	});
 
 	pi.on("context", (event, ctx) => {
 		if (!enabled) return undefined;
 		const state = replayContextPruningState(ctx.sessionManager.getBranch(), true);
-		const stateKey = JSON.stringify([
-			state.latestAnchorToolCallId,
-			[...state.prunedToolCallIds],
-			[...state.prunedAutoreadRowIds],
-		]);
-		if (
-			projectionCache?.generation === lifecycleGeneration &&
-			projectionCache.input === event.messages &&
-			projectionCache.stateKey === stateKey
-		) {
-			return { messages: projectionCache.messages };
-		}
-
-		try {
-			const messages = projectContext(event.messages, state);
-			projectionCache = { generation: lifecycleGeneration, input: event.messages, stateKey, messages };
-			const nextRows = new Set([...state.prunedToolCallIds, ...state.prunedAutoreadRowIds]);
-			if (!setsEqual(visualRows, nextRows)) {
-				visualRows = nextRows;
-				pushVisualSnapshot();
-			}
-			return { messages };
-		} catch {
-			projectionCache = undefined;
-			return undefined;
+		const messages = projectContext(event.messages, state);
+		const nextRows = new Set([...state.prunedToolCallIds, ...state.prunedAutoreadRowIds]);
+		if (!setsEqual(visualRows, nextRows)) {
+			visualRows = nextRows;
+			pushVisualSnapshot();
 		}
+		return { messages };
 	});
 }
 
@@ -300,6 +287,8 @@ function setsEqual(left: ReadonlySet<string>, right: ReadonlySet<string>): boole
 function reconstructNudgeState(branch: readonly SessionEntry[], anchorToolCallId: string | undefined): NudgeState {
 	let growthBaselinePercent = anchorToolCallId === undefined ? 0 : undefined;
 	let highestBoundary = 0;
+	let highestTier = 0;
+	let terminalTierReached = false;
 	let anchorResultIndex = -1;
 	if (anchorToolCallId !== undefined) {
 		anchorResultIndex = branch.findIndex(
@@ -326,19 +315,27 @@ function reconstructNudgeState(branch: readonly SessionEntry[], anchorToolCallId
 			continue;
 		}
 		if (entry.type !== "custom_message" || entry.customType !== NUDGE_MESSAGE_TYPE) continue;
-		const details = parseContextPruningNudgeDetailsV1(entry.details);
+		const details = parseContextPruningNudgeDetailsV2(entry.details);
 		if (
 			!details ||
 			details.kind !== "automatic" ||
+			index <= anchorResultIndex ||
 			details.anchorToolCallId !== (anchorToolCallId ?? null) ||
 			details.boundary === null ||
-			details.growthBaselinePercent === null
+			details.growthBaselinePercent === null ||
+			(growthBaselinePercent !== undefined && details.growthBaselinePercent !== growthBaselinePercent)
 		)
 			continue;
+		const expectedTierFloor: number = terminalTierReached
+			? details.tierCount
+			: Math.min(highestTier, details.tierCount);
+		if (details.boundary <= highestBoundary || details.tierFloor !== expectedTierFloor) continue;
 		highestBoundary = Math.max(highestBoundary, details.boundary);
+		highestTier = Math.max(highestTier, details.tier);
+		terminalTierReached ||= details.tier === details.tierCount;
 		growthBaselinePercent = details.growthBaselinePercent;
 	}
-	return { anchorToolCallId, growthBaselinePercent, highestBoundary };
+	return { anchorToolCallId, growthBaselinePercent, highestBoundary, highestTier, terminalTierReached };
 }
 
 function parseNudgeBaseline(value: unknown): { v: 1; anchorToolCallId: string; baselinePercent: number } | undefined {
@@ -365,15 +362,16 @@ function parseNudgeBaseline(value: unknown): { v: 1; anchorToolCallId: string; b
 	};
 }
 
-function automaticPruneSteeringMessage(pressure: boolean): string {
+function automaticPruneSteeringMessage(instruction: string, finalTier: boolean): string {
 	const silent =
 		"Internal context-management instruction. Follow it silently. Do not mention or acknowledge context percentages, prune messages, or internal context management.";
-	if (pressure) {
-		return `${silent} Finish the current coherent step. When projected savings are substantial, preserve durable conclusions and the next action in visible prose, then call context_prune alone. Do not prune after a routine tool batch or retry immediately after a skipped prune.`;
-	}
-	return `${silent} No prune is required unless broad exploration has converged or substantial evidence is already irrelevant. Continue coherent work. If pruning becomes worthwhile, preserve durable conclusions and the next action in visible prose, then call context_prune alone.`;
+	const protocol =
+		"When pruning, first preserve durable conclusions, user constraints, conditional relevance, and the next action in visible prose, then call context_prune.";
+	return finalTier
+		? `${silent} ${instruction} This is the final reminder tier. Create a context anchor before further tool work. ${protocol}`
+		: `${silent} ${instruction} ${protocol}`;
 }
 
 function manualPruneSteeringMessage(): string {
-	return "Internal context-management instruction. Follow it silently without mentioning this request. Create a context anchor with context_prune, then continue unfinished work. First preserve durable conclusions, conditional relevance, and the next action in visible prose. Call context_prune alone. If projected savings are too small, continue work without immediately retrying.";
+	return "Internal context-management instruction. Follow it silently without mentioning this request. Create a hard context checkpoint with context_prune, then continue unfinished work. First preserve durable conclusions, user constraints, conditional relevance, and the next action in visible prose.";
 }