@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/src/stt/transcriber.ts

@@ -1,5 +1,7 @@
-import { $which, logger } from "@oh-my-pi/pi-utils";
-import transcribeScript from "./transcribe.py" with { type: "text" };
+import { logger } from "@oh-my-pi/pi-utils";
+import { sttClient } from "./asr-client";
+import { resolveSttModelSpec } from "./models";
+import { decodeWavToMono16k } from "./wav";
 
 export interface TranscribeOptions {
 	modelName?: string;
@@ -10,82 +12,49 @@ export interface TranscribeOptions {
 const TRANSCRIBE_TIMEOUT_MS = 120_000;
 
 /**
- * Find a usable Python command.
- */
-export function resolvePython(): string | null {
-	for (const cmd of ["python", "py", "python3"]) {
-		if ($which(cmd)) return cmd;
-	}
-	return null;
-}
-
-/**
- * Transcribe a WAV file using Python openai-whisper.
+ * Transcribe a WAV file using the local ONNX Whisper worker.
  *
- * Reads the WAV via Python's built-in `wave` module (no ffmpeg needed),
- * resamples to 16 kHz mono, and passes the numpy array directly to whisper.
+ * Decodes the WAV to a 16 kHz mono Float32Array in-process (no Python, no
+ * ffmpeg) and routes it to the warm speech worker, which keeps the model loaded
+ * across calls. Honors `options.signal` (abort) and applies an internal timeout
+ * with the same semantics as the previous Python path.
  */
 export async function transcribe(audioPath: string, options?: TranscribeOptions): Promise<string> {
 	const audioFile = Bun.file(audioPath);
 	if (audioFile.size < 100) {
 		throw new Error(`Audio file is empty or too small (${audioFile.size} bytes). Check microphone.`);
 	}
-
-	const pythonCmd = resolvePython();
-	if (!pythonCmd) {
-		throw new Error("Python not found. Install Python 3.8+ from https://python.org");
-	}
-
-	const modelName = options?.modelName ?? "base.en";
-	const language = options?.language ?? "en";
-
-	logger.debug("Transcribing with Python whisper", { pythonCmd, audioPath, modelName, language });
-
-	const proc = Bun.spawn([pythonCmd, "-c", transcribeScript, audioPath, modelName, language], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-
-	if (options?.signal?.aborted) {
-		proc.kill();
-		options.signal.throwIfAborted();
-	}
-
-	const onAbort = () => proc.kill();
-	options?.signal?.addEventListener("abort", onAbort, { once: true });
-
-	let timedOut = false;
-
-	const killTimer = setTimeout(() => {
-		timedOut = true;
-		logger.error("Python whisper transcription timed out, killing process", { timeoutMs: TRANSCRIBE_TIMEOUT_MS });
-		proc.kill();
-	}, TRANSCRIBE_TIMEOUT_MS);
-
-	const exitCode = await proc.exited;
-	clearTimeout(killTimer);
-	options?.signal?.removeEventListener("abort", onAbort);
-
 	options?.signal?.throwIfAborted();
 
-	const stdout = await new Response(proc.stdout).text();
-	const stderr = await new Response(proc.stderr).text();
-
-	if (timedOut) {
-		throw new Error(`Transcription timed out after ${Math.round(TRANSCRIBE_TIMEOUT_MS / 1000)}s`);
-	}
+	const spec = resolveSttModelSpec(options?.modelName);
+	const language = options?.language || undefined;
+	const audio = decodeWavToMono16k(await audioFile.arrayBuffer());
+	if (audio.length === 0) return "";
+
+	logger.debug("Transcribing with local ONNX whisper", {
+		audioPath,
+		modelKey: spec.key,
+		repo: spec.repo,
+		language,
+		samples: audio.length,
+	});
 
-	if (exitCode !== 0) {
-		logger.error("Python whisper transcription failed", { exitCode, stderr: stderr.trim() });
-		if (stderr.includes("No module named 'whisper'")) {
-			throw new Error("openai-whisper not installed. Run: pip install openai-whisper");
+	// Bound runaway inference. Abort the request on timeout; the warm worker
+	// keeps the model loaded (the request promise just rejects).
+	const timeout = new AbortController();
+	const timer = setTimeout(() => timeout.abort(), TRANSCRIBE_TIMEOUT_MS);
+	const signal = options?.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
+	try {
+		const text = (await sttClient.transcribe(spec.key, audio, { language, signal })).trim();
+		logger.debug("Transcription complete", { length: text.length });
+		return text;
+	} catch (error) {
+		if (timeout.signal.aborted && !options?.signal?.aborted) {
+			logger.error("Local whisper transcription timed out", { timeoutMs: TRANSCRIBE_TIMEOUT_MS });
+			throw new Error(`Transcription timed out after ${Math.round(TRANSCRIBE_TIMEOUT_MS / 1000)}s`);
 		}
-		// Show last line of stderr (the actual error, not the full traceback)
-		const lastLine = stderr.trim().split("\n").pop() ?? "";
-		throw new Error(`Transcription failed: ${lastLine}`);
+		throw error;
+	} finally {
+		clearTimeout(timer);
 	}
-
-	const text = stdout.trim();
-	logger.debug("Transcription complete", { length: text.length });
-	return text;
 }

package/src/stt/wav.ts

@@ -0,0 +1,173 @@
+/**
+ * Minimal WAV (RIFF/PCM) decoder producing the Float32Array @ 16 kHz mono that
+ * transformers.js `automatic-speech-recognition` expects. Ports the decode/
+ * mono-mix/resample logic from the retired Python `transcribe.py` (which read
+ * via the stdlib `wave` module) so STT no longer shells out to Python.
+ *
+ * Supported sample formats: PCM uint8 (8-bit), int16 (16-bit), int32 (32-bit),
+ * and IEEE float32 (format tag 3). Any number of channels is mixed down to mono.
+ */
+
+/** transformers.js Whisper feature extractor operates at 16 kHz. */
+export const TARGET_SAMPLE_RATE = 16_000;
+
+const WAV_FORMAT_PCM = 1;
+const WAV_FORMAT_IEEE_FLOAT = 3;
+const WAV_FORMAT_EXTENSIBLE = 0xfffe;
+
+interface WavData {
+	format: number;
+	channels: number;
+	sampleRate: number;
+	bitsPerSample: number;
+	/** Raw PCM/float bytes from the `data` chunk. */
+	samples: DataView;
+}
+
+function readFourCc(view: DataView, offset: number): string {
+	return String.fromCharCode(
+		view.getUint8(offset),
+		view.getUint8(offset + 1),
+		view.getUint8(offset + 2),
+		view.getUint8(offset + 3),
+	);
+}
+
+/** Parse the RIFF container, returning the `fmt ` parameters and `data` bytes. */
+function parseWav(buffer: ArrayBuffer): WavData {
+	const view = new DataView(buffer);
+	if (buffer.byteLength < 12 || readFourCc(view, 0) !== "RIFF" || readFourCc(view, 8) !== "WAVE") {
+		throw new Error("Not a RIFF/WAVE file");
+	}
+
+	let format: number | undefined;
+	let channels = 0;
+	let sampleRate = 0;
+	let bitsPerSample = 0;
+	let samples: DataView | undefined;
+
+	// Chunks begin after the 12-byte RIFF/WAVE header; each is an 8-byte header
+	// (4-char id + uint32 LE size) followed by `size` bytes padded to even.
+	let offset = 12;
+	while (offset + 8 <= buffer.byteLength) {
+		const id = readFourCc(view, offset);
+		const size = view.getUint32(offset + 4, true);
+		const body = offset + 8;
+		if (id === "fmt ") {
+			format = view.getUint16(body, true);
+			channels = view.getUint16(body + 2, true);
+			sampleRate = view.getUint32(body + 4, true);
+			bitsPerSample = view.getUint16(body + 14, true);
+			// WAVE_FORMAT_EXTENSIBLE (ffmpeg & friends): the real codec is the
+			// first 2 bytes of the SubFormat GUID in the fmt extension.
+			if (format === WAV_FORMAT_EXTENSIBLE && size >= 40) format = view.getUint16(body + 24, true);
+		} else if (id === "data") {
+			const length = Math.min(size, buffer.byteLength - body);
+			samples = new DataView(buffer, body, length);
+		}
+		offset = body + size + (size % 2);
+	}
+
+	if (format === undefined || samples === undefined || channels < 1 || sampleRate < 1) {
+		throw new Error("WAV file missing fmt/data chunks");
+	}
+	return { format, channels, sampleRate, bitsPerSample, samples };
+}
+
+/** Decode raw PCM/float bytes into interleaved normalized [-1, 1] float samples. */
+function decodeSamples(wav: WavData): Float32Array {
+	const { format, bitsPerSample, samples } = wav;
+	const view = samples;
+	if (format === WAV_FORMAT_IEEE_FLOAT && bitsPerSample === 32) {
+		const count = Math.floor(view.byteLength / 4);
+		const out = new Float32Array(count);
+		for (let i = 0; i < count; i += 1) out[i] = view.getFloat32(i * 4, true);
+		return out;
+	}
+	if (format !== WAV_FORMAT_PCM) {
+		throw new Error(`Unsupported WAV format tag: ${format}`);
+	}
+	if (bitsPerSample === 16) {
+		const count = Math.floor(view.byteLength / 2);
+		const out = new Float32Array(count);
+		for (let i = 0; i < count; i += 1) out[i] = view.getInt16(i * 2, true) / 32_768;
+		return out;
+	}
+	if (bitsPerSample === 8) {
+		// 8-bit PCM is unsigned, centered at 128.
+		const count = view.byteLength;
+		const out = new Float32Array(count);
+		for (let i = 0; i < count; i += 1) out[i] = (view.getUint8(i) - 128) / 128;
+		return out;
+	}
+	if (bitsPerSample === 32) {
+		const count = Math.floor(view.byteLength / 4);
+		const out = new Float32Array(count);
+		for (let i = 0; i < count; i += 1) out[i] = view.getInt32(i * 4, true) / 2_147_483_648;
+		return out;
+	}
+	throw new Error(`Unsupported PCM sample width: ${bitsPerSample} bits`);
+}
+
+/** Average interleaved channels down to a single mono track. */
+function mixToMono(interleaved: Float32Array, channels: number): Float32Array {
+	if (channels <= 1) return interleaved;
+	const frames = Math.floor(interleaved.length / channels);
+	const out = new Float32Array(frames);
+	for (let frame = 0; frame < frames; frame += 1) {
+		let sum = 0;
+		for (let channel = 0; channel < channels; channel += 1) sum += interleaved[frame * channels + channel]!;
+		out[frame] = sum / channels;
+	}
+	return out;
+}
+
+/**
+ * Resample via linear interpolation, mirroring the Python `np.interp` over
+ * `linspace(0, n-1, targetLen)` against `arange(n)`.
+ */
+export function resampleLinear(input: Float32Array, fromRate: number, toRate: number): Float32Array {
+	if (fromRate === toRate || input.length === 0) return input;
+	const n = input.length;
+	const targetLen = Math.max(1, Math.floor((n * toRate) / fromRate));
+	const out = new Float32Array(targetLen);
+	if (targetLen === 1) {
+		out[0] = input[0]!;
+		return out;
+	}
+	const step = (n - 1) / (targetLen - 1);
+	for (let i = 0; i < targetLen; i += 1) {
+		const pos = i * step;
+		const lo = Math.floor(pos);
+		const hi = Math.min(lo + 1, n - 1);
+		const frac = pos - lo;
+		out[i] = input[lo]! * (1 - frac) + input[hi]! * frac;
+	}
+	return out;
+}
+
+/**
+ * Decode a WAV byte buffer into a 16 kHz mono Float32Array suitable for the
+ * transformers.js Whisper pipeline.
+ */
+export function decodeWavToMono16k(buffer: ArrayBuffer): Float32Array {
+	const wav = parseWav(buffer);
+	const interleaved = decodeSamples(wav);
+	const mono = mixToMono(interleaved, wav.channels);
+	return resampleLinear(mono, wav.sampleRate, TARGET_SAMPLE_RATE);
+}
+
+/**
+ * Decode interleaved little-endian signed 16-bit PCM bytes into normalized
+ * [-1, 1] mono float samples. The live recorder streams raw s16le frames from
+ * sox/ffmpeg/arecord stdout (no RIFF container), so this is the hot-path
+ * counterpart to {@link decodeWavToMono16k}. `bytes` MUST be 2-byte aligned;
+ * callers buffer any trailing odd byte across chunk boundaries.
+ */
+export function decodePcmS16LE(bytes: Uint8Array): Float32Array {
+	const count = bytes.length >>> 1;
+	const view = new DataView(bytes.buffer, bytes.byteOffset, count * 2);
+	const out = new Float32Array(count);
+	for (let i = 0; i < count; i += 1) out[i] = view.getInt16(i * 2, true) / 32_768;
+	return out;
+}

package/src/system-prompt.ts

@@ -385,6 +385,10 @@ export interface BuildSystemPromptOptions {
 	mcpDiscoveryServerSummaries?: string[];
 	/** Encourage the agent to delegate via tasks unless changes are trivial. */
 	eagerTasks?: boolean;
+	/** When true, the Eager Tasks section uses the hard MUST/ONLY wording (`task.eager: always`) rather than the softer `preferred` nudge. */
+	eagerTasksAlways?: boolean;
+	/** Whether `task.batch` is enabled; gates batch-call guidance in the Eager Tasks section. */
+	taskBatch?: boolean;
 	/** Rules with alwaysApply=true — their full content is injected into the prompt. */
 	alwaysApplyRules?: AlwaysApplyRule[];
 	/** Whether secret obfuscation is active. When true, explains the redaction format in the prompt. */
@@ -427,6 +431,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		mcpDiscoveryMode = false,
 		mcpDiscoveryServerSummaries = [],
 		eagerTasks = false,
+		eagerTasksAlways = false,
+		taskBatch = true,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
 		memoryRootEnabled = false,
@@ -610,6 +616,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
 		mcpDiscoveryServerSummaries,
 		eagerTasks,
+		eagerTasksAlways,
+		taskBatch,
 		secretsEnabled,
 		hasMemoryRoot: memoryRootEnabled,
 		hasObsidian: hasObsidian(),

package/src/task/agents.ts

@@ -55,7 +55,6 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 			description: "General-purpose subagent with full capabilities for delegated multi-step tasks",
 			spawns: "*",
 			model: "pi/task",
-			thinkingLevel: Effort.Medium,
 		},
 		template: taskMd,
 	},
@@ -65,7 +64,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 			name: "quick_task",
 			description: "Low-reasoning agent for strictly mechanical updates or data collection only",
 			model: "pi/smol",
-			thinkingLevel: Effort.Minimal,
+			thinkingLevel: Effort.Medium,
 		},
 		template: taskMd,
 	},

package/src/task/executor.ts

@@ -8,7 +8,7 @@ import path from "node:path";
 import type { AgentEvent, AgentIdentity, AgentTelemetryConfig, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { recordHandoff, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
 import type { Usage } from "@oh-my-pi/pi-ai";
-import { logger, prompt, untilAborted } from "@oh-my-pi/pi-utils";
+import { logger, popLoopPhase, prompt, pushLoopPhase, untilAborted } from "@oh-my-pi/pi-utils";
 import type { Rule } from "../capability/rule";
 import { ModelRegistry } from "../config/model-registry";
 import { resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
@@ -56,7 +56,9 @@ import {
 	type AgentProgress,
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
+	oneLineLabel,
 	type ReviewFinding,
+	resolveSubagentDisplayName,
 	type SingleResult,
 	TASK_SUBAGENT_EVENT_CHANNEL,
 	TASK_SUBAGENT_LIFECYCLE_CHANNEL,
@@ -123,7 +125,10 @@ function renderIrcPeerRoster(selfId: string): string {
 		.list()
 		.filter(ref => ref.id !== selfId && ref.status !== "aborted");
 	if (peers.length === 0) return "- (no other agents)";
-	const lines = peers.map(peer => `- \`${peer.id}\` — ${peer.displayName} (${peer.kind}, ${peer.status})`);
+	const lines = peers.map(
+		peer =>
+			`- \`${peer.id}\` — ${peer.displayName} (${peer.kind}, ${peer.status})${peer.activity ? `: ${peer.activity}` : ""}`,
+	);
 	if (peers.some(peer => peer.status === "idle" || peer.status === "parked")) {
 		lines.push("Idle/parked peers are not gone: messaging them wakes (or revives) them.");
 	}
@@ -192,6 +197,8 @@ export interface ExecutorOptions {
 	 */
 	planReference?: { path: string; content: string };
 	description?: string;
+	/** Specialist role/expertise for this spawn; drives the system-prompt preamble, display name, and telemetry identity. */
+	role?: string;
 	index: number;
 	id: string;
 	parentToolCallId?: string;
@@ -837,6 +844,9 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 	const emitProgressNow = () => {
 		progress.durationMs = Date.now() - startTime;
 		onProgress?.({ ...progress });
+		const activityGist =
+			progress.lastIntent ?? (progress.currentTool ? `running ${progress.currentTool}` : undefined);
+		if (activityGist) AgentRegistry.global().setActivity(id, activityGist);
 		if (args.eventBus) {
 			args.eventBus.emit(TASK_SUBAGENT_PROGRESS_CHANNEL, {
 				index,
@@ -1198,6 +1208,9 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 				return;
 			}
 			if (isAgentEvent(event)) {
+				// Breadcrumb the synchronous subagent event handling so the loop
+				// watchdog can attribute any block to this in-process subagent.
+				pushLoopPhase(`subagent:${id}`);
 				try {
 					processEvent(event);
 				} catch (err) {
@@ -1205,6 +1218,8 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 						error: err instanceof Error ? err.message : String(err),
 					});
 					requestAbort("terminate");
+				} finally {
+					popLoopPhase();
 				}
 			}
 		});
@@ -1444,16 +1459,24 @@ async function finalizeRunResult(args: FinalizeRunArgs): Promise<SingleResult> {
 	const yieldItems = progress.extractedToolData?.yield as YieldItem[] | undefined;
 	const reportFindingDetails = progress.extractedToolData?.report_finding as ReportFindingDetails[] | undefined;
 	const reportFindings: ReviewFinding[] | undefined = reportFindingDetails?.map(toReviewFinding);
-	const finalized = finalizeSubprocessOutput({
-		rawOutput,
-		exitCode,
-		stderr,
-		doneAborted: Boolean(done.aborted),
-		signalAborted: Boolean(signal?.aborted),
-		yieldItems,
-		reportFindings,
-		outputSchema: args.outputSchema,
-	});
+	// Breadcrumb the synchronous yield-payload shaping (O(rawOutput)) so a block
+	// here is attributed to this subagent rather than logged as "unknown".
+	pushLoopPhase(`subagent:${id}`);
+	let finalized: FinalizeSubprocessOutputResult;
+	try {
+		finalized = finalizeSubprocessOutput({
+			rawOutput,
+			exitCode,
+			stderr,
+			doneAborted: Boolean(done.aborted),
+			signalAborted: Boolean(signal?.aborted),
+			yieldItems,
+			reportFindings,
+			outputSchema: args.outputSchema,
+		});
+	} finally {
+		popLoopPhase();
+	}
 	rawOutput = finalized.rawOutput;
 	exitCode = finalized.exitCode;
 	stderr = finalized.stderr;
@@ -1618,6 +1641,12 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		agent.readSummarize === false ? { "read.summarize.enabled": false } : undefined,
 	);
 	const maxRecursionDepth = settings.get("task.maxRecursionDepth") ?? 2;
+	// Tailored specialist identity for this spawn. `subagentRole` is the full
+	// (trimmed) role text fed to the system-prompt preamble; `subagentDisplayName`
+	// is the label-normalized form the registry/roster show, falling back to the
+	// agent type name when no role was given.
+	const subagentRole = options.role?.trim() || undefined;
+	const subagentDisplayName = resolveSubagentDisplayName(options.role, agent.name);
 	const maxRuntimeMs = Math.max(
 		0,
 		Math.trunc(Number(options.maxRuntimeMs ?? settings.get("task.maxRuntimeMs") ?? 0) || 0),
@@ -1816,7 +1845,11 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			// carry the subagent's own agent identity, and use the subagent's
 			// own session id for `gen_ai.conversation.id`.
 			const subagentAgentIdentity: AgentIdentity | undefined = options.parentTelemetry
-				? { id, name: agent.name, description: agent.description }
+				? {
+						id,
+						name: subagentDisplayName,
+						description: subagentRole ? oneLineLabel(subagentRole) : agent.description,
+					}
 				: undefined;
 			const subagentTelemetry: AgentTelemetryConfig | undefined =
 				options.parentTelemetry && subagentAgentIdentity
@@ -1866,6 +1899,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				systemPrompt: defaultPrompt => {
 					const subagentPrompt = prompt.render(subagentSystemPromptTemplate, {
 						agent: agent.systemPrompt,
+						role: subagentRole ? oneLineLabel(subagentRole) : "",
 						context: options.context?.trim() ?? "",
 						planReference: options.planReference?.content ?? "",
 						planReferencePath: options.planReference?.path ?? "",
@@ -1886,7 +1920,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				parentMnemopiSessionState: options.parentMnemopiSessionState,
 				parentTaskPrefix: id,
 				agentId: id,
-				agentDisplayName: agent.name,
+				agentDisplayName: subagentDisplayName,
 				enableLsp: lspEnabled,
 				skipPythonPreflight,
 				enableMCP,
@@ -1971,7 +2005,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 
 			const extensionRunner = session.extensionRunner;
-			const pendingExtensionMessages: Promise<void>[] = [];
+			const pendingExtensionMessages: Promise<unknown>[] = [];
 			if (extensionRunner) {
 				extensionRunner.initialize(
 					{

package/src/task/index.ts

@@ -33,6 +33,7 @@ import { formatBytes, formatDuration } from "../tools/render-utils";
 import {
 	type AgentDefinition,
 	type AgentProgress,
+	canSpawnAtDepth,
 	getTaskSchema,
 	type SingleResult,
 	type TaskItem,
@@ -310,7 +311,7 @@ function resolveSpawnItems(params: TaskParams): TaskItem[] {
 	if (Array.isArray(params.tasks) && params.tasks.length > 0) {
 		return params.tasks;
 	}
-	return [{ id: params.id, description: params.description, assignment: params.assignment }];
+	return [{ id: params.id, description: params.description, role: params.role, assignment: params.assignment }];
 }
 
 /**
@@ -324,6 +325,7 @@ function spawnParamsFor(params: TaskParams, item: TaskItem): TaskParams {
 	const spawn: TaskParams = { agent: params.agent };
 	if (item.id !== undefined) spawn.id = item.id;
 	if (item.description !== undefined) spawn.description = item.description;
+	if (item.role !== undefined) spawn.role = item.role;
 	if (item.assignment !== undefined) spawn.assignment = item.assignment;
 	if (params.context !== undefined) spawn.context = params.context;
 	if (item.isolated !== undefined) {
@@ -334,6 +336,36 @@ function spawnParamsFor(params: TaskParams, item: TaskItem): TaskParams {
 	return spawn;
 }
 
+/** Generic worker agents whose output sharpens with a tailored `role` rather than the bare type. */
+const GENERIC_SPAWN_AGENTS: ReadonlySet<string> = new Set(["task", "quick_task"]);
+
+/**
+ * Advisory — never a rejection — nudging the spawner toward tailored
+ * specialists when it spawns generic role-less workers and still holds spawn
+ * capacity (DepthCapacity: it currently has the `task` tool). Fires when a
+ * generic `task`/`quick_task` spawn carries no `role`, or when one call clones
+ * the same agent ≥2× all without roles. Returns undefined when no nudge applies.
+ */
+export function buildSpecializationAdvisory(
+	agentName: string | undefined,
+	items: TaskItem[],
+	depthCapacity: boolean,
+): string | undefined {
+	if (!depthCapacity) return undefined;
+	const rolelessCount = items.filter(item => !item.role?.trim()).length;
+	if (rolelessCount === 0) return undefined;
+	const generic = agentName !== undefined && GENERIC_SPAWN_AGENTS.has(agentName);
+	const cloned = items.length >= 2 && rolelessCount === items.length;
+	if (!generic && !cloned) return undefined;
+	const label = agentName ?? "task";
+	return (
+		`Tip: spawned ${rolelessCount} \`${label}\` worker${rolelessCount === 1 ? "" : "s"} without a \`role\`. ` +
+		`Tailored specialists outperform generic workers — give each spawn a \`role\` naming its expertise ` +
+		`(e.g. "Auth-flow security reviewer"). Depth budget remains, so decompose into named specialists ` +
+		`rather than cloning one generic worker.`
+	);
+}
+
 /** Sentinel for async jobs whose subagent finished with a failing result; progress is already updated. */
 class TaskJobError extends Error {}
 
@@ -388,6 +420,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		if (typeof params.agent === "string") {
 			lines.push(`Agent: ${truncateForPrompt(params.agent)}`);
 		}
+		if (typeof params.role === "string" && params.role.trim()) {
+			lines.push(`Role: ${truncateForPrompt(params.role)}`);
+		}
 		if (typeof params.id === "string" && params.id.trim()) {
 			lines.push(`Task: ${truncateForPrompt(params.id)}`);
 		}
@@ -403,6 +438,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			if (typeof firstTask.id === "string" && firstTask.id.trim()) {
 				lines.push(`Task: ${truncateForPrompt(firstTask.id)}`);
 			}
+			if (typeof firstTask.role === "string" && firstTask.role.trim()) {
+				lines.push(`Role: ${truncateForPrompt(firstTask.role)}`);
+			}
 			if (typeof firstTask.assignment === "string") {
 				lines.push(`Assignment:\n${truncateForPrompt(firstTask.assignment)}`);
 			}
@@ -497,6 +535,21 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const selectedAgent = this.#discoveredAgents.find(agent => agent.name === params.agent);
 		const asyncEnabled = this.session.settings.get("async.enabled");
 		const manager = asyncEnabled ? this.session.asyncJobManager : undefined;
+		const depthCapacity = canSpawnAtDepth(
+			this.session.settings.get("task.maxRecursionDepth") ?? 2,
+			this.session.taskDepth ?? 0,
+		);
+		const advisory = buildSpecializationAdvisory(params.agent, spawnItems, depthCapacity);
+		const withAdvisory = (result: AgentToolResult<TaskToolDetails>): AgentToolResult<TaskToolDetails> => {
+			if (!advisory) return result;
+			const textPart = result.content.find(part => part.type === "text");
+			if (textPart && typeof textPart.text === "string") {
+				textPart.text = `${textPart.text}\n\n${advisory}`;
+			} else {
+				result.content.push({ type: "text", text: advisory });
+			}
+			return result;
+		};
 		if (!asyncEnabled || !manager || selectedAgent?.blocking === true) {
 			// Sync fallback: async execution disabled, orphaned host that never
 			// wired a job manager, or an agent definition that declares
@@ -505,7 +558,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			if (asyncEnabled && !manager) {
 				logger.warn("task: no AsyncJobManager registered; falling back to sync execution");
 			}
-			return this.#executeSyncFanout(toolCallId, params, spawnItems, signal, onUpdate);
+			return withAdvisory(await this.#executeSyncFanout(toolCallId, params, spawnItems, signal, onUpdate));
 		}
 
 		// Resolve agent ids up front so the immediate result can name them.
@@ -613,7 +666,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				content: [{ type: "text", text: `Spawned agent \`${agentId}\`...` }],
 				details: buildAsyncDetails("running", jobId),
 			});
-			return {
+			return withAdvisory({
 				content: [
 					{
 						type: "text",
@@ -621,7 +674,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					},
 				],
 				details: buildAsyncDetails("running", jobId),
-			};
+			});
 		}
 
 		const coordinationHint = ircEnabled
@@ -641,7 +694,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			content: [{ type: "text", text: `Spawned ${started.length} agents...` }],
 			details: buildAsyncDetails("running", primaryJobId),
 		});
-		return {
+		return withAdvisory({
 			content: [
 				{
 					type: "text",
@@ -649,7 +702,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				},
 			],
 			details: buildAsyncDetails("running", primaryJobId),
-		};
+		});
 	}
 
 	/**
@@ -1146,6 +1199,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				context: sharedContext,
 				planReference,
 				description: params.description,
+				role: params.role,
 				index: spawnIndex,
 				parentToolCallId: toolCallId,
 				detached,