@shanepadgett/tau-agent 0.26.0 → 0.27.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-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/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,28 @@
 # Explore
 
+Locator edit tools (`replace_declaration`, `replace_body`, `insert_declaration`, and `rename_declaration`) consume numeric declaration locators and reject stale or parser-recovered targets. They validate candidate syntax before writing, invalidate old locators, and return fresh locators after a clean reparse. For Markdown headings, `replace_declaration` replaces the complete section and `replace_body` preserves the heading while replacing its contents. Nested replacement headings must stay below the selected heading depth. Markdown insertion and rename remain unavailable. Code rename requires an explicit file or repository scope. Inferred references change only with approval; ambiguous references stay unchanged and are reported.
+
 Explore is Tau's first-party filesystem exploration extension.
 
-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.
+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. For configured supported source, the official `read` tool requires a current structural attempt for that exact file fingerprint. Direct file outlines and searches qualify, along with files returned by `symbol`, `api_discover`, structural search, and relationship tools. Markdown is ungated by default. Unsupported files and unavailable workers keep the ordinary read path. 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. A successful Tau patch can return a trusted cached complete-file diff without another structural attempt when the current branch still contains the prior complete-file baseline and the resulting fingerprint matches.
 
 When the source baseline is no longer available, such as after compaction or a cold subagent resume, `read` safely returns the current full source.
 
-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.
+Agents invoke it with `ls`, `find`, `grep`, `api_discover`, `ast_search`, `outline`, `symbol`, `references`, `callers`, `callees`, `implementations`, `tests`, and `read`. The five relationship tools expand a declaration locator across a repository or subtree. Every result reports exact source location, syntactic relationship, exact/inferred/ambiguous certainty, production/test/generated/re-export classification, declaration candidates, and a numeric locator for the nearest complete editable scope. Ambiguous results are marked non-actionable. Scans stay bounded, deterministic, ignore-aware, and cancellable. `ast_search` finds code shapes with ast-grep patterns across one supported source file, repository, package, or subtree. Directory searches require an explicit language; supported files can infer it. Results include exact previews, metavariable bindings, parser uncertainty, numeric locators for matches and enclosing scopes, complete scan counts, and explicit result or traversal limits. Output stays bounded and complete overflow is saved to the active session temporary store. `api_discover` searches declarations across a repository, package, or subtree by exact, prefix, substring, bounded fuzzy, declaration-kind, or documentation query. It filters public, private, source-exported, or package-surface declarations and reports defining files separately from caller access for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, and Swift. Caller access includes the canonical module path, exact import statement, usable access expression, and resolution uncertainty; TypeScript results also include re-export chains. Candidates contain signatures without implementation bodies and numeric locators accepted by `symbol`. `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 accepts a package directory for one-level inspection, or `recursive: true` for ignore-aware mixed-language orientation of a repository or subtree. Recursive output stays bounded; when the complete outline is larger, Tau saves it to a temporary path for targeted `grep` and ranged `read` during the active session. 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 in four views: `signature` omits documentation and bodies, `signatureWithDocs` adds attached documentation without the body, `declaration` returns exact declaration source, and `declarationWithImports` adds required imports. It retrieves several locators in one call, can add bounded surrounding lines to exact declarations, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
+
+Explore scans a bounded, ignore-aware slice of the working root before each agent run. When the repository contains supported source and the selected native worker is usable, Explore adds language-specific AST-first guidance to the agent prompt. Unsupported repositories and hosts get the ordinary filesystem workflow. `api_discover`, `outline`, and `symbol` stay registered either way.
+
+Installed packages support `api_discover`, `ast_search`, `outline`, `symbol`, and the relationship tools 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.
 
-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.
+For supported source, use the cheapest useful step:
 
-Use the cheapest useful step:
+1. Identify the current job: locate, reuse, edit, explain, or debug. Avoid loading implementation, callers, tests, or documentation needed only later.
+2. Use a recursive `outline` to orient an unfamiliar repository or subtree. Outline a known package or file directly. Outline large Markdown files before retrieving a relevant heading section.
+3. Use `api_discover` when reuse intent is known but the declaration path or exact name is not. Prefer package surfaces and public exports before private declarations.
+4. Narrow paths, exact names, query work, and result limits once the likely target is known. Enable `includePrivate` only for targeted implementation work.
+5. Stop at a clear outline or API candidate signature. Use `symbol(signature)` for closer contract inspection, `signatureWithDocs` only when attached documentation matters, and declaration views only for exact source.
+6. Use `references`, `callers`, `callees`, `implementations`, or `tests` after selecting a change target and when the result can affect the plan. Inspect tests earlier only when the task begins with test behavior or a failure.
+7. Use `ast_search` for code shapes and `grep` for literal text. Use targeted `read` for exact formatting, comments, parser gaps, unsupported files, or source outside declaration boundaries.
+8. Prefer locator edits when a complete declaration or body is the natural edit boundary. Use textual patching when the change crosses those boundaries or depends on surrounding text.
 
-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.
+Stop when the current question is answered. Expand exploration only for a specific unresolved question.