@namzu/sdk 36.0.0 → 38.0.0

package/src/runtime/query/iteration/native-output.ts

@@ -0,0 +1,35 @@
+import type { z } from 'zod'
+import type { ChatCompletionResponse } from '../../../types/provider/index.js'
+import { cloneJsonValue } from '../../../utils/json-snapshot.js'
+
+/** Native constraints are transport assistance; local validation still owns acceptance. */
+export async function parseNativeCandidate(
+	schema: z.ZodType,
+	response: ChatCompletionResponse,
+	signal: AbortSignal,
+): Promise<{ success: true; value: unknown } | { success: false }> {
+	signal.throwIfAborted()
+	if (response.finishReason !== 'stop' || response.message.toolCalls?.length)
+		return { success: false }
+	let input: unknown
+	try {
+		input = JSON.parse(response.message.content ?? '')
+	} catch {
+		return { success: false }
+	}
+	let abort!: () => void
+	const cancelled = new Promise<never>((_resolve, reject) => {
+		abort = () => reject(signal.reason ?? new Error('Native output validation cancelled'))
+		signal.addEventListener('abort', abort, { once: true })
+	})
+	try {
+		const parsed = await Promise.race([schema.safeParseAsync(input), cancelled])
+		signal.throwIfAborted()
+		if (!parsed.success) return { success: false }
+		// Match the serialized result contract of output-tool mode. Never rerun transforms.
+		const value = cloneJsonValue(parsed.data, false)
+		return { success: true, value }
+	} finally {
+		signal.removeEventListener('abort', abort)
+	}
+}

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

@@ -5,6 +5,7 @@ import { toolResultToText } from '../../../../types/message/content.js'
 import { createRuntimeContextMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import { toErrorMessage } from '../../../../utils/error.js'
+import { activeContextWindow, measureContext } from './compaction.js'
 import type { IterationContext } from './context.js'
 
 function countToolCalls(ctx: IterationContext): number {
@@ -18,9 +19,8 @@ function countToolCalls(ctx: IterationContext): number {
 }
 
 function estimateContextWindowPercent(ctx: IterationContext): number {
-	const budget = ctx.runConfig.tokenBudget
-	if (budget <= 0) return 0
-	return (ctx.runMgr.tokenUsage.totalTokens / budget) * 100
+	const window = activeContextWindow(ctx)
+	return (measureContext(ctx).tokens / window.tokens) * 100
 }
 
 function computeCostBudgetPercent(ctx: IterationContext): number | undefined {
@@ -67,7 +67,7 @@ export async function runAdvisoryPhase(
 		contextWindowPercent: estimateContextWindowPercent(ctx),
 		totalCostUsd: ctx.runMgr.costInfo.totalCost,
 		costBudgetPercent: computeCostBudgetPercent(ctx),
-		lastError: extractLastErrorFromMessages(ctx),
+		lastError: extractCurrentToolErrors(ctx, response),
 		lastToolCategory: extractLastToolCategory(ctx, response),
 		advisoryCallCount: advisoryCtx.callHistory.length,
 	}
@@ -190,16 +190,26 @@ export async function runAdvisoryPhase(
 	}
 }
 
-function extractLastErrorFromMessages(ctx: IterationContext): string | undefined {
+function extractCurrentToolErrors(
+	ctx: IterationContext,
+	response: ChatCompletionResponse,
+): string | undefined {
+	const calls = new Map(response.message.toolCalls?.map((call) => [call.id, call.function.name]))
+	if (calls.size === 0) return undefined
 	const messages = ctx.runMgr.messages
+	const errors: string[] = []
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i]
-		if (msg?.role === 'tool') {
-			// Tool results can now carry content blocks; the error sentinel is
-			// a text convention, so flatten before matching it.
-			const text = toolResultToText(msg.content)
-			if (text.startsWith('Error:')) return text
+		// The current assistant turn starts this batch. Never resurrect an old
+		// failure, even if a provider reused a call ID in another iteration.
+		if (msg?.role === 'assistant') break
+		if (msg?.role === 'tool' && msg.isError === true && calls.has(msg.toolCallId)) {
+			errors.push(
+				toolResultToText(msg.content).trim() ||
+					`Tool ${calls.get(msg.toolCallId)} reported an error.`,
+			)
 		}
 	}
-	return undefined
+	// A successful sibling does not erase failed results in this same batch.
+	return errors.length > 0 ? errors.reverse().join('\n') : undefined
 }

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

@@ -28,6 +28,16 @@ import { isWorkingMemoryMessage } from './working-memory.js'
 // because `runtime/query/index.ts` already imports it from this path.
 export { isCompactionMessage } from '../../../../compaction/summary.js'
 
+/** The selected request model owns the denominator, including overflow recovery. */
+export function activeContextWindow(ctx: IterationContext) {
+	const model = ctx.contextModel ?? ctx.runConfig.model
+	return resolveContextWindow(
+		ctx.compactionConfig?.contextWindowTokens,
+		model,
+		model === ctx.runConfig.model ? ctx.providerContextWindow : ctx.activeProviderContextWindow,
+	)
+}
+
 /**
  * How much a forced pass must shed before the turn is worth retrying.
  *
@@ -147,7 +157,12 @@ async function commitToolResultClear(
 	plan: ToolResultClearPlan,
 	contextWindowTokens: number,
 	windowSource: 'config' | 'provider' | 'model-table' | 'default',
+	reason: 'threshold' | 'overflow',
 ): Promise<void> {
+	// A shorter replacement also removes evidence. Preserve its original
+	// content in the same archive used by whole-message compaction before
+	// changing the live history or publishing the clear.
+	await recordShed(ctx, [...ctx.runMgr.messages], plan.messages, reason)
 	installMessages(ctx.runMgr.messages, plan.messages)
 	// The provider counted the pre-edit prompt. Leaving that measurement live
 	// makes the next trigger compare the old prompt against the new history.
@@ -547,11 +562,7 @@ async function runCompactionCheckInner(
 	// number. Nothing in the estate ever set `contextWindowTokens`, so the
 	// fallback WAS the behavior, and the shipped CLI's 1M budget put the
 	// trigger at ~700k. See `compaction/context-window.ts`.
-	const window = resolveContextWindow(
-		config.contextWindowTokens,
-		ctx.runConfig.model,
-		ctx.providerContextWindow,
-	)
+	const window = activeContextWindow(ctx)
 	const budget = window.tokens
 
 	const usage = estimatedTokens / budget
@@ -659,7 +670,7 @@ async function runCompactionCheckInner(
 			...(openTasks ? { openTasks } : {}),
 		})
 		if (working.reclaimedTokens > 0) {
-			await commitToolResultClear(ctx, working, budget, window.source)
+			await commitToolResultClear(ctx, working, budget, window.source, pass.reason)
 		}
 		// Under the trigger, the working set was the whole pass: the summary
 		// path is for the trigger, not for the soft target.
@@ -684,7 +695,7 @@ async function runCompactionCheckInner(
 		// the NEXT turn will correct it, and an over-eager summarization is
 		// far more costly than one late pass.
 		if (clearPlan.reliefWasEnough) {
-			await commitToolResultClear(ctx, clearPlan, budget, window.source)
+			await commitToolResultClear(ctx, clearPlan, budget, window.source, pass.reason)
 			return
 		}
 	}
@@ -736,7 +747,7 @@ async function runCompactionCheckInner(
 		// There is no opaque provider wait on this path, so publish that single
 		// complete edit now rather than discarding it.
 		if (stagedClear) {
-			await commitToolResultClear(ctx, stagedClear, budget, window.source)
+			await commitToolResultClear(ctx, stagedClear, budget, window.source, pass.reason)
 		}
 		return
 	}
@@ -823,6 +834,20 @@ async function runCompactionCheckInner(
 
 	const live = ctx.runMgr.messages
 	const oldCount = live.length
+	// Retained history can survive in full while a summary adds another copy
+	// of its facts. Even an unretained span may be smaller than the cumulative
+	// summary. Compare both candidates with the same estimator, rather than
+	// comparing provider usage against an estimate or trusting message count.
+	// When a clear was staged, require the summary itself to improve on it;
+	// otherwise publish the useful clear without consuming its savings.
+	if (estimateMessagesTokens(newMessages) >= estimateMessagesTokens(messages)) {
+		if (stagedClear && stagedClear.reclaimedTokens > 0) {
+			await commitToolResultClear(ctx, stagedClear, budget, window.source, pass.reason)
+		} else {
+			await declined(ctx, 'shed_nothing', oldCount)
+		}
+		return
+	}
 	await recordShed(ctx, [...live], newMessages, options?.force ? 'overflow' : 'threshold')
 
 	installMessages(live, newMessages)
@@ -840,12 +865,9 @@ async function runCompactionCheckInner(
 	// edits are installed and no verifier can still fail between them.
 	if (stagedClear) await emitToolResultClear(ctx, stagedClear)
 
-	// Hysteresis. A pass that only gets the context from 0.72 to 0.71 of the
-	// window leaves the trigger armed, so the next iteration compacts again
-	// — paying a summarization call and busting the prompt-cache prefix each
-	// time, for nothing. Report the shortfall rather than repeating a move
-	// that demonstrably does not work; `resetThreshold` was declared and
-	// CLI-set but read by nothing until now.
+	// Report remaining pressure after a useful edit. This diagnostic does not
+	// suppress future passes: appended evidence may become reclaimable even
+	// when the protected floor and recent history remain above the target.
 	const reachedReset = newEstimate / budget <= config.resetThreshold
 	if (!reachedReset) {
 		ctx.log.warn('Compaction did not reach its reset threshold — context may still be tight', {

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

@@ -131,6 +131,8 @@ export interface IterationContext {
 	 * drained and no tool result is extended.
 	 */
 	readonly steering?: SteeringChannel
+	/** Records operator intent only after guidance was accepted by a tool result. */
+	readonly onSteeringDelivered?: (text: string) => void
 	/** Exit notices for the run's background jobs, drained into the next tool result. */
 	readonly jobNotices?: SteeringChannel
 	readonly checkpointMgr: CheckpointManager
@@ -179,6 +181,11 @@ export interface IterationContext {
 	 * through to the table.
 	 */
 	readonly providerContextWindow?: number
+	/** Selected request model; its window must not reuse another model's metadata. */
+	contextModel?: string
+	activeProviderContextWindow?: number
+	/** Bounded, run-cached provider metadata lookup for a newly selected model. */
+	readonly resolveModelContextWindow?: (model: string) => Promise<number | undefined>
 
 	/**
 	 * Text queued for this run since its last turn.
@@ -188,6 +195,8 @@ export interface IterationContext {
 	 * after tool results and before the next turn.
 	 */
 	readonly inboundMessages?: () => readonly import('../../../../types/message/index.js').Message[]
+	/** Known topic-queue arrivals appended after the restored checkpoint history. */
+	readonly resumedInput?: readonly import('../../../../types/message/index.js').Message[]
 	/** Observes pending input without draining it; abort releases the waiter. */
 	readonly waitForInbound?: (signal: AbortSignal) => Promise<void>
 

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

@@ -146,7 +146,11 @@ export async function* runToolReview(
 		// user message wedged between them is rejected by the provider. Same
 		// delivery a denial already uses, without the refusal.
 		for (const msg of attachRepeatNotice(
-			attachNotice(attachSteering(batch.messages, ctx.steering), ctx.jobNotices, formatJobNote),
+			attachNotice(
+				attachSteering(batch.messages, ctx.steering, ctx.onSteeringDelivered),
+				ctx.jobNotices,
+				formatJobNote,
+			),
 			notices,
 		)) {
 			ctx.runMgr.pushMessage(msg)

package/src/runtime/query/iteration/phases/working-memory.ts

@@ -14,6 +14,10 @@ import type { IterationContext } from './context.js'
 export const WORKING_MEMORY_HEADER =
 	'[WORKING MEMORY] Authoritative state for this conversation — you produced these.'
 
+// Stored in the message, so ownership survives checkpoint JSON. Unmarked
+// inherited blocks may be opaque host ledgers and must never be guessed away.
+const TOOL_PINS_HEADER = `${WORKING_MEMORY_HEADER}\n[Tool-managed pins]`
+
 /**
  * True when `content` is the pinned working-memory slot (header identity only).
  * Shared with `compaction.ts` so the survival guard re-pins by the SAME rule.
@@ -34,16 +38,15 @@ export function isWorkingMemoryMessage(content: string | null | undefined): bool
  *
  * Failure-isolated (the `web-search` seam rule): a throwing/slow provider
  * degrades to "no refresh this turn" (keeps the prior slot), never breaks the
- * run. Early-returns when no provider is configured ⇒ byte-identical run path.
+ * run. With no provider or tool-owned slot, the history is left unchanged.
  */
 export async function refreshWorkingMemory(ctx: IterationContext): Promise<void> {
 	const provider = ctx.workingMemoryProvider
 	// What the tools pinned joins the slot beside what the host provides: a
 	// pin exists to be in front of the model every iteration, and until this
 	// the working state reached the history only through a compaction
-	// summary. No provider and no pins leaves the history untouched.
+	// summary. When the final pin is removed, retire only a tool-owned slot.
 	const pinned = ctx.workingStateManager ? renderPins(ctx.workingStateManager.getState()) : null
-	if (!provider && !pinned) return
 
 	let block = ''
 	if (provider) {
@@ -80,17 +83,32 @@ export async function refreshWorkingMemory(ctx: IterationContext): Promise<void>
 		}
 	}
 
+	if (!provider && !pinned) {
+		if (!ctx.workingStateManager) return
+		const prior = msgs[idx]?.content
+		if (typeof prior !== 'string' || !prior.startsWith(TOOL_PINS_HEADER)) return
+	}
+
 	if (!block.trim()) {
 		// Empty block ⇒ remove the slot (byte-identical-when-empty).
-		if (idx >= 0) msgs.splice(idx, 1)
+		if (idx >= 0) {
+			msgs.splice(idx, 1)
+			ctx.runMgr.clearLastPromptTokens?.()
+		}
 		return
 	}
 
-	const wm = createSystemMessage(`${WORKING_MEMORY_HEADER}\n\n${block}`, 'ephemeral')
+	const header = provider ? WORKING_MEMORY_HEADER : TOOL_PINS_HEADER
+	const content = `${header}\n\n${block}`
+	if (idx >= 0 && msgs[idx]?.content === content) return
+	const wm = createSystemMessage(content, 'ephemeral')
 	if (idx >= 0) {
 		msgs[idx] = wm
 	} else {
 		// Insert as the LAST leading system message (after static + dynamic).
 		msgs.splice(leadEnd, 0, wm)
 	}
+	// The old provider reading measured a different prefix, and an insertion
+	// also moves its tail watermark. Re-estimate until the next request reports.
+	ctx.runMgr.clearLastPromptTokens?.()
 }

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

@@ -1,4 +1,8 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
+import {
+	assertHostedWebSearchSupported,
+	assertNativeStructuredOutputSupported,
+} from '../../../provider/capabilities.js'
 import { isProviderRequestError } from '../../../provider/errors.js'
 import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
 import {
@@ -153,6 +157,8 @@ export async function* streamProviderTurn(
 		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
 	},
 ): 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
@@ -338,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/steering.ts

@@ -1,4 +1,15 @@
-import type { Message } from '../../types/message/index.js'
+import type { Message, UserMessage } from '../../types/message/index.js'
+
+/** User-role runtime reports are context, not new operator intent. */
+export function isOperatorUserMessage(message: Message): message is UserMessage {
+	if (message.role !== 'user') return false
+	const source = message.source
+	return (
+		!source ||
+		source.type === 'goal-round' ||
+		(source.type === 'runtime-context' && source.kind === 'steering')
+	)
+}
 
 /**
  * Guidance a host hands to a turn that is already running.
@@ -134,6 +145,8 @@ export function formatSteeringNote(text: string): string {
 export function attachSteering(
 	messages: readonly Message[],
 	channel: SteeringChannel | undefined,
+	/** Receives accepted operator text, never inferred from a tool's output. */
+	onDelivered?: (text: string) => void,
 ): readonly Message[] {
 	if (!channel?.pending) return messages
 
@@ -162,6 +175,10 @@ export function attachSteering(
 	}
 
 	const next = [...messages]
-	next[lastToolIndex] = { ...target, content: target.content + formatSteeringNote(guidance) }
+	next[lastToolIndex] = {
+		...target,
+		content: target.content + formatSteeringNote(guidance),
+	}
+	onDelivered?.(guidance)
 	return next
 }