@namzu/sdk 8.0.0 → 10.0.0

package/src/runtime/query/events.ts

@@ -121,6 +121,10 @@ export class EventTranslator {
 						taskId: task.id,
 						subject: task.subject,
 						status: task.status,
+						// Absent rather than empty: a reader must be able to tell
+						// "depends on nothing" from an emitter that predates these.
+						...(task.blockedBy.length > 0 ? { blockedBy: task.blockedBy } : {}),
+						...(task.owner !== undefined ? { owner: task.owner } : {}),
 					})
 					break
 				case 'task.updated':
@@ -133,6 +137,7 @@ export class EventTranslator {
 						subject: task.subject,
 						status: task.status,
 						owner: task.owner,
+						...(task.blockedBy.length > 0 ? { blockedBy: task.blockedBy } : {}),
 					})
 					break
 				default: {

package/src/runtime/query/index.ts

@@ -420,11 +420,6 @@ export interface QueryParams {
 	 */
 	completionInbox?: import('../../gateway/completion-inbox.js').CompletionInbox
 
-	launchedTasks?: Map<
-		import('../../types/ids/index.js').TaskId,
-		import('./iteration/phases/context.js').LaunchedTaskMeta
-	>
-
 	onContextCreated?: (ctx: {
 		planManager: import('../../manager/plan/lifecycle.js').PlanManager
 	}) => void
@@ -854,7 +849,6 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		taskGateway: params.taskGateway,
 		completionInbox: params.completionInbox,
 		taskStore: params.taskStore,
-		launchedTasks: params.launchedTasks ?? new Map(),
 		// Run-scoped. An approval is a statement about this run's work;
 		// carrying one into a later run would be reuse nobody agreed to.
 		toolGrants: new ToolGrantSet(),

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

@@ -14,7 +14,6 @@ import type {
 	IterationCheckpoint,
 	ResumeHandler,
 } from '../../../../types/hitl/index.js'
-import type { TaskId } from '../../../../types/ids/index.js'
 import type { LLMProvider } from '../../../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../../../types/router/index.js'
 import type { ReviewAnswer } from '../../../../types/run/answer-review.js'
@@ -36,22 +35,6 @@ import type { GuardCoordinator } from '../../guard.js'
 import type { SteeringChannel } from '../../steering.js'
 import type { ToolGrantSet } from '../../tool-grants.js'
 
-export interface LaunchedTaskMeta {
-	readonly agentId: string
-	readonly description: string
-	readonly planTaskId?: string
-	/**
-	 * The `tool_use_id` of the assistant `create_task` block that
-	 * spawned this background task. Required to emit the canonical
-	 * `tool_result` content block when the task completes — without
-	 * it we'd fall back to the legacy synthetic-user-message inject
-	 * (see ses_009-task-notification-envelope). Optional because
-	 * older call paths that don't thread `ToolContext.toolUseId`
-	 * still publish the meta without it.
-	 */
-	readonly originalToolUseId?: string
-}
-
 export interface IterationContext {
 	readonly provider: LLMProvider
 	/**
@@ -115,8 +98,6 @@ export interface IterationContext {
 
 	readonly taskStore?: TaskStore
 
-	readonly launchedTasks: Map<TaskId, LaunchedTaskMeta>
-
 	/**
 	 * Approvals a human granted earlier in this run, at a scope they chose.
 	 *

package/src/store/task/disk.ts

@@ -35,10 +35,16 @@ export interface DiskTaskStoreConfig {
 	logger?: Logger
 }
 
+// `failed` ranks alongside `completed` rather than after it: both are
+// terminal, and neither may transition to the other. Ranking it higher would
+// admit completed -> failed, which would let a settled unit be reopened as a
+// failure; ranking it lower would forbid in_progress -> failed, which is the
+// transition this status exists for.
 const STATUS_ORDER: Record<TaskStatus, number> = {
 	pending: 0,
 	in_progress: 1,
 	completed: 2,
+	failed: 2,
 }
 
 function isForwardTransition(from: TaskStatus, to: TaskStatus): boolean {
@@ -393,7 +399,16 @@ export class DiskTaskStore implements TaskStore {
 			}
 			if (!mutated) {
 				this.log.debug('block(): edge already exists', { blockerId, blockedId })
+				return
 			}
+
+			// Announce BOTH ends, and only when something actually changed. The
+			// edge was written and nothing said so, so the graph was observable
+			// only by polling — a listener saw a unit created and never learned
+			// that something now waits on it.
+			const now = Date.now()
+			this.emit({ type: 'task.updated', taskId: blockerId, task: blocker, timestamp: now })
+			this.emit({ type: 'task.updated', taskId: blockedId, task: blocked, timestamp: now })
 		})
 	}
 

package/src/store/task/memory.ts

@@ -10,10 +10,16 @@ import type {
 } from '../../types/task/index.js'
 import { generateTaskId } from '../../utils/id.js'
 
+// `failed` ranks alongside `completed` rather than after it: both are
+// terminal, and neither may transition to the other. Ranking it higher would
+// admit completed -> failed, which would let a settled unit be reopened as a
+// failure; ranking it lower would forbid in_progress -> failed, which is the
+// transition this status exists for.
 const STATUS_ORDER: Record<TaskStatus, number> = {
 	pending: 0,
 	in_progress: 1,
 	completed: 2,
+	failed: 2,
 }
 
 function isForwardTransition(from: TaskStatus, to: TaskStatus): boolean {
@@ -177,6 +183,15 @@ export class InMemoryTaskStore implements TaskStore {
 		if (!blocked.blockedBy.includes(blockerId)) {
 			blocked.blockedBy.push(blockerId)
 		}
+
+		// Announce BOTH ends. The edge was written and nothing said so, which
+		// left the graph observable only by polling: a listener saw a unit
+		// created and never learned that something now waits on it. Both sides
+		// changed, so both are announced — a host tracking only one would draw
+		// half the edge.
+		const now = Date.now()
+		this.emit({ type: 'task.updated', taskId: blockerId, task: blocker, timestamp: now })
+		this.emit({ type: 'task.updated', taskId: blockedId, task: blocked, timestamp: now })
 	}
 
 	async reset(): Promise<void> {

package/src/tools/coordinator/__tests__/a-failed-worker-is-not-an-answer.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { TaskId } from '../../../types/ids/index.js'
+import type { ToolDefinition } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+import { failureLabel, taskSucceeded } from '../outcome.js'
+
+/**
+ * A worker that ran and failed was reported to the model as an answer.
+ *
+ * Two layers can disagree. `finalizeChild` always calls `markCompleted`, so the
+ * gateway's `state` is `'completed'` for a child whose run returned
+ * `status: 'failed'` — and `create_task` asked only that layer. The model then
+ * read the failure text as a result, the tool result carried `isError: false`,
+ * and the plan task was written closed as though the work had been done.
+ *
+ * The correct predicate existed twenty lines away in the canonical `Agent`
+ * tool, put there because a review caught it on that site. Nothing carried the
+ * answer to the other one. So this file tests the shared predicate, and the
+ * predicate is shared so there is no longer a second place to forget.
+ */
+
+const handle = (
+	state: TaskHandle['state'],
+	status?: string,
+): Pick<TaskHandle, 'state' | 'result'> =>
+	({ state, result: status === undefined ? undefined : { status } }) as Pick<
+		TaskHandle,
+		'state' | 'result'
+	>
+
+describe('success needs both authorities to agree', () => {
+	it('refuses a child the gateway called complete but whose run failed', () => {
+		// The exact shape the kernel produces: markCompleted was called, and
+		// the run underneath it did not succeed.
+		expect(taskSucceeded(handle('completed', 'failed'))).toBe(false)
+	})
+
+	it('accepts a child both layers agree on', () => {
+		expect(taskSucceeded(handle('completed', 'completed'))).toBe(true)
+	})
+
+	it('accepts a gateway that reports no run status at all', () => {
+		// A host gateway need not surface a run status. Treating its absence as
+		// failure would break every such gateway, so absence means "this layer
+		// has no opinion" rather than "it went wrong".
+		expect(taskSucceeded(handle('completed'))).toBe(true)
+	})
+
+	it('refuses a child that never reached a completed state', () => {
+		expect(taskSucceeded(handle('failed', 'completed'))).toBe(false)
+		expect(taskSucceeded(handle('canceled'))).toBe(false)
+	})
+})
+
+describe('the failure is named by whichever layer reported it', () => {
+	it('uses the task state when the task itself did not complete', () => {
+		// "failed" would lose the distinction a reader needs: a cancelled task
+		// and a task whose run errored call for different next moves.
+		expect(failureLabel(handle('canceled', 'completed'))).toBe('canceled')
+	})
+
+	it('uses the run status when the task completed but the run did not', () => {
+		expect(failureLabel(handle('completed', 'failed'))).toBe('failed')
+	})
+
+	it('falls back to a plain word when neither layer said anything useful', () => {
+		expect(failureLabel(handle('completed'))).toBe('failed')
+	})
+})
+
+describe('create_task itself reaches the predicate', () => {
+	/**
+	 * The unit tests above prove the predicate is right. They would all pass
+	 * with `create_task` still asking only the gateway — which is exactly the
+	 * state that shipped, with the correct version sitting twenty lines away in
+	 * a sibling tool.
+	 *
+	 * So this drives the tool.
+	 */
+	function toolFor(handle: TaskHandle): ToolDefinition {
+		const gateway = {
+			createTask: async () => ({ ...handle, state: 'running' }),
+			waitForTask: async () => handle,
+			getTask: () => handle,
+			listTasks: () => [handle],
+			cancelTask: () => undefined,
+			continueTask: async () => undefined,
+			onTaskCompleted: () => () => undefined,
+		} as unknown as TaskGateway
+
+		const tools = buildCoordinatorTools({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['reviewer'],
+		})
+		const createTask = tools.find((t) => t.name === 'create_task')
+		if (!createTask) throw new Error('create_task was not built')
+		return createTask
+	}
+
+	const settled = (status: string): TaskHandle =>
+		({
+			taskId: 'tsk_1' as TaskId,
+			agentId: 'reviewer',
+			// The kernel's own shape: markCompleted ran regardless of the run.
+			state: 'completed',
+			createdAt: 1_000,
+			completedAt: 2_000,
+			result: { status, result: 'the worker text', lastError: 'it blew up' },
+		}) as unknown as TaskHandle
+
+	it('reports a failed run as a failure', async () => {
+		const tool = toolFor(settled('failed'))
+		const result = await tool.execute(
+			{ agent_id: 'reviewer', prompt: 'go', description: 'a task' },
+			{ toolUseId: 'call_1' } as never,
+		)
+
+		expect(result.success, 'a failed worker was reported as an answer').toBe(false)
+	})
+
+	it('still reports a successful run as a success', async () => {
+		const tool = toolFor(settled('completed'))
+		const result = await tool.execute(
+			{ agent_id: 'reviewer', prompt: 'go', description: 'a task' },
+			{ toolUseId: 'call_1' } as never,
+		)
+
+		expect(result.success).toBe(true)
+	})
+})

package/src/tools/coordinator/__tests__/the-plan-a-human-approves.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+
+import { PlanManager } from '../../../manager/plan/lifecycle.js'
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { PlanApprovalRequest } from '../../../types/plan/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * The plan put in front of a human said a step delegates, never to whom.
+ *
+ * `approve_plan` asks the model for an `agent_id` per step — "which agent
+ * handles this" — and reduced the answer to a boolean: the step got
+ * `toolName: 'create_task'` when any agent was named and nothing when not. The
+ * name itself was dropped between the model saying it and the human being
+ * shown the plan.
+ *
+ * The approval is the one moment where that difference can still be acted on.
+ * Approving "delegate this step" is not the same as approving "delegate this
+ * step to the agent with shell access", and a reviewer who cannot see which
+ * agent was chosen cannot withhold approval from the wrong one.
+ */
+
+const RUN = 'run_plan_approval' as RunId
+
+function unusedGateway(): TaskGateway {
+	return {
+		async createTask() {
+			throw new Error('this test never launches')
+		},
+		async waitForTask() {
+			throw new Error('this test never waits')
+		},
+		async continueTask() {},
+		cancelTask() {},
+		getTask() {
+			return undefined
+		},
+		listTasks() {
+			return []
+		},
+		onTaskCompleted() {
+			return () => {}
+		},
+	}
+}
+
+function testToolContext(): ToolContext {
+	return {
+		runId: RUN,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** Run `approve_plan` and hand back exactly what the approver was shown. */
+async function whatTheApproverSaw(
+	steps: Array<{ description: string; agent_id?: string }>,
+): Promise<PlanApprovalRequest> {
+	let seen: PlanApprovalRequest | undefined
+	const pm = new PlanManager(RUN, async (request) => {
+		seen = request
+		return { approved: true }
+	})
+
+	const tools = buildCoordinatorTools({
+		gateway: unusedGateway(),
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: ['researcher', 'shell-runner'],
+		getPlanManager: () => pm,
+	})
+
+	const approvePlan = tools.find((tool) => tool.name === 'approve_plan')
+	if (!approvePlan) throw new Error('approve_plan tool missing from coordinator builder')
+
+	await approvePlan.execute(
+		{ title: 'Do the work', summary: 'A plan with delegated steps.', steps },
+		testToolContext(),
+	)
+
+	if (!seen) throw new Error('the approval handler was never called')
+	return seen
+}
+
+describe('the plan a human approves names the agent the model chose', () => {
+	it('carries the agent per step, not just that there is one', async () => {
+		const request = await whatTheApproverSaw([
+			{ description: 'Gather the sources', agent_id: 'researcher' },
+			{ description: 'Run the migration', agent_id: 'shell-runner' },
+		])
+
+		expect(request.steps.map((s) => s.agentId)).toEqual(['researcher', 'shell-runner'])
+	})
+
+	it('distinguishes two delegated steps that used to look identical', async () => {
+		// The defect in the shape that matters: before this, both steps below
+		// reached the approver as `toolName: 'create_task'` and nothing else, so
+		// the one with shell access was indistinguishable from the one without.
+		const request = await whatTheApproverSaw([
+			{ description: 'Read the docs', agent_id: 'researcher' },
+			{ description: 'Delete the old rows', agent_id: 'shell-runner' },
+		])
+
+		const [first, second] = request.steps
+		expect(first?.toolName).toBe(second?.toolName)
+		expect(first?.agentId).not.toBe(second?.agentId)
+	})
+
+	it('leaves an orchestrator-owned step unattributed', async () => {
+		// Omitting `agent_id` means the orchestrator does it itself. That has to
+		// stay distinguishable from delegation, so absent stays absent rather
+		// than becoming a placeholder name.
+		const request = await whatTheApproverSaw([{ description: 'Summarize what came back' }])
+
+		expect(request.steps[0]?.agentId).toBeUndefined()
+		expect(request.steps[0]?.toolName).toBeUndefined()
+	})
+})

package/src/tools/coordinator/agent.ts

@@ -5,6 +5,7 @@ import type { TaskGateway } from '../../types/agent/gateway.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
+import { failureLabel, taskSucceeded } from './outcome.js'
 
 import type { TaskLaunchedCallback } from './index.js'
 
@@ -138,6 +139,13 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 				prompt,
 				workingDirectory: cwd,
 				runtimeContext: opts.runtimeContext,
+				// Hang the child off the executing tool's span, so the
+				// delegation appears inside the turn that asked for it rather
+				// than as a disconnected root trace. `create_task` has done
+				// this all along; this tool — the kernel's other delegation
+				// surface, and the one it exports as the canonical shape —
+				// did not.
+				...(context.parentSpan ? { parentSpan: context.parentSpan } : {}),
 			})
 
 			onTaskLaunched?.(handle.taskId, {
@@ -153,26 +161,12 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 
 			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 review flagged on the first cut.
-			const runStatus = completed.result?.status
-			const succeeded =
-				completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed')
+			// Both authorities must agree — see `taskSucceeded` for which two
+			// and why either alone is wrong. The reasoning used to live here
+			// alone, which is exactly how `create_task` came to ship without
+			// it: a review caught this site, and nothing carried the answer to
+			// the other one.
+			const succeeded = taskSucceeded(completed)
 
 			const resultText =
 				typeof completed.result?.result === 'string'
@@ -182,19 +176,17 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 						: ''
 
 			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}`,
+					error: `Subagent ${agentId} ${failureLabel(completed)}: ${detail}`,
 					data: {
 						task_id: handle.taskId,
 						subagent_type: agentId,
 						state: completed.state,
-						status: runStatus,
+						status: completed.result?.status,
 						lastError: completed.result?.lastError,
 					},
 				}
@@ -221,7 +213,7 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 					subagent_type: agentId,
 					result: resultText,
 					state: completed.state,
-					status: runStatus,
+					status: completed.result?.status,
 				},
 			}
 		},

package/src/tools/coordinator/index.ts

@@ -10,6 +10,7 @@ import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
+import { failureLabel, taskSucceeded } from './outcome.js'
 import { resolvePlanDependencies } from './plan-dependencies.js'
 import { describeWaitTimeout, waitForTaskWithBounds } from './wait-with-idle-bound.js'
 
@@ -457,6 +458,17 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// Naming the missing piece is the only response that tells them
 			// what to change.
 			if (background && !canLaunchInBackground) {
+				// The plan task was marked in progress a few lines above, on the
+				// assumption that a worker was about to run. Nothing is running,
+				// so leaving it there would show a plan step underway with no
+				// worker behind it — indefinitely, since nothing later will
+				// close a task whose launch never happened.
+				if (resolvedPlanTaskId && taskStore) {
+					await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+						status: 'failed',
+						description: 'Failed: the launch was refused before any worker started',
+					})
+				}
 				return {
 					success: false,
 					output: '',
@@ -533,15 +545,26 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 			completionInbox?.claim(handle.taskId)
-			const success = completed.state === 'completed'
+			// Both authorities, not just the gateway's. `finalizeChild` always
+			// calls `markCompleted`, so `state === 'completed'` holds for a
+			// child that ran and returned `status: 'failed'` — and this tool
+			// reported that child's error text to the model as its answer, with
+			// `isError: false`, while writing the plan task closed as though
+			// the work had been done.
+			const success = taskSucceeded(completed)
 			const resultText =
 				completed.result?.result ??
 				completed.result?.lastError ??
-				`Task finished with state: ${completed.state}`
+				`Task finished with state: ${failureLabel(completed)}`
 
 			if (resolvedPlanTaskId && taskStore) {
+				// The status carries the outcome now, rather than `completed`
+				// with the failure written into prose. A reader scanning
+				// statuses saw work that had been done; only a reader of every
+				// description saw otherwise — and a dependent unit had no way
+				// to tell at all.
 				await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
-					status: 'completed',
+					status: success ? 'completed' : 'failed',
 					description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
 				})
 			}
@@ -922,6 +945,13 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						id: `step_${i + 1}`,
 						description: step.description,
 						toolName: step.agent_id ? 'create_task' : undefined,
+						// WHICH agent, not just whether there is one. The schema
+						// asks the model to name an agent per step and the answer
+						// was collapsed to the boolean above, so the human
+						// approving the plan saw that a step delegates and never
+						// to whom — at the one moment the difference can still be
+						// acted on.
+						...(step.agent_id ? { agentId: step.agent_id } : {}),
 						// Was `[]` unconditionally, which dropped every ordering
 						// constraint the model was invited to express — and put an
 						// empty dependency list in front of the human approving it.

package/src/tools/coordinator/outcome.ts

@@ -0,0 +1,70 @@
+import type { TaskHandle } from '../../types/agent/gateway.js'
+
+/**
+ * Did this worker actually succeed?
+ *
+ * Two layers can disagree, and asking only one of them is how a failed worker
+ * gets reported as an answer:
+ *
+ * 1. **`TaskHandle.state`** — the gateway's terminal task state. Some gateways
+ *    map a failed run to `state: 'failed'`; others forward whatever the agent
+ *    manager set, which does not always reflect run-level failure. The kernel's
+ *    own `finalizeChild` always calls `markCompleted`, so `state` is
+ *    `'completed'` for a child that ran and returned `status: 'failed'`.
+ * 2. **`BaseAgentResult.status`** — the run's own status, and the canonical
+ *    answer to whether the agent finished its work. `lastError` carries the
+ *    message when it did not.
+ *
+ * So success requires BOTH to agree. Reporting a failed worker as successful
+ * hands the parent garbage output as though it were a result, and makes
+ * debugging impossible — the model reads an error as an answer and builds on
+ * it.
+ *
+ * **This lives here because it was written twice and omitted once**, and the
+ * omission was in `create_task`, the primary delegation surface. The version in
+ * the canonical `Agent` tool was correct because a review caught it there; the
+ * same review never reached the other site. A predicate that is easy to get
+ * wrong, and whose wrong answer is silent, belongs in one place that every
+ * caller reaches rather than in each caller's memory.
+ */
+export function taskSucceeded(handle: Pick<TaskHandle, 'state' | 'result'>): boolean {
+	const runStatus = handle.result?.status
+	return handle.state === 'completed' && (runStatus === undefined || runStatus === 'completed')
+}
+
+/**
+ * Did this worker actually fail? **Not the negation of {@link taskSucceeded}.**
+ *
+ * Three answers exist, not two: succeeded, failed, and not settled yet. A task
+ * still running satisfies neither predicate, and that is the point — a caller
+ * deciding whether to tear down healthy siblings must act on a child that
+ * *failed*, never on one that merely has not succeeded yet. Writing this as
+ * `!taskSucceeded(handle)` would cancel a fan-out the moment the first child
+ * was still working.
+ *
+ * The two-authority rule applies here too, for the same reason: the kernel's
+ * `finalizeChild` always calls `markCompleted`, so a run that returned
+ * `status: 'failed'` carries `state: 'completed'`, and a check that read only
+ * the gateway state would never see it fail.
+ *
+ * Third copy of this knowledge, now in the one place `taskSucceeded` already
+ * lives — it was written independently in `LocalTaskGateway`, which got it
+ * right, but a rule that each caller has to remember is a rule one of them
+ * eventually forgets. That has already happened once with `taskSucceeded`.
+ */
+export function taskFailed(handle: Pick<TaskHandle, 'state' | 'result'>): boolean {
+	return handle.state === 'failed' || handle.result?.status === 'failed'
+}
+
+/**
+ * What to call the failure, in the words of whichever layer reported it.
+ *
+ * The gateway state wins when it is the one that disagrees, because a task that
+ * never reached `completed` failed in a way the run status cannot describe — it
+ * was cancelled, or it timed out, and saying "failed" for those loses the
+ * distinction a reader needs to decide what to do next.
+ */
+export function failureLabel(handle: Pick<TaskHandle, 'state' | 'result'>): string {
+	if (handle.state !== 'completed') return handle.state
+	return handle.result?.status ?? 'failed'
+}

package/src/types/agent/gateway.ts

@@ -1,5 +1,5 @@
 import type { TaskId } from '../ids/index.js'
-import type { AgentRuntimeContext, BaseAgentResult } from './base.js'
+import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentTaskState } from './task.js'
 
 export interface TaskHandle {
@@ -40,7 +40,24 @@ export interface CreateTaskOptions {
 
 	runtimeContext?: AgentRuntimeContext
 
-	configOverrides?: Record<string, unknown>
+	/**
+	 * Config the spawned run should be built with, overriding what the
+	 * agent's own definition supplies — the model it runs on, its iteration
+	 * ceiling, its thinking or effort settings.
+	 *
+	 * **This was accepted and dropped.** `LocalTaskGateway.createTask` built
+	 * its own `configOverrides` object out of `parentSpan` alone and never
+	 * read this field, so a caller pinning a delegated run to a cheaper model
+	 * got the agent's default model and no indication otherwise. It is
+	 * forwarded now, with the dedicated {@link parentSpan} option winning if
+	 * both name a span, since that one is the specific field for the job.
+	 *
+	 * Typed as `Partial<BaseAgentConfig>` rather than
+	 * `Record<string, unknown>`: this lands on `SendMessageOptions`, which is
+	 * already that shape, and the loose type let a misspelled key type-check
+	 * and then do nothing — the same silence this field was already producing.
+	 */
+	configOverrides?: Partial<BaseAgentConfig>
 }
 
 export interface TaskGateway {