@oh-my-pi/pi-coding-agent 16.2.9 → 16.2.12

package/src/stt/asr-client.ts

@@ -4,12 +4,12 @@ import {
 	createWorkerHandle,
 	createWorkerSubprocess,
 	logWorkerMessage,
+	type RefCountedWorkerHandle,
 	resolveWorkerSpawnCmd,
 	SMOKE_TEST_TIMEOUT_MS,
 	type SpawnedSubprocess,
 	smokeTestWorker,
 	spawnWorkerOrUnavailable,
-	type WorkerHandle,
 } from "../subprocess/worker-client";
 import { tinyWorkerEnv } from "../tiny/title-client";
 import { safeSend } from "../utils/ipc";
@@ -18,7 +18,7 @@ import type { SttModelKey } from "./models";
 
 type PendingRequest =
 	| { kind: "transcribe"; modelKey: SttModelKey; resolve: (text: string) => void; reject: (error: Error) => void }
-	| { kind: "download"; modelKey: SttModelKey; resolve: (ok: boolean) => void };
+	| { kind: "download"; modelKey: SttModelKey; resolve: (result: SttDownloadResult) => void };
 
 export interface SttTranscribeOptions {
 	language?: string;
@@ -30,6 +30,11 @@ export interface SttDownloadOptions {
 	onProgress?: (event: SttProgressEvent) => void;
 }
 
+export interface SttDownloadResult {
+	ok: boolean;
+	error?: string;
+}
+
 /** Live streaming session handle returned by {@link SttClient.startStream}. */
 export interface SttStreamHandle {
 	/** Feed 16 kHz mono float samples as the recorder produces them. */
@@ -79,30 +84,55 @@ export function createSttSubprocess(): SpawnedSubprocess<SttWorkerOutbound> {
 
 function wrapSubprocess(
 	spawned: SpawnedSubprocess<SttWorkerOutbound>,
-): WorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
+): RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
 	const { proc } = spawned;
-	return createWorkerHandle<SttWorkerInbound, SttWorkerOutbound>(spawned, message => safeSend(proc, message, "stt"));
+	return {
+		...createWorkerHandle<SttWorkerInbound, SttWorkerOutbound>(spawned, message => safeSend(proc, message, "stt")),
+		ref() {
+			try {
+				proc.ref();
+			} catch {
+				// Already gone.
+			}
+		},
+		unref() {
+			try {
+				proc.unref();
+			} catch {
+				// Already gone.
+			}
+		},
+	};
+}
+
+function spawnInlineUnavailableWorker(error: unknown): RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
+	return {
+		...createUnavailableWorker<SttWorkerInbound, SttWorkerOutbound>(error),
+		ref() {},
+		unref() {},
+	};
 }
 
-function spawnSttWorker(): WorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
+function spawnSttWorker(): RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
 	return spawnWorkerOrUnavailable(
 		() => wrapSubprocess(createSttSubprocess()),
-		createUnavailableWorker<SttWorkerInbound, SttWorkerOutbound>,
+		spawnInlineUnavailableWorker,
 		"stt worker spawn failed; speech-to-text disabled",
 	);
 }
 
 export class SttClient {
-	#worker: WorkerHandle<SttWorkerInbound, SttWorkerOutbound> | null = null;
+	#worker: RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> | null = null;
 	#unsubscribeMessage: (() => void) | null = null;
 	#unsubscribeError: (() => void) | null = null;
 	#pending = new Map<string, PendingRequest>();
 	#streams = new Map<string, StreamState>();
 	#progressListeners = new Set<(event: SttProgressEvent) => void>();
 	#nextRequestId = 0;
-	#spawnWorker: () => WorkerHandle<SttWorkerInbound, SttWorkerOutbound>;
+	#refed = false;
+	#spawnWorker: () => RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound>;
 
-	constructor(spawnWorker: () => WorkerHandle<SttWorkerInbound, SttWorkerOutbound> = spawnSttWorker) {
+	constructor(spawnWorker: () => RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> = spawnSttWorker) {
 		this.#spawnWorker = spawnWorker;
 	}
 
@@ -121,11 +151,11 @@ export class SttClient {
 		const worker = this.#ensureWorker();
 		const id = String(++this.#nextRequestId);
 		const { promise, resolve, reject } = Promise.withResolvers<string>();
-		this.#pending.set(id, { kind: "transcribe", modelKey, resolve, reject });
+		this.#addPending(id, { kind: "transcribe", modelKey, resolve, reject });
 		const abort = (): void => {
 			const pending = this.#pending.get(id);
 			if (pending?.kind !== "transcribe") return;
-			this.#pending.delete(id);
+			this.#deletePending(id);
 			pending.reject(new DOMException("The operation was aborted.", "AbortError"));
 		};
 		options.signal?.addEventListener("abort", abort, { once: true });
@@ -134,7 +164,7 @@ export class SttClient {
 			return await promise;
 		} finally {
 			options.signal?.removeEventListener("abort", abort);
-			this.#pending.delete(id);
+			this.#deletePending(id);
 		}
 	}
 
@@ -163,6 +193,7 @@ export class SttClient {
 			settled = true;
 			this.#streams.delete(id);
 			signal?.removeEventListener("abort", onAbort);
+			this.#syncWorkerRef();
 			apply();
 		};
 		this.#streams.set(id, {
@@ -173,6 +204,7 @@ export class SttClient {
 			reject,
 			finish,
 		});
+		this.#syncWorkerRef();
 		worker.send({ type: "stream_start", id, modelKey, language: options.language });
 		const handle: SttStreamHandle = {
 			pushAudio: audio => {
@@ -193,19 +225,19 @@ export class SttClient {
 		return handle;
 	}
 
-	async downloadModel(modelKey: SttModelKey, options: SttDownloadOptions = {}): Promise<boolean> {
-		if (options.signal?.aborted) return false;
+	async downloadModel(modelKey: SttModelKey, options: SttDownloadOptions = {}): Promise<SttDownloadResult> {
+		if (options.signal?.aborted) return { ok: false };
 		const unsubscribe = options.onProgress ? this.onProgress(options.onProgress) : undefined;
 		try {
 			const worker = this.#ensureWorker();
 			const id = String(++this.#nextRequestId);
-			const { promise, resolve } = Promise.withResolvers<boolean>();
-			this.#pending.set(id, { kind: "download", modelKey, resolve });
+			const { promise, resolve } = Promise.withResolvers<SttDownloadResult>();
+			this.#addPending(id, { kind: "download", modelKey, resolve });
 			const abort = (): void => {
 				const pending = this.#pending.get(id);
 				if (pending?.kind !== "download") return;
-				this.#pending.delete(id);
-				pending.resolve(false);
+				this.#deletePending(id);
+				pending.resolve({ ok: false });
 			};
 			options.signal?.addEventListener("abort", abort, { once: true });
 			try {
@@ -213,14 +245,15 @@ export class SttClient {
 				return await promise;
 			} finally {
 				options.signal?.removeEventListener("abort", abort);
-				this.#pending.delete(id);
+				this.#deletePending(id);
 			}
 		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
 			logger.debug("stt: local model download failed", {
 				modelKey,
-				error: error instanceof Error ? error.message : String(error),
+				error: message,
 			});
-			return false;
+			return { ok: false, error: message };
 		} finally {
 			unsubscribe?.();
 		}
@@ -236,9 +269,10 @@ export class SttClient {
 		for (const pending of this.#pending.values()) {
 			this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
 			if (pending.kind === "transcribe") pending.reject(new Error("stt worker terminated"));
-			else pending.resolve(false);
+			else pending.resolve({ ok: false });
 		}
 		this.#pending.clear();
+		this.#refed = false;
 		this.#failStreams(new Error("stt worker terminated"));
 		try {
 			await worker?.terminate();
@@ -247,7 +281,7 @@ export class SttClient {
 		}
 	}
 
-	#ensureWorker(): WorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
+	#ensureWorker(): RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound> {
 		if (this.#worker) return this.#worker;
 		const worker = this.#spawnWorker();
 		this.#worker = worker;
@@ -256,6 +290,32 @@ export class SttClient {
 		return worker;
 	}
 
+	/** Register a pending request and keep the worker referenced while work is in flight. */
+	#addPending(id: string, request: PendingRequest): void {
+		this.#pending.set(id, request);
+		this.#syncWorkerRef();
+	}
+
+	/** Drop a pending request and unref the worker once no request or stream is active. */
+	#deletePending(id: string): void {
+		if (this.#pending.delete(id)) this.#syncWorkerRef();
+	}
+
+	/**
+	 * STT workers start unreferenced so an idle warm model never blocks exit.
+	 * Setup/download commands must keep the worker alive while awaiting IPC, or
+	 * Bun can drain the event loop immediately after `Preparing Speech-to-Text`.
+	 */
+	#syncWorkerRef(): void {
+		const worker = this.#worker;
+		if (!worker) return;
+		const shouldRef = this.#pending.size > 0 || this.#streams.size > 0;
+		if (shouldRef === this.#refed) return;
+		this.#refed = shouldRef;
+		if (shouldRef) worker.ref();
+		else worker.unref();
+	}
+
 	#handleMessage(message: SttWorkerOutbound): void {
 		if (message.type === "log") {
 			logWorkerMessage(message);
@@ -287,19 +347,19 @@ export class SttClient {
 			}
 			return;
 		}
-		this.#pending.delete(message.id);
+		this.#deletePending(message.id);
 		if (message.type === "transcription") {
 			if (pending.kind === "transcribe") pending.resolve(message.text);
 			return;
 		}
 		if (message.type === "downloaded") {
-			if (pending.kind === "download") pending.resolve(true);
+			if (pending.kind === "download") pending.resolve({ ok: true });
 			return;
 		}
 		// message.type === "error"
 		this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
 		if (pending.kind === "transcribe") pending.reject(new Error(message.error));
-		else pending.resolve(false);
+		else pending.resolve({ ok: false, error: message.error });
 	}
 
 	#emitProgress(event: SttProgressEvent): void {
@@ -318,7 +378,7 @@ export class SttClient {
 		for (const pending of this.#pending.values()) {
 			this.#emitProgress({ modelKey: pending.modelKey, status: "error" });
 			if (pending.kind === "transcribe") pending.reject(error);
-			else pending.resolve(false);
+			else pending.resolve({ ok: false, error: error.message });
 		}
 		this.#pending.clear();
 		this.#failStreams(error);

package/src/stt/downloader.ts

@@ -90,7 +90,7 @@ export async function downloadSttModel(
 ): Promise<void> {
 	const spec = resolveSttModelSpec(key);
 	const files = new Map<string, { loaded: number; total: number }>();
-	const ok = await sttClient.downloadModel(spec.key, {
+	const result = await sttClient.downloadModel(spec.key, {
 		signal: options?.signal,
 		onProgress: event => {
 			if ((event.status === "progress" || event.status === "progress_total") && event.file) {
@@ -117,7 +117,13 @@ export async function downloadSttModel(
 			});
 		},
 	});
-	if (!ok) throw new Error(`Failed to download speech model (${spec.repo}). Check your network connection.`);
+	if (!result.ok) {
+		const detail = result.error ? `: ${result.error}` : ". Check your network connection.";
+		throw new Error(`Failed to download speech model (${spec.repo})${detail}`);
+	}
+	if (!(await isSttModelCached(spec.key))) {
+		throw new Error(`Speech model download finished without required files (${spec.repo}).`);
+	}
 }
 
 // ── Public API ─────────────────────────────────────────────────────

package/src/task/executor.ts

@@ -2053,9 +2053,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					? formatModelSelectorValue(formatModelStringWithRouting(model), resolvedThinkingLevel)
 					: formatModelStringWithRouting(model);
 			}
-			const effectiveThinkingLevel = explicitThinkingLevel
-				? resolvedThinkingLevel
-				: (thinkingLevel ?? resolvedThinkingLevel);
+			const effectiveThinkingLevel = thinkingLevel ?? resolvedThinkingLevel;
 			resolvedAt = performance.now();
 
 			const effectiveCwd = worktree ?? cwd;

package/src/task/index.ts

@@ -30,6 +30,7 @@ import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type:
 import { truncateForPrompt } from "../tools/approval";
 import { isIrcEnabled } from "../tools/irc";
 import { formatBytes, formatDuration } from "../tools/render-utils";
+import { DEFAULT_SPAWN_AGENT, resolveSpawnPolicy } from "./spawn-policy";
 import {
 	type AgentDefinition,
 	type AgentProgress,
@@ -187,17 +188,13 @@ function renderDescription(
 	ircEnabled: boolean,
 	parentSpawns: string,
 ): string {
-	const spawningDisabled = parentSpawns === "";
+	const spawnPolicy = resolveSpawnPolicy(parentSpawns);
+	const spawningDisabled = !spawnPolicy.enabled;
 	let filteredAgents = disabledAgents.length > 0 ? agents.filter(a => !disabledAgents.includes(a.name)) : agents;
 	if (spawningDisabled) {
 		filteredAgents = [];
-	} else if (parentSpawns !== "*") {
-		const allowed = new Set(
-			parentSpawns
-				.split(",")
-				.map(s => s.trim())
-				.filter(Boolean),
-		);
+	} else if (spawnPolicy.allowedAgents !== null) {
+		const allowed = new Set(spawnPolicy.allowedAgents);
 		filteredAgents = filteredAgents.filter(a => allowed.has(a.name));
 	}
 	const renderedAgents = filteredAgents.map(agent => ({
@@ -208,6 +205,9 @@ function renderDescription(
 	return prompt.render(taskDescriptionTemplate, {
 		agents: renderedAgents,
 		spawningDisabled,
+		defaultAgent: spawnPolicy.defaultAgent,
+		defaultAgentIsGeneric: spawnPolicy.defaultAgent === DEFAULT_SPAWN_AGENT,
+		allowedAgentsText: spawnPolicy.allowedPromptText,
 		MAX_CONCURRENCY: maxConcurrency,
 		isolationEnabled,
 		batchEnabled,
@@ -331,9 +331,6 @@ function spawnParamsFor(params: TaskParams, item: TaskItem): TaskParams {
 	return spawn;
 }
 
-/** Agent type spawned when a `task` call omits `agent`; mirrors the schema default in `getTaskSchema`. */
-const DEFAULT_TASK_AGENT = "task";
-
 /** Generic worker agents whose output sharpens with a tailored `role` rather than the bare type. */
 const GENERIC_SPAWN_AGENTS: ReadonlySet<string> = new Set(["task", "sonic"]);
 
@@ -511,7 +508,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 
 	get parameters(): TaskToolSchemaInstance {
 		const isolationEnabled = this.session.settings.get("task.isolation.mode") !== "none";
-		return getTaskSchema({ isolationEnabled, batchEnabled: this.#isBatchEnabled() });
+		const defaultAgent = resolveSpawnPolicy(this.session.getSessionSpawns()).defaultAgent;
+		return getTaskSchema({ isolationEnabled, batchEnabled: this.#isBatchEnabled(), defaultAgent });
 	}
 
 	renderCall(args: unknown, options: Parameters<typeof renderTaskCall>[1], theme: Theme) {
@@ -566,13 +564,14 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
 	): Promise<AgentToolResult<TaskToolDetails>> {
 		const repaired = repairTaskParams(rawParams as TaskParams);
-		// The schema defaults `agent` to `task` for model calls, but internal
-		// callers and stale transcripts build params directly and bypass arktype.
-		// Normalize once here so every downstream path sees the resolved agent.
+		// Schema defaults run for model calls, but internal callers and stale
+		// transcripts can bypass arktype. Normalize once so every downstream path
+		// sees the session's actual default agent.
+		const defaultAgent = resolveSpawnPolicy(this.session.getSessionSpawns()).defaultAgent;
 		const params =
 			typeof repaired.agent === "string" && repaired.agent.trim() !== ""
 				? repaired
-				: { ...repaired, agent: DEFAULT_TASK_AGENT };
+				: { ...repaired, agent: defaultAgent };
 		const batchEnabled = this.#isBatchEnabled();
 		const validationError = validateShapeParams(batchEnabled, params) ?? validateSpawnParams(params, batchEnabled);
 		if (validationError) {
@@ -803,10 +802,19 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			async ({ jobId: ownJobId, signal: runSignal, reportProgress, markRunning }) => {
 				const startedAt = Date.now();
 				const semaphore = this.#getSpawnSemaphore();
-				await semaphore.acquire();
+				let semaphoreHeld = false;
+				try {
+					await semaphore.acquire(runSignal);
+					semaphoreHeld = true;
+				} catch {
+					// Fall through so an acquire-time abort goes through the same
+					// path as the post-acquire race below: progress + onSettled
+					// have to fire even when the spawn never reached the executor,
+					// otherwise the batch aggregate state stays "running" forever.
+				}
 				const acquiredAt = Date.now();
-				if (runSignal.aborted) {
-					semaphore.release();
+				if (!semaphoreHeld || runSignal.aborted) {
+					if (semaphoreHeld) semaphore.release();
 					progress.status = "aborted";
 					onSettled?.(true);
 					throw new Error("Aborted before execution");
@@ -909,7 +917,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const semaphore = this.#getSpawnSemaphore();
 		if (spawnItems.length === 1) {
 			const invokedAt = Date.now();
-			await semaphore.acquire();
+			await semaphore.acquire(signal);
 			const acquiredAt = Date.now();
 			try {
 				return await this.#executeSync(
@@ -948,7 +956,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			spawnItems.length,
 			async (item, index, workerSignal) => {
 				const invokedAt = Date.now();
-				await semaphore.acquire();
+				await semaphore.acquire(workerSignal);
 				const acquiredAt = Date.now();
 				try {
 					const itemOnUpdate: AgentToolUpdateCallback<TaskToolDetails> | undefined = onUpdate
@@ -1180,18 +1188,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			}
 
 			// 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)" : parentSpawns;
+			const spawnPolicy = resolveSpawnPolicy(this.session.getSessionSpawns());
+			const spawnAllowed =
+				spawnPolicy.enabled &&
+				(spawnPolicy.allowedAgents === null || spawnPolicy.allowedAgents.includes(agentName));
+			if (!spawnAllowed) {
 				return {
-					content: [{ type: "text", text: `Cannot spawn '${agentName}'. Allowed: ${allowed}` }],
+					content: [
+						{ type: "text", text: `Cannot spawn '${agentName}'. Allowed: ${spawnPolicy.allowedErrorText}` },
+					],
 					details: { projectAgentsDir, results: [], totalDurationMs: Date.now() - startTime },
 				};
 			}

package/src/task/spawn-policy.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it, vi } from "bun:test";
+import { Settings } from "../config/settings";
+import type { ToolSession } from "../tools";
+import * as taskDiscovery from "./discovery";
+import { TaskTool } from "./index";
+import type { AgentDefinition } from "./types";
+import { getTaskSchema } from "./types";
+
+const factFinderAgent = {
+	name: "fact-finder",
+	description: "Find facts.",
+	systemPrompt: "Find facts.",
+	source: "project",
+} satisfies AgentDefinition;
+
+const oracleAgent = {
+	name: "oracle",
+	description: "Answer hard questions.",
+	systemPrompt: "Answer hard questions.",
+	source: "bundled",
+} satisfies AgentDefinition;
+
+function makeSession(spawns: string): ToolSession {
+	const settings = Settings.isolated({
+		"async.enabled": false,
+		"task.batch": true,
+		"task.isolation.mode": "none",
+	});
+	return {
+		cwd: process.cwd(),
+		hasUI: false,
+		settings,
+		getSessionFile: () => null,
+		getSessionSpawns: () => spawns,
+	};
+}
+
+describe("task spawn policy surfaces", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("uses the first allowed spawn as the schema default", () => {
+		const schema = getTaskSchema({ isolationEnabled: false, batchEnabled: false, defaultAgent: "fact-finder" });
+		const parsed = schema({ assignment: "check" });
+
+		expect(parsed).toEqual({ agent: "fact-finder", assignment: "check" });
+	});
+
+	it("renders the restricted spawn default in the task description", async () => {
+		vi.spyOn(taskDiscovery, "discoverAgents").mockResolvedValue({
+			agents: [factFinderAgent, oracleAgent],
+			projectAgentsDir: null,
+		});
+
+		const tool = await TaskTool.create(makeSession("fact-finder,oracle"));
+		const description = tool.description;
+
+		expect(description).toContain("Defaults to `fact-finder`");
+		expect(description).toContain("Current spawn policy allows: `fact-finder`, `oracle`.");
+		expect(description).not.toContain("Defaults to `task`");
+	});
+});

package/src/task/spawn-policy.ts

@@ -0,0 +1,58 @@
+/** Default agent used when a session has unrestricted spawning. */
+export const DEFAULT_SPAWN_AGENT = "task";
+
+/** Spawn policy derived from a parent agent's `spawns` frontmatter. */
+export interface ResolvedSpawnPolicy {
+	/** True when at least one subagent may be spawned. */
+	enabled: boolean;
+	/** Agent used when the caller omits the agent field. */
+	defaultAgent: string;
+	/** Explicitly allowed agents, or `null` when the policy is unrestricted. */
+	allowedAgents: readonly string[] | null;
+	/** Text used in spawn rejection messages. */
+	allowedErrorText: string;
+	/** Backtick-quoted explicit agents for prompt descriptions. */
+	allowedPromptText?: string;
+}
+
+/** Resolves spawn frontmatter into the default and prompt/error surfaces. */
+export function resolveSpawnPolicy(parentSpawns: string | boolean | null | undefined): ResolvedSpawnPolicy {
+	let normalized: string;
+	if (parentSpawns === false) {
+		normalized = "";
+	} else if (parentSpawns === true || parentSpawns === null || parentSpawns === undefined) {
+		normalized = "*";
+	} else {
+		normalized = parentSpawns.trim();
+	}
+
+	if (normalized === "*") {
+		return {
+			enabled: true,
+			defaultAgent: DEFAULT_SPAWN_AGENT,
+			allowedAgents: null,
+			allowedErrorText: "*",
+		};
+	}
+
+	const allowedAgents = normalized
+		.split(",")
+		.map(spawn => spawn.trim())
+		.filter(Boolean);
+	if (allowedAgents.length === 0) {
+		return {
+			enabled: false,
+			defaultAgent: DEFAULT_SPAWN_AGENT,
+			allowedAgents,
+			allowedErrorText: "none (spawns disabled for this agent)",
+		};
+	}
+
+	return {
+		enabled: true,
+		defaultAgent: allowedAgents[0] ?? DEFAULT_SPAWN_AGENT,
+		allowedAgents,
+		allowedErrorText: allowedAgents.join(","),
+		allowedPromptText: allowedAgents.map(agent => `\`${agent}\``).join(", "),
+	};
+}

package/src/task/types.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Usage } from "@oh-my-pi/pi-ai";
 import { $env } from "@oh-my-pi/pi-utils";
-import { type } from "arktype";
+import { type BaseType, type } from "arktype";
 import type { AgentSessionEvent } from "../session/agent-session";
 import type { NestedRepoPatch } from "./worktree";
 
@@ -144,13 +144,84 @@ const ALL_TASK_SCHEMAS = [taskSchema, taskSchemaNoIsolation, taskSchemaBatch, ta
 type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
 export type TaskSchema = typeof taskSchema;
 /** Active task tool parameter schema for the current isolation / batch flags */
-export type TaskToolSchemaInstance = DynamicTaskSchema;
+export type TaskToolSchemaInstance = DynamicTaskSchema | BaseType;
 
-export function getTaskSchema(options: { isolationEnabled: boolean; batchEnabled: boolean }): DynamicTaskSchema {
+const TASK_AGENT_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const taskSchemaCache = new Map<string, BaseType>();
+
+function taskAgentSchemaRule(defaultAgent: string): string {
+	const trimmed = defaultAgent.trim();
+	if (TASK_AGENT_NAME_PATTERN.test(trimmed)) {
+		return `string = '${trimmed}'`;
+	}
+	return "string";
+}
+
+function createTaskSchema(options: {
+	isolationEnabled: boolean;
+	batchEnabled: boolean;
+	defaultAgent: string;
+}): BaseType {
+	const agent = taskAgentSchemaRule(options.defaultAgent);
 	if (options.batchEnabled) {
-		return options.isolationEnabled ? taskSchemaBatch : taskSchemaBatchNoIsolation;
+		if (options.isolationEnabled) {
+			return type.raw({
+				agent,
+				context: "string",
+				tasks: taskItemSchemaIsolated.array(),
+				"+": "delete",
+			});
+		}
+		return type.raw({
+			agent,
+			context: "string",
+			tasks: taskItemSchema.array(),
+			"+": "delete",
+		});
+	}
+	if (options.isolationEnabled) {
+		return type.raw({
+			agent,
+			"id?": "string",
+			"description?": "string",
+			"role?": ROLE_INPUT_SCHEMA,
+			assignment: "string",
+			"isolated?": "boolean",
+			"+": "delete",
+		});
+	}
+	return type.raw({
+		agent,
+		"id?": "string",
+		"description?": "string",
+		"role?": ROLE_INPUT_SCHEMA,
+		assignment: "string",
+		"+": "delete",
+	});
+}
+
+export function getTaskSchema(options: { isolationEnabled: boolean; batchEnabled: boolean }): DynamicTaskSchema;
+export function getTaskSchema(options: {
+	isolationEnabled: boolean;
+	batchEnabled: boolean;
+	defaultAgent: string;
+}): TaskToolSchemaInstance;
+export function getTaskSchema(options: {
+	isolationEnabled: boolean;
+	batchEnabled: boolean;
+	defaultAgent?: string;
+}): TaskToolSchemaInstance {
+	const defaultAgent = options.defaultAgent ?? "task";
+	if (defaultAgent === "task") {
+		if (options.batchEnabled) return options.isolationEnabled ? taskSchemaBatch : taskSchemaBatchNoIsolation;
+		return options.isolationEnabled ? taskSchema : taskSchemaNoIsolation;
 	}
-	return options.isolationEnabled ? taskSchema : taskSchemaNoIsolation;
+	const key = `${options.isolationEnabled ? "iso" : "flat"}:${options.batchEnabled ? "batch" : "single"}:${defaultAgent}`;
+	const cached = taskSchemaCache.get(key);
+	if (cached) return cached;
+	const schema = createTaskSchema({ ...options, defaultAgent });
+	taskSchemaCache.set(key, schema);
+	return schema;
 }
 
 /**
@@ -160,7 +231,7 @@ export function getTaskSchema(options: { isolationEnabled: boolean; batchEnabled
  * transcripts using the flat form keep working under either setting.
  */
 export interface TaskParams {
-	/** Agent type to spawn; defaults to `"task"` (the general-purpose worker) when omitted. */
+	/** Agent type to spawn; omitted values resolve from the session spawn policy. */
 	agent?: string;
 	/** Stable agent id (flat form); default = generated AdjectiveNoun. */
 	id?: string;