pi-subagents 0.35.1 → 0.37.0

package/src/agents/agents.ts

@@ -35,6 +35,7 @@ export interface AgentMemoryConfig {
 }
 
 export const BUILTIN_AGENT_NAMES = [
+	"advisor",
 	"context-builder",
 	"delegate",
 	"oracle",
@@ -72,6 +73,7 @@ export interface BuiltinAgentOverrideBase {
 	skillPath?: string[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	completionGuard?: boolean;
 	toolBudget?: ToolBudgetConfig;
@@ -90,6 +92,7 @@ interface BuiltinAgentOverrideConfig {
 	systemPrompt?: string;
 	skills?: string[] | false;
 	tools?: string[] | false;
+	extensions?: string[] | false;
 	subagentOnlyExtensions?: string[] | false;
 	completionGuard?: boolean;
 	toolBudget?: ToolBudgetConfig | false;
@@ -133,6 +136,7 @@ export interface AgentConfig {
 	skills?: string[];
 	skillPath?: string[];
 	extensions?: string[];
+	extensionsFromDefault?: boolean;
 	subagentOnlyExtensions?: string[];
 	output?: string;
 	defaultReads?: string[];
@@ -151,6 +155,8 @@ export interface AgentConfig {
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	defaultModel?: string;
+	defaultThinking?: string;
+	defaultExtensions?: string[];
 	disableBuiltins?: boolean;
 	disableThinking?: boolean;
 	modelScope?: ModelScopeConfig;
@@ -476,7 +482,7 @@ function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpD
 		}
 	}
 	return {
-		...(tools.length > 0 ? { tools } : {}),
+		...(rawTools !== undefined ? { tools } : {}),
 		...(mcpDirectTools.length > 0 ? { mcpDirectTools } : {}),
 	};
 }
@@ -515,6 +521,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		skillPath: agent.skillPath ? [...agent.skillPath] : undefined,
 		tools: agent.tools ? [...agent.tools] : undefined,
 		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
+		extensions: agent.extensionsFromDefault ? undefined : agent.extensions ? [...agent.extensions] : undefined,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
 		completionGuard: agent.completionGuard,
 		toolBudget: agent.toolBudget,
@@ -537,6 +544,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
 		...(override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {}),
+		...(override.extensions !== undefined ? { extensions: override.extensions === false ? false : [...override.extensions] } : {}),
 		...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
 		...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
 		...(override.toolBudget !== undefined ? { toolBudget: override.toolBudget === false ? false : { ...override.toolBudget, ...(Array.isArray(override.toolBudget.block) ? { block: [...override.toolBudget.block] } : {}) } } : {}),
@@ -716,6 +724,9 @@ function parseBuiltinOverrideEntry(
 	const tools = parseOverrideStringArrayOrFalse(input.tools, { filePath, name, field: "tools" });
 	if (tools !== undefined) override.tools = tools;
 
+	const extensions = parseOverrideStringArrayOrFalse(input.extensions, { filePath, name, field: "extensions" });
+	if (extensions !== undefined) override.extensions = extensions;
+
 	const subagentOnlyExtensions = parseOverrideStringArrayOrFalse(input.subagentOnlyExtensions, { filePath, name, field: "subagentOnlyExtensions" });
 	if (subagentOnlyExtensions !== undefined) override.subagentOnlyExtensions = subagentOnlyExtensions;
 
@@ -753,18 +764,34 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultModel'; expected a non-empty string.`);
 		}
 	}
+	let defaultThinking: string | undefined;
+	if ("defaultThinking" in subagentsObject) {
+		if (typeof subagentsObject.defaultThinking === "string" && subagentsObject.defaultThinking.trim()) {
+			defaultThinking = subagentsObject.defaultThinking.trim();
+		} else {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultThinking'; expected a non-empty string.`);
+		}
+	}
+	let defaultExtensions: string[] | undefined;
+	if ("defaultExtensions" in subagentsObject) {
+		if (!Array.isArray(subagentsObject.defaultExtensions)
+			|| subagentsObject.defaultExtensions.some((item) => typeof item !== "string" || !item.trim())) {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultExtensions'; expected an array of non-empty strings.`);
+		}
+		defaultExtensions = subagentsObject.defaultExtensions.map((item) => item.trim());
+	}
 	const modelScope = parseModelScopeConfig(subagentsObject.modelScope, { filePath });
 
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
 	const agentOverrides = subagentsObject.agentOverrides;
 	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-		return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
+		return { overrides: parsed, defaultModel, defaultThinking, defaultExtensions, disableBuiltins, disableThinking, modelScope };
 	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
+	return { overrides: parsed, defaultModel, defaultThinking, defaultExtensions, disableBuiltins, disableThinking, modelScope };
 }
 
 function resolveSubagentDefaultModel(
@@ -792,6 +819,58 @@ function applySubagentDefaultModel(agents: AgentConfig[], defaultModel: AgentMod
 	});
 }
 
+function resolveSubagentDefaultThinking(
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
+	projectSettingsPath: string | null,
+): string | undefined {
+	if (projectSettingsPath && projectSettings.defaultThinking !== undefined) return projectSettings.defaultThinking;
+	return userSettings.defaultThinking;
+}
+
+function applySubagentDefaultThinking(agents: AgentConfig[], defaultThinking: string | undefined): AgentConfig[] {
+	if (defaultThinking === undefined) return agents;
+	return agents.map((agent) => {
+		if (agent.thinking !== undefined) return agent;
+		const next = { ...agent, thinking: defaultThinking };
+		const frontmatterFields = agentFrontmatterFields.get(agent);
+		if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
+		return next;
+	});
+}
+
+function resolveSubagentDefaultExtensions(
+	userSettings: SubagentSettings,
+	projectSettings: SubagentSettings,
+	projectSettingsPath: string | null,
+): string[] | undefined {
+	if (projectSettingsPath && projectSettings.defaultExtensions !== undefined) return projectSettings.defaultExtensions;
+	return userSettings.defaultExtensions;
+}
+
+function applySubagentDefaultExtensions(agents: AgentConfig[], defaultExtensions: string[] | undefined): AgentConfig[] {
+	if (defaultExtensions === undefined) return agents;
+	return agents.map((agent) => {
+		if (agent.extensions !== undefined) return agent;
+		const next = { ...agent, extensions: [...defaultExtensions], extensionsFromDefault: true };
+		const frontmatterFields = agentFrontmatterFields.get(agent);
+		if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
+		return next;
+	});
+}
+
+function applySubagentDefaults(
+	agents: AgentConfig[],
+	defaultModel: AgentModelSourceInfo | undefined,
+	defaultThinking: string | undefined,
+	defaultExtensions: string[] | undefined,
+): AgentConfig[] {
+	return applySubagentDefaultExtensions(
+		applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel), defaultThinking),
+		defaultExtensions,
+	);
+}
+
 function applyBuiltinOverride(
 	agent: AgentConfig,
 	override: BuiltinAgentOverrideConfig,
@@ -820,6 +899,7 @@ function applyBuiltinOverride(
 		next.tools = tools;
 		next.mcpDirectTools = mcpDirectTools;
 	}
+	if (override.extensions !== undefined) next.extensions = override.extensions === false ? undefined : [...override.extensions];
 	if (override.subagentOnlyExtensions !== undefined) {
 		next.subagentOnlyExtensions = override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions];
 	}
@@ -963,6 +1043,9 @@ function applyCustomAgentOverride(
 		target.mcpDirectTools = mcpDirectTools;
 		anyFilled = true;
 	}
+	if (override.extensions !== undefined) {
+		fill("extensions", ["extensions"], override.extensions === false ? undefined : [...override.extensions]);
+	}
 	if (override.subagentOnlyExtensions !== undefined) {
 		fill(
 			"subagentOnlyExtensions",
@@ -1008,7 +1091,7 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -1027,6 +1110,7 @@ export function buildBuiltinOverrideConfig(
 	const baseTools = joinToolList(base);
 	const draftTools = joinToolList(draft);
 	if (!arraysEqual(draftTools, baseTools)) override.tools = draftTools ? [...draftTools] : false;
+	if (!arraysEqual(draft.extensions, base.extensions)) override.extensions = draft.extensions ? [...draft.extensions] : false;
 	if (!arraysEqual(draft.subagentOnlyExtensions, base.subagentOnlyExtensions)) {
 		override.subagentOnlyExtensions = draft.subagentOnlyExtensions ? [...draft.subagentOnlyExtensions] : false;
 	}
@@ -1159,7 +1243,19 @@ export function removeBuiltinAgentOverrideFields(
 	return { path: filePath, removed: true };
 }
 
-function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
+const DISCOVERY_PRUNED_DIR_NAMES = new Set([".git", "node_modules"]);
+
+function isDiscoveryNestedProjectRoot(dir: string): boolean {
+	return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+
+function shouldPruneDiscoveryDir(rootDir: string, dir: string, dirName: string): boolean {
+	if (DISCOVERY_PRUNED_DIR_NAMES.has(dirName)) return true;
+	if (fs.existsSync(path.join(dir, ".git"))) return true;
+	return path.resolve(dir) !== path.resolve(rootDir) && isDiscoveryNestedProjectRoot(dir);
+}
+
+function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean, rootDir = dir): string[] {
 	const files: string[] = [];
 	if (!fs.existsSync(dir)) return files;
 
@@ -1173,7 +1269,9 @@ function listFilesRecursive(dir: string, predicate: (fileName: string) => boolea
 	for (const entry of entries) {
 		const filePath = path.join(dir, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...listFilesRecursive(filePath, predicate));
+			if (!shouldPruneDiscoveryDir(rootDir, filePath, entry.name)) {
+				files.push(...listFilesRecursive(filePath, predicate, rootDir));
+			}
 			continue;
 		}
 		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
@@ -1233,7 +1331,9 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const runtimeName = buildRuntimeName(localName, packageName);
 
 		const rawTools = parseFrontmatterList(frontmatter.tools);
-		const { tools = [], mcpDirectTools = [] } = splitToolList(rawTools);
+		const parsedTools = splitToolList(rawTools);
+		const tools = parsedTools.tools ?? [];
+		const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
 		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
 		const skillStr = frontmatter.skill || frontmatter.skills;
 		const skills = parseFrontmatterList(skillStr);
@@ -1315,7 +1415,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			localName,
 			packageName,
 			description: frontmatter.description,
-			tools: tools.length > 0 ? tools : undefined,
+			tools: rawTools !== undefined ? tools : undefined,
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
 			model: frontmatter.model,
 			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,
@@ -1443,6 +1543,8 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
 	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
 	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+	const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
 		includeUser: scope !== "project",
@@ -1450,7 +1552,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	});
 
 	const builtinAgents = applyBuiltinOverrides(
-		applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel),
+		applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1461,7 +1563,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
 	const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
 	const userAgents = applyCustomAgentOverrides(
-		applySubagentDefaultModel([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel),
+		applySubagentDefaults([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1469,14 +1571,14 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	);
 
 	const projectAgents = applyCustomAgentOverrides(
-		applySubagentDefaultModel(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel),
+		applySubagentDefaults(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 	const packageAgents = applyCustomAgentOverrides(
-		applySubagentDefaultModel(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel),
+		applySubagentDefaults(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1512,21 +1614,23 @@ export function discoverAgentsAll(cwd: string): {
 	const userSettings = readSubagentSettings(userSettingsPath);
 	const projectSettings = readSubagentSettings(projectSettingsPath);
 	const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+	const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const packageSubagentPaths = collectPackageSubagentPaths(cwd);
 
 	const builtin = applyBuiltinOverrides(
-		applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel),
+		applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
 		projectSettingsPath,
 	);
 	const user = applyCustomAgentOverrides(
-		applySubagentDefaultModel([
+		applySubagentDefaults([
 			...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
 			...loadAgentsFromDir(userDirOld, "user"),
 			...loadAgentsFromDir(userDirNew, "user"),
-		], defaultModel),
+		], defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1539,7 +1643,7 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const packageAgents = applyCustomAgentOverrides(
-		applySubagentDefaultModel(Array.from(packageMap.values()), defaultModel),
+		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,
@@ -1552,7 +1656,7 @@ export function discoverAgentsAll(cwd: string): {
 		}
 	}
 	const project = applyCustomAgentOverrides(
-		applySubagentDefaultModel(Array.from(projectMap.values()), defaultModel),
+		applySubagentDefaults(Array.from(projectMap.values()), defaultModel, defaultThinking, defaultExtensions),
 		userSettings,
 		projectSettings,
 		userSettingsPath,

package/src/api/capability-ceiling.ts

@@ -0,0 +1,17 @@
+export {
+	SUBAGENT_CAPABILITY_CEILING_ENV,
+	SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY,
+	SUBAGENT_CAPABILITY_CEILING_VERSION,
+	decodeSubagentCapabilityCeiling,
+	encodeSubagentCapabilityCeiling,
+	intersectSubagentCapabilityCeilings,
+	parseSubagentCapabilityCeiling,
+	registerSubagentCapabilityCeiling,
+	resolveCurrentSubagentCapabilityCeiling,
+	resolveSubagentCapabilityCeiling,
+	type RegisterSubagentCapabilityCeilingOptions,
+	type ResolvedSubagentCapabilityCeiling,
+	type SubagentCapabilityCeiling,
+	type SubagentCapabilityCeilingHandle,
+	type SubagentCapabilityAudit,
+} from "../runs/shared/capability-ceiling.ts";

package/src/api/delegation.ts

@@ -1,4 +1,5 @@
 export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
+export const SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION = 2 as const;
 
 // This is the established extension-to-extension transport. The public API
 // intentionally reuses it instead of adding a second event protocol.
@@ -19,6 +20,37 @@ export interface SubagentDelegationToolBudget {
 	block?: string[] | "*";
 }
 
+export interface SubagentDelegationAgentContract {
+	version: 1;
+}
+
+export type SubagentDelegationJsonSchemaObject = Record<string, unknown>;
+
+export interface SubagentDelegationExecutionResult {
+	status: "completed" | "failed" | "paused" | "stopped" | "detached";
+	success: boolean;
+	exitCode: number;
+	error?: string;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	detached?: boolean;
+}
+
+export interface SubagentDelegationReviewResult {
+	status: "not-requested" | "review-required" | "reviewed" | "blockers";
+	findings?: Array<{ severity: "blocker" | "non-blocking"; file?: string; issue: string; rationale: string }>;
+}
+
+export interface SubagentDelegationEffectsResult {
+	fileMutation?: {
+		status: "not-requested" | "not-applicable" | "observed" | "missing";
+		expected: boolean;
+		attempted: boolean;
+		message?: string;
+	};
+}
+
 export type SubagentDelegationAcceptanceEvidence =
 	| "changed-files"
 	| "tests-added"
@@ -87,6 +119,8 @@ export interface SubagentDelegationRequest {
 	skill?: string | string[] | boolean;
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
+	outputSchema?: SubagentDelegationJsonSchemaObject;
+	agentContract?: SubagentDelegationAgentContract;
 	acceptance?: SubagentDelegationAcceptance;
 	artifacts?: boolean;
 }
@@ -116,6 +150,7 @@ export type SubagentDelegationStatus =
 	| "interrupted"
 	| "turn_budget_exhausted"
 	| "tool_budget_exhausted"
+	| "structured_output_failed"
 	| "acceptance_failed"
 	| "invalid_request"
 	| "unavailable_context";
@@ -127,12 +162,14 @@ export type SubagentDelegationAcceptanceStatus =
 	| "attested"
 	| "checked"
 	| "verified"
+	| "review-required"
 	| "reviewed"
 	| "accepted"
 	| "rejected";
 
 export interface SubagentDelegationAcceptanceResult {
 	status: SubagentDelegationAcceptanceStatus;
+	evidenceStatus: Exclude<SubagentDelegationAcceptanceStatus, "review-required" | "reviewed" | "accepted">;
 	explicit: boolean;
 }
 
@@ -144,10 +181,13 @@ export interface SubagentDelegationResponse extends SubagentDelegationStarted {
 	agent?: string;
 	model?: string;
 	exitCode?: number;
+	execution?: SubagentDelegationExecutionResult;
 	output?: string;
 	outputPath?: string;
 	sessionFile?: string;
 	acceptance?: SubagentDelegationAcceptanceResult;
+	review?: SubagentDelegationReviewResult;
+	effects?: SubagentDelegationEffectsResult;
 	turns?: number;
 	toolCount?: number;
 	durationMs?: number;
@@ -156,3 +196,90 @@ export interface SubagentDelegationResponse extends SubagentDelegationStarted {
 }
 
 export interface SubagentDelegationCancel extends SubagentDelegationStarted {}
+
+export type SubagentDelegationV2Thinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export type SubagentDelegationV2ResultRequest =
+	| { kind: "text" }
+	| { kind: "structured"; schema: SubagentDelegationJsonSchemaObject };
+
+export interface SubagentDelegationV2Request {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
+	agent: string;
+	task: string;
+	context: "fresh" | "fork";
+	cwd: string;
+	model?: string;
+	thinking?: SubagentDelegationV2Thinking;
+	timeoutMs?: number;
+	turnBudget?: SubagentDelegationTurnBudget;
+	toolBudget?: SubagentDelegationToolBudget;
+	skill?: string | string[] | boolean;
+	artifacts?: boolean;
+	result: SubagentDelegationV2ResultRequest;
+}
+
+export interface SubagentDelegationV2Started {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
+}
+
+export interface SubagentDelegationV2Update extends SubagentDelegationV2Started {
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput?: string;
+	recentOutputLines?: string[];
+	recentTools?: Array<{ tool: string; args: string }>;
+	model?: string;
+	toolCount?: number;
+	durationMs?: number;
+	tokens?: number;
+}
+
+export type SubagentDelegationV2Status = SubagentDelegationStatus | "duplicate_node";
+
+export type SubagentDelegationV2Value =
+	| { kind: "text"; text: string }
+	| { kind: "structured"; value: unknown };
+
+export interface SubagentDelegationV2Usage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+	toolCalls: number;
+	durationMs: number;
+}
+
+export interface SubagentDelegationV2TerminalResponse extends SubagentDelegationV2Started {
+	status: Exclude<SubagentDelegationV2Status, "invalid_request">;
+	error?: string;
+	runId?: string;
+	agent?: string;
+	model?: string;
+	thinking?: string;
+	exitCode?: number;
+	result?: SubagentDelegationV2Value;
+	usage?: SubagentDelegationV2Usage;
+}
+
+/** A malformed V2 request can only be correlated by the valid identity fields it supplied. */
+export interface SubagentDelegationV2InvalidResponse {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId?: string;
+	nodeId?: string;
+	status: "invalid_request";
+	error?: string;
+}
+
+export type SubagentDelegationV2Response = SubagentDelegationV2TerminalResponse | SubagentDelegationV2InvalidResponse;
+
+export interface SubagentDelegationV2Cancel extends SubagentDelegationV2Started {}