@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/semantic-snapshot.ts

@@ -0,0 +1,214 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const SEMANTIC_SNAPSHOT_VERSION = "pi-subagents:semantic-snapshot:v1" as const;
+const SEMANTIC_COMPONENT_KEYS = [
+	"agent",
+	"rolePrompt",
+	"tools",
+	"model",
+	"thinkingLevel",
+	"transport",
+	"trust",
+	"repository",
+	"artifacts",
+	"workflowGeneration",
+	"schedulerPolicy",
+] as const;
+
+export interface SemanticSnapshotInput {
+	agentName: string;
+	agentManifest?: unknown;
+	rolePrompt: string;
+	tools?: string[];
+	model?: string;
+	thinkingLevel?: string;
+	transport: string;
+	trust: { kind: string; projectTrusted: boolean };
+	repository: { kind: string; generation: string };
+	artifacts: Record<string, string>;
+	workflowGeneration: number;
+	schedulerPolicy: string;
+}
+
+export interface SemanticSnapshot {
+	version: typeof SEMANTIC_SNAPSHOT_VERSION;
+	digest: string;
+	components: {
+		agent: string;
+		rolePrompt: string;
+		tools: string;
+		model: string;
+		thinkingLevel: string;
+		transport: string;
+		trust: string;
+		repository: string;
+		artifacts: string;
+		workflowGeneration: string;
+		schedulerPolicy: string;
+	};
+}
+
+export interface RepositoryGeneration {
+	kind: "git-commit" | "git-dirty" | "filesystem";
+	generation: string;
+}
+
+export interface SemanticCompatibility {
+	status: "compatible" | "warning" | "needs-revalidation" | "rejected";
+	changedComponents: string[];
+}
+
+export async function captureRepositoryGeneration(cwd: string): Promise<RepositoryGeneration> {
+	const resolved = await fs.promises.realpath(path.resolve(cwd));
+	try {
+		const result = await execFileAsync(
+			"git",
+			["-C", resolved, "status", "--porcelain=v2", "--branch", "--untracked-files=all"],
+			{ encoding: "utf8", timeout: 2_000, maxBuffer: 256 * 1024 },
+		);
+		const lines = result.stdout.split("\n");
+		const head = lines
+			.find((line) => line.startsWith("# branch.oid "))
+			?.slice("# branch.oid ".length)
+			.trim();
+		if (!head || head === "(initial)") throw new Error("Repository has no stable HEAD");
+		const status = lines.filter((line) => line && !line.startsWith("# ")).join("\n");
+		return status
+			? { kind: "git-dirty", generation: digest({ head, status }) }
+			: { kind: "git-commit", generation: head };
+	} catch {
+		return {
+			kind: "filesystem",
+			generation: digest({ path: resolved, failClosedNonce: randomUUID() }),
+		};
+	}
+}
+
+export async function captureSemanticResourceGeneration(paths: string[]): Promise<string> {
+	const entries: Array<{ path: string; digest: string }> = [];
+	let totalBytes = 0;
+	const visit = async (candidate: string, label: string): Promise<void> => {
+		if (entries.length >= 256 || totalBytes > 1024 * 1024) {
+			throw new Error("Semantic resource snapshot exceeds bounds");
+		}
+		let stat: fs.Stats;
+		try {
+			stat = await fs.promises.lstat(candidate);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		if (stat.isSymbolicLink()) return;
+		if (stat.isDirectory()) {
+			const children = (await fs.promises.readdir(candidate)).sort();
+			for (const child of children) await visit(path.join(candidate, child), `${label}/${child}`);
+			return;
+		}
+		if (!stat.isFile()) return;
+		totalBytes += stat.size;
+		if (totalBytes > 1024 * 1024) throw new Error("Semantic resource snapshot exceeds bounds");
+		entries.push({ path: label, digest: digestBytes(await fs.promises.readFile(candidate)) });
+	};
+	try {
+		for (const [index, candidate] of paths.entries()) {
+			await visit(path.resolve(candidate), `resource-${index}`);
+		}
+		return digest(entries);
+	} catch {
+		return digest({ failClosedNonce: randomUUID() });
+	}
+}
+
+export function captureSemanticSnapshot(input: SemanticSnapshotInput): SemanticSnapshot {
+	if (!Number.isSafeInteger(input.workflowGeneration) || input.workflowGeneration < 0) {
+		throw new Error("workflowGeneration must be a non-negative safe integer");
+	}
+	const components = {
+		agent: digest({ name: input.agentName, manifest: input.agentManifest ?? null }),
+		rolePrompt: digest(input.rolePrompt),
+		tools: digest([...(input.tools ?? [])].sort()),
+		model: digest(input.model ?? null),
+		thinkingLevel: digest(input.thinkingLevel ?? null),
+		transport: digest(input.transport),
+		trust: digest(input.trust),
+		repository: digest(input.repository),
+		artifacts: digest(input.artifacts),
+		workflowGeneration: digest(input.workflowGeneration),
+		schedulerPolicy: digest(input.schedulerPolicy),
+	};
+	return {
+		version: SEMANTIC_SNAPSHOT_VERSION,
+		digest: digest(components),
+		components,
+	};
+}
+
+export function isSemanticSnapshot(value: unknown): value is SemanticSnapshot {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const snapshot = value as Partial<SemanticSnapshot>;
+	return (
+		snapshot.version === SEMANTIC_SNAPSHOT_VERSION &&
+		typeof snapshot.digest === "string" &&
+		/^[a-f0-9]{64}$/u.test(snapshot.digest) &&
+		Boolean(snapshot.components) &&
+		Object.keys(snapshot.components ?? {}).length === SEMANTIC_COMPONENT_KEYS.length &&
+		SEMANTIC_COMPONENT_KEYS.every((key) =>
+			/^[a-f0-9]{64}$/u.test(snapshot.components?.[key] ?? ""),
+		) &&
+		digest(snapshot.components) === snapshot.digest
+	);
+}
+
+export function evaluateSemanticCompatibility(
+	previous: SemanticSnapshot,
+	current: SemanticSnapshot,
+): SemanticCompatibility {
+	if (
+		previous.version !== SEMANTIC_SNAPSHOT_VERSION ||
+		current.version !== SEMANTIC_SNAPSHOT_VERSION
+	) {
+		return { status: "rejected", changedComponents: ["version"] };
+	}
+	if (!isSemanticSnapshot(previous) || !isSemanticSnapshot(current)) {
+		return { status: "rejected", changedComponents: ["invalid-snapshot"] };
+	}
+	if (previous.digest === current.digest) {
+		return { status: "compatible", changedComponents: [] };
+	}
+	const changedComponents = SEMANTIC_COMPONENT_KEYS.filter(
+		(key) => previous.components[key] !== current.components[key],
+	).sort();
+	const warningOnly = changedComponents.every((key) => key === "schedulerPolicy");
+	return {
+		status: warningOnly ? "warning" : "needs-revalidation",
+		changedComponents,
+	};
+}
+
+function digest(value: unknown): string {
+	return digestBytes(stableStringify(value));
+}
+
+function digestBytes(value: string | Buffer): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function stableStringify(value: unknown): string {
+	return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortValue);
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(
+		Object.entries(value as Record<string, unknown>)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, entry]) => [key, sortValue(entry)]),
+	);
+}

package/src/settings.ts

@@ -16,8 +16,21 @@ import {
 	type SubagentAgentConfig,
 	type SubagentSettings,
 	type SubagentThinkingLevel,
+	type SubagentTransportKind,
 } from "./agents.js";
-import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
+import {
+	DEFAULT_MAX_PARALLEL_TASKS,
+	MAX_CONFIGURABLE_PARALLEL_TASKS,
+	MAX_SUBAGENT_TIMEOUT_MS,
+} from "./limits.js";
+import {
+	isValidStatefulLimit,
+	resolveStatefulLimits,
+	STATEFUL_LIMIT_FIELDS,
+	type StatefulLimitField,
+	type StatefulLimits,
+	statefulLimitDefinition,
+} from "./stateful-limits.js";
 
 export function hasOwn(obj: object, key: PropertyKey): boolean {
 	return Object.hasOwn(obj, key);
@@ -39,10 +52,6 @@ function isPositiveInteger(value: unknown): value is number {
 	return isPositiveNumber(value) && Number.isSafeInteger(value);
 }
 
-function isNonNegativeInteger(value: unknown): value is number {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
 export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | undefined {
 	if (!isPlainObject(value)) return undefined;
 
@@ -100,13 +109,27 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 			if (typeof value.blocking.enabled !== "boolean") return undefined;
 			blocking.enabled = value.blocking.enabled;
 		}
+		if (hasOwn(value.blocking, "maxParallelTasks")) {
+			if (
+				!isPositiveInteger(value.blocking.maxParallelTasks) ||
+				value.blocking.maxParallelTasks > MAX_CONFIGURABLE_PARALLEL_TASKS
+			) {
+				return undefined;
+			}
+			blocking.maxParallelTasks = value.blocking.maxParallelTasks;
+		}
 		settings.blocking = blocking;
 	}
 	if (hasOwn(value, "stateful")) {
 		if (!isPlainObject(value.stateful)) return undefined;
 		const runtime: NonNullable<SubagentSettings["stateful"]> = {};
 		if (hasOwn(value.stateful, "transport")) {
-			if (value.stateful.transport !== "subprocess" && value.stateful.transport !== "in-process") {
+			if (
+				value.stateful.transport !== "subprocess" &&
+				value.stateful.transport !== "in-process" &&
+				value.stateful.transport !== "rpc" &&
+				value.stateful.transport !== "auto"
+			) {
 				return undefined;
 			}
 			runtime.transport = value.stateful.transport;
@@ -120,23 +143,17 @@ export function normalizeSubagentSettings(value: unknown): SubagentSettings | un
 			}
 			runtime.completionDelivery = value.stateful.completionDelivery;
 		}
-		for (const key of [
-			"maxAgents",
-			"maxActiveTurns",
-			"maxChildrenPerAgent",
-			"maxMailboxMessages",
-			"maxMailboxMessageBytes",
-			"idleTtlMs",
-			"maxStoredAgents",
-		] as const) {
+		for (const key of STATEFUL_LIMIT_FIELDS) {
 			if (hasOwn(value.stateful, key)) {
-				if (!isPositiveInteger(value.stateful[key])) return undefined;
+				if (!isValidStatefulLimit(key, value.stateful[key])) return undefined;
 				runtime[key] = value.stateful[key];
 			}
 		}
-		if (hasOwn(value.stateful, "maxDepth")) {
-			if (!isNonNegativeInteger(value.stateful.maxDepth)) return undefined;
-			runtime.maxDepth = value.stateful.maxDepth;
+		for (const key of ["maxMailboxMessages", "maxMailboxMessageBytes", "idleTtlMs"] as const) {
+			if (hasOwn(value.stateful, key)) {
+				if (!isPositiveInteger(value.stateful[key])) return undefined;
+				runtime[key] = value.stateful[key];
+			}
 		}
 		if (hasOwn(value.stateful, "retentionDays")) {
 			if (!isPositiveNumber(value.stateful.retentionDays)) return undefined;
@@ -283,6 +300,32 @@ export interface CompletionDeliverySettingsSnapshot {
 	error?: string;
 }
 
+export interface StatefulTransportSettingsSnapshot {
+	path: string;
+	value: SubagentTransportKind;
+	source: "default" | "user settings";
+	error?: string;
+}
+
+export interface BlockingParallelLimitSettingsSnapshot {
+	path: string;
+	value: number;
+	source: "default" | "user settings";
+	error?: string;
+}
+
+export interface StatefulLimitFieldSnapshot {
+	value: number;
+	source: "default" | "user settings";
+}
+
+export interface StatefulLimitSettingsSnapshot {
+	path: string;
+	writePath: string;
+	values?: Record<StatefulLimitField, StatefulLimitFieldSnapshot>;
+	error?: string;
+}
+
 export interface ConsultResourceSettingsSnapshot {
 	path: string;
 	value: ConsultResourcePolicy;
@@ -462,6 +505,71 @@ export function inspectCompletionDeliverySettings(): CompletionDeliverySettingsS
 	};
 }
 
+export function inspectStatefulTransportSettings(): StatefulTransportSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: "subprocess",
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "transport");
+	return {
+		path: inspected.path,
+		value: inspected.settings.stateful?.transport ?? "subprocess",
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function resolveBlockingMaxParallelTasks(settings?: SubagentSettings): number {
+	return settings?.blocking?.maxParallelTasks ?? DEFAULT_MAX_PARALLEL_TASKS;
+}
+
+export function inspectBlockingParallelLimitSettings(): BlockingParallelLimitSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: DEFAULT_MAX_PARALLEL_TASKS,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "maxParallelTasks");
+	return {
+		path: inspected.path,
+		value: resolveBlockingMaxParallelTasks(inspected.settings),
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function inspectStatefulLimitSettings(): StatefulLimitSettingsSnapshot {
+	const inspected = inspectSubagentSettingsDocument();
+	const writePath = subagentSettingsFilePath();
+	if (inspected.error) {
+		return { path: inspected.path, writePath, error: inspected.error };
+	}
+	const resolved = resolveStatefulLimits(inspected.settings?.stateful);
+	const rawStateful = isPlainObject(inspected.raw?.stateful) ? inspected.raw.stateful : undefined;
+	return {
+		path: inspected.path,
+		writePath,
+		values: Object.fromEntries(
+			STATEFUL_LIMIT_FIELDS.map((field) => [
+				field,
+				{
+					value: resolved[field],
+					source: rawStateful && hasOwn(rawStateful, field) ? "user settings" : "default",
+				},
+			]),
+		) as unknown as Record<StatefulLimitField, StatefulLimitFieldSnapshot>,
+	};
+}
+
 export function updateDelegationWorkflowSetting(
 	value: Exclude<DelegationWorkflow, "disabled">,
 ): void {
@@ -493,6 +601,27 @@ export function updateDelegationWorkflowSetting(
 	});
 }
 
+export function updateStatefulTransportSetting(value: SubagentTransportKind): void {
+	if (!["subprocess", "in-process", "rpc", "auto"].includes(value)) {
+		throw new Error(`Unsupported stateful transport: ${value}`);
+	}
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const stateful = raw.stateful;
+		if (stateful !== undefined && !isPlainObject(stateful)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				stateful: { ...(stateful ?? {}), transport: value },
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
 export function updateCompletionDeliverySetting(value: CompletionDelivery): void {
 	withSettingsMutationLock(() => {
 		const update = readSettingsObjectForUpdate();
@@ -514,6 +643,64 @@ export function updateCompletionDeliverySetting(value: CompletionDelivery): void
 	});
 }
 
+export function updateBlockingMaxParallelTasksSetting(value: number): void {
+	if (!isPositiveInteger(value) || value > MAX_CONFIGURABLE_PARALLEL_TASKS) {
+		throw new Error(
+			`Maximum parallel tasks must be an integer between 1 and ${MAX_CONFIGURABLE_PARALLEL_TASKS}`,
+		);
+	}
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const blocking = raw.blocking;
+		if (blocking !== undefined && !isPlainObject(blocking)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} blocking settings`);
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				blocking: {
+					...(blocking ?? {}),
+					maxParallelTasks: value,
+				},
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
+export function updateStatefulLimitSetting(
+	field: StatefulLimitField,
+	value: number,
+	expected?: StatefulLimits,
+): void {
+	if (!isValidStatefulLimit(field, value)) {
+		throw new Error(
+			`${field} must be a safe integer greater than or equal to ${statefulLimitDefinition(field).minimum}`,
+		);
+	}
+	withSettingsMutationLock(() => {
+		const update = readSettingsObjectForUpdate();
+		const raw = update.document;
+		const stateful = raw.stateful;
+		if (stateful !== undefined && !isPlainObject(stateful)) {
+			throw new Error(`Cannot update invalid ${SETTINGS_FILE} stateful settings`);
+		}
+		const normalized = normalizeSubagentSettings(raw);
+		if (!normalized) throw new Error(`Cannot update invalid ${SETTINGS_FILE}`);
+		if (expected && !sameStatefulLimits(resolveStatefulLimits(normalized.stateful), expected)) {
+			throw new Error("Detached limit settings changed; reopen settings and retry");
+		}
+		writeSettingsObjectUnlocked(
+			{
+				...raw,
+				stateful: { ...(stateful ?? {}), [field]: value },
+			},
+			update.replaceCanonical,
+		);
+	});
+}
+
 export function updateConsultResourceSetting(value: ConsultResourcePolicy): void {
 	withSettingsMutationLock(() => {
 		const update = readSettingsObjectForUpdate();
@@ -558,7 +745,18 @@ export function updateCwdPolicySetting(
 	});
 }
 
+export type AgentSettingsPatch = {
+	tools?: string[] | undefined;
+	model?: string | null | undefined;
+	thinkingLevel?: SubagentThinkingLevel | null | undefined;
+	timeoutMs?: number | null | undefined;
+};
+
 export function updateAgentToolsSetting(name: string, tools: string[] | undefined): void {
+	updateAgentSettingsPatch({ [name]: { tools } });
+}
+
+export function updateAgentSettingsPatch(patches: Record<string, AgentSettingsPatch>): void {
 	withSettingsMutationLock(() => {
 		const update = readSettingsObjectForUpdate();
 		const raw = update.document;
@@ -567,24 +765,41 @@ export function updateAgentToolsSetting(name: string, tools: string[] | undefine
 			throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
 		}
 		const agents = { ...(rawAgents ?? {}) };
-		const rawAgent = hasOwn(agents, name) ? agents[name] : undefined;
-		if (rawAgent !== undefined && !isPlainObject(rawAgent)) {
-			throw new Error(`Cannot update invalid ${SETTINGS_FILE} settings for ${name}`);
-		}
-		const agent = { ...(rawAgent ?? {}) };
-		if (tools === undefined) delete agent.tools;
-		else agent.tools = tools;
-		if (Object.keys(agent).length > 0) {
-			Object.defineProperty(agents, name, {
-				value: agent,
-				enumerable: true,
-				configurable: true,
-				writable: true,
-			});
-		} else {
-			delete agents[name];
+		for (const [name, patch] of Object.entries(patches)) {
+			const rawAgent = hasOwn(agents, name) ? agents[name] : undefined;
+			if (rawAgent !== undefined && !isPlainObject(rawAgent)) {
+				throw new Error(`Cannot update invalid ${SETTINGS_FILE} settings for ${name}`);
+			}
+			const agent = { ...(rawAgent ?? {}) };
+			for (const field of ["tools", "model", "thinkingLevel", "timeoutMs"] as const) {
+				if (!hasOwn(patch, field)) continue;
+				const value = patch[field];
+				if (value === undefined) delete agent[field];
+				else
+					Object.defineProperty(agent, field, {
+						value,
+						enumerable: true,
+						configurable: true,
+						writable: true,
+					});
+			}
+			if (Object.keys(agent).length > 0) {
+				Object.defineProperty(agents, name, {
+					value: agent,
+					enumerable: true,
+					configurable: true,
+					writable: true,
+				});
+			} else {
+				delete agents[name];
+			}
 		}
 
+		const normalized = normalizeSubagentSettings({
+			...raw,
+			...(Object.keys(agents).length > 0 ? { agents } : {}),
+		});
+		if (!normalized) throw new Error(`Cannot update invalid ${SETTINGS_FILE} agent settings`);
 		const updated = { ...raw };
 		if (Object.keys(agents).length > 0) updated.agents = agents;
 		else delete updated.agents;
@@ -659,6 +874,10 @@ function withSettingsMutationLock<T>(mutate: () => T): T {
 	}
 }
 
+function sameStatefulLimits(left: StatefulLimits, right: StatefulLimits): boolean {
+	return STATEFUL_LIMIT_FIELDS.every((field) => left[field] === right[field]);
+}
+
 function pathEntryExists(filePath: string): boolean {
 	try {
 		fs.lstatSync(filePath);

package/src/spawn-idempotency.ts

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import type { AgentScope, SubagentThinkingLevel } from "./agents.js";
+import type { DelegationContract } from "./delegation-contract.js";
+import type { SubagentResultFormat } from "./result-contract.js";
+
+export const MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH = 256;
+
+export interface CanonicalSpawnRequest {
+	agent: string;
+	task: string;
+	cwd: string;
+	agentScope: AgentScope;
+	thinkingLevel?: SubagentThinkingLevel;
+	timeoutMs?: number;
+	idleTimeoutMs?: number;
+	maxTurns?: number;
+	maxToolCalls?: number;
+	parentId?: string;
+	context?: string;
+	contextSourceIds: readonly string[];
+	workspaceMode: "shared" | "worktree";
+	allowConcurrentWrites: boolean;
+	contract?: DelegationContract;
+	resultFormat: SubagentResultFormat;
+}
+
+export function hashSpawnRequest(request: CanonicalSpawnRequest): string {
+	return createHash("sha256")
+		.update(
+			JSON.stringify({
+				agent: request.agent,
+				task: request.task,
+				cwd: request.cwd,
+				agentScope: request.agentScope,
+				thinkingLevel: request.thinkingLevel ?? null,
+				...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+				...(request.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: request.idleTimeoutMs }),
+				...(request.maxTurns === undefined ? {} : { maxTurns: request.maxTurns }),
+				...(request.maxToolCalls === undefined ? {} : { maxToolCalls: request.maxToolCalls }),
+				parentId: request.parentId ?? null,
+				contextHash: request.context
+					? createHash("sha256").update(request.context).digest("hex")
+					: null,
+				contextSourceIds: [...request.contextSourceIds],
+				workspaceMode: request.workspaceMode,
+				allowConcurrentWrites: request.allowConcurrentWrites,
+				...(request.contract === undefined ? {} : { contract: request.contract }),
+				resultFormat: request.resultFormat,
+			}),
+		)
+		.digest("hex");
+}
+
+export function assertSpawnIdempotencyKey(value: string | undefined): void {
+	if (value === undefined) return;
+	if (!value || value.length > MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH) {
+		throw new Error(
+			`subagent_spawn idempotencyKey must contain 1-${MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH} characters`,
+		);
+	}
+}

package/src/stateful-config.ts

@@ -0,0 +1,13 @@
+import type { CompletionDelivery, SubagentTransportKind } from "./agents.js";
+
+export function resolveStatefulTransportKind(
+	value: SubagentTransportKind | undefined,
+): SubagentTransportKind {
+	return value ?? "subprocess";
+}
+
+export function resolveCompletionDelivery(
+	value: CompletionDelivery | undefined,
+): CompletionDelivery {
+	return value ?? "next-turn";
+}

package/src/stateful-guidance.ts

@@ -19,6 +19,7 @@ export function createSpawnPromptGuidelines(
 	return [
 		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
 		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
+		"Set subagent_spawn timeoutMs to the shortest realistic work deadline for the task difficulty; use idleTimeoutMs for stalled work and maxTurns or maxToolCalls to stop repeated work without progress. Split oversized tasks instead of extending budgets merely to compensate for broad scope. Omit these fields only to preserve the retained agent or configured defaults.",
 		deliveryGuidance,
 		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
 		...(blockingEnabled