@namzu/sdk 18.1.0 → 20.0.0

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