@namzu/sdk 3.3.0 → 4.0.0

package/src/tools/builtins/edit.ts

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -99,12 +100,40 @@ const modelInputSchema: Record<string, unknown> = {
 			description:
 				'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
 		},
+		insertLine: {
+			// The union the execution schema already accepts, stated so a
+			// constrained decoder can emit it. Declaring it as `oneOf` of an
+			// integer and the literal `"end"` also makes the synonym problem
+			// structurally impossible: `"EOF"`, `"append"` and `"last"` are
+			// not emittable, because `"end"` is the only string the schema
+			// admits.
+			oneOf: [{ type: 'integer', minimum: 0 }, { const: 'end' }],
+			description:
+				'Insert instead of replacing. The new_string goes after this 1-indexed line; 0 inserts before the first line; "end" appends. Omit for a find-and-replace.',
+		},
 		replace_all: {
 			type: 'boolean',
 			description: 'Replace every occurrence instead of requiring one unique match.',
 		},
 	},
-	required: ['path', 'old_string', 'new_string'],
+	// `old_string` is deliberately NOT required, and this is the fix.
+	//
+	// The tool's own description tells the model to append with `insertLine`,
+	// and this schema forbade the field while `enforceModelInput` was on — so
+	// the idiom the prompt ordered was the one idiom a constrained model could
+	// not express. Requiring `old_string` reintroduces that, since an insert
+	// has no text to match.
+	//
+	// Which of `old_string` / `insertLine` is present is decided by the two
+	// refinements on the execution schema, which already exist and name what
+	// is missing. That is a deliberate choice over a top-level `oneOf`: strict
+	// structured-output modes are least surprising with a flat object, and a
+	// discriminated union at the root is the construct most likely to be
+	// rejected or quietly ignored by a provider. The cost is that an
+	// incomplete call is now expressible and caught at execution rather than
+	// at generation — paid knowingly, because the alternative is that a
+	// working capability stays unreachable.
+	required: ['path', 'new_string'],
 	additionalProperties: false,
 }
 
@@ -130,7 +159,7 @@ export const EditTool = defineTool({
 	modelInputSchema,
 	enforceModelInput: true,
 	validationErrorHint:
-		'Required shape: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}. Optional: "replace_all": true.',
+		'Two shapes. Replace: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"} (optional "replace_all": true). Insert: {"path":"file.md","insertLine":"end","new_string":"text to add"} where insertLine is a non-negative line number or "end". Exactly one of old_string or insertLine.',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -165,14 +194,20 @@ export const EditTool = defineTool({
 			}
 		}
 
-		const filePath = resolve(context.workingDirectory, parsed.data.path)
+		// Host-side containment, on the host branch only. The sandbox has its
+		// own root and its own resolver; canonicalizing a sandbox-relative
+		// path against the HOST filesystem asks a question about the wrong
+		// machine, and answers it with whatever happens to exist there.
+		const filePath = context.sandbox
+			? undefined
+			: await resolveWithinReal(context.workingDirectory, parsed.data.path)
 		// Read-modify-write is not atomic on its own: two edits to the same
 		// path interleave their reads, and the second write lands on content
 		// the first had already replaced — so one edit vanishes and the loser
 		// reports "old_string not found", blaming the model for a race. The
 		// key spans both branches because sandbox and local are distinct
 		// files even when the path string matches.
-		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+		const lockKey = context.sandbox ? `sandbox:${parsed.data.path}` : `local:${filePath as string}`
 
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
@@ -190,7 +225,8 @@ export const EditTool = defineTool({
 				}
 			}
 
-			const content = await readFile(filePath, 'utf-8')
+			const hostPath = filePath as string
+			const content = await readFile(hostPath, 'utf-8')
 
 			const result = applyEdit(content, normalized.operation)
 			if (!result.success) {
@@ -213,9 +249,9 @@ export const EditTool = defineTool({
 				// changed elsewhere in the file, and refusing there would
 				// reject safe edits every time anyone touched an unrelated
 				// line.
-				const seen = context.fileReadTracker?.fingerprint?.(filePath)
+				const seen = context.fileReadTracker?.fingerprint?.(hostPath)
 				if (seen !== undefined && seen !== fingerprintContent(content)) {
-					return { success: false as const, output: '', error: staleFileError(filePath) }
+					return { success: false as const, output: '', error: staleFileError(hostPath) }
 				}
 				return { success: false as const, output: '', error: result.error }
 			}
@@ -223,15 +259,15 @@ export const EditTool = defineTool({
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails
 			// partway leaves the user's source truncated.
-			await atomicWriteFile(filePath, result.content)
+			await atomicWriteFile(hostPath, result.content)
 			// This runtime is now the last writer, so the next edit in the same
 			// turn compares against what we just wrote rather than the read
 			// before it.
-			context.fileReadTracker?.recordRead(filePath, result.content)
+			context.fileReadTracker?.recordRead(hostPath, result.content)
 			return {
 				success: true as const,
-				output: `Edited ${filePath}: ${result.replacements} replacement(s)`,
-				data: { path: filePath, replacements: result.replacements },
+				output: `Edited ${hostPath}: ${result.replacements} replacement(s)`,
+				data: { path: hostPath, replacements: result.replacements },
 			}
 		})
 	},
@@ -274,16 +310,35 @@ function normalizeEditInput(
 	}
 }
 
+/**
+ * Spellings of "the end of the file" a model reaches for.
+ *
+ * Liberal here and strict in the schema, which is the right way round: the
+ * schema makes `"end"` the only emittable string for a provider that
+ * constrains, and this catches the rest for one that does not. None of these
+ * is ambiguous — accepting them is not guessing at intent, it is declining to
+ * spend a round trip on a synonym.
+ */
+const END_ALIASES = new Set(['end', 'eof', 'append', 'last', 'end_of_file', 'end-of-file'])
+
 function normalizeInsertLine(
 	value: string | number,
 ): { success: true; value: number | 'end' } | { success: false; error: string } {
 	if (typeof value === 'string') {
-		if (value.trim().toLowerCase() === 'end') return { success: true, value: 'end' }
+		const normalized = value.trim().toLowerCase()
+		// `"end"` is the only spelling the model-facing schema admits, so a
+		// constrained decoder cannot produce anything else. These aliases are
+		// for the providers that do not constrain: a model reading "appends to
+		// the file" reaches for the word it knows, and every one of these says
+		// the same unambiguous thing. Refusing them bought strictness and cost
+		// a full model round trip per occurrence — measured by a consuming host
+		// as the single largest source of tool-call waste in its runs.
+		if (END_ALIASES.has(normalized)) return { success: true, value: 'end' }
 		const parsed = Number(value)
 		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }
 		return {
 			success: false,
-			error: 'insertLine must be a non-negative line number or "end".',
+			error: `insertLine must be a non-negative line number or "end" (also accepted: ${[...END_ALIASES].filter((a) => a !== 'end').join(', ')}). Received ${JSON.stringify(value)}.`,
 		}
 	}
 	return { success: true, value }

package/src/tools/builtins/ls.ts

@@ -1,8 +1,11 @@
 import { readdir, stat } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import { z } from 'zod'
+import type { Sandbox } from '../../types/sandbox/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithin } from '../paths.js'
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
 
 const inputSchema = z.object({
 	path: z.string().default('.').describe('Directory path to list. Defaults to working directory.'),
@@ -105,6 +108,101 @@ async function listRecursive(
 	}
 }
 
+/**
+ * Enumerate inside the sandbox.
+ *
+ * This tool read the HOST filesystem through `node:fs` and referenced
+ * `context.sandbox` nowhere, so with a container or microVM backend wired in
+ * it enumerated the host — in the one builtin whose entire job is telling the
+ * model what exists. `glob` carried the identical defect, was fixed, and its
+ * fix notes that "every sibling builtin already remembers this branch". This
+ * was the sibling that did not, which is why the claim needed checking rather
+ * than reading.
+ *
+ * Worse than a leak on its own: the paths it returned were host-relative,
+ * while `read`, `grep` and `glob` all resolve INSIDE the sandbox. So every
+ * ls-to-read handoff either failed or opened a different file than the one
+ * listed. This returns the sandbox-relative coordinates the others speak.
+ *
+ * `listFiles` reports files, not directories — every backend implements it as
+ * a recursive file walk — so directories are derived from the paths. A
+ * directory holding nothing is therefore invisible here, which is a real
+ * difference from the host branch and the honest cost of having one
+ * enumeration primitive rather than one per backend.
+ */
+async function listInSandbox(
+	input: { path: string; all: boolean; recursive: boolean; max_depth: number },
+	sandbox: Sandbox,
+): Promise<ToolResult> {
+	const root = resolveWithinPosix(sandbox.rootDir, input.path)
+	const entries = await sandbox.listFiles(root)
+
+	// Relative to the LISTED directory, in the sandbox's own coordinates.
+	const relativePaths: { segments: string[]; size: number }[] = []
+	for (const entry of entries) {
+		const rel = relativePosix(root, joinPosix(root, entry.path))
+		if (!rel || rel.startsWith('..')) continue
+		const segments = rel.split('/').filter(Boolean)
+		if (segments.length === 0) continue
+		if (!input.all && segments.some((s) => s.startsWith('.'))) continue
+		relativePaths.push({ segments, size: entry.size })
+	}
+
+	if (!input.recursive) {
+		// One level: a single segment is a file, more than one means the
+		// first segment is a directory.
+		const files = new Map<string, number>()
+		const dirs = new Set<string>()
+		for (const { segments, size } of relativePaths) {
+			const head = segments[0] as string
+			if (segments.length === 1) files.set(head, size)
+			else dirs.add(head)
+		}
+
+		const lines = [
+			...[...dirs].sort().map((name) => `${name}/`),
+			...[...files.entries()]
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([name, size]) => `${name}\t${formatSize(size)}`),
+		]
+
+		return {
+			success: true,
+			output: lines.length > 0 ? lines.join('\n') : '(empty directory)',
+			data: { count: lines.length, sandboxed: true },
+		}
+	}
+
+	const seenDirs = new Set<string>()
+	const lines: string[] = []
+	let count = 0
+	for (const { segments, size } of relativePaths.sort((a, b) =>
+		a.segments.join('/').localeCompare(b.segments.join('/')),
+	)) {
+		if (segments.length > input.max_depth) continue
+		// Emit each parent directory once, before anything inside it.
+		for (let depth = 1; depth < segments.length; depth++) {
+			const dir = segments.slice(0, depth).join('/')
+			if (seenDirs.has(dir)) continue
+			seenDirs.add(dir)
+			if (count >= MAX_ENTRIES) break
+			lines.push(`./${dir}/`)
+			count++
+		}
+		if (count >= MAX_ENTRIES) break
+		lines.push(`./${segments.join('/')} (${formatSize(size)})`)
+		count++
+	}
+
+	const truncated = count >= MAX_ENTRIES ? `\n(truncated at ${MAX_ENTRIES} entries)` : ''
+
+	return {
+		success: true,
+		output: lines.length > 0 ? lines.join('\n') + truncated : '(empty directory)',
+		data: { count, truncated: count >= MAX_ENTRIES, sandboxed: true },
+	}
+}
+
 export const LsTool = defineTool({
 	name: 'ls',
 	description:
@@ -117,6 +215,10 @@ export const LsTool = defineTool({
 	concurrencySafe: true,
 
 	async execute(input, context) {
+		if (context.sandbox) {
+			return await listInSandbox(input, context.sandbox)
+		}
+
 		// Contained, not merely resolved — see `resolveWithin`.
 		const targetPath = resolveWithin(context.workingDirectory, input.path)
 

package/src/tools/builtins/read-file.ts

@@ -1,7 +1,8 @@
 import { readFile } from 'node:fs/promises'
-import { extname, resolve } from 'node:path'
+import { extname } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
@@ -74,7 +75,7 @@ export const ReadFileTool = defineTool({
 			}
 		}
 
-		const filePath = resolve(context.workingDirectory, input.path)
+		const filePath = await resolveWithinReal(context.workingDirectory, input.path)
 		const buffer = await readFile(filePath)
 		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
 		if (binaryGuidance) {

package/src/tools/builtins/write-file.ts

@@ -1,8 +1,9 @@
 import { access, mkdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
+import { dirname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 
@@ -11,6 +12,12 @@ const inputSchema = z
 		path: z
 			.string()
 			.min(1)
+			// `.min(1)` alone admits `"   "`, which resolves to the working
+			// directory itself and turns a write into a directory-write error
+			// nobody can read. `edit` has refused this since it was written;
+			// the two tools disagreeing on the same input is the kind of gap a
+			// model finds and a reviewer does not.
+			.refine((value) => value.trim().length > 0, 'Path must not be empty.')
 			.describe(
 				'Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.',
 			),
@@ -87,11 +94,17 @@ export const WriteFileTool = defineTool({
 		}
 		const valid = parsed.data
 		const content = valid.content ?? valid.newStr ?? ''
-		const filePath = resolve(context.workingDirectory, valid.path)
+		// Host-side containment, on the host branch only. The sandbox has its
+		// own root and its own resolver; canonicalizing a sandbox-relative
+		// path against the HOST filesystem asks a question about the wrong
+		// machine and answers it with whatever happens to exist there.
+		const filePath = context.sandbox
+			? undefined
+			: await resolveWithinReal(context.workingDirectory, valid.path)
 		// The exists-check and the write are a check-then-act pair. Unlocked,
 		// two writers both see "absent", both skip the read-before-overwrite
 		// guard, and the second silently discards the first.
-		const lockKey = `${context.sandbox ? 'sandbox' : 'local'}:${filePath}`
+		const lockKey = context.sandbox ? `sandbox:${valid.path}` : `local:${filePath as string}`
 
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
@@ -109,23 +122,24 @@ export const WriteFileTool = defineTool({
 				}
 			}
 
-			const localExists = await pathExists(filePath)
+			const hostPath = filePath as string
+			const localExists = await pathExists(hostPath)
 			if (localExists) {
-				const guard = enforceReadBeforeOverwrite(context, filePath)
+				const guard = enforceReadBeforeOverwrite(context, hostPath)
 				if (guard) return guard
 			}
 
-			await mkdir(dirname(filePath), { recursive: true })
+			await mkdir(dirname(hostPath), { recursive: true })
 			// Temp file, fsync, rename. A plain write that fails partway
 			// leaves the destination truncated — and this tool overwrites a
 			// whole file, so the truncation is the user's previous work.
-			await atomicWriteFile(filePath, content)
-			context.fileReadTracker?.recordRead(filePath)
+			await atomicWriteFile(hostPath, content)
+			context.fileReadTracker?.recordRead(hostPath)
 
 			return {
 				success: true as const,
-				output: `File written successfully: ${filePath} (${content.length} chars)`,
-				data: { path: filePath, size: content.length },
+				output: `File written successfully: ${hostPath} (${content.length} chars)`,
+				data: { path: hostPath, size: content.length },
 			}
 		})
 	},
@@ -144,9 +158,9 @@ function enforceReadBeforeOverwrite(
 	}
 }
 
-async function pathExists(filePath: string): Promise<boolean> {
+async function pathExists(hostPath: string): Promise<boolean> {
 	try {
-		await access(filePath)
+		await access(hostPath)
 		return true
 	} catch {
 		return false

package/src/tools/coordinator/__tests__/agent.test.ts

@@ -90,7 +90,12 @@ describe('buildAgentTool', () => {
 		)
 
 		expect(result.success).toBe(true)
-		expect(result.output).toBe('final report text')
+		// The subagent's text is present and unaltered, inside a frame that
+		// says whose text it is. A host reading the result programmatically
+		// gets it verbatim off `data.result` instead.
+		expect(result.output).toContain('final report text')
+		expect(result.output.startsWith('<namzu-untrusted kind="agent-result"')).toBe(true)
+		expect(result.data).toMatchObject({ result: 'final report text' })
 	})
 
 	it('reports failure when run status is failed even though task state is completed', async () => {

package/src/tools/coordinator/__tests__/ask-user-question.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
+import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { TaskGateway } from '../../../types/agent/gateway.js'
 import type {
 	HITLDecisionRequest,
@@ -175,6 +176,63 @@ describe('coordinator ask_user_question input schema', () => {
 	})
 })
 
+/**
+ * The model-facing schema is a module-level object shared by every tool this
+ * builder produces, so it is copied on the way out — TWICE, at two independent
+ * boundaries, and each test below pins exactly one of them. The builder clones
+ * when it attaches the schema to the definition; the registry clones again
+ * when it renders a definition for the wire. Removing either clone fails one
+ * of these and not the other, which is how they were confirmed non-vacuous.
+ *
+ * Both clones survived a version in which neither test did: the defences were
+ * still in the source and nothing pinned them, which is precisely the state
+ * where a later edit drops one and no gate objects.
+ *
+ * The failure they prevent is not hypothetical. A caller that mutates a schema
+ * it received — normalizing it for one provider, adding a legacy alias — would
+ * otherwise be editing the object every OTHER tool instance in the process is
+ * also handing out, including definitions already registered in another run.
+ */
+describe('coordinator ask_user_question canonical schema isolation', () => {
+	const noopHandler: ResumeHandler = async () => ({ action: 'continue' })
+
+	it('returns a fresh schema on every render from the registry boundary', () => {
+		const registry = new ToolRegistry()
+		registry.register(askTool(noopHandler))
+
+		const first = registry.toLLMTools()[0]?.function.parameters
+		expect(first).toEqual(askTool(noopHandler).modelInputSchema)
+		const firstProperties = first?.properties as Record<string, unknown>
+		firstProperties.legacy_options = { type: 'string' }
+
+		const next = registry.toLLMTools()[0]?.function.parameters
+		expect(JSON.stringify(next)).not.toContain('legacy_options')
+		expect(next).toEqual(askTool(noopHandler).modelInputSchema)
+	})
+
+	it('isolates the schema between two results of the public builder', () => {
+		const first = askTool(noopHandler)
+		const second = askTool(noopHandler)
+		expect(first.modelInputSchema).not.toBe(second.modelInputSchema)
+
+		const firstProperties = first.modelInputSchema?.properties as Record<string, unknown>
+		firstProperties.legacy_options = { type: 'string' }
+
+		expect(JSON.stringify(second.modelInputSchema)).not.toContain('legacy_options')
+	})
+
+	it('rejects an unknown property inside an option, not only at the root', () => {
+		const tool = askTool(noopHandler)
+
+		expect(
+			tool.inputSchema.safeParse({
+				...baseInput,
+				options: [{ label: 'A', weight: 3 }, { label: 'B' }],
+			}).success,
+		).toBe(false)
+	})
+})
+
 describe('coordinator ask_user_question request synthesis', () => {
 	it('synthesizes the park request from its own context — questionId = toolUseId', async () => {
 		const { requests } = await executeAsk({

package/src/tools/coordinator/__tests__/empty-roster.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import { buildAgentTool } from '../agent.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * `create_task` used to widen its `agent_id` parameter from the roster enum to
+ * a bare string whenever the roster was empty — so the one configuration that
+ * says "this run may delegate to nobody" was the one that let the model name
+ * anybody. Degrading a closed list to an open one because the list is empty is
+ * failing open (CWE-636), and Saltzer & Schroeder named the rule it breaks in
+ * 1975: fail-safe defaults, §I.A.3(b).
+ *
+ * The control is that the tool is not mounted at all — refusing per call would
+ * reach the same verdict while paying prompt tokens and an iteration for it.
+ * The schema stays closed underneath as defence-in-depth for a definition
+ * built directly.
+ *
+ * What was reachable before is worth stating, because it is why this is a
+ * break worth taking: the id went to the gateway, which resolves against an
+ * `AgentManager` that is typically SHARED — so a name the host deliberately
+ * left out of `agentIds` could still launch if it happened to be registered
+ * there.
+ */
+
+const gateway = {
+	dispatch: async () => {
+		throw new Error('gateway must not be reached — the schema refuses first')
+	},
+	listTasks: () => [],
+	cancel: () => undefined,
+} as unknown as TaskGateway
+
+function toolsFor(allowedAgentIds: string[], resumeHandler?: unknown) {
+	return buildCoordinatorTools({
+		gateway,
+		workingDirectory: '/tmp/test',
+		allowedAgentIds,
+		...(resumeHandler ? { resumeHandler: resumeHandler as never, runId: 'run_1' as never } : {}),
+	})
+}
+
+function createTaskFor(allowedAgentIds: string[]) {
+	const tool = toolsFor(allowedAgentIds).find((t) => t.name === 'create_task')
+	if (!tool) throw new Error('create_task missing from coordinator builder')
+	return tool
+}
+
+describe('create_task delegate roster', () => {
+	it('does not mount create_task at all when the roster is empty', () => {
+		const names = toolsFor([]).map((t) => t.name)
+
+		expect(names).not.toContain('create_task')
+	})
+
+	it('still mounts the coordinator tools that do not read the roster', () => {
+		// "No delegates, but still planning and a human channel" is a
+		// supported configuration, so this omits one tool rather than
+		// refusing to build.
+		const names = toolsFor([], async () => ({ action: 'approve_tools' })).map((t) => t.name)
+
+		expect(names).toContain('agent_task_list')
+		expect(names).toContain('ask_user_question')
+	})
+
+	it('mounts create_task once the roster has an entry', () => {
+		expect(toolsFor(['worker']).map((t) => t.name)).toContain('create_task')
+	})
+
+	it('still admits an id that is on a non-empty roster', () => {
+		const parsed = createTaskFor(['worker']).inputSchema.safeParse({
+			agent_id: 'worker',
+			prompt: 'do the thing',
+			description: 'a task',
+		})
+
+		expect(parsed.success).toBe(true)
+	})
+
+	it('still refuses an id that is off a non-empty roster', () => {
+		const parsed = createTaskFor(['worker']).inputSchema.safeParse({
+			agent_id: 'some-other-agent',
+			prompt: 'do the thing',
+			description: 'a task',
+		})
+
+		expect(parsed.success).toBe(false)
+	})
+})
+
+describe('the Agent tool carries the same closed roster', () => {
+	it('refuses to build at all with no delegates', () => {
+		// Unlike the coordinator builder, this one returns exactly one tool
+		// and that tool IS the delegation surface, so "do not mount" and "do
+		// not build" are the same statement.
+		expect(() =>
+			buildAgentTool({ gateway, workingDirectory: '/tmp/test', allowedAgentIds: [] }),
+		).toThrow(/at least one entry in allowedAgentIds/)
+	})
+
+	it('refuses an off-roster subagent at execution, not only in the schema', async () => {
+		// `execute` is reachable without the registry, so a schema-only check
+		// leaves the roster unenforced on that path.
+		const tool = buildAgentTool({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['worker'],
+		})
+
+		const result = await tool.execute(
+			{ description: 'x', prompt: 'y', subagent_type: 'not-on-the-roster' },
+			{ workingDirectory: '/tmp/test' } as never,
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/Unknown subagent_type/)
+	})
+})