@namzu/sdk 37.0.0 → 38.0.0

package/src/run/token-budget.ts

@@ -21,6 +21,8 @@ export interface TokenBudgetRequestSnapshot {
 	runId: RunId
 	/** Cumulative request usage already charged to the owning run. */
 	usage?: TokenUsage
+	/** No reliable final receipt; only explicit reconciliation clears this marker. */
+	unresolved?: boolean
 }
 
 /** Durable authority independent of a message checkpoint's cadence. */
@@ -49,8 +51,10 @@ export interface TokenBudgetSummary {
 	remainingTokens: number | null
 	inFlightRequests: number
 	unsettledChildren: number
-	/** An unresolved provider call or failed ledger write prevents admission. */
+	/** This account is blocked by accounting failure or uncertain finite allowance. */
 	poisoned: boolean
+	/** Unresolved receipts in this subtree, including retained completion records. */
+	unresolvedRequests?: number
 }
 
 interface SharedLedger {
@@ -150,9 +154,6 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 		const accountId = id(account.id, 'account id')
 		if (typeof account.settled !== 'boolean') throw new Error('Invalid token budget settled flag')
 		const limit = count(account.limit, 'limit')
-		if (accountId !== rootAccountId && limit === 0) {
-			throw new Error('A child token budget must have a positive limit')
-		}
 		const usage: Record<string, TokenUsage> = {}
 		for (const [runId, rawUsage] of Object.entries(object(account.usage, 'account usage'))) {
 			id(runId, 'usage run id')
@@ -198,6 +199,8 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 		const request = object(raw, 'request')
 		const requestId = id(request.id, 'request id')
 		const accountId = id(request.accountId, 'request account id')
+		if (request.unresolved !== undefined && typeof request.unresolved !== 'boolean')
+			throw new Error('Invalid unresolved request marker')
 		if (!isEntityId(request.runId, 'run')) throw new Error('Invalid token budget request run id')
 		if (requestIds.has(requestId)) throw new Error('Duplicate token budget request')
 		requestIds.add(requestId)
@@ -209,6 +212,7 @@ export function validateTokenBudgetSnapshot(value: unknown): TokenBudgetSnapshot
 			accountId,
 			runId: request.runId,
 			...(request.usage === undefined ? {} : { usage: usageValue(request.usage) }),
+			...(request.unresolved === true ? { unresolved: true } : {}),
 		}
 	}
 	const requests = source.requests.map(parseRequest)
@@ -346,9 +350,11 @@ export class TokenBudget {
 				rootAccountId: state.rootAccountId,
 				rootRunId: state.rootRunId,
 				accounts: new Map(state.accounts.map((account) => [account.id, account])),
-				requests: new Map(state.requests.map((request) => [request.id, request])),
+				requests: new Map(
+					state.requests.map((request) => [request.id, { ...request, unresolved: true }]),
+				),
 				finishedRequests: new Map(state.completedRequests.map((request) => [request.id, request])),
-				poisoned: state.poisoned === true || state.requests.length > 0,
+				poisoned: state.poisoned === true,
 				persistence,
 				writes: Promise.resolve(),
 			},
@@ -384,7 +390,7 @@ export class TokenBudget {
 	}
 
 	get remaining(): number {
-		if (this.ledger.poisoned || this.node.settled) return 0
+		if (this.admissionBlocked() || this.node.settled) return 0
 		let cursor = this.node
 		let available = this.free(cursor)
 		while (cursor.parentId !== undefined) {
@@ -430,7 +436,7 @@ export class TokenBudget {
 	reserve(tokens: number): TokenBudget {
 		count(tokens, 'reservation')
 		if (this.hasRequest(this.node)) throw new Error('Token budget has an in-flight request')
-		if (tokens === 0 || tokens > this.remaining)
+		if ((tokens === 0 && this.remaining !== Number.POSITIVE_INFINITY) || tokens > this.remaining)
 			throw new Error('Token budget cannot reserve the requested tokens')
 		count(this.totals(this.node).reserved + tokens, 'reserved allowance')
 		const accountId = randomUUID()
@@ -468,7 +474,8 @@ export class TokenBudget {
 	}
 
 	async beginRequest(): Promise<string> {
-		if (this.ledger.poisoned) throw new Error('Token budget has unresolved spend')
+		if (this.admissionBlocked())
+			throw new Error('Token budget has unresolved spend or an accounting failure')
 		if (this.node.settled) throw new Error('Token budget is settled')
 		if (this.remaining <= 0) throw new Error('Token budget is exhausted')
 		const runId = this.runId
@@ -504,10 +511,11 @@ export class TokenBudget {
 	async failRequest(requestId: string, usage?: TokenUsage): Promise<void> {
 		if (this.hasReceipt(requestId)) return this.flush()
 		const request = this.requireRequest(requestId)
-		this.ledger.poisoned = true
+		request.unresolved = true
 		try {
 			if (usage !== undefined) this.recordRequestUsage(request, usage)
 		} catch (error) {
+			this.ledger.poisoned = true
 			this.persist()
 			await this.flush()
 			throw error
@@ -518,9 +526,9 @@ export class TokenBudget {
 
 	/**
 	 * Explicit host recovery after obtaining the provider's final usage receipt.
-	 * Ordinary completion never reopens an uncertain ledger. Reconciliation can
-	 * do so only after every outstanding request has a measured receipt and all
-	 * accounting writes succeeded; it never resets usage or settled accounts.
+	 * Ordinary completion never clears uncertainty. Reconciliation resolves this
+	 * request after its receipt is persisted; other uncertain requests continue
+	 * to constrain their shared finite allowances. Usage and settlement are retained.
 	 */
 	async reconcileRequest(requestId: string, usage: TokenUsage): Promise<void> {
 		const measured = usageValue(usage)
@@ -536,6 +544,10 @@ export class TokenBudget {
 		} else {
 			await this.finishRequest(requestId, measured)
 		}
+		const receipt = this.ledger.finishedRequests.get(requestId)
+		if (receipt) receipt.unresolved = false
+		this.persist()
+		await this.flush()
 		if (this.ledger.requests.size === 0 && this.ledger.persistenceError === undefined) {
 			this.ledger.poisoned = false
 			this.persist()
@@ -574,7 +586,10 @@ export class TokenBudget {
 			).length,
 			unsettledChildren: this.children(this.node).filter((child) => !this.totals(child).closed)
 				.length,
-			poisoned: this.ledger.poisoned,
+			poisoned: this.admissionBlocked(),
+			unresolvedRequests: this.uncertainRequests().filter((request) =>
+				descendants.has(request.accountId),
+			).length,
 		}
 	}
 
@@ -595,6 +610,28 @@ export class TokenBudget {
 		if (this.ledger.persistenceError !== undefined) throw this.ledger.persistenceError
 	}
 
+	private uncertainRequests(): TokenBudgetRequestSnapshot[] {
+		return [...this.ledger.requests.values(), ...this.ledger.finishedRequests.values()].filter(
+			(request) => request.unresolved === true,
+		)
+	}
+	private admissionBlocked(): boolean {
+		if (this.ledger.poisoned || this.ledger.persistenceError !== undefined) return true
+		const uncertain = this.uncertainRequests()
+		if (uncertain.length === 0) return false
+		// An account cannot resume its own uncertain request, even without a cap.
+		if (uncertain.some((request) => request.accountId === this.accountId)) return true
+		let cursor = this.node
+		for (;;) {
+			if (cursor.limit > 0) {
+				const descendants = this.descendants(cursor)
+				if (uncertain.some((request) => descendants.has(request.accountId))) return true
+			}
+			if (cursor.parentId === undefined) return false
+			cursor = this.requireAccount(cursor.parentId)
+		}
+	}
+
 	private get node(): TokenBudgetAccountSnapshot {
 		return this.requireAccount(this.accountId)
 	}

package/src/runtime/query/executor.ts

@@ -11,8 +11,8 @@ import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import { renderToolSchema } from '../../registry/tool/schema.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
-import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js'
 import { SKILL_TOOL_NAME } from '../../tools/builtins/skill.js'
+import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import type { RunId, ToolUseId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
@@ -290,6 +290,7 @@ function parseArguments(raw: string): unknown {
 }
 
 export interface ToolExecutorConfig {
+	fileReadTracker?: FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -501,20 +502,7 @@ export class ToolExecutor {
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
-	private readonly readPaths: Set<string> = new Set()
-	private readonly readFingerprints: Map<string, string> = new Map()
-	private readonly fileReadTracker: FileReadTracker = {
-		recordRead: (key: string, content?: string) => {
-			this.readPaths.add(key)
-			// Only when the reader had the body. A tool that records a read
-			// without one leaves the previous fingerprint alone rather than
-			// clearing it, so a later write is still checked against the last
-			// body anyone actually saw.
-			if (content !== undefined) this.readFingerprints.set(key, fingerprintContent(content))
-		},
-		hasRead: (key: string) => this.readPaths.has(key),
-		fingerprint: (key: string) => this.readFingerprints.get(key),
-	}
+	private readonly fileReadTracker: FileReadTracker
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -532,6 +520,7 @@ export class ToolExecutor {
 				config.readToolCallBudgetEvents,
 			)
 		}
+		this.fileReadTracker = config.fileReadTracker ?? createFileReadTracker()
 		this.config = config
 		this.activityStore = activityStore
 		this.emitEvent = emitEvent
@@ -1211,6 +1200,7 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			toolName: name,
 			result: budgeted.output,
+			...(!budgeted.truncated ? this.resultPresentation(name, preparedInput, result) : {}),
 			isError: !result.success,
 			durationMs: Date.now() - startedAt,
 			outputLength: budgeted.originalLength,
@@ -1230,6 +1220,21 @@ export class ToolExecutor {
 		return visibleResult
 	}
 
+	private resultPresentation(name: string, input: unknown, result: ToolResult) {
+		if (!result.success) return {}
+		try {
+			const view = this.config.tools.get(name)?.presentResult?.(input, result)
+			if (view?.kind !== 'diff') return {}
+			const serialized = JSON.stringify(view)
+			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
+				return {}
+			return { presentation: view }
+		} catch {
+			// A presentation hook must not fail an already completed mutation.
+			return {}
+		}
+	}
+
 	private buildToolContext(
 		recordObservation: (observation: ToolResultObservation) => void = () => {},
 	): ToolContext {
@@ -1721,6 +1726,9 @@ export class ToolExecutor {
 			toolUseId: toolCall.id,
 			toolName,
 			result: output,
+			...(!postOverride && !budgeted.truncated && rawOutput === output
+				? this.resultPresentation(toolName, input, result)
+				: {}),
 			isError: effectiveIsError,
 			durationMs,
 			// Pre-truncation size, so a host can show "returned 2.1 MB" even

package/src/runtime/query/index.ts

@@ -157,6 +157,8 @@ import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
 
 export interface QueryParams {
+	/** Share observations across turns of one conversation and filesystem; otherwise run-local. */
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	/** One account shared with the task scheduler and descendant runs. */
 	budget?: TokenBudget
 	/** Canonical tree ledger; defaults to disk beside the root run. */
@@ -1731,6 +1733,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			// registry would answer about whatever the last run configured.
 			...(params.skillRegistry ? { skills: params.skillRegistry } : {}),
 			...(params.web ? { web: params.web } : {}),
+			...(params.fileReadTracker ? { fileReadTracker: params.fileReadTracker } : {}),
 			...(params.toolTimeoutMs !== undefined ? { toolTimeoutMs: params.toolTimeoutMs } : {}),
 			...(params.toolRetryBackoff !== undefined
 				? { toolRetryBackoff: params.toolRetryBackoff }

package/src/runtime/query/iteration/index.ts

@@ -54,7 +54,13 @@ import { toErrorMessage } from '../../../utils/error.js'
 import { stableDigest } from '../../../utils/hash.js'
 import { generateMessageId } from '../../../utils/id.js'
 import type { ToolCallOutcome } from '../executor.js'
+import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
+import {
+	type RequestContextSnapshot,
+	diffRequestContext,
+	snapshotRequestContext,
+} from '../request-context.js'
 import {
 	DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 	type RequestImageIdentity,
@@ -164,6 +170,14 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	private previousRequestContext: RequestContextSnapshot | undefined
+
+	private projectObservations(messages: Message[]): Message[] {
+		const config = this.ctx.compactionConfig
+		return config && config.strategy !== 'disabled' && config.deduplicateObservations !== false
+			? projectObservationContext(messages, this.ctx.tools, config.preserveToolResultsFrom)
+			: messages
+	}
 	/** Rich tool blocks already reported; durable history is scanned every turn. */
 	private readonly warnedRichToolResults = new Set<string>()
 	/**
@@ -614,7 +628,7 @@ export class IterationOrchestrator {
 						? [...baseMessages, createSystemMessage(stepPreamble)]
 						: [...baseMessages]
 					const messages = projectRequestRichContent(
-						requestHistory,
+						this.projectObservations(requestHistory),
 						this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 					)
 					await this.reportUnsupportedToolResults(messages)
@@ -664,6 +678,16 @@ export class IterationOrchestrator {
 					}
 
 					if (this.ctx.pluginManager) {
+						const snapshot = snapshotRequestContext(messages)
+						const context = Object.freeze({
+							snapshot,
+							...(this.previousRequestContext
+								? {
+										change: diffRequestContext(this.previousRequestContext, snapshot),
+									}
+								: {}),
+						})
+						this.previousRequestContext = snapshot
 						const hookResults = await this.ctx.pluginManager.executeHooks(
 							'pre_llm_call',
 							{
@@ -673,6 +697,7 @@ export class IterationOrchestrator {
 								// Built inside the guard: a run with no plugins installed
 								// pays nothing for a projection nobody reads.
 								request: Object.freeze({
+									context,
 									model: stepModel,
 									// Copied per turn, not handed over live: these are the
 									// run's own message objects, and a hook writing into
@@ -752,6 +777,7 @@ export class IterationOrchestrator {
 							cacheControl: { type: 'auto' },
 							...(runConfig.thinking ? { thinking: runConfig.thinking } : {}),
 							...(runConfig.effort ? { effort: runConfig.effort } : {}),
+							...(!forceFinalize && runConfig.webSearch ? { webSearch: runConfig.webSearch } : {}),
 							// Thread the run abort into the model call so a Stop tears the
 							// in-flight turn down (provider passes it to fetch; the consumer
 							// also races it). Inert when never aborted.
@@ -2424,7 +2450,7 @@ export class IterationOrchestrator {
 				),
 			]
 			const finalMessages = projectRequestRichContent(
-				finalHistory,
+				this.projectObservations(finalHistory),
 				this.ctx.runConfig.maxRequestRichContentBytes ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 			)
 			await this.reportUnsupportedToolResults(finalMessages)

package/src/runtime/query/iteration/stream-turn.ts

@@ -1,5 +1,8 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
-import { assertNativeStructuredOutputSupported } from '../../../provider/capabilities.js'
+import {
+	assertHostedWebSearchSupported,
+	assertNativeStructuredOutputSupported,
+} from '../../../provider/capabilities.js'
 import { isProviderRequestError } from '../../../provider/errors.js'
 import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
 import {
@@ -155,6 +158,7 @@ export async function* streamProviderTurn(
 	},
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
 	assertNativeStructuredOutputSupported(provider, params)
+	assertHostedWebSearchSupported(provider, params)
 	// The `chat {model}` span the GenAI conventions require. There was none:
 	// `chatSpanName` existed with zero call sites, so a trace carried no LLM
 	// latency at all and the token counts landed on the iteration span
@@ -340,6 +344,15 @@ export async function* streamProviderTurn(
 				recordTimeToFirstToken(params.model, Date.now() - callStartedAt)
 			}
 
+			if (chunk.delta.hostedTool) {
+				await emitEvent({
+					type: 'hosted_tool',
+					runId,
+					iteration,
+					tool: chunk.delta.hostedTool,
+				})
+				yield* drainPending()
+			}
 			if (chunk.delta.citation) citations.push(chunk.delta.citation)
 
 			const reasoning = chunk.delta.reasoning

package/src/runtime/query/observation-context.ts

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto'
+import { findRetainedIndices } from '../../compaction/retention.js'
+import { estimateMessageTokens } from '../../compaction/token-estimate.js'
+import { isClearedToolResult } from '../../compaction/tool-result-editing.js'
+import type { Message, ToolMessage } from '../../types/message/index.js'
+import type { ToolRegistryContract } from '../../types/tool/index.js'
+
+/**
+ * Request-only exact observation masking. Every reference targets a full result
+ * in THIS projection. Recompute from canonical history, never from yesterday's
+ * mask, so removing a former representative cannot leave a dangling reference.
+ * No tool executions are skipped, and equal output is not a freshness claim.
+ */
+export function projectObservationContext(
+	messages: Message[],
+	tools: Pick<ToolRegistryContract, 'get'>,
+	preserveToolResultsFrom: readonly string[] = [],
+): Message[] {
+	const calls = new Map<string, { name: string; arguments: string } | null>()
+	for (const message of messages) {
+		if (message.role !== 'assistant') continue
+		for (const call of message.toolCalls ?? []) {
+			// Ambiguous IDs cannot prove which observation belongs to which call.
+			if (calls.has(call.id)) calls.set(call.id, null)
+			else calls.set(call.id, call.metadata?.inputTruncated ? null : call.function)
+		}
+	}
+	const resultCounts = new Map<string, number>()
+	for (const message of messages) {
+		if (message.role === 'tool') {
+			resultCounts.set(message.toolCallId, (resultCounts.get(message.toolCallId) ?? 0) + 1)
+		}
+	}
+	const protectedIndices = findRetainedIndices(messages)
+	const representatives = new Map<string, ToolMessage>()
+	let projected: Message[] | undefined
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index]
+		if (
+			!message ||
+			message.role !== 'tool' ||
+			message.isError ||
+			typeof message.content !== 'string' ||
+			message.content.length < 1024 ||
+			isClearedToolResult(message.content) ||
+			resultCounts.get(message.toolCallId) !== 1
+		)
+			continue
+		const call = calls.get(message.toolCallId)
+		if (!call || preserveToolResultsFrom.includes(call.name)) continue
+		const definition = tools.get(call.name)
+		if (!definition) continue
+		try {
+			const input = definition.inputSchema.safeParse(JSON.parse(call.arguments))
+			if (
+				!input.success ||
+				definition.isReadOnly?.(input.data) !== true ||
+				definition.isDestructive?.(input.data) === true
+			)
+				continue
+		} catch {
+			// Classification is advisory; invalid input or a broken custom predicate
+			// must leave evidence intact, not abort the request.
+			continue
+		}
+		// Exact arguments intentionally: equivalent JSON with different formatting
+		// is a missed optimization, not permission to merge different file ranges.
+		const key = createHash('sha256')
+			.update(JSON.stringify([call.name, call.arguments, message.content]))
+			.digest('hex')
+		const representative = representatives.get(key)
+		if (!representative) {
+			representatives.set(key, message)
+			continue
+		}
+		if (protectedIndices.has(index)) continue
+		const replacement: ToolMessage = {
+			...message,
+			content: `[Duplicate observation: this call returned exactly the same text as tool result ${JSON.stringify(representative.toolCallId)}, whose full content remains in this request. Both calls occurred. This is historical evidence, not a claim that external state is still unchanged.]`,
+		}
+		if (estimateMessageTokens(replacement) >= estimateMessageTokens(message)) continue
+		projected ??= [...messages]
+		projected[index] = replacement
+	}
+	return projected ?? messages
+}

package/src/runtime/query/request-context.ts

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto'
+import type { Message, MessageRole } from '../../types/message/index.js'
+
+/** A content block present at the SDK's provider-input boundary, not a file freshness claim. */
+export interface RequestContextPart {
+	readonly messageIndex: number
+	readonly partIndex: number
+	readonly role: MessageRole
+	readonly kind: 'text' | 'image' | 'document' | 'stored' | 'tool-call'
+	readonly digest: string
+	readonly toolCallId?: string
+	readonly isError?: boolean
+}
+
+export interface RequestContextSnapshot {
+	readonly boundary: 'provider-input'
+	readonly parts: readonly RequestContextPart[]
+}
+
+export interface RequestContextChange {
+	/** Parts from the earlier snapshot no longer present, including replaced content. */
+	readonly removed: readonly RequestContextPart[]
+	/** Parts in the new snapshot not present before. */
+	readonly added: readonly RequestContextPart[]
+}
+
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_key, item: unknown) => {
+		if (!item || typeof item !== 'object' || Array.isArray(item)) return item
+		return Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+	})
+}
+
+/**
+ * Inspect supplied messages after compaction and request projection. No content
+ * is retained in the snapshot. A digest identifies exact blocks, not semantic
+ * knowledge, token counts, file versions or provider-private reasoning replay.
+ */
+export function snapshotRequestContext(messages: readonly Message[]): RequestContextSnapshot {
+	const parts: RequestContextPart[] = []
+	for (const [messageIndex, message] of messages.entries()) {
+		let partIndex = 0
+		const add = (kind: RequestContextPart['kind'], payload: unknown, toolCallId?: string) => {
+			parts.push(
+				Object.freeze({
+					messageIndex,
+					partIndex: partIndex++,
+					role: message.role,
+					kind,
+					digest: createHash('sha256').update(canonicalJson(payload)).digest('hex'),
+					...(toolCallId !== undefined ? { toolCallId } : {}),
+					...(message.role === 'tool' ? { isError: message.isError === true } : {}),
+				}),
+			)
+		}
+		const callId = message.role === 'tool' ? message.toolCallId : undefined
+		if (typeof message.content === 'string') add('text', message.content, callId)
+		else if (Array.isArray(message.content)) {
+			for (const block of message.content) {
+				if (block.type === 'text') add('text', block.text, callId)
+				else add(block.type, block, callId)
+			}
+		}
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				add(attachment.type ?? 'image', attachment)
+			}
+		}
+		if (message.role === 'assistant') {
+			for (const call of message.toolCalls ?? []) {
+				add('tool-call', [call.function.name, call.function.arguments], call.id)
+			}
+		}
+	}
+	return Object.freeze({ boundary: 'provider-input', parts: Object.freeze(parts) })
+}
+
+const key = (part: RequestContextPart): string =>
+	JSON.stringify([part.role, part.kind, part.toolCallId, part.isError, part.digest])
+
+/** Compare occurrences, not sets: removing one of two identical blocks is a removal. */
+export function diffRequestContext(
+	previous: RequestContextSnapshot,
+	next: RequestContextSnapshot,
+): RequestContextChange {
+	const unmatched = new Map<string, RequestContextPart[]>()
+	for (const part of previous.parts) {
+		const identity = key(part)
+		const occurrences = unmatched.get(identity) ?? []
+		occurrences.push(part)
+		unmatched.set(identity, occurrences)
+	}
+	const added: RequestContextPart[] = []
+	for (const part of next.parts) {
+		const occurrences = unmatched.get(key(part))
+		if (occurrences?.length) occurrences.pop()
+		else added.push(part)
+	}
+	const removed = [...unmatched.values()]
+		.flat()
+		.sort((a, b) => a.messageIndex - b.messageIndex || a.partIndex - b.partIndex)
+	return Object.freeze({ removed: Object.freeze(removed), added: Object.freeze(added) })
+}

package/src/runtime/query/request-rich-content.ts

@@ -45,20 +45,25 @@ export interface RequestImageIdentity {
 const userMarker = (kind: RichKind): string =>
 	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; attach it again in a new message if it is still needed.]`
 
+// Losing an observation does not undo the action that produced it. This
+// projection knows the result bytes, not whether repeating its tool is safe.
+const toolRecovery =
+	'The original result is retained in conversation history, but this content is not available in the current model request. Recover it from an available saved artifact or a read-only observation if needed. Do not repeat a state-changing action merely to recover its output.'
+
 const toolMarker = (kind: RichKind): string =>
-	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit; call the producing tool again if it is still needed.]`
+	`[${kind} omitted from this model request to keep the accumulated rich-content payload within its configured size limit. ${toolRecovery}]`
 
 const rejectedUserImageMarker = (): string =>
 	'[image omitted from this model request because the provider rejected this image; attach a corrected image in a new message if it is still needed.]'
 
 const rejectedToolImageMarker = (): string =>
-	'[image omitted from this model request because the provider rejected this image; call the producing tool again after correcting its image source if it is still needed.]'
+	`[image omitted from this model request because the provider rejected this image. ${toolRecovery} Correct the image source before presenting it again.]`
 
 const invalidUserImageMarker = (): string =>
 	'[image omitted from this model request because its encoded bytes are not a complete supported raster matching the declared media type; attach a corrected image in a new message if it is still needed.]'
 
 const invalidToolImageMarker = (): string =>
-	'[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type; call the tool again after correcting its image source if it is still needed.]'
+	`[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type. ${toolRecovery} Correct the image source before presenting it again.]`
 
 function assertInlineAttachment(
 	attachment: MessageAttachment,

package/src/runtime/query/review-policy.ts

@@ -25,6 +25,7 @@ import type { ToolRegistry } from '../../registry/tool/execute.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../types/hitl/index.js'
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
+import type { RunId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
 
 export type ReviewMode =
@@ -141,6 +142,8 @@ export function batchNeedsReview(
 
 /** The batch a person is asked about. */
 export interface ToolReviewRequest {
+	/** Originating run, preserved by createReviewHandler for host attribution. */
+	readonly runId?: RunId
 	readonly toolCalls: readonly ToolCallSummary[]
 }
 
@@ -204,7 +207,10 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		if (mode === 'auto' || !prompt || remembered.all) {
 			return { action: 'approve_tools' }
 		}
-		const answer = await prompt({ toolCalls: request.toolCalls })
+		const answer = await prompt({
+			runId: request.runId,
+			toolCalls: request.toolCalls,
+		})
 		switch (answer.kind) {
 			case 'approve':
 				return { action: 'approve_tools' }

package/src/runtime/query/tooling.ts

@@ -20,6 +20,7 @@ import { ToolExecutor } from './executor.js'
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
 export interface ToolingBootstrapConfig {
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -67,6 +68,7 @@ export class ToolingBootstrap {
 		return new ToolExecutor(
 			{
 				tools: config.tools,
+				...(config.fileReadTracker ? { fileReadTracker: config.fileReadTracker } : {}),
 				runId: config.runId,
 				workingDirectory: config.workingDirectory,
 				...(config.additionalDirectories?.length

package/src/sandbox/file-walk-program.ts

@@ -51,6 +51,14 @@ async function run() {
     try { canonicalRoot = await fs.realpath(plan.root); }
     catch (error) { if (missing(error)) return; throw error; }
     if (canonicalRoot !== path.resolve(plan.root)) throw new Error('File walk root follows a symbolic link; use its authorized real directory');
+    const rootInfo = await fs.lstat(plan.root);
+    if (rootInfo.isFile()) {
+      visit(++visited);
+      if (matchers.some(matcher => matcher.test(path.basename(plan.root)))) {
+        await write({type:'entry', path:plan.root, size:rootInfo.size});
+      }
+      return;
+    }
     let start = plan.root;
     for (const part of plan.prefix) {
       start = path.join(start, part);