@namzu/sdk 4.0.0 → 5.1.0

package/src/provider/__tests__/thinking-support.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import { assertThinkingUnsupported } from '../thinking-support.js'
+
+/**
+ * `thinking` sits on `ChatCompletionParams`, so every driver accepts it. Six
+ * of the seven in this repo did not implement it, and five of those six simply
+ * dropped the field: the caller got an ordinary completion with an empty
+ * `reasoning` array, indistinguishable from a model that chose not to reason.
+ *
+ * One driver already refused instead, with the reasoning written out. The rule
+ * was decided once and applied once — so it moved here, where a new driver
+ * inherits it rather than re-deciding it.
+ */
+describe('a driver that cannot think says so', () => {
+	it('refuses a manual thinking request', () => {
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'enabled' } }),
+		).toThrow(/TestProvider does not implement thinking/)
+	})
+
+	it('refuses an adaptive one too', () => {
+		// Both are a request to think. Refusing one and dropping the other
+		// would leave exactly the silence this exists to remove.
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'adaptive' } }),
+		).toThrow(/does not implement thinking/)
+	})
+
+	it('names the driver, not just the problem', () => {
+		// In a multi-provider setup this is the difference between a bug
+		// report about the model and a one-line config fix.
+		expect(() =>
+			assertThinkingUnsupported('BedrockProvider', { thinking: { type: 'adaptive' } }),
+		).toThrow(/BedrockProvider/)
+	})
+
+	it('says what silence would have looked like', () => {
+		let message = ''
+		try {
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'enabled' } })
+		} catch (err) {
+			message = (err as Error).message
+		}
+		expect(message).toContain('empty reasoning list')
+		expect(message).toContain('Drop `thinking`')
+	})
+
+	it('honours an explicit disable as a no-op', () => {
+		// A config shared across providers that says "do not think" should not
+		// fail on the ones that were never going to.
+		expect(() =>
+			assertThinkingUnsupported('TestProvider', { thinking: { type: 'disabled' } }),
+		).not.toThrow()
+	})
+
+	it('does nothing when the caller said nothing', () => {
+		expect(() => assertThinkingUnsupported('TestProvider', {})).not.toThrow()
+	})
+})

package/src/provider/__tests__/typed-error-classification.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest'
+
+import { classifyProviderError } from '../../types/provider/errors.js'
+import type { LLMProvider, StreamChunk } from '../../types/provider/index.js'
+import { ProviderRequestError } from '../errors.js'
+import { withProviderRetry } from '../retry.js'
+
+/**
+ * A driver that classified its own failure was coming out WORSE than one that
+ * did not, in two independent places, and both shipped.
+ *
+ * `classifyProviderError` never read `kind`. A `ProviderRequestError` fell
+ * through to the status heuristics, where a carefully-diagnosed
+ * `context_overflow` carrying a 400 became `invalid_request` — so the run
+ * loop's overflow branch, which tests for `context_length_exceeded`, could
+ * never fire for a first-party driver, and compaction relief was unreachable
+ * for exactly the drivers that had diagnosed the problem correctly.
+ *
+ * And `withProviderRetry` rethrew any such error before the retry loop. Its
+ * comment justified preserving the classification, which is right; the code
+ * also skipped retrying, which is a different decision that nobody made.
+ */
+
+function providerThatFails(err: unknown): { provider: LLMProvider; calls: () => number } {
+	let calls = 0
+	const provider = {
+		id: 'test',
+		name: 'Test',
+		async *chatStream(): AsyncIterable<StreamChunk> {
+			calls++
+			throw err
+			// biome-ignore lint/correctness/useYield: it fails before producing anything
+		},
+	} as unknown as LLMProvider
+	return { provider, calls: () => calls }
+}
+
+const typed = (kind: string, status: number) =>
+	new ProviderRequestError({ kind, providerId: 'test', status, message: `a ${kind}` } as never)
+
+describe('a driver that classified its own failure is believed', () => {
+	const cases: readonly [string, number, string, boolean][] = [
+		['throttle', 429, 'rate_limit', true],
+		['server', 500, 'server_error', true],
+		['network', 0, 'network', true],
+		['auth', 401, 'auth', false],
+		['bad_request', 400, 'invalid_request', false],
+		// The one that mattered most: a 400 whose kind says the prompt was too
+		// long is not a bad request, and the difference decides whether the
+		// kernel reaches for compaction.
+		['context_overflow', 400, 'context_length_exceeded', false],
+	]
+
+	for (const [kind, status, code, retryable] of cases) {
+		it(`maps kind "${kind}" to ${code}`, () => {
+			const classified = classifyProviderError(typed(kind, status), 'test')
+			expect(classified.code).toBe(code)
+			expect(classified.retryable).toBe(retryable)
+		})
+	}
+
+	it('keeps the driver-supplied status and provider id', () => {
+		const classified = classifyProviderError(typed('throttle', 429), 'other')
+		expect(classified.status).toBe(429)
+		expect(classified.providerId).toBe('test')
+	})
+})
+
+describe('a classified failure still goes through the retry loop', () => {
+	it('retries a typed throttle', async () => {
+		// This is the regression: a first-party driver reporting a 429 as
+		// `kind: 'throttle'` used to get exactly one attempt, while the same
+		// failure from a driver that classified nothing got the full backoff.
+		const { provider, calls } = providerThatFails(typed('throttle', 429))
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetries: 2 },
+			sleepFn: async () => {},
+			random: () => 0,
+		})
+
+		await expect(async () => {
+			for await (const _ of wrapped.chatStream({} as never)) {
+				// drain
+			}
+		}).rejects.toThrow()
+
+		expect(calls()).toBe(3)
+	})
+
+	it('does not retry a typed auth failure', async () => {
+		const { provider, calls } = providerThatFails(typed('auth', 401))
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetries: 2 },
+			sleepFn: async () => {},
+		})
+
+		await expect(async () => {
+			for await (const _ of wrapped.chatStream({} as never)) {
+				// drain
+			}
+		}).rejects.toThrow()
+
+		expect(calls()).toBe(1)
+	})
+
+	it('does not retry a typed context overflow', async () => {
+		// Correctly non-retryable — an identical prompt overflows identically.
+		// The remedy is compaction, which the run loop reaches for once the
+		// code is `context_length_exceeded`.
+		const { provider, calls } = providerThatFails(typed('context_overflow', 400))
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetries: 2 },
+			sleepFn: async () => {},
+		})
+
+		await expect(async () => {
+			for await (const _ of wrapped.chatStream({} as never)) {
+				// drain
+			}
+			// The ORIGINAL escapes, so the boundary still sees the driver's
+			// own kind rather than a wrapper's code.
+		}).rejects.toMatchObject({ kind: 'context_overflow', status: 400 })
+
+		expect(calls()).toBe(1)
+	})
+
+	it('leaves an abort alone', async () => {
+		const abort = Object.assign(new Error('aborted'), { name: 'AbortError' })
+		const { provider, calls } = providerThatFails(abort)
+		const wrapped = withProviderRetry(provider, {
+			config: { maxRetries: 2 },
+			sleepFn: async () => {},
+		})
+
+		await expect(async () => {
+			for await (const _ of wrapped.chatStream({} as never)) {
+				// drain
+			}
+		}).rejects.toThrow(/aborted/)
+
+		expect(calls()).toBe(1)
+	})
+})

package/src/provider/retry.ts

@@ -111,12 +111,19 @@ export function withProviderRetry(
 				return
 			} catch (err) {
 				if (isAbortError(err) || params.signal?.aborted) throw err
-				// A driver that already classified its own failure has said
-				// everything this layer would: re-wrapping it would replace a
-				// first-hand statement with a guess, and the run boundary reads
-				// that classification to choose between a pause and a failure.
-				if (isProviderRequestError(err)) throw err
-
+				// A driver that already classified its own failure keeps that
+				// classification — `classifyProviderError` reads its `kind`
+				// first and does not re-guess.
+				//
+				// This used to rethrow such an error outright. The stated reason
+				// was sound and the code did more than it said: preserving a
+				// first-hand classification is one thing, and skipping the retry
+				// loop is another. A first-party driver that correctly reported
+				// a 429 as `kind: 'throttle'` got ZERO attempts, while the same
+				// failure from a driver that classified nothing got the full
+				// backoff — so diagnosing your own error was punished. Whether
+				// to retry is now decided the same way for both, by the
+				// classification's own `retryable`.
 				const classified = classifyProviderError(err, provider.id)
 				const exhausted = attempt >= config.maxRetries
 
@@ -133,7 +140,16 @@ export function withProviderRetry(
 								? 'retries exhausted'
 								: 'not retryable',
 					})
-					throw classified
+					// The ORIGINAL escapes when the driver classified it. Two
+					// different consumers want two different things and both are
+					// right: this loop needs a retryable verdict, which the
+					// classification supplies, and the run boundary reports
+					// `lastProviderError` as the driver's own `{kind, status,
+					// retryAfterMs}`, which only survives if the error itself
+					// does. Wrapping here would have kept the retry fix and lost
+					// the vendor's `kind` at the boundary — the existing
+					// stream-recovery test caught exactly that.
+					throw isProviderRequestError(err) ? err : classified
 				}
 
 				const serverDirected = classified.retryAfterMs

package/src/provider/thinking-support.ts

@@ -0,0 +1,37 @@
+import type { ThinkingConfig } from '../types/provider/index.js'
+
+/**
+ * Refuse a thinking request a driver does not implement.
+ *
+ * The failure this prevents is silence. `thinking` sits on
+ * `ChatCompletionParams`, so every driver accepts it; a driver that does not
+ * implement it drops the field and returns an ordinary completion with an
+ * empty `reasoning` array. The caller cannot tell that apart from a model that
+ * simply chose not to reason — the request looks honoured and the answer looks
+ * like an answer.
+ *
+ * Refusing names the driver instead, which is the difference between a bug
+ * report about the model and a one-line configuration fix.
+ *
+ * **Turning thinking OFF is honoured as a no-op**, because that is the state a
+ * driver without thinking is already in. A config shared across providers that
+ * says `{type: 'disabled'}` should not fail on the ones that were never going
+ * to think.
+ *
+ * This lived as a private copy inside one driver while five others dropped the
+ * field silently. It is here so a new driver inherits the rule instead of
+ * re-deciding it.
+ *
+ * @param driverName Named in the error, so the reader knows which provider in
+ *   a multi-provider setup refused.
+ */
+export function assertThinkingUnsupported(
+	driverName: string,
+	params: { thinking?: ThinkingConfig },
+): void {
+	const type = params.thinking?.type
+	if (type !== 'enabled' && type !== 'adaptive') return
+	throw new Error(
+		`${driverName} does not implement thinking. Silently ignoring the request would return an ordinary completion with an empty reasoning list, which reads as "the model did not reason" rather than "this driver cannot ask it to". Drop \`thinking\`, or use a driver that implements it.`,
+	)
+}

package/src/public-runtime.ts

@@ -67,7 +67,14 @@ export { extractFinalResponse } from './utils/conversation.js'
 // ─── router, runtime, run ────────────────────────────────────────────────
 
 export { resolveTaskModel } from './router/task-router.js'
+// Every driver accepts `thinking`; one that does not implement it must
+// refuse rather than drop it. Shared so a new driver inherits the rule.
+export { assertThinkingUnsupported } from './provider/thinking-support.js'
 export { drainQuery, query } from './runtime/query/index.js'
+// Mid-run guidance. A host holds the channel and the loop drains it at the
+// tool-result boundary; see the module for why that is the only legal slot.
+export { SteeringBinding, attachSteering, formatSteeringNote } from './runtime/query/steering.js'
+export type { SteeringChannel } from './runtime/query/steering.js'
 export { createMockBidiProvider, startBidiRun } from './runtime/bidi/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
 export {
@@ -135,6 +142,9 @@ export {
 	PipelineAgent,
 	ReactiveAgent,
 	RouterAgent,
+	// The short path: provider + model + prompt. Assembles the identity and
+	// budgets `drainQuery` requires and hands the generated identity back.
+	runAgent,
 	SupervisorAgent,
 } from './agents/index.js'
 

package/src/public-tools.ts

@@ -12,6 +12,10 @@
 // ─── Tool definition primitive ───────────────────────────────────────────
 
 export { defineTool } from './tools/defineTool.js'
+// Containment, for a host or sibling package that resolves caller-supplied
+// paths against a root. Both were internal while three call sites outside
+// this file needed them.
+export { isWithin, resolveWithin, resolveWithinReal } from './tools/paths.js'
 // A host that surfaces its own untrusted content to a model needs the same
 // framing the kernel applies to connector prompts and delegated results.
 export { neutralizeEnvelopeDelimiter, wrapUntrusted } from './tools/untrusted-envelope.js'

package/src/public-types.ts

@@ -99,7 +99,13 @@ export type { ContextCacheConfig, PromptCacheInput } from './runtime/query/conte
 
 export type { LimitCheckResult, LimitCheckerState, RunReporter } from './run/index.js'
 
-export type { DefineAgentOptions, Disposable } from './agents/index.js'
+export type {
+	AgentIdentity,
+	DefineAgentOptions,
+	Disposable,
+	RunAgentOptions,
+	RunAgentResult,
+} from './agents/index.js'
 
 export type {
 	ActivityEvent,

package/src/runtime/query/__tests__/steering-reaches-the-model.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+import { SteeringBinding } from '../steering.js'
+
+/**
+ * The unit tests next door prove `attachSteering` builds the right message.
+ * They would all pass with the loop never calling it — which is the exact
+ * shape of defect this repo keeps finding, and the reason this file drives a
+ * real run instead.
+ *
+ * A steer queued while a tool is running must be visible in the messages the
+ * NEXT model call receives, or the channel is another declaration nothing
+ * drives.
+ */
+
+registerMock()
+
+async function runWithSteer(steerDuringTool?: string) {
+	const steering = new SteeringBinding()
+
+	const tools = new ToolRegistry()
+	tools.register({
+		name: 'inspect',
+		description: 'looks at something',
+		inputSchema: z.object({}),
+		execute: async () => {
+			// Queued from inside the tool, which is when a host would type it:
+			// the batch is in flight and there is no legal slot for a user
+			// message until it settles.
+			if (steerDuringTool) steering.steer(steerDuringTool)
+			return { success: true, output: 'inspection done' }
+		},
+	} as never)
+
+	const provider = new MockLLMProvider({
+		turns: [
+			{ toolCalls: [{ id: 'c1', name: 'inspect', rawArguments: '{}' }] },
+			{ text: 'finished' },
+		],
+	})
+
+	await drainQuery({
+		provider,
+		tools,
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: {
+			model: 'mock-model',
+			tokenBudget: 100_000,
+			timeoutMs: 30_000,
+			maxIterations: 4,
+		},
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		steering,
+	} as never)
+
+	return { provider, steering }
+}
+
+/** Every message body the model saw on its Nth call, flattened to text. */
+function bodiesOn(provider: MockLLMProvider, call: number): string {
+	return (provider.requests[call]?.messages ?? [])
+		.map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+		.join('\n')
+}
+
+describe('guidance queued during a tool batch reaches the model', () => {
+	it('is in the messages of the next model call', async () => {
+		const { provider } = await runWithSteer('actually, check the tests as well')
+
+		expect(provider.requests.length).toBeGreaterThan(1)
+		expect(bodiesOn(provider, 1)).toContain('actually, check the tests as well')
+	})
+
+	it('rides on the tool result rather than as a separate turn', async () => {
+		const { provider } = await runWithSteer('check the tests as well')
+
+		const second = provider.requests[1]?.messages ?? []
+		const carrier = second.find((m) =>
+			typeof m.content === 'string' ? m.content.includes('check the tests as well') : false,
+		)
+
+		// The slot matters: a `tool_use` block must be answered by a
+		// `tool_result` with the same id, so a user turn wedged in here is
+		// rejected by the provider outright.
+		expect(carrier?.role).toBe('tool')
+		expect(String(carrier?.content)).toContain('inspection done')
+	})
+
+	it('is delivered once and leaves the channel empty', async () => {
+		const { steering } = await runWithSteer('one time only')
+
+		expect(steering.pending).toBe(false)
+	})
+
+	it('changes nothing when nobody steers', async () => {
+		const { provider } = await runWithSteer()
+
+		expect(bodiesOn(provider, 1)).toContain('inspection done')
+		expect(bodiesOn(provider, 1)).not.toContain('operator')
+	})
+})

package/src/runtime/query/__tests__/steering.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Message } from '../../../types/message/index.js'
+import { SteeringBinding, attachSteering, formatSteeringNote } from '../steering.js'
+
+/**
+ * `AgentManager.queueMessage` / `drainMessages` have existed for a while and
+ * nothing in the iteration loop ever read them — the type says so outright.
+ * So a host watching a run go wrong could cancel it, throwing away every tool
+ * result already paid for, or reject through the review gate, which only
+ * works when a call happens to be pending approval and says "no" when the
+ * host meant "yes, but read this first".
+ *
+ * The delivery is the interesting part. A `tool_use` block must be answered
+ * by a `tool_result` with the same id, so there is no legal slot for a user
+ * message mid-batch; this codebase had already worked that out for denials,
+ * which carry their reason inside the `tool_result` precisely because that is
+ * where the model looks.
+ */
+
+const toolMessage = (id: string, content: string): Message =>
+	({ role: 'tool', content, toolCallId: id, timestamp: 1 }) as unknown as Message
+
+const assistantMessage = (content: string): Message =>
+	({ role: 'assistant', content, timestamp: 1 }) as unknown as Message
+
+describe('steering a running turn', () => {
+	it('appends the guidance to the last tool result', () => {
+		const channel = new SteeringBinding()
+		channel.steer('check the tests too')
+
+		const out = attachSteering([toolMessage('a', 'first'), toolMessage('b', 'second')], channel)
+
+		expect(out[0]?.content).toBe('first')
+		// The LAST one: it is the final thing the model reads before deciding
+		// what to do next, where the first would be buried under every later
+		// result.
+		expect(out[1]?.content).toContain('second')
+		expect(out[1]?.content).toContain('check the tests too')
+	})
+
+	it('labels the guidance as the operator speaking, not the tool', () => {
+		const channel = new SteeringBinding()
+		channel.steer('stop and ask me first')
+
+		const out = attachSteering([toolMessage('a', 'output')], channel)
+
+		// Unlabelled it would read as something `bash` said.
+		expect(out[0]?.content).toContain('[Message from the operator')
+	})
+
+	it('accumulates repeated calls in order rather than replacing', () => {
+		const channel = new SteeringBinding()
+		channel.steer('first correction')
+		channel.steer('second correction')
+
+		const out = attachSteering([toolMessage('a', 'output')], channel)
+
+		const text = String(out[0]?.content)
+		expect(text.indexOf('first correction')).toBeLessThan(text.indexOf('second correction'))
+	})
+
+	it('ignores empty and whitespace-only guidance', () => {
+		const channel = new SteeringBinding()
+		channel.steer('   ')
+		channel.steer('')
+
+		expect(channel.pending).toBe(false)
+		expect(attachSteering([toolMessage('a', 'output')], channel)[0]?.content).toBe('output')
+	})
+
+	it('drains the channel, so guidance is delivered once', () => {
+		const channel = new SteeringBinding()
+		channel.steer('once')
+
+		attachSteering([toolMessage('a', 'output')], channel)
+		const second = attachSteering([toolMessage('b', 'later')], channel)
+
+		expect(channel.pending).toBe(false)
+		expect(second[0]?.content).toBe('later')
+	})
+
+	it('keeps guidance queued when the batch has no tool result to carry it', () => {
+		const channel = new SteeringBinding()
+		channel.steer('for the next turn')
+
+		const out = attachSteering([assistantMessage('just text')], channel)
+
+		expect(out[0]?.content).toBe('just text')
+		// Not dropped. A turn that called no tools has nothing in flight, so
+		// the guidance belongs to the next one.
+		expect(channel.pending).toBe(true)
+	})
+
+	it('leaves non-text tool content alone and re-queues rather than corrupting it', () => {
+		const channel = new SteeringBinding()
+		channel.steer('guidance')
+		const structured = {
+			role: 'tool',
+			content: [{ type: 'image', source: 'x' }],
+			toolCallId: 'a',
+			timestamp: 1,
+		} as unknown as Message
+
+		const out = attachSteering([structured], channel)
+
+		expect(out[0]?.content).toEqual([{ type: 'image', source: 'x' }])
+		expect(channel.pending).toBe(true)
+	})
+
+	it('does nothing at all without a channel', () => {
+		const messages = [toolMessage('a', 'output')]
+
+		expect(attachSteering(messages, undefined)).toBe(messages)
+	})
+
+	it('formats a note that names who is speaking', () => {
+		expect(formatSteeringNote('hello')).toContain('operator')
+		expect(formatSteeringNote('hello')).toContain('hello')
+	})
+})

package/src/runtime/query/__tests__/stream-recovery.test.ts

@@ -182,6 +182,11 @@ describe('query stream recovery', () => {
 		const run = await drainQuery(
 			{
 				provider: new ClassifiedFailureProvider(),
+				// Retry off: this pins METADATA at the boundary, and a throttle
+				// is genuinely retryable — leaving retry on would spend the run's
+				// whole timeout backing off and settle it as a timeout instead,
+				// testing the retry policy rather than the thing named here.
+				retry: { maxRetries: 0 },
 				tools: new ToolRegistry(),
 				runConfig: {
 					model: 'mock-model',

package/src/runtime/query/index.ts

@@ -98,6 +98,7 @@ import {
 	recoverCompletedCalls,
 	unansweredToolCalls,
 } from './resume-pending.js'
+import type { SteeringChannel } from './steering.js'
 import { ToolGrantSet } from './tool-grants.js'
 import { createToolPause } from './tool-pause.js'
 import { ToolingBootstrap } from './tooling.js'
@@ -151,6 +152,16 @@ export interface QueryParams {
 	 */
 	questionParks?: QuestionParkBinding
 
+	/**
+	 * Channel a host uses to hand guidance to the running turn.
+	 *
+	 * Optional and additive: absent leaves the loop byte-identical. Present,
+	 * anything queued during a tool batch is appended to that batch's last
+	 * tool result — the only slot a provider will accept text in mid-batch,
+	 * and the one the model already reads for tool outcomes.
+	 */
+	steering?: SteeringChannel
+
 	/**
 	 * The registry a re-entered `ask_user_question` reads its answer from.
 	 *
@@ -827,6 +838,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		abortController: ctx.abortController,
 		log: ctx.log,
 		resumeHandler: params.resumeHandler,
+		...(params.steering ? { steering: params.steering } : {}),
 		checkpointMgr,
 		planManager: ctx.planManager,
 		taskGateway: params.taskGateway,

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

@@ -32,6 +32,7 @@ import type { CheckpointManager } from '../../checkpoint.js'
 import type { EmitEvent } from '../../events.js'
 import type { ToolExecutor } from '../../executor.js'
 import type { GuardCoordinator } from '../../guard.js'
+import type { SteeringChannel } from '../../steering.js'
 import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface LaunchedTaskMeta {
@@ -89,6 +90,14 @@ export interface IterationContext {
 	readonly abortController: AbortController
 	readonly log: Logger
 	readonly resumeHandler: ResumeHandler
+
+	/**
+	 * Guidance a host may hand to the turn while it runs.
+	 *
+	 * Absent means the loop behaves exactly as it always has — nothing is
+	 * drained and no tool result is extended.
+	 */
+	readonly steering?: SteeringChannel
 	readonly checkpointMgr: CheckpointManager
 	readonly planManager: PlanManager
 

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

@@ -2,6 +2,7 @@ import type { ChatCompletionResponse } from '../../../../types/provider/index.js
 import type { RunEvent } from '../../../../types/run/index.js'
 import type { VerificationGate } from '../../../../verification/index.js'
 import type { ToolCallDenials } from '../../executor.js'
+import { attachSteering } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 
 interface VerificationAwareContext extends IterationContext {
@@ -82,7 +83,12 @@ export async function* runToolReview(
 		const batch = await ctx.toolExecutor.executeBatch(response, denials)
 		toolMs += Date.now() - startedAt
 		executed = batch.results
-		for (const msg of batch.messages) {
+		// Guidance the host queued while this batch was running rides out on
+		// the last result. This is the only legal slot for it: a `tool_use`
+		// block must be answered by a `tool_result` with the same id, so a
+		// user message wedged between them is rejected by the provider. Same
+		// delivery a denial already uses, without the refusal.
+		for (const msg of attachSteering(batch.messages, ctx.steering)) {
 			ctx.runMgr.pushMessage(msg)
 		}
 	}