@namzu/sdk 38.2.1 → 39.0.0

package/src/run/index.ts

@@ -29,3 +29,14 @@ export { RUN_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
 export type { MemoryPromoterOptions } from './memory-promoter.js'
 export { createMemoryRecallStep } from './memory-recall.js'
 export type { MemoryRecallOptions } from './memory-recall.js'
+export { createJsonClaimVerifier } from './json-claim-verifier.js'
+export type {
+	JsonClaimValue,
+	JsonClaimRequirement,
+	JsonClaimReadRequest,
+	JsonClaimObservation,
+	JsonClaimReceipt,
+	JsonClaimVerdict,
+	JsonClaimVerifierOptions,
+	JsonClaimVerifier,
+} from './json-claim-verifier.js'

package/src/run/json-claim-verifier.ts

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+import type { RunId } from '../types/ids/index.js'
+import type { AnswerReviewContext } from '../types/run/answer-review.js'
+
+/** Numbers are restricted to safe integers; use strings for exact decimal values. */
+export type JsonClaimValue = string | number | boolean | null
+
+export interface JsonClaimRequirement {
+	readonly id: string
+	/** Host-selected source identifier, never an address supplied by the candidate. */
+	readonly source: string
+	/** RFC 6901 pointer to a scalar in the complete JSON document. */
+	readonly pointer: string
+	/** Optional postcondition in addition to candidate/source equality. */
+	readonly expected?: JsonClaimValue
+}
+
+export interface JsonClaimReadRequest {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly requestId: string
+	readonly startedAt: number
+	/** Remaining total allowance. The host must bound capture, not only the returned buffer. */
+	readonly maxBytes: number
+	readonly signal: AbortSignal
+}
+
+export interface JsonClaimObservation {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly requestId: string
+	readonly source: string
+	readonly observedAt: number
+	readonly complete: boolean
+	readonly kind: 'current' | 'historical'
+	readonly bytes: Uint8Array
+}
+
+export interface JsonClaimReceipt {
+	readonly scope: string
+	readonly runId: RunId
+	readonly iteration: number
+	readonly claims: Readonly<Record<string, JsonClaimValue>>
+	readonly observations: readonly {
+		readonly source: string
+		readonly requestId: string
+		readonly observedAt: number
+		readonly bytes: number
+		readonly sha256: string
+	}[]
+}
+
+export type JsonClaimVerdict =
+	| { readonly accept: true; readonly receipt: JsonClaimReceipt }
+	| { readonly accept: false; readonly feedback: string }
+
+export interface JsonClaimVerifierOptions {
+	/** Host-owned authorization scope, including the admitted revision/claim where applicable. */
+	readonly scope: string
+	readonly runId: RunId
+	readonly requirements: readonly JsonClaimRequirement[]
+	/**
+	 * Trusted, read-only adapter. Enforce access, capture bounds and cancellation;
+	 * observe during this call. A matching envelope is not authentication against
+	 * a dishonest adapter. Do not replay an action or relabel an archive as current.
+	 */
+	readonly observe: (source: string, request: JsonClaimReadRequest) => Promise<JsonClaimObservation>
+	/** Total captured source bytes per verification; default 1 MiB, at most 8 MiB. */
+	readonly maxBytes?: number
+	/** Whole verification deadline; default 2 seconds, at most 30 seconds. */
+	readonly timeoutMs?: number
+}
+
+export interface JsonClaimVerifier {
+	/** False while an observer is outstanding, including after timeout/cancellation. */
+	isDrained(): boolean
+	/** No success cache. Every call observes the configured sources again. */
+	verify(
+		claims: unknown,
+		context: Pick<AnswerReviewContext, 'runId' | 'iteration' | 'signal'>,
+	): Promise<JsonClaimVerdict>
+}
+
+function scalar(value: unknown): value is JsonClaimValue {
+	return (
+		value === null ||
+		typeof value === 'boolean' ||
+		(typeof value === 'string' && value.length <= 2_000) ||
+		(typeof value === 'number' && Number.isSafeInteger(value))
+	)
+}
+
+function reject(reason: string): JsonClaimVerdict {
+	return {
+		accept: false,
+		feedback: `Claim verification failed: ${reason} Do not claim verified completion. Correct the claims using a permitted observation, or report that completion is unavailable.`,
+	}
+}
+
+function pointerParts(pointer: string): string[] {
+	if (pointer === '') return []
+	if (!pointer.startsWith('/') || pointer.length > 512 || /~(?:[^01]|$)/u.test(pointer))
+		throw new Error('Invalid JSON claim pointer.')
+	return pointer
+		.slice(1)
+		.split('/')
+		.map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+}
+
+function select(document: unknown, parts: readonly string[]): unknown {
+	let value = document
+	for (const part of parts) {
+		if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) return undefined
+		if (Array.isArray(value) && !/^(0|[1-9]\d*)$/u.test(part)) return undefined
+		value = (value as Record<string, unknown>)[part]
+	}
+	return value
+}
+
+/**
+ * Compare explicit candidate fields with fresh, host-authorized JSON observations.
+ * This does not judge prose or prove the broader task complete. A receipt describes
+ * observation time, not an atomic snapshot or continuing truth after the read.
+ */
+export function createJsonClaimVerifier(options: JsonClaimVerifierOptions): JsonClaimVerifier {
+	const { scope, runId, observe } = options
+	const maxBytes = options.maxBytes ?? 1_048_576
+	const timeoutMs = options.timeoutMs ?? 2_000
+	if (
+		typeof scope !== 'string' ||
+		!scope ||
+		scope.length > 2_000 ||
+		typeof runId !== 'string' ||
+		!runId ||
+		typeof observe !== 'function'
+	)
+		throw new Error('JSON claim verification requires a scope, run ID and observer.')
+	if (
+		!Number.isSafeInteger(maxBytes) ||
+		maxBytes < 1 ||
+		maxBytes > 8_388_608 ||
+		!Number.isSafeInteger(timeoutMs) ||
+		timeoutMs < 1 ||
+		timeoutMs > 30_000
+	)
+		throw new Error('Invalid JSON claim verification bounds.')
+	if (!options.requirements.length || options.requirements.length > 32)
+		throw new Error('JSON claim verification requires 1–32 requirements.')
+	const ids = new Set<string>()
+	const requirements = options.requirements.map((item) => {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_-]{0,99}$/u.test(item.id) ||
+			ids.has(item.id) ||
+			typeof item.source !== 'string' ||
+			!item.source ||
+			item.source.length > 512 ||
+			typeof item.pointer !== 'string' ||
+			(Object.hasOwn(item, 'expected') && !scalar(item.expected))
+		)
+			throw new Error('Invalid or duplicate JSON claim requirement.')
+		ids.add(item.id)
+		return { ...item, parts: pointerParts(item.pointer) }
+	})
+	let active = false
+	let pending = 0
+	return {
+		isDrained: () => !active && pending === 0,
+		async verify(claims, context) {
+			context.signal?.throwIfAborted()
+			if (
+				context.runId !== runId ||
+				!Number.isSafeInteger(context.iteration) ||
+				context.iteration < 0
+			)
+				return reject('The review belongs to a different run or invalid iteration.')
+			if (active || pending) return reject('A previous observation has not drained.')
+			if (
+				!claims ||
+				typeof claims !== 'object' ||
+				Array.isArray(claims) ||
+				Object.keys(claims).length !== requirements.length ||
+				Object.keys(claims).some((id) => !ids.has(id))
+			)
+				return reject('Supply exactly the configured claim IDs and scalar values.')
+			const values: Record<string, JsonClaimValue> = Object.create(null)
+			for (const item of requirements) {
+				if (!Object.hasOwn(claims, item.id)) return reject('A required claim is missing.')
+				const value = (claims as Record<string, unknown>)[item.id]
+				if (!scalar(value)) return reject(`Claim ${item.id} is not a supported scalar.`)
+				values[item.id] = value
+			}
+			active = true
+			const controller = new AbortController()
+			const expiresAt = performance.now() + timeoutMs
+			const ensureActive = () => {
+				// A synchronous adapter can delay timers; late bytes still cannot pass.
+				if (performance.now() >= expiresAt) controller.abort(new Error('Verification timed out.'))
+				controller.signal.throwIfAborted()
+			}
+			const onAbort = () => controller.abort(context.signal?.reason)
+			context.signal?.addEventListener('abort', onAbort, { once: true })
+			const timer = setTimeout(
+				() => controller.abort(new Error('Verification timed out.')),
+				timeoutMs,
+			)
+			const observations: JsonClaimReceipt['observations'][number][] = []
+			let remaining = maxBytes
+			let removeAbort: (() => void) | undefined
+			try {
+				for (const source of new Set(requirements.map((item) => item.source))) {
+					ensureActive()
+					if (remaining < 1) return reject('The source byte allowance is exhausted.')
+					const request = Object.freeze({
+						scope,
+						runId,
+						iteration: context.iteration,
+						requestId: randomUUID(),
+						startedAt: Date.now(),
+						maxBytes: remaining,
+						signal: controller.signal,
+					})
+					pending++
+					const work = Promise.resolve()
+						.then(() => {
+							ensureActive()
+							return observe(source, request)
+						})
+						.finally(() => {
+							pending--
+						})
+					const aborted = new Promise<never>((_, fail) => {
+						const listener = () => fail(controller.signal.reason)
+						controller.signal.addEventListener('abort', listener, { once: true })
+						removeAbort = () => controller.signal.removeEventListener('abort', listener)
+					})
+					const observation = await Promise.race([work, aborted])
+					removeAbort?.()
+					ensureActive()
+					if (
+						!observation ||
+						observation.scope !== scope ||
+						observation.runId !== runId ||
+						observation.iteration !== context.iteration ||
+						observation.requestId !== request.requestId ||
+						observation.source !== source ||
+						observation.complete !== true ||
+						observation.kind !== 'current' ||
+						!Number.isSafeInteger(observation.observedAt) ||
+						observation.observedAt < request.startedAt ||
+						observation.observedAt > Date.now() ||
+						!(observation.bytes instanceof Uint8Array)
+					)
+						return reject('The observation is incomplete, historical or outside this review scope.')
+					if (observation.bytes.byteLength > remaining)
+						return reject('A source exceeded the byte allowance.')
+					const bytes = Buffer.from(observation.bytes)
+					remaining -= bytes.byteLength
+					const document: unknown = JSON.parse(
+						new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+					)
+					for (const item of requirements.filter((item) => item.source === source)) {
+						const actual = select(document, item.parts)
+						if (!scalar(actual) || actual !== values[item.id])
+							return reject(`Claim ${item.id} does not match the selected source field.`)
+						if (Object.hasOwn(item, 'expected') && actual !== item.expected)
+							return reject(`Claim ${item.id} does not satisfy the configured postcondition.`)
+					}
+					observations.push({
+						source,
+						requestId: request.requestId,
+						observedAt: observation.observedAt,
+						bytes: bytes.byteLength,
+						sha256: createHash('sha256').update(bytes).digest('hex'),
+					})
+				}
+				ensureActive()
+				return {
+					accept: true,
+					receipt: { scope, runId, iteration: context.iteration, claims: values, observations },
+				}
+			} catch {
+				context.signal?.throwIfAborted()
+				return reject(
+					'A current source could not be fully observed and parsed within the deadline.',
+				)
+			} finally {
+				clearTimeout(timer)
+				removeAbort?.()
+				context.signal?.removeEventListener('abort', onAbort)
+				controller.abort()
+				active = false
+			}
+		},
+	}
+}

package/src/run/preparation-context-error.ts

@@ -0,0 +1,16 @@
+import { toErrorMessage } from '../utils/error.js'
+
+/**
+ * Internal bridge for SDK preparation failures with a safe availability note
+ * and, when available, fully validated fallback evidence within the same budget.
+ * The cause remains diagnostic-only. Ordinary thrown errors never become context.
+ */
+export class PreparationContextError extends Error {
+	constructor(
+		cause: unknown,
+		readonly context: string,
+	) {
+		super(toErrorMessage(cause), { cause })
+		this.name = 'PreparationContextError'
+	}
+}

package/src/run-query/index.ts

@@ -62,7 +62,7 @@ export class RunTranscriptUnavailableError extends Error {
 /** What one compaction pass removed. */
 export interface ShedPass {
 	readonly iteration: number
-	readonly reason: 'threshold' | 'overflow'
+	readonly reason: Extract<PersistedRunEvent, { type: 'compaction_shed' }>['reason']
 	readonly messages: readonly Message[]
 	/** Where in the log the pass sits, for a caller correlating with events. */
 	readonly seq: number

package/src/runtime/query/callback-inference.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+import { StreamTextAccumulator } from '../../provider/stream-text.js'
+import { type TokenUsage, mergeTokenUsage } from '../../types/common/index.js'
+import { createSystemMessage, createUserMessage } from '../../types/message/index.js'
+import type { PreparationTextRequest, PreparationTextResult } from '../../types/run/prepare-step.js'
+import type { IterationContext } from './iteration/phases/context.js'
+
+const requestSchema = z
+	.object({
+		system: z.string().min(1).max(12_000),
+		prompt: z.string().min(1).max(12_000),
+		maxTokens: z.number().int().min(1).max(1024).default(256),
+		timeoutMs: z.number().int().min(1).max(10_000).default(10_000),
+	})
+	.strict()
+
+/** The provider already owns retry, fallback, cancellation and budget admission. */
+export function createCallbackInference(
+	ctx: IterationContext,
+	model: string,
+	phase: 'preparation' | 'review',
+) {
+	const label = phase === 'preparation' ? 'Preparation' : 'Review'
+	const owner = phase === 'preparation' ? 'preparation stage' : 'answer reviewer'
+	const lifetime = new AbortController()
+	let used = false
+	return {
+		close: () => lifetime.abort(new Error(`The ${owner} has ended.`)),
+		async generateText(request: PreparationTextRequest): Promise<PreparationTextResult> {
+			lifetime.signal.throwIfAborted()
+			ctx.abortController.signal.throwIfAborted()
+			request.signal?.throwIfAborted()
+			const { signal: requestedSignal, ...fields } = request
+			const input = requestSchema.parse(fields)
+			if (input.system.length + input.prompt.length > 12_000)
+				throw new Error(`${label} inference input exceeds 12,000 characters.`)
+			if (used)
+				throw new Error(
+					`${phase === 'preparation' ? 'A' : 'An'} ${owner} may make only one inference call.`,
+				)
+			used = true
+			const deadline = new AbortController()
+			const timer = setTimeout(
+				() => deadline.abort(new Error(`${label} inference timed out.`)),
+				input.timeoutMs,
+			)
+			const signal = AbortSignal.any([
+				ctx.abortController.signal,
+				lifetime.signal,
+				deadline.signal,
+				...(requestedSignal ? [requestedSignal] : []),
+			])
+			const requested = ctx.servingMember?.() ?? { index: 0, providerId: ctx.provider.id }
+			const route = () => {
+				const member = ctx.servingMember?.() ?? requested
+				return {
+					providerId: member.providerId,
+					model: member.model ?? model,
+					chainIndex: member.index,
+				}
+			}
+			const text = new StreamTextAccumulator()
+			let invalidOutput: string | undefined
+			let usage: TokenUsage | undefined
+			try {
+				for await (const chunk of ctx.provider.chatStream({
+					model,
+					providerRoute: route(),
+					messages: [createSystemMessage(input.system), createUserMessage(input.prompt)],
+					maxTokens: input.maxTokens,
+					...(ctx.runConfig.effort ? { effort: ctx.runConfig.effort } : {}),
+					signal,
+				})) {
+					if (chunk.usage) usage = usage ? mergeTokenUsage(usage, chunk.usage) : { ...chunk.usage }
+					if (chunk.error) throw new Error(chunk.error)
+					signal.throwIfAborted()
+					if (chunk.delta.toolCalls?.length) invalidOutput = `${label} inference cannot call tools.`
+					if (!invalidOutput) {
+						text.push(chunk)
+						if (text.characters > 8192)
+							invalidOutput = `${label} inference output exceeds 8,192 characters.`
+					}
+				}
+				signal.throwIfAborted()
+				if (!usage) throw new Error(`${label} inference ended without usage.`)
+				if (invalidOutput) throw new Error(invalidOutput)
+				return { text: text.text, usage, servedBy: route() }
+			} finally {
+				clearTimeout(timer)
+				if (usage) ctx.runMgr.accumulateUsage(usage, route())
+			}
+		},
+	}
+}

package/src/runtime/query/checkpoint.ts

@@ -214,6 +214,8 @@ export class CheckpointManager {
 	private workingStateSource?: () => WorkingStateSnapshot | undefined
 	private latestUserMessageSource?: () => UserMessage | undefined
 	private restoredUserMessage?: UserMessage
+	private answerReviewAttemptsSource?: () => number
+	private restoredAnswerAttempts = 0
 	private structuredReviewAttemptsSource?: () => number
 	private restoredReviewAttempts = 0
 	private nativeStructuredAttemptsSource?: () => number
@@ -298,6 +300,13 @@ export class CheckpointManager {
 		return this.restoredUserMessage
 	}
 
+	setAnswerReviewAttemptsSource(source: () => number): void {
+		this.answerReviewAttemptsSource = source
+	}
+	get restoredAnswerReviewAttempts(): number {
+		return this.restoredAnswerAttempts
+	}
+
 	setNativeStructuredAttemptsSource(source: () => number): void {
 		this.nativeStructuredAttemptsSource = source
 	}
@@ -344,6 +353,7 @@ export class CheckpointManager {
 			runCreatedAt: this.runCreatedAt,
 			iteration,
 			messages: [...runMgr.messages],
+			answerReviewAttempts: this.answerReviewAttemptsSource?.() ?? this.restoredAnswerAttempts,
 			nativeStructuredAttempts:
 				this.nativeStructuredAttemptsSource?.() ?? this.restoredNativeAttempts,
 			structuredReviewAttempts:
@@ -539,6 +549,10 @@ export class CheckpointManager {
 		// its origin's age. A guard that no input can trip would have read as
 		// protection and been none.
 		this.runCreatedAt ??= checkpoint.runCreatedAt
+		const answerAttempts = checkpoint.answerReviewAttempts ?? 0
+		if (!Number.isSafeInteger(answerAttempts) || answerAttempts < 0)
+			throw new Error('Checkpoint answerReviewAttempts must be a nonnegative safe integer')
+		this.restoredAnswerAttempts = answerAttempts
 		const nativeAttempts = checkpoint.nativeStructuredAttempts ?? 0
 		if (!Number.isSafeInteger(nativeAttempts) || nativeAttempts < 0)
 			throw new Error('Invalid nativeStructuredAttempts in checkpoint')

package/src/runtime/query/events.ts

@@ -11,6 +11,7 @@ import { type PersistedRunEvent, isEphemeralEvent } from '../../types/run/events
 import type { RunEvent } from '../../types/run/index.js'
 import type { ReadRunEventsOptions } from '../../types/run/store.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 
@@ -78,6 +79,27 @@ export class EventTranslator {
 		return this.withTranscriptLock(() => this.runMgr.getRunStore().readEvents(options))
 	}
 
+	captureRunEvidence(
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	): Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined> {
+		const capture = this.withTranscriptLock(async () => {
+			signal?.throwIfAborted()
+			const run = this.runMgr.getRun()
+			if (run.status !== 'running')
+				throw new Error('Evidence capture requires the active invocation.')
+			const { tenantId, projectId, sessionId, runId } = this.runMgr.getRunScope()
+			const source = await this.runMgr
+				.getRunStore()
+				.captureTextEvidence?.({ tenantId, projectId, sessionId, runId }, maxReadBytes, signal)
+			signal?.throwIfAborted()
+			if (this.runMgr.getRun().status !== 'running')
+				throw new Error('Evidence capture requires the active invocation.')
+			return source
+		})
+		return awaitWithAbort(capture, signal)
+	}
+
 	setGeneration(fence: FencingToken | undefined): void {
 		this.generation = fence
 	}

package/src/runtime/query/executor.ts

@@ -43,12 +43,14 @@ import type {
 	ToolCallRepairReason,
 } from '../../types/tool/repair.js'
 import { abortReasonText } from '../../utils/abort.js'
+import { awaitWithAbort } from '../../utils/await-with-abort.js'
 import { type BackoffPolicy, backoffWithJitter, sleep } from '../../utils/backoff.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { generateToolCallId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
+import { describeVisibleFileEvidence } from './file-evidence-context.js'
 import type { ToolResultObservation } from './project-instructions.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
@@ -376,6 +378,8 @@ export interface ToolExecutorConfig {
 	 * {@link DEFAULT_MAX_TOOL_OUTPUT_CHARS}; set `0` to disable.
 	 */
 	maxToolOutputChars?: number
+	/** See QueryParams.retainedToolPreviewChars; applies to the recorded host output. */
+	retainedToolPreviewChars?: number
 
 	/**
 	 * Cap on the RICH channel of a single tool result, in base64
@@ -401,7 +405,8 @@ export interface ToolExecutorConfig {
 	 * with `read`/`grep`. Absent ⇒ over-budget output is middle-elided and
 	 * the overflow is lost.
 	 */
-	toolOutputDir?: string
+	captureRunEvidence?: ToolContext['captureRunEvidence']
+	toolOutputDir?: string | (() => string | undefined)
 	/**
 	 * Last chance to fix a tool call the model got wrong, before the error
 	 * reaches it. See {@link RepairToolCall}.
@@ -491,6 +496,12 @@ export function deniedToolOutput(toolName: string, reason: string): string {
 }
 
 export class ToolExecutor {
+	private outputDirectory(): string | undefined {
+		return typeof this.config.toolOutputDir === 'function'
+			? this.config.toolOutputDir()
+			: this.config.toolOutputDir
+	}
+
 	private config: ToolExecutorConfig
 	private activityStore: ActivityStore
 	private emitEvent: EmitEvent
@@ -536,6 +547,16 @@ export class ToolExecutor {
 		this.config = { ...this.config, sandbox }
 	}
 
+	/** Request-only evidence from the same ledger used by mutation admission. No filesystem I/O. */
+	describeFileEvidence(messages: readonly Message[]): string | undefined {
+		return describeVisibleFileEvidence(
+			messages,
+			this.fileReadTracker,
+			this.config.workingDirectory,
+			this.config.sandbox !== undefined,
+		)
+	}
+
 	/**
 	 * Span that this executor's tool spans should hang off — the current
 	 * iteration. Re-set each turn by the orchestrator, because a tool span
@@ -1175,7 +1196,8 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			output: rawOutput,
 			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized nested tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
@@ -1206,6 +1228,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 			...(via ? { via } : {}),
 		})
 		recordObservation({
@@ -1253,6 +1276,7 @@ export class ToolExecutor {
 				workingDirectory: this.config.workingDirectory,
 			},
 			invocationState: this.config.invocationState,
+			captureRunEvidence: this.config.captureRunEvidence,
 			toolRegistry: this.config.tools,
 			// The step's list wins where it has one; the run's is the default.
 			// Same precedence the request already uses when it decides which
@@ -1628,8 +1652,8 @@ export class ToolExecutor {
 			: formatFailedToolOutput(result.output, result.error)
 
 		const postOverride = post.override
-		let output =
-			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
+		let output = postOverride?.output ?? rawOutput
+		const preview = !postOverride && result.success ? this.maybeCompress(toolName, output) : output
 		let selectedContent = postOverride?.isError
 			? undefined
 			: (postOverride?.content ?? result.content)
@@ -1655,16 +1679,22 @@ export class ToolExecutor {
 			toolName,
 			toolUseId: toolCall.id,
 			output,
+			preview,
 			maxChars: maxToolOutputChars,
-			spillDir: this.config.toolOutputDir,
+			retainedPreviewChars: this.config.retainedToolPreviewChars,
+			spillDir: this.outputDirectory(),
 			onError: (message) =>
-				this.log.warn('Failed to spill oversized tool output', {
+				this.log.warn('Failed to retain original tool output', {
 					[NAMZU.RUN_ID]: this.config.runId,
 					[GENAI.TOOL_NAME]: toolName,
 					'exception.message': message,
 				}),
 		})
-		if (budgeted.truncated) {
+		if (
+			budgeted.truncated &&
+			maxToolOutputChars > 0 &&
+			budgeted.originalLength > maxToolOutputChars
+		) {
 			this.log.warn('Tool output exceeded the model-visible budget', {
 				[NAMZU.RUN_ID]: this.config.runId,
 				[GENAI.TOOL_NAME]: toolName,
@@ -1736,6 +1766,7 @@ export class ToolExecutor {
 			outputLength: budgeted.originalLength,
 			...(budgeted.truncated ? { outputTruncated: true } : {}),
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
+			...(budgeted.spillIntegrity ? { outputSpillIntegrity: budgeted.spillIntegrity } : {}),
 		})
 		recordObservation({
 			runId: this.config.runId,
@@ -1864,9 +1895,20 @@ export class ToolExecutor {
 				}
 			}
 
+			const inheritedCapture = toolContext.captureRunEvidence
+			const scopedCapture: ToolContext['captureRunEvidence'] = inheritedCapture
+				? async (maxReadBytes, signal) => {
+						const combined = signal
+							? AbortSignal.any([controller.signal, signal])
+							: controller.signal
+						combined.throwIfAborted()
+						return awaitWithAbort(inheritedCapture(maxReadBytes, combined), combined)
+					}
+				: undefined
 			const context = {
 				...toolContext,
 				abortSignal: controller.signal,
+				...(scopedCapture ? { captureRunEvidence: scopedCapture } : {}),
 				...(scopedDispatch ? { dispatchTool: scopedDispatch } : {}),
 			}
 			const execution = prepared
@@ -2686,8 +2728,8 @@ export class ToolExecutor {
 						...(notice ? { notice } : {}),
 						// A tool may return different host and model text. They must
 						// never compete for the same exclusive spill filename.
-						spillDir: this.config.toolOutputDir
-							? join(this.config.toolOutputDir, 'content')
+						spillDir: this.outputDirectory()
+							? join(this.outputDirectory() as string, 'content')
 							: undefined,
 						onError: (message) =>
 							this.log.warn('Failed to spill oversized model tool content', {