@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/docs/subagents.md

@@ -83,7 +83,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` — find local files, symbols, data flow, constraints, and unknowns without changing anything
+- `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/appshot/README.md

@@ -1,6 +1,6 @@
 # Appshot
 
-Appshot gives Tau direct discovery and capture of macOS application windows. Tau can list visible windows as compact TOON with their application identity, title, process ID, bounds, and stable window ID; capture an exact window as a PNG for visual inspection; and bring an application forward when needed. Captures preserve aspect ratio and fit within 1568×1568 pixels to keep image payloads bounded.
+Appshot gives Tau direct discovery and capture of macOS application windows. Tau can list visible windows as compact JSON with their application identity, title, process ID, bounds, and stable window ID; capture an exact window as a PNG for visual inspection; and bring an application forward when needed. Captures preserve aspect ratio and fit within 1568×1568 pixels to keep image payloads bounded.
 
 The extension provides three tools:
 

package/extensions/appshot/index.ts

@@ -6,7 +6,6 @@ import {
 	type ExtensionAPI,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { encode } from "@toon-format/toon";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
@@ -86,20 +85,15 @@ function encodeWindowList(windows: WindowInfo[]): string {
 		height: window.bounds.height,
 	}));
 	const render = (count: number, omitted: number) =>
-		encode(omitted === 0 ? { windows: rows.slice(0, count) } : { windows: rows.slice(0, count), omitted }, {
-			indent: 1,
-		});
+		JSON.stringify(omitted === 0 ? { windows: rows.slice(0, count) } : { windows: rows.slice(0, count), omitted });
 	const fits = (value: string) =>
 		Buffer.byteLength(value, "utf8") <= DEFAULT_MAX_BYTES && value.split("\n").length <= DEFAULT_MAX_LINES;
-	const maximumRows = Math.max(0, DEFAULT_MAX_LINES - 2);
 
-	if (rows.length <= maximumRows) {
-		const full = render(rows.length, 0);
-		if (fits(full)) return full;
-	}
+	const full = render(rows.length, 0);
+	if (fits(full)) return full;
 
 	let low = 0;
-	let high = Math.min(rows.length, maximumRows);
+	let high = rows.length;
 	while (low < high) {
 		const middle = Math.ceil((low + high) / 2);
 		if (fits(render(middle, rows.length - middle))) low = middle;
@@ -116,7 +110,7 @@ function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
 			name: "list_windows",
 			label: "List Windows",
 			description:
-				"List visible normal macOS windows as compact TOON with window IDs, titles, application identity, process IDs, and bounds. Use list_windows to discover exact window IDs and application PIDs before screenshot_window or activate_app. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
+				"List visible normal macOS windows as compact JSON with window IDs, titles, application identity, process IDs, and bounds. Use list_windows to discover exact window IDs and application PIDs before screenshot_window or activate_app. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
 			parameters: listWindowsSchema,
 			async execute(_toolCallId, _params, signal) {
 				if (process.platform !== "darwin") throw new Error("list_windows is only available on macOS");

package/extensions/context/sync.ts

@@ -223,12 +223,4 @@ function changedCatalogPaths(before: Map<string, string>, after: Map<string, str
 }
 
 // Ensure evidence tool name stays aligned with agent definition tooling.
-export const CONTEXT_SYNC_REQUIRED_TOOLS = [
-	"read",
-	"ls",
-	"find",
-	"grep",
-	"bash",
-	"patch",
-	CONTEXT_SYNC_EVIDENCE_TOOL,
-] as const;
+export const CONTEXT_SYNC_REQUIRED_TOOLS = ["read", "bash", "patch", CONTEXT_SYNC_EVIDENCE_TOOL] as const;

package/extensions/context-pruning/README.md

@@ -20,7 +20,7 @@ Context Pruning does not impose a minimum token saving and does not reject a che
 
 ## Automatic and manual requests
 
-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.
+Tau checks active context size after tool-using turns and can send progressively stronger private instructions from `nudgeInstructions`. Hints occur at fixed token intervals rather than percentages of the model's context window. After a checkpoint, Tau suppresses boundaries already crossed by the resulting context and resumes at the next boundary. Branch navigation and compaction reconstruct that state from the active branch.
 
 Run `/prune` with no arguments to ask the agent to create a checkpoint and continue its task immediately.
 
@@ -35,5 +35,5 @@ Normal Pi compaction remains independent. When a compaction no longer includes a
 Settings live under `extensions.contextPruning` in Tau settings.
 
 - `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`.
+- `nudgeEveryTokens`: active-context interval between automatic hints. Defaults to `30000`, producing the default instruction ladder at 30k, 60k, and 90k tokens.
 - `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

@@ -15,11 +15,11 @@ import { createToolRowStateStore } from "../../shared/tool-row-state.ts";
 import { contextPruneParameters, executeContextPrune } from "./prune.ts";
 import { projectContext } from "./projection.ts";
 import {
-	parseContextPruningNudgeDetailsV2,
+	parseContextPruningNudgeDetailsV3,
 	renderContextPruneCall,
 	renderContextPruneResult,
 	renderContextPruningNudge,
-	type ContextPruningNudgeDetailsV2,
+	type ContextPruningNudgeDetailsV3,
 } from "./render.ts";
 import contextPruningSettings from "./settings.ts";
 
@@ -30,8 +30,8 @@ const NUDGE_BASELINE_ENTRY_TYPE = "tau.context-pruning.nudge-baseline";
 
 interface NudgeState {
 	anchorToolCallId: string | undefined;
-	growthBaselinePercent: number | undefined;
-	highestBoundary: number;
+	suppressedThroughTokens: number | undefined;
+	highestBoundaryTokens: number;
 	highestTier: number;
 	terminalTierReached: boolean;
 }
@@ -39,20 +39,20 @@ interface NudgeState {
 export default function contextPruningExtension(pi: ExtensionAPI): void {
 	let enabled = false;
 	let lifecycleGeneration = 0;
-	let nudgeEveryPercent = contextPruningSettings.defaults.nudgeEveryPercent;
+	let nudgeEveryTokens = contextPruningSettings.defaults.nudgeEveryTokens;
 	let nudgeInstructions = contextPruningSettings.defaults.nudgeInstructions;
 	let toolRegistered = false;
 	let commandRegistered = false;
 	let visualRows = new Set<string>();
 	let nudgeState: NudgeState = {
 		anchorToolCallId: undefined,
-		growthBaselinePercent: 0,
-		highestBoundary: 0,
+		suppressedThroughTokens: 0,
+		highestBoundaryTokens: 0,
 		highestTier: 0,
 		terminalTierReached: false,
 	};
 	const rowState = createToolRowStateStore(pi, "context-pruning.tool-row-state");
-	pi.registerMessageRenderer<ContextPruningNudgeDetailsV2>(NUDGE_MESSAGE_TYPE, (message, _options, theme) =>
+	pi.registerMessageRenderer<ContextPruningNudgeDetailsV3>(NUDGE_MESSAGE_TYPE, (message, _options, theme) =>
 		renderContextPruningNudge(message.details, theme),
 	);
 
@@ -98,7 +98,7 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 		const settings = await loadTauExtensionSettings(ctx, contextPruningSettings);
 		if (generation !== lifecycleGeneration) return;
 		enabled = settings.enabled;
-		nudgeEveryPercent = settings.nudgeEveryPercent;
+		nudgeEveryTokens = settings.nudgeEveryTokens;
 		nudgeInstructions = settings.nudgeInstructions;
 		setContextPruningEnabled(enabled);
 		if (enabled && !toolRegistered) {
@@ -162,22 +162,22 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 						commandContext.sessionManager.getBranch(),
 						true,
 					).latestAnchorToolCallId;
-					pi.sendMessage<ContextPruningNudgeDetailsV2>(
+					pi.sendMessage<ContextPruningNudgeDetailsV3>(
 						{
 							customType: NUDGE_MESSAGE_TYPE,
 							content: manualPruneSteeringMessage(),
 							display: true,
 							details: {
-								v: 2,
+								v: 3,
 								kind: "manual",
-								percent: null,
-								boundary: null,
+								tokens: null,
+								boundaryTokens: null,
 								reminder: null,
 								tier: null,
 								tierCount: null,
 								tierFloor: null,
 								anchorToolCallId: anchorToolCallId ?? null,
-								growthBaselinePercent: null,
+								suppressedThroughTokens: null,
 							},
 						},
 						{ deliverAs: "steer", triggerTurn: true },
@@ -204,8 +204,8 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 		visualRows.clear();
 		nudgeState = {
 			anchorToolCallId: undefined,
-			growthBaselinePercent: 0,
-			highestBoundary: 0,
+			suppressedThroughTokens: 0,
+			highestBoundaryTokens: 0,
 			highestTier: 0,
 			terminalTierReached: false,
 		};
@@ -216,45 +216,44 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 	pi.on("turn_end", (event, ctx) => {
 		if (!enabled || event.toolResults.length === 0) return undefined;
 		const usage = ctx.getContextUsage();
-		if (!usage || usage.percent === null || !Number.isFinite(usage.percent)) return undefined;
-		const rawPercent = Math.max(0, Math.min(100, usage.percent));
-		const percent = Math.floor(rawPercent);
+		if (!usage || usage.tokens === null || !Number.isFinite(usage.tokens)) return undefined;
+		const tokens = Math.max(0, Math.floor(usage.tokens));
 		const activeAnchor = replayContextPruningState(ctx.sessionManager.getBranch(), true).latestAnchorToolCallId;
 		if (activeAnchor !== nudgeState.anchorToolCallId) {
 			nudgeState = reconstructNudgeState(ctx.sessionManager.getBranch(), activeAnchor);
 		}
-		if (activeAnchor !== undefined && nudgeState.growthBaselinePercent === undefined) {
-			const baselinePercent = Math.ceil(rawPercent);
+		if (activeAnchor !== undefined && nudgeState.suppressedThroughTokens === undefined) {
+			const suppressedThroughTokens = Math.floor(tokens / nudgeEveryTokens) * nudgeEveryTokens;
 			pi.appendEntry(NUDGE_BASELINE_ENTRY_TYPE, {
-				v: 1,
+				v: 2,
 				anchorToolCallId: activeAnchor,
-				baselinePercent,
+				suppressedThroughTokens,
 			});
-			nudgeState.growthBaselinePercent = baselinePercent;
+			nudgeState.suppressedThroughTokens = suppressedThroughTokens;
+			nudgeState.highestBoundaryTokens = suppressedThroughTokens;
 			return undefined;
 		}
-		const baseline = nudgeState.growthBaselinePercent ?? 0;
-		const reminder = Math.floor((percent - baseline) / nudgeEveryPercent);
+		const reminder = Math.floor(tokens / nudgeEveryTokens);
 		if (reminder < 1) return undefined;
-		const boundary = baseline + reminder * nudgeEveryPercent;
-		if (boundary <= nudgeState.highestBoundary) return undefined;
+		const boundaryTokens = reminder * nudgeEveryTokens;
+		if (boundaryTokens <= nudgeState.highestBoundaryTokens) return undefined;
 		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,
+		const details: ContextPruningNudgeDetailsV3 = {
+			v: 3,
 			kind: "automatic",
-			percent,
-			boundary,
+			tokens,
+			boundaryTokens,
 			reminder,
 			tier,
 			tierCount,
 			tierFloor,
 			anchorToolCallId: activeAnchor ?? null,
-			growthBaselinePercent: baseline,
+			suppressedThroughTokens: nudgeState.suppressedThroughTokens ?? 0,
 		};
-		pi.sendMessage<ContextPruningNudgeDetailsV2>(
+		pi.sendMessage<ContextPruningNudgeDetailsV3>(
 			{
 				customType: NUDGE_MESSAGE_TYPE,
 				content: automaticPruneSteeringMessage(instruction, tier === tierCount),
@@ -263,7 +262,7 @@ export default function contextPruningExtension(pi: ExtensionAPI): void {
 			},
 			{ deliverAs: "steer" },
 		);
-		nudgeState.highestBoundary = boundary;
+		nudgeState.highestBoundaryTokens = boundaryTokens;
 		nudgeState.highestTier = Math.max(nudgeState.highestTier, tier);
 		nudgeState.terminalTierReached ||= tier === tierCount;
 		return undefined;
@@ -289,8 +288,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 suppressedThroughTokens = anchorToolCallId === undefined ? 0 : undefined;
+	let highestBoundaryTokens = 0;
 	let highestTier = 0;
 	let terminalTierReached = false;
 	let anchorResultIndex = -1;
@@ -310,65 +309,67 @@ function reconstructNudgeState(branch: readonly SessionEntry[], anchorToolCallId
 			const baseline = parseNudgeBaseline(entry.data);
 			if (
 				baseline &&
-				growthBaselinePercent === undefined &&
+				suppressedThroughTokens === undefined &&
 				index > anchorResultIndex &&
 				baseline.anchorToolCallId === anchorToolCallId
 			) {
-				growthBaselinePercent = baseline.baselinePercent;
+				suppressedThroughTokens = baseline.suppressedThroughTokens;
+				highestBoundaryTokens = baseline.suppressedThroughTokens;
 			}
 			continue;
 		}
 		if (entry.type !== "custom_message" || entry.customType !== NUDGE_MESSAGE_TYPE) continue;
-		const details = parseContextPruningNudgeDetailsV2(entry.details);
+		const details = parseContextPruningNudgeDetailsV3(entry.details);
 		if (
 			!details ||
 			details.kind !== "automatic" ||
 			index <= anchorResultIndex ||
 			details.anchorToolCallId !== (anchorToolCallId ?? null) ||
-			details.boundary === null ||
-			details.growthBaselinePercent === null ||
-			(growthBaselinePercent !== undefined && details.growthBaselinePercent !== growthBaselinePercent)
+			details.boundaryTokens === null ||
+			details.suppressedThroughTokens === null ||
+			(suppressedThroughTokens !== undefined && details.suppressedThroughTokens !== suppressedThroughTokens)
 		)
 			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);
+		if (details.boundaryTokens <= highestBoundaryTokens || details.tierFloor !== expectedTierFloor) continue;
+		highestBoundaryTokens = Math.max(highestBoundaryTokens, details.boundaryTokens);
 		highestTier = Math.max(highestTier, details.tier);
 		terminalTierReached ||= details.tier === details.tierCount;
-		growthBaselinePercent = details.growthBaselinePercent;
+		suppressedThroughTokens = details.suppressedThroughTokens;
 	}
-	return { anchorToolCallId, growthBaselinePercent, highestBoundary, highestTier, terminalTierReached };
+	return { anchorToolCallId, suppressedThroughTokens, highestBoundaryTokens, highestTier, terminalTierReached };
 }
 
-function parseNudgeBaseline(value: unknown): { v: 1; anchorToolCallId: string; baselinePercent: number } | undefined {
+function parseNudgeBaseline(
+	value: unknown,
+): { v: 2; anchorToolCallId: string; suppressedThroughTokens: number } | undefined {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
 	const record = value as Record<string, unknown>;
 	if (
 		Object.keys(record).length !== 3 ||
 		!Object.hasOwn(record, "v") ||
 		!Object.hasOwn(record, "anchorToolCallId") ||
-		!Object.hasOwn(record, "baselinePercent") ||
-		record.v !== 1 ||
+		!Object.hasOwn(record, "suppressedThroughTokens") ||
+		record.v !== 2 ||
 		typeof record.anchorToolCallId !== "string" ||
 		record.anchorToolCallId.length === 0 ||
-		typeof record.baselinePercent !== "number" ||
-		!Number.isInteger(record.baselinePercent) ||
-		record.baselinePercent < 0 ||
-		record.baselinePercent > 100
+		typeof record.suppressedThroughTokens !== "number" ||
+		!Number.isSafeInteger(record.suppressedThroughTokens) ||
+		record.suppressedThroughTokens < 0
 	)
 		return undefined;
 	return {
-		v: 1,
+		v: 2,
 		anchorToolCallId: record.anchorToolCallId,
-		baselinePercent: record.baselinePercent,
+		suppressedThroughTokens: record.suppressedThroughTokens,
 	};
 }
 
 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.";
+		"Internal context-management instruction. Follow it silently. Do not mention or acknowledge context-token counts, prune messages, or internal context management.";
 	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

package/extensions/context-pruning/prune.ts

@@ -2,8 +2,8 @@ import { resolve } from "node:path";
 import { type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import type { ContextPruneDeferredFileV2, ContextPruneDetailsV2 } from "../../shared/context-pruning-state.ts";
-import { prepareAutoreadMessage, type PreparedAutoreadMessage } from "../explore/autoread.ts";
-import { MAX_COMPLETE_FILE_SNAPSHOT_BYTES } from "../explore/full-file-knowledge.ts";
+import { prepareAutoreadMessage, type PreparedAutoreadMessage } from "../../shared/autoread.ts";
+import { MAX_COMPLETE_FILE_SNAPSHOT_BYTES } from "../../shared/full-file-knowledge.ts";
 
 export const contextPruneParameters = Type.Object(
 	{

package/extensions/context-pruning/render.ts

@@ -10,48 +10,48 @@ const MAX_EXPANDED_LINE_CHARACTERS = 240;
 const MAX_EXPANDED_TEXT_CHARACTERS = 3_000;
 const MAX_WARNING_CHARACTERS = 1_000;
 
-export type ContextPruningNudgeDetailsV2 =
+export type ContextPruningNudgeDetailsV3 =
 	| {
-			v: 2;
+			v: 3;
 			kind: "automatic";
-			percent: number;
-			boundary: number;
+			tokens: number;
+			boundaryTokens: number;
 			reminder: number;
 			tier: number;
 			tierCount: number;
 			tierFloor: number;
 			anchorToolCallId: string | null;
-			growthBaselinePercent: number;
+			suppressedThroughTokens: number;
 	  }
 	| {
-			v: 2;
+			v: 3;
 			kind: "manual";
-			percent: null;
-			boundary: null;
+			tokens: null;
+			boundaryTokens: null;
 			reminder: null;
 			tier: null;
 			tierCount: null;
 			tierFloor: null;
 			anchorToolCallId: string | null;
-			growthBaselinePercent: null;
+			suppressedThroughTokens: null;
 	  };
 
-export function parseContextPruningNudgeDetailsV2(value: unknown): ContextPruningNudgeDetailsV2 | undefined {
+export function parseContextPruningNudgeDetailsV3(value: unknown): ContextPruningNudgeDetailsV3 | undefined {
 	if (!isRecord(value)) return undefined;
 	const keys = [
 		"v",
 		"kind",
-		"percent",
-		"boundary",
+		"tokens",
+		"boundaryTokens",
 		"reminder",
 		"tier",
 		"tierCount",
 		"tierFloor",
 		"anchorToolCallId",
-		"growthBaselinePercent",
+		"suppressedThroughTokens",
 	];
 	if (Object.keys(value).length !== keys.length || !keys.every((key) => Object.hasOwn(value, key))) return undefined;
-	if (value.v !== 2 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
+	if (value.v !== 3 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
 	if (
 		value.anchorToolCallId !== null &&
 		(typeof value.anchorToolCallId !== "string" || value.anchorToolCallId.length === 0)
@@ -60,64 +60,69 @@ export function parseContextPruningNudgeDetailsV2(value: unknown): ContextPrunin
 	}
 	if (value.kind === "manual") {
 		if (
-			value.percent !== null ||
-			value.boundary !== null ||
+			value.tokens !== null ||
+			value.boundaryTokens !== null ||
 			value.reminder !== null ||
 			value.tier !== null ||
 			value.tierCount !== null ||
 			value.tierFloor !== null ||
-			value.growthBaselinePercent !== null
+			value.suppressedThroughTokens !== null
 		)
 			return undefined;
 		return {
-			v: 2,
+			v: 3,
 			kind: "manual",
-			percent: null,
-			boundary: null,
+			tokens: null,
+			boundaryTokens: null,
 			reminder: null,
 			tier: null,
 			tierCount: null,
 			tierFloor: null,
 			anchorToolCallId: value.anchorToolCallId,
-			growthBaselinePercent: null,
+			suppressedThroughTokens: null,
 		};
 	}
 	if (
-		!isPercent(value.percent) ||
-		!isBoundary(value.boundary) ||
+		!isTokenCount(value.tokens) ||
+		!isBoundary(value.boundaryTokens) ||
 		!isReminder(value.reminder) ||
 		!isTier(value.tier) ||
 		!isTier(value.tierCount) ||
 		!isTierFloor(value.tierFloor) ||
-		!isPercent(value.growthBaselinePercent) ||
-		value.boundary > value.percent ||
-		value.boundary <= value.growthBaselinePercent ||
+		!isTokenCount(value.suppressedThroughTokens) ||
+		value.boundaryTokens > value.tokens ||
+		value.boundaryTokens <= value.suppressedThroughTokens ||
 		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)
+		(value.anchorToolCallId === null && value.suppressedThroughTokens !== 0)
 	) {
 		return undefined;
 	}
-	const interval = (value.boundary - value.growthBaselinePercent) / value.reminder;
-	if (!Number.isInteger(interval) || interval < 1 || interval > 100 || value.percent - value.boundary >= interval)
+	const interval = value.boundaryTokens / value.reminder;
+	if (
+		!Number.isSafeInteger(interval) ||
+		interval < 1 ||
+		value.tokens - value.boundaryTokens >= interval ||
+		value.suppressedThroughTokens % interval !== 0
+	)
 		return undefined;
 	return {
-		v: 2,
+		v: 3,
 		kind: "automatic",
-		percent: value.percent,
-		boundary: value.boundary,
+		tokens: value.tokens,
+		boundaryTokens: value.boundaryTokens,
 		reminder: value.reminder,
 		tier: value.tier,
 		tierCount: value.tierCount,
 		tierFloor: value.tierFloor,
 		anchorToolCallId: value.anchorToolCallId,
-		growthBaselinePercent: value.growthBaselinePercent,
+		suppressedThroughTokens: value.suppressedThroughTokens,
 	};
 }
 
 export function renderContextPruningNudge(details: unknown, theme: Theme): Marker | undefined {
-	const parsed = parseContextPruningNudgeDetailsV2(details);
+	const parsed = parseContextPruningNudgeDetailsV3(details);
 	if (!parsed) return undefined;
 	return new Marker({
 		theme,
@@ -127,7 +132,7 @@ export function renderContextPruningNudge(details: unknown, theme: Theme): Marke
 			parsed.kind === "manual"
 				? ["Prune requested."]
 				: [
-						`${parsed.percent}%`,
+						formatTokens(parsed.tokens),
 						...(parsed.tier === parsed.tierCount ? ["Prune now."] : parsed.tier > 1 ? ["Prune soon."] : []),
 					],
 	});
@@ -214,16 +219,23 @@ function firstResultText(result: AgentToolResult<unknown>): string {
 	return "";
 }
 
-function isPercent(value: unknown): value is number {
-	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100;
+function formatTokens(count: number): string {
+	if (count < 1_000) return `${count}`;
+	if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1_000)}k`;
+	return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+function isTokenCount(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
 
 function isBoundary(value: unknown): value is number {
-	return isPercent(value) && value > 0;
+	return isTokenCount(value) && value > 0;
 }
 
 function isReminder(value: unknown): value is number {
-	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100;
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
 }
 
 function isTier(value: unknown): value is number {

package/extensions/context-pruning/settings.ts

@@ -11,18 +11,17 @@ export default defineTauExtensionSettings({
 	key: "contextPruning",
 	defaults: {
 		enabled: true as boolean,
-		nudgeEveryPercent: 20 as number,
+		nudgeEveryTokens: 30_000 as number,
 		nudgeInstructions: DEFAULT_NUDGE_INSTRUCTIONS,
 	},
 	schema: Type.Object(
 		{
 			enabled: Type.Optional(Type.Boolean({ default: true, description: "Enable context pruning." })),
-			nudgeEveryPercent: Type.Optional(
+			nudgeEveryTokens: Type.Optional(
 				Type.Integer({
-					default: 20,
+					default: 30_000,
 					minimum: 1,
-					maximum: 100,
-					description: "Context growth interval between automatic pruning hints.",
+					description: "Active-context token interval between automatic pruning hints.",
 				}),
 			),
 			nudgeInstructions: Type.Optional(

package/extensions/explore/README.md

@@ -1,21 +1,20 @@
 # Explore
 
-Explore is Tau's first-party filesystem exploration extension.
+Explore gives Tau 12 structural source tools: outlines, declaration slices, discovery, structural search, graph and relationship queries, impact, and context packs. Targets use path + declaration name, with an optional line to disambiguate.
 
-It exists so agents can inspect paths, discover files, search text, inspect declarations in supported source languages, and read exact source with compact model payloads and readable tool rows. Autoread establishes complete-file knowledge while that source remains in active context. Later reads can return an unchanged marker or a smaller diff instead of resending the file.
+Pi keeps ordinary filesystem tools (`ls`, `find`, `grep`, `read`). Explore adds structure on top of supported source languages via in-process tree-sitter (WASM) on every platform supported by the Node runtime. Registered languages share the same tools and exploration workflow.
 
-When the source baseline is no longer available, such as after compaction or a cold subagent resume, `read` safely returns the current full source.
+## Large `read` / autoread
 
-Agents invoke it with `ls`, `find`, `grep`, `outline`, `symbol`, and `read`. `outline` returns public declaration signatures and parenthesized numeric locators for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files. Markdown headings locate their complete sections. It also accepts a package directory, which inspects supported files directly inside it. Exact-name filters narrow the result, `includePrivate` exposes internal declarations, and `includeDocs` adds attached documentation comments when they are needed. Annotations and attributes remain in normal outlines. `symbol` accepts those numbers to retrieve several exact declarations in one call, can add bounded surrounding lines, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
+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.
 
-Installed packages support `outline` and `symbol` on Apple Silicon Macs. They include the worker, so users do not need Rust or Cargo. On other platforms, the rest of Explore remains available and AST tools report the platform limit when invoked.
+## Tools
 
-Use the cheapest useful step:
-
-1. Outline a package directory to discover its public API.
-2. Add exact names when likely declarations are known.
-3. Set `includePrivate` when implementation work needs internals.
-4. Set `includeDocs` when declaration documentation affects the task.
-5. Send several locators to `symbol` for complete declarations.
-6. Add context lines when the edit needs nearby source.
-7. Use ranged or whole-file `read` for cross-cutting logic, exact formatting, or parser gaps.
+- `outline` — declarations and structure for a file, one-level directory, or recursive subtree (no bodies).
+- `show` — exact signature / docs / declaration / declaration+imports for path+name targets.
+- `discover` — find reusable declarations across a repo/package/subtree by name, kind, or docs (signatures only).
+- `deps` / `reverse_deps` — file import graph forward and reverse.
+- `callers` / `callees` / `references` / `implementations` — symbol relationship sites.
+- `impact` — blast radius: symbol callees/callers plus file imports/importers/transitive dependents.
+- `context` — budgeted pack of bodies/signatures around one symbol.
+- `ast_search` — structural pattern search (ast-grep) over supported source.