pi-subagents 0.35.1 → 0.37.0

package/src/slash/delegation-adapters.ts

@@ -1,12 +1,23 @@
 import {
 	SUBAGENT_DELEGATION_PROTOCOL_VERSION,
+	SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION,
 	type SubagentDelegationAcceptanceResult,
+	type SubagentDelegationEffectsResult,
+	type SubagentDelegationExecutionResult,
 	type SubagentDelegationRequest,
 	type SubagentDelegationResponse,
+	type SubagentDelegationReviewResult,
 	type SubagentDelegationStatus,
 	type SubagentDelegationUpdate,
+	type SubagentDelegationV2Request,
+	type SubagentDelegationV2Response,
+	type SubagentDelegationV2Thinking,
+	type SubagentDelegationV2Value,
+	type SubagentDelegationV2Update,
 } from "../api/delegation.ts";
-import type { AcceptanceInput, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
+import type { AcceptanceInput, AgentContract, EffectsProjection, ExecutionProjection, JsonSchemaObject, ReviewProjection, ToolBudgetConfig, TurnBudgetConfig, Usage } from "../shared/types.ts";
+import { isAgentContractV1 } from "../runs/shared/agent-contract.ts";
+import { cloneJsonWithinByteLimit } from "./delegation-json.ts";
 
 export interface PromptTemplateDelegationTask {
 	agent: string;
@@ -86,15 +97,22 @@ export interface PromptTemplateBridgeResult {
 			exitCode?: number;
 			error?: string;
 			model?: string;
+			thinking?: string;
+			structuredOutput?: unknown;
 			interrupted?: boolean;
 			timedOut?: boolean;
 			stopped?: boolean;
 			turnBudgetExceeded?: boolean;
 			toolBudgetBlocked?: boolean;
+			structuredOutputFailed?: boolean;
 			savedOutputPath?: string;
 			sessionFile?: string;
+			agentContract?: AgentContract;
+			execution?: ExecutionProjection;
 			acceptance?: SubagentDelegationAcceptanceResult;
-			usage?: { turns?: number };
+			review?: ReviewProjection;
+			effects?: EffectsProjection;
+			usage?: Usage;
 			progressSummary?: { toolCount?: number; durationMs?: number; tokens?: number };
 			skillsWarning?: string;
 			outputSaveError?: string;
@@ -125,12 +143,20 @@ export interface DelegatedSubagentExecutionParams {
 	worktree?: boolean;
 	timeoutMs?: number;
 	turnBudget?: TurnBudgetConfig;
+	/** Internal-only strict turn-boundary enforcement for versioned foreground delegation. */
+	enforceHardTurnLimit?: boolean;
 	toolBudget?: ToolBudgetConfig;
 	skill?: string | string[] | boolean;
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
+	outputSchema?: JsonSchemaObject;
+	agentContract?: AgentContract;
 	acceptance?: AcceptanceInput;
 	artifacts?: boolean;
+	/** Internal-only thinking override accepted by executeDelegated. */
+	delegatedThinkingOverride?: SubagentDelegationV2Thinking;
+	/** Internal-only V2 capability accepted and stripped by executeDelegated. */
+	delegatedAllowZeroToolBudget?: true;
 	async: false;
 	foregroundOnly: true;
 	clarify: false;
@@ -175,8 +201,8 @@ export function parsePromptTemplateRequest(data: unknown): PromptTemplateDelegat
 	const fallbackTask = tasks[0];
 	return {
 		requestId: value.requestId,
-		agent: hasSingle ? value.agent : fallbackTask!.agent,
-		task: hasSingle ? value.task : fallbackTask!.task,
+		agent: hasSingle ? value.agent! : fallbackTask!.agent,
+		task: hasSingle ? value.task! : fallbackTask!.task,
 		...(tasks.length > 0 ? { tasks } : {}),
 		context: value.context,
 		model: value.model,
@@ -343,10 +369,13 @@ export function toSubagentDelegationExecutionParams(request: SubagentDelegationR
 		model: request.model,
 		timeoutMs: request.timeoutMs,
 		turnBudget: request.turnBudget,
+		enforceHardTurnLimit: true,
 		toolBudget: request.toolBudget,
 		skill: request.skill,
 		output: request.output,
 		outputMode: request.outputMode,
+		outputSchema: request.outputSchema,
+		agentContract: request.agentContract,
 		acceptance: request.acceptance,
 		artifacts: request.artifacts,
 		async: false,
@@ -355,6 +384,30 @@ export function toSubagentDelegationExecutionParams(request: SubagentDelegationR
 	};
 }
 
+export function toSubagentDelegationV2ExecutionParams(request: SubagentDelegationV2Request): DelegatedSubagentExecutionParams {
+	return {
+		agent: request.agent,
+		task: request.task,
+		context: request.context,
+		cwd: request.cwd,
+		model: request.model,
+		timeoutMs: request.timeoutMs,
+		turnBudget: request.turnBudget,
+		enforceHardTurnLimit: true,
+		toolBudget: request.toolBudget,
+		skill: request.skill,
+		output: false,
+		...(request.result.kind === "structured" ? { outputSchema: request.result.schema } : {}),
+		acceptance: false,
+		artifacts: request.artifacts,
+		delegatedThinkingOverride: request.thinking,
+		delegatedAllowZeroToolBudget: true,
+		async: false,
+		foregroundOnly: true,
+		clarify: false,
+	};
+}
+
 export function toSubagentDelegationUpdate(requestId: string, result: PromptTemplateBridgeResult): SubagentDelegationUpdate | undefined {
 	const legacy = toDelegationUpdate(requestId, result);
 	if (!legacy) return undefined;
@@ -373,6 +426,29 @@ export function toSubagentDelegationUpdate(requestId: string, result: PromptTemp
 	};
 }
 
+export function toSubagentDelegationV2Update(
+	request: SubagentDelegationV2Request,
+	result: PromptTemplateBridgeResult,
+): SubagentDelegationV2Update | undefined {
+	const legacy = toDelegationUpdate(request.requestId, result);
+	if (!legacy) return undefined;
+	return {
+		version: SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION,
+		requestId: request.requestId,
+		ownerRunId: request.ownerRunId,
+		nodeId: request.nodeId,
+		...(legacy.currentTool ? { currentTool: legacy.currentTool } : {}),
+		...(legacy.currentToolArgs ? { currentToolArgs: legacy.currentToolArgs } : {}),
+		...(legacy.recentOutput ? { recentOutput: legacy.recentOutput } : {}),
+		...(legacy.recentOutputLines ? { recentOutputLines: legacy.recentOutputLines } : {}),
+		...(legacy.recentTools ? { recentTools: legacy.recentTools } : {}),
+		...(legacy.model ? { model: legacy.model } : {}),
+		...(typeof legacy.toolCount === "number" ? { toolCount: legacy.toolCount } : {}),
+		...(typeof legacy.durationMs === "number" ? { durationMs: legacy.durationMs } : {}),
+		...(typeof legacy.tokens === "number" ? { tokens: legacy.tokens } : {}),
+	};
+}
+
 function resolveSubagentDelegationStatus(
 	result: PromptTemplateBridgeResult,
 	aborted: boolean,
@@ -381,9 +457,10 @@ function resolveSubagentDelegationStatus(
 	const child = result.details?.results?.[0];
 	if (!child) return "failed";
 	if (result.details?.timedOut || child.timedOut) return "timed_out";
+	if (child?.structuredOutputFailed) return "structured_output_failed";
 	if (child?.turnBudgetExceeded) return "turn_budget_exhausted";
 	if (child?.toolBudgetBlocked) return "tool_budget_exhausted";
-	if (child?.acceptance?.status === "rejected" && child.acceptance.explicit) return "acceptance_failed";
+	if (!isAgentContractV1(child.agentContract) && child?.acceptance?.status === "rejected" && child.acceptance.explicit) return "acceptance_failed";
 	if (result.details?.stopped || child?.stopped || child?.interrupted) return "interrupted";
 	if (result.isError || child?.error || (typeof child?.exitCode === "number" && child.exitCode !== 0)) return "failed";
 	return "completed";
@@ -410,10 +487,13 @@ export function toSubagentDelegationResponse(
 		...(child?.agent ? { agent: child.agent } : {}),
 		...(child?.model ? { model: child.model } : {}),
 		...(typeof child?.exitCode === "number" ? { exitCode: child.exitCode } : {}),
+		...(child?.execution ? { execution: child.execution as SubagentDelegationExecutionResult } : {}),
 		...(child?.finalOutput ? { output: child.finalOutput } : {}),
 		...(child?.savedOutputPath ? { outputPath: child.savedOutputPath } : {}),
 		...(child?.sessionFile ? { sessionFile: child.sessionFile } : {}),
-		...(child?.acceptance ? { acceptance: { status: child.acceptance.status, explicit: child.acceptance.explicit } } : {}),
+		...(child?.acceptance ? { acceptance: { status: child.acceptance.status, evidenceStatus: child.acceptance.evidenceStatus, explicit: child.acceptance.explicit } } : {}),
+		...(child?.review ? { review: child.review as SubagentDelegationReviewResult } : {}),
+		...(child?.effects ? { effects: child.effects as SubagentDelegationEffectsResult } : {}),
 		...(typeof child?.usage?.turns === "number" ? { turns: child.usage.turns } : {}),
 		...(typeof progress?.toolCount === "number" ? { toolCount: progress.toolCount } : {}),
 		...(typeof progress?.durationMs === "number" ? { durationMs: progress.durationMs } : {}),
@@ -422,6 +502,73 @@ export function toSubagentDelegationResponse(
 	};
 }
 
+const MAX_V2_RESULT_BYTES = 1024 * 1024;
+
+export function toSubagentDelegationV2Response(
+	request: SubagentDelegationV2Request,
+	result: PromptTemplateBridgeResult,
+	aborted: boolean,
+): SubagentDelegationV2Response {
+	const child = result.details?.results?.[0];
+	const progress = child?.progressSummary ?? result.details?.progress?.[0];
+	let status = resolveSubagentDelegationStatus(result, aborted);
+	let error = child?.error ?? (status === "failed" ? firstTextContent(result.content) : undefined);
+	let projectedResult: SubagentDelegationV2Value | undefined;
+	if (status === "completed") {
+		if (request.result.kind === "text") {
+			if (typeof child?.finalOutput !== "string") {
+				status = "failed";
+				error = "Delegated subagent did not capture a text result.";
+			} else if (Buffer.byteLength(child.finalOutput, "utf8") > MAX_V2_RESULT_BYTES) {
+				status = "failed";
+				error = "Delegated text result exceeds 1 MiB when UTF-8 encoded.";
+			} else {
+				projectedResult = { kind: "text", text: child.finalOutput };
+			}
+		} else if (child?.structuredOutput === undefined) {
+			status = "failed";
+			error = "Delegated subagent did not capture the requested structured result.";
+		} else {
+			const inspected = cloneJsonWithinByteLimit(child.structuredOutput, MAX_V2_RESULT_BYTES);
+			if (!inspected.ok) {
+				status = "failed";
+				error = inspected.reason === "too_large"
+					? "Delegated structured result exceeds 1 MiB when encoded."
+					: "Delegated structured result is not plain JSON data.";
+			} else {
+				projectedResult = { kind: "structured", value: inspected.value };
+			}
+		}
+	}
+	const usage = child?.usage;
+	return {
+		version: SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION,
+		requestId: request.requestId,
+		ownerRunId: request.ownerRunId,
+		nodeId: request.nodeId,
+		status,
+		...(error ? { error } : {}),
+		...(result.details?.runId ? { runId: result.details.runId } : {}),
+		...(child?.agent ? { agent: child.agent } : {}),
+		...(child?.model ? { model: child.model } : {}),
+		...(child?.thinking ? { thinking: child.thinking } : {}),
+		...(typeof child?.exitCode === "number" ? { exitCode: child.exitCode } : {}),
+		...(projectedResult ? { result: projectedResult } : {}),
+		...(usage ? {
+			usage: {
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				cost: usage.cost,
+				turns: usage.turns,
+				toolCalls: progress?.toolCount ?? 0,
+				durationMs: progress?.durationMs ?? 0,
+			},
+		} : {}),
+	};
+}
+
 export function toPromptTemplateResponse(
 	request: PromptTemplateDelegationRequest,
 	result: PromptTemplateBridgeResult,

package/src/slash/delegation-json.ts

@@ -0,0 +1,108 @@
+const MAX_JSON_DEPTH = 64;
+const MAX_JSON_ENTRIES = 100_000;
+
+export type BoundedJsonClone =
+	| { ok: true; value: unknown; encodedBytes: number }
+	| { ok: false; reason: "invalid" | "too_large" };
+
+/** Clone plain JSON data without invoking getters or toJSON hooks. */
+export function cloneJsonWithinByteLimit(input: unknown, maxBytes: number): BoundedJsonClone {
+	let minimumBytes = 0;
+	let entries = 0;
+	const active = new WeakSet<object>();
+
+	const addMinimumBytes = (bytes: number): void => {
+		minimumBytes += bytes;
+		if (minimumBytes > maxBytes) throw new RangeError("too_large");
+	};
+
+	const visit = (value: unknown, depth: number): unknown => {
+		if (depth > MAX_JSON_DEPTH) throw new TypeError("invalid");
+		if (value === null) {
+			addMinimumBytes(4);
+			return null;
+		}
+		if (typeof value === "boolean") {
+			addMinimumBytes(value ? 4 : 5);
+			return value;
+		}
+		if (typeof value === "number") {
+			if (!Number.isFinite(value)) throw new TypeError("invalid");
+			const encoded = JSON.stringify(Object.is(value, -0) ? 0 : value);
+			addMinimumBytes(Buffer.byteLength(encoded, "utf8"));
+			return Object.is(value, -0) ? 0 : value;
+		}
+		if (typeof value === "string") {
+			// Quoting and escaping can only increase the encoded size.
+			addMinimumBytes(Buffer.byteLength(value, "utf8") + 2);
+			return value;
+		}
+		if (typeof value !== "object") throw new TypeError("invalid");
+
+		const object = value as object;
+		if (active.has(object)) throw new TypeError("invalid");
+		active.add(object);
+		try {
+			const prototype = Object.getPrototypeOf(object);
+			const keys = Reflect.ownKeys(object);
+			if (Array.isArray(object)) {
+				if (prototype !== Array.prototype) throw new TypeError("invalid");
+				const lengthDescriptor = Object.getOwnPropertyDescriptor(object, "length");
+				if (!lengthDescriptor || !("value" in lengthDescriptor) || !Number.isSafeInteger(lengthDescriptor.value) || lengthDescriptor.value < 0) {
+					throw new TypeError("invalid");
+				}
+				const length = lengthDescriptor.value as number;
+				addMinimumBytes(2 + Math.max(0, length - 1));
+				const output: unknown[] = [];
+				for (const key of keys) {
+					if (typeof key === "symbol") throw new TypeError("invalid");
+					if (key === "length") continue;
+					if (!/^(?:0|[1-9][0-9]*)$/.test(key) || Number(key) >= length) throw new TypeError("invalid");
+				}
+				for (let index = 0; index < length; index++) {
+					const descriptor = Object.getOwnPropertyDescriptor(object, String(index));
+					if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) throw new TypeError("invalid");
+					entries++;
+					if (entries > MAX_JSON_ENTRIES) throw new TypeError("invalid");
+					output.push(visit(descriptor.value, depth + 1));
+				}
+				return output;
+			}
+
+			if (prototype !== Object.prototype && prototype !== null) throw new TypeError("invalid");
+			addMinimumBytes(2 + Math.max(0, keys.length - 1));
+			const output: Record<string, unknown> = {};
+			for (const key of keys) {
+				if (typeof key === "symbol") throw new TypeError("invalid");
+				const descriptor = Object.getOwnPropertyDescriptor(object, key);
+				if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) throw new TypeError("invalid");
+				entries++;
+				if (entries > MAX_JSON_ENTRIES) throw new TypeError("invalid");
+				addMinimumBytes(Buffer.byteLength(JSON.stringify(key), "utf8") + 1);
+				Object.defineProperty(output, key, {
+					value: visit(descriptor.value, depth + 1),
+					enumerable: true,
+					configurable: true,
+					writable: true,
+				});
+			}
+			return output;
+		} finally {
+			active.delete(object);
+		}
+	};
+
+	try {
+		const value = visit(input, 0);
+		const encoded = JSON.stringify(value);
+		if (encoded === undefined) return { ok: false, reason: "invalid" };
+		const encodedBytes = Buffer.byteLength(encoded, "utf8");
+		if (encodedBytes > maxBytes) return { ok: false, reason: "too_large" };
+		return { ok: true, value, encodedBytes };
+	} catch (error) {
+		return {
+			ok: false,
+			reason: error instanceof RangeError && error.message === "too_large" ? "too_large" : "invalid",
+		};
+	}
+}

package/src/slash/delegation-request.ts

@@ -1,16 +1,19 @@
 import {
 	SUBAGENT_DELEGATION_PROTOCOL_VERSION,
+	SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION,
 	type SubagentDelegationRequest,
+	type SubagentDelegationV2Request,
 } from "../api/delegation.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
 import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
+import { cloneJsonWithinByteLimit } from "./delegation-json.ts";
 
 export type SubagentDelegationParseResult =
-	| { ok: true; request: SubagentDelegationRequest }
-	| { ok: false; requestId?: string; error: string };
+	| { ok: true; request: SubagentDelegationRequest | SubagentDelegationV2Request }
+	| { ok: false; version?: 1 | 2; requestId?: string; ownerRunId?: string; nodeId?: string; error: string };
 
-const supportedFields = new Set([
+const v1SupportedFields = new Set([
 	"version",
 	"requestId",
 	"agent",
@@ -24,67 +27,178 @@ const supportedFields = new Set([
 	"skill",
 	"output",
 	"outputMode",
+	"outputSchema",
+	"agentContract",
 	"acceptance",
 	"artifacts",
 ]);
 
+const v2SupportedFields = new Set([
+	"version",
+	"requestId",
+	"ownerRunId",
+	"nodeId",
+	"agent",
+	"task",
+	"context",
+	"cwd",
+	"model",
+	"thinking",
+	"timeoutMs",
+	"turnBudget",
+	"toolBudget",
+	"skill",
+	"artifacts",
+	"result",
+]);
+
+const v2ThinkingLevels = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const MAX_SCHEMA_BYTES = 64 * 1024;
+const MAX_V2_TASK_BYTES = 1024 * 1024;
+const MAX_V2_CWD_BYTES = 32 * 1024;
+const MAX_V2_SHORT_TEXT_BYTES = 1024;
+const MAX_V2_SKILL_ENTRIES = 256;
+const MAX_V2_SKILL_AGGREGATE_BYTES = 64 * 1024;
+
 function nonEmptyString(value: unknown): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
 
-function validateRequestId(value: unknown): string | undefined {
+function validateId(value: unknown): string | undefined {
 	if (!nonEmptyString(value) || value.length > 256 || /[\r\n]/.test(value)) return undefined;
 	return value;
 }
 
-export function parseSubagentDelegationRequest(data: unknown): SubagentDelegationParseResult {
-	if (!data || typeof data !== "object" || Array.isArray(data)) {
-		return { ok: false, error: "Delegation request must be an object." };
-	}
-	const value = data as Record<string, unknown>;
-	const requestId = validateRequestId(value.requestId);
-	if (value.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION) {
-		return {
-			...(requestId ? { requestId } : {}),
-			ok: false,
-			error: `Unsupported delegation protocol version: ${String(value.version)}.`,
-		};
-	}
-	if (!requestId) {
-		return { ok: false, error: "Delegation requestId must be a non-empty string of at most 256 characters without newlines." };
-	}
-	const unsupportedField = Object.keys(value).find((key) => !supportedFields.has(key));
-	if (unsupportedField) return { ok: false, requestId, error: `Unsupported delegation field: ${unsupportedField}.` };
-	if (!nonEmptyString(value.agent)) return { ok: false, requestId, error: "Delegation agent must be a non-empty string." };
-	if (!nonEmptyString(value.task)) return { ok: false, requestId, error: "Delegation task must be a non-empty string." };
+function validateSharedFields(
+	value: Record<string, unknown>,
+	identity: { requestId: string; version?: 1 | 2; ownerRunId?: string; nodeId?: string },
+): SubagentDelegationParseResult | undefined {
+	if (!nonEmptyString(value.agent)) return { ok: false, ...identity, error: "Delegation agent must be a non-empty string." };
+	if (!nonEmptyString(value.task)) return { ok: false, ...identity, error: "Delegation task must be a non-empty string." };
 	if (value.context !== "fresh" && value.context !== "fork") {
-		return { ok: false, requestId, error: "Delegation context must be fresh or fork." };
+		return { ok: false, ...identity, error: "Delegation context must be fresh or fork." };
 	}
-	if (!nonEmptyString(value.cwd)) return { ok: false, requestId, error: "Delegation cwd must be a non-empty string." };
+	if (!nonEmptyString(value.cwd)) return { ok: false, ...identity, error: "Delegation cwd must be a non-empty string." };
 	if (value.model !== undefined && !nonEmptyString(value.model)) {
-		return { ok: false, requestId, error: "model must be a non-empty string when provided." };
+		return { ok: false, ...identity, error: "model must be a non-empty string when provided." };
 	}
 	if (value.timeoutMs !== undefined && (typeof value.timeoutMs !== "number" || !Number.isInteger(value.timeoutMs) || value.timeoutMs < 1)) {
-		return { ok: false, requestId, error: "timeoutMs must be an integer >= 1." };
+		return { ok: false, ...identity, error: "timeoutMs must be an integer >= 1." };
+	}
+	if (identity.version === SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION && value.timeoutMs !== undefined && value.timeoutMs > 2_147_483_647) {
+		return { ok: false, ...identity, error: "timeoutMs must be <= 2147483647 for delegation v2." };
 	}
 	const turnBudget = resolveTurnBudgetConfig(value.turnBudget);
-	if (turnBudget.error) return { ok: false, requestId, error: turnBudget.error };
+	if (turnBudget.error) return { ok: false, ...identity, error: turnBudget.error };
 	if (value.toolBudget && typeof value.toolBudget === "object" && !Array.isArray(value.toolBudget)) {
 		const unsupportedToolBudgetField = Object.keys(value.toolBudget).find((key) => key !== "soft" && key !== "hard" && key !== "block");
 		if (unsupportedToolBudgetField) {
-			return { ok: false, requestId, error: `toolBudget.${unsupportedToolBudgetField} is not supported.` };
+			return { ok: false, ...identity, error: `toolBudget.${unsupportedToolBudgetField} is not supported.` };
 		}
 	}
-	const toolBudget = validateToolBudgetConfig(value.toolBudget);
-	if (toolBudget.error) return { ok: false, requestId, error: toolBudget.error };
+	const toolBudget = validateToolBudgetConfig(
+		value.toolBudget,
+		"toolBudget",
+		identity.version === SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION ? { minimumHard: 0 } : undefined,
+	);
+	if (toolBudget.error) return { ok: false, ...identity, error: toolBudget.error };
 	if (value.skill !== undefined) {
 		const validSkill = typeof value.skill === "boolean"
 			|| nonEmptyString(value.skill)
 			|| (Array.isArray(value.skill) && value.skill.length > 0 && value.skill.every(nonEmptyString));
 		if (!validSkill) {
-			return { ok: false, requestId, error: "skill must be a boolean, non-empty string, or non-empty string array." };
+			return { ok: false, ...identity, error: "skill must be a boolean, non-empty string, or non-empty string array." };
+		}
+	}
+	if (value.artifacts !== undefined && typeof value.artifacts !== "boolean") {
+		return { ok: false, ...identity, error: "artifacts must be a boolean." };
+	}
+	return undefined;
+}
+
+function parseV2(value: Record<string, unknown>, requestId: string): SubagentDelegationParseResult {
+	const ownerRunId = validateId(value.ownerRunId);
+	if (!ownerRunId) {
+		return { ok: false, version: 2, requestId, error: "Delegation ownerRunId must be a non-empty string of at most 256 characters without newlines." };
+	}
+	const nodeId = validateId(value.nodeId);
+	if (!nodeId) {
+		return { ok: false, version: 2, requestId, ownerRunId, error: "Delegation nodeId must be a non-empty string of at most 256 characters without newlines." };
+	}
+	const identity = { version: 2 as const, requestId, ownerRunId, nodeId };
+	const unsupportedField = Object.keys(value).find((key) => !v2SupportedFields.has(key));
+	if (unsupportedField) return { ok: false, ...identity, error: `Unsupported delegation field: ${unsupportedField}.` };
+	const sharedError = validateSharedFields(value, identity);
+	if (sharedError) return sharedError;
+	if (Buffer.byteLength(value.task as string, "utf8") > MAX_V2_TASK_BYTES) {
+		return { ok: false, ...identity, error: "Delegation task exceeds 1 MiB when UTF-8 encoded." };
+	}
+	if (Buffer.byteLength(value.cwd as string, "utf8") > MAX_V2_CWD_BYTES) {
+		return { ok: false, ...identity, error: "Delegation cwd exceeds 32 KiB when UTF-8 encoded." };
+	}
+	if (Buffer.byteLength(value.agent as string, "utf8") > MAX_V2_SHORT_TEXT_BYTES) {
+		return { ok: false, ...identity, error: "Delegation agent exceeds 1 KiB when UTF-8 encoded." };
+	}
+	if (typeof value.model === "string" && Buffer.byteLength(value.model, "utf8") > MAX_V2_SHORT_TEXT_BYTES) {
+		return { ok: false, ...identity, error: "Delegation model exceeds 1 KiB when UTF-8 encoded." };
+	}
+	const skillEntries = typeof value.skill === "string" ? [value.skill] : Array.isArray(value.skill) ? value.skill as string[] : [];
+	if (skillEntries.length > MAX_V2_SKILL_ENTRIES) {
+		return { ok: false, ...identity, error: "Delegation skill supports at most 256 entries." };
+	}
+	if (skillEntries.some((entry) => Buffer.byteLength(entry, "utf8") > MAX_V2_SHORT_TEXT_BYTES)) {
+		return { ok: false, ...identity, error: "Delegation skill entry exceeds 1 KiB when UTF-8 encoded." };
+	}
+	if (skillEntries.reduce((total, entry) => total + Buffer.byteLength(entry, "utf8"), 0) > MAX_V2_SKILL_AGGREGATE_BYTES) {
+		return { ok: false, ...identity, error: "Delegation skill entries exceed 64 KiB in aggregate when UTF-8 encoded." };
+	}
+	if (value.thinking !== undefined && (typeof value.thinking !== "string" || !v2ThinkingLevels.has(value.thinking))) {
+		return { ok: false, ...identity, error: "thinking must be one of off, minimal, low, medium, high, xhigh, or max." };
+	}
+	if (!value.result || typeof value.result !== "object" || Array.isArray(value.result)) {
+		return { ok: false, ...identity, error: "result must be { kind: \"text\" } or { kind: \"structured\", schema: object }." };
+	}
+	const result = value.result as Record<string, unknown>;
+	let structuredSchema: Record<string, unknown> | undefined;
+	if (result.kind === "text") {
+		const unsupportedResultField = Object.keys(result).find((key) => key !== "kind");
+		if (unsupportedResultField) return { ok: false, ...identity, error: `result.${unsupportedResultField} is not supported for text results.` };
+	} else if (result.kind === "structured") {
+		const unsupportedResultField = Object.keys(result).find((key) => key !== "kind" && key !== "schema");
+		if (unsupportedResultField) return { ok: false, ...identity, error: `result.${unsupportedResultField} is not supported for structured results.` };
+		if (!result.schema || typeof result.schema !== "object" || Array.isArray(result.schema)) {
+			return { ok: false, ...identity, error: "result.schema must be a JSON Schema object." };
+		}
+		const inspectedSchema = cloneJsonWithinByteLimit(result.schema, MAX_SCHEMA_BYTES);
+		if (!inspectedSchema.ok) {
+			return {
+				ok: false,
+				...identity,
+				error: inspectedSchema.reason === "too_large"
+					? "result.schema exceeds 64 KiB when encoded."
+					: "result.schema must be plain JSON data.",
+			};
 		}
+		structuredSchema = inspectedSchema.value as Record<string, unknown>;
+	} else {
+		return { ok: false, ...identity, error: "result.kind must be text or structured." };
 	}
+	return {
+		ok: true,
+		request: {
+			...value,
+			result: structuredSchema
+				? { kind: "structured", schema: structuredSchema }
+				: { kind: "text" },
+		} as unknown as SubagentDelegationV2Request,
+	};
+}
+
+function parseV1(value: Record<string, unknown>, requestId: string): SubagentDelegationParseResult {
+	const unsupportedField = Object.keys(value).find((key) => !v1SupportedFields.has(key));
+	if (unsupportedField) return { ok: false, requestId, error: `Unsupported delegation field: ${unsupportedField}.` };
+	const sharedError = validateSharedFields(value, { requestId });
+	if (sharedError) return sharedError;
 	if (value.output !== undefined && typeof value.output !== "boolean" && !nonEmptyString(value.output)) {
 		return { ok: false, requestId, error: "output must be a boolean or non-empty string." };
 	}
@@ -94,10 +208,42 @@ export function parseSubagentDelegationRequest(data: unknown): SubagentDelegatio
 	if (value.outputMode === "file-only" && !nonEmptyString(value.output)) {
 		return { ok: false, requestId, error: 'outputMode "file-only" requires output to be a non-empty path.' };
 	}
+	if (value.outputSchema !== undefined && (!value.outputSchema || typeof value.outputSchema !== "object" || Array.isArray(value.outputSchema))) {
+		return { ok: false, requestId, error: "outputSchema must be a JSON Schema object." };
+	}
+	if (value.agentContract !== undefined) {
+		if (!value.agentContract || typeof value.agentContract !== "object" || Array.isArray(value.agentContract)) return { ok: false, requestId, error: "agentContract must be an object." };
+		const contract = value.agentContract as Record<string, unknown>;
+		if (contract.version !== 1 || Object.keys(contract).some((key) => key !== "version")) return { ok: false, requestId, error: "agentContract must be { version: 1 }." };
+	}
 	const acceptanceErrors = validateAcceptanceInput(value.acceptance);
 	if (acceptanceErrors.length > 0) return { ok: false, requestId, error: acceptanceErrors.join(" ") };
-	if (value.artifacts !== undefined && typeof value.artifacts !== "boolean") {
-		return { ok: false, requestId, error: "artifacts must be a boolean." };
-	}
 	return { ok: true, request: value as unknown as SubagentDelegationRequest };
 }
+
+export function parseSubagentDelegationRequest(data: unknown): SubagentDelegationParseResult {
+	if (!data || typeof data !== "object" || Array.isArray(data)) {
+		return { ok: false, error: "Delegation request must be an object." };
+	}
+	const value = data as Record<string, unknown>;
+	const requestId = validateId(value.requestId);
+	if (value.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION && value.version !== SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION) {
+		return {
+			...(requestId ? { requestId } : {}),
+			ok: false,
+			error: `Unsupported delegation protocol version: ${String(value.version)}.`,
+		};
+	}
+	if (!requestId) {
+		return { ok: false, error: "Delegation requestId must be a non-empty string of at most 256 characters without newlines." };
+	}
+	if (value.version === SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION) {
+		// Preserve the v1 parser's historical diagnostic for a v1-shaped payload
+		// whose version alone was changed to 2.
+		if (!Object.hasOwn(value, "ownerRunId") && !Object.hasOwn(value, "nodeId") && !Object.hasOwn(value, "result")) {
+			return { ok: false, version: 2, requestId, error: "Unsupported delegation protocol version: 2." };
+		}
+		return parseV2(value, requestId);
+	}
+	return parseV1(value, requestId);
+}