@namzu/sdk 48.3.1 → 50.0.0

package/src/runtime/query/executor.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { join } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
@@ -19,12 +20,13 @@ import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
 import type { ToolManager } from '../../toolsets/manager.js'
 import type { ToolSourceRef } from '../../toolsets/types.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
-import type { ToolCallEscalation } from '../../types/hitl/index.js'
+import type { ToolCallDeclined, ToolCallEscalation } from '../../types/hitl/index.js'
 import type { SessionId, ToolUseId, TurnId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import {
 	type Message,
 	type ToolCall,
+	type ToolMessage,
 	type ToolResultContent,
 	type ToolRevealReceipt,
 	createToolMessage,
@@ -35,15 +37,18 @@ import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import type { AuditEventInput } from '../../types/session/audit.js'
 import type { SessionRecord } from '../../types/session/records.js'
+import type { CompletedToolRecord } from '../../types/session/tool-execution.js'
 import type {
 	FileReadTracker,
 	PreparedToolExecution,
 	RequestToolPause,
 	ShellDialect,
 	SkillRegistryRef,
+	ToolCallView,
 	ToolContext,
 	ToolDefinition,
 	ToolDispatchOptions,
+	ToolFacts,
 	ToolHandoff,
 	ToolResult,
 } from '../../types/tool/index.js'
@@ -55,22 +60,21 @@ 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 { parseStructuredResultJson } from '../../utils/structured-result-json.js'
 import { type BackgroundJobRegistry, type JobProcess, bindOwner } from '../jobs/registry.js'
 import {
 	type ToolAdmissionHost,
 	formatFailedToolOutput,
 	isUnregistered,
 	prepareDirectCall,
-	repairTruncatedCall,
-	resolveCall,
 	runPreToolHook,
 	unknownToolMessage,
-	unreadableToolCallMessage,
 } from './executor/tool-call-admission.js'
 import { describeVisibleFileEvidence } from './file-evidence-context.js'
 import { seedObservationLedger } from './file-evidence-seed.js'
 import { DEFAULT_TOOL_RESULT_GUARDRAILS } from './guardrail-presets.js'
 import type { ToolResultObservation } from './project-instructions.js'
+import { savedPresentation } from './saved-presentation.js'
 import { ToolCallBudget, assertMaxToolCalls } from './tool-call-budget.js'
 import {
 	DEFAULT_MAX_TOOL_OUTPUT_CHARS,
@@ -96,6 +100,7 @@ export type PreparedDirectCall =
 			readonly toolCall: ToolCall
 			readonly toolName: string
 			readonly input: unknown
+			readonly inputFailure?: CompletedToolRecord['inputFailure']
 	  }
 	| {
 			readonly kind: 'synthetic'
@@ -104,6 +109,10 @@ export type PreparedDirectCall =
 			readonly input: unknown
 			readonly message: string
 			readonly isError: boolean
+			readonly inputFailure?: CompletedToolRecord['inputFailure']
+			readonly skipped?: true
+			/** Why it never ran, as a kind; see `ToolFacts`. */
+			readonly facts?: ToolFacts
 	  }
 
 /**
@@ -152,6 +161,7 @@ type PreparedNestedCall =
 			readonly input: unknown
 			readonly message: string
 			readonly isError: boolean
+			readonly skipped?: true
 	  }
 
 /**
@@ -309,6 +319,8 @@ export const DEFAULT_TOOL_RETRY_BACKOFF: BackoffPolicy = {
 export interface ToolExecutorConfig {
 	fileReadTracker?: FileReadTracker
 	tools: ToolManager
+	/** Exact runtime output-tool owner allowed to retain post-screen, post-hook JSON before preview capping. */
+	durableStructuredOutputTool?: ToolDefinition
 	sessionId: SessionId
 	turnId: TurnId
 	workingDirectory: string
@@ -496,6 +508,12 @@ export interface ToolCallOutcome {
 	/** Rich form for the model, when the tool supplied one. */
 	content?: ToolResultContent
 	isError?: boolean
+	/** Provider argument admission failure, never inferred from receipt text. */
+	inputFailure?: CompletedToolRecord['inputFailure']
+	/** A pre-tool hook deliberately skipped execution; its receipt is not an output candidate. */
+	skipped?: true
+	/** Opt-in execution evidence, never provider content or accepted output. */
+	structuredResultJson?: string
 	/** The tool asked for a person; see `ToolResult.handoff`. */
 	handoff?: ToolHandoff
 	/**
@@ -523,6 +541,16 @@ export interface ToolExecutionBatch {
  */
 export type ToolCallDenials = ReadonlyMap<string, string>
 
+/**
+ * The subset of {@link ToolCallDenials} a person refused, keyed by the same
+ * ids. Only the review answer fills it, so a call listed here was declined
+ * by someone and a policy refusal is never in it.
+ */
+export type ToolCallDeclines = ReadonlyMap<string, ToolCallDeclined>
+
+/** A person's note is kept whole up to this many characters. */
+export const DECLINED_NOTE_MAX_CHARS = 4_000
+
 /**
  * Results for calls that already ran, keyed by `toolUseId`.
  *
@@ -533,7 +561,11 @@ export type ToolCallDenials = ReadonlyMap<string, string>
  * again — which for a payment or an email is the difference between
  * resuming and repeating.
  */
-export type PriorToolResults = ReadonlyMap<string, { result: string; isError: boolean }>
+export type PriorToolResult = Pick<
+	CompletedToolRecord,
+	'result' | 'isError' | 'inputFailure' | 'skipped' | 'structuredResultJson'
+>
+export type PriorToolResults = ReadonlyMap<string, PriorToolResult>
 
 /**
  * Model-visible text for a tool call that was never executed.
@@ -544,6 +576,22 @@ export type PriorToolResults = ReadonlyMap<string, { result: string; isError: bo
  * the reason here is also what makes rejection *steer* — the model reads
  * it in the slot it already attends to for tool outcomes.
  */
+/**
+ * The kind of refusal a call met, for the person's view. A command that asks
+ * for administrator rights is named as that; everything else is a plain block.
+ * Read from the call's own argument, never from the refusal's wording.
+ */
+function refusalFacts(toolName: string, input: unknown): ToolFacts {
+	const command =
+		input && typeof input === 'object' ? (input as { command?: unknown }).command : undefined
+	const elevated = typeof command === 'string' && /(^|[\s;&|(])(sudo|doas)\b/.test(command)
+	return {
+		kind: 'failure',
+		reason: elevated ? 'needs_administrator' : 'blocked',
+		subject: toolName,
+	}
+}
+
 export function deniedToolOutput(toolName: string, reason: string): string {
 	return `Error: Tool "${toolName}" was not executed. ${reason}`
 }
@@ -564,6 +612,16 @@ export class ToolExecutor {
 	private parentSpan?: Span
 	private readonly toolCallBudget?: ToolCallBudget
 	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
+	/** Ephemeral proof of actual execution; restored messages do not acquire it. */
+	private readonly recordedObservations = new Map<
+		string,
+		{
+			readonly toolName: string
+			readonly definition: ToolDefinition
+			readonly fingerprint: string
+			readonly inputFingerprint: string
+		}
+	>()
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly fileReadTracker: FileReadTracker
@@ -602,6 +660,50 @@ export class ToolExecutor {
 		this.config = { ...this.config, sandbox }
 	}
 
+	/** Classify only the exact successful result executed by this executor. */
+	recordedObservationKey(call: ToolCall, message: ToolMessage): string | undefined {
+		const recorded = this.recordedObservations.get(call.id)
+		return recorded !== undefined &&
+			message.toolCallId === call.id &&
+			!message.isError &&
+			typeof message.content === 'string' &&
+			this.config.tools.get(recorded.toolName) === recorded.definition &&
+			recorded.fingerprint === this.observationFingerprint(call, message.content)
+			? recorded.inputFingerprint
+			: undefined
+	}
+
+	private observationFingerprint(call: ToolCall, content: string): string {
+		return createHash('sha256')
+			.update(JSON.stringify([call.function.name, call.function.arguments, content]))
+			.digest('hex')
+	}
+
+	private recordExecutedObservation(
+		call: ToolCall,
+		toolName: string,
+		definition: ToolDefinition,
+		input: unknown,
+		content: ToolResultContent,
+	): void {
+		if (typeof content !== 'string' || this.config.tools.get(toolName) !== definition) return
+		try {
+			if (definition.isReadOnly?.(input) !== true || definition.isDestructive?.(input) === true)
+				return
+			this.recordedObservations.set(call.id, {
+				toolName,
+				definition,
+				fingerprint: this.observationFingerprint(call, content),
+				inputFingerprint: createHash('sha256')
+					.update(JSON.stringify([toolName, input]))
+					.digest('hex'),
+			})
+		} catch {
+			// Classification is advisory. A broken predicate preserves the
+			// full evidence instead of failing an already completed call.
+		}
+	}
+
 	/**
 	 * Rebuild this turn's observation ledger from history a resume restored.
 	 *
@@ -844,16 +946,24 @@ export class ToolExecutor {
 	 * The returned projection is what policy and a human review; execution later
 	 * consumes the registry-owned preparations rather than parsing again.
 	 */
-	async prepareBatchForReview(response: ChatCompletionResponse): Promise<PreparedToolBatch> {
+	async prepareBatchForReview(
+		response: ChatCompletionResponse,
+		hostModifiedCallIds?: ReadonlySet<string>,
+	): Promise<PreparedToolBatch> {
 		assertUniqueToolCallIds(response.message.toolCalls ?? [])
 		const calls = new Map<string, PreparedDirectCall>()
 		const escalations = new Map<string, ToolCallEscalation>()
 		for (const toolCall of response.message.toolCalls ?? []) {
-			const call = await prepareDirectCall(this.admissionHost(), toolCall)
+			const call = await prepareDirectCall(
+				this.admissionHost(),
+				toolCall,
+				!hostModifiedCallIds?.has(toolCall.id),
+			)
 			calls.set(toolCall.id, call)
 			const escalation = await this.escalationOf(call)
 			if (escalation) escalations.set(toolCall.id, escalation)
 		}
+		this.config.abortSignal.throwIfAborted()
 		return this.publishPreparedBatch(calls, escalations)
 	}
 
@@ -937,13 +1047,14 @@ export class ToolExecutor {
 		const escalations = new Map((previous as OwnedPreparedToolBatch).escalations)
 		for (const toolCall of response.message.toolCalls ?? []) {
 			if (changedCallIds.has(toolCall.id)) {
-				const call = await prepareDirectCall(this.admissionHost(), toolCall)
+				const call = await prepareDirectCall(this.admissionHost(), toolCall, false)
 				calls.set(toolCall.id, call)
 				const escalation = await this.escalationOf(call)
 				if (escalation) escalations.set(toolCall.id, escalation)
 				else escalations.delete(toolCall.id)
 			}
 		}
+		this.config.abortSignal.throwIfAborted()
 		return this.publishPreparedBatch(calls, escalations)
 	}
 
@@ -979,6 +1090,7 @@ export class ToolExecutor {
 		denials?: ToolCallDenials,
 		prior?: PriorToolResults,
 		preparedBatch?: PreparedToolBatch,
+		declines?: ToolCallDeclines,
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
@@ -1004,9 +1116,9 @@ export class ToolExecutor {
 			if (refusal) {
 				const refused = new Map(denials)
 				for (const call of toolCalls) if (!refused.has(call.id)) refused.set(call.id, refusal)
-				return await this.runBatch(toolCalls, refused, prior, owned)
+				return await this.runBatch(toolCalls, refused, prior, owned, declines)
 			}
-			return await this.runBatch(toolCalls, denials, prior, owned)
+			return await this.runBatch(toolCalls, denials, prior, owned, declines)
 		} finally {
 			// Cleared so a later single execution outside a batch resolves
 			// live rather than inheriting the last batch's sample.
@@ -1019,6 +1131,7 @@ export class ToolExecutor {
 		denials?: ToolCallDenials,
 		prior?: PriorToolResults,
 		preparedBatch?: OwnedPreparedToolBatch,
+		declines?: ToolCallDeclines,
 	): Promise<ToolExecutionBatch> {
 		this.log.debug('Executing tool batch', {
 			[NAMZU.TURN_ID]: this.config.turnId,
@@ -1031,6 +1144,7 @@ export class ToolExecutor {
 		// One context per call so each execution can see its own
 		// `toolUseId`. The base context is built once; we spread + add
 		// per-call to keep allocations cheap.
+		for (const call of toolCalls) this.recordedObservations.delete(call.id)
 		const observations: ToolResultObservation[] = []
 		const recordObservation = (observation: ToolResultObservation): void => {
 			observations.push(observation)
@@ -1093,6 +1207,11 @@ export class ToolExecutor {
 					toolName: toolCall.function.name,
 					output: recovered.result,
 					isError: recovered.isError,
+					...(recovered.inputFailure ? { inputFailure: recovered.inputFailure } : {}),
+					...(recovered.skipped ? { skipped: true as const } : {}),
+					...(recovered.structuredResultJson !== undefined
+						? { structuredResultJson: recovered.structuredResultJson }
+						: {}),
 				}
 				if (isBarrier) schedule(async () => {}, true, true)
 				return
@@ -1105,7 +1224,12 @@ export class ToolExecutor {
 				// overlap other calls within a segment, respecting its barriers.
 				schedule(
 					async () => {
-						results[i] = await this.recordDenial(toolCall, denialReason, preparedCall)
+						results[i] = await this.recordDenial(
+							toolCall,
+							denialReason,
+							preparedCall,
+							declines?.get(toolCall.id),
+						)
 					},
 					true,
 					isBarrier,
@@ -1300,6 +1424,7 @@ export class ToolExecutor {
 				toolName: name,
 				result: preparedCall.message,
 				isError: preparedCall.isError,
+				...(preparedCall.skipped ? { skipped: true as const } : {}),
 				durationMs: Date.now() - startedAt,
 				outputLength: preparedCall.message.length,
 				...(via ? { via } : {}),
@@ -1316,11 +1441,23 @@ export class ToolExecutor {
 			commandDialect: this.commandDialect(name),
 			toolSource: this.toolSource(name),
 		})
-		if (gateResult && gateResult.decision !== 'allow') {
-			const reason =
-				gateResult.decision === 'deny'
+		// A tool that declares `requiresApproval` for this input needs a person's
+		// yes for every call, and no rule outranks that. An operator review cannot
+		// be opened from inside another tool, so a nested call to it is refused
+		// even when a rule allows it (the direct path turns that allow into a review).
+		const nestedTool = this.config.tools.get(name)
+		let needsApproval = false
+		try {
+			needsApproval = nestedTool?.requiresApproval?.(preparedInput as never) === true
+		} catch {
+			needsApproval = true
+		}
+		if (needsApproval || (gateResult && gateResult.decision !== 'allow')) {
+			const reason = needsApproval
+				? `Blocked: "${name}" requires the person's approval for every call, and an approval cannot be requested from inside another tool. Call it directly.`
+				: gateResult?.decision === 'deny'
 					? `Blocked by the authorization gate: ${gateResult.reason}`
-					: `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult.reason}`
+					: `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult?.reason}`
 			const output = deniedToolOutput(name, reason)
 			// Same fail-closed durability rule as a direct gate denial: if the
 			// configured session log cannot record the refusal, do not quietly carry
@@ -1485,7 +1622,8 @@ export class ToolExecutor {
 			toolUseId: nestedId,
 			toolName: name,
 			result: budgeted.output,
-			...(!budgeted.truncated ? this.resultPresentation(name, preparedInput, result) : {}),
+			...this.resultPresentation(name, preparedInput, result, budgeted.truncated),
+			...(result.facts !== undefined ? { facts: result.facts } : {}),
 			isError: !result.success,
 			durationMs: Date.now() - startedAt,
 			outputLength: budgeted.originalLength,
@@ -1507,24 +1645,34 @@ export class ToolExecutor {
 		return visibleResult
 	}
 
-	private resultPresentation(name: string, input: unknown, result: ToolResult) {
+	private resultPresentation(name: string, input: unknown, result: ToolResult, savedOnly = false) {
 		try {
 			const view = this.config.tools.get(name)?.presentResult?.(input, result)
 			// A failed call carries one view only: the person's No on the tool's
 			// own screen, which a host draws as cancelled rather than failed and
 			// cannot tell apart from the result text alone.
 			if (!result.success) {
-				return view?.kind === 'generic' && view.outcome === 'cancelled'
-					? {
-							presentation: {
-								kind: 'generic',
-								label: view.label,
-								outcome: 'cancelled',
-							} as const,
-						}
-					: {}
+				if (!savedOnly && view?.kind === 'generic' && view.outcome === 'cancelled')
+					return {
+						presentation: {
+							kind: 'generic',
+							label: view.label,
+							outcome: 'cancelled',
+						} as const,
+					}
+				const saved = savedPresentation(
+					input,
+					this.config.tools.get(name)?.presentCall?.(input),
+					undefined,
+				)
+				return saved ? { savedPresentation: saved } : {}
+			}
+			if (savedOnly || view?.kind !== 'diff') {
+				// Journal-only: the live event keeps drawing the real result.
+				const tool = this.config.tools.get(name)
+				const saved = savedPresentation(input, tool?.presentCall?.(input), view)
+				return saved ? { savedPresentation: saved } : {}
 			}
-			if (view?.kind !== 'diff') return {}
 			const serialized = JSON.stringify(view)
 			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
 				return {}
@@ -1653,111 +1801,33 @@ export class ToolExecutor {
 		let toolName = preparedCall?.toolName ?? toolCall.function.name
 		let input: unknown
 		let prepared: PreparedToolExecution | undefined
+		let inputFailure: ToolCallOutcome['inputFailure']
 
 		if (preparedCall?.kind === 'ready' || preparedCall?.kind === 'legacy') {
 			input = preparedCall.input
 			prepared = preparedCall.kind === 'ready' ? preparedCall.prepared : undefined
+			if (preparedCall.kind === 'legacy') inputFailure = preparedCall.inputFailure
 		} else {
-			// A stream that cut off mid-JSON is the case `repairToolCall` exists
-			// for, and it used to be the one case that never reached it: this
-			// branch returned before `resolveCall` ran, so the motivating failure
-			// was answered with a generic hint while the configured repairer sat
-			// unused. Offer it the partial buffer first.
-			const truncationRepair =
-				toolCall.metadata?.inputTruncated === true
-					? await repairTruncatedCall(this.admissionHost(), toolCall, toolName)
-					: null
-
-			if (toolCall.metadata?.inputTruncated === true && !truncationRepair) {
-				const message = unreadableToolCallMessage(this.admissionHost(), toolCall, toolName)
-				await this.emitEvent({
-					type: 'tool_executing',
-					turnId: this.config.turnId,
-					toolUseId: toolCall.id,
-					toolName,
-					input: {},
-				})
-				await this.emitEvent({
-					type: 'tool_completed',
-					turnId: this.config.turnId,
-					toolUseId: toolCall.id,
-					toolName,
-					result: message,
-					isError: true,
-				})
-				return {
-					toolCallId: toolCall.id,
-					toolName,
-					output: message,
-					isError: true,
-				}
-			}
-
-			// A malformed call used to cost a full model round trip to fix: the
-			// error went back as a `tool_result`, the model re-read the whole
-			// context and tried again. A host that can repair it locally turns
-			// that into nothing. No-op when no repairer is configured.
-			const resolved = await resolveCall(
-				this.admissionHost(),
-				truncationRepair
-					? {
-							...toolCall,
-							function: {
-								...toolCall.function,
-								name: truncationRepair.toolName ?? toolName,
-								arguments: truncationRepair.arguments,
-							},
-							metadata: {},
-						}
-					: toolCall,
-			)
-			toolName = resolved.toolName
-
-			if (!resolved.ok) {
-				// malformed JSON args used to return without ever
-				// emitting tool_executing or tool_completed, leaving UI cards
-				// orphaned in `streaming_input`. Emit the executing→completed
-				// terminal pair so the card lifecycle closes.
-				const message = resolved.message
-				await this.emitEvent({
-					type: 'tool_executing',
-					turnId: this.config.turnId,
-					toolUseId: toolCall.id,
-					toolName,
-					input: {},
-				})
-				await this.emitEvent({
-					type: 'tool_completed',
-					turnId: this.config.turnId,
-					toolUseId: toolCall.id,
-					toolName,
-					result: message,
-					isError: true,
-				})
-				return {
-					toolCallId: toolCall.id,
-					toolName,
-					output: message,
-					isError: true,
-				}
-			}
-
-			input = resolved.input
-
-			let preOutcome: PreToolHookOutcome
+			// The unreviewed executor path uses the same preparation as a
+			// reviewed call. Parsing here and again in the registry would run
+			// transforms twice and reject asynchronous schemas.
+			let admitted: PreparedDirectCall
 			try {
-				preOutcome = await runPreToolHook(this.admissionHost(), toolName, input)
+				admitted = await prepareDirectCall(this.admissionHost(), toolCall)
+				this.config.abortSignal.throwIfAborted()
 			} catch (error) {
 				if (!this.config.abortSignal.aborted) throw error
-				// A later call's interrupted preparation must not reject the batch
-				// that already holds an earlier call's settled side-effect receipt.
-				return this.recordCancelledBeforeExecution(toolCall.id, toolName, input)
+				// Keep earlier settled siblings' receipts when a later
+				// preparation is interrupted.
+				return this.recordCancelledBeforeExecution(toolCall.id, toolName, {})
 			}
-			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
-				return this.recordSyntheticHookOutcome(toolCall.id, toolName, preOutcome.input, preOutcome)
-			}
-			input = preOutcome.input
+			if (admitted.kind === 'synthetic') return this.recordSyntheticPreparation(admitted)
+			toolName = admitted.toolName
+			input = admitted.input
+			prepared = admitted.kind === 'ready' ? admitted.prepared : undefined
+			if (admitted.kind === 'legacy') inputFailure = admitted.inputFailure
 		}
+		const executedDefinition = this.config.tools.get(toolName)
 
 		const activity = this.activityStore.create({
 			type: 'tool_call',
@@ -1961,6 +2031,28 @@ export class ToolExecutor {
 		}
 		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
 		const sourceOutput = output
+		// This owner-bound channel follows the selected receipt after both result
+		// screening and post-tool replacement. ToolResult.data and raw input can
+		// still carry pre-redaction values and must never be promoted here.
+		let structuredResultJson: string | undefined
+		if (
+			prepared &&
+			executedDefinition !== undefined &&
+			executedDefinition === this.config.durableStructuredOutputTool &&
+			toolName === 'structured_output' &&
+			toolCall.function.name === 'structured_output' &&
+			result.success &&
+			!postOverride?.isError &&
+			!this.config.abortSignal.aborted
+		) {
+			try {
+				parseStructuredResultJson(sourceOutput)
+				structuredResultJson = sourceOutput
+			} catch {
+				// Keep the completion receipt: malformed host output fails at the
+				// normal candidate-integrity boundary, never as a schema correction.
+			}
+		}
 
 		// Compression is opportunistic and shell-only; the budget is the
 		// hard bound that applies to every final tool result, including a
@@ -2006,6 +2098,10 @@ export class ToolExecutor {
 		// unusable: the model was told a successful call had gone wrong, and
 		// routed around it.
 		const effectiveIsError = !result.success || (postOverride?.isError ?? false)
+		const visibleInputFailure =
+			!result.success && !postOverride && !this.config.abortSignal.aborted
+				? inputFailure
+				: undefined
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
@@ -2067,16 +2163,27 @@ export class ToolExecutor {
 		// call it has already removed. Detached work reporting after a timeout is
 		// ignored because close() also revokes the publisher.
 		await settleProgress()
+		if (this.config.abortSignal.aborted) structuredResultJson = undefined
 		await this.emitEvent({
 			type: 'tool_completed',
 			turnId: this.config.turnId,
 			toolUseId: toolCall.id,
 			toolName,
 			result: output,
-			...(!postOverride && !budgeted.truncated && rawOutput === output
-				? this.resultPresentation(toolName, input, result)
-				: {}),
+			// The result view only describes an output the host will show as is; the
+			// saved label never depended on the output, so it is kept regardless.
+			...this.resultPresentation(
+				toolName,
+				input,
+				result,
+				Boolean(postOverride) || budgeted.truncated || rawOutput !== output,
+			),
+			// Typed fields for the person's view. A replaced output is a redaction
+			// the host chose, and a structured copy of the original would undo it.
+			...(result.facts !== undefined && !postOverride ? { facts: result.facts } : {}),
 			isError: effectiveIsError,
+			...(visibleInputFailure ? { inputFailure: visibleInputFailure } : {}),
+			...(structuredResultJson !== undefined ? { structuredResultJson } : {}),
 			durationMs,
 			// Pre-truncation size, so a host can show "returned 2.1 MB" even
 			// though the model only ever saw a preview.
@@ -2094,11 +2201,23 @@ export class ToolExecutor {
 			result,
 		})
 
+		if (prepared && executedDefinition && !effectiveIsError && !this.config.abortSignal.aborted) {
+			this.recordExecutedObservation(
+				toolCall,
+				toolName,
+				executedDefinition,
+				input,
+				modelContent ?? output,
+			)
+		}
+
 		return {
 			toolCallId: toolCall.id,
 			toolName,
 			output,
 			isError: effectiveIsError,
+			...(visibleInputFailure ? { inputFailure: visibleInputFailure } : {}),
+			...(structuredResultJson !== undefined ? { structuredResultJson } : {}),
 			// Rich content follows the override's own decision.
 			//
 			// An ERROR override drops it: the payload is no longer the tool's,
@@ -2327,7 +2446,8 @@ export class ToolExecutor {
 		input: unknown,
 		signal: AbortSignal,
 	): Promise<PreparedNestedCall> {
-		const prepare = this.config.tools.prepareExecution
+		signal.throwIfAborted()
+		const prepare = this.config.tools.prepareExecutionAsync ?? this.config.tools.prepareExecution
 		const executePrepared = this.config.tools.executePrepared
 		if (typeof prepare !== 'function' || typeof executePrepared !== 'function') {
 			if (this.config.authorizationGate) {
@@ -2345,15 +2465,18 @@ export class ToolExecutor {
 					input: preOutcome.input,
 					message: preOutcome.output,
 					isError: preOutcome.kind === 'error',
+					...(preOutcome.kind === 'skip' ? { skipped: true as const } : {}),
 				}
 			}
 			return { kind: 'legacy', input: preOutcome.input }
 		}
 
-		let preparation: ReturnType<typeof prepare>
+		let preparation: Awaited<ReturnType<typeof prepare>>
 		try {
-			preparation = prepare.call(this.config.tools, toolName, input)
+			preparation = await prepare.call(this.config.tools, toolName, input, signal)
+			signal.throwIfAborted()
 		} catch (err) {
+			signal.throwIfAborted()
 			// A name the registry does not hold is answered with what this step
 			// can call, as a model's own call is; the registry's "Not found"
 			// lists everything it holds.
@@ -2387,6 +2510,7 @@ export class ToolExecutor {
 				input: preOutcome.input,
 				message: preOutcome.output,
 				isError: preOutcome.kind === 'error',
+				...(preOutcome.kind === 'skip' ? { skipped: true as const } : {}),
 			}
 		}
 		if (!preOutcome.modified) {
@@ -2396,7 +2520,8 @@ export class ToolExecutor {
 				prepared: preparation.prepared,
 			}
 		}
-		const modified = prepare.call(this.config.tools, toolName, preOutcome.input)
+		const modified = await prepare.call(this.config.tools, toolName, preOutcome.input, signal)
+		signal.throwIfAborted()
 		if (!modified.success) {
 			return {
 				kind: 'synthetic',
@@ -2534,6 +2659,7 @@ export class ToolExecutor {
 		toolCall: ToolCall,
 		reason: string,
 		preparedCall?: PreparedDirectCall,
+		declined?: ToolCallDeclined,
 	): Promise<ToolCallOutcome> {
 		const toolName = preparedCall?.toolName ?? toolCall.function.name
 		let input: unknown = preparedCall?.input ?? {}
@@ -2579,12 +2705,58 @@ export class ToolExecutor {
 			toolUseId: toolCall.id,
 			toolName,
 			result: output,
+			// Recorded only for a person's No. Every other refusal keeps the
+			// shape it always had: no presentation at all.
+			...(declined ? { presentation: this.declinedPresentation(toolName, input, declined) } : {}),
+			// A refusal by policy says what kind it was; the person's own No is
+			// already carried by the presentation above.
+			...(declined ? {} : { facts: refusalFacts(toolName, input) }),
 			isError: true,
 		})
 
 		return { toolCallId: toolCall.id, toolName, output, isError: true }
 	}
 
+	/**
+	 * What a host replays for a call the person declined. The label names the
+	 * target of the call (a path, a command) and nothing is inferred from the
+	 * refusal text: the note comes from the review answer.
+	 */
+	private declinedPresentation(
+		toolName: string,
+		input: unknown,
+		declined: ToolCallDeclined,
+	): ToolCallView {
+		let target: string | undefined
+		try {
+			const view = this.config.tools.get(toolName)?.presentCall?.(input)
+			const text =
+				view?.kind === 'generic'
+					? view.label
+					: view?.kind === 'diff'
+						? view.path || view.label
+						: view?.kind === 'terminal'
+							? view.command
+							: undefined
+			target = text
+				?.split(/\r?\n/)
+				.find((line) => line.trim())
+				?.trim()
+				.slice(0, 200)
+		} catch {
+			// A presentation hook must not turn a refusal into a failure.
+		}
+		// Cut by code point so a surrogate pair is never split.
+		const note = Array.from(declined.note?.trim() ?? '')
+			.slice(0, DECLINED_NOTE_MAX_CHARS)
+			.join('')
+		return {
+			kind: 'generic',
+			label: target || toolName,
+			declined: note ? { note } : {},
+		}
+	}
+
 	private recordCancelledBeforeExecution(
 		toolCallId: string,
 		toolName: string,
@@ -2601,7 +2773,13 @@ export class ToolExecutor {
 		toolCallId: string,
 		toolName: string,
 		input: unknown,
-		outcome: { kind: 'skip' | 'error'; output: string },
+		outcome: {
+			kind: 'skip' | 'error'
+			output: string
+			inputFailure?: ToolCallOutcome['inputFailure']
+			skipped?: true
+			facts?: ToolFacts
+		},
 	): Promise<ToolCallOutcome> {
 		const activity = this.activityStore.create({
 			type: 'tool_call',
@@ -2632,12 +2810,17 @@ export class ToolExecutor {
 			toolName,
 			result: outcome.output,
 			isError: outcome.kind === 'error',
+			...(outcome.facts ? { facts: outcome.facts } : {}),
+			...(outcome.inputFailure ? { inputFailure: outcome.inputFailure } : {}),
+			...(outcome.skipped ? { skipped: true as const } : {}),
 		})
 		return {
 			toolCallId,
 			toolName,
 			output: outcome.output,
 			isError: outcome.kind === 'error',
+			...(outcome.inputFailure ? { inputFailure: outcome.inputFailure } : {}),
+			...(outcome.skipped ? { skipped: true as const } : {}),
 		}
 	}
 
@@ -2645,6 +2828,9 @@ export class ToolExecutor {
 		return this.recordSyntheticHookOutcome(call.toolCall.id, call.toolName, call.input, {
 			kind: call.isError ? 'error' : 'skip',
 			output: call.message,
+			...(call.facts ? { facts: call.facts } : {}),
+			...(call.inputFailure ? { inputFailure: call.inputFailure } : {}),
+			...(call.skipped ? { skipped: true as const } : {}),
 		})
 	}