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

package/src/sdk.ts

@@ -1244,7 +1244,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		resolveModelRoleValue(settings.getModelRole("default"), allowedModels, {
 			settings,
 			matchPreferences: modelMatchPreferences,
-			modelRegistry,
 		}),
 	);
 	let model = options.model;
@@ -1946,9 +1945,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (!model && options.modelPattern) {
 			const availableModels = modelRegistry.getAll();
 			const matchPreferences = getModelMatchPreferences(settings);
-			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
-				modelRegistry,
-			});
+			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences);
 			if (resolved) {
 				model = resolved;
 				modelFallbackMessage = undefined;
@@ -1978,7 +1975,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const reResolvedRoleSpec = resolveModelRoleValue(settings.getModelRole("default"), fallbackCandidates, {
 					settings,
 					matchPreferences: modelMatchPreferences,
-					modelRegistry,
 				});
 				if (reResolvedRoleSpec.model) {
 					defaultRoleSpec = reResolvedRoleSpec;
@@ -2179,10 +2175,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// `auto` enforces the per-model policy (inline for Gemini, off otherwise);
 		// like the rest of the prune machinery this is fixed for the session, so a
 		// mid-session model switch keeps the start-time decision.
-		const inlineToolDescriptors = shouldInlineToolDescriptors(
-			settings.get("inlineToolDescriptors"),
-			model ? (modelRegistry.getCanonicalId(model) ?? model.id) : undefined,
-		);
+		const inlineToolDescriptors = shouldInlineToolDescriptors(settings.get("inlineToolDescriptors"), model?.id);
 		const eagerTasks = settings.get("task.eager") !== "default";
 		const eagerTasksAlways = settings.get("task.eager") === "always";
 		const intentField = $flag("PI_INTENT_TRACING", settings.get("tools.intentTracing")) ? INTENT_FIELD : undefined;

package/src/session/agent-session.ts

@@ -115,6 +115,7 @@ import {
 import * as AIError from "@oh-my-pi/pi-ai/error";
 import { toolWireSchema } from "@oh-my-pi/pi-ai/utils/schema";
 import { GeminiHeaderRunDetector, isGeminiThinkingModel } from "@oh-my-pi/pi-ai/utils/thinking-loop";
+import { type RepeatedToolCallDetection, ToolCallLoopGuard } from "@oh-my-pi/pi-ai/utils/tool-call-loop-guard";
 import { isFireworksFastModelId, toFireworksBaseModelId } from "@oh-my-pi/pi-catalog/fireworks-model-id";
 import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
@@ -251,6 +252,7 @@ import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool
 };
 import sideChannelNoToolsReminder from "../prompts/system/side-channel-no-tools.md" with { type: "text" };
 import thinkingLoopRedirectTemplate from "../prompts/system/thinking-loop-redirect.md" with { type: "text" };
+import toolCallLoopRedirectTemplate from "../prompts/system/tool-call-loop-redirect.md" with { type: "text" };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
 import ttsrToolReminderTemplate from "../prompts/system/ttsr-tool-reminder.md" with { type: "text" };
 import unexpectedStopRetryTemplate from "../prompts/system/unexpected-stop-retry.md" with { type: "text" };
@@ -285,6 +287,7 @@ import {
 	selectDiscoverableToolNamesByServer,
 } from "../tool-discovery/tool-index";
 import { assertEditableFile } from "../tools/auto-generated-guard";
+import { releaseTabsForOwner } from "../tools/browser/tab-supervisor";
 import { normalizeToolNames } from "../tools/builtin-names";
 import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta, wrapToolWithMetaNotice } from "../tools/output-meta";
@@ -350,6 +353,7 @@ const GEMINI_TOOL_REMINDER_TYPE = "gemini-tool-call-reminder";
 /** `customType` for the hidden redirect notice injected into a turn retried after a
  *  thinking/response loop. Steers the model off the repeated content; never displayed. */
 const THINKING_LOOP_REDIRECT_TYPE = "thinking-loop-redirect";
+const TOOL_CALL_LOOP_REDIRECT_TYPE = "tool-call-loop-redirect";
 
 // A side-channel assistant response is signed for the hidden prompt/history that
 // produced it. If we persist that response under a different user turn, native
@@ -1554,6 +1558,8 @@ export class AgentSession {
 	 *  `#geminiHeaderGuardActive`); undefined for non-Gemini models or when the
 	 *  guard is off. Fed thinking deltas in the assistant-message interceptor. */
 	#geminiHeaderDetector: GeminiHeaderRunDetector | undefined;
+	#toolCallLoopGuard: ToolCallLoopGuard | undefined;
+	#toolCallLoopGuardSettingsKey: string | undefined;
 	#promptInFlightCount = 0;
 	#abortInProgress = false;
 	// Wire-level agent_end emission deferred until #promptInFlightCount drops to 0.
@@ -1848,6 +1854,13 @@ export class AgentSession {
 				this.#pendingRewindReport = undefined;
 				await this.#applyRewind(rewindReport, messages);
 			}
+			if (context?.message.role === "assistant") {
+				const detection = this.#activeToolCallLoopGuard()?.recordTurn({
+					message: context.message,
+					toolResults: context.toolResults,
+				});
+				if (detection) this.#maybeInjectToolCallLoopRedirect(messages, detection);
+			}
 			this.#advisorPrimaryTurnsCompleted++;
 			if (this.#advisors.length > 0) {
 				for (const a of this.#advisors) {
@@ -2095,11 +2108,7 @@ export class AgentSession {
 					continue;
 				}
 			} else {
-				const sel = resolveAdvisorRoleSelection(
-					this.settings,
-					this.#modelRegistry.getAvailable(),
-					this.#modelRegistry,
-				);
+				const sel = resolveAdvisorRoleSelection(this.settings, this.#modelRegistry.getAvailable());
 				if (!sel) {
 					logger.debug("advisor enabled but no model assigned to the 'advisor' role; advisor inactive", {
 						advisor: config.name,
@@ -4299,6 +4308,58 @@ export class AgentSession {
 		this.#streamingEditFileCache.clear();
 	}
 
+	#activeToolCallLoopGuard(): ToolCallLoopGuard | undefined {
+		if (this.settings.get("model.toolCallLoopGuard.enabled") !== true) {
+			this.#toolCallLoopGuard = undefined;
+			this.#toolCallLoopGuardSettingsKey = undefined;
+			return undefined;
+		}
+
+		const threshold = this.settings.get("model.toolCallLoopGuard.threshold");
+		const exemptTools = this.settings
+			.get("model.toolCallLoopGuard.exemptTools")
+			.filter((tool): tool is string => typeof tool === "string" && tool.length > 0);
+		const settingsKey = `${threshold}:${JSON.stringify(exemptTools)}`;
+		if (!this.#toolCallLoopGuard || this.#toolCallLoopGuardSettingsKey !== settingsKey) {
+			this.#toolCallLoopGuard = new ToolCallLoopGuard({ threshold, exemptTools });
+			this.#toolCallLoopGuardSettingsKey = settingsKey;
+		}
+		return this.#toolCallLoopGuard;
+	}
+
+	#maybeInjectToolCallLoopRedirect(messages: AgentMessage[], detection: RepeatedToolCallDetection): void {
+		const content = prompt.render(toolCallLoopRedirectTemplate, {
+			tool_name: detection.toolName,
+			count: detection.count,
+			arguments_summary: detection.argumentsSummary,
+			result_summary: detection.resultSummary || "(no text result)",
+		});
+		const details = {
+			toolName: detection.toolName,
+			count: detection.count,
+			argumentsSummary: detection.argumentsSummary,
+			resultSummary: detection.resultSummary,
+		};
+		logger.warn("cross-turn tool-call loop detected", {
+			toolName: detection.toolName,
+			count: detection.count,
+		});
+		const redirectMessage: CustomMessage = {
+			role: "custom",
+			customType: TOOL_CALL_LOOP_REDIRECT_TYPE,
+			content,
+			display: false,
+			details,
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+		messages.push(redirectMessage);
+		if (this.agent.state.messages !== messages) {
+			this.agent.appendMessage(redirectMessage);
+		}
+		this.sessionManager.appendCustomMessageEntry(TOOL_CALL_LOOP_REDIRECT_TYPE, content, false, details, "agent");
+	}
+
 	/**
 	 * Whether the Gemini header-runaway guard applies to the current model: the loop
 	 * guard is on (settings + `PI_NO_THINKING_LOOP_GUARD`), the tool-call reminder is
@@ -5093,6 +5154,28 @@ export class AgentSession {
 		await disposeKernelSessionsByOwner(this.#evalKernelOwnerId);
 		await disposeRubyKernelSessionsByOwner(this.#evalKernelOwnerId);
 		await disposeJuliaKernelSessionsByOwner(this.#evalKernelOwnerId);
+		// Release headless / spawned Chromium and worker tabs this session
+		// opened via the browser tool. The tool's `tabs`/`browsers` maps are
+		// module-global — subagents and future sessions share them — so we
+		// walk by `ownerSessionId` (assigned at `acquireTab` creation, never on
+		// reuse) and touch only what THIS session created. Bounded so a broken
+		// CDP close cannot stall `/exit`; mirrors the async-job/MCP pattern.
+		// (Issue #3963.)
+		const browserOwnerId = this.sessionManager.getSessionId();
+		if (browserOwnerId) {
+			try {
+				const released = await withTimeout(
+					releaseTabsForOwner(browserOwnerId, { kill: true }),
+					3_000,
+					"Timed out releasing owned browser tabs during dispose",
+				);
+				if (released > 0) {
+					logger.debug("Released owned browser tabs during dispose", { ownerId: browserOwnerId, released });
+				}
+			} catch (error) {
+				logger.warn("Failed to release owned browser tabs during dispose", { error: String(error) });
+			}
+		}
 		await shutdownTinyTitleClient();
 		this.#releasePowerAssertion();
 		// Clean up an empty session created by this session's /move so it doesn't accumulate.
@@ -8158,7 +8241,6 @@ export class AgentSession {
 			const resolved = resolveModelRoleValue(roleModelStr, availableModels, {
 				settings: this.settings,
 				matchPreferences,
-				modelRegistry: this.#modelRegistry,
 			});
 			if (!resolved.model) continue;
 
@@ -8299,7 +8381,7 @@ export class AgentSession {
 		const all = this.#modelRegistry.getAvailable();
 		const patterns = this.settings.get("enabledModels");
 		if (!patterns || patterns.length === 0) return all;
-		return filterAvailableModelsByEnabledPatterns(all, patterns, this.#modelRegistry);
+		return filterAvailableModelsByEnabledPatterns(all, patterns);
 	}
 
 	// =========================================================================
@@ -10713,7 +10795,6 @@ export class AgentSession {
 		return resolveModelRoleValue(roleModelStr, availableModels, {
 			settings: this.settings,
 			matchPreferences: getModelMatchPreferences(this.settings),
-			modelRegistry: this.#modelRegistry,
 		});
 	}
 

package/src/session/session-context.ts

@@ -142,9 +142,10 @@ export function buildSessionContext(
 	const path: SessionEntry[] = [];
 	let current: SessionEntry | undefined = leaf;
 	while (current) {
-		path.unshift(current);
+		path.push(current);
 		current = current.parentId ? byId.get(current.parentId) : undefined;
 	}
+	path.reverse();
 
 	// Extract settings and find compaction
 	let thinkingLevel: string | undefined = "off";

package/src/session/session-manager.ts

@@ -242,9 +242,10 @@ class SessionEntryIndex {
 
 		while (cursor && !seen.has(cursor.id)) {
 			seen.add(cursor.id);
-			branch.unshift(cursor);
+			branch.push(cursor);
 			cursor = cursor.parentId ? this.#entriesById.get(cursor.parentId) : undefined;
 		}
+		branch.reverse();
 
 		return branch;
 	}

package/src/session/unexpected-stop-classifier.ts

@@ -64,7 +64,7 @@ export async function classifyUnexpectedStop(
 }
 
 async function classifyOnline(text: string, deps: ClassifyUnexpectedStopDeps): Promise<boolean | undefined> {
-	const resolved = resolveRoleSelection(["tiny", "smol"], deps.settings, deps.registry.getAvailable(), deps.registry);
+	const resolved = resolveRoleSelection(["tiny", "smol"], deps.settings, deps.registry.getAvailable());
 	const model = resolved?.model;
 	if (!model) {
 		throw new Error("unexpected-stop: no tiny/smol model available for classification");

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) {
@@ -1189,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;

package/src/tools/__tests__/eval-description.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { getEvalToolDescription } from "../eval";
+
+describe("eval tool description", () => {
+	it("advertises the first allowed spawn as the agent() default", () => {
+		const description = getEvalToolDescription({ py: true, js: false, spawns: "fact-finder,oracle" });
+
+		expect(description).toContain('agent(prompt, agent?="fact-finder"');
+		expect(description).toContain("omit it to use `fact-finder`");
+		expect(description).toContain("Allowed agents: `fact-finder`, `oracle`.");
+	});
+
+	it("omits agent() when spawning is disabled", () => {
+		const description = getEvalToolDescription({ py: true, js: false, spawns: "" });
+
+		expect(description).not.toContain("agent(prompt");
+		expect(description).not.toContain("<dag>");
+	});
+});