@shanepadgett/tau-agent 0.26.0 → 0.27.0

package/extensions/explore/index.ts

@@ -1,31 +1,74 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolve } from "node:path";
-import { onTauEvent } from "../../shared/events.js";
+import { emitTauEvent, onTauEvent } from "../../shared/events.js";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { createTemporaryOutputStore } from "../../shared/temporary-output-store.ts";
 import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { AST_DISCOVERY_BUDGET, effectiveAstGuidance } from "./ast-guidance.ts";
 import { createAstTools } from "./ast-tools.ts";
 import { AstWorkerClient } from "./ast-worker.ts";
 import { registerAutoread } from "./autoread.ts";
 import { createFindTool } from "./find.ts";
 import { createGrepTool } from "./grep.ts";
 import { createLsTool } from "./ls.ts";
+import { createOrientationState } from "./orientation-state.ts";
 import { createReadCacheStore } from "./read-cache.ts";
 import { createReadSnapshotStore } from "./read-snapshots.ts";
 import { showReadStats } from "./read-stats.ts";
 import { createExploreReadTool } from "./read.ts";
+import exploreSettings from "./settings.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
+	let settings = exploreSettings.defaults;
 	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
 	const readCache = createReadCacheStore();
 	const readSnapshots = createReadSnapshotStore();
 	const astClient = new AstWorkerClient();
-	const ast = createAstTools(astClient, rowState);
+	const orientation = createOrientationState(() => astClient.supportedLanguages());
+	const temporaryOutput = createTemporaryOutputStore();
+	const ast = createAstTools(astClient, rowState, temporaryOutput, orientation, (toolCallId, cwd, summary) => {
+		emitTauEvent(pi, "tau:file-mutation.applied", {
+			source: "locatorEdit",
+			toolCallId,
+			cwd,
+			status: summary.status,
+			changes: summary.changes.map((change) => ({
+				path: change.path,
+				kind: change.kind,
+				move: change.move,
+				linesAdded: change.linesAdded,
+				linesRemoved: change.linesRemoved,
+				resultingFingerprint: change.resultingFingerprint,
+				snapshotRanges: change.snapshotRanges,
+			})),
+		});
+	});
 	registerAutoread(pi, rowState);
 	pi.registerTool(ast.outline);
 	pi.registerTool(ast.symbol);
+	pi.registerTool(ast.replace_declaration);
+	pi.registerTool(ast.replace_body);
+	pi.registerTool(ast.insert_declaration);
+	pi.registerTool(ast.rename_declaration);
+	pi.registerTool(ast.api_discover);
+	pi.registerTool(ast.ast_search);
+	pi.registerTool(ast.references);
+	pi.registerTool(ast.callers);
+	pi.registerTool(ast.callees);
+	pi.registerTool(ast.implementations);
+	pi.registerTool(ast.tests);
 	pi.registerTool(createLsTool(rowState));
 	pi.registerTool(createFindTool(rowState));
 	pi.registerTool(createGrepTool(rowState));
-	pi.registerTool(createExploreReadTool(rowState, readCache, readSnapshots));
+	pi.registerTool(createExploreReadTool(rowState, orientation, readCache, readSnapshots, () => settings.readGate));
+	pi.on("before_agent_start", async (event, ctx) => {
+		const guidance = await effectiveAstGuidance({
+			cwd: ctx.cwd,
+			workerLanguages: () => astClient.supportedLanguages(),
+			discoveryBudget: AST_DISCOVERY_BUDGET,
+		});
+		return guidance ? { systemPrompt: `${event.systemPrompt}\n\n${guidance}` } : undefined;
+	});
 	pi.registerCommand("read-stats", {
 		description: "Show estimated read token and cost savings for this session",
 		async handler(_args, ctx) {
@@ -33,10 +76,13 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 				ctx.ui.notify("Read stats require TUI mode", "error");
 				return;
 			}
-			await showReadStats(ctx);
+			await showReadStats(ctx, orientation);
 		},
 	});
-	pi.on("session_start", () => {
+	pi.on("session_start", async (_event, ctx) => {
+		settings = await loadTauExtensionSettings(ctx, exploreSettings);
+		await temporaryOutput.shutdown();
+		await temporaryOutput.start();
 		rowState.clear();
 		readSnapshots.clear();
 		ast.clear();
@@ -47,11 +93,21 @@ export default function exploreExtension(pi: ExtensionAPI): void {
 			...(change.move ? [resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)] : []),
 		]);
 		ast.invalidate(paths);
+		orientation.recordPatched(
+			event.changes.map((change) => ({
+				path: resolve(event.cwd, change.path),
+				resultingFingerprint: change.resultingFingerprint,
+			})),
+		);
 	});
 	pi.on("session_compact", () => readSnapshots.clear());
-	pi.on("session_tree", () => readSnapshots.clear());
+	pi.on("session_tree", () => {
+		readSnapshots.clear();
+		ast.resetForTree();
+	});
 	pi.on("session_shutdown", async () => {
 		ast.clear();
 		await astClient.shutdown();
+		await temporaryOutput.shutdown();
 	});
 }

package/extensions/explore/orientation-state.ts

@@ -0,0 +1,280 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { astLanguageForPath, type AstLanguage } from "./ast-languages.ts";
+
+export type StructuralAttemptKind =
+	| "directOutline"
+	| "symbol"
+	| "apiCandidate"
+	| "structuralMatch"
+	| "relationshipLocation"
+	| "relationshipScope";
+export type ReadGateDecision = StructuralAttemptKind | "fatalFallback" | "blocked";
+export type ReadPermission = Exclude<ReadGateDecision, "blocked"> | "postPatchDiff" | "ungated";
+
+export interface OrientationTelemetry {
+	blockedReadAttempts: number;
+	permittedReadAttempts: number;
+	fallbackReadAttempts: number;
+	permissionReadAttempts: Record<Exclude<ReadPermission, "ungated">, number>;
+	workerInputBytes: number;
+	completeRenderedBytes: number;
+	modelVisibleAstBytes: number;
+	sourceBytesDeflected: number;
+	temporaryOutputBytes: number;
+	directReadBytes: number;
+	overflowReadBytes: number;
+}
+
+interface AttemptRecord {
+	fingerprint: string;
+	kind: StructuralAttemptKind;
+}
+
+interface FatalFallbackRecord {
+	fingerprint: string;
+	includePrivate: boolean;
+	names: readonly string[];
+	diagnostic: {
+		code: "outline_failed" | "outlineFailed" | "response_too_large" | "resultFrameTooLarge";
+		message: string;
+	};
+}
+
+interface FileState {
+	attempt: AttemptRecord | undefined;
+	fallback: FatalFallbackRecord | undefined;
+	patchFingerprint: string | undefined;
+}
+
+type TelemetryEvent =
+	| {
+			toolCallId: string;
+			kind: "outline";
+			workerInputBytes: number;
+			completeRenderedBytes: number;
+			modelVisibleAstBytes: number;
+			temporaryOutputBytes: number;
+	  }
+	| {
+			toolCallId: string;
+			kind: "structuralAttempt";
+			sourceBytesDeflected: number;
+	  }
+	| {
+			toolCallId: string;
+			kind: "blockedRead";
+	  }
+	| {
+			toolCallId: string;
+			kind: "read";
+			permission: ReadPermission;
+			returnedBytes: number;
+			overflow: boolean;
+	  };
+
+export interface OrientationState {
+	supports(path: string): Promise<boolean>;
+	check(path: string, fingerprint: string): ReadGateDecision;
+	checkPatch(path: string, fingerprint: string): boolean;
+	recordAttempts(
+		records: readonly {
+			path: string;
+			fingerprint: string;
+			kind: StructuralAttemptKind;
+			toolCallId: string;
+			sourceBytesDeflected: number;
+		}[],
+	): void;
+	recordFatal(input: {
+		path: string;
+		fingerprint: string;
+		includePrivate: boolean;
+		names: readonly string[];
+		code: "outline_failed" | "outlineFailed" | "response_too_large" | "resultFrameTooLarge";
+		message: string;
+	}): void;
+	recordPatched(records: readonly { path: string; resultingFingerprint: string | null }[]): void;
+	recordOutlineTelemetry(
+		toolCallId: string,
+		metrics: {
+			workerInputBytes: number;
+			completeRenderedBytes: number;
+			modelVisibleAstBytes: number;
+			temporaryOutputBytes: number;
+		},
+	): void;
+	recordBlockedRead(toolCallId: string, path: string): void;
+	recordRead(toolCallId: string, path: string, permission: ReadPermission, returnedBytes: number): void;
+	recordTemporaryOutput(path: string): void;
+	telemetry(includedToolCallIds: ReadonlySet<string> | undefined): OrientationTelemetry;
+	invalidate(paths: readonly string[]): void;
+	clear(): void;
+	resetGate(): void;
+}
+
+export function sourceFingerprint(source: Uint8Array): string {
+	return `sha256:${createHash("sha256").update(source).digest("hex")}`;
+}
+
+export function createOrientationState(workerLanguages: () => Promise<readonly AstLanguage[]>): OrientationState {
+	const files = new Map<string, FileState>();
+	const temporaryOutputs = new Set<string>();
+	const events: TelemetryEvent[] = [];
+
+	function stateFor(path: string): FileState {
+		const canonicalPath = canonicalPathForState(path);
+		const existing = files.get(canonicalPath);
+		if (existing) return existing;
+		const state: FileState = { attempt: undefined, fallback: undefined, patchFingerprint: undefined };
+		files.set(canonicalPath, state);
+		return state;
+	}
+
+	return {
+		async supports(path) {
+			const language = astLanguageForPath(canonicalPathForState(path));
+			if (!language) return false;
+			try {
+				return (await workerLanguages()).includes(language);
+			} catch {
+				return false;
+			}
+		},
+		check(path, fingerprint) {
+			const state = files.get(canonicalPathForState(path));
+			if (!state) return "blocked";
+			if (state.attempt && state.attempt.fingerprint !== fingerprint) state.attempt = undefined;
+			if (state.fallback && state.fallback.fingerprint !== fingerprint) state.fallback = undefined;
+			if (state.attempt?.fingerprint === fingerprint) return state.attempt.kind;
+			return state.fallback?.fingerprint === fingerprint ? "fatalFallback" : "blocked";
+		},
+		checkPatch(path, fingerprint) {
+			const state = files.get(canonicalPathForState(path));
+			if (!state?.patchFingerprint) return false;
+			if (state.patchFingerprint === fingerprint) return true;
+			state.patchFingerprint = undefined;
+			return false;
+		},
+		recordAttempts(records) {
+			for (const record of records) {
+				const state = stateFor(record.path);
+				state.attempt = { fingerprint: record.fingerprint, kind: record.kind };
+				state.fallback = undefined;
+				events.push({
+					toolCallId: record.toolCallId,
+					kind: "structuralAttempt",
+					sourceBytesDeflected: record.sourceBytesDeflected,
+				});
+			}
+		},
+		recordFatal(input) {
+			const state = stateFor(input.path);
+			state.fallback = {
+				fingerprint: input.fingerprint,
+				includePrivate: input.includePrivate,
+				names: [...input.names],
+				diagnostic: { code: input.code, message: input.message },
+			};
+		},
+		recordPatched(records) {
+			for (const record of records) {
+				if (record.resultingFingerprint === null) continue;
+				stateFor(record.path).patchFingerprint = record.resultingFingerprint;
+			}
+		},
+		recordOutlineTelemetry(toolCallId, metrics) {
+			events.push({ toolCallId, kind: "outline", ...metrics });
+		},
+		recordBlockedRead(toolCallId, path) {
+			stateFor(path);
+			events.push({ toolCallId, kind: "blockedRead" });
+		},
+		recordRead(toolCallId, path, permission, returnedBytes) {
+			events.push({
+				toolCallId,
+				kind: "read",
+				permission,
+				returnedBytes,
+				overflow: temporaryOutputs.has(canonicalPathForState(path)),
+			});
+		},
+		recordTemporaryOutput(path) {
+			temporaryOutputs.add(canonicalPathForState(path));
+		},
+		telemetry(includedToolCallIds) {
+			const permissionReadAttempts: OrientationTelemetry["permissionReadAttempts"] = {
+				directOutline: 0,
+				symbol: 0,
+				apiCandidate: 0,
+				structuralMatch: 0,
+				relationshipLocation: 0,
+				relationshipScope: 0,
+				fatalFallback: 0,
+				postPatchDiff: 0,
+			};
+			const result: OrientationTelemetry = {
+				blockedReadAttempts: 0,
+				permittedReadAttempts: 0,
+				fallbackReadAttempts: 0,
+				permissionReadAttempts,
+				workerInputBytes: 0,
+				completeRenderedBytes: 0,
+				modelVisibleAstBytes: 0,
+				sourceBytesDeflected: 0,
+				temporaryOutputBytes: 0,
+				directReadBytes: 0,
+				overflowReadBytes: 0,
+			};
+			for (const event of events) {
+				if (includedToolCallIds && !includedToolCallIds.has(event.toolCallId)) continue;
+				if (event.kind === "outline") {
+					result.workerInputBytes += event.workerInputBytes;
+					result.completeRenderedBytes += event.completeRenderedBytes;
+					result.modelVisibleAstBytes += event.modelVisibleAstBytes;
+					result.temporaryOutputBytes += event.temporaryOutputBytes;
+				} else if (event.kind === "structuralAttempt") {
+					result.sourceBytesDeflected += event.sourceBytesDeflected;
+				} else if (event.kind === "blockedRead") {
+					result.blockedReadAttempts += 1;
+				} else {
+					result.directReadBytes += event.returnedBytes;
+					if (event.overflow) result.overflowReadBytes += event.returnedBytes;
+					if (event.permission !== "ungated") {
+						result.permittedReadAttempts += 1;
+						result.permissionReadAttempts[event.permission] += 1;
+					}
+					if (event.permission === "fatalFallback") result.fallbackReadAttempts += 1;
+				}
+			}
+			return result;
+		},
+		invalidate(paths) {
+			for (const path of paths) {
+				const state = files.get(canonicalPathForState(path));
+				if (!state) continue;
+				state.attempt = undefined;
+				state.fallback = undefined;
+				state.patchFingerprint = undefined;
+			}
+		},
+		clear() {
+			files.clear();
+			temporaryOutputs.clear();
+			events.length = 0;
+		},
+		resetGate() {
+			files.clear();
+		},
+	};
+}
+
+function canonicalPathForState(path: string): string {
+	const absolutePath = resolve(path);
+	try {
+		return realpathSync(absolutePath);
+	} catch {
+		return absolutePath;
+	}
+}

package/extensions/explore/read-stats-panel.ts

@@ -1,7 +1,8 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import { formatSize, type Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, type KeybindingsManager, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
 import { bindingHint, Tabs, ToolPanel, type ToolPanelConfig } from "@shanepadgett/tau-tui";
 import type { ReadCacheMode } from "./read-cache.ts";
+import type { OrientationTelemetry } from "./orientation-state.ts";
 
 export interface ReadSavingsSnapshot {
 	label: string;
@@ -12,6 +13,7 @@ export interface ReadSavingsSnapshot {
 	unchangedCost: number;
 	diffCost: number;
 	counts: Record<ReadCacheMode, number>;
+	gate: OrientationTelemetry;
 }
 
 export function createReadStatsPanel(
@@ -100,6 +102,7 @@ class SavingsBody implements Component {
 	render(width: number): string[] {
 		const avoided = Math.max(0, this.snapshot.baselineTokens - this.snapshot.returnedTokens);
 		const reduction = this.snapshot.baselineTokens > 0 ? avoided / this.snapshot.baselineTokens : 0;
+		const sourceAvoided = Math.max(0, this.snapshot.gate.sourceBytesDeflected - this.snapshot.gate.overflowReadBytes);
 		return [
 			this.theme.bold("Tokens"),
 			metricRow("Without cache", formatTokens(this.snapshot.baselineTokens), width),
@@ -119,6 +122,25 @@ class SavingsBody implements Component {
 			countRow("Baseline", this.snapshot.counts.baseline, "Unchanged", this.snapshot.counts.unchanged, width),
 			countRow("Changes", this.snapshot.counts.diff, "Recovery", this.snapshot.counts.recovery, width),
 			"",
+			this.theme.bold("AST-first reads"),
+			countRow(
+				"Blocked",
+				this.snapshot.gate.blockedReadAttempts,
+				"Permitted",
+				this.snapshot.gate.permittedReadAttempts,
+				width,
+			),
+			metricRow("Fallback reads", String(this.snapshot.gate.fallbackReadAttempts), width),
+			metricRow("Source avoided", formatSize(sourceAvoided), width),
+			metricRow("Direct returned", formatSize(this.snapshot.gate.directReadBytes), width),
+			metricRow("Overflow reread", formatSize(this.snapshot.gate.overflowReadBytes), width),
+			"",
+			this.theme.bold("AST bytes"),
+			metricRow("Worker input", formatSize(this.snapshot.gate.workerInputBytes), width),
+			metricRow("Full rendered", formatSize(this.snapshot.gate.completeRenderedBytes), width),
+			metricRow("Model visible", formatSize(this.snapshot.gate.modelVisibleAstBytes), width),
+			metricRow("Temporary", formatSize(this.snapshot.gate.temporaryOutputBytes), width),
+			"",
 			truncateToWidth(
 				this.theme.fg("dim", "Estimates include repeated chat history and prompt caching."),
 				width,

package/extensions/explore/read-stats.ts

@@ -1,4 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { OrientationState } from "./orientation-state.ts";
 import { readMetaFromMessage, type ReadCacheMode } from "./read-cache.ts";
 import { createReadStatsPanel, type ReadSavingsSnapshot } from "./read-stats-panel.ts";
 
@@ -9,11 +10,16 @@ interface ContextTotals {
 	diffSaved: number;
 }
 
-export async function showReadStats(ctx: ExtensionCommandContext): Promise<void> {
+export async function showReadStats(ctx: ExtensionCommandContext, orientation: OrientationState): Promise<void> {
 	const entries = ctx.sessionManager.getEntries();
 	const branchIds = new Set(ctx.sessionManager.getBranch().map((entry) => entry.id));
-	const current = calculateSnapshot(entries, branchIds, "Current chat");
-	const whole = calculateSnapshot(entries, undefined, "Whole session");
+	const current = calculateSnapshot(
+		entries,
+		branchIds,
+		"Current chat",
+		orientation.telemetry(toolCallIds(entries, branchIds)),
+	);
+	const whole = calculateSnapshot(entries, undefined, "Whole session", orientation.telemetry(undefined));
 	await ctx.ui.custom(
 		(tui, theme, keybindings, done) => createReadStatsPanel(tui, theme, keybindings, done, current, whole),
 		{
@@ -27,6 +33,7 @@ function calculateSnapshot(
 	entries: readonly unknown[],
 	includedIds: ReadonlySet<string> | undefined,
 	label: string,
+	gate: ReadSavingsSnapshot["gate"],
 ): ReadSavingsSnapshot {
 	const states = new Map<string, ContextTotals>();
 	const counts: Record<ReadCacheMode, number> = { baseline: 0, recovery: 0, unchanged: 0, diff: 0 };
@@ -91,9 +98,20 @@ function calculateSnapshot(
 		unchangedCost,
 		diffCost,
 		counts,
+		gate,
 	};
 }
 
+function toolCallIds(entries: readonly unknown[], includedIds: ReadonlySet<string>): Set<string> {
+	const ids = new Set<string>();
+	for (const entry of entries) {
+		if (!isRecord(entry) || typeof entry.id !== "string" || !includedIds.has(entry.id)) continue;
+		if (entry.type !== "message" || !isRecord(entry.message)) continue;
+		if (typeof entry.message.toolCallId === "string") ids.add(entry.message.toolCallId);
+	}
+	return ids;
+}
+
 function isAssistantMessage(value: unknown): value is {
 	role: "assistant";
 	usage: {

package/extensions/explore/read.ts

@@ -8,7 +8,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, realpath } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { Type, type Static } from "typebox";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
@@ -19,6 +19,7 @@ import {
 	selectCompleteFileResponse,
 } from "./full-file-knowledge.ts";
 import { normalizeCountLimit } from "./limits.ts";
+import type { OrientationState, ReadPermission } from "./orientation-state.ts";
 import { stripLeadingAt } from "./path-display.ts";
 import {
 	createReadCacheStore,
@@ -27,6 +28,7 @@ import {
 	type ReadCacheStore,
 } from "./read-cache.ts";
 import { createReadSnapshotStore, type ReadSnapshotStore } from "./read-snapshots.ts";
+import exploreSettings, { matchesExploreReadGate, type ExploreReadGateSettings } from "./settings.ts";
 
 const readSchema = Type.Object({
 	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
@@ -204,14 +206,16 @@ function createMeta(
 
 export function createExploreReadTool(
 	rowState: ToolRowStateStore,
+	orientation: OrientationState,
 	cache: ReadCacheStore = createReadCacheStore(),
 	snapshots: ReadSnapshotStore = createReadSnapshotStore(),
+	readGate: () => ExploreReadGateSettings = () => exploreSettings.defaults.readGate,
 ): ReadDefinition {
 	const baseDefinition = readDefinitionForCwd(process.cwd());
 	return {
 		...baseDefinition,
 		description:
-			"Read a relevant file as a whole by omitting offset, limit, and lineNumbers. Later whole-file reads avoid repeating unchanged content and return useful diffs or current source after changes. Use ranges only for targeted peripheral inspection or to continue after truncation.",
+			"Read a text or image file with optional line ranges and line numbers. Configured supported source requires a current structural attempt first. Repeated complete-file reads avoid repeating unchanged content and can return a useful diff or current source after changes.",
 		parameters: readSchema,
 		async execute(
 			toolCallId: Parameters<ReadExecute>[0],
@@ -222,13 +226,16 @@ export function createExploreReadTool(
 		) {
 			const definition = readDefinitionForCwd(ctx.cwd);
 			const normalized = normalizeReadParams(params);
-			const path = isAbsolute(normalized.path) ? resolve(normalized.path) : resolve(ctx.cwd, normalized.path);
+			const requestedPath = isAbsolute(normalized.path)
+				? resolve(normalized.path)
+				: resolve(ctx.cwd, normalized.path);
+			const path = await realpath(requestedPath);
 			const snapshotEpoch = snapshots.epoch();
 			const buffer = await readFile(path);
 			if (isSupportedImage(buffer)) {
 				return definition.execute(
 					toolCallId,
-					{ path: normalized.path, offset: normalized.offset, limit: normalized.limit },
+					{ path, offset: normalized.offset, limit: normalized.limit },
 					signal,
 					onUpdate,
 					ctx,
@@ -240,48 +247,78 @@ export function createExploreReadTool(
 			try {
 				text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
 			} catch {
-				return definition.execute(toolCallId, normalized, signal, onUpdate, ctx);
-			}
-
-			const baseline = baselineText(text, normalized);
-			if (!baseline.cacheable) {
-				return { content: [{ type: "text", text: baseline.text }], details: baseline.details };
+				return definition.execute(toolCallId, { ...normalized, path }, signal, onUpdate, ctx);
 			}
 			const hash = createHash("sha256").update(buffer).digest("hex");
+			const baseline = baselineText(text, normalized);
 			const staleEpoch = !snapshots.isCurrent(snapshotEpoch);
-			const decision = staleEpoch
+			const cacheDecision = staleEpoch
 				? { baseHash: undefined, baselineText: undefined, recovery: false }
-				: cache.decision(ctx, path, baseline.scopeKey);
+				: cache.decision(ctx, requestedPath, baseline.scopeKey);
 			let output = baseline.text;
-			let mode: ReadCacheMetaV1["mode"] = decision.recovery ? "recovery" : "baseline";
+			let mode: ReadCacheMetaV1["mode"] = cacheDecision.recovery ? "recovery" : "baseline";
 			let summary = baseline.summary;
 
-			if (baseline.completeFile) {
+			if (baseline.cacheable && baseline.completeFile) {
 				const selected = selectCompleteFileResponse({
 					displayPath: normalized.path,
 					currentText: text,
 					currentHash: hash,
 					fullText: baseline.text,
 					totalLines: baseline.totalLines,
-					recovery: decision.recovery,
-					baseHash: decision.baseHash,
+					recovery: cacheDecision.recovery,
+					baseHash: cacheDecision.baseHash,
 					baselineText:
-						decision.baselineText ??
-						(decision.baseHash === undefined ? undefined : snapshots.get(decision.baseHash)),
+						cacheDecision.baselineText ??
+						(cacheDecision.baseHash === undefined ? undefined : snapshots.get(cacheDecision.baseHash)),
 				});
 				output = selected.text;
 				mode = selected.mode;
 				summary = selected.summary;
-			} else if (!decision.recovery && decision.baseHash === hash) {
+			} else if (baseline.cacheable && !cacheDecision.recovery && cacheDecision.baseHash === hash) {
 				output = `unchanged, lines ${baseline.startLine}-${baseline.endLine} of ${baseline.totalLines}`;
 				mode = "unchanged";
 				summary = output;
 			}
 
+			let permission: ReadPermission = "ungated";
+			if ((await orientation.supports(path)) && matchesExploreReadGate(path, ctx.cwd, readGate())) {
+				const fingerprint = `sha256:${hash}`;
+				const gateDecision = orientation.check(path, fingerprint);
+				if (gateDecision === "blocked") {
+					const patchDiffPermitted =
+						baseline.cacheable &&
+						baseline.completeFile &&
+						normalized.offset === undefined &&
+						normalized.limit === undefined &&
+						!cacheDecision.recovery &&
+						cacheDecision.baselineText !== undefined &&
+						(mode === "diff" || mode === "unchanged") &&
+						orientation.checkPatch(path, fingerprint);
+					if (!patchDiffPermitted) {
+						orientation.recordBlockedRead(toolCallId, path);
+						throw new Error(
+							`Read blocked for ${normalized.path}: configured source has no current structural attempt. Use exact-name outline, focused api_discover, file-scoped ast_search, or symbol with a fresh locator, then retry read.`,
+						);
+					}
+					permission = "postPatchDiff";
+				} else {
+					permission = gateDecision;
+				}
+			}
+
+			if (!baseline.cacheable) {
+				const result = { content: [{ type: "text" as const, text: baseline.text }], details: baseline.details };
+				orientation.recordRead(toolCallId, path, permission, Buffer.byteLength(baseline.text));
+				return result;
+			}
+
 			if (signal?.aborted) throw new Error("Operation aborted");
 			snapshots.set(hash, text, buffer.byteLength, snapshotEpoch);
-			const meta = createMeta(baseline, path, hash, mode, output, decision.baseHash, summary);
-			return withMeta(baseline, meta, output);
+			const meta = createMeta(baseline, requestedPath, hash, mode, output, cacheDecision.baseHash, summary);
+			const result = withMeta(baseline, meta, output);
+			orientation.recordRead(toolCallId, path, permission, Buffer.byteLength(output));
+			return result;
 		},
 		renderCall(
 			args: Parameters<ReadRenderCall>[0],