@ferris1225/pi-subagents 0.7.0 → 0.9.0

package/README.md

@@ -4,7 +4,7 @@
 [![downloads](https://img.shields.io/npm/dm/@ferris1225/pi-subagents)](https://www.npmjs.com/package/@ferris1225/pi-subagents)
 [![license](https://img.shields.io/npm/l/@ferris1225/pi-subagents)](./LICENSE)
 ![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
-![pi](https://img.shields.io/badge/platform-pi-orange)
+![pi](https://img.shields.io/badge/pi-extension-orange)
 
 Focused background delegation for [pi](https://pi.dev). `pi-subagents` adds a small set of
 specialized agents that run in isolated child processes, report results back to the main
@@ -21,8 +21,8 @@ agent, and keep the workflow moving without manual polling.
 - **Parallel fan-out** — run independent tasks together, with a bounded background queue.
 - **Live progress** — a TUI widget shows each agent's status, activity, model, usage, and
   elapsed time; completion also produces a concise notification.
-- **Per-agent configuration** — enable agents, select models, set thinking strength, and
-  choose discovery scope from `/subagents-setup`.
+- **Per-agent configuration** — enable agents, select models, set thinking strength, tune
+  concurrency limits, and choose discovery scope from `/subagents-setup`.
 - **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
   recurse.
 
@@ -40,8 +40,7 @@ After installation, open the setup wizard in an interactive TUI session:
 /subagents-setup
 ```
 
-The default configuration enables `explore`, `worker`, and `reviewer`. `plan` is available
-but opt-in.
+The default configuration enables `explore`, `worker`, and `reviewer`.
 
 ## Included agents
 
@@ -50,7 +49,6 @@ but opt-in.
 | `explore` | Yes | Read-only | Fast codebase reconnaissance and structured findings. |
 | `worker` | Yes | Full | Implements, fixes, refactors, and tests a self-contained task. |
 | `reviewer` | Yes | Read-only | Independent adversarial review of a diff before completion. |
-| `plan` | No | Read-only | Produces a separate implementation plan when one is useful. |
 
 Agents are Markdown files in `agents/`. Each file contains YAML frontmatter and a system
 prompt. User and project scopes can override a built-in agent with the same name.
@@ -72,8 +70,9 @@ main agent
 1. The main agent calls `subagent` with a self-contained brief.
 2. The tool returns immediately and ends that foreground tool turn, leaving the editor ready
    for input.
-3. The child process works independently. Up to four queued runs execute at once; a single
-   parallel request may contain up to eight tasks.
+3. The child process works independently. By default up to four queued runs execute at
+   once and a single parallel request may contain up to eight tasks; both limits are
+   configurable (`maxConcurrency` / `maxParallelTasks`).
 4. On completion or failure, the extension sends a durable result message to the main
    session. That message automatically wakes the main agent, or waits until its current turn
    finishes.
@@ -131,7 +130,10 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
   },
   "thinkingLevel": "max",
   "proactiveInjection": true,
-  "agentScope": "user"
+  "agentScope": "user",
+  "maxConcurrency": 4,
+  "maxParallelTasks": 8,
+  "maxSubagentDepth": 1
 }
 ```
 
@@ -142,6 +144,18 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
 | `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
 | `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
+| `maxConcurrency` | How many sub-agent processes run at once (1–16, default 4). Extra work waits in the queue. |
+| `maxParallelTasks` | Maximum tasks accepted by one parallel `subagent` call (1–32, default 8). |
+| `maxSubagentDepth` | Depth at which the `subagent` tool is no longer registered (default 1: the main session delegates, children are leaf processes). `0` disables the tool entirely. Read once at extension load. |
+
+### Configuration migration
+
+The config file migrates itself on load — no manual steps after an upgrade:
+
+- **Schema upgrades** — a config written by an older version (missing newer keys or
+  holding invalid values) is normalized and saved back with the new fields filled in.
+- **Removed agents** — agents no longer shipped (e.g. the old `plan` agent) are stripped
+  from `enabledAgents` and `agentModels` automatically.
 
 Model selection uses this precedence:
 

package/agents/explore.md

@@ -26,7 +26,7 @@ You are an explore agent: a fast, read-only reconnaissance specialist. You inves
 - Thorough: trace dependencies across modules; check tests and types.
 
 ## Collaboration
-- Your output feeds `plan` or `worker`. Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
+- Your output feeds `worker` (or the main agent directly). Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
 
 ## Output format
 ## Files Retrieved

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.7.0",
-  "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
+  "version": "0.9.0",
+  "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -43,7 +43,7 @@
     "@earendil-works/pi-coding-agent": "^0.83.0",
     "@earendil-works/pi-tui": "^0.83.0",
     "@types/node": "^22.10.0",
-    "typebox": "^1.3.7",
+    "typebox": "^1.3.9",
     "typescript": "^5.9.0",
     "vitest": "^4.1.0"
   },

package/src/background.ts

@@ -14,7 +14,7 @@ interface PendingTask {
 }
 
 export class BackgroundTaskQueue {
-	private readonly concurrency: number;
+	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
 	private readonly active = new Set<AbortController>();
 	private stopped = false;
@@ -23,6 +23,16 @@ export class BackgroundTaskQueue {
 		this.concurrency = Math.max(1, concurrency);
 	}
 
+	/**
+	 * Update the concurrency limit (e.g. after a config change). Raising it
+	 * immediately starts more queued work; lowering it takes effect as running
+	 * tasks finish — already-running tasks are never interrupted.
+	 */
+	setConcurrency(concurrency: number): void {
+		this.concurrency = Math.max(1, concurrency);
+		this.drain();
+	}
+
 	enqueue(task: BackgroundTask, onCancelled?: () => void): AbortController {
 		const controller = new AbortController();
 		if (this.stopped) {

package/src/config.ts

@@ -5,19 +5,31 @@
  * and honors PI_CODING_AGENT_DIR). Parsing is defensive: invalid fields fall back
  * to defaults instead of throwing, so a hand-edited or partially-written file can
  * never break the extension at runtime.
+ *
+ * Schema upgrades happen transparently on load: a config written by an older
+ * version (missing newer keys, holding removed agents, or containing invalid
+ * values) is normalized and persisted back with the new fields filled in.
  */
 
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["explore", "plan", "worker", "reviewer"] as const;
+export const BUILTIN_AGENT_NAMES = ["explore", "worker", "reviewer"] as const;
 export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
 
-/** Agents enabled out of the box. `plan` ships but is opt-in: a worker plans internally. */
+/** Agents enabled out of the box. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explore", "worker", "reviewer"];
 
+/**
+ * Agents that used to ship but were removed. normalizeConfig strips them from
+ * enabledAgents/agentModels so upgraded installs clean their config automatically
+ * (the schema-upgrade save in loadConfig then persists the cleanup).
+ */
+export const REMOVED_AGENT_NAMES: readonly string[] = ["plan"];
+
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
 export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 
@@ -28,6 +40,22 @@ export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "max";
 
 export const CONFIG_FILE_NAME = "pi-subagents.json";
 
+/** How many sub-agent processes may run at once. Default: 4. */
+export const DEFAULT_MAX_CONCURRENCY = 4;
+/** Upper bound accepted for maxConcurrency (defensive clamp). */
+export const MAX_CONCURRENCY_LIMIT = 16;
+/** How many tasks a single parallel `subagent` call may contain. Default: 8. */
+export const DEFAULT_MAX_PARALLEL_TASKS = 8;
+/** Upper bound accepted for maxParallelTasks (defensive clamp). */
+export const MAX_PARALLEL_TASKS_LIMIT = 32;
+/**
+ * Depth at which the subagent tool stops being available. 1 = the main session
+ * delegates and child processes are leaves; 0 disables the tool entirely.
+ */
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 1;
+/** Upper bound accepted for maxSubagentDepth (defensive clamp). */
+export const MAX_SUBAGENT_DEPTH_LIMIT = 4;
+
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
@@ -39,6 +67,12 @@ export interface SubagentsConfig {
 	proactiveInjection: boolean;
 	/** Which agent directories to discover from. Default: "user". */
 	agentScope: AgentScope;
+	/** Max sub-agent processes running at once (extra work queues). Default: 4. */
+	maxConcurrency: number;
+	/** Max tasks accepted by one parallel `subagent` call. Default: 8. */
+	maxParallelTasks: number;
+	/** Depth at which the subagent tool is no longer registered. Default: 1. */
+	maxSubagentDepth: number;
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -47,6 +81,9 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	thinkingLevel: DEFAULT_THINKING_LEVEL,
 	proactiveInjection: true,
 	agentScope: "user",
+	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+	maxParallelTasks: DEFAULT_MAX_PARALLEL_TASKS,
+	maxSubagentDepth: DEFAULT_MAX_SUBAGENT_DEPTH,
 };
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
@@ -68,6 +105,12 @@ function isModelReference(value: unknown): value is string {
 	return slash > 0 && slash < normalized.length - 1 && !/\s/u.test(normalized);
 }
 
+/** Clamp a raw value to a positive integer within [1, upper]; undefined when invalid. */
+function clampCount(value: unknown, upper: number): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+	return Math.max(1, Math.min(upper, Math.round(value)));
+}
+
 /**
  * Merge a raw parsed JSON value over the defaults, dropping invalid fields.
  * Exported for tests.
@@ -81,6 +124,9 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		thinkingLevel: DEFAULT_CONFIG.thinkingLevel,
 		proactiveInjection: DEFAULT_CONFIG.proactiveInjection,
 		agentScope: DEFAULT_CONFIG.agentScope,
+		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
+		maxParallelTasks: DEFAULT_CONFIG.maxParallelTasks,
+		maxSubagentDepth: DEFAULT_CONFIG.maxSubagentDepth,
 	};
 
 	if (Array.isArray(raw.enabledAgents)) {
@@ -88,11 +134,15 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 			(name): name is string => typeof name === "string" && name.trim().length > 0,
 		);
 		// An explicitly empty array is honored (disables all agents); otherwise keep valid names.
-		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
+		// Agents removed from the package (e.g. plan) are stripped from upgraded configs.
+		config.enabledAgents = [...new Set(names.map((name) => name.trim()))].filter(
+			(name) => !REMOVED_AGENT_NAMES.includes(name),
+		);
 	}
 
 	if (isRecord(raw.agentModels)) {
 		for (const [key, value] of Object.entries(raw.agentModels)) {
+			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
 			if (isModelReference(value)) config.agentModels[key.trim()] = value.trim();
 		}
 	}
@@ -109,33 +159,71 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.agentScope = raw.agentScope;
 	}
 
+	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
+	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
+
+	const maxParallelTasks = clampCount(raw.maxParallelTasks, MAX_PARALLEL_TASKS_LIMIT);
+	if (maxParallelTasks !== undefined) config.maxParallelTasks = maxParallelTasks;
+
+	// 0 is meaningful here (disables the tool), so clamp to [0, limit] instead.
+	if (typeof raw.maxSubagentDepth === "number" && Number.isFinite(raw.maxSubagentDepth)) {
+		config.maxSubagentDepth = Math.max(0, Math.min(MAX_SUBAGENT_DEPTH_LIMIT, Math.round(raw.maxSubagentDepth)));
+	}
+
 	return config;
 }
 
+function defaultConfig(): SubagentsConfig {
+	return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents], agentModels: {} };
+}
+
 /**
  * Load config. A missing file is a normal state and yields the defaults (not an error).
  * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
+ * A file from an older version (missing newer keys or holding removed agents) is
+ * normalized and persisted back, so the on-disk config stays current.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
 	try {
 		text = await readFile(configPath, "utf8");
-	} catch (error) {
-		if (isNodeError(error) && error.code === "ENOENT") {
-			return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
-		}
-		// Unreadable for another reason: fall back to defaults but do not crash startup.
-		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+	} catch {
+		// Missing or unreadable: fall back to defaults but do not crash startup.
+		return defaultConfig();
 	}
 
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(text);
 	} catch {
-		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+		return defaultConfig();
+	}
+
+	const config = normalizeConfig(parsed);
+
+	// Schema upgrade: persist the normalized shape when the file gained fields
+	// (new version) or dropped invalid/removed ones.
+	if (JSON.stringify(config) !== JSON.stringify(parsed)) {
+		try {
+			await saveConfig(config, configPath);
+		} catch {
+			// Non-fatal: keep the in-memory config for this run.
+		}
 	}
 
-	return normalizeConfig(parsed);
+	return config;
+}
+
+/**
+ * Synchronous load for the extension's init-time decisions (e.g. the recursion
+ * guard). Runs before any async context is available; never migrates or saves.
+ */
+export function loadConfigSync(configPath: string = getConfigPath()): SubagentsConfig {
+	try {
+		return normalizeConfig(JSON.parse(readFileSync(configPath, "utf8")));
+	} catch {
+		return defaultConfig();
+	}
 }
 
 /**
@@ -159,10 +247,6 @@ export async function saveConfig(
 	});
 }
 
-function isNodeError(error: unknown): error is NodeJS.ErrnoException {
-	return error instanceof Error;
-}
-
 export function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }

package/src/index.ts

@@ -2,7 +2,7 @@
  * pi-subagents — focused sub-agent delegation for pi.
  *
  * Registers:
- *   - a `subagent` tool that runs explore/plan/worker/reviewer agents as isolated
+ *   - a `subagent` tool that runs explore/worker/reviewer agents as isolated
  *     `pi` child processes (single or parallel),
  *   - a `/subagents-setup` command for selection-only configuration,
  *   - a `before_agent_start` hook that injects a delegation directive into the
@@ -18,14 +18,11 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { BackgroundTaskQueue } from "./background.ts";
-import { getConfigPath, loadConfig, saveConfig } from "./config.ts";
+import { getConfigPath, loadConfig, loadConfigSync, saveConfig } from "./config.ts";
 import { repairUnavailableModelOverrides } from "./models.ts";
 import { buildDelegationDirective } from "./prompt.ts";
 import { runSetup } from "./setup.ts";
 import {
-	MAX_CONCURRENCY,
-	MAX_PARALLEL_TASKS,
-	MAX_SUBAGENT_DEPTH,
 	currentSubagentDepth,
 	getFinalOutput,
 	getResultOutput,
@@ -36,17 +33,24 @@ import {
 	type SubagentLiveEvent,
 	type UsageStats,
 } from "./spawn.ts";
-import { formatToolActivity, monitor, statusColor, statusIcon, statusLabel } from "./monitor.ts";
+import { formatTaskSummary, formatToolActivity, monitor, statusColor, statusIcon, statusLabel } from "./monitor.ts";
+
+const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({ description: "Self-contained task to delegate (the agent has no memory of this conversation)" }),
+	task: Type.String({
+		...NON_BLANK_TASK_OPTIONS,
+		description: "Self-contained task to delegate (the agent has no memory of this conversation)",
+	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 
 const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
-	task: Type.Optional(Type.String({ description: "Self-contained task to delegate (single mode)" })),
+	task: Type.Optional(
+		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Self-contained task to delegate (single mode)" }),
+	),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 });
@@ -112,15 +116,23 @@ function formatUsage(usage: UsageStats): string {
 
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
-	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENCY);
+	// Init-time decisions need the config synchronously; the full (migrating)
+	// async load runs per tool call.
+	const initialConfig = loadConfigSync(configPath);
+	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
 	let sessionActive = true;
 
-	// Recursion guard: child sub-agents are leaf processes and cannot delegate again.
-	if (currentSubagentDepth() >= MAX_SUBAGENT_DEPTH) {
+	// Recursion guard: sub-agents at the configured depth are leaf processes and
+	// cannot delegate again. maxSubagentDepth 0 disables the tool entirely.
+	if (currentSubagentDepth() >= initialConfig.maxSubagentDepth) {
+		const reason =
+			initialConfig.maxSubagentDepth === 0
+				? "disabled by maxSubagentDepth 0 in pi-subagents.json"
+				: "disabled in nested sub-agent processes";
 		pi.registerCommand("subagents-setup", {
-			description: "Configure pi-subagents (disabled in nested sub-agent processes)",
+			description: `Configure pi-subagents (${reason})`,
 			handler: async (_args, ctx) => {
-				ctx.ui.notify("pi-subagents setup is unavailable inside a nested sub-agent.", "warning");
+				ctx.ui.notify(`pi-subagents setup is unavailable here (${reason}).`, "warning");
 			},
 		});
 		return;
@@ -144,7 +156,7 @@ export default function (pi: ExtensionAPI): void {
 		label: "Subagent",
 		description: [
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
-			"Agents: explore (read-only codebase recon), plan (implementation plan, opt-in), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
+			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
 			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
@@ -164,6 +176,8 @@ export default function (pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			monitor.beginTurn();
 			let config = await loadConfig(configPath);
+			// Pick up concurrency changes from /subagents-setup without a restart.
+			backgroundQueue.setConcurrency(config.maxConcurrency);
 			const repairedModels = repairUnavailableModelOverrides(ctx, config.agentModels);
 			if (repairedModels.changed) {
 				config = { ...config, agentModels: repairedModels.agentModels };
@@ -233,7 +247,7 @@ export default function (pi: ExtensionAPI): void {
 			}));
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
-			const hasSingle = Boolean(params.agent && params.task);
+			const hasSingle = Boolean(params.agent) && params.task !== undefined;
 
 			const makeDetails =
 				(mode: "single" | "parallel", background = false) =>
@@ -253,12 +267,37 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
+			if (hasTasks) {
+				const blankTaskIndex = params.tasks?.findIndex(({ task }) => task.trim().length === 0) ?? -1;
+				if (blankTaskIndex !== -1) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Invalid parameters. tasks[${blankTaskIndex}].task must contain at least one non-whitespace character. No background tasks were started. Enabled agents: ${catalog}.`,
+							},
+						],
+						details: makeDetails("parallel")([]),
+					};
+				}
+			} else if (params.task?.trim().length === 0) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Invalid parameters. task must contain at least one non-whitespace character. Enabled agents: ${catalog}.`,
+						},
+					],
+					details: makeDetails("single")([]),
+				};
+			}
+
 			const startBackground = (agentName: string, task: string, cwd?: string): SingleResult => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 
 				const pending = queuedResult(agent, task);
-				const runId = monitor.addRun(agent.name, agent.model);
+				const runId = monitor.addRun(agent.name, task, agent.model);
 				const onLive = makeLiveHandler(runId);
 
 				backgroundQueue.enqueue(
@@ -294,7 +333,7 @@ export default function (pi: ExtensionAPI): void {
 						pi.sendMessage(
 							{
 								customType: "subagent-result",
-								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${getResultOutput(result)}`,
+								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\nTask: ${formatTaskSummary(result.task)}\n\n${getResultOutput(result)}`,
 								display: true,
 							},
 							// The result is both durable context and a wake-up signal. If the
@@ -311,10 +350,13 @@ export default function (pi: ExtensionAPI): void {
 			// Sub-agents intentionally detach from the foreground turn. This makes the
 			// editor available immediately; completion messages later wake the main agent.
 			if (params.tasks && params.tasks.length > 0) {
-				if (params.tasks.length > MAX_PARALLEL_TASKS) {
+				if (params.tasks.length > config.maxParallelTasks) {
 					return {
 						content: [
-							{ type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.` },
+							{
+								type: "text",
+								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxParallelTasks} (configurable via /subagents-setup).`,
+							},
 						],
 						details: makeDetails("parallel", true)([]),
 					};
@@ -432,6 +474,9 @@ export default function (pi: ExtensionAPI): void {
 							const icon = statusIcon(r.status, theme);
 							const label = theme.fg(statusColor(r.status), statusLabel(r.status));
 							lines.push(truncateToWidth(` ${icon} ${monitor.summarize(r)} · ${label}`, width, ""));
+							if (r.status === "queued" || r.status === "running") {
+								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task)}`), width, ""));
+							}
 							// Activity sits one indent level below the agent name.
 							if (r.activity) lines.push(truncateToWidth(theme.fg("dim", `     ${r.activity}`), width, ""));
 						}

package/src/monitor.ts

@@ -10,7 +10,9 @@
  * conversation, so a stale "done" row must not linger in the widget.
  */
 
+import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import type { UsageStats } from "./spawn.ts";
 
 // ---------------------------------------------------------------------------
@@ -22,6 +24,7 @@ export type RunStatus = "queued" | "running" | "done" | "failed";
 export interface RunView {
 	id: number;
 	agent: string;
+	task: string;
 	model?: string;
 	status: RunStatus;
 	usage: UsageStats;
@@ -37,6 +40,27 @@ export interface RunView {
 // Formatting helpers
 // ---------------------------------------------------------------------------
 
+const TASK_SUMMARY_MAX = 80;
+const TASK_SUMMARY_ELLIPSIS = "…";
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/** One-line task preview, capped by terminal display columns (including the ellipsis). */
+export function formatTaskSummary(task: string): string {
+	const oneLine = stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
+	if (visibleWidth(oneLine) <= TASK_SUMMARY_MAX) return oneLine;
+
+	const prefixMax = TASK_SUMMARY_MAX - visibleWidth(TASK_SUMMARY_ELLIPSIS);
+	let prefix = "";
+	let prefixWidth = 0;
+	for (const { segment } of graphemeSegmenter.segment(oneLine)) {
+		const segmentWidth = visibleWidth(segment);
+		if (prefixWidth + segmentWidth > prefixMax) break;
+		prefix += segment;
+		prefixWidth += segmentWidth;
+	}
+	return `${prefix}${TASK_SUMMARY_ELLIPSIS}`;
+}
+
 function formatTokens(count: number): string {
 	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
 	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
@@ -142,11 +166,12 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	addRun(agent: string, model?: string): number {
+	addRun(agent: string, task: string, model?: string): number {
 		const id = this.nextId++;
 		this.runs.push({
 			id,
 			agent,
+			task,
 			model,
 			status: "queued",
 			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },

package/src/prompt.ts

@@ -17,7 +17,6 @@ import { formatCatalogEntry } from "./agents.ts";
 /** Compact role routing hints, emitted only for roles that are enabled. */
 const ROLE_ROUTING: Record<string, string> = {
 	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
-	plan: "plan — a separate, human-reviewable implementation plan before any code (read-only).",
 	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
 	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
 };

package/src/setup.ts

@@ -14,6 +14,8 @@ import {
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
+	DEFAULT_MAX_CONCURRENCY,
+	DEFAULT_MAX_PARALLEL_TASKS,
 	THINKING_LEVEL_VALUES,
 	type AgentScope,
 	type SubagentsConfig,
@@ -31,7 +33,6 @@ const INHERIT = "__inherit__";
 /** Short, selection-friendly descriptions for the built-in agents. */
 const MODULE_HINTS: Record<string, string> = {
 	explore: "read-only codebase recon (fast model)",
-	plan: "implementation plan before code (opt-in)",
 	worker: "implement / fix / refactor / test (full tools)",
 	reviewer: "adversarial pre-commit review (read-only)",
 };
@@ -129,6 +130,29 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 	return choice.startsWith("On");
 }
 
+/** Preset steps offered for the two numeric limits (selection-only wizard). */
+const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
+const PARALLEL_TASK_STEPS = [2, 4, 6, 8, 12, 16, 24, 32];
+
+async function pickCount(
+	ctx: ExtensionCommandContext,
+	title: string,
+	steps: readonly number[],
+	current: number,
+	defaultValue: number,
+): Promise<number | undefined> {
+	const values = [...new Set([...steps, current])].sort((a, b) => a - b);
+	const options = values.map((value) => {
+		const tags = [value === current ? "current" : "", value === defaultValue ? "default" : ""]
+			.filter(Boolean)
+			.join(", ");
+		return tags ? `${value} (${tags})` : String(value);
+	});
+	const choice = await ctx.ui.select(title, options);
+	if (choice === undefined) return undefined;
+	return Number.parseInt(choice, 10);
+}
+
 async function pickScope(ctx: ExtensionCommandContext, current: AgentScope): Promise<AgentScope | undefined> {
 	const labels: Record<AgentScope, string> = {
 		user: "user — built-in + ~/.pi/agent/agents (default)",
@@ -190,12 +214,33 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	const scope = await pickScope(ctx, base.agentScope);
 	if (scope === undefined) return notifyCancelled(ctx);
 
+	const maxConcurrency = await pickCount(
+		ctx,
+		"Max sub-agents running at once? (extra work queues)",
+		CONCURRENCY_STEPS,
+		base.maxConcurrency,
+		DEFAULT_MAX_CONCURRENCY,
+	);
+	if (maxConcurrency === undefined) return notifyCancelled(ctx);
+
+	const maxParallelTasks = await pickCount(
+		ctx,
+		"Max tasks in one parallel subagent call?",
+		PARALLEL_TASK_STEPS,
+		base.maxParallelTasks,
+		DEFAULT_MAX_PARALLEL_TASKS,
+	);
+	if (maxParallelTasks === undefined) return notifyCancelled(ctx);
+
 	const next: SubagentsConfig = {
 		enabledAgents: enabled,
 		agentModels: repairStaleModels(ctx, models),
 		thinkingLevel,
 		proactiveInjection: injection,
 		agentScope: scope,
+		maxConcurrency,
+		maxParallelTasks,
+		maxSubagentDepth: base.maxSubagentDepth,
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
@@ -208,6 +253,8 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		"Change thinking strength",
 		"Toggle proactive injection",
 		"Change agent scope",
+		"Change max concurrent sub-agents",
+		"Change max parallel tasks",
 		"Full re-setup",
 	]);
 	if (choice === undefined) return notifyCancelled(ctx);
@@ -236,6 +283,26 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		const scope = await pickScope(ctx, config.agentScope);
 		if (scope === undefined) return notifyCancelled(ctx);
 		next.agentScope = scope;
+	} else if (choice.startsWith("Change max concurrent")) {
+		const maxConcurrency = await pickCount(
+			ctx,
+			"Max sub-agents running at once? (extra work queues)",
+			CONCURRENCY_STEPS,
+			config.maxConcurrency,
+			DEFAULT_MAX_CONCURRENCY,
+		);
+		if (maxConcurrency === undefined) return notifyCancelled(ctx);
+		next.maxConcurrency = maxConcurrency;
+	} else if (choice.startsWith("Change max parallel")) {
+		const maxParallelTasks = await pickCount(
+			ctx,
+			"Max tasks in one parallel subagent call?",
+			PARALLEL_TASK_STEPS,
+			config.maxParallelTasks,
+			DEFAULT_MAX_PARALLEL_TASKS,
+		);
+		if (maxParallelTasks === undefined) return notifyCancelled(ctx);
+		next.maxParallelTasks = maxParallelTasks;
 	}
 
 	await saveConfig(next, configPath);

package/src/spawn.ts

@@ -20,12 +20,13 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, AgentSource } from "./agents.ts";
 import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
 
-export const MAX_PARALLEL_TASKS = 8;
-export const MAX_CONCURRENCY = 4;
+/**
+ * Limits are configurable: see maxConcurrency / maxParallelTasks /
+ * maxSubagentDepth in config.ts (defaults 4 / 8 / 1, via /subagents-setup
+ * or pi-subagents.json).
+ */
 /** Default thinking level for sub-agents. pi clamps it to the resolved model's support. */
 export const SUBAGENT_THINKING_LEVEL: ThinkingLevel = DEFAULT_THINKING_LEVEL;
-/** Child processes are leaf agents: they never receive the subagent tool. */
-export const MAX_SUBAGENT_DEPTH = 1;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 /** No default deadline: sub-agents may run until completion or explicit cancellation. */
 export const SUBAGENT_TIMEOUT_MS = 0;

package/agents/plan.md

@@ -1,41 +0,0 @@
----
-name: plan
-description: Implementation planning for non-trivial changes (opt-in). Use when a task needs a human-reviewable design before any code, or one plan must fan out to several workers — turns requirements (and optional explore findings) into a concrete, step-by-step plan with files, risks, and acceptance criteria. Read-only; never edits. Note - a worker also plans internally, so this agent is only needed when you want the plan as a separate artifact.
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
-# Model selection: REASONING + STRUCTURE. Use a strong reasoning model.
----
-
-You are a planning specialist. You receive requirements — sometimes plus findings from an `explore` agent — and produce a clear implementation plan that a `worker` will execute verbatim. You have NOT got the caller's conversation history.
-
-## Hard constraints
-- You must NOT make any changes. Only read, analyze, and plan.
-- Bash is read-only: `grep`, `find`, `ls`, `cat`, `git log/show/diff`. No installs, builds, or edits.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-
-## When invoked
-1. Restate the goal in one sentence. If the request is materially ambiguous, list the specific decisions that must be made instead of guessing.
-2. Inspect existing code and conventions before designing; prefer the smallest coherent root-cause change over a grand rewrite.
-3. Produce small, ordered, independently-verifiable steps. Each step names the file/function to touch and the change.
-4. Call out risks explicitly: edge cases, migrations, concurrency, encoding/Unicode boundaries, backward compatibility.
-
-## Collaboration
-- Consumes `explore` output when provided; if context is missing, say what an explore should retrieve.
-- Feeds `worker`: keep steps concrete enough to execute without re-deriving the design.
-
-## Output format
-## Goal
-One sentence.
-## Plan
-1. Step — specific file/function to modify and what changes.
-## Files to Modify
-- `path/to/file.ts` — what changes and why.
-## New Files (if any)
-- `path/to/new.ts` — responsibility.
-## Risks
-What to watch out for, and how to mitigate.
-## Acceptance
-How to verify correctness: commands, tests, expected behavior.
-
-## Quality standards
-Concrete and minimal. No prose to fill space. Every step is actionable and verifiable.