@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/extensions/subagent/agents/scout.md

@@ -1,11 +1,21 @@
 ---
 name: scout
-description: Find local files, symbols, data flow, constraints, and unknowns without changing anything
+description: Tiered, AST-first local discovery of files, declarations, data flow, constraints, and unknowns without changes
 tools:
   - read
-  - grep
-  - find
-  - ls
+  - bash
+  - outline
+  - show
+  - discover
+  - ast_search
+  - deps
+  - reverse_deps
+  - callers
+  - callees
+  - references
+  - implementations
+  - impact
+  - context
 names:
   - Pathfinder
   - Trailblazer
@@ -16,36 +26,50 @@ model: openai-codex/gpt-5.6-luna
 thinking: high
 ---
 
-Stay inside delegated task. Answer exactly what was asked. No broader questions, background collection, unrequested recommendations, or mutations.
+Stay inside task. Answer only what was asked. No mutations, side quests, background sweeps, or unasked advice.
 
-Delegating prompt is output contract. Requested shape wins. Otherwise use smallest matching shape below.
+Delegating prompt controls output. Otherwise use smallest matching shape below.
 
-## Inspection discipline
+## Evidence ladder
 
-1. Extract exact target, question, and required output before searching.
-2. Start with named paths and symbols. Use `grep` or `find` for specific evidence. Do not map repository.
-3. Every read answers a pending question. Read smallest useful range. Follow imports, callers, or related files only when evidence requires it.
-4. Use `lineNumbers: true` for text supporting findings. Cite exact `path:start-end` ranges from tool output. Never estimate line numbers.
-5. Stop when every requested field has evidence. Put unresolved facts under `Unknowns`. Do not explore unrelated code for completeness.
+Use cheapest source that proves each claim. Skip steps when task supplies exact path or declaration. Escalate only when current evidence cannot answer.
 
-Absolute paths may identify readable reference repositories outside current working directory.
+1. **Supplied context** — Treat current line-numbered task files as authoritative this turn.
+2. **Paths and literals** — Use read-only `bash` (`ls`, `find`, `rg`/`grep`) for narrow path discovery, exact text, registrations, and unsupported formats. Use ranged `read` for formatting or source without structural support.
+3. **Structure** — Default to `outline` for known files/packages and unfamiliar supported subtrees. Use `discover` when reuse intent is known but path or exact name is not. Use `ast_search` for source shapes.
+4. **Exact declarations** — Use `show` with path + name (+ line when needed). Prefer `signature`; add docs, body, imports, or context lines only when question requires them.
+5. **Focused relationships** — After resolving a declaration, use `callers`, `callees`, `references`, or `implementations` for one direct relationship question. Use `deps` and `reverse_deps` for file imports, not declaration calls.
+6. **Composition** — Use `impact` for full one-hop declaration plus transitive file blast radius. Use `context` for one budgeted declaration pack when nearby bodies and relationships answer faster than separate calls.
+
+Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels. Do not turn ambiguous sites into claimed impact.
+
+## Search procedure
+
+1. Extract target, question, scope, and requested output shape.
+2. List required claims and select cheapest evidence for each.
+3. Start from supplied paths and names. Search outward only for required relationships.
+4. For reuse, run `discover`, then inspect selected candidates with `show`.
+5. For unknown source shape, run `ast_search`, then inspect only selected enclosing declarations.
+6. For behavior or data flow, orient target, follow focused relationships, then retrieve only declarations needed to explain flow.
+7. For impact, use `impact`; use focused relationship tools only when one section needs closer evidence.
+8. Stop when requested claims are supported. Put material gaps under `Unknowns`.
+
+Absolute paths may point to read-only reference repositories outside cwd.
 
 ## Result shapes
 
-Use only relevant sections. Omit empty sections.
+Use relevant sections only. Omit empty sections.
 
 ### Locate
 
-`path:start-end` — symbol — match reason
+`path:start-end` — declaration — match reason
 
 ### Explain behavior
 
-- `Entry:` `path:start-end` — symbol
-- `Flow:` ordered steps; one cited fact per step
+- `Entry:` `path:start-end` — declaration
+- `Flow:` ordered steps; one cited fact each
 - `Result:` observed outcome
 
-Only branches relevant to requested behavior.
-
 ### Trace data
 
 - `Source:` cited origin
@@ -54,12 +78,11 @@ Only branches relevant to requested behavior.
 
 ### Find references or impact
 
-- `Direct references:` cited relationships
+- `Direct references:` cited relationships with certainty
+- `Editable scopes:` declarations requiring inspection or change
 - `Behavior affected:` evidence-backed consequences
 - `Unknowns:` remaining uncertainty
 
-No speculative blast radius.
-
 ### Verify a claim
 
 - `Verdict:` `yes`, `no`, `partially`, or `unknown`
@@ -69,23 +92,19 @@ No speculative blast radius.
 ### Compare
 
 - `Shared:` cited similarities
-- `Differences:` cited differences by aspect
+- `Differences:` cited by aspect
 - `Relevant consequence:` requested consequences only
 
 ### Inventory
 
-`path:start-end` — symbol — role
-
-When completeness matters, state searched scope. If completeness cannot be guaranteed, say why.
-
-### Constraints and unknowns
+`path:start-end` — declaration — role
 
-- `Constraints:` constraint — supporting citation
-- `Unknowns:` missing fact — evidence needed
+When completeness matters, state searched scope. If uncertain, say why.
 
 ## Reporting rules
 
-- Every material code claim needs exact path, line range, and symbol when one exists.
-- Separate observed facts from inference. Label inference.
-- Quote smallest fragment needed to disambiguate. No whole functions or blocks when citation and concise description suffice.
-- No preamble, search log, generic repository summary, repeated evidence, or unrequested next steps.
+- Every material code claim needs exact path, line range, and declaration when one exists.
+- Cite ranges returned by tools. Never estimate line numbers.
+- Separate fact from inference. Label inference.
+- Quote smallest useful fragment.
+- No preamble, search log, generic repository summary, repeated evidence, or unasked next steps.

package/extensions/subagent/run.ts

@@ -12,7 +12,7 @@ import {
 	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { createCompleteFileMeta } from "../explore/full-file-knowledge.ts";
+import { createCompleteFileMeta } from "../../shared/full-file-knowledge.ts";
 import type { AgentDefinition } from "./agents.ts";
 import { emptySubagentResumeState, type RetainedTurnOutcome, type SubagentResumeState } from "./resume.ts";
 import {

package/extensions/tau-help/help.md

@@ -40,7 +40,7 @@ Gives the agent `context_prune` for creating a hard context checkpoint after bro
 
 ## explore
 
-Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. It also adds `outline` for public declarations in TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files or package directories. Markdown headings locate their complete sections. Exact-name filters and `includePrivate` narrow or expand that surface. Attached documentation comments are omitted by default; `includeDocs` adds them without hiding annotations or attributes. Parenthesized numbers identify declarations for `symbol`, which retrieves several complete declarations with optional surrounding lines and rejects stale batches. Installed packages support `outline` and `symbol` on Apple Silicon Macs without requiring Rust or Cargo; other platforms retain the rest of Explore and report the limit when an AST tool is invoked. These tools produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A failed patch unlocks one normal reread of the affected path. `/read-stats` shows estimated token and cost savings for the current chat and whole session.
+Structural source tools on in-process tree-sitter (WASM), available on every Node-supported platform. Registers `outline`, `show`, `discover`, `ast_search`, `deps`, `reverse_deps`, `callers`, `callees`, `references`, `implementations`, `impact`, and `context`; symbol targets use path + name (+ line when needed). Pi keeps `ls` / `find` / `grep` / `read`. Large full `read`/autoread of registered source (including Markdown) returns outline by default (`explore.read.*`); ranged `read` or `show` for bodies. Disable with `explore.read.enabled: false`.
 
 ## footer
 
@@ -92,7 +92,7 @@ Runs configured commands while keeping their output out of agent context when th
 
 ## soul
 
-Adds Rok’s persona and operating rules to Pi’s native assistant prompt.
+Adds two independently toggleable sections to Pi’s native assistant prompt: `ponytail` (a lazy-senior-dev build ethos) and `caveman` (a terse communication style). Both on by default.
 
 ## stash
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.26.0",
+	"version": "0.28.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -31,14 +31,15 @@
 		"themes/**/*",
 		"docs/**/*",
 		"schemas/**/*",
-		"native-bin/**/*",
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.26.0",
-		"@toon-format/toon": "2.3.0",
+		"@ast-grep/wasm": "0.45.0",
+		"@shanepadgett/tau-tui": "0.28.0",
+		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
-		"smol-toml": "1.7.0"
+		"smol-toml": "1.7.0",
+		"web-tree-sitter": "0.26.11"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/schemas/tau.schema.json

@@ -61,12 +61,11 @@
 							"default": true,
 							"description": "Enable context pruning."
 						},
-						"nudgeEveryPercent": {
+						"nudgeEveryTokens": {
 							"type": "integer",
-							"default": 20,
+							"default": 30000,
 							"minimum": 1,
-							"maximum": 100,
-							"description": "Context growth interval between automatic pruning hints."
+							"description": "Active-context token interval between automatic pruning hints."
 						},
 						"nudgeInstructions": {
 							"type": "array",
@@ -87,6 +86,47 @@
 					},
 					"additionalProperties": false
 				},
+				"explore": {
+					"type": "object",
+					"properties": {
+						"context": {
+							"type": "object",
+							"properties": {
+								"defaultBudgetTokens": {
+									"type": "integer",
+									"default": 8000,
+									"minimum": 1,
+									"description": "Default token budget for context when the caller omits budget."
+								}
+							},
+							"additionalProperties": false
+						},
+						"read": {
+							"type": "object",
+							"properties": {
+								"enabled": {
+									"type": "boolean",
+									"default": true,
+									"description": "Master switch for Explore structural read overlay and large-source autoread outline path. When false, Pi read and autoread keep ordinary full bodies."
+								},
+								"structureThresholdLines": {
+									"type": "integer",
+									"default": 200,
+									"minimum": 1,
+									"description": "Registered source at or under this line count may be full-read. Above it, full read model-visible result is outline only."
+								},
+								"maxRangeLines": {
+									"type": "integer",
+									"default": 200,
+									"minimum": 1,
+									"description": "Maximum lines returned by one ranged read on registered source."
+								}
+							},
+							"additionalProperties": false
+						}
+					},
+					"additionalProperties": false
+				},
 				"footer": {
 					"type": "object",
 					"properties": {
@@ -234,10 +274,15 @@
 				"soul": {
 					"type": "object",
 					"properties": {
-						"enabled": {
+						"ponytail": {
+							"type": "boolean",
+							"default": true,
+							"description": "Add the lazy-senior-dev build ethos to Tau's system prompt."
+						},
+						"caveman": {
 							"type": "boolean",
 							"default": true,
-							"description": "Enable Tau's Rok system prompt."
+							"description": "Add the terse communication style to Tau's system prompt."
 						}
 					},
 					"additionalProperties": false

package/{extensions/explore → shared}/autoread.ts

@@ -2,11 +2,10 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
-import { onTauEvent, type TauAgentEvents } from "../../shared/events.js";
-import type { ToolRowStateStore } from "../../shared/tool-row-state.js";
 import { Marker, type MarkerState } from "@shanepadgett/tau-tui";
-import { createCompleteFileMeta } from "./full-file-knowledge.ts";
-import type { ReadCacheMetaV1 } from "./read-cache.ts";
+import { onTauEvent, type TauAgentEvents } from "./events.js";
+import { createCompleteFileMeta, type ReadCacheMetaV1 } from "./full-file-knowledge.ts";
+import type { ToolRowStateStore } from "./tool-row-state.js";
 
 const AUTOREAD_MESSAGE_TYPE = "tau.autoread";
 
@@ -30,6 +29,17 @@ export interface PreparedAutoreadMessage {
 	details: AutoreadDetails & { status: "read"; readCache: ReadCacheMetaV1 };
 }
 
+export type PrepareAutoreadMessage = (options: {
+	rowId: string;
+	path: string;
+	cwd: string;
+	source: string;
+	batchId: string;
+	signal: AbortSignal | undefined;
+	isLifecycleCurrent: () => boolean;
+	maximumBytes?: number;
+}) => Promise<PreparedAutoreadMessage>;
+
 export async function prepareAutoreadMessage(options: {
 	rowId: string;
 	path: string;
@@ -76,7 +86,11 @@ export async function prepareAutoreadMessage(options: {
 	};
 }
 
-export function registerAutoread(pi: ExtensionAPI, rowState: ToolRowStateStore): void {
+export function registerAutoread(
+	pi: ExtensionAPI,
+	rowState: ToolRowStateStore,
+	prepare: PrepareAutoreadMessage = prepareAutoreadMessage,
+): void {
 	let lifecycleGeneration = 0;
 	pi.on("session_start", () => {
 		lifecycleGeneration += 1;
@@ -90,7 +104,7 @@ export function registerAutoread(pi: ExtensionAPI, rowState: ToolRowStateStore):
 	pi.on("session_shutdown", () => {
 		lifecycleGeneration += 1;
 	});
-	onTauEvent(pi, "explore.autoread", "tau:autoread.requested", async (data) => {
+	onTauEvent(pi, "shared.autoread", "tau:autoread.requested", async (data) => {
 		const event = readAutoreadRequestedEvent(data);
 		if (!event) return;
 		const generation = lifecycleGeneration;
@@ -105,7 +119,7 @@ export function registerAutoread(pi: ExtensionAPI, rowState: ToolRowStateStore):
 					batchId: event.batchId,
 				} satisfies Omit<AutoreadDetails, "status" | "error">;
 				try {
-					const message = await prepareAutoreadMessage({
+					const message = await prepare({
 						...details,
 						signal: undefined,
 						isLifecycleCurrent: () => generation === lifecycleGeneration,

package/shared/bounded-text-result.ts

@@ -0,0 +1,304 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import {
+	TemporaryOutputError,
+	type TemporaryOutputStore,
+	type TemporaryOutputWriter,
+} from "./temporary-output-store.ts";
+
+export type BoundedTextStrategy = "head" | "tail" | "completeBlocks";
+
+export interface BoundedTextOverflowDetails {
+	strategy: BoundedTextStrategy;
+	truncated: boolean;
+	shownLines: number;
+	totalLines: number;
+	shownBytes: number;
+	totalBytes: number;
+	fullOutputComplete: boolean;
+	temporaryPath: string | undefined;
+	failure: "quota" | "write" | undefined;
+}
+
+export interface BoundedTextResult {
+	content: string;
+	overflow: BoundedTextOverflowDetails;
+	visibleUnitIds: string[];
+}
+
+export function truncateBoundedHead(content: string): ReturnType<typeof truncateHead> {
+	return truncateHead(content, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+}
+
+interface VisibleBlock {
+	id: string | undefined;
+	label: string;
+	text: string;
+}
+
+export class BoundedTextResultBuilder {
+	private readonly store: TemporaryOutputStore;
+	private readonly strategy: BoundedTextStrategy;
+	private snapshot = "";
+	private blocks: VisibleBlock[] = [];
+	private requiredBlocks: VisibleBlock[] = [];
+	private totalBytes = 0;
+	private newlineCount = 0;
+	private hasContent = false;
+	private endsWithNewline = false;
+	private overflowed = false;
+	private modelClosed = false;
+	private oversizedBlockLabel: string | undefined;
+	private output: TemporaryOutputWriter | undefined;
+	private persistenceFailure: "quota" | "write" | undefined;
+	private finished = false;
+
+	constructor(store: TemporaryOutputStore, strategy: BoundedTextStrategy) {
+		this.store = store;
+		this.strategy = strategy;
+	}
+
+	async append(text: string): Promise<void> {
+		if (this.strategy === "completeBlocks") throw new Error("Complete-block results require appendBlock");
+		this.requireOpen();
+		this.count(text);
+		if (!this.overflowed) {
+			const candidate = `${this.snapshot}${text}`;
+			const truncation = this.strategy === "head" ? truncateHead(candidate) : truncateTail(candidate);
+			this.snapshot = truncation.content;
+			if (!truncation.truncated) return;
+			this.overflowed = true;
+			await this.persist(candidate);
+			return;
+		}
+		if (this.strategy === "tail") this.snapshot = truncateTail(`${this.snapshot}${text}`).content;
+		await this.persist(text);
+	}
+
+	async appendBlock(id: string | undefined, label: string, text: string): Promise<void> {
+		if (this.strategy !== "completeBlocks") throw new Error("Text results require append");
+		this.requireOpen();
+		const prefix = this.hasContent ? "\n\n" : "";
+		const chunk = `${prefix}${text}`;
+		this.count(chunk);
+
+		if (!this.modelClosed) {
+			const candidate = `${this.snapshot}${chunk}`;
+			if (!truncateHead(candidate).truncated) {
+				this.snapshot = candidate;
+				this.blocks.push({ id, label, text });
+				return;
+			}
+			this.modelClosed = true;
+			this.overflowed = true;
+			if (this.blocks.length === 0) this.oversizedBlockLabel = label.replaceAll(/[\r\n]/g, " ");
+			await this.persist(candidate);
+			return;
+		}
+		await this.persist(chunk);
+	}
+
+	async appendRequiredBlock(label: string, text: string): Promise<void> {
+		if (this.strategy !== "completeBlocks") throw new Error("Required blocks need complete-block retention");
+		this.requireOpen();
+		const block = { id: undefined, label, text };
+		this.requiredBlocks.push(block);
+		const prefix = this.hasContent ? "\n\n" : "";
+		const chunk = `${prefix}${text}`;
+		this.count(chunk);
+		if (!this.overflowed) {
+			const candidate = `${this.snapshot}${chunk}`;
+			if (!truncateHead(candidate).truncated) {
+				this.snapshot = candidate;
+				return;
+			}
+			this.overflowed = true;
+			this.modelClosed = true;
+			await this.persist(candidate);
+			return;
+		}
+		await this.persist(chunk);
+	}
+
+	async finish(): Promise<BoundedTextResult> {
+		this.requireOpen();
+		this.finished = true;
+		let temporaryPath: string | undefined;
+		if (this.output) {
+			try {
+				temporaryPath = await this.output.finish();
+			} catch (error) {
+				this.persistenceFailure = error instanceof TemporaryOutputError ? error.code : "write";
+			}
+			this.output = undefined;
+		}
+
+		const totalLines = lineCount(this.hasContent, this.newlineCount, this.endsWithNewline);
+		if (!this.overflowed) {
+			return {
+				content: this.snapshot,
+				overflow: {
+					strategy: this.strategy,
+					truncated: false,
+					shownLines: totalLines,
+					totalLines,
+					shownBytes: this.totalBytes,
+					totalBytes: this.totalBytes,
+					fullOutputComplete: true,
+					temporaryPath: undefined,
+					failure: undefined,
+				},
+				visibleUnitIds: this.blocks.flatMap((block) => (block.id === undefined ? [] : [block.id])),
+			};
+		}
+
+		if (this.strategy === "completeBlocks") {
+			return this.finishBlocks(totalLines, temporaryPath);
+		}
+		return this.finishText(totalLines, temporaryPath);
+	}
+
+	async abort(): Promise<void> {
+		this.finished = true;
+		const output = this.output;
+		this.output = undefined;
+		if (output) await output.abort();
+	}
+
+	private finishBlocks(totalLines: number, temporaryPath: string | undefined): BoundedTextResult {
+		const blocks = [...this.blocks];
+		const required = this.requiredBlocks.map((block) => block.text).join("\n\n");
+		let retained = [...blocks.map((block) => block.text), required].filter(Boolean).join("\n\n");
+		let shownBytes = Buffer.byteLength(retained);
+		let shownLines = textLineCount(retained);
+		let notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		const oversized = this.oversizedBlockLabel
+			? `[File block omitted because it exceeds the model-output budget: ${this.oversizedBlockLabel}. Run a non-recursive outline for that file.]`
+			: "";
+		while (blocks.length > 0 && truncateHead([retained, oversized, notice].filter(Boolean).join("\n\n")).truncated) {
+			blocks.pop();
+			retained = [...blocks.map((block) => block.text), required].filter(Boolean).join("\n\n");
+			shownBytes = Buffer.byteLength(retained);
+			shownLines = textLineCount(retained);
+			notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		}
+		let content = [retained, oversized, notice].filter(Boolean).join("\n\n");
+		if (truncateHead(content).truncated) content = truncateHead(content).content;
+		return {
+			content,
+			overflow: this.overflowDetails(shownLines, shownBytes, totalLines, temporaryPath),
+			visibleUnitIds: blocks.flatMap((block) => (block.id === undefined ? [] : [block.id])),
+		};
+	}
+
+	private finishText(totalLines: number, temporaryPath: string | undefined): BoundedTextResult {
+		let retained = this.snapshot;
+		let shownBytes = Buffer.byteLength(retained);
+		let shownLines = textLineCount(retained);
+		let notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		for (let iteration = 0; iteration < 3; iteration += 1) {
+			const noticeLines = textLineCount(notice) + 1;
+			const noticeBytes = Buffer.byteLength(notice) + 2;
+			const options = {
+				maxLines: Math.max(0, DEFAULT_MAX_LINES - noticeLines),
+				maxBytes: Math.max(0, DEFAULT_MAX_BYTES - noticeBytes),
+			};
+			retained = (
+				this.strategy === "head" ? truncateHead(this.snapshot, options) : truncateTail(this.snapshot, options)
+			).content;
+			shownBytes = Buffer.byteLength(retained);
+			shownLines = textLineCount(retained);
+			notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		}
+		return {
+			content: [retained, notice].filter(Boolean).join("\n\n"),
+			overflow: this.overflowDetails(shownLines, shownBytes, totalLines, temporaryPath),
+			visibleUnitIds: [],
+		};
+	}
+
+	private overflowDetails(
+		shownLines: number,
+		shownBytes: number,
+		totalLines: number,
+		temporaryPath: string | undefined,
+	): BoundedTextOverflowDetails {
+		return {
+			strategy: this.strategy,
+			truncated: true,
+			shownLines,
+			totalLines,
+			shownBytes,
+			totalBytes: this.totalBytes,
+			fullOutputComplete: temporaryPath !== undefined && this.persistenceFailure === undefined,
+			temporaryPath,
+			failure: this.persistenceFailure,
+		};
+	}
+
+	private notice(
+		shownLines: number,
+		shownBytes: number,
+		totalLines: number,
+		temporaryPath: string | undefined,
+	): string {
+		return formatBoundedTextOverflow({
+			strategy: this.strategy,
+			truncated: true,
+			shownLines,
+			totalLines,
+			shownBytes,
+			totalBytes: this.totalBytes,
+			fullOutputComplete: temporaryPath !== undefined && this.persistenceFailure === undefined,
+			temporaryPath,
+			failure: this.persistenceFailure,
+		});
+	}
+
+	private count(text: string): void {
+		if (text.length === 0) return;
+		this.totalBytes += Buffer.byteLength(text);
+		this.newlineCount += text.split("\n").length - 1;
+		this.hasContent = true;
+		this.endsWithNewline = text.endsWith("\n");
+	}
+
+	private async persist(text: string): Promise<void> {
+		if (this.persistenceFailure) return;
+		try {
+			this.output ??= await this.store.createOutput();
+			await this.output.write(text);
+		} catch (error) {
+			this.persistenceFailure = error instanceof TemporaryOutputError ? error.code : "write";
+			const output = this.output;
+			this.output = undefined;
+			if (output) await output.abort();
+		}
+	}
+
+	private requireOpen(): void {
+		if (this.finished) throw new Error("Bounded text result is already finished");
+	}
+}
+
+function formatBoundedTextOverflow(details: BoundedTextOverflowDetails): string {
+	const sizes = `${details.shownLines} of ${details.totalLines} lines (${formatSize(details.shownBytes)} of ${formatSize(details.totalBytes)})`;
+	if (details.fullOutputComplete && details.temporaryPath) {
+		return `[Output truncated: showing ${sizes}. Complete output: ${details.temporaryPath}\nTemporary output is valid only for the active session. Use targeted grep or ranged read; reading the whole file will hit the same output limits.]`;
+	}
+	const reason = details.failure === "quota" ? "disk quota exceeded" : "temporary-file write failed";
+	return `[Output truncated: showing ${sizes}. Complete temporary output unavailable: ${reason}.]`;
+}
+
+function textLineCount(text: string): number {
+	return lineCount(text.length > 0, text.split("\n").length - 1, text.endsWith("\n"));
+}
+
+function lineCount(hasContent: boolean, newlineCount: number, endsWithNewline: boolean): number {
+	return hasContent ? newlineCount + (endsWithNewline ? 0 : 1) : 0;
+}

package/shared/events.ts

@@ -25,6 +25,7 @@ export type TauAgentEvents = {
 			move?: { from: string; to: string };
 			linesAdded: number;
 			linesRemoved: number;
+			resultingFingerprint: string | null;
 			snapshotRanges?: Array<{ startLine: number; endLine: number }>;
 		}>;
 	};