@namzu/sdk 48.3.1 → 50.0.0

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -1,4 +1,5 @@
 import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 
 /**
  * Waiting on a background job, bounded by two different questions — the
@@ -42,6 +43,8 @@ interface JobWaitProgress {
 	readonly output: string
 	readonly nextOffset: number
 	readonly droppedBytes: number
+	/** Earlier bytes omitted from this wait's own bounded output, separately from registry loss. */
+	readonly omittedOutputBytes: number
 }
 
 export type JobWaitOutcome =
@@ -49,6 +52,8 @@ export type JobWaitOutcome =
 			readonly kind: 'exited'
 			readonly status: string
 			readonly exitCode?: number
+			/** Why the command never started, when it could not. */
+			readonly error?: string
 	  } & JobWaitProgress)
 	| ({
 			readonly kind: 'timeout'
@@ -67,12 +72,27 @@ export type JobWaitOutcome =
  */
 const POLL_INTERVAL_MS = 1_000
 
+/** Leave room for the status and recovery instructions inside the tool-result budget. */
+const MAX_WAIT_OUTPUT_BYTES = 32 * 1024
+
+function boundedTail(value: string): { output: string; omittedBytes: number } {
+	const bytes = Buffer.from(value, 'utf8')
+	if (bytes.length <= MAX_WAIT_OUTPUT_BYTES) return { output: value, omittedBytes: 0 }
+	let start = bytes.length - MAX_WAIT_OUTPUT_BYTES
+	// The cap is in bytes, but the displayed tail must begin at a UTF-8 character.
+	while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start++
+	return {
+		output: bytes.subarray(start).toString('utf8'),
+		omittedBytes: start,
+	}
+}
+
 /**
- * Await a job under both bounds, accumulating its output as it goes.
+ * Await a job under both bounds, retaining a bounded tail as it goes.
  *
- * Returns the output gathered so far either way: a completed wait has all
- * of it, and a timed-out one has everything read up to the moment it gave
- * up, so the caller never has to throw away a partial answer.
+ * A completed or timed-out wait returns the bytes it observed up to its
+ * absolute cursor. If the displayed tail could not hold all of them, its
+ * omitted-byte count keeps that gap visible to the caller.
  */
 export async function waitForJobWithBounds(
 	jobs: Pick<BackgroundJobRegistryRef, 'read' | 'waitForExit'>,
@@ -90,8 +110,16 @@ export async function waitForJobWithBounds(
 	let cursor = options.fromOffset ?? 0
 	let output = ''
 	let droppedBytes = 0
+	let omittedOutputBytes = 0
 	let settled = false
 	let poll: ReturnType<typeof setInterval> | undefined
+	// Each bounded wait owns its exit subscription. A timeout must release that
+	// subscription even when the job itself runs forever.
+	const waitAbort = new AbortController()
+	const forwardAbort = (): void => waitAbort.abort(options.signal?.reason)
+	let disposeCallerAbort = () => {}
+	if (options.signal?.aborted) forwardAbort()
+	else if (options.signal) disposeCallerAbort = subscribeToAbort(options.signal, forwardAbort)
 
 	/** Read whatever is new since `cursor`, and count it as progress if it is. */
 	const drain = (): void => {
@@ -99,11 +127,15 @@ export async function waitForJobWithBounds(
 		if (chunk.droppedBytes > 0) droppedBytes += chunk.droppedBytes
 		if (chunk.nextOffset > cursor) lastProgressAt = now()
 		cursor = chunk.nextOffset
-		if (chunk.chunk) output += chunk.chunk
+		if (chunk.chunk) {
+			const bounded = boundedTail(output + chunk.chunk)
+			output = bounded.output
+			omittedOutputBytes += bounded.omittedBytes
+		}
 	}
 
 	try {
-		const exited = waitForExit(id, { signal: options.signal }).then((job): JobWaitOutcome => {
+		const exited = waitForExit(id, { signal: waitAbort.signal }).then((job): JobWaitOutcome => {
 			// One last read: the job can exit between ticks, and the bytes
 			// it wrote in its final moment are exactly the ones a caller
 			// most wants — the error, the summary line, the exit trace.
@@ -112,9 +144,11 @@ export async function waitForJobWithBounds(
 				kind: 'exited',
 				status: job.status,
 				...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+				...(job.error === undefined ? {} : { error: job.error }),
 				output,
 				nextOffset: cursor,
 				droppedBytes,
+				omittedOutputBytes,
 			}
 		})
 
@@ -136,6 +170,7 @@ export async function waitForJobWithBounds(
 						output,
 						nextOffset: cursor,
 						droppedBytes,
+						omittedOutputBytes,
 					})
 					return
 				}
@@ -150,6 +185,7 @@ export async function waitForJobWithBounds(
 							output,
 							nextOffset: cursor,
 							droppedBytes,
+							omittedOutputBytes,
 						})
 					}
 				}
@@ -165,6 +201,8 @@ export async function waitForJobWithBounds(
 	} finally {
 		settled = true
 		if (poll !== undefined) clearInterval(poll)
+		disposeCallerAbort()
+		waitAbort.abort(new Error('Job wait finished'))
 	}
 }
 
@@ -174,7 +212,7 @@ export function describeJobWaitTimeout(
 	outcome: Extract<JobWaitOutcome, { kind: 'timeout' }>,
 ): string {
 	const seconds = Math.round(outcome.elapsedMs / 1000)
-	const resume = `call wait_for_job again, or job read with from_offset ${outcome.nextOffset}, to see what it does next`
+	const resume = `call wait_for_job or job read with from_offset ${outcome.nextOffset} to see only what comes next`
 	if (outcome.cause === 'idle') {
 		return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`
 	}

package/src/tools/builtins/wait-for-job.ts

@@ -33,34 +33,69 @@ const DEFAULT_IDLE_TIMEOUT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_IDLE_MS', 2 *
  */
 const MAX_WAIT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_MAX_MS', 60 * 60 * 1000)
 
-const inputSchema = z.object({
-	id: z.string().describe('The job id, as returned by bash with run_in_background.'),
-	timeout_ms: z
-		.number()
-		.int()
-		.positive()
-		.max(MAX_WAIT_MS)
-		.optional()
-		.describe(
-			`Give up after this long even if the job keeps producing output, in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}, maximum: ${MAX_WAIT_MS}. The job is never stopped by this running out.`,
-		),
-	idle_timeout_ms: z
-		.number()
-		.int()
-		.positive()
-		.max(MAX_WAIT_MS)
-		.optional()
-		.describe(
-			`Give up if the job produces no new output for this long, in milliseconds. Default: ${DEFAULT_IDLE_TIMEOUT_MS}. Resets on every new byte of output, so a job that is still working is not cut off; only real silence ends the wait early.`,
-		),
-})
+const inputSchema = z
+	.object({
+		id: z.string().describe('The job id, as returned by bash with run_in_background.'),
+		output_contains: z
+			.string()
+			.min(1)
+			.max(4096)
+			.refine(
+				(value) =>
+					Buffer.byteLength(value) <= 4096 && Buffer.from(value).toString('utf8') === value,
+				'Use a non-empty UTF-8 literal of at most 4096 bytes.',
+			)
+			.optional()
+			.describe(
+				'Wait for this exact literal in output rather than for exit. This observes a marker; it does not prove service health or keep the turn open until the job exits.',
+			),
+		output_stream: z
+			.enum(['stdout', 'stderr', 'either'])
+			.optional()
+			.describe(
+				'Pipe to inspect with output_contains. Default either; stdout and stderr are never joined for a match.',
+			),
+		from_offset: z
+			.number()
+			.int()
+			.nonnegative()
+			.optional()
+			.describe('Resume after a previous wait: pass its next_offset to receive only new output.'),
+		timeout_ms: z
+			.number()
+			.int()
+			.positive()
+			.max(MAX_WAIT_MS)
+			.optional()
+			.describe(
+				`Give up after this long even if the job keeps producing output, in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}, maximum: ${MAX_WAIT_MS}. The job is never stopped by this running out.`,
+			),
+		idle_timeout_ms: z
+			.number()
+			.int()
+			.positive()
+			.max(MAX_WAIT_MS)
+			.optional()
+			.describe(
+				`Give up if the job produces no new output for this long, in milliseconds. Default: ${DEFAULT_IDLE_TIMEOUT_MS}. Resets on every new byte of output, so a job that is still working is not cut off; only real silence ends the wait early.`,
+			),
+	})
+	.superRefine((input, ctx) => {
+		if (input.output_stream !== undefined && input.output_contains === undefined) {
+			ctx.addIssue({
+				code: 'custom',
+				path: ['output_stream'],
+				message: 'output_stream requires output_contains.',
+			})
+		}
+	})
 
 type WaitForJobInput = z.infer<typeof inputSchema>
 
 export const WaitForJobTool = defineTool({
 	name: 'wait_for_job',
 	description:
-		'Block until a background job started by bash with run_in_background ends, and return its accumulated output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. Gives up — WITHOUT stopping the job — if it runs too long or goes quiet for too long; either outcome says so, and the job keeps running either way.',
+		'Wait for an owned background job to exit, or set output_contains to observe an exact output marker while it stays running. Use one wait instead of polling job read. Output markers do not prove service health or completion and never express intent to wait until exit. A bounded wait returns output and next_offset without stopping the job; pass that cursor as from_offset to exclude earlier output.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
@@ -82,7 +117,7 @@ export const WaitForJobTool = defineTool({
 		return {
 			kind: 'generic',
 			presentation: 'activity',
-			label: `Wait for background job · ${input.id ?? '(missing id)'}`,
+			label: `${input.output_contains === undefined ? 'Wait for background job' : 'Wait for job output'} · ${input.id ?? '(missing id)'}`,
 		}
 	},
 
@@ -106,6 +141,83 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		if (input.output_stream !== undefined && input.output_contains === undefined) {
+			return { success: false, output: '', error: 'output_stream requires output_contains.' }
+		}
+		if (input.output_contains !== undefined) {
+			if (!jobs.waitForOutput) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'This host cannot observe output readiness. It must implement backgroundJobs.waitForOutput; no exit wait was started.',
+				}
+			}
+			try {
+				const outcome = await jobs.waitForOutput(input.id, {
+					literal: input.output_contains,
+					stream: input.output_stream ?? 'either',
+					timeoutMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+					idleTimeoutMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+					...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
+					signal: context.abortSignal,
+				})
+				const notices = [
+					...(outcome.droppedBytes > 0
+						? [`[${outcome.droppedBytes} bytes unavailable before the retained output]`]
+						: []),
+					...(outcome.unsearchedBytes > 0
+						? [
+								`[${outcome.unsearchedBytes} retained bytes could not be searched because the channel history cap discarded them]`,
+							]
+						: []),
+					...(outcome.omittedOutputBytes > 0
+						? [`[${outcome.omittedOutputBytes} earlier bytes omitted from this bounded result]`]
+						: []),
+				]
+				const status =
+					outcome.error !== undefined
+						? `failed to start: ${outcome.error}`
+						: outcome.exitCode === undefined
+							? outcome.status
+							: `${outcome.status} with code ${outcome.exitCode}`
+				const reason =
+					outcome.kind === 'matched'
+						? `Output marker observed on ${outcome.matchedStream}. This is output evidence, not a health check or completion claim.`
+						: outcome.kind === 'exited'
+							? 'Job exited before the marker was observed.'
+							: outcome.kind === 'stopped'
+								? 'Job stop was requested before the marker was observed; shutdown may still be completing.'
+								: outcome.kind === 'aborted'
+									? 'Output observation was cancelled; this wait did not stop the job.'
+									: `Output marker was not observed before the ${outcome.cause} timeout (${outcome.elapsedMs} ms); this wait did not stop the job.`
+				return {
+					success: outcome.kind !== 'aborted',
+					output: `${reason}\n\n${notices.length > 0 ? `${notices.join('\n')}\n` : ''}${outcome.output || '(no new output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+					data: {
+						jobId: input.id,
+						outcome: outcome.kind,
+						status: outcome.status,
+						nextOffset: outcome.nextOffset,
+						droppedBytes: outcome.droppedBytes,
+						unsearchedBytes: outcome.unsearchedBytes,
+						omittedOutputBytes: outcome.omittedOutputBytes,
+						...(outcome.kind === 'matched' ? { matchedStream: outcome.matchedStream } : {}),
+						...(outcome.kind === 'timeout' ? { timedOut: outcome.cause } : {}),
+						...(outcome.kind === 'aborted' ? { abandoned: true } : {}),
+						...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
+						...(outcome.error === undefined ? {} : { error: outcome.error }),
+					},
+				}
+			} catch (err) {
+				return {
+					success: false,
+					output: '',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+		}
+
 		if (!jobs.waitForExit) {
 			return {
 				success: false,
@@ -128,6 +240,7 @@ export const WaitForJobTool = defineTool({
 			outcome = await waitForJobWithBounds(jobs, input.id, {
 				wallMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
 				idleMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+				...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
 				signal: context.abortSignal,
 			})
 		} catch {
@@ -144,40 +257,50 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		const notices = [
+			...(outcome.droppedBytes > 0
+				? [`[${outcome.droppedBytes} bytes were dropped by the job's output retention cap]`]
+				: []),
+			...(outcome.omittedOutputBytes > 0
+				? [`[${outcome.omittedOutputBytes} earlier bytes omitted from this bounded wait result]`]
+				: []),
+		]
+		const observed = `${notices.length > 0 ? `${notices.join('\n')}\n` : ''}${outcome.output || '(no new output)'}`
+
 		if (outcome.kind === 'timeout') {
 			return {
-				success: false,
-				output: describeJobWaitTimeout(input.id, outcome),
+				// The wait observed a bound, not a failed command. A tool error
+				// would also be promoted as a durable failure by the turn's memory.
+				success: true,
+				output: `${describeJobWaitTimeout(input.id, outcome)}\n\n${observed}\n\n[next_offset ${outcome.nextOffset}]`,
 				data: {
 					jobId: input.id,
 					timedOut: outcome.cause,
 					nextOffset: outcome.nextOffset,
 					droppedBytes: outcome.droppedBytes,
+					omittedOutputBytes: outcome.omittedOutputBytes,
 				},
 			}
 		}
 
-		// The dropped count is stated, never absorbed — same rule `job read`
-		// follows, for the same reason: a job whose middle vanished quietly
-		// reads as a complete result that happens to be short.
-		const notice =
-			outcome.droppedBytes > 0
-				? `[${outcome.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
-				: ''
 		const status =
-			outcome.exitCode === undefined
-				? outcome.status
-				: `${outcome.status} with code ${outcome.exitCode}`
+			outcome.error !== undefined
+				? `failed to start: ${outcome.error}`
+				: outcome.exitCode === undefined
+					? outcome.status
+					: `${outcome.status} with code ${outcome.exitCode}`
 
 		return {
 			success: true,
-			output: `${notice}${outcome.output || '(no output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+			output: `${observed}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
 			data: {
 				jobId: input.id,
 				status: outcome.status,
 				nextOffset: outcome.nextOffset,
 				droppedBytes: outcome.droppedBytes,
+				omittedOutputBytes: outcome.omittedOutputBytes,
 				...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
+				...(outcome.error === undefined ? {} : { error: outcome.error }),
 			},
 		}
 	},

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

@@ -2,6 +2,7 @@ import { mkdir, readFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext, ToolResult } from '../../types/tool/index.js'
+import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
@@ -196,13 +197,14 @@ export const WriteFileTool = defineTool({
 function enforceReadBeforeOverwrite(
 	context: ToolContext,
 	key: string,
-): { success: false; output: ''; error: string } | null {
+): { success: false; output: ''; error: string; facts?: ToolFacts } | null {
 	if (!context.fileReadTracker) return null
 	if (context.fileReadTracker.hasRead(key)) return null
 	return {
 		success: false,
 		output: '',
 		error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
+		facts: { kind: 'failure', reason: 'already_exists', subject: key },
 	}
 }
 
@@ -210,7 +212,7 @@ function enforceFreshOverwrite(
 	context: ToolContext,
 	key: string,
 	currentContent: string,
-): { success: false; output: ''; error: string } | null {
+): { success: false; output: ''; error: string; facts?: ToolFacts } | null {
 	const unread = enforceReadBeforeOverwrite(context, key)
 	if (unread) return unread
 

package/src/tools/command-shell.ts

@@ -34,7 +34,8 @@
  * `NAMZU_BASH_SHELL=/bin/sh` restores the old shell exactly.
  */
 
-import { constants, accessSync } from 'node:fs'
+import { type ChildProcess, type SpawnOptions, spawn as nodeSpawn } from 'node:child_process'
+import { constants, accessSync, existsSync } from 'node:fs'
 import { delimiter, isAbsolute, join } from 'node:path'
 
 import type { ShellDialect } from '../types/tool/index.js'
@@ -67,12 +68,19 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 	if (override !== undefined && override !== '') {
 		// Read as bash only when it is bash; anything else gets the reading
 		// that holds for every POSIX shell.
-		const name = override.slice(override.lastIndexOf('/') + 1)
+		const name =
+			probe.platform === 'win32'
+				? override
+						.split(/[\\/]/)
+						.at(-1)
+						?.toLowerCase()
+						.replace(/\.exe$/, '')
+				: override.slice(override.lastIndexOf('/') + 1)
 		return { path: override, dialect: name === 'bash' ? 'bash' : 'sh', source: 'override' }
 	}
 	// Windows keeps Node's platform shell. Looking `bash` up on its PATH can
 	// find WSL's launcher, which runs the command in another system.
-	if (probe.platform === 'win32') return { path: undefined, dialect: 'sh', source: 'platform' }
+	if (probe.platform === 'win32') return { path: undefined, dialect: 'cmd', source: 'platform' }
 	for (const directory of (probe.env.PATH ?? '').split(delimiter)) {
 		if (directory === '' || !directory.startsWith('/')) continue
 		const candidate = join(directory, 'bash')
@@ -94,7 +102,7 @@ export function findCommandShell(probe: CommandShellProbe): CommandShell {
 export function findCommandShellForDialect(
 	dialect: 'bash' | 'sh',
 	probe: CommandShellProbe,
-): CommandShell | undefined {
+): (CommandShell & { readonly dialect: 'bash' | 'sh' }) | undefined {
 	if (probe.platform === 'win32') return undefined
 	const override = probe.env.NAMZU_BASH_SHELL
 	if (override) {
@@ -142,7 +150,9 @@ export function hostCommandShell(): CommandShell {
 }
 
 /** Re-check the requested executable each time a job is confirmed or fired. */
-export function installedCommandShellForDialect(dialect: 'bash' | 'sh'): CommandShell | undefined {
+export function installedCommandShellForDialect(
+	dialect: 'bash' | 'sh',
+): (CommandShell & { readonly dialect: 'bash' | 'sh' }) | undefined {
 	return findCommandShellForDialect(dialect, {
 		env: process.env,
 		platform: process.platform,
@@ -173,6 +183,123 @@ export function hostShellSpawn(
 	return { file: shell.path, args: ['-c', command], env: withoutBashStartup(env) }
 }
 
+/** Why a command could not be started, in the words a model or operator reads. */
+export function describeSpawnFailure(error: unknown, cwd?: string): string {
+	// Node reports a missing working directory as ENOENT on the shell's own
+	// path ("spawn C:\Windows\system32\cmd.exe ENOENT"), which sends the reader
+	// looking for a missing shell. Say what is actually missing.
+	if (
+		cwd !== undefined &&
+		(error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT' &&
+		!existsSync(cwd)
+	) {
+		return `Could not start the command: the working directory does not exist: ${cwd}`
+	}
+	const detail = error instanceof Error ? error.message : String(error)
+	return `Could not start the command: ${detail}`
+}
+
+/** Environment variable that carries the command line into the inner cmd. */
+const WINDOWS_COMMAND_VARIABLE = 'NAMZU_HOST_COMMAND'
+const WINDOWS_SHELL_VARIABLE = 'NAMZU_HOST_COMSPEC'
+
+/**
+ * The spawn for one command line under cmd on Windows: the outer cmd's file,
+ * its arguments and the environment that carries the command.
+ *
+ * A bare `cmd /d /s /c <command>` converts the command line to the console's
+ * OEM code page before it runs anything, so letters that page lacks arrive
+ * as their nearest ASCII look-alike (g-breve as `g`, s-cedilla as `s` on
+ * CP850) and are gone before the command writes a byte. `chcp` inside the
+ * same line is too late: the line is already converted. So the outer cmd
+ * only switches the console to UTF-8 and starts a second cmd, and the
+ * command travels in the environment, which is Unicode and never converted.
+ * The outer cmd reads it with delayed expansion (`!NAME!`), which happens
+ * after its line is parsed, so quotes, `&`, `|` and `>` in the command are
+ * inert there and reach the second cmd as the line it was given: quoting,
+ * `%` and redirection mean what they meant before, and its exit code is the
+ * command's. Neither cmd is looked up on PATH, so a `cmd.exe` in the
+ * working directory is never picked up.
+ */
+function windowsCmdSpawn(
+	command: string,
+	env: NodeJS.ProcessEnv,
+): {
+	readonly file: string
+	readonly args: readonly string[]
+	readonly env: NodeJS.ProcessEnv
+} {
+	const lookup = (name: string): string | undefined => {
+		const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase())
+		return key === undefined ? undefined : env[key]
+	}
+	const comspec =
+		lookup('ComSpec') ??
+		`${lookup('SystemRoot') ?? process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\cmd.exe`
+	return {
+		file: comspec,
+		// Passed verbatim: Node must not re-quote the line, whose outer quotes
+		// `/s` strips.
+		args: [
+			'/d',
+			'/v:on',
+			'/s',
+			'/c',
+			`"chcp 65001>nul & "!${WINDOWS_SHELL_VARIABLE}!" /d /s /c "!${WINDOWS_COMMAND_VARIABLE}!""`,
+		],
+		env: { ...env, [WINDOWS_SHELL_VARIABLE]: comspec, [WINDOWS_COMMAND_VARIABLE]: command },
+	}
+}
+
+/**
+ * Start one command on the host, in the shell {@link hostCommandShell} chose.
+ *
+ * The ONE place that knows what Windows needs: with no shell path (cmd), Node
+ * itself must run the line (`cmd.exe /d /s /c`, see `windowsCmdSpawn`);
+ * everywhere else it is `<shell> -c <command>`. The foreground `bash` tool,
+ * the background job registry and plugin hooks all spawn through here, so
+ * they cannot diverge: the registry once spawned `/bin/sh` on Windows while
+ * the foreground tool did not, and every background job died at once with no
+ * message.
+ *
+ * - On Windows the line runs under UTF-8 (see `windowsCmdSpawn`).
+ * - `detached` (own process group, for `killTree`) is POSIX only; on Windows
+ *   it opens a new console window instead.
+ * - `windowsHide` keeps a GUI host from flashing a console per command.
+ */
+export function spawnHostShell(
+	command: string,
+	options: {
+		readonly cwd: string
+		readonly env: NodeJS.ProcessEnv
+		readonly stdio?: SpawnOptions['stdio']
+		/** Default: true off Windows. */
+		readonly detached?: boolean
+		readonly shell?: CommandShell
+		/** For tests: the platform the options are shaped for. */
+		readonly platform?: NodeJS.Platform
+		/** For tests: the spawn that runs it. */
+		readonly spawnImpl?: typeof nodeSpawn
+	},
+): ChildProcess {
+	const spawnFn = options.spawnImpl ?? nodeSpawn
+	const resolved = hostShellSpawn(command, options.env, options.shell)
+	const common: SpawnOptions = {
+		cwd: options.cwd,
+		env: resolved.env,
+		detached: options.detached ?? (options.platform ?? process.platform) !== 'win32',
+		windowsHide: true,
+		...(options.stdio === undefined ? {} : { stdio: options.stdio }),
+	}
+	if (resolved.file !== undefined) return spawnFn(resolved.file, [...resolved.args], common)
+	const windows = windowsCmdSpawn(command, resolved.env)
+	return spawnFn(windows.file, [...windows.args], {
+		...common,
+		env: windows.env,
+		windowsVerbatimArguments: true,
+	})
+}
+
 export function withoutBashStartup<T extends Readonly<Record<string, string | undefined>>>(
 	env: T,
 ): T {

package/src/tools/coordinator/agent.ts

@@ -21,26 +21,16 @@ import type { TaskLaunchedCallback } from './index.js'
  * subagent tool calls are isolated — only the summary surfaces to
  * the parent.
  *
- * **How this relates to `create_task`.** This paragraph used to say the two
- * were different shapes — that `create_task` / `continue_task` /
- * `cancel_task` were a non-blocking trio driven by a `<task-notification>`
- * callback, and that the blocking `Agent` tool should be preferred. None of
- * that is true any more. `create_task` blocks and returns the worker's output
- * as its own `tool_result`, exactly like this tool; `continue_task` and
- * `cancel_task` are still defined in `./index.ts` but are deliberately not
- * registered, because a blocking launch leaves every worker terminal by the
- * time a later turn learns its id. So a reader following the old advice was
- * choosing between two tools on a distinction that no longer existed.
+ * `create_task` also returns the worker result inline by default. When a
+ * CompletionInbox is supplied it can instead launch in the background;
+ * `wait_for_task`, `continue_task` and `cancel_task` let the supervisor join,
+ * steer or stop its own launched work. Linked planning tasks and approved
+ * plan steps settle from the worker's actual outcome on either launch path.
  *
- * What actually separates them is the surface, not the timing:
- *
- * - `create_task` arrives with the rest of the coordinator surface —
- *   `agent_task_list`, and `approve_plan` / `ask_user_question` when their
- *   dependencies are wired. That is the supervisor's toolkit.
- * - This builds one tool and nothing else, for an agent whose only delegation
- *   need is "hand this to a specialist". `terminal: true` additionally lets a
- *   pure router settle on the specialist's answer instead of spending a turn
- *   at full parent context to paraphrase it.
+ * `create_task` arrives with the coordinator toolkit, including task listing
+ * and optional plan approval/question tools. This builds one delegation tool.
+ * `terminal: true` additionally lets a pure router settle on the specialist's
+ * answer instead of spending a turn restating it.
  *
  * Neither is legacy. Pick by how much of the coordinator surface you want.
  */