@namzu/sdk 8.0.0 → 9.0.0

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 {

package/src/types/agent/supervisor.ts

@@ -10,7 +10,7 @@ import type { ToolRegistryContract } from '../tool/index.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
-import type { TaskGateway } from './gateway.js'
+import type { SiblingFailurePolicy, TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
@@ -72,6 +72,45 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	maxDepth?: number
 
+	/**
+	 * How many tools may execute at once in one turn — which, for a
+	 * supervisor, is how wide a fan-out actually runs.
+	 *
+	 * The kernel has honoured this all along and `ReactiveAgent` forwards it.
+	 * It was missing here, so the agent whose entire job is delegation could
+	 * not set the gate that bounds delegation, while the agent that does not
+	 * delegate could. A host wanting a narrower fan-out had to reach past the
+	 * supervisor to `drainQuery`.
+	 *
+	 * Absent leaves the kernel default. Note what it does and does not bound:
+	 * it limits how many delegated children run CONCURRENTLY, not how many a
+	 * turn may launch — a model that emits twenty `create_task` blocks still
+	 * launches twenty, and they queue.
+	 */
+	maxToolConcurrency?: number
+
+	/**
+	 * What a failed child means for the siblings still running. Defaults to
+	 * `'continue'`.
+	 *
+	 * `LocalTaskGateway` has honoured this since it was written, and the
+	 * cancellation machinery behind `'cancel-siblings'` is complete — but the
+	 * policy was a constructor argument on a gateway the supervisor builds
+	 * itself, and the supervisor passed nothing. So every host in existence
+	 * ran `'continue'`, and the only way to reach the other value was to
+	 * construct the gateway by hand and hand it in. A policy nobody can select
+	 * is not a policy.
+	 *
+	 * `'continue'` stays the default deliberately: partial results are usually
+	 * worth having, and tearing down healthy siblings on any failure lets one
+	 * flaky child waste four good ones. `'cancel-siblings'` is for a fan-out
+	 * whose parts only mean something together — if one leg of a comparison
+	 * dies, the others are spending budget on an answer nobody can use.
+	 *
+	 * Ignored when the host supplies its own `gateway`, which owns its policy.
+	 */
+	siblingFailurePolicy?: SiblingFailurePolicy
+
 	taskRouter?: TaskRouterConfig
 
 	factoryOptions?: AgentFactoryOptions

package/src/types/plan/index.ts

@@ -18,7 +18,36 @@ export interface PlanStep {
 	id: string
 	description: string
 	toolName?: string
+
+	/**
+	 * Which agent this step is to be delegated to, when it is delegated at all.
+	 *
+	 * `approve_plan` invites the model to name an agent per step, and that
+	 * answer was reduced to a boolean: the step got `toolName: 'create_task'`
+	 * if any agent was named and nothing if not. So the human approving the
+	 * plan was shown THAT a step delegates and never TO WHOM — while the model
+	 * had said, and the approval is the one moment where the difference can
+	 * still be acted on. Approving "delegate this" is not approving "delegate
+	 * this to the agent with shell access".
+	 *
+	 * Typed rather than folded into {@link estimatedInput}, which is `unknown`:
+	 * an approval gate's whole job is being readable, and a field a host has to
+	 * cast before it can render is one a host renders wrong or not at all.
+	 *
+	 * Absent means the step is the orchestrator's own work, which is what
+	 * omitting `agent_id` in `approve_plan` says.
+	 */
+	agentId?: string
+
+	/**
+	 * **No producer and no reader.** Nothing in the SDK writes this and
+	 * nothing reads it; it is declared here and that is all. Noted rather
+	 * than removed because it is on the published typings — see
+	 * {@link agentId}, which is the field the plan approval path actually
+	 * needed and did not have.
+	 */
 	estimatedInput?: unknown
+
 	dependsOn: string[]
 	status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed'
 	error?: string

package/src/types/run/events.ts

@@ -461,6 +461,21 @@ type CoreRunEvent =
 			taskId: TaskId
 			subject: string
 			status: TaskStatus
+			/**
+			 * What this unit waits on, and who claims it.
+			 *
+			 * The store maintains a full dependency graph — `blocks` and
+			 * `blockedBy` are mirrored on both ends, written under a lock, and
+			 * deadlock-avoided — and none of it reached the wire. So a host
+			 * could show a flat list of units and nothing about their order,
+			 * while the model was already maintaining the order.
+			 *
+			 * Absent rather than empty when the unit depends on nothing, so a
+			 * reader can tell "no dependencies" from an emitter that predates
+			 * these fields.
+			 */
+			blockedBy?: readonly TaskId[]
+			owner?: string
 	  }
 	| {
 			type: 'task_updated'
@@ -469,6 +484,8 @@ type CoreRunEvent =
 			subject: string
 			status: TaskStatus
 			owner?: string
+			/** See `task_created`. Carried on updates because an edge can be added later. */
+			blockedBy?: readonly TaskId[]
 	  }
 	| {
 			type: 'plugin_hook_executing'

package/src/types/task/index.ts

@@ -1,9 +1,27 @@
 import type { RunId, TaskId, TenantId } from '../ids/index.js'
 
-export type TaskStatus = 'pending' | 'in_progress' | 'completed'
-
+/**
+ * `failed` exists because a unit that did not succeed had nowhere to say so.
+ *
+ * Delegation wrote a failed worker's task as `completed` with the failure
+ * encoded as prose in `description` — so a reader scanning statuses saw work
+ * that had been done, and only a reader of every description saw otherwise. A
+ * status nobody can set is a status nobody can act on: a dependent unit cannot
+ * decide whether to wait or give up, and a plan cannot report that it did not
+ * finish.
+ */
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed'
+
+/**
+ * Terminal means "will not change on its own", not "succeeded".
+ *
+ * `failed` is terminal for the same reason `completed` is: nothing downstream
+ * should wait on it. That matters most to the blocker check in the task
+ * listing — a dependent unit blocked on something that failed would otherwise
+ * wait forever for a status that will never arrive.
+ */
 export function isTerminalTaskStatus(status: TaskStatus): boolean {
-	return status === 'completed'
+	return status === 'completed' || status === 'failed'
 }
 
 export function assertTaskStatus(status: TaskStatus): void {
@@ -11,6 +29,7 @@ export function assertTaskStatus(status: TaskStatus): void {
 		case 'pending':
 		case 'in_progress':
 		case 'completed':
+		case 'failed':
 			return
 		default: {
 			const _exhaustive: never = status