@namzu/sdk 54.0.0 → 55.1.0

package/src/runtime/query/prompt.ts

@@ -150,6 +150,8 @@ function buildShellContext(config: PromptBuilderConfig): string | undefined {
 	return lines.length > 0 ? lines.join('\n') : undefined
 }
 
+const SEGMENT_SEPARATOR = '\n\n---\n\n'
+
 export class PromptBuilder {
 	private config: PromptBuilderConfig
 
@@ -232,67 +234,22 @@ export class PromptBuilder {
 		)
 	}
 
+	/**
+	 * The whole prompt as one string: exactly the two segments a request
+	 * sends, static then dynamic, joined by the separator. It is derived from
+	 * `buildSegmented` rather than assembled a second time, so the order the
+	 * model reads and the text the prompt-cache hash covers cannot drift apart.
+	 */
 	build(contextLevel: AgentContextLevel = 'full', workingDirectory?: string): string {
-		const parts: string[] = []
-
-		if (contextLevel === 'full' && this.config.basePrompt) {
-			parts.push(this.config.basePrompt)
-		}
-
-		if (this.config.systemPrompt) {
-			parts.push(this.config.systemPrompt)
-		} else if (this.config.persona) {
-			parts.push(assembleSystemPrompt(this.config.persona, this.config.skills))
-		} else {
-			const skillSection = this.renderSkillsInPlace()
-			if (skillSection) parts.push(skillSection)
-		}
-
-		if (this.config.systemPrompt) {
-			const skillSection = this.renderSkillsInPlace()
-			if (skillSection) parts.push(skillSection)
-		}
-
-		if (contextLevel !== 'minimal') {
-			const toolSection = this.config.tools.toPromptSection(this.config.allowedTools)
-			if (toolSection) {
-				parts.push(toolSection)
-			}
-
-			const tierGuidance = this.config.tools.toTierGuidance()
-			if (tierGuidance) {
-				parts.push(tierGuidance)
-			}
-		}
-
-		if (contextLevel !== 'minimal' && workingDirectory) {
-			const shouldIncludeEnv =
-				hasFilesystemTools(this.config.tools, this.config.allowedTools) ||
-				Boolean(this.config.runtimeContext)
-			if (shouldIncludeEnv) {
-				parts.push(buildEnvContext(workingDirectory, this.config))
-			}
-		}
-
-		// Static then dynamic, in that order and nothing between them,
-		// because that is exactly how `buildSegmented` is rejoined upstream:
-		// `${static}\n\n---\n\n${dynamic}`. The two methods produce the same
-		// prompt for the same input, and a turn that hits the prompt cache
-		// must not be asking a different question from one that misses it.
-		const shellContext = buildShellContext(this.config)
-		if (shellContext) parts.push(shellContext)
-
-		parts.push(...this.renderContributions('static', workingDirectory))
-		parts.push(...this.renderContributions('dynamic', workingDirectory))
-
-		return parts.join('\n\n---\n\n')
+		const { static: staticText, dynamic } = this.buildSegmented(contextLevel, workingDirectory)
+		return [staticText, dynamic].filter((part) => part.length > 0).join(SEGMENT_SEPARATOR)
 	}
 
 	buildSegmented(
 		contextLevel: AgentContextLevel = 'full',
 		workingDirectory?: string,
 	): PromptSegments {
-		const separator = '\n\n---\n\n'
+		const separator = SEGMENT_SEPARATOR
 		const staticParts: string[] = []
 		const dynamicParts: string[] = []
 

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

@@ -75,6 +75,12 @@ export interface PendingResumePlan {
 	readonly modifiedCallIds?: ReadonlySet<string>
 	/** Calls whose sandbox escape the durable decision confirmed; see `HITLResumeDecision`. */
 	readonly confirmedEscalations?: readonly string[]
+	/**
+	 * The park asked about some calls of the batch (the per-call review), so the
+	 * decision speaks for those and no others. Every other call that has no
+	 * recovered result is not run; see {@link applyPendingResume}.
+	 */
+	readonly partial?: true
 	/**
 	 * Answers to deliver to tools that parked on a question, keyed by the
 	 * asking call's id. Present only on a question resume.
@@ -136,6 +142,9 @@ export function planPendingResume(
 	// describe this state and applying it would be consent-by-coincidence.
 	const recordedIds = new Set(pending.request.toolCalls.map((tc) => tc.id))
 	const actualIds = assistant.toolCalls.map((tc) => tc.id)
+	if (pending.request.perCall === true) {
+		return planPartialResume(checkpoint, pending.request.toolCalls, assistant, decision, log)
+	}
 	const mismatched = actualIds.filter((id) => !recordedIds.has(id))
 	if (mismatched.length > 0 || recordedIds.size !== actualIds.length) {
 		log.error('Tool calls in the checkpoint do not match the ones the decision was made about', {
@@ -166,6 +175,118 @@ export function planPendingResume(
 	}
 }
 
+/** What a call is told when it had not run, and nobody had answered it, when the session stopped. */
+export const NOT_RUN_BEFORE_RESTART =
+	'This call had not run when the session stopped, and an earlier approval does not carry over. Ask again if it is still needed.'
+
+/**
+ * Resume a park that asked about some calls of a batch, not all of them.
+ *
+ * The decision speaks for the calls it was shown, and only those: the id check
+ * is that every one of them is still an unanswered call of the batch. Calls
+ * that already ran are answered from the record when the plan is applied, and
+ * a call that had not run and was not asked about is not run: a yes given to
+ * one call is not a yes to another.
+ */
+function planPartialResume(
+	checkpoint: RestoredCheckpoint,
+	shown: readonly ToolCallSummary[],
+	assistant: AssistantMessage,
+	decision: HITLResumeDecision,
+	log: Logger,
+): PendingResumePlan | null {
+	const calls = assistant.toolCalls ?? []
+	const byId = new Map(calls.map((call) => [call.id, call]))
+	const shownCalls = shown.map((summary) => byId.get(summary.id))
+	if (shown.length === 0 || shownCalls.some((call) => call === undefined)) {
+		log.error('The call a decision was made about is not among the unanswered tool calls', {
+			'namzu.checkpoint.id': checkpoint.id,
+			'namzu.runtime.recorded': shown.map((summary) => summary.id),
+			'namzu.runtime.actual': calls.map((call) => call.id),
+		})
+		return null
+	}
+	const asked = shownCalls as ToolCall[]
+	const denials = derivePartialDenials(asked, decision)
+	if (!denials) return null
+	const declines = derivePartialDeclines(asked, decision, shown)
+	return {
+		source: 'decision',
+		checkpointId: checkpoint.id,
+		assistant,
+		response: synthesizeResponse(assistant),
+		denials,
+		...(declines ? { declines } : {}),
+		reviewedCalls: shown,
+		modifiedCallIds: new Set(),
+		partial: true,
+		...((decision.action === 'approve_tools' || decision.action === 'modify_tools') &&
+		decision.confirmedEscalations
+			? { confirmedEscalations: decision.confirmedEscalations }
+			: {}),
+	}
+}
+
+/**
+ * The same reading of a decision the live per-call review makes: nothing the
+ * decision does not name is approved, and an edit is not offered.
+ */
+function derivePartialDenials(
+	asked: readonly ToolCall[],
+	decision: HITLResumeDecision,
+): ToolCallDenials | null {
+	switch (decision.action) {
+		case 'approve_tools':
+		case 'continue':
+			return new Map()
+		case 'reject_tools': {
+			const reason = decision.feedback || DECLINED_TOOL_CALL_FEEDBACK
+			return new Map(asked.map((call) => [call.id, reason]))
+		}
+		case 'modify_tools': {
+			const denials = new Map<string, string>()
+			for (const call of asked) {
+				const mods = decision.modifications.filter((mod) => mod.toolCallId === call.id)
+				if (mods.some((mod) => mod.action === 'deny'))
+					denials.set(call.id, DECLINED_TOOL_CALL_FEEDBACK)
+				else if (!mods.some((mod) => mod.action === 'approve')) {
+					denials.set(
+						call.id,
+						'No answer was given for this call, so it was not run. Ask again if it is still needed.',
+					)
+				}
+			}
+			return denials
+		}
+		default:
+			return null
+	}
+}
+
+function derivePartialDeclines(
+	asked: readonly ToolCall[],
+	decision: HITLResumeDecision,
+	shown: readonly ToolCallSummary[],
+): ToolCallDeclines | undefined {
+	const gateDenied = new Set(
+		shown.filter((call) => call.authorization?.decision === 'deny').map((call) => call.id),
+	)
+	if (decision.action === 'reject_tools' && decision.declined) {
+		const declined = decision.declined
+		const calls = asked.filter((call) => !gateDenied.has(call.id))
+		return calls.length > 0 ? new Map(calls.map((call) => [call.id, declined])) : undefined
+	}
+	if (decision.action === 'modify_tools') {
+		const denied = asked.filter(
+			(call) =>
+				!gateDenied.has(call.id) &&
+				decision.modifications.some((mod) => mod.toolCallId === call.id && mod.action === 'deny'),
+		)
+		if (denied.length > 0) return new Map(denied.map((call) => [call.id, {}]))
+	}
+	return undefined
+}
+
 /**
  * The stable marker `supersededByRecovery` puts at the head of its reason.
  *
@@ -432,6 +553,16 @@ export async function applyPendingResume(
 	const denials = new Map(plan.denials)
 	const reviewedById = new Map(plan.reviewedCalls?.map((call) => [call.id, call]))
 
+	// A decision about some calls is not a decision about the rest. A call that
+	// already ran is answered from the record (`prior`); one that had not run and
+	// was not asked about is not run, and the model is told so.
+	if (plan.partial) {
+		for (const call of plan.response.message.toolCalls ?? []) {
+			if (prior?.has(call.id) || reviewedById.has(call.id) || denials.has(call.id)) continue
+			denials.set(call.id, NOT_RUN_BEFORE_RESTART)
+		}
+	}
+
 	// A gate denial belongs to the turn, not to the process that first evaluated
 	// it. Restore it before preparation so denied calls do not even reach a
 	// pre-tool hook after restart.

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

@@ -664,6 +664,18 @@ export interface ToolReviewRequest {
 	 * in the session run without asking.
 	 */
 	readonly screenConsent?: true
+	/**
+	 * Set when the request is the per-call review's question about one call (or
+	 * the few asked together), not the whole batch. See `PerCallReviewConfig`.
+	 */
+	readonly perCall?: true
+	/**
+	 * Aborts when the question stops being open: the turn was cancelled, a
+	 * rule or the mode now covers the call, or an earlier refusal ended the
+	 * turn. A host that shows the question closes it then; its answer is
+	 * ignored. Present only with `perCall`.
+	 */
+	readonly signal?: AbortSignal
 }
 
 export type ToolReviewAnswer =
@@ -680,6 +692,12 @@ export type ToolReviewAnswer =
 			 * cannot carry this. `note` is the person's own words.
 			 */
 			readonly declined?: ToolCallDeclined
+			/**
+			 * The refusal also ends the turn: see `endTurn` on the `reject_tools`
+			 * decision. A plain No sets it; a No that carries the person's reason
+			 * leaves it out so the model reads the reason and carries on.
+			 */
+			readonly endTurn?: true
 	  }
 
 /** How a host asks a person. The one thing the kernel cannot supply. */
@@ -955,6 +973,8 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				turnId: request.turnId,
 				toolCalls: request.toolCalls,
 				...(screenConsent ? { screenConsent } : {}),
+				...(request.perCall ? { perCall: true as const } : {}),
+				...(request.perCall && context?.signal ? { signal: context.signal } : {}),
 			})
 		// The first look at the screen in a session is the operator's to allow:
 		// what is on it goes to the model provider, and a screenshot reads as
@@ -982,6 +1002,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? SCREEN_CONSENT_DECLINED_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			consent.sessions.add(sessionKey)
@@ -1038,6 +1059,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 						action: 'reject_tools',
 						feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 						...(answer.declined ? { declined: answer.declined } : {}),
+						...(answer.endTurn ? { endTurn: true as const } : {}),
 					}
 				}
 				if (answer.kind === 'approve-all') remembered.all = true
@@ -1145,6 +1167,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			// "Approve all" still latches for the calls that follow; it never
@@ -1164,6 +1187,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			// Latches for the ordinary calls that follow, never for the next floor.
@@ -1182,6 +1206,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			// Latches for the ordinary calls that follow, never for the next path.
@@ -1202,6 +1227,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			if (answer.kind === 'approve-all') remembered.all = true
@@ -1222,6 +1248,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 			}
 			if (answer.kind === 'approve-all') remembered.all = true
@@ -1272,6 +1299,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					action: 'reject_tools',
 					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 					...(answer.declined ? { declined: answer.declined } : {}),
+					...(answer.endTurn ? { endTurn: true as const } : {}),
 				}
 		}
 	}

package/src/runtime/query/steering.ts

@@ -1,4 +1,6 @@
+import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message, UserMessage } from '../../types/message/index.js'
+import { NOTICE_TAG, frameNotice, readOperatorNotice } from '../../types/message/notice-frame.js'
 import {
 	MONITOR_EVENT_CONTENT_MAX_CHARS,
 	MONITOR_NOTIFICATION_MAX_CHARS,
@@ -20,28 +22,24 @@ export function isOperatorUserMessage(message: Message): message is UserMessage
 /**
  * Guidance a host hands to a turn that is already running.
  *
- * This tool-result channel is distinct from `inboundMessages`. The manager
- * injects its mailbox through that callback, and query-backed agents consume
- * it at provider-valid message boundaries. Custom agents must consume their
- * injected callback themselves. This channel instead lets a host attach
- * guidance to a completed tool batch without adding another user message.
+ * This channel is distinct from `inboundMessages`. The manager injects its
+ * mailbox through that callback, and query-backed agents consume it at
+ * provider-valid message boundaries. Custom agents must consume their injected
+ * callback themselves. This channel instead lets a host attach guidance to a
+ * settled tool batch.
  *
- * **Why the text rides on a tool result rather than arriving as a user
- * message.** A `tool_use` block must be answered by a `tool_result` with the
- * same id — providers reject a user turn wedged between them — so there is no
- * legal place to insert a message mid-batch at all. The slot that already
- * exists is the tool result itself, and this codebase had already worked that
- * out for a neighbouring case: a denied call carries its reason INSIDE the
- * `tool_result`, and `executor.ts` notes that this is also what makes a
- * rejection *steer*, because the model reads it in the slot it already
- * attends to for tool outcomes. Steering is the same delivery with the
- * refusal removed.
+ * **Where the text lands.** A `tool_use` block must be answered by a
+ * `tool_result` with the same id, so nothing can sit between them. The
+ * guidance therefore follows the finished batch as a user-role message of its
+ * own, at the next request boundary, framed as the operator's words. It is not
+ * written into a tool result: a tool result carries only what the tool
+ * returned, and a model reads instructions placed inside one as tool output.
  *
- * It does not interrupt. The batch in flight
- * finishes, and the guidance lands where the model looks next. A host that
- * wants the current work stopped wants `AbortSignal`, which is a different
- * question with a different answer — and conflating the two is how "please
- * also check the tests" ends up killing a half-written file.
+ * It does not interrupt. The batch in flight finishes, and the guidance lands
+ * where the model looks next. A host that wants the current work stopped wants
+ * `AbortSignal`, which is a different question with a different answer, and
+ * conflating the two is how "please also check the tests" ends up killing a
+ * half-written file.
  */
 export interface SteeringChannel {
 	/**
@@ -53,7 +51,7 @@ export interface SteeringChannel {
 	 * discards a host's instruction.
 	 *
 	 * Empty and whitespace-only text is ignored, so a stray keystroke does
-	 * not append a blank line to a tool result.
+	 * not send a blank message.
 	 */
 	steer(text: string): void
 
@@ -85,60 +83,9 @@ export class SteeringBinding implements SteeringChannel {
 	}
 }
 
-/**
- * The frame the guidance arrives in.
- *
- * Labelled because the model is being handed text from a party other than the
- * tool whose result it is reading, in that tool's slot. Unlabelled, it reads
- * as something the tool said — so a steer saying "stop and ask me first" would
- * look like output from `bash`.
- *
- * This is NOT the untrusted-content envelope. The host operating the turn is
- * the one party whose words the agent SHOULD act on; framing them as material
- * to be worked with rather than followed would inverting the very thing the
- * host is trying to do. Different party, different frame, on purpose.
- */
-/** The same slot as steering, for notices the kernel itself has to deliver. */
-export function attachNotice(
-	messages: readonly Message[],
-	channel: SteeringChannel | undefined,
-	format: (text: string) => string,
-	/**
-	 * Told only when the text actually landed on a result the model will read.
-	 *
-	 * Not on the two paths above it: a batch with no tool result leaves the
-	 * notice queued, and a result whose content is not a string puts it back.
-	 * Draining is therefore not delivery, which matters to the caller that
-	 * keeps its own record of what the text accounts for — `AwaitedJobs`
-	 * drops an exit's entry here, and a premature drop would strand the exit.
-	 */
-	onDelivered?: () => void,
-): readonly Message[] {
-	if (!channel?.pending) return messages
-	let lastToolIndex = -1
-	for (let index = messages.length - 1; index >= 0; index--) {
-		if (messages[index]?.role === 'tool') {
-			lastToolIndex = index
-			break
-		}
-	}
-	if (lastToolIndex === -1) return messages
-	const text = channel.drain()
-	if (text === undefined) return messages
-	const target = messages[lastToolIndex] as Message
-	if (typeof target.content !== 'string') {
-		channel.steer(text)
-		return messages
-	}
-	const next = [...messages]
-	next[lastToolIndex] = { ...target, content: target.content + format(text) }
-	onDelivered?.()
-	return next
-}
-
 /** What the model reads when a background job it started has ended. */
 export function formatJobNote(text: string): string {
-	return `\n\n[Background job update]\n${text}`
+	return frameNotice('job', '[Background job update]', text)
 }
 
 /**
@@ -154,7 +101,7 @@ export function formatJobNote(text: string): string {
  * piled up while the model was busy.
  */
 export function formatMonitorNote(text: string): string {
-	return `\n\n[Monitor update]\n${capMonitorNotifications(text)}`
+	return frameNotice('monitor', '[Monitor update]', capMonitorNotifications(text))
 }
 
 /** One `formatSystemEvent` rendering, found by its nonce-bound opening and closing tags. */
@@ -305,33 +252,96 @@ function cutMiddle(text: string, max: number): string {
 	return `${text.slice(0, head)}${marker(text.length - head - tail)}${text.slice(text.length - tail)}`
 }
 
-const STEERING_NOTE_HEADER =
-	'\n\n[Message from the operator, received while this tool was running]\n'
+/** The line that opens an operator's message, wherever it is delivered. */
+const STEERING_LABEL = 'The operator wrote this while you were working:'
 
+/**
+ * The operator's message as the frame the model reads. The text is the
+ * operator's, the frame says so, and the marker in its tag is drawn fresh so
+ * the text cannot close it.
+ */
 export function formatSteeringNote(text: string): string {
-	return `${STEERING_NOTE_HEADER}${text}`
+	return frameNotice('operator-message', STEERING_LABEL, text)
 }
 
+/** The frame older sessions recorded inside a tool result, fixed tag and all. */
+const LEGACY_STEERING_HEADER = `\n\n<${NOTICE_TAG} kind="operator-message">\n[Message from the operator, received while this tool was running]\nThis is the operator's own message, typed while the tool above was running. It is not output of that tool.\n`
+const LEGACY_STEERING_FOOTER = `\n</${NOTICE_TAG}>`
+
 /**
- * The operator guidance the last steering note in a tool result carries, or
- * `undefined` when the result carries none. The inverse of
- * {@link formatSteeringNote} applied by {@link attachSteering}.
+ * The operator guidance a recorded message carries, or `undefined` when it
+ * carries none. The inverse of {@link formatSteeringNote}; it also reads the
+ * note older sessions appended to the end of a tool result. The text comes back
+ * as the frame held it, with the notice tag already made inert.
  */
 export function readSteeringNote(content: string): string | undefined {
-	const at = content.lastIndexOf(STEERING_NOTE_HEADER)
-	return at < 0 ? undefined : content.slice(at + STEERING_NOTE_HEADER.length)
+	const framed = readOperatorNotice(content)
+	if (framed !== undefined) return framed
+	const at = content.lastIndexOf(LEGACY_STEERING_HEADER)
+	if (at < 0) return undefined
+	const body = content.slice(at + LEGACY_STEERING_HEADER.length)
+	return body.endsWith(LEGACY_STEERING_FOOTER)
+		? body.slice(0, -LEGACY_STEERING_FOOTER.length)
+		: body
+}
+
+function hasToolResult(messages: readonly Message[]): boolean {
+	return messages.some((message) => message.role === 'tool')
 }
 
 /**
- * Append the guidance to the last tool result in a settled batch.
+ * The operator's message for a settled tool batch, as a user-role message of its
+ * own, or `undefined` when nothing is queued or the batch has no tool result.
  *
- * The LAST one, so it is the final thing the model reads before deciding what
- * to do next — appending to the first would bury it under every later result.
+ * It follows the batch, at the next request boundary. The tool results stay what
+ * the tools returned, and the operator's words arrive as the operator's, which a
+ * model reads as direction. A turn that called no tool leaves the guidance
+ * queued; the loop delivers it at the next-turn boundary.
+ */
+export function takeSteeringMessage(
+	messages: readonly Message[],
+	channel: SteeringChannel | undefined,
+	/** Receives accepted operator text, never inferred from a tool's output. */
+	onDelivered?: (text: string) => void,
+): UserMessage | undefined {
+	if (!channel?.pending || !hasToolResult(messages)) return undefined
+	const guidance = channel.drain()
+	if (guidance === undefined) return undefined
+	onDelivered?.(guidance)
+	return createRuntimeContextMessage(formatSteeringNote(guidance), 'steering')
+}
+
+/**
+ * A kernel notice (a job's exit, a monitor's events) for a settled tool batch,
+ * as a user-role message of its own, under the same rules as
+ * {@link takeSteeringMessage}.
+ */
+export function takeNoticeMessage(
+	messages: readonly Message[],
+	channel: SteeringChannel | undefined,
+	format: (text: string) => string,
+	/**
+	 * Told only when the text actually became a message the model will read.
+	 * Draining is not delivery, which matters to the caller that keeps its own
+	 * record of what the text accounts for: `AwaitedJobs` drops an exit's entry
+	 * here, and a premature drop would strand the exit.
+	 */
+	onDelivered?: () => void,
+): UserMessage | undefined {
+	if (!channel?.pending || !hasToolResult(messages)) return undefined
+	const text = channel.drain()
+	if (text === undefined) return undefined
+	onDelivered?.()
+	return createRuntimeContextMessage(format(text), 'job-exit')
+}
+
+/**
+ * Append the guidance to the last tool result in a settled batch.
  *
- * Returns the messages unchanged when there is nothing queued, and when the
- * batch carries no tool result to attach to. The second case is not a failure
- * to handle: a turn that called no tools has nothing in flight, so guidance
- * belongs to the next turn and stays queued for it.
+ * @deprecated The kernel no longer delivers guidance this way: a tool result
+ * carries only what the tool returned, and {@link takeSteeringMessage} sends the
+ * operator's words as a message of their own. Kept so a host that calls it keeps
+ * working.
  */
 export function attachSteering(
 	messages: readonly Message[],
@@ -354,12 +364,6 @@ export function attachSteering(
 	if (guidance === undefined) return messages
 
 	const target = messages[lastToolIndex] as Message
-	// Only text is extended. A tool that answered with structured content —
-	// an image block, say — has a shape the model reads positionally, and
-	// appending a string to it would either be dropped or corrupt the block.
-	// Such a result keeps its content and the note follows it as its own text
-	// part where the shape allows, and otherwise the guidance stays queued
-	// for the next turn rather than being forced into a slot it does not fit.
 	if (typeof target.content !== 'string') {
 		channel.steer(guidance)
 		return messages
@@ -368,7 +372,7 @@ export function attachSteering(
 	const next = [...messages]
 	next[lastToolIndex] = {
 		...target,
-		content: target.content + formatSteeringNote(guidance),
+		content: `${target.content}\n\n${formatSteeringNote(guidance)}`,
 	}
 	onDelivered?.(guidance)
 	return next