@namzu/sdk 49.0.0 → 50.0.0

package/src/tools/schedules/schedule-tool.ts

@@ -54,6 +54,12 @@ const inputSchema = z.object({
 			body: z.string().min(1).describe('The exact script text, run verbatim once confirmed'),
 			shell: z.enum(['bash', 'sh']).describe('Which shell reads it; no default'),
 			timeoutMs: z.number().int().positive().optional().describe('The script’s own wall clock'),
+			report: z
+				.literal('json-v1')
+				.optional()
+				.describe(
+					'Pure script only: stdout must be exactly one JSON object line, {"v":1,"state":"quiet"} or {"v":1,"state":"changed","summary":"..."}, with optional nextState. Quiet runs report no result; changed runs deliver the summary. The scheduler owns nextState. Omit for ordinary stdout.',
+				),
 		})
 		.optional()
 		.describe(
@@ -75,7 +81,13 @@ const inputSchema = z.object({
 		.string()
 		.optional()
 		.describe(
-			"create: existing working directory for the job; leave unset for the session's folder when valid. The file system root, the operator's home directory, NAMZU_HOME and a folder containing NAMZU_HOME are refused. If this session is in one of those, choose an existing project subfolder and set folder explicitly",
+			"create/update: existing project directory for the job; leave unset to use this session's project folder. Root, the operator's home directory, NAMZU_HOME and a folder containing NAMZU_HOME are refused. For a project-free pure script use workspace: 'none' and omit folder; do not make a visible folder merely to satisfy validation",
+		),
+	workspace: z
+		.literal('none')
+		.optional()
+		.describe(
+			'create/update: pure script only. Run in a private scheduler workspace with no project; omit folder. The script still runs as your user on this machine, so this is not a sandbox or a write boundary.',
 		),
 	tz: z
 		.string()
@@ -143,10 +155,10 @@ const inputSchema = z.object({
 			tokenBudget: z
 				.number()
 				.int()
-				.positive()
+				.nonnegative()
 				.optional()
 				.describe(
-					'Tokens one run may spend in total. Every model call resends the whole prompt (often 10,000-30,000 tokens each), so a run needs far more than its answer; omit for the default.',
+					'Tokens one run may spend in total; 0 means no token limit. Every model call resends the whole prompt (often 10,000-30,000 tokens each), so a finite budget needs far more than its answer; omit to inherit the host default.',
 				),
 			timeoutMs: z
 				.number()
@@ -299,6 +311,12 @@ async function create(
 	if (runKind === 'agent' && input.script !== undefined) {
 		return refuse('an agent job has no script; omit kind (or set it to agent) to use one')
 	}
+	if (input.workspace === 'none' && runKind !== 'script')
+		return refuse("workspace: 'none' is only for a pure script job")
+	if (input.workspace === 'none' && input.folder !== undefined)
+		return refuse("workspace: 'none' cannot be combined with folder; omit folder")
+	if (input.script?.report !== undefined && runKind !== 'script')
+		return refuse('script.report is only for a pure script job')
 	if (runKind === 'script' && input.prompt !== undefined)
 		return refuse('a pure script job has no prompt; remove prompt')
 	if (runKind === 'script' && input.budget !== undefined) {
@@ -318,6 +336,7 @@ async function create(
 		...(input.script ? { script: input.script } : {}),
 		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
 		...(input.folder !== undefined ? { folder: input.folder } : {}),
+		...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
 		...(input.tz !== undefined ? { tz: input.tz } : {}),
 		...(input.notifyOnFinish !== undefined ? { notifyOnFinish: input.notifyOnFinish } : {}),
 		permissions,
@@ -389,6 +408,7 @@ const CHANGEABLE = [
 	'prompt',
 	'when',
 	'folder',
+	'workspace',
 	'tz',
 	'notifyOnFinish',
 	'permissions',
@@ -422,6 +442,12 @@ async function update(
 			'update cannot set kind to agent while also giving a script; drop script to make it an agent job, or leave kind unset (or as script/script+agent) to keep one.',
 		)
 	}
+	if (input.workspace === 'none' && input.folder !== undefined)
+		return refuse("workspace: 'none' cannot be combined with folder; omit folder")
+	if (input.workspace === 'none' && input.kind !== undefined && input.kind !== 'script')
+		return refuse("workspace: 'none' is only for a pure script job")
+	if (input.script?.report !== undefined && input.kind !== undefined && input.kind !== 'script')
+		return refuse('script.report is only for a pure script job')
 	let permissions: ScheduleJobDraft['permissions'] | undefined
 	if (input.permissions) {
 		const checked = checkPermissions(host, input.permissions)
@@ -448,6 +474,7 @@ async function update(
 		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
 		...(input.when !== undefined ? { when: input.when } : {}),
 		...(input.folder !== undefined ? { folder: input.folder } : {}),
+		...(input.workspace !== undefined ? { workspace: input.workspace } : {}),
 		...(input.tz !== undefined ? { tz: input.tz } : {}),
 		...(input.notifyOnFinish !== undefined ? { notifyOnFinish: input.notifyOnFinish } : {}),
 		...(permissions ? { permissions } : {}),
@@ -532,7 +559,13 @@ async function lifecycle(
 	}
 	if (action === 'pause') await host.pause(job.name)
 	else if (action === 'resume') await host.resume(job.name)
-	else await host.delete(job.name)
+	else {
+		try {
+			await host.delete(job.name)
+		} catch (error) {
+			return refuse(error instanceof Error ? error.message : String(error))
+		}
+	}
 	const verb = action === 'pause' ? 'paused' : action === 'resume' ? 'resumed' : 'deleted'
 	return { success: true, output: `Job "${job.name}" ${verb}.`, data: { name: job.name, action } }
 }
@@ -554,7 +587,7 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 		defineTool({
 			name: SCHEDULE_TOOL_NAME,
 			description:
-				"Manage the operator's scheduled jobs: model prompts or fixed scripts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, update, resume and delete are confirmed by the operator; pause is not. A job needs name, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). agent and script+agent also need prompt; script and script+agent also need script. For a pure script, use permissions {rules:{},unmatched:'deny'} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script has no prompt, model, agent budget, browser grant or session; set script.timeoutMs to limit it. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave folder unset when the session folder is valid; home, root and NAMZU_HOME are invalid, so choose an existing project subfolder there. Leave tz, execution, budget and headed unset unless the user asked for them: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
+				"Manage durable jobs that run later, including while Namzu is closed when its scheduler is installed. For repetition in this open conversation while the TUI is open, use session_loop (/loop); a loop is not a background service. Use schedule only when the user asks for durable scheduled work. create, update, resume and delete ask the operator; pause does not. A job needs name, when and explicit permissions. agent and script+agent need prompt; script and script+agent need script. For a pure script, use permissions {rules:{},unmatched:'deny'} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script has no prompt, model, agent budget, browser grant or run session; set script.timeoutMs to limit it. A pure script may opt into script.report:'json-v1': one JSON stdout line says quiet or changed with a summary and optional scheduler-owned nextState. For a project-free pure script set workspace:'none' and omit folder; its private scheduler workspace is not a sandbox, and its shell still has host authority. For project work, use the actual existing project folder; home, root and NAMZU_HOME are invalid. Do not create a visible folder merely to satisfy validation. The requesting conversation can receive important results separately from the run workspace. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave tz, execution, budget and headed unset unless requested: defaults are the operator's. Scheduled runs cannot ask questions.",
 			inputSchema,
 			category: 'custom',
 			permissions: [],

package/src/tools/schedules/types.ts

@@ -33,11 +33,15 @@ export interface ScheduleJobDraft {
 		readonly body: string
 		readonly shell: 'bash' | 'sh'
 		readonly timeoutMs?: number
+		/** Pure scripts only: one JSON v1 report line on stdout per run. */
+		readonly report?: 'json-v1'
 	}
 	/** Schedule words: `every 30m`, `0 9 * * 1-5`, `at 09:00`, `in 2h`. */
 	readonly when: string
-	/** Folder the job runs in. Absent: the session's working directory. */
+	/** Project folder the job runs in. Absent: the session's folder, unless `workspace` is `'none'`. */
 	readonly folder?: string
+	/** A private scheduler workspace for a pure script; omit `folder` when set. */
+	readonly workspace?: 'none'
 	/** IANA zone for a cron expression or a local time. Absent: the host's. */
 	readonly tz?: string
 	/** Enable routine completion notices. Absent: the host's usual setting. */
@@ -65,6 +69,7 @@ export interface ScheduleJobDraft {
 	}
 	readonly budget?: {
 		readonly maxIterations?: number
+		/** Total model tokens per agent phase; zero means no token limit. Omit to inherit the host default. */
 		readonly tokenBudget?: number
 		readonly timeoutMs?: number
 	}
@@ -95,8 +100,18 @@ export interface ScheduleBrowserGrant {
 /** What the person confirming is shown. Every field is the host's own computation. */
 export interface ScheduleJobPreview {
 	readonly name: string
-	/** The canonical folder the job would run in. */
+	/** The canonical working directory, including the private planned path for `workspace: 'none'`. */
 	readonly folder: string
+	/** The private scheduler workspace is used instead of a project folder. */
+	readonly workspace?: 'none'
+	/** Host-bound source conversation that receives results; absent for older hosts. */
+	readonly delivery?: {
+		readonly kind: 'source-conversation'
+		readonly sessionId: string
+		readonly projectSlug: string
+		readonly projectId: string
+		readonly tenantId: string
+	}
 	/** True when `folder` is outside the session's working directory and added directories. */
 	readonly outsideSessionRoots: boolean
 	/** Empty for a pure `'script'` job, whose prompt is unused. */
@@ -108,6 +123,7 @@ export interface ScheduleJobPreview {
 		readonly body: string
 		readonly shell: 'bash' | 'sh'
 		readonly timeoutMs: number
+		readonly report?: 'json-v1'
 	}
 	/** The schedule in words, with its zone. */
 	readonly schedule: string
@@ -126,10 +142,11 @@ export interface ScheduleJobPreview {
 	/** Effective run limits. A pure script has zero model iterations/tokens and its script timeout. */
 	readonly budget: {
 		readonly maxIterations: number
+		/** Zero means no token limit for an agent phase, or no model use for a pure script. */
 		readonly tokenBudget: number
 		readonly timeoutMs: number
 	}
-	/** Runs per day at most, times the token budget. Absent for a one-shot. */
+	/** Runs per day at most, times a finite token budget. Absent for a one-shot, an unlimited agent phase, or a pure script. */
 	readonly dailyTokenCeiling?: number
 	/** Provider and model the agent phase is pinned to. Absent for a pure script job. */
 	readonly model?: string
@@ -142,6 +159,7 @@ export interface ScheduleJobPreview {
 /** A job as the `list` action reports it. */
 export interface ScheduleJobSummary {
 	readonly name: string
+	/** Canonical project path, or a host-provided label for a private workspace. */
 	readonly folder: string
 	readonly state: string
 	readonly schedule: string
@@ -167,6 +185,8 @@ export interface ScheduleJobChanges {
 	readonly prompt?: string
 	readonly when?: string
 	readonly folder?: string
+	/** Switch a pure script to a private scheduler workspace; omit `folder` when set. */
+	readonly workspace?: 'none'
 	readonly tz?: string
 	/** Whether routine Namzu desktop completion notices are enabled. */
 	readonly notifyOnFinish?: boolean

package/src/tools/task/list.ts

@@ -13,7 +13,7 @@ export function buildTaskListTool(
 	return defineTool({
 		name: 'task_list',
 		description:
-			'List planning items for this session: every open one, and those closed during the current turn. Not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
+			'List planning items for this session: every open one, and those closed during the current turn. Earlier completed or failed items remain stored but are omitted; returned tasks and stats count only this current-turn view, not the full stored history. Not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
 		inputSchema: z.object({}),
 		category: 'custom',
 		permissions: [],
@@ -26,13 +26,13 @@ export function buildTaskListTool(
 			const all = await taskStore.list({ sessionId: scope.sessionId })
 			// Blockers resolve against every task of the session, shown or not: a
 			// blocker closed in an earlier turn is resolved, not unknown.
-			const completedIds = new Set(
+			const terminalIds = new Set(
 				all.filter((t) => isTerminalTaskStatus(t.status)).map((t) => t.id),
 			)
 			const tasks = selectTaskContext(all, scope)
 
 			const summary = tasks.map((task) => {
-				const unresolvedBlockers = task.blockedBy.filter((bid) => !completedIds.has(bid))
+				const unresolvedBlockers = task.blockedBy.filter((bid) => !terminalIds.has(bid))
 
 				return {
 					id: task.id,
@@ -49,14 +49,22 @@ export function buildTaskListTool(
 				pending: tasks.filter((t) => t.status === 'pending').length,
 				in_progress: tasks.filter((t) => t.status === 'in_progress').length,
 				completed: tasks.filter((t) => t.status === 'completed').length,
+				failed: tasks.filter((t) => t.status === 'failed').length,
 			}
+			const omitted = all.length - tasks.length
+			const history = omitted
+				? ` ${countTasks(omitted)} closed in earlier turns ${omitted === 1 ? 'remains' : 'remain'} stored and ${omitted === 1 ? 'is' : 'are'} omitted from this view.`
+				: ''
+			const output =
+				all.length === 0
+					? 'No planning tasks found for this session. This list does not report delegated agent status; use agent_task_list when available.'
+					: tasks.length === 0
+						? `No open or current-turn planning tasks.${history}`
+						: `Current-turn view: ${countTasks(stats.total)}: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending${stats.failed ? `, ${stats.failed} failed` : ''}.${history}`
 
 			return {
 				success: true,
-				output:
-					tasks.length === 0
-						? 'No planning tasks yet. This list does not report delegated agent status; use agent_task_list when available.'
-						: `${countTasks(stats.total)}: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
+				output,
 				data: { tasks: summary, stats },
 			}
 		},

package/src/tools/task/present.ts

@@ -28,7 +28,11 @@ function activity(label: string): ToolCallView {
 }
 
 /** A successful receipt: the call row already said it. */
-const HIDDEN_RESULT: ToolResultView = { kind: 'generic', label: '', visibility: 'hidden' }
+const HIDDEN_RESULT: ToolResultView = {
+	kind: 'generic',
+	label: '',
+	visibility: 'hidden',
+}
 
 /** `N task` / `N tasks`. */
 export function countTasks(count: number): string {
@@ -44,7 +48,9 @@ function failure(result: ToolResult, fallback: string): ToolResultView {
 	}
 }
 
-export function presentTaskCreateCall(input: { readonly subject?: unknown }): ToolCallView {
+export function presentTaskCreateCall(input: {
+	readonly subject?: unknown
+}): ToolCallView {
 	const subject = typeof input.subject === 'string' ? oneLine(input.subject) : ''
 	return activity(subject ? `Add task · ${subject}` : 'Add task')
 }
@@ -61,10 +67,12 @@ export function taskUpdateVerb(status: unknown): string {
 			return 'Start task'
 		case 'completed':
 			return 'Complete task'
+		case 'failed':
+			return 'Fail task'
 		case 'deleted':
 			return 'Remove task'
 		case 'pending':
-			return 'Reopen task'
+			return 'Set task pending'
 		default:
 			return 'Update task'
 	}
@@ -80,7 +88,22 @@ export function presentTaskUpdateCall(input: {
 }
 
 export function presentTaskUpdateResult(_input: unknown, result: ToolResult): ToolResultView {
-	if (!result.success) return failure(result, 'The task was not changed')
+	if (!result.success) {
+		const data = result.data as { status?: unknown; requestedStatus?: unknown } | undefined
+		if (
+			typeof data?.requestedStatus === 'string' &&
+			data.requestedStatus !== data.status &&
+			(data.status === 'pending' ||
+				data.status === 'in_progress' ||
+				data.status === 'completed' ||
+				data.status === 'failed')
+		)
+			return {
+				kind: 'generic',
+				label: `Task remains ${data.status.replace('_', ' ')}; other edits may have applied`,
+			}
+		return failure(result, 'The task was not changed')
+	}
 	return HIDDEN_RESULT
 }
 
@@ -90,13 +113,20 @@ export function presentTaskListCall(): ToolCallView {
 
 export function presentTaskListResult(_input: unknown, result: ToolResult): ToolResultView {
 	if (!result.success) return { kind: 'generic', label: 'The task list could not be read' }
-	const stats = (result.data as { stats?: { total?: unknown; completed?: unknown } } | undefined)
-		?.stats
+	const stats = (
+		result.data as
+			| { stats?: { total?: unknown; completed?: unknown; failed?: unknown } }
+			| undefined
+	)?.stats
 	const total = typeof stats?.total === 'number' ? stats.total : undefined
 	const completed = typeof stats?.completed === 'number' ? stats.completed : undefined
+	const failed = typeof stats?.failed === 'number' ? stats.failed : 0
 	if (total === undefined || completed === undefined) return HIDDEN_RESULT
 	return {
 		kind: 'generic',
-		label: total === 0 ? 'No tasks yet' : `Tasks · ${completed}/${total} done`,
+		label:
+			total === 0
+				? 'No open or current-turn tasks'
+				: `Current-turn task view · ${completed}/${total} done${failed ? ` · ${failed} failed` : ''}`,
 	}
 }

package/src/tools/task/update.ts

@@ -9,14 +9,14 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 	return defineTool({
 		name: 'task_update',
 		description:
-			'Update an existing task. Change its status (pending → in_progress → completed), edit its description, transfer ownership, or manage dependencies. Use status "deleted" to remove a task entirely.',
+			'Update task fields, owner or dependencies. Built-in statuses move forward only; completed/failed are terminal. Create follow-up tasks instead of reopening. Record failures as failed. An unconfirmed status may leave other edits applied. Outcomes are reported, not verified. Use "deleted" to remove a task.',
 		inputSchema: z.object({
 			id: z.string().describe('Task ID (e.g. "task_abc123")'),
 			subject: z.string().optional().describe('Updated title'),
 			description: z.string().optional().describe('Updated description'),
 			activeForm: z.string().optional().describe('Updated present continuous form'),
 			status: z
-				.enum(['pending', 'in_progress', 'completed', 'deleted'])
+				.enum(['pending', 'in_progress', 'completed', 'failed', 'deleted'])
 				.optional()
 				.describe('New status'),
 			owner: z.string().optional().describe('Agent name to assign ownership'),
@@ -76,7 +76,7 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 				subject,
 				description,
 				activeForm,
-				status: status as 'pending' | 'in_progress' | 'completed' | undefined,
+				status,
 				owner,
 				metadata,
 			})
@@ -85,14 +85,21 @@ export function buildTaskUpdateTool(taskStore: TaskStore): ToolDefinition {
 				return { success: false, output: `Task ${id} not found` }
 			}
 
+			// Stores can retain the old status while applying other edits. The
+			// receipt describes the returned state; it cannot prove whether the
+			// request was refused or a concurrent writer advanced it again.
+			const statusApplied = status === undefined || updated.status === status
 			return {
-				success: true,
-				output: `Task ${id} updated — status: ${updated.status}`,
+				success: statusApplied,
+				output: statusApplied
+					? `Task ${id} updated — status: ${updated.status}`
+					: `Task ${id} requested status "${status}" could not be confirmed; returned status is "${updated.status}". Other requested edits may have applied. Inspect the task and create a new task for follow-up work.`,
 				data: {
 					id: updated.id,
 					subject: updated.subject,
 					status: updated.status,
 					owner: updated.owner,
+					...(statusApplied ? {} : { requestedStatus: status }),
 				},
 			}
 		},

package/src/tools/text-window.ts

@@ -0,0 +1,87 @@
+import type { ToolTextWindow } from '../types/tool/presentation.js'
+
+/** Lines kept from the start and from the end of a long text. */
+export const WINDOW_HEAD_LINES = 80
+export const WINDOW_TAIL_LINES = 40
+/** A window never holds more than this many characters in either half. */
+export const WINDOW_HALF_CHARS = 6_000
+
+function clipHead(text: string, max: number): string {
+	if (text.length <= max) return text
+	// By code point so a surrogate pair is never cut in two.
+	let end = max
+	const last = text.charCodeAt(end - 1)
+	if (last >= 0xd800 && last <= 0xdbff) end -= 1
+	return `${text.slice(0, end)}…`
+}
+
+function clipTail(text: string, max: number): string {
+	if (text.length <= max) return text
+	let start = text.length - max
+	const first = text.charCodeAt(start)
+	if (first >= 0xdc00 && first <= 0xdfff) start += 1
+	return `…${text.slice(start)}`
+}
+
+/**
+ * A bounded window onto `text` for the person's view: everything when it is
+ * short, otherwise the first and last lines with a count of what lay between.
+ * The model's own text is not touched; this is built beside it.
+ */
+export function windowText(
+	text: string,
+	totalBytes = Buffer.byteLength(text, 'utf8'),
+): ToolTextWindow {
+	const body = text.endsWith('\n') ? text.slice(0, -1) : text
+	const lines = body.length === 0 ? [] : body.split('\n')
+	const totalLines = lines.length
+	if (totalLines <= WINDOW_HEAD_LINES + WINDOW_TAIL_LINES && body.length <= WINDOW_HALF_CHARS * 2) {
+		return { head: body, totalLines, totalBytes }
+	}
+	const headLines = lines.slice(0, WINDOW_HEAD_LINES)
+	const tailLines =
+		totalLines > WINDOW_HEAD_LINES
+			? lines.slice(Math.max(WINDOW_HEAD_LINES, totalLines - WINDOW_TAIL_LINES))
+			: []
+	const head = clipHead(headLines.join('\n'), WINDOW_HALF_CHARS)
+	const tail = clipTail(tailLines.join('\n'), WINDOW_HALF_CHARS)
+	const omittedLines = totalLines - headLines.length - tailLines.length
+	return {
+		head,
+		...(tail ? { tail } : {}),
+		...(omittedLines > 0 ? { omittedLines } : {}),
+		totalLines,
+		totalBytes,
+	}
+}
+
+const SAMPLE_CHARS = 8_000
+
+/**
+ * Whether decoded output is a stream of bytes and not text: a NUL, or a
+ * noticeable share of control characters and replacement characters that no
+ * terminal prints. ANSI escapes, tabs, backspaces and line ends are text.
+ */
+export function looksBinary(text: string): boolean {
+	const sample = text.length > SAMPLE_CHARS ? text.slice(0, SAMPLE_CHARS) : text
+	if (sample.length === 0) return false
+	let odd = 0
+	for (let i = 0; i < sample.length; i++) {
+		const code = sample.charCodeAt(i)
+		if (code === 0) return true
+		if (code === 0xfffd) odd++
+		else if (
+			code < 0x20 &&
+			code !== 9 &&
+			code !== 10 &&
+			code !== 13 &&
+			code !== 27 &&
+			code !== 8 &&
+			code !== 7 &&
+			code !== 12
+		)
+			odd++
+		else if (code === 0x7f) odd++
+	}
+	return odd / sample.length > 0.02
+}

package/src/toolsets/manager.ts

@@ -8,6 +8,7 @@ import { ToolResultHalted, screenToolResult } from '../registry/tool/screen.js'
 import { GENAI, NAMZU, toolSpanName } from '../telemetry/attributes.js'
 import { recordToolCall } from '../telemetry/metrics.js'
 import { getTracer } from '../telemetry/runtime-accessors.js'
+import { failureFactsFromError } from '../tools/failure-facts.js'
 import { isTrustedReadOnly } from '../tools/trusted-read-only.js'
 import { wrapUntrusted } from '../tools/untrusted-envelope.js'
 import type { ToolResultGuardrailSpec } from '../types/guardrail/index.js'
@@ -25,6 +26,8 @@ import type {
 	ToolTierConfig,
 	ToolsView,
 } from '../types/tool/index.js'
+import type { ToolFacts } from '../types/tool/presentation.js'
+import { awaitWithAbort } from '../utils/await-with-abort.js'
 import { toErrorMessage } from '../utils/error.js'
 import { cloneJsonValue as clonePreparedInput } from '../utils/json-snapshot.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
@@ -670,10 +673,55 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult {
 		const tool = this.getOrThrow(toolName)
 		const parseResult = tool.inputSchema.safeParse(rawInput)
+		return this.finalizePreparation(tool, rawInput, parseResult)
+	}
+
+	/**
+	 * Decode an input once, including asynchronous schema refinements and transforms.
+	 * JSON-compatible raw values are detached synchronously before validation can
+	 * yield. Non-JSON host values retain the schema's input semantics; callers must
+	 * not mutate them while preparation is pending. The prepared output must still
+	 * be immutable JSON, as with `prepareExecution`.
+	 * Cancellation stops waiting and prevents publication, but cannot stop schema
+	 * work that does not cooperate with cancellation.
+	 */
+	async prepareExecutionAsync(
+		toolName: string,
+		rawInput: unknown,
+		signal?: AbortSignal,
+	): Promise<ToolPreparationResult> {
+		signal?.throwIfAborted()
+		const tool = this.getOrThrow(toolName)
+		let validationInput = rawInput
+		try {
+			validationInput = clonePreparedInput(rawInput, false, '$', true)
+		} catch {
+			// A schema may normalize a Date or another host value into JSON.
+			// Raw input safety must not narrow that existing normalization domain.
+		}
+		signal?.throwIfAborted()
+		const asyncParse = tool.inputSchema.safeParseAsync
+		const operation =
+			typeof asyncParse === 'function'
+				? asyncParse.call(tool.inputSchema, validationInput)
+				: Promise.resolve(tool.inputSchema.safeParse(validationInput))
+		const parseResult = await awaitWithAbort(operation, signal)
+		signal?.throwIfAborted()
+		return this.finalizePreparation(tool, validationInput, parseResult, signal)
+	}
+
+	private finalizePreparation(
+		tool: ToolDefinition,
+		rawInput: unknown,
+		parseResult: ReturnType<ToolDefinition['inputSchema']['safeParse']>,
+		signal?: AbortSignal,
+	): ToolPreparationResult {
+		const toolName = tool.name
 		if (!parseResult.success) {
 			return {
 				success: false,
 				result: this.validationFailure(tool, rawInput, parseResult.error),
+				inputFailure: 'schema_validation',
 			}
 		}
 
@@ -683,6 +731,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			retainedInput = clonePreparedInput(parseResult.data, false)
 			reviewInput = clonePreparedInput(retainedInput, true)
 		} catch (err) {
+			signal?.throwIfAborted()
 			const message = `Tool "${toolName}" produced an input that cannot be safely prepared for review and execution: ${toErrorMessage(err)}`
 			this.log.error('Prepared tool input could not be detached for review and execution', {
 				'namzu.tool.name': toolName,
@@ -694,6 +743,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 			}
 		}
 
+		signal?.throwIfAborted()
 		const prepared = Object.freeze({ toolName, input: reviewInput })
 		this.preparations.set(prepared, { tool, input: retainedInput })
 		return { success: true, prepared }
@@ -728,7 +778,8 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	): Promise<ToolExecutionResult> {
 		let preparation: ToolPreparationResult
 		try {
-			preparation = this.prepareExecution(toolName, rawInput)
+			preparation = await this.prepareExecutionAsync(toolName, rawInput, context.abortSignal)
+			context.abortSignal?.throwIfAborted()
 		} catch (err) {
 			return this.rejectPreparationWithClosedSpan(toolName, context, err)
 		}
@@ -921,6 +972,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						success: false,
 						output: '',
 						error: `Tool "${toolName}" execution failed: ${errorMessage}`,
+						...failureFactsField(err),
 					}
 				}
 			} finally {
@@ -1067,3 +1119,8 @@ function describeRequiredInput(schema: { _def?: unknown }): string {
 		return 'Could not introspect required parameters.'
 	}
 }
+
+function failureFactsField(err: unknown): { facts?: ToolFacts } {
+	const facts = failureFactsFromError(err)
+	return facts ? { facts } : {}
+}