@namzu/sdk 31.1.0 → 33.0.0

package/src/provider/errors.ts

@@ -57,6 +57,7 @@ const PROVIDER_ERROR_KINDS: readonly ProviderErrorKind[] = [
 export class ProviderRequestError extends Error {
 	public readonly kind: ProviderErrorKind
 	public readonly providerId: string
+	public readonly providerCode?: string
 	public readonly status?: number
 	public readonly retryAfterMs?: number
 	/**
@@ -81,6 +82,8 @@ export class ProviderRequestError extends Error {
 		this.name = 'ProviderRequestError'
 		this.kind = init.kind
 		this.providerId = init.providerId
+		const exactProviderCode = safeProviderCode(init.providerCode)
+		if (exactProviderCode !== undefined) this.providerCode = exactProviderCode
 		if (init.status !== undefined) this.status = init.status
 		if (init.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
 		if (init.detail !== undefined) this.detail = init.detail
@@ -90,6 +93,32 @@ export class ProviderRequestError extends Error {
 /** Longest detail worth carrying. A provider's complaint is a sentence. */
 const DETAIL_MAX = 400
 
+/** Provider codes are identifiers, not another channel for an arbitrary response body. */
+const PROVIDER_CODE = /^[A-Za-z][A-Za-z0-9._-]{0,79}$/
+
+function safeProviderCode(value: unknown): string | undefined {
+	if (typeof value !== 'string' || !PROVIDER_CODE.test(value)) return undefined
+	return redactSecrets(value) === value ? value : undefined
+}
+
+function providerCode(value: unknown): string | undefined {
+	let decoded = value
+	if (typeof decoded === 'string') {
+		try {
+			decoded = JSON.parse(decoded)
+		} catch {
+			return undefined
+		}
+	}
+	if (typeof decoded !== 'object' || decoded === null) return undefined
+	const record = decoded as Record<string, unknown>
+	const nested =
+		typeof record.error === 'object' && record.error !== null
+			? (record.error as Record<string, unknown>).code
+			: undefined
+	return safeProviderCode(record.code ?? nested)
+}
+
 /**
  * Credential shapes to scrub before a provider's words are kept.
  *
@@ -161,11 +190,15 @@ function pickMessage(value: unknown): string | undefined {
 
 /** Is this a classified provider failure, whichever SDK copy threw it? */
 export function isProviderRequestError(err: unknown): err is ProviderRequestError {
+	const exactProviderCode = (err as { providerCode?: unknown } | null)?.providerCode
 	return (
 		err instanceof Error &&
 		err.name === 'ProviderRequestError' &&
 		typeof (err as { providerId?: unknown }).providerId === 'string' &&
-		PROVIDER_ERROR_KINDS.includes((err as { kind?: ProviderErrorKind }).kind as ProviderErrorKind)
+		PROVIDER_ERROR_KINDS.includes(
+			(err as { kind?: ProviderErrorKind }).kind as ProviderErrorKind,
+		) &&
+		(exactProviderCode === undefined || safeProviderCode(exactProviderCode) === exactProviderCode)
 	)
 }
 
@@ -393,6 +426,7 @@ export function providerVendorError(input: {
 }): ProviderRequestError {
 	const { error } = input
 	const status = vendorErrorStatus(error)
+	const exactProviderCode = providerCode(error)
 	const name = error instanceof Error ? error.name : ''
 	const message = error instanceof Error ? error.message : ''
 
@@ -411,6 +445,8 @@ export function providerVendorError(input: {
 		kind = 'server'
 	} else if (status !== undefined) {
 		kind = classifyProviderHttpStatus(status, message)
+	} else if (exactProviderCode === 'invalid_image') {
+		kind = 'bad_request'
 	} else if (bodySaysContextOverflow(message)) {
 		kind = 'context_overflow'
 	} else {
@@ -428,6 +464,7 @@ export function providerVendorError(input: {
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
+		...(exactProviderCode !== undefined ? { providerCode: exactProviderCode } : {}),
 		...(status !== undefined ? { status } : {}),
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),
@@ -450,9 +487,11 @@ export function providerHttpError(input: {
 	const kind = classifyProviderHttpStatus(input.status, input.body)
 	const retryAfterMs = parseRetryAfterMs(input.retryAfter, input.now ?? Date.now())
 	const detail = vendorDetail(input.body)
+	const exactProviderCode = providerCode(input.body)
 	return new ProviderRequestError({
 		kind,
 		providerId: input.providerId,
+		...(exactProviderCode !== undefined ? { providerCode: exactProviderCode } : {}),
 		status: input.status,
 		...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 		...(detail !== undefined ? { detail } : {}),

package/src/provider/fallback.ts

@@ -230,6 +230,40 @@ function memberReasoningEffortLevels(
 	return member.provider.effortLevelsFor?.(model, thinking)
 }
 
+/** Read one member's model-owned default using its routed model id. */
+function memberReasoningEffortDefault(
+	member: ProviderChainMember,
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): ReasoningEffort | undefined {
+	return member.provider.reasoningEffortDefaultFor?.(member.model ?? requestModel, thinking)
+}
+
+/**
+ * A fallback request has one unambiguous default only when every route agrees.
+ *
+ * Omitting effort lets whichever member serves the request choose its own
+ * default. Publishing the head's answer as the chain's answer can therefore
+ * make the same shortcut move in opposite directions after fallback. The
+ * agreed value must also survive the chain-wide exact menu.
+ */
+function commonReasoningEffortDefault(
+	members: readonly ProviderChainMember[],
+	requestModel: string,
+	thinking?: ThinkingConfig,
+): ReasoningEffort | undefined {
+	const common = commonReasoningEffortLevels(members, requestModel, thinking)
+	if (common === undefined) return undefined
+	let agreed: ReasoningEffort | undefined
+	for (const member of members) {
+		const value = memberReasoningEffortDefault(member, requestModel, thinking)
+		if (value === undefined) return undefined
+		if (agreed !== undefined && value !== agreed) return undefined
+		agreed = value
+	}
+	return agreed !== undefined && common.includes(agreed) ? agreed : undefined
+}
+
 /**
  * The levels one request may carry safely through every member it can reach.
  *
@@ -463,6 +497,11 @@ export function withProviderFallback(
 		// answer when any member cannot enumerate its selected model.
 		reasoningEffortLevelsFor: (model: string, thinking?: ThinkingConfig) =>
 			commonReasoningEffortLevels(members, model, thinking),
+		// Present on the chain wrapper for the same reason the menu method is:
+		// `undefined` is the honest answer when a member cannot answer, defaults
+		// disagree, or the value is absent from the common exact menu.
+		reasoningEffortDefaultFor: (model: string, thinking?: ThinkingConfig) =>
+			commonReasoningEffortDefault(members, model, thinking),
 		// Compatibility projection only. Existing consumers of the deprecated
 		// member keep the head-only answer they had; new consumers use the
 		// canonical chain-aware member above.

package/src/provider/idle-timeout.ts

@@ -220,6 +220,14 @@ export function withStreamIdleTimeout(
 					) => provider.reasoningEffortLevelsFor?.(model, thinking),
 				}
 			: {}),
+		...(provider.reasoningEffortDefaultFor
+			? {
+					reasoningEffortDefaultFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortDefaultFor']>>[1],
+					) => provider.reasoningEffortDefaultFor?.(model, thinking),
+				}
+			: {}),
 		...(provider.effortLevelsFor
 			? {
 					effortLevelsFor: (

package/src/provider/retry.ts

@@ -275,6 +275,14 @@ export function withProviderRetry(
 					) => provider.reasoningEffortLevelsFor?.(model, thinking),
 				}
 			: {}),
+		...(provider.reasoningEffortDefaultFor
+			? {
+					reasoningEffortDefaultFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['reasoningEffortDefaultFor']>>[1],
+					) => provider.reasoningEffortDefaultFor?.(model, thinking),
+				}
+			: {}),
 		// Forwarded for the same reason `healthCheck` is, and both were
 		// missing until something consumed them. A member this wrapper drops
 		// does not fail — it reads as "this driver cannot answer", which is a

package/src/public-runtime.ts

@@ -12,6 +12,12 @@
 
 export { VERSION } from './version.js'
 
+// The opt-in model-authored-code backend. `RunCodeToolOptions.runtime` has
+// always accepted this contract; exporting the implementation and its refusal
+// class makes that signature nameable from the package root.
+export { HostCallDeniedError } from './execution/code-runtime/types.js'
+export { WorkerCodeRuntime } from './execution/code-runtime/worker.js'
+
 export {
 	CompactionConfigSchema,
 	PluginRuntimeConfigSchema,
@@ -287,7 +293,11 @@ export {
 	formatSteeringNote,
 } from './runtime/query/steering.js'
 export type { SteeringChannel } from './runtime/query/steering.js'
-export { createMockBidiProvider, startBidiRun } from './runtime/bidi/index.js'
+export {
+	BidiSessionCloseTimeoutError,
+	createMockBidiProvider,
+	startBidiRun,
+} from './runtime/bidi/index.js'
 export { PromptCache } from './runtime/query/prompt-cache.js'
 export {
 	CheckpointManager,
@@ -666,6 +676,7 @@ export {
 export {
 	BaseConnector,
 	BaseExecutionContext,
+	CommandCancellationUnsupportedError,
 	ConnectorManager,
 	ConnectorRegistry,
 	EnvironmentConnectorManager,
@@ -689,6 +700,7 @@ export {
 	mcpToolResultToToolResult,
 	mcpToolToToolDefinition,
 	RemoteExecutionContext,
+	RemoteExecutionBusyError,
 	ScopedConnectorRegistry,
 	// The only transport in the tree that can RUN an `MCPServer`. It reached
 	// `connector/mcp/index.ts` and stopped there, so the server was public
@@ -995,6 +1007,7 @@ export { assertMemoryStatus } from './types/memory/index.js'
 export {
 	createAssistantMessage,
 	createProjectInstructionMessage,
+	createRuntimeContextMessage,
 	createSystemMessage,
 	createToolMessage,
 	hasNonTextBlocks,
@@ -1002,7 +1015,10 @@ export {
 	toolResultToText,
 	createUserMessage,
 	isProjectInstructionMessageSource,
+	isRuntimeContextMessageSource,
+	isModelContentOmission,
 	MAX_PROJECT_INSTRUCTION_SOURCE_FILES,
+	RUNTIME_CONTEXT_MESSAGE_KINDS,
 } from './types/message/index.js'
 export { isTerminalPlanStatus } from './types/plan/index.js'
 export {
@@ -1198,8 +1214,10 @@ export {
 // Inline base64 lands in the transcript, in every checkpoint, and on the
 // wire once per turn; a reference does not.
 export {
+	DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS,
 	AttachmentMediaTypeMismatchError,
 	AttachmentNotFoundError,
+	AttachmentResolutionTimeoutError,
 	NoAttachmentStoreError,
 	isStoredAttachment,
 	resolveAttachment,
@@ -1254,7 +1272,10 @@ export type {
 	CompactionVerificationOptions,
 	UsageSink,
 } from './compaction/verifier.js'
-export type { PluginDiscoveryOptions, PluginEnablementCapabilities } from './plugin/loader.js'
+export type {
+	PluginDiscoveryOptions,
+	PluginEnablementCapabilities,
+} from './plugin/loader.js'
 export type { ProbeContextInput } from './probe/context.js'
 export type {
 	GoalCommandScope,

package/src/public-types.ts

@@ -19,6 +19,16 @@ export type * from './types/common/index.js'
 export type { CoalesceOptions } from './streaming/coalesce.js'
 export type * from './types/bidi/index.js'
 export type * from './types/tool/index.js'
+export type {
+	CodeRunOutcome,
+	CodeRunResult,
+	CodeRuntime,
+	HostCallContext,
+	HostCallHandler,
+	HostCallRequest,
+	HostCallResult,
+	RunCodeOptions,
+} from './execution/code-runtime/types.js'
 // The directory convention: what a loaded `agent/` directory is, and what the
 // loader reports about the files it could not use.
 export type * from './directory/types.js'
@@ -336,6 +346,7 @@ export type {
 
 export type {
 	AttachmentOperationOptions,
+	AttachmentResolutionOptions,
 	AttachmentStore,
 	StoredAttachment,
 	StoredBytes,

package/src/registry/tool/execute.ts

@@ -7,10 +7,12 @@ import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
 import type {
 	LLMToolSchema,
+	PreparedToolExecution,
 	ToolAvailability,
 	ToolContext,
 	ToolDefinition,
 	ToolExecutionResult,
+	ToolPreparationResult,
 	ToolRegistryConfig,
 	ToolTierConfig,
 } from '../../types/tool/index.js'
@@ -87,6 +89,82 @@ export function assertToolName(name: string): void {
 	)
 }
 
+function clonePreparedInput(value: unknown, freeze: boolean, path = '$'): unknown {
+	const active = new WeakSet<object>()
+	const copies = new WeakMap<object, object>()
+
+	const clone = (candidate: unknown, at: string): unknown => {
+		if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+			return candidate
+		}
+		if (typeof candidate === 'number') {
+			if (!Number.isFinite(candidate) || Object.is(candidate, -0)) {
+				throw new TypeError(`${at} must be a finite JSON number`)
+			}
+			return candidate
+		}
+		if (typeof candidate !== 'object') {
+			throw new TypeError(`${at} must be a JSON value, not ${typeof candidate}`)
+		}
+		if (active.has(candidate)) throw new TypeError(`${at} contains a cycle`)
+		const existing = copies.get(candidate)
+		if (existing) return existing
+
+		active.add(candidate)
+		try {
+			if (Array.isArray(candidate)) {
+				const extra = Reflect.ownKeys(candidate).filter(
+					(key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)),
+				)
+				if (extra.length > 0) throw new TypeError(`${at} has non-JSON array properties`)
+				const result: unknown[] = new Array(candidate.length)
+				copies.set(candidate, result)
+				for (let index = 0; index < candidate.length; index++) {
+					const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index))
+					if (!descriptor) throw new TypeError(`${at}[${index}] is a sparse array hole`)
+					if (!descriptor.enumerable || !('value' in descriptor)) {
+						throw new TypeError(`${at}[${index}] must be an enumerable data property`)
+					}
+					result[index] = clone(descriptor.value, `${at}[${index}]`)
+				}
+				if (freeze) Object.freeze(result)
+				return result
+			}
+
+			const prototype = Object.getPrototypeOf(candidate)
+			if (prototype !== Object.prototype && prototype !== null) {
+				throw new TypeError(`${at} must be a plain JSON object`)
+			}
+			// JSON does not preserve prototypes. Canonicalize both admitted plain
+			// shapes to an ordinary object so a disk checkpoint round-trip compares
+			// equal to a fresh preparation of the same semantic value. Properties
+			// are still defined explicitly, so a literal "__proto__" key remains
+			// data rather than changing this object's prototype.
+			const result: Record<string, unknown> = {}
+			copies.set(candidate, result)
+			for (const key of Reflect.ownKeys(candidate)) {
+				if (typeof key !== 'string') throw new TypeError(`${at} has a symbol property`)
+				const descriptor = Object.getOwnPropertyDescriptor(candidate, key)
+				if (!descriptor?.enumerable || !('value' in descriptor)) {
+					throw new TypeError(`${at}.${key} must be an enumerable data property`)
+				}
+				Object.defineProperty(result, key, {
+					value: clone(descriptor.value, `${at}.${key}`),
+					enumerable: true,
+					writable: !freeze,
+					configurable: !freeze,
+				})
+			}
+			if (freeze) Object.freeze(result)
+			return result
+		} finally {
+			active.delete(candidate)
+		}
+	}
+
+	return clone(value, path)
+}
+
 /**
  * Two sources contributed the same tool name and neither may take it.
  *
@@ -136,9 +214,17 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
 	private tierConfig?: ToolTierConfig
 	private resultGuardrails?: readonly ToolResultGuardrailSpec[]
+	private readonly preparations = new WeakMap<
+		PreparedToolExecution,
+		{ readonly tool: ToolDefinition; readonly input: unknown }
+	>()
 
 	constructor(config?: ToolRegistryConfig) {
-		super({ componentName: 'ToolRegistry', idField: 'name', logger: config?.logger })
+		super({
+			componentName: 'ToolRegistry',
+			idField: 'name',
+			logger: config?.logger,
+		})
 		this.tierConfig = config?.tierConfig
 		this.resultGuardrails = config?.resultGuardrails
 	}
@@ -401,10 +487,106 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 		return this.getByAvailability(['active'], toolNames)
 	}
 
+	prepareExecution(toolName: string, rawInput: unknown): ToolPreparationResult {
+		const tool = this.getOrThrow(toolName)
+		const parseResult = tool.inputSchema.safeParse(rawInput)
+		if (!parseResult.success) {
+			return {
+				success: false,
+				result: this.validationFailure(tool, rawInput, parseResult.error),
+			}
+		}
+
+		let retainedInput: unknown
+		let reviewInput: unknown
+		try {
+			retainedInput = clonePreparedInput(parseResult.data, false)
+			reviewInput = clonePreparedInput(retainedInput, true)
+		} catch (err) {
+			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,
+				'exception.message': toErrorMessage(err),
+			})
+			return {
+				success: false,
+				result: { success: false, output: '', error: message },
+			}
+		}
+
+		const prepared = Object.freeze({ toolName, input: reviewInput })
+		this.preparations.set(prepared, { tool, input: retainedInput })
+		return { success: true, prepared }
+	}
+
+	async executePrepared(
+		prepared: PreparedToolExecution,
+		context: ToolContext,
+	): Promise<ToolExecutionResult> {
+		const retained = this.preparations.get(prepared)
+		if (!retained) {
+			return {
+				success: false,
+				output: '',
+				error: `Tool "${prepared.toolName}" preparation is not owned by this registry or is no longer valid.`,
+			}
+		}
+		if (this.get(prepared.toolName) !== retained.tool) {
+			return {
+				success: false,
+				output: '',
+				error: `Tool "${prepared.toolName}" changed after its input was reviewed; prepare the call again.`,
+			}
+		}
+		return this.executeRetained(prepared.toolName, retained.tool, retained.input, context)
+	}
+
 	async execute(
 		toolName: string,
 		rawInput: unknown,
 		context: ToolContext,
+	): Promise<ToolExecutionResult> {
+		let preparation: ToolPreparationResult
+		try {
+			preparation = this.prepareExecution(toolName, rawInput)
+		} catch (err) {
+			return this.rejectPreparationWithClosedSpan(toolName, context, err)
+		}
+		if (!preparation.success) return preparation.result
+		return this.executePrepared(preparation.prepared, context)
+	}
+
+	private rejectPreparationWithClosedSpan(
+		toolName: string,
+		context: ToolContext,
+		err: unknown,
+	): Promise<never> {
+		const tracer = getTracer()
+		const parentCtx = context.parentSpan
+			? trace.setSpan(otelContext.active(), context.parentSpan)
+			: otelContext.active()
+		return tracer.startActiveSpan(toolSpanName(toolName), {}, parentCtx, async (span) => {
+			try {
+				span.setAttributes({
+					[GENAI.TOOL_NAME]: toolName,
+					[GENAI.TOOL_TYPE]: 'function',
+					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
+					[NAMZU.TOOL_SUCCESS]: false,
+					[NAMZU.TOOL_ERROR]: toErrorMessage(err),
+				})
+				span.setStatus({ code: SpanStatusCode.ERROR, message: toErrorMessage(err) })
+				throw err
+			} finally {
+				span.end()
+			}
+		})
+	}
+
+	private async executeRetained(
+		toolName: string,
+		tool: ToolDefinition,
+		finalInput: unknown,
+		context: ToolContext,
 	): Promise<ToolExecutionResult> {
 		const tracer = getTracer()
 
@@ -437,8 +619,6 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
 				})
 
-				const tool = this.getOrThrow(toolName)
-
 				const availability = this.getAvailability(toolName)
 				if (availability !== 'active') {
 					const msg = `Tool "${toolName}" is ${availability} and cannot be executed`
@@ -492,7 +672,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 				const mode = context.permissionContext?.mode ?? 'auto'
 				if (mode === 'plan') {
-					const isReadOnly = isTrustedReadOnly(tool, rawInput)
+					const isReadOnly = isTrustedReadOnly(tool, finalInput)
 					if (!isReadOnly) {
 						const msg = `plan mode: non-read-only tool "${toolName}" blocked`
 						span.setAttributes({
@@ -510,63 +690,6 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					}
 				}
 
-				const parseResult = tool.inputSchema.safeParse(rawInput)
-				if (!parseResult.success) {
-					const errorMessage = parseResult.error.issues
-						.map((i) => `${i.path.join('.')}: ${i.message}`)
-						.join('; ')
-
-					// Distinguish "model sent an empty/no-arg call" from
-					// "model sent partial args" — the first is most often a
-					// streaming hiccup or a definition-test ping (a provider
-					// occasionally pings tool surfaces with `{}` while the
-					// schema is still loading), the second is a genuine
-					// programming mistake by the model. The model self-
-					// corrects MUCH more reliably when the error tells it
-					// (a) which fields are required, (b) their types, and
-					// (c) a minimal example call. Without these hints the
-					// downstream UI just shows a red "Failed" row and the
-					// model rarely retries with the right args.
-					const isEmptyInput =
-						rawInput === null ||
-						rawInput === undefined ||
-						(typeof rawInput === 'object' &&
-							!Array.isArray(rawInput) &&
-							Object.keys(rawInput as Record<string, unknown>).length === 0)
-
-					const requiredHint = describeRequiredInput(tool.inputSchema)
-					// A conditional schema's required shape cannot be reconstructed
-					// from JSON Schema's top-level `required`, so the author gets to
-					// say what a valid retry looks like.
-					const recoveryHint = tool.validationErrorHint?.trim()
-						? ` ${tool.validationErrorHint.trim()}`
-						: ''
-
-					const enrichedMessage = isEmptyInput
-						? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
-						: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
-
-					this.log.error('Tool input validation failed', {
-						'namzu.tool.name': toolName,
-						'namzu.registry.errors': errorMessage,
-						'namzu.registry.empty': isEmptyInput,
-					})
-
-					span.setAttributes({
-						[NAMZU.TOOL_SUCCESS]: false,
-						[NAMZU.TOOL_ERROR]: `Validation: ${errorMessage}`,
-					})
-					span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
-
-					return {
-						success: false,
-						output: '',
-						error: enrichedMessage,
-					}
-				}
-
-				const finalInput = parseResult.data
-
 				try {
 					this.log.debug('Executing tool', { 'namzu.tool.name': toolName })
 					const startedAt = Date.now()
@@ -604,7 +727,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					)
 					if (!result.success && result.error) {
 						span.setAttribute(NAMZU.TOOL_ERROR, result.error)
-						span.setStatus({ code: SpanStatusCode.ERROR, message: result.error })
+						span.setStatus({
+							code: SpanStatusCode.ERROR,
+							message: result.error,
+						})
 					} else {
 						span.setStatus({ code: SpanStatusCode.OK })
 					}
@@ -622,7 +748,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 							[NAMZU.TOOL_SUCCESS]: false,
 							[NAMZU.TOOL_ERROR]: err.message,
 						})
-						span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
+						span.setStatus({
+							code: SpanStatusCode.ERROR,
+							message: err.message,
+						})
 						throw err
 					}
 					const errorMessage = toErrorMessage(err)
@@ -635,7 +764,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						[NAMZU.TOOL_SUCCESS]: false,
 						[NAMZU.TOOL_ERROR]: errorMessage,
 					})
-					span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message: errorMessage,
+					})
 					span.recordException(err instanceof Error ? err : new Error(errorMessage))
 
 					return {
@@ -655,6 +787,40 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 		})
 	}
 
+	private validationFailure(
+		tool: ToolDefinition,
+		rawInput: unknown,
+		error: {
+			readonly issues: readonly {
+				readonly path: readonly PropertyKey[]
+				readonly message: string
+			}[]
+		},
+	): ToolExecutionResult {
+		const errorMessage = error.issues
+			.map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+			.join('; ')
+		const isEmptyInput =
+			rawInput === null ||
+			rawInput === undefined ||
+			(typeof rawInput === 'object' &&
+				!Array.isArray(rawInput) &&
+				Object.keys(rawInput as Record<string, unknown>).length === 0)
+		const requiredHint = describeRequiredInput(tool.inputSchema)
+		const recoveryHint = tool.validationErrorHint?.trim()
+			? ` ${tool.validationErrorHint.trim()}`
+			: ''
+		const enrichedMessage = isEmptyInput
+			? `Tool "${tool.name}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
+			: `Validation failed for "${tool.name}": ${errorMessage}. ${requiredHint}${recoveryHint}`
+		this.log.error('Tool input validation failed', {
+			'namzu.tool.name': tool.name,
+			'namzu.registry.errors': errorMessage,
+			'namzu.registry.empty': isEmptyInput,
+		})
+		return { success: false, output: '', error: enrichedMessage }
+	}
+
 	private getByAvailability(states: ToolAvailability[], filter?: string[]): ToolDefinition[] {
 		const candidates = filter ? filter.map((n) => this.getOrThrow(n)) : this.getAll()
 		return candidates.filter((t) => states.includes(this.getAvailability(t.name)))