@namzu/sdk 6.2.0 → 8.0.0

package/src/tools/coordinator/__tests__/wait-with-idle-bound.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { TaskId } from '../../../types/ids/index.js'
+import { describeWaitTimeout, waitForTaskWithBounds } from '../wait-with-idle-bound.js'
+
+/**
+ * A wall clock cannot tell a slow worker from a stuck one.
+ *
+ * The bound before this was an hour of elapsed time, and an hour has to do
+ * two incompatible jobs: be long enough for a child doing real work, and
+ * short enough to notice one that wedged. It cannot be both, so a worker
+ * stuck in minute two held the supervisor for another fifty-eight, and one
+ * making steady progress at minute fifty-nine was killed for being slow.
+ *
+ * These tests drive both clocks with a fake one, because the real bounds are
+ * measured in minutes and a test that actually waits them out is a test
+ * nobody runs.
+ */
+
+function gatewayFor(opts: {
+	/** Resolve the wait when this is called. */
+	settle?: (resolve: (h: TaskHandle) => void) => void
+	withProgress?: boolean
+}): { gateway: TaskGateway; progress: () => void; finish: () => void } {
+	let resolveWait: ((h: TaskHandle) => void) | undefined
+	const listeners = new Set<(id: TaskId) => void>()
+
+	const handle: TaskHandle = {
+		taskId: 'tsk_1' as TaskId,
+		agentId: 'worker',
+		state: 'completed',
+		createdAt: 0,
+		completedAt: 1,
+	}
+
+	const gateway = {
+		waitForTask: () =>
+			new Promise<TaskHandle>((resolve) => {
+				resolveWait = resolve
+				opts.settle?.(resolve)
+			}),
+		...(opts.withProgress === false
+			? {}
+			: {
+					onTaskProgress: (cb: (id: TaskId) => void) => {
+						listeners.add(cb)
+						return () => listeners.delete(cb)
+					},
+				}),
+	} as unknown as TaskGateway
+
+	return {
+		gateway,
+		progress: () => {
+			for (const cb of listeners) cb('tsk_1' as TaskId)
+		},
+		finish: () => resolveWait?.(handle),
+	}
+}
+
+/** A clock the test moves by hand. */
+function fakeClock(): { now: () => number; advance: (ms: number) => void } {
+	let t = 1_000_000
+	return {
+		now: () => t,
+		advance: (ms) => {
+			t += ms
+		},
+	}
+}
+
+describe('a worker that is still working is not killed for being slow', () => {
+	it('keeps waiting past the idle bound while progress keeps arriving', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, progress, finish } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 60_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			// Four times the idle bound in elapsed time, but never quiet for
+			// more than half of it.
+			for (let i = 0; i < 8; i += 1) {
+				clock.advance(2_500)
+				progress()
+				await vi.advanceTimersByTimeAsync(1_000)
+			}
+
+			finish()
+			await vi.advanceTimersByTimeAsync(1_000)
+
+			expect((await waiting).kind, 'a working worker was cut off').toBe('completed')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})
+
+describe('a worker that has gone quiet is reported as quiet', () => {
+	it('fires the idle bound and says which clock it was', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 600_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			clock.advance(6_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			// The distinction is the point: "went quiet" and "ran too long"
+			// are different diagnoses and the caller acts on the message.
+			expect(outcome.cause).toBe('idle')
+			expect(outcome.idleBoundArmed).toBe(true)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('says it went quiet, and that the worker was not cancelled', () => {
+		const text = describeWaitTimeout({
+			kind: 'timeout',
+			cause: 'idle',
+			elapsedMs: 30_000,
+			idleBoundArmed: true,
+		})
+
+		expect(text).toContain('went quiet')
+		// A wait that ran out is a statement about the WAITER. Losing an
+		// eight-minute worker's output because a short clock expired is the
+		// bug this whole area has been unpicking.
+		expect(text).toContain('not been cancelled')
+	})
+})
+
+describe('the run bound still catches a worker that never stops', () => {
+	it('fires on elapsed time even while progress keeps arriving', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, progress } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			for (let i = 0; i < 6; i += 1) {
+				clock.advance(2_000)
+				progress()
+				await vi.advanceTimersByTimeAsync(1_000)
+			}
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			expect(outcome.cause).toBe('run')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})
+
+describe('a gateway that cannot see its children', () => {
+	it('is bounded by the wall clock alone, as it was before', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway } = gatewayFor({ withProgress: false })
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 1_000 },
+				clock.now,
+			)
+
+			// Far past the idle bound, and it must NOT fire — there is no
+			// signal, so silence carries no information.
+			clock.advance(5_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+			clock.advance(6_000)
+			await vi.advanceTimersByTimeAsync(1_100)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('timeout')
+			if (outcome.kind !== 'timeout') return
+			expect(outcome.cause).toBe('run')
+			// And the degradation is visible rather than silent.
+			expect(outcome.idleBoundArmed).toBe(false)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('says so, instead of implying the worker was stuck', () => {
+		const text = describeWaitTimeout({
+			kind: 'timeout',
+			cause: 'run',
+			elapsedMs: 3_600_000,
+			idleBoundArmed: false,
+		})
+
+		expect(text).toContain('cannot report progress')
+	})
+})
+
+describe('a completion always wins', () => {
+	it('returns the handle rather than a timeout when the task finishes first', async () => {
+		vi.useFakeTimers()
+		try {
+			const clock = fakeClock()
+			const { gateway, finish } = gatewayFor({})
+
+			const waiting = waitForTaskWithBounds(
+				gateway,
+				'tsk_1' as TaskId,
+				{ runMs: 10_000, idleMs: 5_000 },
+				clock.now,
+			)
+
+			finish()
+			await vi.advanceTimersByTimeAsync(10)
+
+			const outcome = await waiting
+			expect(outcome.kind).toBe('completed')
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+})

package/src/tools/coordinator/index.ts

@@ -11,6 +11,7 @@ import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
 import { resolvePlanDependencies } from './plan-dependencies.js'
+import { describeWaitTimeout, waitForTaskWithBounds } from './wait-with-idle-bound.js'
 
 export type TaskLaunchedCallback = (
 	agentTaskId: TaskId,
@@ -259,6 +260,33 @@ const LISTED_RESULT_LIMIT = 2_000
  */
 export const DELEGATION_TIMEOUT_MS = 60 * 60 * 1000
 
+/**
+ * How long a delegated worker may say nothing before the wait gives up.
+ *
+ * The hour above answers "how long is too long". It cannot also answer
+ * "how quiet is too quiet", because it has to be generous enough for a
+ * child doing real work — which makes it useless as a stall detector. A
+ * worker wedged in its second minute held the supervisor for another
+ * fifty-eight under that number alone.
+ *
+ * Five minutes of silence, because a worker between tool calls can be
+ * quiet for a while legitimately — a long model turn emits nothing until
+ * it starts streaming — and the cost of guessing low is killing a wait on
+ * a worker that was fine. Guessing high only delays a diagnosis. Set
+ * `NAMZU_DELEGATION_IDLE_MS` to change it.
+ *
+ * Only armed when the gateway can report progress at all; see
+ * `TaskGateway.onTaskProgress`.
+ */
+export const DELEGATION_IDLE_MS = readPositiveIntEnv('NAMZU_DELEGATION_IDLE_MS', 5 * 60 * 1000)
+
+function readPositiveIntEnv(key: string, fallback: number): number {
+	const value = process.env[key]?.trim()
+	if (!value) return fallback
+	const parsed = Number(value)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -283,9 +311,66 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 	const agentIdEnum = delegateSchema(agentIds)
 
+	/**
+	 * Whether a launch can be made with nothing waiting on it.
+	 *
+	 * A background launch returns a task id and promises the result "later, as
+	 * a task notification". The only thing that keeps that promise is the
+	 * inbox: it is what holds the run open for an outstanding worker and what
+	 * puts the completion into the transcript. With no inbox the tool told the
+	 * model to expect a message on a channel that does not exist — measured,
+	 * and the launch itself succeeded, so nothing failed loudly either.
+	 *
+	 * Withheld rather than refused per call, and rather than thrown at
+	 * construction. Least functionality (NIST SP 800-53 Rev. 5 CM-7: provide
+	 * only mission-essential capabilities): a parameter the model is never
+	 * shown costs it nothing, where a parameter it is shown and then denied
+	 * costs prompt-prefix tokens plus an iteration per attempt. And a throw
+	 * would break a legitimate caller — an inbox-less coordinator surface is a
+	 * supported configuration whose blocking path is unaffected, pinned by a
+	 * test ("runs unchanged with no inbox at all"). That is the same reasoning
+	 * that made an empty roster WITHHOLD `create_task` rather than refuse to
+	 * build, and it is one parameter wide here for the same reason it was one
+	 * tool wide there.
+	 */
+	const canLaunchInBackground = completionInbox !== undefined
+
+	const backgroundClause = canLaunchInBackground
+		? " By default this BLOCKS and returns the agent's final output as this call's tool_result; pass background: true to get a task_id back immediately and receive the result later as a task notification."
+		: " This BLOCKS and returns the agent's final output as this call's tool_result."
+
+	/**
+	 * What to tell the model when a wait was cut short.
+	 *
+	 * The worker keeps going either way — giving up on a wait is a statement
+	 * about the waiter, not about the work. Where the result then turns up is
+	 * NOT the same either way, and the tool said it was: it promised a task
+	 * notification unconditionally, which without an inbox is a message on a
+	 * channel that does not exist. A model told to expect one waits for it,
+	 * and the one tool that could still reach the output is the one it was
+	 * told not to use for this.
+	 */
+	const whereTheResultWillTurnUp = (taskId: TaskId): string =>
+		completionInbox
+			? `its result will arrive separately as a task notification (task ${taskId}).`
+			: `it is still running as task ${taskId} — call wait_for_task with that id, or find it in agent_task_list once it finishes. Nothing will announce it on its own.`
+
+	/**
+	 * The listing's standing advice, which depends on there being an inbox.
+	 *
+	 * "Do not call this to find out whether work finished" is right when a
+	 * notification is coming. With no inbox an abandoned blocking launch has
+	 * no announcer at all, and this listing is the only way left to reach the
+	 * output — so the same sentence would send the model away from the one
+	 * tool that could help it.
+	 */
+	const listingAdvice = completionInbox
+		? "Do NOT call this to find out whether work finished: a blocking create_task has already returned each worker's output, and a backgrounded one arrives as a task notification. Use it when you need to see what is still running, or to re-read the output of a task whose launch you stopped waiting for."
+		: "A blocking create_task already returns each worker's output, so do not call this in a loop to find out whether work finished. Nothing announces a completion on this configuration, so this listing and wait_for_task are how you reach the output of a task whose launch you stopped waiting for."
+
 	const createTask = defineTool({
 		name: 'create_task',
-		description: `Launch a task on a specialized agent. By default this BLOCKS and returns the agent's final output as this call's tool_result; pass background: true to get a task_id back immediately and receive the result later as a task notification. 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. Do not race: until a worker's result reaches you, you know nothing about it — never fabricate, summarise or predict what it will say, in any form.`,
+		description: `Launch a task on a specialized agent.${backgroundClause} 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. Do not race: until a worker's result reaches you, you know nothing about it — never fabricate, summarise or predict what it will say, in any form.`,
 		inputSchema: z.object({
 			agent_id: agentIdEnum.describe('Which agent to run'),
 			prompt: z
@@ -300,12 +385,16 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				.describe(
 					'Existing planning task ID to link. If omitted, a planning task is auto-created.',
 				),
-			background: z
-				.boolean()
-				.optional()
-				.describe(
-					'Return immediately with a task_id instead of waiting. The result arrives later as a task notification. Use this when you have other work to do meanwhile; leave it off when the next thing you do depends on this answer.',
-				),
+			...(canLaunchInBackground
+				? {
+						background: z
+							.boolean()
+							.optional()
+							.describe(
+								'Return immediately with a task_id instead of waiting. The result arrives later as a task notification. Use this when you have other work to do meanwhile; leave it off when the next thing you do depends on this answer.',
+							),
+					}
+				: {}),
 		}),
 		category: 'custom',
 		permissions: [],
@@ -348,6 +437,34 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
 			})
 
+			// Whose task this is. The inbox ignores completions for anything it
+			// was not told about, because `onTaskCompleted` is a broadcast and a
+			// gateway shared between two supervisors would otherwise hand each
+			// of them the other's worker output. Said on BOTH paths: the
+			// blocking one needs it too, because the case the inbox exists for
+			// is exactly the blocking launch whose wait was abandoned.
+			completionInbox?.launched(handle.taskId)
+
+			// A background launch asked for with nowhere to deliver it is
+			// REFUSED, not quietly turned into a blocking one.
+			//
+			// The schema withholds the parameter and Zod strips what it does
+			// not declare, so this is unreachable through the model; it exists
+			// for a directly-constructed definition. Falling back to blocking
+			// would have been the tempting answer — the caller does get the
+			// output — but it is accepting work whose stated terms cannot be
+			// met, and the caller asked for a call that returns immediately.
+			// Naming the missing piece is the only response that tells them
+			// what to change.
+			if (background && !canLaunchInBackground) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'background: true needs a CompletionInbox — without one there is no channel for the notification this launch promises. Pass `completionInbox` to buildCoordinatorTools and the same instance to drainQuery, or omit `background` to wait for the result inline.',
+				}
+			}
+
 			if (background) {
 				// Tell the inbox to hold the run open for this. Without it the
 				// supervisor could launch a worker, answer, and settle the run
@@ -379,7 +496,23 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// assistant turn, the runtime runs them together and delivers all
 			// N `tool_result`s at once. No second `tool_result` for the
 			// same `tool_use_id` — providers reject a duplicated id outright.
-			const completed = await gateway.waitForTask(handle.taskId)
+			// Bounded by two clocks rather than one. The wait gives up on a
+			// worker that has gone quiet long before the hour is out, and says
+			// which of the two ran out — the caller acts on that difference.
+			// Giving up does NOT cancel the child: it keeps going, and its
+			// result still reaches the supervisor as a notification.
+			const outcome = await waitForTaskWithBounds(gateway, handle.taskId, {
+				runMs: DELEGATION_TIMEOUT_MS,
+				idleMs: DELEGATION_IDLE_MS,
+			})
+			if (outcome.kind === 'timeout') {
+				return {
+					success: false,
+					output: describeWaitTimeout(outcome),
+					data: { task_id: handle.taskId, agent_id, timed_out: outcome.cause },
+				}
+			}
+			const completed = outcome.handle
 
 			// Whether this call is still the live path decides who delivers the
 			// result. If the executor already gave up on us — its deadline
@@ -395,7 +528,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			if (_context.abortSignal?.aborted) {
 				return {
 					success: false,
-					output: `This wait was abandoned before ${agent_id} finished; its result will arrive separately as a task notification (task ${handle.taskId}).`,
+					output: `This wait was abandoned before ${agent_id} finished; ${whereTheResultWillTurnUp(handle.taskId)}`,
 					data: { task_id: handle.taskId, agent_id, abandoned: true },
 				}
 			}
@@ -450,55 +583,6 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	const continueTask = defineTool({
-		name: 'continue_task',
-		description:
-			"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'),
-			message: z.string().describe('Follow-up instruction for the agent'),
-		}),
-		category: 'custom',
-		permissions: [],
-		readOnly: false,
-		destructive: false,
-		concurrencySafe: true,
-		// It waits on a child exactly as create_task does, so it inherits
-		// the same bound rather than the file-read default.
-		timeoutMs: DELEGATION_TIMEOUT_MS,
-		async execute({ task_id, message }, _context) {
-			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)
-			// Same reasoning as create_task: the model already has a timeout
-			// for this call, so leaving the completion unclaimed is what sends
-			// it to the transcript as a notification.
-			if (_context.abortSignal?.aborted) {
-				return {
-					success: false,
-					output: `This wait was abandoned before task ${task_id} finished; its result will arrive separately as a task notification.`,
-					data: { task_id, abandoned: true },
-				}
-			}
-			completionInbox?.claim(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,
-				output: resultText,
-				data: { task_id, state: completed.state },
-			}
-		},
-	})
-
 	/**
 	 * Join a task already running, without sending it anything.
 	 *
@@ -533,11 +617,22 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const completed = await gateway.waitForTask(task_id as TaskId)
+			const outcome = await waitForTaskWithBounds(gateway, task_id as TaskId, {
+				runMs: DELEGATION_TIMEOUT_MS,
+				idleMs: DELEGATION_IDLE_MS,
+			})
+			if (outcome.kind === 'timeout') {
+				return {
+					success: false,
+					output: describeWaitTimeout(outcome),
+					data: { task_id, timed_out: outcome.cause },
+				}
+			}
+			const completed = outcome.handle
 			if (_context.abortSignal?.aborted) {
 				return {
 					success: false,
-					output: `This wait was abandoned before task ${task_id} finished; its result will arrive separately as a task notification.`,
+					output: `This wait was abandoned before task ${task_id} finished; ${whereTheResultWillTurnUp(task_id as TaskId)}`,
 					data: { task_id, abandoned: true },
 				}
 			}
@@ -598,8 +693,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 	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. Do NOT call this to find out whether work finished: a blocking create_task has already returned each worker's output, and a backgrounded one arrives as a task notification. Use it when you need to see what is still running, or to re-read the output of a task whose launch you stopped waiting for.",
+		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. ${listingAdvice}`,
 		inputSchema: z.object({
 			state: z
 				.enum(['pending', 'running', 'completed', 'failed', 'canceled'])
@@ -656,10 +750,29 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						// model cannot see, which is how this listing came to prove a
 						// task had finished while withholding what it said.
 						if (i.result === undefined) return head
-						const body =
-							i.result.length > LISTED_RESULT_LIMIT
-								? `${i.result.slice(0, LISTED_RESULT_LIMIT)}\n    … truncated; call wait_for_task with "${i.task_id}" for the whole thing.`
-								: i.result
+						const overLimit = i.result.length > LISTED_RESULT_LIMIT
+						// Framed exactly as the blocking `create_task` and
+						// `wait_for_task` frame the same bytes. This listing was the
+						// third way to read a delegate's output and the only one that
+						// pasted it bare — so a worker's text was material on two
+						// paths and read as the parent's own reasoning on the third,
+						// and which one a run got depended on how the model chose to
+						// fetch it.
+						const framed = wrapUntrusted(
+							{
+								kind: 'agent-result',
+								attributes: { agent: i.agent_id, task: i.task_id },
+								provenance: `This is the output of the delegated agent "${i.agent_id}", not this agent's own work.`,
+							},
+							overLimit ? i.result.slice(0, LISTED_RESULT_LIMIT) : i.result,
+						)
+						// After the closing tag, not inside it: this sentence is the
+						// kernel telling the model how to get the rest, and inside
+						// the envelope it has just been told the contents are not
+						// instructions addressed to it.
+						const body = overLimit
+							? `${framed}\n… truncated; call wait_for_task with "${i.task_id}" for the whole thing.`
+							: framed
 						return `${head}\n${body
 							.split('\n')
 							.map((line) => `    ${line}`)
@@ -675,18 +788,32 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `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
+	// `continue_task` is gone, and the reasoning is worth keeping because
+	// the obvious argument for bringing it back does not survive contact.
+	//
+	// It was dropped on the grounds that a blocking `create_task` leaves every
+	// worker terminal before a later turn learns its id, and the manager
+	// refuses `continue` on a terminal task. `background: true` reinstated that
+	// precondition — a live id is reachable now — so the question was reopened.
+	//
+	// Measured rather than assumed, and it fails on the other side. On a LIVE
+	// task the manager accepts the call and pushes onto `pendingMessages`,
+	// and NOTHING drains that queue during a run. This codebase already
+	// knows: `runtime/query/steering.ts` says in as many words that
+	// `queueMessage`/`drainMessages` were never read by the iteration loop,
+	// and `SteeringChannel` exists BECAUSE of that — it delivers guidance on a
+	// tool result instead, since a `tool_use` must be answered by a
+	// `tool_result` with the same id and there is no legal slot for a user
+	// message mid-batch.
+	//
+	// So the tool had no state it worked in: terminal tasks refuse it, live
+	// tasks accept it into a queue nobody reads. Registering it would have
+	// handed the model a call that silently does nothing — worse than the
+	// unregistered definition it replaced, because a defined-but-unreachable
+	// tool at least cannot be called.
+	//
+	// If follow-ups on a live worker are wanted, the work is a consumer for
+	// the queue or a steering channel that reaches a child, not this tool.
 	// `cancel_task` is registered again, and the reasoning that dropped it is
 	// worth keeping because it was sound at the time and is not any more.
 	//