@jawcode-dev/coding-agent 1.1.0

package/src/task/index.ts

@@ -0,0 +1,2173 @@
+/**
+ * Task tool - Delegate tasks to specialized agents.
+ *
+ * Discovers agent definitions from:
+ *   - Bundled agents (shipped with gjc-coding-agent)
+ *   - ~/.jwc/agent/agents/*.md (user-level)
+ *   - .jwc/agents/*.md (project-level)
+ *
+ * Supports:
+ *   - Single agent execution
+ *   - Parallel execution with concurrency limits
+ *   - Progress tracking via JSON events
+ *   - Session artifacts for debugging
+ */
+import { createHash } from "node:crypto";
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import path from "node:path";
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@jawcode-dev/agent-core";
+import type { Model, Usage } from "@jawcode-dev/ai";
+import { $env, prompt, Snowflake } from "@jawcode-dev/utils";
+import type { ToolSession } from "..";
+import { AsyncJobManager } from "../async";
+import { resolveAgentModelPatterns } from "../config/model-resolver";
+import {
+	allocateActorRecord,
+	buildWorkflowActorKey,
+	findRunningActor,
+	markActorFailed,
+	markActorIdle,
+	markActorMaintained,
+	markActorPaused,
+	markActorRunning,
+	readActorRegistry,
+	resolveCompatibleActor,
+	upsertActor,
+	type WorkflowActorKey,
+	type WorkflowActorRecord,
+	type WorkflowActorRegistry,
+	type WorkflowActorStage,
+	workflowActorId,
+	writeActorRegistryAtomic,
+} from "../jwc-runtime/actor-registry";
+import { readPabcdStateWithFallback } from "../jwc-runtime/orchestrate-state";
+import type { Theme } from "../modes/theme/theme";
+import executorSelfForkPrompt from "../prompts/system/executor-self-fork.md" with { type: "text" };
+import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" with { type: "text" };
+import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
+import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
+import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
+import type { ForkContextSeed } from "../session/agent-session";
+import { formatBytes, formatDuration } from "../tools/render-utils";
+import {
+	type AgentDefinition,
+	type AgentProgress,
+	type CacheAffinityMetadata,
+	type ForkContextMode,
+	type ForkContextPolicy,
+	getTaskSchema,
+	type SingleResult,
+	type TaskItem,
+	type TaskParams,
+	type TaskToolDetails,
+	type TaskToolSchemaInstance,
+} from "./types";
+// Import review tools for side effects (registers subagent tool handlers)
+import "../tools/review";
+import type { LocalProtocolOptions } from "../internal-urls";
+import { generateCommitMessage } from "../utils/commit-message-generator";
+import * as git from "../utils/git";
+import { discoverAgents, filterVisibleAgents, getAgent } from "./discovery";
+import { runSubprocess } from "./executor";
+import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
+import { resolveModelHint } from "./model-presets";
+import { AgentOutputManager } from "./output-manager";
+import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
+import { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoiSummary } from "./receipt";
+import { renderResult, renderCall as renderTaskCall } from "./render";
+import { getTaskSimpleModeCapabilities, type TaskSimpleMode } from "./simple-mode";
+import { DEFAULT_SPAWN_THRESHOLD, evaluateReviewerExploreGate, evaluateSpawnGate } from "./spawn-gate";
+import {
+	applyNestedPatches,
+	captureBaseline,
+	captureDeltaPatch,
+	cleanupIsolation,
+	cleanupTaskBranches,
+	commitToBranch,
+	ensureIsolation,
+	getRepoRoot,
+	type IsolationHandle,
+	mergeTaskBranches,
+	parseIsolationMode,
+	type WorktreeBaseline,
+} from "./worktree";
+
+interface TaskResumeDescriptor {
+	toolCallId: string;
+	params: TaskParams;
+	task: TaskItem & { id: string };
+	sessionFile: string | null;
+	forkContextSeed?: ForkContextSeed;
+	agentSource: AgentDefinition["source"];
+}
+
+function isTaskResumeDescriptor(value: unknown): value is TaskResumeDescriptor {
+	return typeof value === "object" && value !== null && "task" in value && "params" in value;
+}
+function renderSubagentUserPrompt(assignment: string, simpleMode: TaskSimpleMode): string {
+	return prompt.render(subagentUserPromptTemplate, {
+		assignment: assignment.trim(),
+		independentMode: simpleMode === "independent",
+	});
+}
+function createUsageTotals(): Usage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+function addUsageTotals(target: Usage, usage: Partial<Usage>): void {
+	const input = usage.input ?? 0;
+	const output = usage.output ?? 0;
+	const cacheRead = usage.cacheRead ?? 0;
+	const cacheWrite = usage.cacheWrite ?? 0;
+	const totalTokens = usage.totalTokens ?? input + output + cacheRead + cacheWrite;
+	const cost =
+		usage.cost ??
+		({
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 0,
+		} satisfies Usage["cost"]);
+
+	target.input += input;
+	target.output += output;
+	target.cacheRead += cacheRead;
+	target.cacheWrite += cacheWrite;
+	target.totalTokens += totalTokens;
+	target.cost.input += cost.input;
+	target.cost.output += cost.output;
+	target.cost.cacheRead += cost.cacheRead;
+	target.cost.cacheWrite += cost.cacheWrite;
+	target.cost.total += cost.total;
+}
+
+function hashTaskValue(value: unknown): string {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}
+
+function firstModelPattern(value: string | string[] | undefined): string {
+	if (Array.isArray(value)) return value[0] ?? "default";
+	return value ?? "default";
+}
+
+function providerFromModelPattern(value: string): string {
+	const slash = value.indexOf("/");
+	return slash > 0 ? value.slice(0, slash) : "unknown";
+}
+
+function isPabcdActorStage(value: unknown): value is WorkflowActorStage {
+	return value === "i" || value === "p" || value === "a" || value === "b" || value === "c" || value === "d";
+}
+
+function buildActorBusyResult(
+	task: TaskItem & { id: string },
+	index: number,
+	agentName: string,
+	agentSource: AgentDefinition["source"],
+	modelOverride: string | string[] | undefined,
+	simpleMode: TaskSimpleMode,
+	actor: WorkflowActorRecord,
+): SingleResult {
+	const output = `PABCD actor ${actor.id} (${actor.lane}) is already running for this stage. Wait for that subagent to finish before reusing the same resume lane.`;
+	return {
+		index,
+		id: task.id,
+		agent: agentName,
+		agentSource,
+		task: renderSubagentUserPrompt(task.assignment, simpleMode),
+		assignment: task.assignment.trim(),
+		description: task.description,
+		exitCode: 1,
+		output,
+		stderr: output,
+		truncated: false,
+		durationMs: 0,
+		tokens: 0,
+		modelOverride,
+		error: output,
+	};
+}
+
+function buildActorContextUnavailableResult(
+	task: TaskItem & { id: string },
+	index: number,
+	agentName: string,
+	agentSource: AgentDefinition["source"],
+	modelOverride: string | string[] | undefined,
+	simpleMode: TaskSimpleMode,
+	actor: WorkflowActorRecord,
+	reason: string,
+): SingleResult {
+	const output = `PABCD actor ${actor.id} (${actor.lane}) cannot be resumed in this process: ${reason}.`;
+	return {
+		index,
+		id: task.id,
+		agent: agentName,
+		agentSource,
+		task: renderSubagentUserPrompt(task.assignment, simpleMode),
+		assignment: task.assignment.trim(),
+		description: task.description,
+		exitCode: 1,
+		output,
+		stderr: output,
+		truncated: false,
+		durationMs: 0,
+		tokens: 0,
+		modelOverride,
+		error: "context_unavailable",
+		cacheAffinity: { affine: false, reason: "not_applicable" },
+	};
+}
+
+function validateTaskIdsForScheduling(tasks: readonly TaskItem[]): string | undefined {
+	const invalid: string[] = [];
+	for (let i = 0; i < tasks.length; i++) {
+		const error = getTaskIdValidationError(tasks[i]?.id);
+		if (error) invalid.push(`index ${i}: ${error}`);
+	}
+	return invalid.length > 0 ? `Invalid task ids: ${invalid.join(" ")}` : undefined;
+}
+
+// Re-export types and utilities
+export { loadBundledAgents as BUNDLED_AGENTS } from "./agents";
+export { discoverCommands, expandCommand, getCommand } from "./commands";
+export { discoverAgents, getAgent } from "./discovery";
+export {
+	isValidAllocatedTaskId,
+	isValidTaskId,
+	TASK_ID_DESCRIPTION,
+	TASK_ID_PATTERN,
+	validateAllocatedTaskId,
+	validateTaskId,
+} from "./id";
+export { AgentOutputManager } from "./output-manager";
+export type { TaskResultReceipt } from "./receipt";
+export {
+	assertNoRawTaskFields,
+	buildTaskReceipt,
+	buildTaskRoi,
+	buildTaskRoiSummary,
+	findRawTaskLeakKeys,
+	sanitizeTaskToolDetails,
+} from "./receipt";
+export type {
+	AgentDefinition,
+	AgentProgress,
+	SingleResult,
+	SubagentLifecyclePayload,
+	SubagentProgressPayload,
+	TaskParams,
+	TaskToolDetails,
+} from "./types";
+export {
+	TASK_SUBAGENT_EVENT_CHANNEL,
+	TASK_SUBAGENT_LIFECYCLE_CHANNEL,
+	TASK_SUBAGENT_PROGRESS_CHANNEL,
+	taskSchema,
+} from "./types";
+
+/**
+ * Render the tool description from a cached agent list and current settings.
+ */
+function renderDescription(
+	agents: AgentDefinition[],
+	maxConcurrency: number,
+	isolationEnabled: boolean,
+	asyncEnabled: boolean,
+	disabledAgents: string[],
+	simpleMode: TaskSimpleMode,
+	ircEnabled: boolean,
+	parentSpawns: string,
+): string {
+	const spawningDisabled = parentSpawns === "";
+	let filteredAgents = filterVisibleAgents(agents);
+	filteredAgents =
+		disabledAgents.length > 0 ? filteredAgents.filter(a => !disabledAgents.includes(a.name)) : filteredAgents;
+	if (spawningDisabled) {
+		filteredAgents = [];
+	} else if (parentSpawns !== "*") {
+		const allowed = new Set(
+			parentSpawns
+				.split(",")
+				.map(s => s.trim())
+				.filter(Boolean),
+		);
+		filteredAgents = filteredAgents.filter(a => allowed.has(a.name));
+	}
+	const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
+	return prompt.render(taskDescriptionTemplate, {
+		agents: filteredAgents,
+		spawningDisabled,
+		MAX_CONCURRENCY: maxConcurrency,
+		isolationEnabled,
+		asyncEnabled,
+		contextEnabled,
+		customSchemaEnabled,
+		ircEnabled,
+		defaultMode: simpleMode === "default",
+		schemaFreeMode: simpleMode === "schema-free",
+		independentMode: simpleMode === "independent",
+	});
+}
+
+function createTaskModeError(text: string): AgentToolResult<TaskToolDetails> {
+	return {
+		content: [{ type: "text", text }],
+		details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+	};
+}
+
+function validateTaskModeParams(simpleMode: TaskSimpleMode, params: TaskParams): string | undefined {
+	const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
+	const disallowedFields: string[] = [];
+	if (!contextEnabled && params.context !== undefined) {
+		disallowedFields.push("context");
+	}
+	if (!customSchemaEnabled && params.schema !== undefined) {
+		disallowedFields.push("schema");
+	}
+	if (!contextEnabled) {
+		const inheritedTaskIds = (params.tasks ?? [])
+			.filter(task => task.inheritContext !== undefined && task.inheritContext !== "none")
+			.map(task => task.id);
+		if (inheritedTaskIds.length > 0) {
+			disallowedFields.push(`inheritContext for task(s) ${inheritedTaskIds.join(", ")}`);
+		}
+	}
+	if (disallowedFields.length === 0) {
+		return undefined;
+	}
+
+	if (simpleMode === "schema-free") {
+		return "task.simple is set to schema-free, so the task tool does not accept `schema`. Remove it and rely on the selected agent definition or inherited session schema.";
+	}
+
+	if (disallowedFields.length === 1) {
+		return `task.simple is set to independent, so the task tool does not accept ${disallowedFields[0].startsWith("inheritContext") ? disallowedFields[0] : `\`${disallowedFields[0]}\``}. Put everything the subagent needs inside each task assignment.`;
+	}
+
+	return `task.simple is set to independent, so the task tool does not accept ${disallowedFields.map(field => (field.startsWith("inheritContext") ? field : `\`${field}\``)).join(", ")}. Put all required background and output expectations inside each task assignment or the selected agent definition.`;
+}
+
+function getForkContextPolicy(agent: AgentDefinition): ForkContextPolicy {
+	return agent.forkContext ?? "forbidden";
+}
+const FORK_CONTEXT_MODES = [
+	"none",
+	"receipt",
+	"last-turn",
+	"bounded",
+	"full",
+] as const satisfies readonly ForkContextMode[];
+const FORK_CONTEXT_MODE_SET = new Set<unknown>(FORK_CONTEXT_MODES);
+const FORK_CONTEXT_REQUEST_MODES = ["receipt", "last-turn", "bounded", "full"] as const satisfies readonly Exclude<
+	ForkContextMode,
+	"none"
+>[];
+const FORK_CONTEXT_REQUEST_MODE_SET = new Set<unknown>(FORK_CONTEXT_REQUEST_MODES);
+
+function isValidForkContextMode(value: unknown): value is ForkContextMode {
+	return FORK_CONTEXT_MODE_SET.has(value);
+}
+
+function requestsForkContext(
+	task: Pick<TaskItem, "inheritContext">,
+): task is TaskItem & { inheritContext: Exclude<ForkContextMode, "none"> } {
+	return FORK_CONTEXT_REQUEST_MODE_SET.has(task.inheritContext);
+}
+
+function resolveForkSeedParamsForMode(
+	mode: ForkContextMode,
+	configuredMaxMessages: number | undefined,
+	configuredMaxTokens: number,
+	model: Model | undefined,
+): { maxMessages: number; maxTokens: number } | undefined {
+	const capMessages = (defaultMaxMessages: number): number =>
+		configuredMaxMessages === undefined
+			? defaultMaxMessages
+			: Math.min(defaultMaxMessages, Math.max(0, Math.trunc(configuredMaxMessages)));
+	switch (mode) {
+		case "none":
+			return undefined;
+		case "receipt":
+			return { maxMessages: 1, maxTokens: 64 };
+		case "last-turn":
+			return { maxMessages: 2, maxTokens: 250 };
+		case "bounded":
+			return { maxMessages: capMessages(50), maxTokens: 250 };
+		case "full":
+			return { maxMessages: capMessages(500), maxTokens: resolveForkContextMaxTokens(configuredMaxTokens, model) };
+		default:
+			return undefined;
+	}
+}
+
+function validateForkContextRequests(
+	tasks: readonly TaskItem[],
+	agent: AgentDefinition,
+	forkContextEnabled: boolean,
+): string | undefined {
+	const invalidTaskIds = tasks
+		.filter(task => task.inheritContext !== undefined && !isValidForkContextMode(task.inheritContext as unknown))
+		.map(task => task.id);
+	if (invalidTaskIds.length > 0) {
+		return `Invalid inheritContext for task(s) ${invalidTaskIds.join(", ")}. Allowed modes: ${FORK_CONTEXT_MODES.join(", ")}.`;
+	}
+	const requested = tasks.filter(requestsForkContext);
+	if (requested.length === 0) return undefined;
+	const taskIds = requested.map(task => task.id).join(", ");
+	if (!forkContextEnabled) {
+		return `Cannot inherit parent context for task(s) ${taskIds}: task.forkContext.enabled is false.`;
+	}
+	if (getForkContextPolicy(agent) !== "allowed") {
+		return `Cannot inherit parent context for task(s) ${taskIds}: agent '${agent.name}' does not declare forkContext: allowed.`;
+	}
+	return undefined;
+}
+
+export function resolveForkContextMaxTokens(configured: number, model: Model | undefined): number {
+	if (configured > 0) return Math.trunc(configured);
+	const contextWindow = model?.contextWindow ?? 0;
+	return contextWindow > 0 ? Math.max(1, Math.floor(contextWindow * 0.15)) : 15_000;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tool Class
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Task tool - Delegate tasks to specialized agents.
+ *
+ * Requires async initialization to discover available agents.
+ * Use `TaskTool.create(session)` to instantiate.
+ */
+export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetails, Theme> {
+	readonly name = "task";
+	readonly label = "Task";
+	readonly summary = "Spawn a subagent to complete a parallel task";
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly renderResult = renderResult;
+	readonly #discoveredAgents: AgentDefinition[];
+	readonly #blockedAgent: string | undefined;
+	readonly #spawningAgentType: string | undefined;
+
+	get parameters(): TaskToolSchemaInstance {
+		const isolationEnabled = this.session.settings.get("task.isolation.mode") !== "none";
+		return getTaskSchema({ isolationEnabled, simpleMode: this.#getTaskSimpleMode() });
+	}
+
+	renderCall(args: unknown, options: Parameters<typeof renderTaskCall>[1], theme: Theme) {
+		return renderTaskCall(args as TaskParams, options, theme);
+	}
+
+	/** Dynamic description that reflects current disabled-agent settings */
+	get description(): string {
+		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
+		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
+		const isolationMode = this.session.settings.get("task.isolation.mode");
+		return renderDescription(
+			this.#discoveredAgents,
+			maxConcurrency,
+			isolationMode !== "none",
+			true,
+			disabledAgents,
+			this.#getTaskSimpleMode(),
+			this.session.settings.get("irc.enabled") === true,
+			this.session.getSessionSpawns() ?? "*",
+		);
+	}
+	private constructor(
+		private readonly session: ToolSession,
+		discoveredAgents: AgentDefinition[],
+	) {
+		this.#blockedAgent = $env.PI_BLOCKED_AGENT;
+		this.#spawningAgentType = session.currentAgentType;
+		this.#discoveredAgents = discoveredAgents;
+	}
+
+	#getTaskSimpleMode(): TaskSimpleMode {
+		return this.session.settings.get("task.simple");
+	}
+
+	/**
+	 * Create a TaskTool instance with async agent discovery.
+	 */
+	static async create(session: ToolSession): Promise<TaskTool> {
+		const { agents } = await discoverAgents(session.cwd);
+		return new TaskTool(session, agents);
+	}
+
+	async execute(
+		_toolCallId: string,
+		rawParams: unknown,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
+	): Promise<AgentToolResult<TaskToolDetails>> {
+		const params = rawParams as TaskParams;
+		const requestedAgentName = params.agent;
+		const agentLookupName = requestedAgentName === "executor_ext" ? "executor" : requestedAgentName;
+		const simpleMode = this.#getTaskSimpleMode();
+		const validationError = validateTaskModeParams(simpleMode, params);
+		if (validationError) {
+			return createTaskModeError(validationError);
+		}
+
+		const taskItems = params.tasks ?? [];
+		const taskIdValidationError = validateTaskIdsForScheduling(taskItems);
+		if (taskIdValidationError) {
+			return createTaskModeError(taskIdValidationError);
+		}
+		if (taskItems.length === 0) {
+			return this.#executeSync(_toolCallId, params, signal, onUpdate);
+		}
+		const agent = getAgent(this.#discoveredAgents, agentLookupName);
+		if (!agent) {
+			const available =
+				filterVisibleAgents(this.#discoveredAgents)
+					.map(a => a.name)
+					.join(", ") || "none";
+			return {
+				content: [{ type: "text", text: `Unknown agent "${params.agent}". Available: ${available}` }],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
+		if (disabledAgents.length > 0 && disabledAgents.includes(requestedAgentName)) {
+			const enabled = filterVisibleAgents(this.#discoveredAgents)
+				.filter(a => !disabledAgents.includes(a.name))
+				.map(a => a.name);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Agent "${params.agent}" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(", ")}` : ""}`,
+					},
+				],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const forkContextValidationError = validateForkContextRequests(
+			taskItems,
+			agent,
+			this.session.settings.get("task.forkContext.enabled"),
+		);
+		if (forkContextValidationError) {
+			return createTaskModeError(forkContextValidationError);
+		}
+
+		const batchGateDecision = evaluateSpawnGate({ childCount: taskItems.length, plan: params.spawnPlan });
+		if (batchGateDecision.outcome === "rejected") {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Task spawn gate rejected this batch: ${batchGateDecision.reason}. Batches with more than ${DEFAULT_SPAWN_THRESHOLD} tasks require spawnPlan fields: ${batchGateDecision.missingFields.join(", ")}.`,
+					},
+				],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const reviewerExploreDecision = evaluateReviewerExploreGate({
+			spawningAgentType: this.#spawningAgentType,
+			targetAgent: requestedAgentName,
+			plan: params.spawnPlan,
+		});
+		if (reviewerExploreDecision.outcome === "rejected") {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Task spawn gate rejected reviewer->explore: ${reviewerExploreDecision.reason}. Provide spawnPlan fields: ${reviewerExploreDecision.missingFields.join(", ")}.`,
+					},
+				],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const manager = AsyncJobManager.instance();
+		if (!manager) {
+			return {
+				content: [{ type: "text", text: "Subagent background execution is unavailable in this session." }],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const outputManager =
+			this.session.agentOutputManager ?? new AgentOutputManager(this.session.getArtifactsDir ?? (() => null));
+		const uniqueIds = await outputManager.allocateBatch(taskItems.map(t => t.id));
+		const fallbackAgentSource =
+			this.#discoveredAgents.find(agent => agent.name === params.agent)?.source ?? "bundled";
+		const progressByTaskId = new Map<string, AgentProgress>();
+		for (let index = 0; index < taskItems.length; index++) {
+			const taskItem = taskItems[index];
+			const assignment = taskItem.assignment.trim();
+			progressByTaskId.set(taskItem.id, {
+				index,
+				id: taskItem.id,
+				agent: params.agent,
+				agentSource: fallbackAgentSource,
+				status: "pending",
+				task: renderSubagentUserPrompt(assignment, simpleMode),
+				assignment,
+				description: taskItem.description,
+				recentTools: [],
+				recentOutput: [],
+				toolCount: 0,
+				tokens: 0,
+				cost: 0,
+				durationMs: 0,
+			});
+		}
+
+		const startedJobs: Array<{ jobId: string; taskId: string }> = [];
+		const failedSchedules: string[] = [];
+		let completedJobs = 0;
+		let failedJobs = 0;
+
+		const getProgressSnapshot = (): AgentProgress[] => {
+			return Array.from(progressByTaskId.values())
+				.sort((a, b) => a.index - b.index)
+				.map(progress => structuredClone(progress));
+		};
+
+		const buildAsyncDetails = (state: "running" | "completed" | "failed", jobId: string): TaskToolDetails => ({
+			projectAgentsDir: null,
+			results: [],
+			totalDurationMs: 0,
+			progress: getProgressSnapshot(),
+			async: { state, jobId, type: "task" },
+		});
+
+		const emitAsyncUpdate = (state: "running" | "completed" | "failed", text: string): void => {
+			const primaryJobId = startedJobs[0]?.jobId ?? "task";
+			onUpdate?.({
+				content: [{ type: "text", text }],
+				details: buildAsyncDetails(state, primaryJobId),
+			});
+		};
+
+		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
+		if (typeof manager.setResumeRunner === "function") {
+			manager.setResumeRunner((_subagentId, message, resumeDescriptor) => {
+				const descriptor = isTaskResumeDescriptor(resumeDescriptor?.data) ? resumeDescriptor.data : undefined;
+				if (!descriptor) return undefined;
+				const forkSeeds = descriptor.forkContextSeed
+					? new Map([[descriptor.task.id, descriptor.forkContextSeed]])
+					: undefined;
+				return manager.register(
+					"task",
+					descriptor.task.id,
+					async ({ signal: runSignal }) => {
+						const result = await this.#executeSync(
+							descriptor.toolCallId,
+							{ ...descriptor.params, tasks: [descriptor.task] },
+							runSignal,
+							undefined,
+							[descriptor.task.id],
+							forkSeeds,
+							{
+								runMode: message ? "message" : "resume",
+								resumeMessage: message,
+								sessionFiles: new Map([[descriptor.task.id, descriptor.sessionFile]]),
+							},
+						);
+						const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
+						const singleResult = result.details?.results[0];
+						return singleResult?.paused ? { kind: "paused" } : finalText;
+					},
+					{
+						id: `${descriptor.task.id}-resume-${Snowflake.next()}`,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						metadata: {
+							subagent: {
+								id: descriptor.task.id,
+								agent: descriptor.params.agent,
+								agentSource: descriptor.agentSource,
+								description: descriptor.task.description,
+								assignment: descriptor.task.assignment.trim(),
+							},
+						},
+					},
+				);
+			});
+		}
+		const semaphore = new Semaphore(maxConcurrency);
+		const buildForkContextSeedForTask = async (task: TaskItem): Promise<ForkContextSeed | undefined> => {
+			if (params.agent === "executor") return undefined;
+			if (!requestsForkContext(task)) return undefined;
+			if (!this.session.buildForkContextSeed) {
+				throw new Error("Current session cannot build fork-context seeds.");
+			}
+			const configuredMaxMessages = this.session.settings.has("task.forkContext.maxMessages")
+				? this.session.settings.get("task.forkContext.maxMessages")
+				: undefined;
+			const configuredMaxTokens = this.session.settings.get("task.forkContext.maxTokens");
+			const seedParams = resolveForkSeedParamsForMode(
+				task.inheritContext,
+				configuredMaxMessages,
+				configuredMaxTokens,
+				this.session.model,
+			);
+			if (!seedParams) return undefined;
+			return await this.session.buildForkContextSeed({
+				...seedParams,
+				signal,
+			});
+		};
+		const frozenForkSeeds = new Map<string, ForkContextSeed>();
+		const parentSessionFileForBatch = this.session.getSessionFile();
+		const batchArtifactsDir = parentSessionFileForBatch ? parentSessionFileForBatch.slice(0, -6) : null;
+
+		for (let i = 0; i < taskItems.length; i++) {
+			const taskItem = taskItems[i];
+			if (signal?.aborted) {
+				failedSchedules.push(`${taskItem.id}: cancelled before scheduling`);
+				const progress = progressByTaskId.get(taskItem.id);
+				if (progress) {
+					progress.status = "aborted";
+				}
+				continue;
+			}
+
+			const uniqueId = validateAllocatedTaskId(uniqueIds[i] ?? "");
+			const frozenForkSeed = await buildForkContextSeedForTask(taskItem);
+			if (frozenForkSeed) frozenForkSeeds.set(uniqueId, frozenForkSeed);
+			const singleParams: TaskParams = { ...params, tasks: [taskItem] };
+			const label = uniqueId;
+			try {
+				const subtaskSessionFile = batchArtifactsDir ? path.join(batchArtifactsDir, `${uniqueId}.jsonl`) : null;
+				const jobId = manager.register(
+					"task",
+					label,
+					async ({ signal: runSignal, reportProgress }) => {
+						const startedAt = Date.now();
+						const progress = progressByTaskId.get(taskItem.id);
+						await semaphore.acquire();
+						if (runSignal.aborted) {
+							semaphore.release();
+							if (progress) {
+								progress.status = "aborted";
+							}
+							throw new Error("Aborted before execution");
+						}
+						if (progress) {
+							progress.status = "running";
+						}
+						await reportProgress(
+							`Running background task ${taskItem.id}...`,
+							buildAsyncDetails("running", startedJobs[0]?.jobId ?? label) as unknown as Record<string, unknown>,
+						);
+						try {
+							const result = await this.#executeSync(
+								_toolCallId,
+								singleParams,
+								runSignal,
+								undefined,
+								[uniqueId],
+								frozenForkSeeds,
+								{
+									sessionFiles: new Map([[uniqueId, subtaskSessionFile]]),
+								},
+							);
+							const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
+							const singleResult = result.details?.results[0];
+							if (progress) {
+								progress.status = singleResult?.paused
+									? "paused"
+									: singleResult?.aborted
+										? "aborted"
+										: singleResult?.status === "completed"
+											? "completed"
+											: "failed";
+								progress.durationMs = singleResult?.durationMs ?? Math.max(0, Date.now() - startedAt);
+								progress.tokens = singleResult?.tokens ?? 0;
+								progress.contextTokens = singleResult?.contextTokens;
+								progress.contextWindow = singleResult?.contextWindow;
+								progress.cost = singleResult?.usage?.cost.total ?? 0;
+								progress.extractedToolData = undefined;
+								progress.retryFailure = singleResult?.retryFailure
+									? {
+											attempt: singleResult.retryFailure.attempt,
+											errorMessage: singleResult.retryFailure.errorSummary,
+										}
+									: undefined;
+								progress.retryState = undefined;
+							}
+							completedJobs += 1;
+							if (singleResult && ((singleResult.aborted ?? false) || singleResult.exitCode !== 0)) {
+								failedJobs += 1;
+							}
+							const remaining = taskItems.length - completedJobs;
+							const isDone = remaining === 0;
+							await reportProgress(
+								isDone
+									? `Background task batch complete: ${completedJobs}/${taskItems.length} finished.`
+									: `Background task batch progress: ${completedJobs}/${taskItems.length} finished (${remaining} running).`,
+								buildAsyncDetails(
+									isDone ? (failedJobs > 0 || failedSchedules.length > 0 ? "failed" : "completed") : "running",
+									startedJobs[0]?.jobId ?? label,
+								) as unknown as Record<string, unknown>,
+							);
+							if (isDone) {
+								emitAsyncUpdate(
+									failedJobs > 0 || failedSchedules.length > 0 ? "failed" : "completed",
+									`Background task batch complete: ${completedJobs}/${taskItems.length} finished.`,
+								);
+							}
+							if (singleResult?.paused) {
+								return { kind: "paused" };
+							}
+							return finalText;
+						} catch (error) {
+							if (progress) {
+								progress.status = "failed";
+								progress.durationMs = Math.max(0, Date.now() - startedAt);
+							}
+							completedJobs += 1;
+							failedJobs += 1;
+							const remaining = taskItems.length - completedJobs;
+							const isDone = remaining === 0;
+							await reportProgress(
+								isDone
+									? `Background task batch complete with failures: ${failedJobs} failed.`
+									: `Background task batch progress: ${completedJobs}/${taskItems.length} finished (${remaining} running).`,
+								buildAsyncDetails(
+									isDone ? "failed" : "running",
+									startedJobs[0]?.jobId ?? label,
+								) as unknown as Record<string, unknown>,
+							);
+							if (isDone) {
+								emitAsyncUpdate(
+									"failed",
+									`Background task batch complete with failures: ${failedJobs} failed.`,
+								);
+							}
+							throw error;
+						} finally {
+							semaphore.release();
+						}
+					},
+					{
+						id: label,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						metadata: {
+							subagent: {
+								id: uniqueId,
+								agent: params.agent,
+								agentSource: fallbackAgentSource,
+								description: taskItem.description,
+								assignment: taskItem.assignment.trim(),
+							},
+						},
+						onProgress: (text, details) => {
+							const progressDetails =
+								(details as TaskToolDetails | undefined) ??
+								buildAsyncDetails("running", startedJobs[0]?.jobId ?? label);
+							onUpdate?.({ content: [{ type: "text", text }], details: progressDetails });
+						},
+					},
+				);
+				startedJobs.push({ jobId, taskId: taskItem.id });
+				if (typeof manager.registerResumeDescriptor === "function") {
+					manager.registerResumeDescriptor({
+						subagentId: uniqueId,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						data: {
+							toolCallId: _toolCallId,
+							params,
+							task: { ...taskItem, id: uniqueId },
+							sessionFile: subtaskSessionFile,
+							forkContextSeed: frozenForkSeed,
+							agentSource: fallbackAgentSource,
+						} satisfies TaskResumeDescriptor,
+					});
+				}
+				if (typeof manager.registerSubagentRecord === "function") {
+					manager.registerSubagentRecord({
+						subagentId: uniqueId,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						currentJobId: jobId,
+						historicalJobIds: [],
+						status: manager.getJob(jobId)?.status ?? "running",
+						sessionFile: subtaskSessionFile,
+						resumable: !!batchArtifactsDir,
+					});
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				failedSchedules.push(`${taskItem.id}: ${message}`);
+				const progress = progressByTaskId.get(taskItem.id);
+				if (progress) {
+					progress.status = "failed";
+				}
+			}
+		}
+
+		if (startedJobs.length === 0) {
+			const failureText = `Failed to start background task jobs: ${failedSchedules.join("; ")}`;
+			return {
+				content: [{ type: "text", text: failureText }],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		emitAsyncUpdate(
+			"running",
+			`Launching ${startedJobs.length} background ${startedJobs.length === 1 ? "task" : "tasks"}...`,
+		);
+
+		const scheduleFailureSummary =
+			failedSchedules.length > 0
+				? ` Failed to schedule ${failedSchedules.length} task${failedSchedules.length === 1 ? "" : "s"}.`
+				: "";
+
+		const ircEnabled = this.session.settings.get("irc.enabled") === true;
+		const taskIdByItemId = new Map<string, string>();
+		for (let i = 0; i < taskItems.length; i++) {
+			taskIdByItemId.set(taskItems[i].id, uniqueIds[i]);
+		}
+		const startedListing = startedJobs
+			.map(({ taskId, jobId }) => {
+				const id = taskIdByItemId.get(taskId) ?? taskId;
+				const desc = progressByTaskId.get(taskId)?.description;
+				const prefix = `- \`${id}\` (job \`${jobId}\`)`;
+				return desc ? `${prefix} — ${desc}` : prefix;
+			})
+			.join("\n");
+		const coordinationHint = ircEnabled
+			? ` DM these ids via \`irc\` to coordinate while they run. Use \`subagent\` to list, inspect, or await with a timeout; a timeout only bounds your wait and is never a cancellation reason. Cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; \`job\` remains available for generic background jobs.`
+			: ` Use \`subagent\` to list, inspect, or await with a timeout; a timeout only bounds your wait and is never a cancellation reason. Cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; \`job\` remains available for generic background jobs.`;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Started ${startedJobs.length} background task job${startedJobs.length === 1 ? "" : "s"} using ${params.agent}.${scheduleFailureSummary} Results will be delivered when complete.\n${startedListing}\n${coordinationHint}`,
+				},
+			],
+			details: {
+				projectAgentsDir: null,
+				results: [],
+				totalDurationMs: 0,
+				progress: getProgressSnapshot(),
+				async: { state: "running", jobId: startedJobs[0].jobId, type: "task" },
+			},
+		};
+	}
+
+	async #executeSync(
+		_toolCallId: string,
+		params: TaskParams,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
+		preAllocatedIds?: string[],
+		prebuiltForkContextSeeds?: ReadonlyMap<string, ForkContextSeed>,
+		executionOverrides?: {
+			runMode?: "initial" | "resume" | "message";
+			resumeMessage?: string;
+			sessionFiles?: ReadonlyMap<string, string | null>;
+		},
+	): Promise<AgentToolResult<TaskToolDetails>> {
+		const startTime = Date.now();
+		const { agents, projectAgentsDir } = await discoverAgents(this.session.cwd);
+		const { agent: requestedAgentName, context, schema: outputSchema } = params;
+		const agentName = requestedAgentName === "executor_ext" ? "executor_ext" : requestedAgentName;
+		const agentLookupName = requestedAgentName === "executor_ext" ? "executor" : requestedAgentName;
+		const simpleMode = this.#getTaskSimpleMode();
+		const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
+		const sharedContext = contextEnabled ? context?.trim() : undefined;
+		const isolationMode = this.session.settings.get("task.isolation.mode");
+		const isolationRequested = "isolated" in params ? params.isolated === true : false;
+		const isIsolated = isolationMode !== "none" && isolationRequested;
+		const mergeMode = this.session.settings.get("task.isolation.merge");
+		const commitStyle = this.session.settings.get("task.isolation.commits");
+		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
+		const taskDepth = this.session.taskDepth ?? 0;
+		const subagentLspEnabled = (this.session.enableLsp ?? true) && this.session.settings.get("task.enableLsp");
+
+		if (isolationMode === "none" && "isolated" in params) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: "Task isolation is disabled.",
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: 0,
+				},
+			};
+		}
+
+		// Validate agent exists
+		const agent = getAgent(agents, agentLookupName);
+		if (!agent) {
+			const available =
+				filterVisibleAgents(agents)
+					.map(a => a.name)
+					.join(", ") || "none";
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Unknown agent "${agentName}". Available: ${available}`,
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: 0,
+				},
+			};
+		}
+
+		// Check if agent is disabled in settings
+		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
+		if (disabledAgents.length > 0 && disabledAgents.includes(agentName)) {
+			const enabled = filterVisibleAgents(agents)
+				.filter(a => !disabledAgents.includes(a.name))
+				.map(a => a.name);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Agent "${agentName}" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(", ")}` : ""}`,
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: 0,
+				},
+			};
+		}
+
+		const forkContextValidationError = validateForkContextRequests(
+			params.tasks ?? [],
+			agent,
+			this.session.settings.get("task.forkContext.enabled"),
+		);
+		if (forkContextValidationError) {
+			return createTaskModeError(forkContextValidationError);
+		}
+
+		const planModeState = this.session.getPlanModeState?.();
+		const planModeTools = ["read", "search", "find", "lsp", "web_search"];
+		const planModeAgent: typeof agent = planModeState?.enabled
+			? {
+					...agent,
+					systemPrompt: `${planModeSubagentPrompt}\n\n${agent.systemPrompt}`,
+					tools: planModeTools,
+					spawns: undefined,
+				}
+			: agent;
+		const effectiveAgent: typeof agent =
+			agentName === "executor"
+				? {
+						...planModeAgent,
+						systemPrompt: `${planModeAgent.systemPrompt}\n\n${executorSelfForkPrompt}`,
+					}
+				: planModeAgent;
+
+		// Apply per-agent model override from settings (highest priority)
+		const agentModelOverrides = this.session.settings.get("task.agentModelOverrides");
+		const settingsModelOverride =
+			agentName === "executor"
+				? undefined
+				: agentName === "executor_ext"
+					? (agentModelOverrides.executor_ext ?? agentModelOverrides.executor)
+					: agentModelOverrides[agentName];
+		const parentActiveModelPattern = this.session.getActiveModelString?.();
+		const modelOverride = resolveAgentModelPatterns({
+			settingsOverride: settingsModelOverride,
+			agentModel: effectiveAgent.model,
+			settings: this.session.settings,
+			activeModelPattern: parentActiveModelPattern,
+			fallbackModelPattern: this.session.getModelString?.(),
+		});
+		const thinkingLevelOverride = effectiveAgent.thinkingLevel;
+
+		// Output schema priority: task call > agent frontmatter > inherited parent session.
+		// task.simple can disable the task-call override while leaving agent/session schemas intact.
+		const effectiveOutputSchema = customSchemaEnabled
+			? (outputSchema ?? effectiveAgent.output ?? this.session.outputSchema)
+			: (effectiveAgent.output ?? this.session.outputSchema);
+
+		// Handle empty or missing tasks
+		if (!params.tasks || params.tasks.length === 0) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: contextEnabled
+							? "No tasks provided. Use: { agent, context?, tasks: [{ id, description, assignment }, ...] }"
+							: "No tasks provided. Use: { agent, tasks: [{ id, description, assignment }, ...] }",
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: 0,
+				},
+			};
+		}
+
+		const tasks = params.tasks;
+		const missingTaskIndexes: number[] = [];
+		const idIndexes = new Map<string, number[]>();
+
+		for (let i = 0; i < tasks.length; i++) {
+			const id = tasks[i]?.id;
+			if (typeof id !== "string" || id.trim() === "") {
+				missingTaskIndexes.push(i);
+				continue;
+			}
+			const normalizedId = id.toLowerCase();
+			const indexes = idIndexes.get(normalizedId);
+			if (indexes) {
+				indexes.push(i);
+			} else {
+				idIndexes.set(normalizedId, [i]);
+			}
+		}
+
+		const duplicateIds: Array<{ id: string; indexes: number[] }> = [];
+		for (const [normalizedId, indexes] of idIndexes.entries()) {
+			if (indexes.length > 1) {
+				duplicateIds.push({
+					id: tasks[indexes[0]]?.id ?? normalizedId,
+					indexes,
+				});
+			}
+		}
+
+		if (missingTaskIndexes.length > 0 || duplicateIds.length > 0) {
+			const problems: string[] = [];
+			if (missingTaskIndexes.length > 0) {
+				problems.push(`Missing task ids at indexes: ${missingTaskIndexes.join(", ")}`);
+			}
+			if (duplicateIds.length > 0) {
+				const details = duplicateIds.map(entry => `${entry.id} (indexes ${entry.indexes.join(", ")})`).join("; ");
+				problems.push(`Duplicate task ids detected (case-insensitive): ${details}`);
+			}
+			return {
+				content: [{ type: "text", text: `Invalid tasks: ${problems.join(". ")}` }],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: 0,
+				},
+			};
+		}
+
+		const batchGateDecision = evaluateSpawnGate({ childCount: tasks.length, plan: params.spawnPlan });
+		if (batchGateDecision.outcome === "rejected") {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Task spawn gate rejected this batch: ${batchGateDecision.reason}. Batches with more than ${DEFAULT_SPAWN_THRESHOLD} tasks require spawnPlan fields: ${batchGateDecision.missingFields.join(", ")}.`,
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: Date.now() - startTime,
+				},
+			};
+		}
+
+		const reviewerExploreDecision = evaluateReviewerExploreGate({
+			spawningAgentType: this.#spawningAgentType,
+			targetAgent: agentName,
+			plan: params.spawnPlan,
+		});
+		if (reviewerExploreDecision.outcome === "rejected") {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Task spawn gate rejected reviewer->explore: ${reviewerExploreDecision.reason}. Provide spawnPlan fields: ${reviewerExploreDecision.missingFields.join(", ")}.`,
+					},
+				],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: Date.now() - startTime,
+				},
+			};
+		}
+
+		let repoRoot: string | null = null;
+		let baseline: WorktreeBaseline | null = null;
+		if (isIsolated) {
+			try {
+				repoRoot = await getRepoRoot(this.session.cwd);
+				baseline = await captureBaseline(repoRoot);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Isolated task execution requires a git repository. ${message}`,
+						},
+					],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: Date.now() - startTime,
+					},
+				};
+			}
+		}
+
+		const preferredIsolationBackend = parseIsolationMode(isolationMode);
+
+		// Derive artifacts directory
+		const sessionFile = this.session.getSessionFile();
+		const artifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
+		const tempArtifactsDir = artifactsDir ? null : path.join(os.tmpdir(), `gjc-task-${Snowflake.next()}`);
+		const effectiveArtifactsDir = artifactsDir || tempArtifactsDir!;
+
+		// Share the parent session's local:// root with subagents so they read/write the same scratch space
+		const localProtocolOptions: LocalProtocolOptions = {
+			getArtifactsDir: this.session.getArtifactsDir ?? (() => null),
+			getSessionId: this.session.getSessionId ?? (() => null),
+		};
+
+		// Subagents adopt the parent's ArtifactManager so artifact IDs are unique
+		// across the whole tree and outputs land flat in the parent's dir.
+		const parentArtifactManager = this.session.getArtifactManager?.() ?? undefined;
+
+		// Initialize progress tracking
+		const progressMap = new Map<number, AgentProgress>();
+
+		// Update callback
+		const emitProgress = () => {
+			const progress = Array.from(progressMap.values()).sort((a, b) => a.index - b.index);
+			onUpdate?.({
+				content: [{ type: "text", text: `Running ${params.tasks.length} agents...` }],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: Date.now() - startTime,
+					progress,
+				},
+			});
+		};
+
+		try {
+			// Check self-recursion prevention
+			if (this.#blockedAgent && agentName === this.#blockedAgent) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Cannot spawn ${this.#blockedAgent} agent from within itself (recursion prevention). Use a different agent type.`,
+						},
+					],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: Date.now() - startTime,
+					},
+				};
+			}
+
+			// Check spawn restrictions from parent
+			const parentSpawns = this.session.getSessionSpawns() ?? "*";
+			const allowedSpawns = parentSpawns.split(",").map(s => s.trim());
+			const isSpawnAllowed = (): boolean => {
+				if (parentSpawns === "") return false; // Empty = deny all
+				if (parentSpawns === "*") return true; // Wildcard = allow all
+				return allowedSpawns.includes(agentName);
+			};
+
+			if (!isSpawnAllowed()) {
+				const allowed =
+					parentSpawns === ""
+						? "none (spawns disabled for this agent)"
+						: filterVisibleAgents(agents)
+								.filter(candidate => allowedSpawns.includes(candidate.name))
+								.map(candidate => candidate.name)
+								.join(", ") || "none";
+				return {
+					content: [{ type: "text", text: `Cannot spawn '${agentName}'. Allowed: ${allowed}` }],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: Date.now() - startTime,
+					},
+				};
+			}
+
+			// Write parent conversation context for subagents. When IRC is available,
+			// subagents should ask live peers instead of reading a stale markdown dump.
+			await fs.mkdir(effectiveArtifactsDir, { recursive: true });
+			const shouldWriteConversationContext = this.session.settings.get("irc.enabled") !== true;
+			const compactContext = shouldWriteConversationContext ? this.session.getCompactContext?.() : undefined;
+			let contextFilePath: string | undefined;
+			if (compactContext) {
+				contextFilePath = path.join(effectiveArtifactsDir, "context.md");
+				await Bun.write(contextFilePath, compactContext);
+			}
+
+			// Build full prompts with context prepended
+			// Allocate unique IDs across the session to prevent artifact collisions
+			let uniqueIds: string[];
+			if (preAllocatedIds && preAllocatedIds.length === tasks.length) {
+				uniqueIds = preAllocatedIds;
+			} else {
+				const outputManager =
+					this.session.agentOutputManager ?? new AgentOutputManager(this.session.getArtifactsDir ?? (() => null));
+				uniqueIds = await outputManager.allocateBatch(tasks.map(t => t.id));
+			}
+			const tasksWithUniqueIds = tasks.map((t, i) => ({ ...t, id: validateAllocatedTaskId(uniqueIds[i] ?? "") }));
+
+			const availableSkills = [...(this.session.skills ?? [])];
+			// Resolve autoload skills from agent definition against available skills
+			const resolvedAutoloadSkills =
+				agent.autoloadSkills?.length && availableSkills.length > 0
+					? agent.autoloadSkills
+							.map(name => availableSkills.find(s => s.name === name))
+							.filter((s): s is NonNullable<typeof s> => s !== undefined)
+					: [];
+			const contextFiles = this.session.contextFiles;
+			const promptTemplates = this.session.promptTemplates;
+
+			type WorkflowActorRouting =
+				| { kind: "none" }
+				| { kind: "busy"; actor: WorkflowActorRecord }
+				| { kind: "actor"; actor: WorkflowActorRecord; runMode: "initial" | "message" };
+
+			const resolveWorkflowActorForTask = async (
+				task: (typeof tasksWithUniqueIds)[number],
+				modelPattern: string | string[] | undefined,
+			): Promise<WorkflowActorRouting> => {
+				if (executionOverrides?.runMode || executionOverrides?.resumeMessage || agentName === "executor_ext") {
+					return { kind: "none" };
+				}
+				const workflowSessionId = this.session.getSessionId?.();
+				if (!workflowSessionId || !artifactsDir) return { kind: "none" };
+
+				const pabcdState = await readPabcdStateWithFallback(this.session.cwd, workflowSessionId);
+				if (pabcdState?.ok !== true || pabcdState.value.active !== true) {
+					return { kind: "none" };
+				}
+				const phase = pabcdState.value.current_phase;
+				if (!isPabcdActorStage(phase)) return { kind: "none" };
+				const namespaceId = pabcdState.value.ctx?.actor_namespace_id;
+				if (typeof namespaceId !== "string" || namespaceId.length === 0) return { kind: "none" };
+
+				const modelId = firstModelPattern(modelPattern ?? effectiveAgent.model);
+				const actorRoleAgent = agentName === "executor" ? "self-fork" : agentName;
+				const key = buildWorkflowActorKey({
+					namespaceId,
+					workflowSessionId,
+					stage: phase,
+					roleAgent: actorRoleAgent,
+					taskId: task.id,
+					description: task.description,
+					modelId,
+					provider: providerFromModelPattern(modelId),
+					thinkingLevel: thinkingLevelOverride,
+					rolePromptHash: hashTaskValue({
+						prompt: effectiveAgent.systemPrompt,
+						source: effectiveAgent.source,
+						filePath: effectiveAgent.filePath,
+					}),
+					cwdOrWorktree: this.session.cwd,
+					writablePolicy: isIsolated ? `isolated:${mergeMode}` : "workspace",
+					toolSurfaceHash: hashTaskValue({ tools: effectiveAgent.tools ?? [], lsp: subagentLspEnabled }),
+				});
+
+				const registry = await readActorRegistry(this.session.cwd, workflowSessionId);
+				const runningActor = findRunningActor(registry, key);
+				if (runningActor) return { kind: "busy", actor: runningActor };
+
+				const compatibleActor = resolveCompatibleActor(registry, key);
+				if (compatibleActor) return { kind: "actor", actor: compatibleActor, runMode: "message" };
+
+				const actorId = workflowActorId(key);
+				const actor = allocateActorRecord(key, path.join(artifactsDir, `${actorId}.jsonl`));
+				await writeActorRegistryAtomic(this.session.cwd, workflowSessionId, upsertActor(registry, actor));
+				return { kind: "actor", actor, runMode: "initial" };
+			};
+
+			const updateWorkflowActor = async (
+				_actor: WorkflowActorRecord,
+				update: (registry: WorkflowActorRegistry) => WorkflowActorRegistry,
+			): Promise<void> => {
+				const workflowSessionId = this.session.getSessionId?.();
+				if (!workflowSessionId) return;
+				const registry = await readActorRegistry(this.session.cwd, workflowSessionId);
+				await writeActorRegistryAtomic(this.session.cwd, workflowSessionId, update(registry));
+			};
+
+			const maintainWorkflowActorBeforeResume = async (
+				actor: WorkflowActorRecord,
+			): Promise<{ ok: true; cacheAffinity: CacheAffinityMetadata } | { ok: false; reason: string }> => {
+				try {
+					const stat = await fs.stat(actor.sessionFile);
+					if (!stat.isFile()) return { ok: false, reason: "actor session file is not a file" };
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return { ok: false, reason: message || "actor session file is unavailable" };
+				}
+
+				if (actor.needsCompact) {
+					await updateWorkflowActor(actor, registry =>
+						markActorMaintained(registry, actor.id, {
+							compactedAt: new Date().toISOString(),
+							needsCompact: false,
+						}),
+					);
+				}
+
+				return { ok: true, cacheAffinity: { affine: true, reason: "actor_resume", prewarm: "skipped" } };
+			};
+
+			// Initialize progress for all tasks
+			for (let i = 0; i < tasksWithUniqueIds.length; i++) {
+				const taskItem = tasksWithUniqueIds[i];
+				const assignment = taskItem.assignment.trim();
+				progressMap.set(i, {
+					index: i,
+					id: taskItem.id,
+					agent: agentName,
+					agentSource: agent.source,
+					status: "pending",
+					task: renderSubagentUserPrompt(assignment, simpleMode),
+					assignment,
+					recentTools: [],
+					recentOutput: [],
+					toolCount: 0,
+					tokens: 0,
+					cost: 0,
+					durationMs: 0,
+					modelOverride,
+					description: taskItem.description,
+				});
+			}
+			emitProgress();
+
+			const buildForkContextSeed = async (
+				mode: Exclude<ForkContextMode, "none">,
+			): Promise<ForkContextSeed | undefined> => {
+				if (!this.session.buildForkContextSeed) {
+					throw new Error("Current session cannot build fork-context seeds.");
+				}
+				const configuredMaxMessages = this.session.settings.has("task.forkContext.maxMessages")
+					? this.session.settings.get("task.forkContext.maxMessages")
+					: undefined;
+				const configuredMaxTokens = this.session.settings.get("task.forkContext.maxTokens");
+				const params = resolveForkSeedParamsForMode(
+					mode,
+					configuredMaxMessages,
+					configuredMaxTokens,
+					this.session.model,
+				);
+				if (!params) return undefined;
+				return await this.session.buildForkContextSeed({
+					...params,
+					signal,
+				});
+			};
+
+			const runTask = async (
+				task: (typeof tasksWithUniqueIds)[number],
+				index: number,
+				overrides?: {
+					runMode?: "initial" | "resume" | "message";
+					resumeMessage?: string;
+					sessionFile?: string | null;
+				},
+			) => {
+				const userPresets = this.session.settings.get("task.modelPresets") as
+					| Record<string, { best?: string; cheap?: string }>
+					| undefined;
+				const perTaskModel = resolveModelHint(task.model, userPresets);
+				const effectiveModelOverride =
+					agentName === "executor_ext" && perTaskModel && modelOverride.length > 0
+						? [...perTaskModel, ...modelOverride]
+						: (perTaskModel ?? modelOverride);
+				const actorRouting = await resolveWorkflowActorForTask(task, effectiveModelOverride);
+				if (actorRouting.kind === "busy") {
+					return buildActorBusyResult(
+						task,
+						index,
+						agentName,
+						agent.source,
+						effectiveModelOverride,
+						simpleMode,
+						actorRouting.actor,
+					);
+				}
+				let cacheAffinity: CacheAffinityMetadata | undefined =
+					agentName === "executor_ext" ? { affine: false, reason: "executor_ext" } : undefined;
+				if (actorRouting.kind === "actor" && actorRouting.runMode === "message") {
+					const maintenance = await maintainWorkflowActorBeforeResume(actorRouting.actor);
+					if (!maintenance.ok) {
+						return buildActorContextUnavailableResult(
+							task,
+							index,
+							agentName,
+							agent.source,
+							effectiveModelOverride,
+							simpleMode,
+							actorRouting.actor,
+							maintenance.reason,
+						);
+					}
+					cacheAffinity = maintenance.cacheAffinity;
+				} else if (
+					actorRouting.kind === "actor" &&
+					actorRouting.runMode === "initial" &&
+					agentName === "executor"
+				) {
+					cacheAffinity = { affine: true, reason: "self_fork", prewarm: "skipped" };
+				}
+				const shouldCreateExecutorForkSeed =
+					agentName === "executor" &&
+					(actorRouting.kind === "none" ||
+						(actorRouting.kind === "actor" && actorRouting.runMode === "initial")) &&
+					task.inheritContext !== "none" &&
+					this.session.buildForkContextSeed !== undefined;
+				const forkContextMode: Exclude<ForkContextMode, "none"> | undefined = shouldCreateExecutorForkSeed
+					? requestsForkContext(task)
+						? task.inheritContext
+						: "full"
+					: agentName !== "executor" && requestsForkContext(task)
+						? task.inheritContext
+						: undefined;
+				const forkContextSeed =
+					agentName === "executor"
+						? forkContextMode
+							? await buildForkContextSeed(forkContextMode)
+							: undefined
+						: (prebuiltForkContextSeeds?.get(task.id) ??
+							(forkContextMode ? await buildForkContextSeed(forkContextMode) : undefined));
+				const forkContext = forkContextMode
+					? { mode: forkContextMode, clonedTokens: forkContextSeed?.metadata.approximateTokens ?? 0 }
+					: undefined;
+				const actorRunMode = actorRouting.kind === "actor" ? actorRouting.runMode : undefined;
+				const actorResumeMessage =
+					actorRouting.kind === "actor" && actorRouting.runMode === "message"
+						? renderSubagentUserPrompt(task.assignment, simpleMode)
+						: undefined;
+				let taskSessionFile =
+					actorRouting.kind === "actor"
+						? actorRouting.actor.sessionFile
+						: (overrides?.sessionFile ?? executionOverrides?.sessionFiles?.get(task.id) ?? null);
+				if (actorRouting.kind === "actor") {
+					await updateWorkflowActor(actorRouting.actor, registry =>
+						markActorRunning(registry, actorRouting.actor.id, task.id),
+					);
+				}
+				let finalizeWorkflowActorResult = async (result: SingleResult): Promise<void> => {
+					if (actorRouting.kind !== "actor") return;
+					await updateWorkflowActor(actorRouting.actor, registry =>
+						result.paused
+							? markActorPaused(
+									registry,
+									actorRouting.actor.id,
+									taskSessionFile ?? actorRouting.actor.sessionFile,
+									task.id,
+								)
+							: result.exitCode === 0 && !result.error
+								? markActorIdle(
+										registry,
+										actorRouting.actor.id,
+										taskSessionFile ?? actorRouting.actor.sessionFile,
+										task.id,
+									)
+								: markActorFailed(
+										registry,
+										actorRouting.actor.id,
+										result.error ?? result.stderr ?? "subagent failed",
+										task.id,
+									),
+					);
+				};
+				const runSubprocessBaseArgs = {
+					cwd: this.session.cwd,
+					agent: effectiveAgent,
+					task: renderSubagentUserPrompt(task.assignment, simpleMode),
+					assignment: task.assignment.trim(),
+					context: sharedContext,
+					description: task.description,
+					index,
+					id: task.id,
+					subagentId: task.id,
+					taskDepth,
+					modelOverride: effectiveModelOverride,
+					parentActiveModelPattern,
+					parentSessionId: this.session.getSessionId?.() ?? undefined,
+					thinkingLevel: thinkingLevelOverride,
+					outputSchema: effectiveOutputSchema,
+					persistArtifacts: !!artifactsDir,
+					artifactsDir: effectiveArtifactsDir,
+					contextFile: contextFilePath,
+					enableLsp: subagentLspEnabled,
+					signal,
+					eventBus: this.session.eventBus,
+					onProgress: (progress: AgentProgress) => {
+						progressMap.set(index, {
+							...structuredClone(progress),
+						});
+						AsyncJobManager.instance()?.recordSubagentProgress(task.id, progress);
+						emitProgress();
+					},
+					authStorage: this.session.authStorage,
+					modelRegistry: this.session.modelRegistry,
+					settings: this.session.settings,
+					contextFiles,
+					skills: availableSkills,
+					autoloadSkills: resolvedAutoloadSkills,
+					workspaceTree: this.session.workspaceTree,
+					promptTemplates,
+					localProtocolOptions,
+					parentArtifactManager,
+					parentHindsightSessionState: this.session.getHindsightSessionState?.(),
+					parentTelemetry: this.session.getTelemetry?.(),
+					forkContextSeed,
+				};
+				const attemptFreshFallback = async (
+					result: SingleResult,
+					worktree?: string,
+				): Promise<
+					{ result: SingleResult; freshActor: WorkflowActorRecord; freshSessionFile: string } | undefined
+				> => {
+					if (actorRouting.kind !== "actor" || actorRouting.runMode !== "message") return undefined;
+					if (result.paused || result.aborted) return undefined;
+					if (result.exitCode === 0 && !result.error) return undefined;
+					await finalizeWorkflowActorResult(result);
+					const freshSessionFile = path.join(
+						effectiveArtifactsDir,
+						`${workflowActorId(actorRouting.actor)}-${Date.now()}.jsonl`,
+					);
+					const actorKey: WorkflowActorKey = {
+						namespaceId: actorRouting.actor.namespaceId,
+						workflow: actorRouting.actor.workflow,
+						workflowSessionId: actorRouting.actor.workflowSessionId,
+						stage: actorRouting.actor.stage,
+						lane: actorRouting.actor.lane,
+						roleAgent: actorRouting.actor.roleAgent,
+						modelId: actorRouting.actor.modelId,
+						provider: actorRouting.actor.provider,
+						...(actorRouting.actor.thinkingLevel ? { thinkingLevel: actorRouting.actor.thinkingLevel } : {}),
+						rolePromptHash: actorRouting.actor.rolePromptHash,
+						cwdOrWorktree: actorRouting.actor.cwdOrWorktree,
+						writablePolicy: actorRouting.actor.writablePolicy,
+						toolSurfaceHash: actorRouting.actor.toolSurfaceHash,
+					};
+					const freshActor = allocateActorRecord(actorKey, freshSessionFile);
+					const wfSessionId = this.session.getSessionId?.();
+					if (wfSessionId) {
+						const reg = await readActorRegistry(this.session.cwd, wfSessionId);
+						await writeActorRegistryAtomic(
+							this.session.cwd,
+							wfSessionId,
+							markActorRunning(upsertActor(reg, freshActor), freshActor.id, task.id),
+						);
+					}
+					let freshResult: SingleResult;
+					try {
+						freshResult = await runSubprocess({
+							...runSubprocessBaseArgs,
+							...(worktree ? { worktree } : {}),
+							runMode: "initial",
+							resumeMessage: undefined,
+							sessionFile: freshSessionFile,
+							cacheAffinity: undefined,
+						});
+					} catch (err) {
+						if (wfSessionId) {
+							const reg = await readActorRegistry(this.session.cwd, wfSessionId);
+							const msg = err instanceof Error ? err.message : String(err);
+							await writeActorRegistryAtomic(
+								this.session.cwd,
+								wfSessionId,
+								markActorFailed(reg, freshActor.id, msg || "fresh spawn threw", task.id),
+							);
+						}
+						throw err;
+					}
+					if (wfSessionId) {
+						const reg2 = await readActorRegistry(this.session.cwd, wfSessionId);
+						const updatedReg = freshResult.paused
+							? markActorPaused(reg2, freshActor.id, freshSessionFile, task.id)
+							: freshResult.exitCode === 0 && !freshResult.error
+								? markActorIdle(reg2, freshActor.id, freshSessionFile, task.id)
+								: markActorFailed(
+										reg2,
+										freshActor.id,
+										freshResult.error ?? freshResult.stderr ?? "fresh spawn failed",
+										task.id,
+									);
+						await writeActorRegistryAtomic(this.session.cwd, wfSessionId, updatedReg);
+					}
+					return { result: freshResult, freshActor, freshSessionFile };
+				};
+				if (!isIsolated) {
+					const result = await runSubprocess({
+						...runSubprocessBaseArgs,
+						runMode: actorRunMode ?? overrides?.runMode ?? executionOverrides?.runMode,
+						resumeMessage: actorResumeMessage ?? overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
+						sessionFile: taskSessionFile,
+						cacheAffinity,
+					});
+					const freshFallback = await attemptFreshFallback(result);
+					if (freshFallback) {
+						const freshWithForkContext = forkContext
+							? { ...freshFallback.result, forkContext }
+							: freshFallback.result;
+						return freshWithForkContext;
+					}
+					const resultWithForkContext = forkContext ? { ...result, forkContext } : result;
+					await finalizeWorkflowActorResult(resultWithForkContext);
+					return resultWithForkContext;
+				}
+
+				const taskStart = Date.now();
+				let isolationHandle: IsolationHandle | undefined;
+				try {
+					if (!repoRoot || !baseline) {
+						throw new Error("Isolated task execution not initialized.");
+					}
+					const taskBaseline = structuredClone(baseline);
+
+					isolationHandle = await ensureIsolation(repoRoot, task.id, preferredIsolationBackend);
+					const isolationDir = isolationHandle.mergedDir;
+
+					let result = await runSubprocess({
+						...runSubprocessBaseArgs,
+						worktree: isolationDir,
+						runMode: actorRunMode ?? overrides?.runMode ?? executionOverrides?.runMode,
+						resumeMessage: actorResumeMessage ?? overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
+						sessionFile: taskSessionFile,
+						cacheAffinity,
+					});
+					// Fresh-spawn fallback for isolated path
+					const freshFallback = await attemptFreshFallback(result, isolationDir);
+					if (freshFallback) {
+						if (
+							freshFallback.result.paused ||
+							freshFallback.result.exitCode !== 0 ||
+							freshFallback.result.error
+						) {
+							// Fresh also failed/paused — helper already finalized, return directly
+							const freshWithForkContext = forkContext
+								? { ...freshFallback.result, forkContext }
+								: freshFallback.result;
+							return freshWithForkContext;
+						}
+						// Fresh succeeded — rebind for merge/patch post-processing
+						result = freshFallback.result;
+						taskSessionFile = freshFallback.freshSessionFile;
+						finalizeWorkflowActorResult = async (r: SingleResult): Promise<void> => {
+							const wfSid = this.session.getSessionId?.();
+							if (!wfSid) return;
+							const reg = await readActorRegistry(this.session.cwd, wfSid);
+							const updated = r.paused
+								? markActorPaused(reg, freshFallback.freshActor.id, freshFallback.freshSessionFile, task.id)
+								: r.exitCode === 0 && !r.error
+									? markActorIdle(reg, freshFallback.freshActor.id, freshFallback.freshSessionFile, task.id)
+									: markActorFailed(
+											reg,
+											freshFallback.freshActor.id,
+											r.error ?? r.stderr ?? "failed",
+											task.id,
+										);
+							await writeActorRegistryAtomic(this.session.cwd, wfSid, updated);
+						};
+					}
+					const resultWithForkContext = forkContext ? { ...result, forkContext } : result;
+					if (mergeMode === "branch" && resultWithForkContext.exitCode === 0) {
+						try {
+							const commitMsg =
+								commitStyle === "ai" && this.session.modelRegistry
+									? async (diff: string) => {
+											return generateCommitMessage(
+												diff,
+												this.session.modelRegistry!,
+												this.session.settings,
+												this.session.getSessionId?.() ?? undefined,
+											);
+										}
+									: undefined;
+							const commitResult = await commitToBranch(
+								isolationDir,
+								taskBaseline,
+								task.id,
+								task.description,
+								commitMsg,
+							);
+							const producedChanges = Boolean(commitResult?.branchName || commitResult?.nestedPatches.length);
+							const mergedResult: SingleResult = {
+								...resultWithForkContext,
+								branchName: commitResult?.branchName,
+								nestedPatches: commitResult?.nestedPatches,
+								producedChanges,
+							};
+							await finalizeWorkflowActorResult(mergedResult);
+							return mergedResult;
+						} catch (mergeErr) {
+							// Agent succeeded but branch commit failed — clean up stale branch
+							const branchName = `gjc/task/${task.id}`;
+							await git.branch.tryDelete(repoRoot, branchName);
+							const msg = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
+							const failedMergeResult: SingleResult = {
+								...resultWithForkContext,
+								error: `Merge failed: ${msg}`,
+							};
+							await finalizeWorkflowActorResult(failedMergeResult);
+							return failedMergeResult;
+						}
+					}
+					if (resultWithForkContext.exitCode === 0) {
+						try {
+							const delta = await captureDeltaPatch(isolationDir, taskBaseline);
+							const artifactId = validateAllocatedTaskId(task.id);
+							const patchPath = path.join(effectiveArtifactsDir, `${artifactId}.patch`);
+							await Bun.write(patchPath, delta.rootPatch);
+							const producedChanges = Boolean(delta.rootPatch.trim() || delta.nestedPatches.length);
+							const patchResult: SingleResult = {
+								...resultWithForkContext,
+								patchPath,
+								nestedPatches: delta.nestedPatches,
+								producedChanges,
+							};
+							await finalizeWorkflowActorResult(patchResult);
+							return patchResult;
+						} catch (patchErr) {
+							const msg = patchErr instanceof Error ? patchErr.message : String(patchErr);
+							const failedPatchResult: SingleResult = {
+								...resultWithForkContext,
+								error: `Patch capture failed: ${msg}`,
+							};
+							await finalizeWorkflowActorResult(failedPatchResult);
+							return failedPatchResult;
+						}
+					}
+					await finalizeWorkflowActorResult(resultWithForkContext);
+					return resultWithForkContext;
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const assignment = task.assignment.trim();
+					const failedResult: SingleResult = {
+						index,
+						id: task.id,
+						agent: agent.name,
+						agentSource: agent.source,
+						task: renderSubagentUserPrompt(assignment, simpleMode),
+						assignment,
+						description: task.description,
+						exitCode: 1,
+						output: "",
+						stderr: message,
+						truncated: false,
+						durationMs: Date.now() - taskStart,
+						tokens: 0,
+						modelOverride,
+						forkContext,
+						error: message,
+					};
+					await finalizeWorkflowActorResult(failedResult);
+					return failedResult;
+				} finally {
+					if (isolationHandle) {
+						await cleanupIsolation(isolationHandle);
+					}
+				}
+			};
+
+			// Execute in parallel with concurrency limit
+			const { results: partialResults, aborted } = await mapWithConcurrencyLimit(
+				tasksWithUniqueIds,
+				maxConcurrency,
+				runTask,
+				signal,
+			);
+
+			// Fill in skipped tasks (undefined entries from abort) with placeholder results
+			const results: SingleResult[] = partialResults.map((result, index) => {
+				if (result !== undefined) {
+					return result;
+				}
+				const task = tasksWithUniqueIds[index];
+				const assignment = task.assignment.trim();
+				return {
+					index,
+					id: task.id,
+					agent: agentName,
+					agentSource: agent.source,
+					task: renderSubagentUserPrompt(assignment, simpleMode),
+					assignment,
+					description: task.description,
+					exitCode: 1,
+					output: "",
+					stderr: "Skipped (cancelled before start)",
+					truncated: false,
+					durationMs: 0,
+					tokens: 0,
+					modelOverride,
+					error: "Cancelled before start",
+					aborted: true,
+					abortReason: "Cancelled before start",
+				};
+			});
+			if (!artifactsDir) {
+				for (const result of results) {
+					delete result.outputMeta;
+					delete result.outputPath;
+				}
+			}
+
+			const forkContextClonedTokens = results.reduce(
+				(total, result) => total + (result.forkContext?.clonedTokens ?? 0),
+				0,
+			);
+
+			// Aggregate usage from executor results (already accumulated incrementally)
+			const aggregatedUsage = createUsageTotals();
+			let hasAggregatedUsage = false;
+			for (const result of results) {
+				if (result.usage) {
+					addUsageTotals(aggregatedUsage, result.usage);
+					hasAggregatedUsage = true;
+				}
+			}
+
+			const patchPaths: string[] = [];
+			for (const result of results) {
+				if (result.patchPath) {
+					patchPaths.push(result.patchPath);
+				}
+			}
+
+			let mergeSummary = "";
+			let changesApplied: boolean | null = null;
+			let hadAnyChanges = false;
+			let mergedBranchesForNestedPatches: Set<string> | null = null;
+			if (isIsolated && repoRoot) {
+				try {
+					if (mergeMode === "branch") {
+						// Branch mode: merge task branches sequentially
+						const branchEntries = results
+							.filter(r => r.branchName && r.exitCode === 0 && !r.aborted)
+							.map(r => ({ branchName: r.branchName!, taskId: r.id, description: r.description }));
+
+						if (branchEntries.length === 0) {
+							changesApplied = true;
+							hadAnyChanges = false;
+							mergeSummary = "\n\nNo changes to apply.";
+						} else {
+							const mergeResult = await mergeTaskBranches(repoRoot, branchEntries);
+							mergedBranchesForNestedPatches = new Set(mergeResult.merged);
+							changesApplied = mergeResult.failed.length === 0;
+							hadAnyChanges = changesApplied && mergeResult.merged.length > 0;
+
+							if (changesApplied) {
+								mergeSummary = hadAnyChanges
+									? `\n\nMerged ${mergeResult.merged.length} branch${mergeResult.merged.length === 1 ? "" : "es"}: ${mergeResult.merged.join(", ")}`
+									: "\n\nNo changes to apply.";
+							} else {
+								const mergedPart =
+									mergeResult.merged.length > 0 ? `Merged: ${mergeResult.merged.join(", ")}.\n` : "";
+								const failedPart = `Failed: ${mergeResult.failed.join(", ")}.`;
+								const conflictPart = mergeResult.conflict ? `\nConflict: ${mergeResult.conflict}` : "";
+								mergeSummary = `\n\n<system-notification>Branch merge failed. ${mergedPart}${failedPart}${conflictPart}\nUnmerged branches remain for manual resolution.</system-notification>`;
+							}
+						}
+
+						// Clean up merged branches (keep failed ones for manual resolution)
+						const allBranches = branchEntries.map(b => b.branchName);
+						if (changesApplied) {
+							await cleanupTaskBranches(repoRoot, allBranches);
+						}
+					} else {
+						// Patch mode: combine and apply patches
+						const patchesInOrder = results.map(result => result.patchPath).filter(Boolean) as string[];
+						const missingPatch = results.some(result => !result.patchPath);
+						if (missingPatch) {
+							changesApplied = false;
+							hadAnyChanges = false;
+						} else {
+							const patchStats = await Promise.all(
+								patchesInOrder.map(async patchPath => ({
+									patchPath,
+									size: (await fs.stat(patchPath)).size,
+								})),
+							);
+							const nonEmptyPatches = patchStats.filter(patch => patch.size > 0).map(patch => patch.patchPath);
+							if (nonEmptyPatches.length === 0) {
+								changesApplied = true;
+								hadAnyChanges = false;
+							} else {
+								const patchTexts = await Promise.all(
+									nonEmptyPatches.map(async patchPath => Bun.file(patchPath).text()),
+								);
+								const combinedPatch = patchTexts
+									.map(text => (text.endsWith("\n") ? text : `${text}\n`))
+									.join("");
+								if (!combinedPatch.trim()) {
+									changesApplied = true;
+									hadAnyChanges = false;
+								} else {
+									changesApplied = await git.patch.canApplyText(repoRoot, combinedPatch);
+									if (changesApplied) {
+										try {
+											await git.patch.applyText(repoRoot, combinedPatch);
+											hadAnyChanges = true;
+										} catch {
+											changesApplied = false;
+											hadAnyChanges = false;
+										}
+									}
+								}
+							}
+						}
+
+						if (changesApplied) {
+							mergeSummary = hadAnyChanges ? "\n\nApplied patches: yes" : "\n\nNo changes to apply.";
+						} else {
+							const notification =
+								"<system-notification>Patches were not applied and must be handled manually.</system-notification>";
+							const patchList =
+								patchPaths.length > 0
+									? `\n\nPatch artifacts: ${patchPaths.length} preserved for internal merge recovery.`
+									: "";
+							mergeSummary = `\n\n${notification}${patchList}`;
+						}
+					}
+				} catch (mergeErr) {
+					const msg = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
+					changesApplied = false;
+					hadAnyChanges = false;
+					mergeSummary = `\n\n<system-notification>Merge phase failed: ${msg}\nTask outputs are preserved but changes were not applied.</system-notification>`;
+				}
+			}
+
+			// Apply nested repo patches (separate from parent git)
+			if (isIsolated && repoRoot && (mergeMode === "branch" || changesApplied !== false)) {
+				const allNestedPatches = results
+					.filter(r => {
+						if (!r.nestedPatches || r.nestedPatches.length === 0 || r.exitCode !== 0 || r.aborted) {
+							return false;
+						}
+						if (mergeMode !== "branch") {
+							return true;
+						}
+						if (!r.branchName || !mergedBranchesForNestedPatches) {
+							return false;
+						}
+						return mergedBranchesForNestedPatches.has(r.branchName);
+					})
+					.flatMap(r => r.nestedPatches!);
+				if (allNestedPatches.length > 0) {
+					try {
+						const commitMsg =
+							commitStyle === "ai" && this.session.modelRegistry
+								? async (diff: string) => {
+										return generateCommitMessage(
+											diff,
+											this.session.modelRegistry!,
+											this.session.settings,
+											this.session.getSessionId?.() ?? undefined,
+										);
+									}
+								: undefined;
+						await applyNestedPatches(repoRoot, allNestedPatches, commitMsg);
+					} catch {
+						// Nested patch failures are non-fatal to the parent merge
+						mergeSummary +=
+							"\n\n<system-notification>Some nested repository patches failed to apply.</system-notification>";
+					}
+				}
+			}
+
+			// Build final output - match plugin format
+			const cancelledCount = results.filter(r => r.aborted).length;
+			const successCount = results.filter(r => r.exitCode === 0 && !r.error && !r.aborted).length;
+			const totalDuration = Date.now() - startTime;
+
+			const receipts = results.map(buildTaskReceipt);
+			const roiSummary = buildTaskRoiSummary(receipts);
+			const summaries = receipts.map(r => {
+				const status = r.status === "merge_failed" ? "merge failed" : r.status;
+				return {
+					agent: r.agent,
+					status,
+					id: r.id,
+					synopsis: r.preview,
+					outputUri: r.outputRef?.uri,
+					meta: r.outputRef
+						? {
+								lineCount: r.outputRef.lineCount,
+								charSize: formatBytes(r.outputRef.sizeBytes),
+							}
+						: undefined,
+				};
+			});
+
+			const summary = prompt.render(taskSummaryTemplate, {
+				successCount,
+				totalCount: results.length,
+				cancelledCount,
+				hasCancelledNote: aborted && cancelledCount > 0,
+				duration: formatDuration(totalDuration),
+				summaries,
+				agentName,
+				mergeSummary,
+			});
+
+			// Cleanup temp directory if used
+			const shouldCleanupTempArtifacts =
+				tempArtifactsDir && (!isIsolated || changesApplied === true || changesApplied === null);
+			if (shouldCleanupTempArtifacts) {
+				await fs.rm(tempArtifactsDir, { recursive: true, force: true });
+			}
+
+			const details: TaskToolDetails = {
+				projectAgentsDir,
+				results: receipts,
+				totalDurationMs: totalDuration,
+				usage: hasAggregatedUsage ? aggregatedUsage : undefined,
+				forkContextClonedTokens: forkContextClonedTokens > 0 ? forkContextClonedTokens : undefined,
+				roiSummary,
+			};
+			assertNoRawTaskFields(details, "task.return.details");
+			return {
+				content: [{ type: "text", text: summary }],
+				details,
+			};
+		} catch (err) {
+			return {
+				content: [{ type: "text", text: `Task execution failed: ${err}` }],
+				details: {
+					projectAgentsDir,
+					results: [],
+					totalDurationMs: Date.now() - startTime,
+				},
+			};
+		}
+	}
+}