@namzu/sdk 38.2.1 → 39.0.0

package/src/runtime/query/iteration/phases/advisory.ts

@@ -1,3 +1,4 @@
+import type { AdvisoryTurnContext } from '../../../../advisory/executor.js'
 import { serializeState } from '../../../../compaction/serializer.js'
 import { NAMZU } from '../../../../constants/telemetry/index.js'
 import type { AdvisoryRequest, TriggerEvaluationState } from '../../../../types/advisory/index.js'
@@ -47,6 +48,7 @@ export async function runAdvisoryPhase(
 	ctx: IterationContext,
 	iterationNum: number,
 	response: ChatCompletionResponse,
+	turn?: AdvisoryTurnContext,
 ): Promise<void> {
 	const advisoryCtx = ctx.advisoryCtx
 	if (!advisoryCtx) return
@@ -105,6 +107,7 @@ export async function runAdvisoryPhase(
 	try {
 		const executionResult = await advisoryCtx.executor.consult(advisor, request, {
 			messages: ctx.runMgr.messages,
+			...(turn ? { turn } : {}),
 			workingStateSummary,
 			toolCatalog: ctx.tools.toLLMTools(ctx.allowedTools),
 			iteration: iterationNum,

package/src/runtime/query/iteration/phases/context.ts

@@ -26,6 +26,7 @@ import type {
 	AgentRunConfig,
 	BeforeStep,
 	PrepareStepChain,
+	PrepareStepContext,
 	RunEvent,
 	StepResult,
 	StopCondition,
@@ -229,6 +230,7 @@ export interface IterationContext {
 
 	/** Host hook that shapes each step before the model call. */
 	readonly prepareStep?: PrepareStepChain
+	readonly captureRunEvidence?: PrepareStepContext['captureRunEvidence']
 	readonly beforeStep?: BeforeStep
 }
 

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -220,6 +220,9 @@ export async function* runToolReview(
 			toolCall.authorization = {
 				decision: gateResult.decision,
 				...(gateResult.reason ? { reason: gateResult.reason } : {}),
+				...(gateResult.decision === 'review' && gateResult.matchedRule
+					? { explicitReview: true as const }
+					: {}),
 			}
 		}
 

package/src/runtime/query/iteration/provider-rejected-image.ts

@@ -1,4 +1,5 @@
 import { isProviderRequestError } from '../../../provider/errors.js'
+import type { Message } from '../../../types/message/index.js'
 import type {
 	ChatCompletionParams,
 	LLMProvider,
@@ -42,7 +43,8 @@ function isAcceptedChunk(chunk: StreamChunk): boolean {
 			chunk.delta.citation ||
 			chunk.finishReason !== undefined ||
 			chunk.usage !== undefined ||
-			chunk.replayState !== undefined,
+			chunk.replayState !== undefined ||
+			chunk.textParts !== undefined,
 	)
 }
 
@@ -62,8 +64,10 @@ export async function* streamWithProviderRejectedImageRecovery(
 	provider: LLMProvider,
 	params: ChatCompletionParams,
 	onAccepted: (identity: RequestImageIdentity) => Promise<void>,
+	onRequest?: (messages: readonly Message[]) => void,
 ): AsyncIterable<StreamChunk> {
 	const candidate = findSingleRequestImage(params.messages)
+	onRequest?.(params.messages)
 	if (candidate === null) {
 		yield* provider.chatStream(params)
 		return
@@ -90,6 +94,7 @@ export async function* streamWithProviderRejectedImageRecovery(
 	}
 	let accepted = false
 	let retryReportedError = false
+	onRequest?.(retryParams.messages)
 	for await (const chunk of provider.chatStream(retryParams)) {
 		if (chunk.error !== undefined) retryReportedError = true
 		if (!accepted && isAcceptedChunk(chunk)) {

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

@@ -4,6 +4,7 @@ import {
 	assertNativeStructuredOutputSupported,
 } from '../../../provider/capabilities.js'
 import { isProviderRequestError } from '../../../provider/errors.js'
+import { StreamTextAccumulator } from '../../../provider/stream-text.js'
 import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
 import {
 	recordModelDuration,
@@ -14,7 +15,12 @@ import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { mergeTokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
-import type { Citation, ReasoningBlock } from '../../../types/message/index.js'
+import type {
+	AssistantTextPart,
+	Citation,
+	Message,
+	ReasoningBlock,
+} from '../../../types/message/index.js'
 import { ProviderError } from '../../../types/provider/errors.js'
 import type {
 	ChatCompletionResponse,
@@ -54,6 +60,8 @@ function synthesizeMessageStopReason(
 export interface StreamingTurnResult {
 	response: ChatCompletionResponse
 	messageId: import('../../../types/ids/index.js').MessageId
+	/** Captured only for host review, at the provider-chain dispatch boundary. */
+	requestMessages?: readonly Message[]
 }
 
 /**
@@ -100,6 +108,7 @@ async function settleCancelledTurn(args: {
 	messageId: import('../../../types/ids/index.js').MessageId
 	usage: ChatCompletionResponse['usage']
 	text: string
+	textParts?: readonly AssistantTextPart[]
 	model: string
 	startedAt: number
 	span: Span
@@ -124,6 +133,7 @@ async function settleCancelledTurn(args: {
 			stopReason: 'cancelled',
 			usage: args.usage,
 			content: args.text || undefined,
+			...(args.textParts ? { textParts: args.textParts } : {}),
 		})
 	} catch {
 		// Best effort. The cancellation is the news.
@@ -156,6 +166,7 @@ export async function* streamProviderTurn(
 	imageRecovery?: {
 		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
 	},
+	captureRequest = false,
 ): AsyncGenerator<RunEvent, StreamingTurnResult> {
 	assertNativeStructuredOutputSupported(provider, params)
 	assertHostedWebSearchSupported(provider, params)
@@ -181,7 +192,7 @@ export async function* streamProviderTurn(
 
 	let id = ''
 	const model = ''
-	let textBuf = ''
+	const text = new StreamTextAccumulator()
 	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
 	let usage: ChatCompletionResponse['usage'] = {
 		promptTokens: 0,
@@ -239,9 +250,21 @@ export async function* streamProviderTurn(
 		...params,
 		stream: true,
 	} satisfies import('../../../types/provider/index.js').ChatCompletionParams
+	let requestMessages: readonly Message[] | undefined
+	const observeRequest = captureRequest
+		? (messages: readonly Message[]) => {
+				requestMessages = structuredClone(messages)
+			}
+		: undefined
+	if (!imageRecovery) observeRequest?.(streamParams.messages)
 	const stream = (
 		imageRecovery
-			? streamWithProviderRejectedImageRecovery(provider, streamParams, imageRecovery.onAccepted)
+			? streamWithProviderRejectedImageRecovery(
+					provider,
+					streamParams,
+					imageRecovery.onAccepted,
+					observeRequest,
+				)
 			: provider.chatStream(streamParams)
 	) as AsyncIterable<StreamChunk>
 
@@ -328,6 +351,7 @@ export async function* streamProviderTurn(
 			}
 			if (!id && chunk.id) id = chunk.id
 			if (chunk.replayState !== undefined) replayState = chunk.replayState
+			text.push(chunk)
 
 			// The first delta of the turn, of ANY kind — text, reasoning or a
 			// tool call. namzu streams, so perceived latency is dominated by
@@ -401,13 +425,13 @@ export async function* streamProviderTurn(
 			}
 
 			if (chunk.delta.content) {
-				textBuf += chunk.delta.content
 				await emitEvent({
 					type: 'text_delta',
 					runId,
 					iteration,
 					messageId,
 					text: chunk.delta.content,
+					...(chunk.delta.textPart ? { textPart: chunk.delta.textPart } : {}),
 				})
 				yield* drainPending()
 			}
@@ -518,7 +542,8 @@ export async function* streamProviderTurn(
 				iteration,
 				messageId,
 				usage,
-				text: textBuf,
+				text: text.text,
+				textParts: text.textParts,
 				model: params.model,
 				startedAt: callStartedAt,
 				span: chatSpan,
@@ -661,7 +686,8 @@ export async function* streamProviderTurn(
 		messageId,
 		stopReason,
 		usage,
-		content: textBuf || undefined,
+		content: text.text || undefined,
+		...(text.textParts ? { textParts: text.textParts } : {}),
 	})
 	yield* drainPending()
 
@@ -714,7 +740,8 @@ export async function* streamProviderTurn(
 		model: model || params.model,
 		message: {
 			role: 'assistant',
-			content: textBuf.length > 0 ? textBuf : null,
+			content: text.text || null,
+			...(text.textParts ? { textParts: text.textParts } : {}),
 			toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
 			...(reasoningBlocks.length > 0 ? { reasoning: reasoningBlocks } : {}),
 			...(replayState !== undefined ? { replayState } : {}),
@@ -746,5 +773,5 @@ export async function* streamProviderTurn(
 	chatSpan.setStatus({ code: SpanStatusCode.OK })
 	chatSpan.end()
 
-	return { response, messageId }
+	return { response, messageId, ...(requestMessages ? { requestMessages } : {}) }
 }

package/src/runtime/query/resume-pending.ts

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from 'node:util'
 
 import type { RunPersistence } from '../../manager/run/persistence.js'
+import { ToolExecutionCollector } from '../../store/run/tool-executions.js'
 import type {
 	CheckpointId,
 	HITLResumeDecision,
@@ -9,6 +10,7 @@ import type {
 } from '../../types/hitl/index.js'
 import type { AssistantMessage, Message, ToolCall } from '../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
+import type { ToolExecutionSnapshot } from '../../types/run/store.js'
 import type { Logger } from '../../utils/logger.js'
 import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
 import { PendingAnswers } from './question-park.js'
@@ -192,24 +194,11 @@ function planQuestionResume(
 }
 
 /**
- * Decide whether a checkpoint left behind a batch that was PART-WAY
- * through executing when the process died.
- *
- * The ordinary repair for an unanswered assistant turn — strip it and let
- * the model re-decide — is right when nothing ran: the calls were still
- * awaiting a decision, so re-deciding costs only a round trip. It is
- * exactly wrong when some of them already ran, because re-deciding means
- * re-executing, and a tool that charged a card does not become idempotent
- * on the second attempt.
- *
- * The discriminator is the transcript: a tool-review park records the
- * checkpoint BEFORE any execution, so it has no completed calls and takes
- * the cheap path unchanged. One or more completions means execution had
- * begun, which is a resume, not a fresh decision.
- *
- * The calls that did NOT complete are executed here for the first time,
- * through the ordinary executor — so every guard, permission check and
- * probe still applies to them.
+ * Preserve a restored batch's recorded and explicitly unknown outcomes.
+ * `completed` comes from recoverCompletedCalls: missing entries are eligible
+ * only after a complete scan establishes that they have no recorded start.
+ * A started tool with no trustworthy completion is carried as an unknown
+ * outcome, not executed again. An untouched batch uses ordinary history repair.
  */
 export function planCrashResume(
 	checkpoint: IterationCheckpoint,
@@ -219,13 +208,19 @@ export function planCrashResume(
 	const assistant = lastUnansweredBatch(checkpoint.messages)?.assistant
 	const calls = assistant?.toolCalls
 	if (!assistant || !calls || calls.length === 0) return null
+	// Only the current tail can be resumed in place. An older incomplete
+	// batch belongs to history repair; re-appending it would move its action
+	// past a newer operator message and silently reorder the conversation.
+	const ownerIndex = checkpoint.messages.lastIndexOf(assistant)
+	if (checkpoint.messages.slice(ownerIndex + 1).some((message) => message.role !== 'tool'))
+		return null
 
 	const done = calls.filter((tc) => completed.has(tc.id))
 	if (done.length === 0) return null
 
 	log.warn('Checkpoint holds a tool batch that was part-way through executing', {
 		'namzu.checkpoint.id': checkpoint.id,
-		'namzu.runtime.completed': done.length,
+		'namzu.runtime.recovered': done.length,
 		'namzu.runtime.total': calls.length,
 		'namzu.runtime.remaining': calls
 			.filter((tc) => !completed.has(tc.id))
@@ -336,37 +331,67 @@ function modifiedCallIds(decision: HITLResumeDecision): ReadonlySet<string> {
 }
 
 /**
- * Results the run already produced for calls in `toolCalls`.
- *
- * Read from the transcript, which records a `tool_completed` per tool as
- * it finishes — durable long before the batch settles. Scoped to the calls
- * being resumed so an id from an earlier turn can never answer this one.
- *
- * A failure to read is not fatal: the worst case is the behaviour that
- * existed before this recovery, and refusing to resume because a log could
- * not be read would be a strictly worse trade.
+ * Recover completed results and close interrupted calls with unknown outcomes.
+ * Only a complete execution scan can authorize the absence of a start record.
+ * Unreadable, partial or contradictory evidence never becomes permission to
+ * replay; an explicitly answered durable question may re-enter its own tool.
  */
 export async function recoverCompletedCalls(
 	runMgr: RunPersistence,
 	toolCalls: readonly ToolCall[],
 	log: Logger,
+	options: { answers?: PendingAnswers; signal?: AbortSignal } = {},
 ): Promise<Map<string, { result: string; isError: boolean }>> {
 	const recovered = new Map<string, { result: string; isError: boolean }>()
+	let snapshot: ToolExecutionSnapshot | undefined
 	try {
-		const completed = await runMgr.getRunStore().readCompletedTools()
-		for (const call of toolCalls) {
-			const record = completed.get(call.id)
-			if (record) recovered.set(call.id, { result: record.result, isError: record.isError })
+		const store = runMgr.getRunStore()
+		if (store.readToolExecutions) {
+			snapshot = await store.readToolExecutions(
+				toolCalls.map((call) => call.id),
+				options.signal,
+			)
+		} else {
+			const collector = new ToolExecutionCollector(
+				runMgr.id,
+				toolCalls.map((call) => call.id),
+			)
+			for (const event of await store.readEvents({ integrity: 'strict' })) {
+				options.signal?.throwIfAborted()
+				collector.accept(event)
+			}
+			snapshot = collector.finish()
 		}
 	} catch (error) {
+		if (options.signal?.aborted) throw error
 		log.warn('Could not read the transcript to recover completed tool calls', {
 			'exception.message': error instanceof Error ? error.message : String(error),
 		})
-		return new Map()
+	}
+	for (const call of toolCalls) {
+		const record = snapshot?.records.get(call.id)
+		if (
+			snapshot?.complete &&
+			(!record || (record.toolName === call.function.name && record.toolUseId === call.id))
+		) {
+			if (!record) continue // Complete evidence proves this call has no recorded start.
+			if (record.status === 'completed') {
+				recovered.set(call.id, { result: record.result, isError: record.isError })
+				continue
+			}
+		}
+		// The validated checkpoint and explicit answer own this re-entry even
+		// when the prior event store is unavailable. No sibling inherits it.
+		if ([...(options.answers?.entries() ?? [])].some(([id]) => isPauseForCall(id, call.id)))
+			continue
+		recovered.set(call.id, {
+			result: `Tool execution was interrupted and no trustworthy completion is available for \`${call.function.name}\`. Its outcome is unknown. This resume did not execute it again. Verify external state before deciding whether another call is needed; do not replay a state-changing action to recover its output.`,
+			isError: true,
+		})
 	}
 
 	if (recovered.size > 0) {
-		log.info('Recovered tool results from the transcript instead of re-executing', {
+		log.info('Restored recorded or unknown tool outcomes without re-executing', {
 			'namzu.runtime.recovered': recovered.size,
 			'namzu.runtime.of_calls': toolCalls.length,
 		})
@@ -452,13 +477,13 @@ function synthesizeResponse(assistant: AssistantMessage): ChatCompletionResponse
 }
 
 /**
- * Tool calls in the history that no `tool_result` answers.
- *
- * The set worth asking the transcript about: an already-answered call's
- * result is in the history and needs no recovery.
+ * All calls owned by the last incomplete batch. Applying a resume plan
+ * reconstructs that entire batch, including any partial results already in
+ * the checkpoint. Those answered siblings must also be recovered, or their
+ * missing prior-result entries would let the executor repeat them.
  */
-export function unansweredToolCalls(messages: readonly Message[]): ToolCall[] {
-	return lastUnansweredBatch(messages)?.unanswered ?? []
+export function interruptedToolCalls(messages: readonly Message[]): ToolCall[] {
+	return lastUnansweredBatch(messages)?.assistant.toolCalls ?? []
 }
 
 function lastUnansweredBatch(

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

@@ -1,9 +1,9 @@
 /**
- * How a run resolves the calls no rule decided.
+ * How a run resolves calls routed to review.
  *
  * An authorization rule says what a tool may do. A review policy says what
- * happens to everything the rules did not cover: the batch the gate routed
- * to REVIEW. The two axes are separate on purpose — a rule is a durable
+ * happens to calls the rules did not cover or explicitly routed to REVIEW.
+ * The two axes are separate on purpose — a rule is a durable
  * statement an operator reviewed, and a mode is a property of ONE run, the
  * difference between "we never force-push" and "this run is unattended".
  *
@@ -132,12 +132,14 @@ export function isReviewExempt(
 
 export type ReviewExemption = (name: string, input: unknown) => boolean
 
-/** A batch needs review when any call mutates state: flagged destructive, or not exempt. */
+/** Review explicit requests and calls that are destructive or not exempt. */
 export function batchNeedsReview(
 	toolCalls: readonly ToolCallSummary[],
 	exempt: ReviewExemption,
 ): boolean {
-	return toolCalls.some((tc) => tc.isDestructive || !exempt(tc.name, tc.input))
+	return toolCalls.some(
+		(tc) => tc.authorization?.explicitReview || tc.isDestructive || !exempt(tc.name, tc.input),
+	)
 }
 
 /** The batch a person is asked about. */
@@ -194,14 +196,16 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		if (
 			mode === 'accept-edits' &&
 			request.toolCalls.every(
-				(tc) => !tc.isDestructive && (ACCEPT_EDITS_TOOLS.has(tc.name) || exempt(tc.name, tc.input)),
+				(tc) =>
+					!tc.authorization?.explicitReview &&
+					!tc.isDestructive &&
+					(ACCEPT_EDITS_TOOLS.has(tc.name) || exempt(tc.name, tc.input)),
 			)
 		) {
 			return { action: 'approve_tools' }
 		}
-		// Reads were approved above. Anything that reached here would change
-		// something, and plan mode's answer is the same every time: not now,
-		// tell the user what you would do.
+		// Ordinary reads were approved above. Remaining calls either change
+		// state or carry explicit review; plan mode does not grant that authority.
 		if (mode === 'plan') return { action: 'reject_tools', feedback: PLAN_MODE_REFUSAL }
 		if (mode === 'strict') return { action: 'reject_tools', feedback: STRICT_MODE_REFUSAL }
 		if (mode === 'auto' || !prompt || remembered.all) {

package/src/runtime/query/sandbox-lifecycle.ts

@@ -138,6 +138,9 @@ export async function acquireSandbox(options: {
 		runSignal.addEventListener('abort', onAbort, { once: true })
 	})
 	const timedOut = new Promise<{ readonly kind: 'timed_out'; readonly error: Error }>((resolve) => {
+		// An unlimited run still observes cancellation; Infinity must never reach
+		// setTimeout, where Node would coerce it to a one-millisecond deadline.
+		if (options.timeoutMs === Number.POSITIVE_INFINITY) return
 		timer = setTimeout(() => {
 			timeoutError = acquisitionTimeoutError(options.timeoutMs)
 			operationController.abort(timeoutError)

package/src/runtime/query/tool-output-budget.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { digest, spillManifest } from '../../store/evidence/format.js'
 
 /**
  * Model-visible size cap for a single tool result.
@@ -104,6 +105,8 @@ export interface ToolOutputBudgetResult {
 	readonly truncated: boolean
 	/** Where the full output was written, when it was. */
 	readonly spillPath?: string
+	/** Digest of the bounded chunk manifest, recorded at retention time. */
+	readonly spillIntegrity?: string
 }
 
 /**
@@ -155,6 +158,10 @@ export interface ApplyToolOutputBudgetOptions {
 	readonly toolUseId: string
 	readonly output: string
 	readonly maxChars: number
+	/** Optional condensed presentation; used only after authenticated retention of output. */
+	readonly preview?: string
+	/** Smaller preview only after the full output and its integrity manifest are saved. */
+	readonly retainedPreviewChars?: number
 	/** An omission notice that shares the text budget, never extends it. */
 	readonly notice?: string
 	/**
@@ -168,12 +175,10 @@ export interface ApplyToolOutputBudgetOptions {
 /**
  * Bound a tool result to the model-visible budget.
  *
- * Spilling beats truncating on every axis that matters: nothing is lost,
- * tokens are paid only if the agent decides the rest is worth re-reading,
- * and retrieval uses `read`/`grep` — tools it already has — rather than a
- * new affordance. A hosted agent runtime does the same thing above 100k
- * characters. Middle-elision is the fallback for a run with no directory
- * to write to.
+ * Retention keeps the original while bounding its model-visible preview.
+ * The host owns the recovery route and its permissions; a spill path is not
+ * proof that workspace read/grep tools can access it. Middle-elision is the
+ * fallback for a run with no directory to write to.
  *
  * The preview keeps head AND tail because the two ends carry different
  * information: the head has the schema/opening of a document, the tail has
@@ -194,26 +199,65 @@ export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolO
 			: Math.max(0, limit - notice.length - (notice && output ? 2 : 0))
 	const withNotice = (text: string) => [text, notice].filter(Boolean).join('\n\n')
 
-	if (textBudget === undefined || originalLength <= textBudget) {
+	const preview =
+		opts.preview !== undefined && opts.preview.length < originalLength ? opts.preview : undefined
+	if (preview === undefined && (textBudget === undefined || originalLength <= textBudget)) {
 		return { output: withNotice(output), originalLength, truncated: false }
 	}
 
-	const spillPath = opts.spillDir
+	const retained = opts.spillDir
 		? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
 		: undefined
 
+	const spillPath = retained?.path
 	const recovery = spillPath
 		? [
 				`${SPILL_MARKER} ${spillPath}`,
-				'Read a specific window with `read` (offset/limit) or search it with `grep`. Do NOT read it whole — that is what exceeded the budget.',
+				'This path identifies retained output, not the original input. Use the host-authorized retained-output recovery tools when available; the path does not grant filesystem access. A fresh observation of the original input cannot recover its earlier contents. If recovery is unavailable, report the missing detail; do not replay the original action.',
 			].join('\n')
 		: 'The full output was not retained. Use a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.'
+	const requestedPreview = opts.retainedPreviewChars
+	// Separate the spill threshold from the cost of carrying its preview on every
+	// later request. Failed retention must not silently discard additional text.
+	// A small configured preview still needs room for the durable recovery path.
+	const previewLimit =
+		retained?.integrity &&
+		requestedPreview !== undefined &&
+		Number.isFinite(requestedPreview) &&
+		requestedPreview > 0
+			? Math.min(limit as number, Math.floor(requestedPreview))
+			: (limit as number)
+	const previewTextBudget = Math.max(0, previewLimit - notice.length - (notice && output ? 2 : 0))
+	const minimumRecoveryChars = `\n[... omitted ...]\n${SPILL_MARKER} ${spillPath}\n`.length
+	const effectiveTextBudget =
+		previewTextBudget > minimumRecoveryChars ? previewTextBudget : textBudget
+	// Condensation is a display choice, not permission to discard evidence. The
+	// original can be under the ordinary cap while still losing distinct rows.
+	// Failed retention falls back to the original, bounded by the usual cap.
+	if (preview !== undefined && retained?.integrity) {
+		const condensed = [preview, recovery].filter(Boolean).join('\n\n')
+		if (effectiveTextBudget === undefined || condensed.length <= effectiveTextBudget) {
+			return {
+				output: withNotice(condensed),
+				originalLength,
+				truncated: true,
+				spillPath,
+				spillIntegrity: retained.integrity,
+			}
+		}
+	}
+	if (textBudget === undefined || originalLength <= textBudget) {
+		return { output: withNotice(output), originalLength, truncated: false }
+	}
 
 	return {
-		output: withNotice(boundedPreview(output, textBudget, opts.toolName, recovery)),
+		output: withNotice(
+			boundedPreview(output, effectiveTextBudget ?? textBudget, opts.toolName, recovery),
+		),
 		originalLength,
 		truncated: true,
 		...(spillPath ? { spillPath } : {}),
+		...(retained?.integrity ? { spillIntegrity: retained.integrity } : {}),
 	}
 }
 
@@ -222,7 +266,7 @@ function spill(
 	toolUseId: string,
 	content: string,
 	onError?: (message: string) => void,
-): string | undefined {
+): { path: string; integrity?: string } | undefined {
 	try {
 		// `0o700` on the directory and `0o600` on the file: a spilled output is
 		// routinely the largest and most sensitive thing a run produces — whole
@@ -250,8 +294,16 @@ function spill(
 		// so randomising the filename would add nothing this does not already
 		// have. Do not "improve" it back to a random name and a plain `w` —
 		// that trades a guarantee for a guess.
-		writeFileSync(path, content, { encoding: 'utf-8', flag: 'wx', mode: 0o600 })
-		return path
+		const bytes = Buffer.from(content, 'utf8')
+		writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 })
+		try {
+			const manifest = spillManifest(bytes)
+			writeFileSync(`${path}.manifest.json`, manifest, { flag: 'wx', mode: 0o600 })
+			return { path, integrity: digest(manifest) }
+		} catch {
+			onError?.('The full output was retained, but its integrity manifest could not be written.')
+			return { path }
+		}
 	} catch (err) {
 		// A spill failure must never fail the tool call — the model still
 		// gets the preview, just without a path to recover the rest.

package/src/runtime/query/tooling.ts

@@ -47,8 +47,10 @@ export interface ToolingBootstrapConfig {
 	maxToolCalls?: number
 	readToolCallBudgetEvents?: () => Promise<readonly RunEvent[]>
 	maxToolOutputChars?: number
+	retainedToolPreviewChars?: number
 	maxToolContentBytes?: number
-	toolOutputDir?: string
+	captureRunEvidence?: import('../../types/tool/index.js').ToolContext['captureRunEvidence']
+	toolOutputDir?: string | (() => string | undefined)
 	repairToolCall?: RepairToolCall
 	/** Operator authorization shared with the direct-call review path. */
 	authorizationGate?: AuthorizationGate
@@ -79,6 +81,7 @@ export class ToolingBootstrap {
 				abortSignal: config.abortSignal,
 				allowedTools: config.allowedTools,
 				invocationState: config.invocationState,
+				captureRunEvidence: config.captureRunEvidence,
 				pluginManager: config.pluginManager,
 				...(config.backgroundJobs ? { backgroundJobs: config.backgroundJobs } : {}),
 				...(config.backgroundJobOwner ? { backgroundJobOwner: config.backgroundJobOwner } : {}),
@@ -98,6 +101,9 @@ export class ToolingBootstrap {
 				...(config.maxToolOutputChars !== undefined
 					? { maxToolOutputChars: config.maxToolOutputChars }
 					: {}),
+				...(config.retainedToolPreviewChars !== undefined
+					? { retainedToolPreviewChars: config.retainedToolPreviewChars }
+					: {}),
 				...(config.maxToolContentBytes !== undefined
 					? { maxToolContentBytes: config.maxToolContentBytes }
 					: {}),