@namzu/sdk 0.6.0 → 1.1.0

package/src/tools/coordinator/agent.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod'
+
+import type { AgentRuntimeContext } from '../../types/agent/base.js'
+import type { TaskGateway } from '../../types/agent/gateway.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+import type { TaskLaunchedCallback } from './index.js'
+
+/**
+ * Build the canonical Claude Code `Agent` tool — synchronous subagent
+ * delegation that mirrors what Claude is trained against in
+ * `code.claude.com/docs/en/sub-agents`.
+ *
+ * Semantics: parent calls `Agent({ description, prompt, subagent_type })`,
+ * the runtime spawns the chosen subagent with its own context window,
+ * the parent's tool call BLOCKS until the subagent finishes, and the
+ * subagent's final text comes back as the tool result. Intermediate
+ * subagent tool calls are isolated — only the summary surfaces to
+ * the parent.
+ *
+ * This is **NOT** the same shape as the legacy `create_task` /
+ * `continue_task` / `cancel_task` trio that this package ships
+ * alongside it: those are non-blocking and use a `<task-notification>`
+ * callback model. The async pattern is useful for hosts that want a
+ * work-queue surface, but it is not what Claude Code trained against.
+ * For free agentic alignment, prefer the canonical `Agent` tool; keep
+ * the legacy coordinator tools only when you genuinely need
+ * fire-and-forget multi-task fan-out.
+ */
+export interface AgentToolOptions {
+	gateway: TaskGateway
+	workingDirectory: string
+	runtimeContext?: AgentRuntimeContext
+	allowedAgentIds: string[]
+
+	onTaskLaunched?: TaskLaunchedCallback
+}
+
+export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
+	const { gateway, allowedAgentIds: agentIds, onTaskLaunched } = opts
+	const cwd = opts.workingDirectory
+
+	const subagentTypeEnum =
+		agentIds.length > 0 ? z.enum(agentIds as [string, ...string[]]) : z.string()
+
+	return defineTool({
+		name: 'Agent',
+		description: `Delegate a task to a specialized subagent. BLOCKING: returns when the subagent has finished, with the subagent's final text as the tool result. The subagent runs in its own context window and cannot see your conversation — include all necessary context in the prompt. Available subagents: ${agentIds.join(', ')}. To run multiple subagents in parallel, call this tool multiple times in a single response.`,
+		inputSchema: z.object({
+			description: z.string().describe('Short label for tracking (shown to the user)'),
+			prompt: z
+				.string()
+				.describe('Self-contained task description with all context the subagent needs'),
+			subagent_type:
+				agentIds.length === 1
+					? subagentTypeEnum
+							.optional()
+							.describe(`Which subagent to run (defaults to the only one: ${agentIds[0]})`)
+					: subagentTypeEnum.describe('Which subagent to run'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ description, prompt, subagent_type }, context) {
+			// With a single registered subagent the type is optional — default to
+			// it so the model can't trip the "subagent_type required" validation.
+			const agentId = subagent_type ?? (agentIds.length === 1 ? agentIds[0] : undefined)
+			if (!agentId) {
+				return {
+					success: false,
+					output: '',
+					error: `subagent_type is required — choose one of: ${agentIds.join(', ')}`,
+				}
+			}
+			const handle = await gateway.createTask({
+				agentId,
+				prompt,
+				workingDirectory: cwd,
+				runtimeContext: opts.runtimeContext,
+			})
+
+			onTaskLaunched?.(handle.taskId, {
+				agentId,
+				description,
+				// Same canonical-envelope plumbing as coordinator/index.ts
+				// (ses_009-task-notification-envelope). For Agent-tool path
+				// the subagent run is awaited synchronously below, so this
+				// id is only used if a probe / hook unexpectedly forks the
+				// completion to the background notification channel.
+				originalToolUseId: context.toolUseId,
+			})
+
+			const completed = await gateway.waitForTask(handle.taskId)
+
+			// Two layers can disagree on whether the subagent succeeded:
+			//
+			// 1. `TaskHandle.state` — the gateway's terminal task state.
+			//    Some gateways (e.g. vandal's) explicitly map
+			//    `result.status !== 'completed'` to `state = 'failed'`,
+			//    others (e.g. SDK's `LocalTaskGateway`) just forward
+			//    whatever the AgentManager set, which does not always
+			//    reflect run-level failure.
+			// 2. `BaseAgentResult.status` — the run's own status. The
+			//    canonical source of truth for whether the agent actually
+			//    finished its work; `lastError` carries the failure
+			//    message when set.
+			//
+			// Treat the subagent as successful only when BOTH agree.
+			// Reporting a failed subagent as successful would silently
+			// hand the parent garbage output and make debugging
+			// impossible, which is what Codex flagged on the first cut.
+			const runStatus = completed.result?.status
+			const succeeded =
+				completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed')
+
+			const resultText =
+				typeof completed.result?.result === 'string'
+					? completed.result.result
+					: completed.result?.result !== undefined
+						? JSON.stringify(completed.result.result)
+						: ''
+
+			if (!succeeded) {
+				const failureLabel =
+					completed.state !== 'completed' ? completed.state : (runStatus ?? 'failed')
+				const detail =
+					completed.result?.lastError ?? resultText ?? '(subagent provided no failure detail)'
+				return {
+					success: false,
+					output: '',
+					error: `Subagent ${agentId} ${failureLabel}: ${detail}`,
+					data: {
+						task_id: handle.taskId,
+						subagent_type: agentId,
+						state: completed.state,
+						status: runStatus,
+						lastError: completed.result?.lastError,
+					},
+				}
+			}
+
+			return {
+				success: true,
+				output: resultText || '(subagent returned no text)',
+				data: {
+					task_id: handle.taskId,
+					subagent_type: agentId,
+					state: completed.state,
+					status: runStatus,
+				},
+			}
+		},
+	})
+}

package/src/tools/coordinator/index.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { TaskGateway } from '../../types/agent/gateway.js'
+import type { ResumeHandler, UserQuestionOption } from '../../types/hitl/index.js'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
@@ -13,6 +14,13 @@ export type TaskLaunchedCallback = (
 		agentId: string
 		description: string
 		planTaskId?: string
+		/**
+		 * The assistant `tool_use_id` that dispatched this task.
+		 * Threaded from `ToolContext.toolUseId` so the runtime can
+		 * later emit a canonical `tool_result` content block bound
+		 * to the same id when the background task completes.
+		 */
+		originalToolUseId?: string
 	},
 ) => void
 
@@ -29,6 +37,52 @@ export interface CoordinatorToolsOptions {
 	getPlanManager?: () => PlanManager | undefined
 
 	onTaskLaunched?: TaskLaunchedCallback
+
+	/**
+	 * HITL park channel for `ask_user_question`. The tool is registered
+	 * only when BOTH `resumeHandler` and `runId` are present — without a
+	 * handler there is no one to route the question to, and without a
+	 * runId the park request cannot be addressed.
+	 */
+	resumeHandler?: ResumeHandler
+}
+
+const approvePlanStepSchema = z.object({
+	description: z.string().describe('What this step does'),
+	agent_id: z
+		.string()
+		.optional()
+		.describe('Which agent handles this (omit for orchestrator-owned steps)'),
+	depends_on: z.array(z.string()).optional().describe('Step descriptions this depends on'),
+})
+
+function normalizeApprovePlanSteps(value: unknown): unknown {
+	if (typeof value !== 'string') return value
+
+	const trimmed = value.trim()
+	if (!trimmed) return []
+
+	if (trimmed.startsWith('[')) {
+		try {
+			return JSON.parse(trimmed)
+		} catch {
+			// Fall through to plain-text line parsing.
+		}
+	}
+
+	const lines = trimmed
+		.split(/\r?\n+/)
+		.map((line) =>
+			line
+				.trim()
+				.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+				.trim(),
+		)
+		.filter(Boolean)
+
+	return (lines.length ? lines : [trimmed]).map((description) => ({
+		description,
+	}))
 }
 
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
@@ -38,21 +92,30 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		taskStore,
 		runId,
 		getPlanManager,
-		onTaskLaunched,
+		resumeHandler,
+		// `onTaskLaunched` was the entry point for the old
+		// non-blocking + envelope-injection flow. create_task is now
+		// blocking, so the callback is no longer wired here.
+		// Intentionally not destructured to keep the unused-binding
+		// lint clean; callers can still pass it for backwards
+		// compatibility (Agent tool consumes it from its own path).
 	} = opts
 	const cwd = opts.workingDirectory
+	void opts.onTaskLaunched
 
 	const agentIdEnum = agentIds.length > 0 ? z.enum(agentIds as [string, ...string[]]) : z.string()
 
 	const createTask = defineTool({
 		name: 'create_task',
-		description: `Launch a task on a specialized agent. NON-BLOCKING: returns immediately. You will receive a <task-notification> message when the agent finishes. Available agents: ${agentIds.join(', ')}. The agent cannot see your conversation — include ALL necessary context in the prompt. To launch multiple tasks in parallel, call this tool multiple times in a single response. After launching, briefly tell the user what you launched and end your turn — do NOT predict or fabricate results.`,
+		description: `Launch a task on a specialized agent and await its result. BLOCKING: returns the agent's final output as this call's tool_result. Available agents: ${agentIds.join(', ')}. Prefer compact assignments; for large context, write/read shared workspace files and pass filenames or references. To launch multiple tasks in parallel, call this tool multiple times in a single assistant turn — the runtime executes every tool_use block from one response concurrently and delivers all tool_results together, so 'fan out 8 specialists' is one assistant message with 8 create_task blocks.`,
 		inputSchema: z.object({
 			agent_id: agentIdEnum.describe('Which agent to run'),
 			prompt: z
 				.string()
-				.describe('Self-contained task description with all context the agent needs'),
-			description: z.string().describe('Short summary for tracking (shown to user)'),
+				.describe(
+					'Self-contained assignment for the agent. For large generated content, prefer workspace file references so provider output-token limits do not cut off the tool call.',
+				),
+			description: z.string().describe('Short summary for tracking, shown to the user.'),
 			plan_task_id: z
 				.string()
 				.optional()
@@ -65,7 +128,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
-		async execute({ agent_id, prompt, description, plan_task_id }) {
+		async execute({ agent_id, prompt, description, plan_task_id }, _context) {
 			let resolvedPlanTaskId = plan_task_id
 
 			if (taskStore) {
@@ -93,22 +156,36 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				runtimeContext: opts.runtimeContext,
 			})
 
-			if (onTaskLaunched) {
-				onTaskLaunched(handle.taskId, {
-					agentId: agent_id,
-					description,
-					planTaskId: resolvedPlanTaskId,
+			// Industrial-standard Anthropic tool pattern: tool returns
+			// its real result as the tool_result for the dispatching
+			// tool_use. Parallel fan-out happens at the executor layer
+			// — when the supervisor emits N create_task blocks in one
+			// assistant turn, the runtime runs them with Promise.all
+			// and delivers all N tool_results together. No async
+			// envelope injection, no second tool_result for the same
+			// tool_use_id (which Anthropic rejects with 400).
+			const completed = await gateway.waitForTask(handle.taskId)
+			const success = completed.state === 'completed'
+			const resultText =
+				completed.result?.result ??
+				completed.result?.lastError ??
+				`Task finished with state: ${completed.state}`
+
+			if (resolvedPlanTaskId && taskStore) {
+				await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+					status: 'completed',
+					description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
 				})
 			}
 
 			return {
-				success: true,
-				output: `Task launched: ${handle.taskId} → ${agent_id} ("${description}"). You will receive a task-notification when it completes.`,
+				success,
+				output: resultText,
 				data: {
 					task_id: handle.taskId,
 					agent_id,
 					description,
-					state: 'running',
+					state: completed.state,
 					plan_task_id: resolvedPlanTaskId,
 				},
 			}
@@ -118,11 +195,9 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	const continueTask = defineTool({
 		name: 'continue_task',
 		description:
-			'Send a follow-up message to a previously completed task. NON-BLOCKING: the agent resumes in the background with full prior context. You will receive a task-notification when it finishes. Only use this with a task_id from a previous create_task or task-notification.',
+			"Send a follow-up message to a previously completed task and await the agent's next reply. BLOCKING: returns the agent's new output as this call's tool_result, the same shape as create_task. Only use this with a task_id from a previous create_task. To run multiple follow-ups in parallel, call this tool multiple times in a single assistant turn.",
 		inputSchema: z.object({
-			task_id: z
-				.string()
-				.describe('Agent task ID from a previous create_task or task-notification'),
+			task_id: z.string().describe('Agent task ID from a previous create_task'),
 			message: z.string().describe('Follow-up instruction for the agent'),
 		}),
 		category: 'custom',
@@ -132,11 +207,22 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		concurrencySafe: true,
 		async execute({ task_id, message }) {
 			await gateway.continueTask(task_id as TaskId, message)
-
+			// Mirror create_task's blocking pattern: await the new
+			// completion and return the agent's output inline. The
+			// previous non-blocking shape ('You will receive a
+			// task-notification…') relied on a global
+			// onTaskCompleted listener that the iteration loop
+			// no longer registers (envelope path is dead).
+			const completed = await gateway.waitForTask(task_id as TaskId)
+			const success = completed.state === 'completed'
+			const resultText =
+				completed.result?.result ??
+				completed.result?.lastError ??
+				`Task finished with state: ${completed.state}`
 			return {
-				success: true,
-				output: `Follow-up sent to ${task_id}. You will receive a task-notification when it finishes.`,
-				data: { task_id, state: 'running' },
+				success,
+				output: resultText,
+				data: { task_id, state: completed.state },
 			}
 		},
 	})
@@ -163,7 +249,75 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	const tools: ToolDefinition[] = [createTask, continueTask, cancelTask]
+	const agentTaskList = defineTool({
+		name: 'agent_task_list',
+		description:
+			"Inspect the live state of every agent task launched on this gateway via create_task: returns each task's id, agent, state (pending/running/completed/failed/canceled), and timing. Distinct from the plan-task store's `task_list` (which lists planning tasks): this tool lists running/completed worker invocations. Use it BEFORE declaring multi-worker work done — confirm every launched task reached `completed`, none still `running` or `failed`. Read-only and safe to call repeatedly.",
+		inputSchema: z.object({
+			state: z
+				.enum(['pending', 'running', 'completed', 'failed', 'canceled'])
+				.optional()
+				.describe('Filter by terminal/non-terminal state. Omit to list every task.'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ state }) {
+			const handles = gateway.listTasks()
+			const filtered = state ? handles.filter((h) => h.state === state) : handles
+			const items = filtered.map((h) => {
+				const runStatus = h.result?.status
+				const lastError = h.result?.lastError ?? undefined
+				return {
+					task_id: h.taskId,
+					agent_id: h.agentId,
+					state: h.state,
+					run_status: runStatus,
+					created_at: new Date(h.createdAt).toISOString(),
+					completed_at: h.completedAt ? new Date(h.completedAt).toISOString() : null,
+					duration_ms: h.completedAt ? h.completedAt - h.createdAt : null,
+					last_error: lastError,
+				}
+			})
+			const summary = {
+				total: handles.length,
+				running: handles.filter((h) => h.state === 'running').length,
+				completed: handles.filter((h) => h.state === 'completed').length,
+				failed: handles.filter((h) => h.state === 'failed').length,
+				canceled: handles.filter((h) => h.state === 'canceled').length,
+			}
+			const lines = items.length
+				? items.map(
+						(i) =>
+							`- ${i.task_id} → ${i.agent_id} [${i.state}${i.run_status && i.run_status !== i.state ? ` / ${i.run_status}` : ''}]${
+								i.duration_ms !== null ? ` (${Math.round(i.duration_ms / 1000)}s)` : ''
+							}${i.last_error ? ` — error: ${i.last_error.slice(0, 200)}` : ''}`,
+					)
+				: ['(no tasks launched yet)']
+			const header = `Tasks: ${summary.total} total — ${summary.running} running, ${summary.completed} completed, ${summary.failed} failed, ${summary.canceled} canceled`
+			return {
+				success: true,
+				output: [header, '', ...lines].join('\n'),
+				data: { items, summary },
+			}
+		},
+	})
+
+	// `continue_task` was a follow-up channel for a still-alive worker
+	// task. With `create_task` now blocking + tool_result returning
+	// the worker's final output, every worker reaches a terminal
+	// state by the time the supervisor wants to follow up — and the
+	// agent manager rejects `continue` on terminal tasks. The
+	// industrial pattern is to issue a fresh `create_task` that
+	// references the prior worker's output path, so we drop
+	// `continue_task` from the registered surface entirely. The
+	// definition stays in this file for now in case a future
+	// non-default gateway (one that keeps the worker process alive
+	// for follow-ups) wants to re-register it.
+	void continueTask
+	const tools: ToolDefinition[] = [createTask, cancelTask, agentTaskList]
 
 	if (getPlanManager) {
 		const approvePlan = defineTool({
@@ -176,26 +330,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					.describe('Short title for the plan (e.g. "TypeScript Security & Performance Review")'),
 				summary: z.string().describe('1-3 sentence summary of what you plan to do'),
 				steps: z
-					.array(
-						z.object({
-							description: z.string().describe('What this step does'),
-							agent_id: z
-								.string()
-								.optional()
-								.describe('Which agent handles this (omit for orchestrator-owned steps)'),
-							depends_on: z
-								.array(z.string())
-								.optional()
-								.describe('Step descriptions this depends on'),
-						}),
-					)
+					.preprocess(normalizeApprovePlanSteps, z.array(approvePlanStepSchema))
 					.describe('Ordered list of planned steps'),
 			}),
 			category: 'custom',
 			permissions: [],
 			readOnly: true,
 			destructive: false,
-			concurrencySafe: true,
+			// Parks through the SAME runId-keyed host resume registry as
+			// ask_user_question — concurrent parks in one batch clobber the
+			// registry entry and deadlock the loser, so the executor must
+			// serialize this tool exactly like the question tool.
+			concurrencySafe: false,
 			async execute({ title, summary, steps }) {
 				const pm = getPlanManager()
 				if (!pm) {
@@ -224,17 +370,27 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 				if (response.approved) {
 					pm.startExecution()
+					// Approve-with-edits: when the user attached feedback to an
+					// approval, embed it in the model-visible output so the
+					// supervisor applies the edits during execution. A bare
+					// approve keeps the historical output byte-identical.
+					const output = response.feedback
+						? `Plan approved by user with required edits — apply them during execution:\n${response.feedback}\nProceed with execution — launch workers via create_task.`
+						: 'Plan approved by user. Proceed with execution — launch workers via create_task.'
 					return {
 						success: true,
-						output:
-							'Plan approved by user. Proceed with execution — launch workers via create_task.',
+						output,
 						data: { approved: true, feedback: response.feedback },
 					}
 				}
 
+				// Rejection guidance follows the FEEDBACK, not a baked-in
+				// revise loop: the old unconditional "revise … and call
+				// approve_plan again" contradicted stop-style feedback, so a
+				// user rejecting a plan got another plan instead of a halt.
 				return {
 					success: false,
-					output: `Plan rejected. User feedback: ${response.feedback ?? 'No feedback provided'}. Revise your plan based on this feedback and call approve_plan again, or ask the user for clarification.`,
+					output: `Plan rejected. User feedback: ${response.feedback ?? 'No feedback provided'}. Follow this feedback: if it requests changes, revise your plan and call approve_plan again; if it asks you to stop, acknowledge briefly and end your turn. If no feedback was provided, ask the user how to proceed before planning again.`,
 					data: { approved: false, feedback: response.feedback },
 				}
 			},
@@ -242,5 +398,165 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		tools.push(approvePlan)
 	}
 
+	if (resumeHandler && runId) {
+		const parkRunId = runId
+		const parkHandler = resumeHandler
+		const askUserQuestion = defineTool({
+			name: 'ask_user_question',
+			description:
+				'Ask the user ONE question ONLY when you are blocked on a decision that is genuinely theirs to make — one you cannot resolve from their request, your tools, the files you can read, or sensible defaults. The question must be the genuinely undecidable thing in THIS task. Never ask for information a tool can discover (do not ask what you can read, list, or search), never re-ask what the conversation already answers, and never ask meta-questions like "Shall I proceed?" — plan ratification goes through approve_plan. Provide 2-4 genuinely distinct options derived from the actual context — concrete paths, never generic placeholders (for example, asked to prepare a presentation, ask "Who is the audience?" with options like Board / Engineering team / Customer); keep labels short (1-5 words) and give each option a one-line description of what practically changes if it is chosen. Put your recommended option FIRST and append " (Recommended)" to its label. Set multiSelect: true only when several options can apply at once. A free-text "Something else" escape hatch is always shown automatically — do not add your own "Other" option. Ask ONE question per call and prefer at most one question per assistant turn; if several decisions block you, ask only the ones that materially change your next actions, in sequence — most work needs at most 2-3 questions, so prefer proceeding on stated defaults over interrogating the user. Never invent answers or synthetic content on the user\'s behalf unless they explicitly asked for a random/test scenario. The answer arrives as this tool\'s result; if the result says the user did not answer, do not ask this or any other question again — proceed on your best judgment without assuming consent.',
+			inputSchema: z.object({
+				question: z
+					.string()
+					.min(1)
+					.describe('Full question text — clear, specific, ends with a question mark.'),
+				header: z
+					.string()
+					.max(24)
+					.optional()
+					.describe('Very short topic label for the question (e.g. "Audience", "Auth method").'),
+				options: z
+					.array(
+						z.object({
+							label: z
+								.string()
+								.min(1)
+								.max(80)
+								.describe(
+									'Concise option label (1-5 words). Recommended option goes first with " (Recommended)" appended.',
+								),
+							description: z
+								.string()
+								.max(300)
+								.optional()
+								.describe('One line on what practically changes if this option is chosen.'),
+						}),
+					)
+					.min(2)
+					.max(4)
+					.describe('2-4 genuinely distinct, context-derived options.'),
+				multiSelect: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('True only when several options can apply at once.'),
+				allowFreeText: z
+					.boolean()
+					.optional()
+					.default(true)
+					.describe('Whether the user may answer in their own words.'),
+			}),
+			category: 'custom',
+			permissions: [],
+			readOnly: true,
+			destructive: false,
+			// MUST stay false: the executor serializes non-concurrency-safe
+			// tools in a single chain, so N question blocks in one assistant
+			// turn park strictly one-at-a-time. Hosts key their park/resolve
+			// registries by runId — concurrent parks on one run clobber each
+			// other and the first promise never resolves (run hangs to TTL).
+			concurrencySafe: false,
+			async execute({ question, header, options, multiSelect, allowFreeText }, context) {
+				const toolUseId = context.toolUseId
+				if (!toolUseId) {
+					// Without the executing tool_use_id the question has no
+					// stable identity: the host could never merge the awaiting
+					// card with its resolution, and answers could not be matched
+					// back. Hard-fail instead of parking an unmergeable id.
+					return {
+						success: false,
+						output: '',
+						error:
+							'ask_user_question requires an executor that threads ToolContext.toolUseId; the question cannot be tracked without it.',
+					}
+				}
+
+				const questionOptions: UserQuestionOption[] = options.map((opt, i) => ({
+					id: `opt_${i + 1}`,
+					label: opt.label,
+					...(opt.description !== undefined ? { description: opt.description } : {}),
+				}))
+
+				const decision = await parkHandler({
+					type: 'user_question',
+					runId: parkRunId,
+					checkpointId: `cp_question_${toolUseId}`,
+					question: {
+						questionId: toolUseId,
+						question,
+						...(header !== undefined ? { header } : {}),
+						options: questionOptions,
+						multiSelect,
+						allowFreeText,
+					},
+				})
+
+				// The no-answer sentinel (explicitly NOT consent — fixes the
+				// "empty answer reads as approval" ambiguity): used for empty
+				// answers, misdirected legacy decisions (e.g. a stale replica
+				// resolving with approve/continue verbs), and answers that
+				// carry a different question's id.
+				const noAnswer = {
+					success: true,
+					output:
+						'The user did not answer this question. Do not assume a choice or consent; proceed on your best judgment or continue without this information.',
+					data: { question, answered: false },
+				}
+
+				if (decision.action === 'abort') {
+					return {
+						success: false,
+						output:
+							'The user declined to answer and asked to stop. Acknowledge briefly and end your turn.',
+						data: { question, answered: false, declined: true },
+					}
+				}
+
+				if (decision.action !== 'answer_question') return noAnswer
+				if (decision.questionId !== undefined && decision.questionId !== toolUseId) {
+					// Misdirection guard: this answer was meant for a different
+					// question parked under the same run (stale client). Never
+					// fabricate a selection against the wrong question.
+					return noAnswer
+				}
+
+				const stripRecommended = (label: string) =>
+					label.replace(/\s*\(recommended\)\s*$/i, '').trim()
+
+				const selected = decision.selectedOptionIds
+					.map((id) => questionOptions.find((opt) => opt.id === id))
+					.filter((opt): opt is UserQuestionOption => opt !== undefined)
+					.map((opt) => ({ id: opt.id, label: stripRecommended(opt.label) }))
+
+				const freeText = decision.freeText?.trim() ?? ''
+
+				if (selected.length === 0 && !freeText) return noAnswer
+
+				let output: string
+				if (selected.length > 0) {
+					const joined = selected.map((s) => `"${s.label}"`).join(', ')
+					output = `User answered "${question}": ${joined}`
+					if (freeText) {
+						output += `\nAdditional note from the user: "${freeText}"`
+					}
+				} else {
+					output = `User answered "${question}" in their own words: "${freeText}"`
+				}
+
+				return {
+					success: true,
+					output,
+					data: {
+						question,
+						selected,
+						...(freeText ? { freeText } : {}),
+						answered: true,
+					},
+				}
+			},
+		})
+		tools.push(askUserQuestion)
+	}
+
 	return tools
 }

package/src/types/agent/base.ts

@@ -65,6 +65,14 @@ export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>
 export interface AgentRuntimeContext {
 	label?: string
 	outputDirectory?: string
+	/**
+	 * Optional working/scratch directory the runtime exposes to the
+	 * agent — sibling to `outputDirectory`, invisible to the
+	 * output collector. Mirrors the Anthropic Cowork pattern
+	 * where `/home/claude` is scratch and `/mnt/user-data/outputs` is
+	 * user-visible.
+	 */
+	scratchDirectory?: string
 	outputFileMarker?: string
 	notes?: readonly string[]
 }