@namzu/sdk 49.0.0 → 50.1.0

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.
  */

package/src/tools/coordinator/index.ts

@@ -3,7 +3,8 @@ import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js'
 import type { CompletionInbox } from '../../scheduler/completion-inbox.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
-import type { TaskScheduler } from '../../types/agent/scheduler.js'
+import type { TaskHandle, TaskScheduler } from '../../types/agent/scheduler.js'
+import { isTerminalAgentTaskState } from '../../types/agent/task.js'
 import type { ResumeHandler } from '../../types/hitl/index.js'
 import type { SessionId, TaskId, TurnId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
@@ -402,6 +403,29 @@ function delegatedAnswer(
 	return result?.result
 }
 
+/** Keep an empty answer from hiding the worker's error on any result path. */
+function delegatedResultText(completed: Pick<TaskHandle, 'state' | 'result'>): {
+	resultText: string
+	outputText: string
+} {
+	const success = taskSucceeded(completed)
+	const answer = delegatedAnswer(completed.result)
+	const lastError = completed.result?.lastError
+	const outcomeText = `Task finished with outcome: ${failureLabel(completed)}`
+	const resultText =
+		(answer?.trim() ? answer : lastError) ||
+		(success ? `Task finished with state: ${completed.state}` : outcomeText)
+	const outputText =
+		success || resultText === outcomeText
+			? resultText
+			: [
+					outcomeText,
+					...(lastError && lastError !== resultText ? [`Error: ${lastError}`] : []),
+					resultText,
+				].join('\n')
+	return { resultText, outputText }
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -451,6 +475,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	 * here. That is the same rule, not an exception to it.
 	 */
 	const launchedHere = new Set<TaskId>()
+	const trackedCompletions = new Map<TaskId, Promise<TaskHandle>>()
 	void opts.onTaskLaunched
 
 	const agentIdEnum = delegateSchema(agentIds)
@@ -573,10 +598,12 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// could report `failed` or stay `executing` forever but never
 			// `completed`.
 			const planStepId = plan_step_id
-			const planId = planStepId ? getPlanManager?.()?.active?.id : undefined
+			const planManager = planStepId ? getPlanManager?.() : undefined
+			const planId = planManager?.active?.id
 			const reportStep = (status: 'running' | 'completed' | 'failed', error?: string): void => {
-				if (!planStepId) return
-				getPlanManager?.()?.updateStepStatus(planStepId, status, error)
+				// A replacement plan may reuse step ids; it is not this worker's plan.
+				if (!planStepId || !planId || planManager?.active?.id !== planId) return
+				planManager.updateStepStatus(planStepId, status, error)
 			}
 			reportStep('running')
 
@@ -599,49 +626,6 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const handle = await gateway.createTask({
-				agentId: agent_id,
-				prompt,
-				workingDirectory: cwd,
-				runtimeContext: opts.runtimeContext,
-				...(planStepId ? { planStepId } : {}),
-				...(planId ? { planId } : {}),
-				// Hang the child session off THIS tool's span, so the delegation
-				// shows up inside the turn that asked for it.
-				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
-				// Same as the `Agent` tool: a delegate inherits the environment
-				// its parent was given, or it runs against different services
-				// than the turn that asked for the work — and the turn's screens,
-				// for the same reason: the child's executor installs the shipped
-				// default unless the spawn says otherwise, so a parent that
-				// turned them off had that decision revert behind every
-				// delegation. One merged `configOverrides`, because a second
-				// spread of the key would replace this one.
-				...(Object.keys(_context.env ?? {}).length > 0 || _context.toolResultGuardrails
-					? {
-							configOverrides: {
-								...(_context.env && Object.keys(_context.env).length > 0
-									? { env: _context.env }
-									: {}),
-								...(_context.toolResultGuardrails
-									? { toolResultGuardrails: _context.toolResultGuardrails }
-									: {}),
-							},
-						}
-					: {}),
-			})
-
-			// 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)
-
-			// ...and whose it is for the READ side too. See `launchedHere`.
-			launchedHere.add(handle.taskId)
-
 			// A background launch asked for with nowhere to deliver it is
 			// REFUSED, not quietly turned into a blocking one.
 			//
@@ -677,6 +661,111 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
+			let handle: TaskHandle
+			try {
+				handle = await gateway.createTask({
+					agentId: agent_id,
+					prompt,
+					workingDirectory: cwd,
+					runtimeContext: opts.runtimeContext,
+					...(planStepId ? { planStepId } : {}),
+					...(planId ? { planId } : {}),
+					// Hang the child session off THIS tool's span, so the delegation
+					// shows up inside the turn that asked for it.
+					...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
+					// Same as the `Agent` tool: a delegate inherits the environment
+					// its parent was given, or it runs against different services
+					// than the turn that asked for the work — and the turn's screens,
+					// for the same reason: the child's executor installs the shipped
+					// default unless the spawn says otherwise, so a parent that
+					// turned them off had that decision revert behind every
+					// delegation. One merged `configOverrides`, because a second
+					// spread of the key would replace this one.
+					...(Object.keys(_context.env ?? {}).length > 0 || _context.toolResultGuardrails
+						? {
+								configOverrides: {
+									...(_context.env && Object.keys(_context.env).length > 0
+										? { env: _context.env }
+										: {}),
+									...(_context.toolResultGuardrails
+										? { toolResultGuardrails: _context.toolResultGuardrails }
+										: {}),
+								},
+							}
+						: {}),
+				})
+			} catch (launchError) {
+				// No handle means admission failed from this caller's perspective.
+				// A host scheduler may have dispatched before losing its response;
+				// neither a missing worker nor a safe retry is established here.
+				const failure = `Delegation admission failed: ${toErrorMessage(launchError)}. No task handle was returned; the worker dispatch outcome is not established.`
+				reportStep('failed', failure)
+				if (resolvedPlanTaskId && taskStore) {
+					try {
+						const updated = await taskStore.update(asTaskId(resolvedPlanTaskId), {
+							status: 'failed',
+							description: failure,
+						})
+						if (!updated)
+							throw new Error(
+								`Planning task ${resolvedPlanTaskId} disappeared during failed admission`,
+							)
+					} catch (trackingError) {
+						throw new AggregateError(
+							[launchError, trackingError],
+							`${failure} Planning settlement failed: ${toErrorMessage(trackingError)}`,
+							{ cause: launchError },
+						)
+					}
+				}
+				throw launchError
+			}
+
+			// 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)
+
+			// ...and whose it is for the READ side too. See `launchedHere`.
+			launchedHere.add(handle.taskId)
+
+			// Own one completion for both delivery paths. Neither a background
+			// return nor an abandoned bounded wait discards these tracking writes.
+			if ((resolvedPlanTaskId && taskStore) || (planStepId && planId)) {
+				// A fast worker may already be terminal and forgotten by the gateway.
+				// The returned handle is the exact outcome; do not fetch it again.
+				const workerCompletion = isTerminalAgentTaskState(handle.state)
+					? Promise.resolve(handle)
+					: gateway.waitForTask(handle.taskId)
+				const completion = workerCompletion.then(async (completed) => {
+					const success = taskSucceeded(completed)
+					const { outputText } = delegatedResultText(completed)
+					if (resolvedPlanTaskId && taskStore) {
+						const updated = await taskStore.update(asTaskId(resolvedPlanTaskId), {
+							status: success ? 'completed' : 'failed',
+							description: success ? undefined : `Failed: ${outputText.substring(0, 200)}`,
+						})
+						if (!updated)
+							throw new Error(
+								`Planning task ${resolvedPlanTaskId} disappeared before worker settlement`,
+							)
+					}
+					reportStep(
+						success ? 'completed' : 'failed',
+						success ? undefined : outputText.slice(0, 200),
+					)
+					return completed
+				})
+				trackedCompletions.set(handle.taskId, completion)
+				completionInbox?.deferDelivery(
+					handle.taskId,
+					completion.then(() => {}),
+				)
+			}
+
 			if (background) {
 				// Tell the inbox to hold the turn open for this. Without it the
 				// supervisor could launch a worker, answer, and settle the turn
@@ -716,6 +805,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			const outcome = await waitForTaskWithBounds(gateway, handle.taskId, {
 				wallMs: DELEGATION_TIMEOUT_MS,
 				idleMs: DELEGATION_IDLE_MS,
+				completion: trackedCompletions.get(handle.taskId),
 			})
 			if (outcome.kind === 'timeout') {
 				return {
@@ -752,27 +842,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// `isError: false`, while writing the plan task closed as though
 			// the work had been done.
 			const success = taskSucceeded(completed)
-			const resultText =
-				delegatedAnswer(completed.result) ??
-				completed.result?.lastError ??
-				`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(asTaskId(resolvedPlanTaskId), {
-					status: success ? 'completed' : 'failed',
-					description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
-				})
-			}
-
-			// The step reports the same outcome, from the same two authorities.
-			// This is the only point in a delegated launch where the answer is
-			// actually known.
-			reportStep(success ? 'completed' : 'failed', success ? undefined : resultText.slice(0, 200))
+			const { resultText, outputText } = delegatedResultText(completed)
 
 			return {
 				success,
@@ -797,7 +867,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						attributes: { agent: agent_id, task: handle.taskId },
 						provenance: `This is the output of the delegated agent "${agent_id}", not this agent's own work.`,
 					},
-					resultText,
+					outputText,
 				),
 				data: {
 					task_id: handle.taskId,
@@ -870,6 +940,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			const outcome = await waitForTaskWithBounds(gateway, taskId, {
 				wallMs: DELEGATION_TIMEOUT_MS,
 				idleMs: DELEGATION_IDLE_MS,
+				completion: trackedCompletions.get(taskId),
 			})
 			if (outcome.kind === 'timeout') {
 				return {
@@ -888,11 +959,11 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			}
 			completionInbox?.claim(taskId)
 
-			const success = completed.state === 'completed'
-			const resultText =
-				delegatedAnswer(completed.result) ??
-				completed.result?.lastError ??
-				`Task finished with state: ${completed.state}`
+			// Finishing the invocation does not prove the worker succeeded. Use
+			// the same two-authority check as the call that launched this task.
+			const success = taskSucceeded(completed)
+			const lastError = completed.result?.lastError
+			const { resultText, outputText } = delegatedResultText(completed)
 			return {
 				success,
 				output: wrapUntrusted(
@@ -901,12 +972,16 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						attributes: { agent: completed.agentId, task: completed.taskId },
 						provenance: `This is the output of the delegated agent "${completed.agentId}", not this agent's own work.`,
 					},
-					resultText,
+					outputText,
 				),
 				data: {
 					task_id,
 					agent_id: completed.agentId,
 					state: completed.state,
+					...(completed.result?.status === undefined
+						? {}
+						: { turn_status: completed.result.status }),
+					...(lastError === undefined || lastError === null ? {} : { last_error: lastError }),
 					result: resultText,
 				},
 			}

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

@@ -47,6 +47,8 @@ export interface WaitBounds {
 	 * Omit to bound by the turn clock alone.
 	 */
 	readonly idleMs?: number
+	/** Reuse the launch's completion, including its tracking settlement. */
+	readonly completion?: Promise<TaskHandle>
 }
 
 /**
@@ -77,7 +79,7 @@ export async function waitForTaskWithBounds(
 	const idleBoundArmed = detach !== undefined && bounds.idleMs !== undefined
 
 	try {
-		const completion = gateway.waitForTask(taskId).then(
+		const completion = (bounds.completion ?? gateway.waitForTask(taskId)).then(
 			(handle): WaitOutcome => ({ kind: 'completed', handle }),
 			// A gateway that rejects has answered the question; let it through
 			// rather than reporting a timeout that did not happen.

package/src/tools/defineTool.ts

@@ -7,6 +7,7 @@ import type {
 } from '../types/tool/index.js'
 import type { ToolPresentation } from '../types/tool/presentation.js'
 import { toErrorMessage } from '../utils/error.js'
+import { failureFactsFromError } from './failure-facts.js'
 
 export interface DefineToolOptions<S extends z.ZodType> {
 	name: string
@@ -183,10 +184,13 @@ export function defineTool<S extends z.ZodType>(
 				return await options.execute(input, context)
 			} catch (err) {
 				const message = toErrorMessage(err)
+				const facts = failureFactsFromError(err)
 				return {
 					success: false,
 					output: '',
 					error: `${options.name} failed: ${message}`,
+					// The kind of failure, from the error's own code, for the person's view.
+					...(facts ? { facts } : {}),
 				}
 			}
 		},

package/src/tools/failure-facts.ts

@@ -0,0 +1,24 @@
+import type { ToolFacts } from '../types/tool/presentation.js'
+
+/**
+ * The kind of failure a thrown filesystem error is, as typed facts for the
+ * person's view. Read from the error's `code` and `path`, which Node sets
+ * structurally, and never from its message.
+ */
+export function failureFactsFromError(err: unknown): ToolFacts | undefined {
+	if (!err || typeof err !== 'object') return undefined
+	const { code, path } = err as { code?: unknown; path?: unknown }
+	const subject = typeof path === 'string' ? path : undefined
+	const reason =
+		code === 'ENOENT'
+			? 'not_found'
+			: code === 'EACCES' || code === 'EPERM'
+				? 'permission_denied'
+				: code === 'EISDIR' || code === 'ENOTDIR'
+					? 'not_a_file'
+					: code === 'EEXIST'
+						? 'already_exists'
+						: undefined
+	if (!reason) return undefined
+	return { kind: 'failure', reason, ...(subject ? { subject } : {}) }
+}