@oh-my-pi/pi-coding-agent 12.18.3 → 12.19.0

package/src/slash-commands/builtin-registry.ts

@@ -176,6 +176,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<BuiltinSlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "jobs",
+		description: "Show async background jobs status",
+		handle: async (_command, runtime) => {
+			await runtime.ctx.handleJobsCommand();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "usage",
 		description: "Show provider usage and limits",

package/src/ssh/connection-manager.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { getRemoteHostDir, getSshControlDir } from "@oh-my-pi/pi-utils/dirs";
 import { $ } from "bun";
+import { buildSshTarget, sanitizeHostName } from "./utils";
 
 export interface SSHConnectionTarget {
 	name: string;
@@ -42,11 +43,6 @@ function ensureControlDir() {
 	}
 }
 
-function sanitizeHostName(name: string): string {
-	const sanitized = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
-	return sanitized.length > 0 ? sanitized : "host";
-}
-
 function getHostInfoPath(name: string): string {
 	return path.join(HOST_INFO_DIR, `${sanitizeHostName(name)}.json`);
 }
@@ -71,10 +67,6 @@ async function validateKeyPermissions(keyPath?: string): Promise<void> {
 	}
 }
 
-function buildSshTarget(host: SSHConnectionTarget): string {
-	return host.username ? `${host.username}@${host.host}` : host.host;
-}
-
 function buildCommonArgs(host: SSHConnectionTarget): string[] {
 	const args = [
 		"-o",
@@ -367,7 +359,7 @@ export async function ensureHostInfo(host: SSHConnectionTarget): Promise<SSHHost
 
 export async function buildRemoteCommand(host: SSHConnectionTarget, command: string): Promise<string[]> {
 	await validateKeyPermissions(host.keyPath);
-	return [...buildCommonArgs(host), buildSshTarget(host), command];
+	return [...buildCommonArgs(host), buildSshTarget(host.username, host.host), command];
 }
 
 export async function ensureConnection(host: SSHConnectionTarget): Promise<void> {
@@ -383,7 +375,7 @@ export async function ensureConnection(host: SSHConnectionTarget): Promise<void>
 		ensureControlDir();
 		await validateKeyPermissions(host.keyPath);
 
-		const target = buildSshTarget(host);
+		const target = buildSshTarget(host.username, host.host);
 		const check = await runSshSync(["-O", "check", ...buildCommonArgs(host), target]);
 		if (check.exitCode === 0) {
 			activeHosts.set(key, host);
@@ -414,7 +406,7 @@ export async function ensureConnection(host: SSHConnectionTarget): Promise<void>
 }
 
 async function closeConnectionInternal(host: SSHConnectionTarget): Promise<void> {
-	const target = buildSshTarget(host);
+	const target = buildSshTarget(host.username, host.host);
 	await runSshSync(["-O", "exit", ...buildCommonArgs(host), target]);
 }
 

package/src/ssh/sshfs-mount.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { getRemoteDir } from "@oh-my-pi/pi-utils/dirs";
 import { $ } from "bun";
 import { getControlDir, getControlPathTemplate, type SSHConnectionTarget } from "./connection-manager";
+import { buildSshTarget, sanitizeHostName } from "./utils";
 
 const REMOTE_DIR = getRemoteDir();
 const CONTROL_DIR = getControlDir();
@@ -20,18 +21,13 @@ async function ensureDir(path: string, mode = 0o700): Promise<void> {
 
 function getMountName(host: SSHConnectionTarget): string {
 	const raw = (host.name ?? host.host).trim();
-	const sanitized = raw.replace(/[^a-zA-Z0-9._-]+/g, "_");
-	return sanitized.length > 0 ? sanitized : "remote";
+	return sanitizeHostName(raw);
 }
 
 function getMountPath(host: SSHConnectionTarget): string {
 	return path.join(REMOTE_DIR, getMountName(host));
 }
 
-function buildSshTarget(host: SSHConnectionTarget): string {
-	return host.username ? `${host.username}@${host.host}` : host.host;
-}
-
 function buildSshfsArgs(host: SSHConnectionTarget): string[] {
 	const args = [
 		"-o",
@@ -98,7 +94,7 @@ export async function mountRemote(host: SSHConnectionTarget, remotePath = "/"):
 		return mountPath;
 	}
 
-	const target = `${buildSshTarget(host)}:${remotePath}`;
+	const target = `${buildSshTarget(host.username, host.host)}:${remotePath}`;
 	const args = buildSshfsArgs(host);
 	const result = await $`sshfs ${args} ${target} ${mountPath}`.nothrow();
 

package/src/ssh/utils.ts

@@ -0,0 +1,8 @@
+export function sanitizeHostName(name: string): string {
+	const sanitized = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
+	return sanitized.length > 0 ? sanitized : "remote";
+}
+
+export function buildSshTarget(username: string | undefined, host: string): string {
+	return username ? `${username}@${host}` : host;
+}

package/src/system-prompt.ts

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $env, hasFsCode, isEnoent, logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { $env, hasFsCode, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { getGpuCachePath, getProjectDir } from "@oh-my-pi/pi-utils/dirs";
 import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
@@ -18,14 +18,6 @@ import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
 import type { ToolName } from "./tools";
 
-interface GitContext {
-	isRepo: boolean;
-	currentBranch: string;
-	mainBranch: string;
-	status: string;
-	commits: string;
-}
-
 type PreloadedSkill = { name: string; content: string };
 
 async function loadPreloadedSkillContents(preloadedSkills: Skill[]): Promise<PreloadedSkill[]> {
@@ -44,54 +36,6 @@ async function loadPreloadedSkillContents(preloadedSkills: Skill[]): Promise<Pre
 	return contents;
 }
 
-/**
- * Load git context for the system prompt.
- * Returns structured git data or null if not in a git repo.
- */
-export async function loadGitContext(cwd: string): Promise<GitContext | null> {
-	const timeout = 3000;
-	const abortSignal = AbortSignal.timeout(timeout);
-
-	const git = async (...args: string[]): Promise<string | null> => {
-		const proc = Bun.spawn(["git", ...args], {
-			cwd,
-			stdout: "pipe",
-			stderr: "ignore",
-			timeout: timeout,
-			killSignal: "SIGKILL",
-		});
-		return untilAborted(abortSignal, async () => {
-			const exitCode = await proc.exited;
-			const stdout = await proc.stdout.text();
-			return exitCode === 0 ? stdout.trim() : null;
-		});
-	};
-
-	// Check if inside a git repo
-	const isGitRepo = await git("rev-parse", "--is-inside-work-tree");
-	if (isGitRepo !== "true") return null;
-	const currentBranch = await git("rev-parse", "--abbrev-ref", "HEAD");
-	if (!currentBranch) return null;
-	let mainBranch = "main";
-	const mainExists = await git("rev-parse", "--verify", "main");
-	if (mainExists === null) {
-		const masterExists = await git("rev-parse", "--verify", "master");
-		if (masterExists !== null) mainBranch = "master";
-	}
-
-	const [status, commits] = await Promise.all([
-		git("status", "--porcelain", "--untracked-files=no"),
-		git("log", "--oneline", "-5"),
-	]);
-	return {
-		isRepo: true,
-		currentBranch,
-		mainBranch,
-		status: status === "" ? "(clean)" : (status ?? "(status unavailable)"),
-		commits: commits && commits.length > 0 ? commits : "(no commits)",
-	};
-}
-
 function firstNonEmpty(...values: (string | undefined | null)[]): string | null {
 	for (const value of values) {
 		const trimmed = value?.trim();
@@ -333,9 +277,7 @@ function getSystemInfoCachePath(): string {
 async function loadGpuCache(): Promise<GpuCache | null> {
 	try {
 		const cachePath = getSystemInfoCachePath();
-		const file = Bun.file(cachePath);
-		if (!(await file.exists())) return null;
-		const content = await file.json();
+		const content = await Bun.file(cachePath).json();
 		return content as GpuCache;
 	} catch {
 		return null;
@@ -501,7 +443,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	const resolvedCwd = cwd ?? getProjectDir();
 	const preloadedSkills = providedPreloadedSkills;
 
-	const prepPromise = (async () => {
+	const prepPromise = (() => {
 		const systemPromptCustomizationPromise = logger.timeAsync("loadSystemPromptFiles", loadSystemPromptFiles, {
 			cwd: resolvedCwd,
 		});
@@ -516,20 +458,10 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 					? loadSkills({ ...skillsSettings, cwd: resolvedCwd }).then(result => result.skills)
 					: Promise.resolve([]);
 		const preloadedSkillContentsPromise = preloadedSkills
-			? await logger.timeAsync("loadPreloadedSkills", loadPreloadedSkillContents, preloadedSkills)
+			? logger.timeAsync("loadPreloadedSkills", loadPreloadedSkillContents, preloadedSkills)
 			: [];
-		const gitPromise = logger.timeAsync("loadGitContext", loadGitContext, resolvedCwd);
 
-		const [
-			resolvedCustomPrompt,
-			resolvedAppendPrompt,
-			systemPromptCustomization,
-			contextFiles,
-			agentsMdSearch,
-			skills,
-			preloadedSkillContents,
-			git,
-		] = await Promise.all([
+		return Promise.all([
 			resolvePromptInput(customPrompt, "system prompt"),
 			resolvePromptInput(appendSystemPrompt, "append system prompt"),
 			systemPromptCustomizationPromise,
@@ -537,19 +469,25 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 			agentsMdSearchPromise,
 			skillsPromise,
 			preloadedSkillContentsPromise,
-			gitPromise,
-		]);
-
-		return {
-			resolvedCustomPrompt,
-			resolvedAppendPrompt,
-			systemPromptCustomization,
-			contextFiles,
-			agentsMdSearch,
-			skills,
-			preloadedSkillContents,
-			git,
-		};
+		]).then(
+			([
+				resolvedCustomPrompt,
+				resolvedAppendPrompt,
+				systemPromptCustomization,
+				contextFiles,
+				agentsMdSearch,
+				skills,
+				preloadedSkillContents,
+			]) => ({
+				resolvedCustomPrompt,
+				resolvedAppendPrompt,
+				systemPromptCustomization,
+				contextFiles,
+				agentsMdSearch,
+				skills,
+				preloadedSkillContents,
+			}),
+		);
 	})();
 
 	const prepResult = await Promise.race([
@@ -571,7 +509,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	};
 	let skills: Skill[] = providedSkills ?? [];
 	let preloadedSkillContents: PreloadedSkill[] = [];
-	let git: GitContext | null = null;
 
 	if (prepResult.type === "timeout") {
 		logger.warn("System prompt preparation timed out; using minimal startup context", {
@@ -595,7 +532,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		agentsMdSearch = prepResult.value.agentsMdSearch;
 		skills = prepResult.value.skills;
 		preloadedSkillContents = prepResult.value.preloadedSkillContents;
-		git = prepResult.value.git;
 	}
 
 	const now = new Date();
@@ -648,7 +584,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 			appendPrompt: resolvedAppendPrompt ?? "",
 			contextFiles,
 			agentsMdSearch,
-			git,
 			skills: filteredSkills,
 			preloadedSkills: preloadedSkillContents,
 			rules: rules ?? [],
@@ -667,7 +602,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		systemPromptCustomization: systemPromptCustomization ?? "",
 		contextFiles,
 		agentsMdSearch,
-		git,
 		skills: filteredSkills,
 		preloadedSkills: preloadedSkillContents,
 		rules: rules ?? [],

package/src/task/executor.ts

@@ -13,6 +13,7 @@ import { ModelRegistry } from "../config/model-registry";
 import { resolveModelOverride } from "../config/model-resolver";
 import { type PromptTemplate, renderPromptTemplate } from "../config/prompt-templates";
 import { Settings } from "../config/settings";
+import { SETTINGS_SCHEMA, type SettingPath } from "../config/settings-schema";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import type { Skill } from "../extensibility/skills";
 import { callTool } from "../mcp/client";
@@ -442,6 +443,14 @@ function createMCPProxyTools(mcpManager: MCPManager): CustomTool<TSchema>[] {
 	});
 }
 
+function createSubagentSettings(baseSettings: Settings): Settings {
+	const snapshot: Partial<Record<SettingPath, unknown>> = {};
+	for (const key of Object.keys(SETTINGS_SCHEMA) as SettingPath[]) {
+		snapshot[key] = baseSettings.get(key);
+	}
+	return Settings.isolated({ ...snapshot, "async.enabled": false });
+}
+
 /**
  * Run a single agent in-process.
  */
@@ -507,6 +516,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	}
 
 	const settings = options.settings ?? Settings.isolated();
+	const subagentSettings = createSubagentSettings(settings);
 	const maxRecursionDepth = settings.get("task.maxRecursionDepth") ?? 2;
 	const parentDepth = options.taskDepth ?? 0;
 	const childDepth = parentDepth + 1;
@@ -932,7 +942,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				cwd: worktree ?? cwd,
 				authStorage,
 				modelRegistry,
-				settings,
+				settings: subagentSettings,
 				model,
 				thinkingLevel: effectiveThinkingLevel,
 				toolNames,

package/src/task/index.ts

@@ -26,13 +26,13 @@ import type { Theme } from "../modes/theme/theme";
 import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.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 { formatDuration } from "../tools/render-utils";
+import { formatBytes, formatDuration } from "../tools/render-utils";
 // Import review tools for side effects (registers subagent tool handlers)
 import "../tools/review";
 import { discoverAgents, getAgent } from "./discovery";
 import { runSubprocess } from "./executor";
 import { AgentOutputManager } from "./output-manager";
-import { mapWithConcurrencyLimit } from "./parallel";
+import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
 import { renderCall, renderResult } from "./render";
 import { renderTemplate } from "./template";
 import {
@@ -55,13 +55,6 @@ import {
 	type WorktreeBaseline,
 } from "./worktree";
 
-/** Format byte count for display */
-function formatBytes(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
-}
-
 function createUsageTotals(): Usage {
 	return {
 		input: 0,
@@ -116,6 +109,7 @@ function renderDescription(
 	agents: AgentDefinition[],
 	maxConcurrency: number,
 	isolationEnabled: boolean,
+	asyncEnabled: boolean,
 	disabledAgents: string[],
 ): string {
 	const filteredAgents = disabledAgents.length > 0 ? agents.filter(a => !disabledAgents.includes(a.name)) : agents;
@@ -123,6 +117,7 @@ function renderDescription(
 		agents: filteredAgents,
 		MAX_CONCURRENCY: maxConcurrency,
 		isolationEnabled,
+		asyncEnabled,
 	});
 }
 
@@ -150,7 +145,13 @@ export class TaskTool implements AgentTool<TaskSchema, TaskToolDetails, Theme> {
 		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
 		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
 		const isolationEnabled = this.session.settings.get("task.isolation.enabled");
-		return renderDescription(this.#discoveredAgents, maxConcurrency, isolationEnabled, disabledAgents);
+		return renderDescription(
+			this.#discoveredAgents,
+			maxConcurrency,
+			isolationEnabled,
+			this.session.settings.get("async.enabled"),
+			disabledAgents,
+		);
 	}
 	private constructor(
 		private readonly session: ToolSession,
@@ -176,6 +177,245 @@ export class TaskTool implements AgentTool<TaskSchema, TaskToolDetails, Theme> {
 		params: TaskParams,
 		signal?: AbortSignal,
 		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
+	): Promise<AgentToolResult<TaskToolDetails>> {
+		const asyncEnabled = this.session.settings.get("async.enabled");
+		if (!asyncEnabled) {
+			return this.#executeSync(_toolCallId, params, signal, onUpdate);
+		}
+
+		const manager = this.session.asyncJobManager;
+		if (!manager) {
+			return {
+				content: [{ type: "text", text: "Async execution is enabled but no async job manager is available." }],
+				details: { projectAgentsDir: null, results: [], totalDurationMs: 0 },
+			};
+		}
+
+		const taskItems = params.tasks ?? [];
+		if (taskItems.length === 0) {
+			return this.#executeSync(_toolCallId, params, signal, onUpdate);
+		}
+
+		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 renderedTasks = taskItems.map(taskItem => renderTemplate(params.context, taskItem));
+		const progressByTaskId = new Map<string, AgentProgress>();
+		for (let index = 0; index < renderedTasks.length; index++) {
+			const renderedTask = renderedTasks[index];
+			progressByTaskId.set(renderedTask.id, {
+				index,
+				id: renderedTask.id,
+				agent: params.agent,
+				agentSource: fallbackAgentSource,
+				status: "pending",
+				task: renderedTask.task,
+				description: renderedTask.description,
+				recentTools: [],
+				recentOutput: [],
+				toolCount: 0,
+				tokens: 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");
+		const semaphore = new Semaphore(maxConcurrency);
+
+		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 = uniqueIds[i];
+			const singleParams: TaskParams = { ...params, tasks: [taskItem] };
+			const label = uniqueId;
+			try {
+				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,
+							]);
+							const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
+							const singleResult = result.details?.results[0];
+							if (progress) {
+								progress.status = singleResult?.aborted
+									? "aborted"
+									: (singleResult?.exitCode ?? 0) === 0
+										? "completed"
+										: "failed";
+								progress.durationMs = singleResult?.durationMs ?? Math.max(0, Date.now() - startedAt);
+								progress.tokens = singleResult?.tokens ?? 0;
+								progress.extractedToolData = singleResult?.extractedToolData;
+							}
+							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.`,
+								);
+							}
+							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,
+						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 });
+			} 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"}.`
+				: "";
+
+		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.`,
+				},
+			],
+			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[],
 	): Promise<AgentToolResult<TaskToolDetails>> {
 		const startTime = Date.now();
 		const { agents, projectAgentsDir } = await discoverAgents(this.session.cwd);
@@ -427,9 +667,14 @@ export class TaskTool implements AgentTool<TaskSchema, TaskToolDetails, Theme> {
 
 			// Build full prompts with context prepended
 			// Allocate unique IDs across the session to prevent artifact collisions
-			const outputManager =
-				this.session.agentOutputManager ?? new AgentOutputManager(this.session.getArtifactsDir ?? (() => null));
-			const uniqueIds = await outputManager.allocateBatch(tasks.map(t => t.id));
+			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: uniqueIds[i] }));
 
 			// Build full prompts with context prepended