@namzu/sdk 5.2.0 → 6.1.0

package/src/registry/tool/dialect.ts

@@ -0,0 +1,143 @@
+/**
+ * The dialect a wire speaks, and how to say the same schema in it.
+ *
+ * A tool has one Zod schema. What changes between providers is not the tool —
+ * it is the JSON Schema dialect the wire parses, which is a property of the
+ * wire. So the shape is rendered once, canonically, and each driver converts
+ * at the boundary where it knows which wire it is about to talk to.
+ *
+ * This exists because that layering was missing and it cost a production
+ * outage. `renderToolSchema` emits draft-07 (zod-to-json-schema's
+ * `jsonSchema7` target), every driver forwarded it verbatim, and one of the
+ * wires namzu speaks requires draft 2020-12. Measured against that live
+ * endpoint:
+ *
+ * | tool schema                    | result                                  |
+ * |--------------------------------|-----------------------------------------|
+ * | `items: [a, b]`   (draft-07)   | 400 — "must match JSON Schema draft 2020-12" |
+ * | `prefixItems: [a, b]` (2020-12)| accepted                                |
+ * | `items: { a }`                 | accepted                                |
+ *
+ * The failure is NOT about strict tool use. It fires with strict validation
+ * unset, and with it on the dialect error arrives *before* the strict-subset
+ * error — so a guard scoped to strict misses it entirely. One was, and did.
+ *
+ * Which wires want which dialect is the drivers' knowledge, not this file's:
+ * the vocabulary lives beside the wire that speaks it, and only the mechanism
+ * lives here.
+ *
+ * Only the conversions namzu can actually emit are implemented. The renderer
+ * runs with `$refStrategy: 'none'`, so there are no `$ref`/`definitions` to
+ * rewrite; a construct that cannot appear is not worth code that cannot be
+ * tested.
+ */
+
+/** Which spelling of JSON Schema a wire accepts. */
+export type JsonSchemaDialect = 'draft-07' | '2020-12'
+
+/**
+ * Rendered schemas are memoized and deeply frozen, so their identity is
+ * stable for the life of the tool — which makes them a sound `WeakMap` key.
+ *
+ * Converting per request would re-walk every tool's tree on every iteration,
+ * which is the waste `renderToolSchema`'s own cache exists to remove, and it
+ * would hand a fresh object to the wire each time. The tools block renders at
+ * position 0 of the prompt-cache prefix, so a differently-ordered but equal
+ * object still invalidates the cache for the whole run. Caching the conversion
+ * keeps the bytes identical across iterations.
+ */
+const CONVERTED = new Map<JsonSchemaDialect, WeakMap<object, Record<string, unknown>>>()
+
+/**
+ * Say this schema in the dialect the wire parses.
+ *
+ * Returns the input unchanged — same reference — when nothing needs saying
+ * differently, so the common case costs one map lookup and no allocation.
+ */
+export function toSchemaDialect(
+	schema: Record<string, unknown>,
+	dialect: JsonSchemaDialect,
+): Record<string, unknown> {
+	if (dialect === 'draft-07') return schema
+
+	let cache = CONVERTED.get(dialect)
+	if (!cache) {
+		cache = new WeakMap()
+		CONVERTED.set(dialect, cache)
+	}
+	const hit = cache.get(schema)
+	if (hit) return hit
+
+	const converted = to2020(schema) as Record<string, unknown>
+	const frozen = deepFreeze(converted)
+	cache.set(schema, frozen)
+	return frozen
+}
+
+/**
+ * Whether a schema still carries a construct the 2020-12 wire refuses.
+ *
+ * Exported so a test can sweep every shipped tool without reaching into the
+ * conversion, and so a driver can assert rather than hope.
+ */
+export function findDraft07Only(schema: unknown, path = ''): string[] {
+	if (Array.isArray(schema)) {
+		return schema.flatMap((item, i) => findDraft07Only(item, `${path}[${i}]`))
+	}
+	if (typeof schema !== 'object' || schema === null) return []
+
+	const node = schema as Record<string, unknown>
+	const found: string[] = []
+	// A tuple. In draft-07 the positional schemas live in `items`; 2020-12
+	// moved them to `prefixItems` and kept `items` for the rest, so the array
+	// form is not merely old — it means something else now, and the wire
+	// rejects the whole request rather than one field.
+	if (Array.isArray(node.items)) found.push(`${path ? `${path}.` : ''}items`)
+	// `additionalItems` only ever qualified an array-form `items`; 2020-12
+	// spells that `items`.
+	if ('additionalItems' in node) found.push(`${path ? `${path}.` : ''}additionalItems`)
+
+	for (const [key, value] of Object.entries(node)) {
+		if (key === 'items' && Array.isArray(value)) continue
+		found.push(...findDraft07Only(value, path ? `${path}.${key}` : key))
+	}
+	return found
+}
+
+function to2020(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(to2020)
+	if (typeof value !== 'object' || value === null) return value
+
+	const node = value as Record<string, unknown>
+	const out: Record<string, unknown> = {}
+	for (const [key, child] of Object.entries(node)) {
+		if (key === 'items' && Array.isArray(child)) {
+			out.prefixItems = child.map(to2020)
+			continue
+		}
+		if (key === 'additionalItems') {
+			// Only meaningful alongside an array-form `items`, and 2020-12
+			// calls the same thing `items`.
+			//
+			// `false` is carried across, and the first version of this dropped
+			// it on the reasoning that a closed tuple is 2020-12's default. It
+			// is not: with `prefixItems` set and no `items`, elements past the
+			// tuple are UNCONSTRAINED. Dropping the `false` therefore turned a
+			// closed tuple into an open one — a schema the author wrote to
+			// forbid a third element silently began to allow any. The wire
+			// accepts `items: false`, measured, so nothing was gained by it.
+			if (Array.isArray(node.items)) out.items = to2020(child)
+			continue
+		}
+		out[key] = to2020(child)
+	}
+	return out
+}
+
+function deepFreeze<T>(value: T): T {
+	if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value
+	for (const key of Object.keys(value as Record<string, unknown>)) {
+		deepFreeze((value as Record<string, unknown>)[key])
+	}
+	return Object.freeze(value)
+}

package/src/registry/tool/execute.ts

@@ -438,6 +438,41 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					}
 				}
 
+				// A turn that was narrowed may only call what it was narrowed to.
+				//
+				// This used to be enforced nowhere. `allowedTools` decided which
+				// schemas went into the request and was then carried into this
+				// context and read by nothing, so the restriction was a statement
+				// about the menu rather than about the kitchen: a model that named
+				// a withheld tool — from earlier context, from a gateway holding
+				// its own tool list, from a replayed cache prefix — had it run.
+				// The type says "restrict which tools the model may call"; this is
+				// the line that makes that true.
+				//
+				// Absent means unrestricted. An EMPTY list does not: it is a turn
+				// that may call nothing, and treating it as "no restriction" is
+				// the fail-open reading this codebase has already been bitten by
+				// once, in the delegate roster.
+				const allowed = context.allowedTools
+				if (allowed !== undefined && !allowed.includes(toolName)) {
+					const msg = `Tool "${toolName}" is not available on this step. Available: ${allowed.length > 0 ? allowed.join(', ') : '(none)'}`
+					this.log.warn('Blocked a tool outside the step allow-list', {
+						tool: toolName,
+						allowed: allowed.length,
+					})
+					span.setAttributes({
+						[NAMZU.TOOL_SUCCESS]: false,
+						[NAMZU.TOOL_ERROR]: msg,
+					})
+					span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
+					return {
+						success: false,
+						output: '',
+						error: msg,
+						permissionDenied: true,
+					}
+				}
+
 				const mode = context.permissionContext?.mode ?? 'auto'
 				if (mode === 'plan') {
 					const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false

package/src/registry/toolset/catalog.ts

@@ -1,4 +1,3 @@
-import { zodToJsonSchema } from 'zod-to-json-schema'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import type { LLMToolSchema, ToolAvailability, ToolDefinition } from '../../types/tool/index.js'
 import type {
@@ -10,6 +9,7 @@ import type {
 	ToolsetDefinition,
 	ToolsetPolicy,
 } from '../../types/toolset/index.js'
+import { renderToolSchema } from '../tool/schema.js'
 
 export interface ToolCatalogSearchOptions {
 	readonly loading?: readonly ToolLoadingMode[]
@@ -245,12 +245,17 @@ function toolDefinitionToLLMTool(definition: ToolDefinition | undefined): LLMToo
 		function: {
 			name: definition.name,
 			description: definition.description,
+			// Through `renderToolSchema`, not a second inline conversion. The
+			// options were already identical, so this was not a different
+			// rendering — it was the same rendering without the guarantees:
+			// no `$schema` stripping (that key rides in the tools block, which
+			// sits at position 0 inside the prompt-cache prefix), no memoization,
+			// and no freeze. Two paths that agree today are two paths that can
+			// disagree tomorrow, and a tool reaching the wire through the catalog
+			// rather than the registry is not a different tool.
 			parameters:
 				(definition.modelInputSchema ? structuredClone(definition.modelInputSchema) : undefined) ??
-				(zodToJsonSchema(definition.inputSchema, {
-					target: 'jsonSchema7',
-					$refStrategy: 'none',
-				}) as Record<string, unknown>),
+				renderToolSchema(definition.inputSchema),
 		},
 	}
 }

package/src/runtime/query/__tests__/completion-notification.test.ts

@@ -0,0 +1,196 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { CompletionInbox } from '../../../gateway/completion-inbox.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import { defineTool } from '../../../tools/defineTool.js'
+import type { TaskHandle } from '../../../types/agent/gateway.js'
+import type { SessionId, TaskId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * The last link, and the one most likely to be built and never wired.
+ *
+ * `CompletionInbox` can queue an unclaimed completion and format it, and the
+ * coordinator tools can decline to claim one — but none of that reaches the
+ * model unless the iteration loop actually drains the inbox into the
+ * transcript. A mechanism that is declared, threaded through types, and
+ * driven by nothing is precisely the shape of the defect this whole change
+ * exists to fix, so the drain gets its own test at the loop level rather
+ * than being assumed from its parts.
+ */
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+/** Calls a tool once, then answers. Two turns is all the drain needs. */
+class ToolThenAnswerProvider implements LLMProvider {
+	readonly id = 'tool-then-answer'
+	readonly name = 'Tool Then Answer Provider'
+	calls = 0
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		this.calls += 1
+
+		if (this.calls === 1) {
+			yield {
+				id: 'msg_1',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_noop_1',
+							type: 'function',
+							function: { name: 'noop', arguments: '{}' },
+						},
+					],
+				},
+			}
+			yield {
+				id: 'msg_1',
+				delta: {},
+				finishReason: 'tool_calls',
+				usage: ZERO_USAGE,
+			}
+			return
+		}
+
+		yield { id: 'msg_2', delta: { content: 'Done.' } }
+		yield { id: 'msg_2', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+	}
+}
+
+const noop = defineTool({
+	name: 'noop',
+	description: 'does nothing',
+	inputSchema: z.object({}),
+	category: 'analysis',
+	permissions: [],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+	async execute() {
+		return { success: true, output: 'ok' }
+	},
+})
+
+function completed(taskId: string, result: string): TaskHandle {
+	return {
+		taskId: taskId as TaskId,
+		agentId: 'reviewer',
+		state: 'completed',
+		createdAt: 1_000,
+		completedAt: 4_000,
+		result: { status: 'completed', result } as TaskHandle['result'],
+	}
+}
+
+const workdirs: string[] = []
+afterEach(async () => {
+	await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+	workdirs.length = 0
+})
+
+async function runWith(inbox: CompletionInbox | undefined): Promise<string[]> {
+	const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-completion-'))
+	workdirs.push(workingDirectory)
+
+	const tools = new ToolRegistry()
+	tools.register(noop)
+
+	const run = await drainQuery({
+		provider: new ToolThenAnswerProvider(),
+		tools,
+		...(inbox ? { completionInbox: inbox } : {}),
+		agentId: 'agent_test',
+		agentName: 'Test Agent',
+		messages: [createUserMessage('delegate and report')],
+		workingDirectory,
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 10_000,
+			tokenBudget: 100_000,
+			maxIterations: 4,
+			maxResponseTokens: 256,
+		},
+		sessionId: 'ses_completion' as SessionId,
+		threadId: 'thd_completion' as ThreadId,
+		projectId: 'prj_completion' as ProjectId,
+		tenantId: 'tnt_completion' as TenantId,
+	})
+
+	return run.messages
+		.filter((m) => m.role === 'user')
+		.map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+}
+
+describe('an unclaimed completion reaches the transcript', () => {
+	it('injects the notification as a user message the next turn can read', async () => {
+		const inbox = new CompletionInbox()
+		// Settled by a gateway before the turn ended, with nothing waiting on
+		// it — the abandoned-launch case.
+		inbox.attach({
+			onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+				cb(completed('tsk_late', 'the worker finished after the wait was abandoned'))
+				return () => {}
+			},
+		} as never)
+
+		const userMessages = await runWith(inbox)
+		const notification = userMessages.find((m) => m.includes('task-notification'))
+
+		expect(notification).toBeDefined()
+		expect(notification).toContain('tsk_late')
+		expect(notification).toContain('the worker finished after the wait was abandoned')
+	})
+
+	it('drains it exactly once, however many turns follow', async () => {
+		const inbox = new CompletionInbox()
+		inbox.attach({
+			onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+				cb(completed('tsk_late', 'only once'))
+				return () => {}
+			},
+		} as never)
+
+		const userMessages = await runWith(inbox)
+
+		expect(userMessages.filter((m) => m.includes('task-notification'))).toHaveLength(1)
+	})
+
+	it('says nothing when every completion was already delivered', async () => {
+		// The `dc16d58` regression at the loop level: a blocking `create_task`
+		// claims its own completion, so the transcript must stay clean.
+		const inbox = new CompletionInbox()
+		inbox.attach({
+			onTaskCompleted: (cb: (h: TaskHandle) => void) => {
+				cb(completed('tsk_awaited', 'delivered as a tool_result'))
+				return () => {}
+			},
+		} as never)
+		inbox.claim('tsk_awaited' as TaskId)
+
+		const userMessages = await runWith(inbox)
+
+		expect(userMessages.some((m) => m.includes('task-notification'))).toBe(false)
+	})
+
+	it('runs unchanged with no inbox at all', async () => {
+		// The kernel must not require one: a host on the old wiring keeps
+		// working, it just never hears about abandoned completions.
+		const userMessages = await runWith(undefined)
+
+		expect(userMessages.some((m) => m.includes('task-notification'))).toBe(false)
+	})
+})

package/src/runtime/query/__tests__/step-allow-list.test.ts

@@ -0,0 +1,205 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import { defineTool } from '../../../tools/defineTool.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * Narrowing a step has to narrow what RUNS, not only what is offered.
+ *
+ * `prepareStep.activeTools` says "restrict which tools the model may call
+ * this step, by name", and for a while it did nothing of the sort: it chose
+ * which schemas went into the request, was copied into the tool context, and
+ * was read by nobody on the execution path. A model that named a withheld
+ * tool had it run — and a model does name one, from a repeated call earlier
+ * in the context, from a gateway carrying its own tool list, or from a
+ * replayed cache prefix.
+ *
+ * These tests call the withheld tool deliberately, which is the only way to
+ * tell an enforced restriction from a presentational one. Every existing test
+ * asked the model nicely and so could not have caught this.
+ */
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+let danger = 0
+
+const readOnly = defineTool({
+	name: 'read_only',
+	description: 'observes',
+	inputSchema: z.object({}),
+	category: 'analysis',
+	permissions: [],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+	async execute() {
+		return { success: true, output: 'observed' }
+	},
+})
+
+const dangerous = defineTool({
+	name: 'danger',
+	description: 'mutates',
+	inputSchema: z.object({}),
+	category: 'custom',
+	permissions: [],
+	readOnly: false,
+	destructive: true,
+	concurrencySafe: false,
+	async execute() {
+		danger += 1
+		return { success: true, output: 'the withheld tool ran' }
+	},
+})
+
+/** Calls whichever tool it is told to, then answers. */
+class NamesTool implements LLMProvider {
+	readonly id = 'names-tool'
+	readonly name = 'Names Tool Provider'
+	calls = 0
+	offered: string[][] = []
+
+	constructor(private readonly toolName: string) {}
+
+	async *chatStream(params: {
+		tools?: { function: { name: string } }[]
+	}): AsyncIterable<StreamChunk> {
+		this.calls += 1
+		this.offered.push((params.tools ?? []).map((t) => t.function.name))
+
+		if (this.calls === 1) {
+			yield {
+				id: 'msg_1',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_1',
+							type: 'function',
+							function: { name: this.toolName, arguments: '{}' },
+						},
+					],
+				},
+			}
+			yield { id: 'msg_1', delta: {}, finishReason: 'tool_calls', usage: ZERO_USAGE }
+			return
+		}
+
+		yield { id: 'msg_2', delta: { content: 'done' } }
+		yield { id: 'msg_2', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+	}
+}
+
+const workdirs: string[] = []
+afterEach(async () => {
+	await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+	workdirs.length = 0
+	danger = 0
+})
+
+async function run(opts: {
+	names: string
+	allowedTools?: string[]
+	activeTools?: string[]
+}): Promise<{ offered: string[][]; output: string }> {
+	const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-allow-'))
+	workdirs.push(workingDirectory)
+
+	const tools = new ToolRegistry()
+	tools.register(readOnly)
+	tools.register(dangerous)
+
+	const provider = new NamesTool(opts.names)
+	let output = ''
+
+	await drainQuery(
+		{
+			provider,
+			tools,
+			...(opts.allowedTools ? { allowedTools: opts.allowedTools } : {}),
+			...(opts.activeTools
+				? { prepareStep: () => ({ activeTools: opts.activeTools as string[] }) }
+				: {}),
+			agentId: 'agent_test',
+			agentName: 'Test Agent',
+			messages: [createUserMessage('go')],
+			workingDirectory,
+			runConfig: {
+				model: 'mock-model',
+				timeoutMs: 10_000,
+				tokenBudget: 100_000,
+				maxIterations: 3,
+				maxResponseTokens: 256,
+			},
+			sessionId: 'ses_allow' as SessionId,
+			threadId: 'thd_allow' as ThreadId,
+			projectId: 'prj_allow' as ProjectId,
+			tenantId: 'tnt_allow' as TenantId,
+		},
+		(event) => {
+			if (event.type === 'tool_completed') output += event.result ?? ''
+		},
+	)
+
+	return { offered: provider.offered, output }
+}
+
+describe('a narrowed step narrows what can run, not just what is shown', () => {
+	it('refuses a tool the step withheld, even when the model names it', async () => {
+		const { offered, output } = await run({ names: 'danger', activeTools: ['read_only'] })
+
+		// The request really was narrowed — otherwise this test proves nothing
+		// about enforcement, only about the model's manners.
+		expect(offered[0]).toEqual(['read_only'])
+		// And the call was refused rather than executed.
+		expect(danger, 'the withheld tool executed').toBe(0)
+		expect(output).toContain('not available on this step')
+	})
+
+	it('refuses a tool outside the run-level list too', async () => {
+		const { output } = await run({ names: 'danger', allowedTools: ['read_only'] })
+
+		expect(danger).toBe(0)
+		expect(output).toContain('not available on this step')
+	})
+
+	it('still runs a tool that is on the list', async () => {
+		const { output } = await run({ names: 'read_only', activeTools: ['read_only'] })
+
+		expect(output).toContain('observed')
+	})
+
+	it('leaves an unnarrowed run alone', async () => {
+		// Absent means unrestricted. A run that never narrows anything must not
+		// suddenly start refusing its own tools.
+		const { output } = await run({ names: 'danger' })
+
+		expect(danger).toBe(1)
+		expect(output).toContain('the withheld tool ran')
+	})
+
+	it('treats an empty list as "nothing", not as "no restriction"', async () => {
+		// The fail-open reading this codebase has already been bitten by once,
+		// in the delegate roster: an empty allow-list IS the answer, and
+		// degrading it to "unrestricted" is how a closed list becomes open.
+		const { output } = await run({ names: 'danger', activeTools: [] })
+
+		expect(danger).toBe(0)
+		expect(output).toContain('(none)')
+	})
+})

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

@@ -84,6 +84,7 @@ class ClassifiedFailureProvider implements LLMProvider {
 				providerId: 'classified-failure',
 				status: 429,
 				retryAfterMs: 2000,
+				detail: 'rate limit reached for this organization',
 			}),
 		)
 	}
@@ -210,11 +211,16 @@ describe('query stream recovery', () => {
 		)
 
 		expect(run.status).toBe('failed')
+		// `detail` rides along with the classification. Without it a host
+		// rendering this metadata knows a request was rejected but not why, and
+		// has to go re-parse the message string — which is the re-parsing this
+		// structured field exists to avoid.
 		expect(run.lastProviderError).toEqual({
 			kind: 'throttle',
 			providerId: 'classified-failure',
 			status: 429,
 			retryAfterMs: 2000,
+			detail: 'rate limit reached for this organization',
 		})
 		expect(events.find((event) => event.type === 'run_failed')).toMatchObject({
 			type: 'run_failed',

package/src/runtime/query/executor.ts

@@ -205,6 +205,8 @@ export class ToolExecutor {
 	private workingStateManager?: WorkingStateManager
 	private probes: ProbeRegistry
 	private parentSpan?: Span
+	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
+	private stepAllowedTools?: readonly string[]
 	private readonly readPaths: Set<string> = new Set()
 	private readonly readFingerprints: Map<string, string> = new Map()
 	private readonly fileReadTracker: FileReadTracker = {
@@ -251,6 +253,21 @@ export class ToolExecutor {
 		this.parentSpan = span
 	}
 
+	/**
+	 * Narrow what this turn may call, or clear the narrowing.
+	 *
+	 * Re-set each turn by the orchestrator for the same reason the parent span
+	 * is: `prepareStep` can hand a different list to every step, and the run's
+	 * own `allowedTools` is only the default when a step names none.
+	 *
+	 * Without this the executor could only ever see the RUN-level list, so a
+	 * per-step narrowing reached the request that was sent and nothing else —
+	 * the model was shown fewer tools and could still call all of them.
+	 */
+	setStepAllowedTools(names: readonly string[] | undefined): void {
+		this.stepAllowedTools = names
+	}
+
 	/**
 	 * Answer every `tool_use` block in `response` with exactly one
 	 * `tool_result`.
@@ -424,7 +441,10 @@ export class ToolExecutor {
 			},
 			invocationState: this.config.invocationState,
 			toolRegistry: this.config.tools,
-			allowedTools: this.config.allowedTools,
+			// The step's list wins where it has one; the run's is the default.
+			// Same precedence the request already uses when it decides which
+			// schemas to send, so the menu and the kitchen agree.
+			allowedTools: this.stepAllowedTools ?? this.config.allowedTools,
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
 			...(this.parentSpan ? { parentSpan: this.parentSpan } : {}),