@namzu/sdk 19.0.0 → 20.0.0

package/src/runtime/query/executor.ts

@@ -144,6 +144,20 @@ export interface ToolExecutorConfig {
 	repairToolCall?: RepairToolCall
 }
 
+/**
+ * What a `post_tool_use` hook decided to show the model instead.
+ *
+ * `isError` is the field this type exists for. The override used to be a bare
+ * string, so the executor had no way to tell "the call failed" from "the call
+ * succeeded and the model may not see all of it" — and it assumed the first,
+ * which turned every redaction into a reported tool failure.
+ */
+interface PostToolOverride {
+	readonly output: string
+	readonly isError: boolean
+	readonly content?: ToolResultContent
+}
+
 type PreToolHookOutcome =
 	| { kind: 'continue'; input: unknown }
 	| { kind: 'skip'; input: unknown; output: string }
@@ -708,10 +722,14 @@ export class ToolExecutor {
 
 		const postOverride = post.override
 		if (postOverride !== null) {
-			output = postOverride
+			output = postOverride.output
 		}
 
-		const effectiveIsError = !result.success || postOverride !== null
+		// A failed call, or an override that says the call failed. A `replace`
+		// says the opposite, and reading it as a failure is what made redaction
+		// unusable: the model was told a successful call had gone wrong, and
+		// routed around it.
+		const effectiveIsError = !result.success || (postOverride?.isError ?? false)
 
 		if (this.workingStateManager) {
 			extractFromToolResult(this.workingStateManager, toolName, output, effectiveIsError)
@@ -756,17 +774,31 @@ export class ToolExecutor {
 			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
 		})
 
+		const resolveContent = (): { content?: ToolResultContent } => {
+			if (postOverride?.content !== undefined) {
+				return { content: this.budgetContent(postOverride.content, toolName) }
+			}
+			if (postOverride?.isError) return {}
+			if (budgeted.truncated || result.content === undefined) return {}
+			return { content: this.budgetContent(result.content, toolName) }
+		}
+
 		return {
 			toolCallId: toolCall.id,
 			toolName,
 			output,
 			isError: effectiveIsError,
-			// A plugin override replaces what the model sees, and a spilled
-			// preview is no longer the tool's own payload — neither may carry
-			// rich content through.
-			...(result.content !== undefined && postOverride === null && !budgeted.truncated
-				? { content: this.budgetContent(result.content, toolName) }
-				: {}),
+			// Rich content follows the override's own decision.
+			//
+			// An ERROR override drops it: the payload is no longer the tool's,
+			// and shipping an image beside a failure message describes something
+			// the model was just told did not happen. A spilled preview drops it
+			// for the same reason.
+			//
+			// A REPLACE keeps it, because the common case is redacting text from
+			// a result whose image is unaffected — and a hook that needs it gone
+			// says so with `content`, which wins over both.
+			...resolveContent(),
 		}
 	}
 
@@ -919,6 +951,11 @@ export class ToolExecutor {
 						output: `Error: ${result.message}`,
 					}
 				case 'retry':
+				// There is no result to replace yet. Rejecting loudly beats
+				// silently ignoring it: a hook author who returned this here
+				// meant to redact something and would otherwise watch the secret
+				// go through.
+				case 'replace':
 					throw new Error(
 						`Plugin hook pre_tool_use returned unsupported action '${result.action}' for tool ${toolName}`,
 					)
@@ -1120,21 +1157,32 @@ export class ToolExecutor {
 		toolName: string,
 		input: unknown,
 		toolResult: ToolResult,
-	): Promise<{ override: string | null; retry: boolean }> {
+	): Promise<{ override: PostToolOverride | null; retry: boolean }> {
 		if (!this.config.pluginManager) return { override: null, retry: false }
 		const results = await this.config.pluginManager.executeHooks(
 			'post_tool_use',
 			{ runId: this.config.runId, toolName, toolInput: input, toolResult },
 			this.emitEvent,
 		)
-		let override: string | null = null
+		let override: PostToolOverride | null = null
 		let retry = false
 		for (const result of results) {
 			switch (result.action) {
 				case 'continue':
 					continue
 				case 'error':
-					override = `Error: ${result.message}`
+					override = { output: `Error: ${result.message}`, isError: true }
+					continue
+				// A redaction, not a failure. The call stood; the model is shown
+				// less of it. Rich content survives unless the hook replaced it —
+				// see the variant's own documentation for why that default, and
+				// for what a hook redacting a secret in an image has to do.
+				case 'replace':
+					override = {
+						output: result.output,
+						isError: false,
+						...(result.content !== undefined ? { content: result.content } : {}),
+					}
 					continue
 				// `retry` was a declared variant with no implementation: every
 				// site that consumed it threw. Here it finally means something

package/src/runtime/query/plugin-hooks.ts

@@ -26,6 +26,7 @@ export function applyLifecycleHookResults(
 			case 'skip':
 			case 'modify':
 			case 'retry':
+			case 'replace':
 				throw new Error(
 					`Plugin hook ${event} returned unsupported action '${result.action}' for a lifecycle event`,
 				)

package/src/store/run/disk.ts

@@ -136,6 +136,12 @@ export class RunDiskStore {
 			messageCount: run.messages.length,
 		}
 
+		// The schema-validated answer belongs in the durable record for the same
+		// reason `result` does: a run reloaded by id that has lost its answer has
+		// lost the thing it was run for. Written only when present, so a run that
+		// asked for no schema carries no key rather than an explicit `undefined`.
+		if (run.structuredOutput !== undefined) meta.structuredOutput = run.structuredOutput
+
 		if (run.parentRunId) meta.parentRunId = run.parentRunId
 		if (run.depth !== undefined && run.depth > 0) meta.depth = run.depth
 

package/src/tools/coordinator/agent.ts

@@ -175,12 +175,27 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 			// the other one.
 			const succeeded = taskSucceeded(completed)
 
+			// A schema-configured child answers with an OBJECT, and this used to
+			// hand the parent model the child's prose instead — so a supervisor
+			// fanning out to five specialists got five strings and had to
+			// re-parse what it had just caused to be serialized.
+			//
+			// `structuredOutput` wins over `result` when present, and reading it
+			// first is what makes that true. They agree by construction anyway:
+			// `setStructuredOutput` serializes the value into `result`, so this
+			// preference is about which field is authoritative rather than about
+			// which string is produced.
+			const structured = completed.result?.structuredOutput
 			const resultText =
-				typeof completed.result?.result === 'string'
-					? completed.result.result
-					: completed.result?.result !== undefined
-						? JSON.stringify(completed.result.result)
-						: ''
+				structured !== undefined
+					? typeof structured === 'string'
+						? structured
+						: JSON.stringify(structured)
+					: typeof completed.result?.result === 'string'
+						? completed.result.result
+						: completed.result?.result !== undefined
+							? JSON.stringify(completed.result.result)
+							: ''
 
 			if (!succeeded) {
 				const detail =

package/src/tools/coordinator/index.ts

@@ -288,6 +288,26 @@ function readPositiveIntEnv(key: string, fallback: number): number {
 	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
 }
 
+/**
+ * The answer a delegated child produced, as the string a parent model reads.
+ *
+ * One function because two delegation surfaces ask the same question, and the
+ * comment on the other one records what happens when a rule lives at one site
+ * only: create_task shipped without the success check that agent already had.
+ *
+ * A schema-configured child answers with an object. Reading structuredOutput
+ * first is what stops a supervisor receiving prose it then has to re-parse.
+ */
+function delegatedAnswer(
+	result: { structuredOutput?: unknown; result?: string } | undefined,
+): string | undefined {
+	const structured = result?.structuredOutput
+	if (structured !== undefined) {
+		return typeof structured === 'string' ? structured : JSON.stringify(structured)
+	}
+	return result?.result
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -614,7 +634,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// the work had been done.
 			const success = taskSucceeded(completed)
 			const resultText =
-				completed.result?.result ??
+				delegatedAnswer(completed.result) ??
 				completed.result?.lastError ??
 				`Task finished with state: ${failureLabel(completed)}`
 
@@ -744,7 +764,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 			const success = completed.state === 'completed'
 			const resultText =
-				completed.result?.result ??
+				delegatedAnswer(completed.result) ??
 				completed.result?.lastError ??
 				`Task finished with state: ${completed.state}`
 			return {

package/src/types/agent/base.ts

@@ -186,6 +186,26 @@ export interface BaseAgentResult {
 	durationMs: number
 	messages: Message[]
 	result?: string
+	/**
+	 * The schema-validated answer, when the run was configured to produce one.
+	 *
+	 * `Run.structuredOutput` has carried this all along and every ergonomic
+	 * boundary above it dropped the value three lines from its caller: an
+	 * archetype's result literal did not copy it, `runAgent` did not even
+	 * forward the config that produces it, and both delegation tools handed a
+	 * parent the child's prose. So a supervisor fanning out to five
+	 * schema-configured specialists received five strings and had to make the
+	 * model re-parse what it had just caused to be serialized.
+	 *
+	 * `unknown` rather than a generic, deliberately. The schema lives on the
+	 * run's config and a result type parameter would have to be threaded
+	 * through every archetype, both delegation tools and the task record to
+	 * reach here — and at the delegation boundary the parent does not hold the
+	 * child's schema anyway, so the parameter would be `unknown` again at the
+	 * only place it was wanted. Narrow it at the call site with the schema you
+	 * already have.
+	 */
+	structuredOutput?: unknown
 	lastError?: string
 }
 

package/src/types/plugin/index.ts

@@ -9,7 +9,7 @@ import {
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
 import type { PluginId, RunId } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import type { Message, ToolResultContent } from '../message/index.js'
 import type { ToolResult } from '../tool/index.js'
 
 // ---------------------------------------------------------------------------
@@ -191,6 +191,31 @@ export type PluginHookResult =
 	| { action: 'modify'; input: unknown }
 	| { action: 'error'; message: string }
 	| { action: 'retry' }
+	/**
+	 * Replace what the model sees, WITHOUT reporting the call as failed.
+	 *
+	 * The substitution seam already existed and was typed as a failure channel:
+	 * the only way a `post_tool_use` hook could change the output was
+	 * `action: 'error'`, which prefixes `Error: ` and sets the error flag. So
+	 * redacting a credential out of a successful result was delivered to the
+	 * model as a tool failure, and the model routed around a call that had
+	 * worked — retrying it, or reporting to the user that it had failed.
+	 *
+	 * That is the difference this variant exists for. `error` says the call went
+	 * wrong; this says the call went right and the model may not see all of it.
+	 *
+	 * `modify` is not this. It carries `input` and belongs to the pre-call
+	 * hooks, which is why `post_tool_use` rejects it — a result is not an input,
+	 * and reusing the variant would have made one action mean two things
+	 * depending on where it was returned.
+	 *
+	 * Rich content blocks SURVIVE a replace unless `content` is given, because
+	 * the common case is redacting text from a result whose image or resource
+	 * is unaffected. A hook that needs to drop them passes `content: []`, and a
+	 * hook redacting a secret that also appears in an image must — this variant
+	 * cannot inspect what it is preserving.
+	 */
+	| { action: 'replace'; output: string; content?: ToolResultContent }
 
 export function assertPluginHookResult(result: PluginHookResult): asserts result {
 	const action = result.action
@@ -200,6 +225,7 @@ export function assertPluginHookResult(result: PluginHookResult): asserts result
 		case 'modify':
 		case 'error':
 		case 'retry':
+		case 'replace':
 			break
 		default: {
 			const _exhaustive: never = action