@ferris1225/pi-subagents 0.12.0 → 0.14.0

package/README.md

@@ -68,48 +68,48 @@ here first.
 <summary><code>agents/explore.md</code> — reconnaissance</summary>
 
 ```markdown
----
-name: explore
-description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
-thinking: low
-# Model selection: SPEED over depth. Pick the fastest available model.
-# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
----
-
-You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
-
-## Hard constraints
-- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
-- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-
-## When invoked
-1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
-2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
-3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
-4. Record exact paths and line ranges so the caller can jump straight in.
-
-## Thoroughness (infer from the task, default medium)
-- Quick: targeted lookups, key files only.
-- Medium: follow imports and callers, read critical sections.
-- Thorough: trace dependencies across modules; check tests and types.
-
-## Collaboration
-- 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
-1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
-## Key Code
-Critical types / interfaces / signatures as short code blocks.
-## Architecture
-A brief explanation of how the pieces connect.
-## Start Here
-Which file to look at first, and why.
-
-## Quality standards
+---
+name: explore
+description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+thinking: low
+# Model selection: SPEED over depth. Pick the fastest available model.
+# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
+---
+
+You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
+
+## Hard constraints
+- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
+- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## When invoked
+1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
+2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
+3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
+4. Record exact paths and line ranges so the caller can jump straight in.
+
+## Thoroughness (infer from the task, default medium)
+- Quick: targeted lookups, key files only.
+- Medium: follow imports and callers, read critical sections.
+- Thorough: trace dependencies across modules; check tests and types.
+
+## Collaboration
+- 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
+1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
+## Key Code
+Critical types / interfaces / signatures as short code blocks.
+## Architecture
+A brief explanation of how the pieces connect.
+## Start Here
+Which file to look at first, and why.
+
+## Quality standards
 Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
 ```
 
@@ -119,52 +119,52 @@ Terse and factual. Exact paths and line numbers. Compress — do not narrate you
 <summary><code>agents/worker.md</code> — implementation</summary>
 
 ```markdown
----
-name: worker
-description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
-model: claude-sonnet-4-5
-thinking: high
-# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
-# balance quality against cost. No `tools` field => inherits all tools (full capability).
----
-
-You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-## Standard operating procedure
-Work in phases. Do not skip planning or verification.
-
-### Phase 1 — Context
-Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
-
-### Phase 2 — Plan
-Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
-
-### Phase 3 — Implement
-Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
-
-### Phase 4 — Verify
-Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
-
-### Phase 5 — Handoff
-Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
-
-## Collaboration
-- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
-  brief lacks context that needs broad code discovery, state concretely what an `explore` should
-  retrieve for the caller — do not guess.
-- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
-
-## Output format
-## Completed
-What was done, in a few lines.
-## Files Changed
-- `path/to/file.ts` — what changed.
-## Verification
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
-## Notes (if any)
-Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
-
-## Quality standards
+---
+name: worker
+description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
+# balance quality against cost. No `tools` field => inherits all tools (full capability).
+---
+
+You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+## Standard operating procedure
+Work in phases. Do not skip planning or verification.
+
+### Phase 1 — Context
+Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
+
+### Phase 2 — Plan
+Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
+
+### Phase 3 — Implement
+Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
+
+### Phase 4 — Verify
+Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
+
+### Phase 5 — Handoff
+Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
+
+## Collaboration
+- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
+  brief lacks context that needs broad code discovery, state concretely what an `explore` should
+  retrieve for the caller — do not guess.
+- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
+
+## Output format
+## Completed
+What was done, in a few lines.
+## Files Changed
+- `path/to/file.ts` — what changed.
+## Verification
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+## Notes (if any)
+Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
+
+## Quality standards
 Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
 ```
 
@@ -257,9 +257,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. 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`).
+3. The child process works independently. By default up to four sub-agents run at once —
+   and one parallel call accepts at most four tasks; extra runs queue up to `maxConcurrency`
+   (configurable via `/subagents-setup` or `pi-subagents.json`).
 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.
@@ -331,8 +331,6 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
   "proactiveInjection": true,
   "agentScope": "user",
   "maxConcurrency": 4,
-  "maxParallelTasks": 8,
-  "maxSubagentDepth": 1,
   "maxFixRounds": 2
 }
 ```
@@ -347,9 +345,7 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
 | `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; the full text is written to a temp file whose path is included in the message. |
 | `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. |
+| `maxConcurrency` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL`: the extension dispatches a `worker` (briefed with the review's concrete findings) then a `reviewer` re-review, repeating up to this many times before waking the main agent with the full chain. `0` disables it (the main agent handles fixes itself). Default 2. The reviewer stays read-only and in its own context; the loop is orchestrated by the extension, not by the reviewer. |
 
 ### Configuration migration
@@ -360,6 +356,11 @@ The config file migrates itself on load — no manual steps after an upgrade:
   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`, `agentModels`, and `agentThinkingLevels` automatically.
+- **Merged limits** — the pre-0.13 `maxParallelTasks` key is folded into `maxConcurrency`
+  (the larger of the two wins) and dropped on the next save.
+- **Removed keys** — `maxSubagentDepth` (0.14) is dropped on load: sub-agent children are
+  always leaf processes (the `subagent` tool is excluded from their toolset, with a depth
+  marker as defense in depth). To disable delegation entirely, use `"enabledAgents": []`.
 
 Model selection uses this precedence:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.12.0",
+  "version": "0.14.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",

package/src/config.ts

@@ -45,21 +45,10 @@ export const MAX_RESULT_LINES_LIMIT = 2000;
 
 export const CONFIG_FILE_NAME = "pi-subagents.json";
 
-/** How many sub-agent processes may run at once. Default: 4. */
+/** How many sub-agent processes may run at once, and how many tasks one parallel `subagent` call may contain. 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;
 /**
  * How many automatic worker→reviewer fix rounds run when a reviewer returns
  * REVIEW_FAIL before waking the main agent. 0 disables the auto-fix loop
@@ -93,12 +82,9 @@ 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. */
+	/** Max sub-agent processes running at once (extra work queues) and the max tasks
+	 * one parallel `subagent` call may contain. 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;
 	/**
 	 * Auto-fix rounds when a reviewer returns REVIEW_FAIL: the extension dispatches
 	 * a worker (briefed with the review's concrete findings) then a reviewer
@@ -119,8 +105,6 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	proactiveInjection: true,
 	agentScope: "user",
 	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
-	maxParallelTasks: DEFAULT_MAX_PARALLEL_TASKS,
-	maxSubagentDepth: DEFAULT_MAX_SUBAGENT_DEPTH,
 	maxFixRounds: DEFAULT_MAX_FIX_ROUNDS,
 };
 
@@ -166,8 +150,6 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		proactiveInjection: DEFAULT_CONFIG.proactiveInjection,
 		agentScope: DEFAULT_CONFIG.agentScope,
 		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
-		maxParallelTasks: DEFAULT_CONFIG.maxParallelTasks,
-		maxSubagentDepth: DEFAULT_CONFIG.maxSubagentDepth,
 		maxFixRounds: DEFAULT_CONFIG.maxFixRounds,
 	};
 
@@ -223,12 +205,12 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	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)));
+	// Schema migration: maxParallelTasks (pre-0.13) merged into maxConcurrency.
+	// Take the larger of the two so an upgraded config never loses capacity it
+	// was explicitly given; the old key is dropped on the persisted save.
+	const legacyParallelTasks = clampCount(raw.maxParallelTasks, MAX_CONCURRENCY_LIMIT);
+	if (legacyParallelTasks !== undefined && legacyParallelTasks > config.maxConcurrency) {
+		config.maxConcurrency = legacyParallelTasks;
 	}
 
 	// 0 disables the auto-fix loop (main agent handles fixes itself).

package/src/index.ts

@@ -167,17 +167,15 @@ export default function (pi: ExtensionAPI): void {
 	};
 	const completionBatcher = createCompletionBatcher<CompletionMessageItem>({ emit: sendCompletionGroup });
 
-	// 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";
+	// Recursion guard: sub-agent children are leaf processes. The `subagent` tool is
+	// excluded from their toolset at spawn (--exclude-tools); this check is defense
+	// in depth so a child can never expose the tool back to its model, even if
+	// another extension ignores the depth marker.
+	if (currentSubagentDepth() >= 1) {
 		pi.registerCommand("subagents-setup", {
-			description: `Configure pi-subagents (${reason})`,
+			description: "Configure pi-subagents (unavailable in nested sub-agent processes)",
 			handler: async (_args, ctx) => {
-				ctx.ui.notify(`pi-subagents setup is unavailable here (${reason}).`, "warning");
+				ctx.ui.notify("pi-subagents setup is unavailable in nested sub-agent processes.", "warning");
 			},
 		});
 		return;
@@ -245,22 +243,34 @@ export default function (pi: ExtensionAPI): void {
 
 			// Finished runs leave the widget immediately. Their final findings are sent
 			// back as a custom message that automatically starts a follow-up turn.
-			const finishRun = (runId: number, status: "done" | "failed"): void => {
+			const finishRun = (
+				runId: number,
+				status: "done" | "failed",
+				opts?: { silent?: boolean; retain?: boolean },
+			): void => {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-				const run = monitor.removeRun(runId);
+				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
-				if (!sessionActive) return;
+				if (opts?.silent || !sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob.
-			const makeLiveHandler = (runId: number) => (e: SubagentLiveEvent): void => {
+			// "read src/index.ts", ...), never a raw args blob. Reviewer runs started
+			// by the main agent defer finishing so the queue task can decide between
+			// delivering the review and starting an auto-fix chain: a triggered chain
+			// keeps the parent row in the widget (annotated) until it completes and
+			// suppresses the premature "done" notification.
+			const makeLiveHandler = (runId: number, deferFinish = false) => (e: SubagentLiveEvent): void => {
 				switch (e.kind) {
 					case "status":
-						if (e.status === "done" || e.status === "failed") finishRun(runId, e.status);
-						else monitor.setStatus(runId, e.status);
+						if (e.status === "done" || e.status === "failed") {
+							// Deferred runs only update the widget; the queue task finishes
+							// them once it knows whether an auto-fix chain will follow.
+							if (deferFinish) monitor.setStatus(runId, e.status);
+							else finishRun(runId, e.status);
+						} else monitor.setStatus(runId, e.status);
 						break;
 					case "usage":
 						monitor.setUsage(runId, e.usage, e.model);
@@ -388,8 +398,10 @@ export default function (pi: ExtensionAPI): void {
 			 * findings) → reviewer re-review, up to maxFixRounds times. The main agent is
 			 * not woken mid-loop; the full chain is delivered as one group at the end.
 			 * Failures short-circuit: a crashed worker skips its re-review and delivers.
+			 * The triggering reviewer's run stays visible in the widget (annotated) until
+			 * the chain resolves, so the ↳ rows have an obvious parent.
 			 */
-			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string): void => {
+			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string, parentRunId: number): void => {
 				backgroundQueue.enqueue(
 					async (signal) => {
 						const chain: SingleResult[] = [initialReviewerResult];
@@ -410,12 +422,18 @@ export default function (pi: ExtensionAPI): void {
 							});
 							chain.push(reviewResult);
 							lastReviewer = reviewResult;
-							if (!sessionActive) break;
+							// A crashed re-review must stop the chain like a crashed worker: its
+							// output (if any) is not a verdict, and feeding it to the next fix
+							// round would brief the worker from garbage.
+							if (!sessionActive || isFailedResult(reviewResult)) break;
 							if (reviewVerdict(getResultOutput(reviewResult)) === "pass") break;
 						}
+						// The chain is done (success, exhaustion, or abort): drop the retained
+						// parent row, then deliver the whole chain as one group. The loop's
+						// outcome always wakes the main agent (a passing chain reports
+						// success, a stuck one needs a human).
+						monitor.removeRun(parentRunId);
 						if (!sessionActive) return;
-						// Deliver the whole chain as one group; the loop's outcome always wakes
-						// the main agent (a passing chain reports success, a stuck one needs a human).
 						const items: CompletionMessageItem[] = chain.map((r) => ({
 							agent: r.agent,
 							block: formatCompletionBlock(r, config.maxResultLines),
@@ -425,7 +443,9 @@ export default function (pi: ExtensionAPI): void {
 						completionBatcher.flush();
 					},
 					() => {
-						// Cancelled: each in-flight run was already finished by its launchInLoop path.
+						// Cancelled before delivery: clean up the retained parent row (each
+						// in-flight chain run was already finished by its launchInLoop path).
+						monitor.removeRun(parentRunId);
 					},
 				);
 			};
@@ -438,7 +458,9 @@ export default function (pi: ExtensionAPI): void {
 				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
 				const pending = queuedResult(agent, task, thinkingLevel);
 				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel);
-				const onLive = makeLiveHandler(runId);
+				// Only a main-agent-dispatched reviewer can trigger an auto-fix chain, so
+				// only its finish is deferred to the queue task (see startFixLoop).
+				const onLive = makeLiveHandler(runId, agent.name === "reviewer");
 
 				backgroundQueue.enqueue(
 					async (backgroundSignal) => {
@@ -475,12 +497,22 @@ export default function (pi: ExtensionAPI): void {
 						// triggers a worker→reviewer chain (up to maxFixRounds) without waking
 						// the main agent. Loop-internal re-reviews never reach here (they are
 						// awaited inside launchInLoop); the initial review is delivered with
-						// the chain at the end.
+						// the chain at the end. While the chain runs, the triggering review
+						// stays in the widget (annotated) so the chain rows have an obvious
+						// parent; no premature "done" notification is shown.
 						if (shouldTriggerFixLoop(result, config)) {
-							startFixLoop(result, `fix-${runId}`);
+							// The session is known active here (checked above), so the chain
+							// always starts: keep the triggering review in the widget
+							// (annotated) without a premature "done" notification, and let
+							// startFixLoop deliver the whole chain and drop the parent row.
+							finishRun(runId, "done", { silent: true, retain: true });
+							monitor.setAnnotation(runId, "auto-fix chain running");
+							startFixLoop(result, `fix-${runId}`, runId);
 							return;
 						}
 						const failed = isFailedResult(result);
+						finishRun(runId, failed ? "failed" : "done");
+						if (!sessionActive) return;
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
 							block: formatCompletionBlock(result, config.maxResultLines),
@@ -504,12 +536,12 @@ 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 > config.maxParallelTasks) {
+				if (params.tasks.length > config.maxConcurrency) {
 					return {
 						content: [
 							{
 								type: "text",
-								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxParallelTasks} (configurable via /subagents-setup).`,
+								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxConcurrency} (configurable via /subagents-setup).`,
 							},
 						],
 						details: makeDetails("parallel", true)([]),
@@ -630,7 +662,8 @@ export default function (pi: ExtensionAPI): void {
 							// Chain-internal runs (auto-fix worker/reviewer) indent under their
 							// parent reviewer; summarize() already carries the relationLabel.
 							const head = r.groupId ? theme.fg("dim", "  ↳ ") : " ";
-							lines.push(truncateToWidth(`${head}${icon} ${monitor.summarize(r)} · ${label}`, width, ""));
+							const note = r.annotation ? theme.fg("dim", ` · ${r.annotation}`) : "";
+							lines.push(truncateToWidth(`${head}${icon} ${monitor.summarize(r)} · ${label}${note}`, width, ""));
 							if (r.status === "queued" || r.status === "running") {
 								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task)}`), width, ""));
 							}

package/src/monitor.ts

@@ -40,6 +40,8 @@ export interface RunView {
 	groupId?: string;
 	/** Human-readable role within a chain, e.g. "fix round 1" or "re-review round 1". */
 	relationLabel?: string;
+	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
+	annotation?: string;
 }
 
 /** Optional chain metadata for runs spawned by an auto-fix loop. */
@@ -199,8 +201,11 @@ export class MonitorStore {
 		const run = this.find(id);
 		if (!run) return;
 		run.status = status;
-		if (status === "running" && run.startedAt === undefined) {
-			run.startedAt = Date.now();
+		if (status === "running") {
+			if (run.startedAt === undefined) run.startedAt = Date.now();
+			// A model-fallback retry after a failed attempt restarts the clock; a
+			// stale endedAt would freeze the elapsed display at the first attempt.
+			if (run.endedAt !== undefined) run.endedAt = undefined;
 		} else if ((status === "done" || status === "failed") && run.endedAt === undefined) {
 			run.endedAt = Date.now();
 		}
@@ -222,6 +227,19 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Set a widget note on the run (e.g. that its auto-fix chain is still running). */
+	setAnnotation(id: number, text: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.annotation = text;
+		this.notify();
+	}
+
+	/** Look up a run by id without removing it. */
+	findRun(id: number): RunView | undefined {
+		return this.find(id);
+	}
+
 	/** Remove a run (finished runs leave the widget). Returns the removed run. */
 	removeRun(id: number): RunView | undefined {
 		const index = this.runs.findIndex((r) => r.id === id);

package/src/setup.ts

@@ -16,7 +16,6 @@ import {
 	DEFAULT_ENABLED_AGENTS,
 	DEFAULT_MAX_CONCURRENCY,
 	DEFAULT_MAX_FIX_ROUNDS,
-	DEFAULT_MAX_PARALLEL_TASKS,
 	THINKING_LEVEL_VALUES,
 	type AgentScope,
 	type SubagentsConfig,
@@ -196,7 +195,6 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 
 /** 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];
 /** Preset rounds offered for the auto-fix loop (0 disables it). */
 const FIX_ROUNDS_STEPS = [0, 1, 2, 3, 5];
 
@@ -284,22 +282,13 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 
 	const maxConcurrency = await pickCount(
 		ctx,
-		"Max sub-agents running at once? (extra work queues)",
+		"Max sub-agents running at once (and per parallel call)? (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 maxFixRounds = await pickCount(
 			ctx,
 			"Auto-fix rounds when a reviewer returns REQUEST_CHANGES? (0 = main agent handles fixes)",
@@ -319,8 +308,6 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		proactiveInjection: injection,
 		agentScope: scope,
 		maxConcurrency,
-		maxParallelTasks,
-		maxSubagentDepth: base.maxSubagentDepth,
 		maxFixRounds,
 	};
 	await saveConfig(next, configPath);
@@ -335,7 +322,6 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		"Toggle proactive injection",
 		"Change agent scope",
 		"Change max concurrent sub-agents",
-		"Change max parallel tasks",
 		"Change max fix rounds",
 		"Full re-setup",
 	]);
@@ -381,23 +367,13 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 	} else if (choice.startsWith("Change max concurrent")) {
 		const maxConcurrency = await pickCount(
 			ctx,
-			"Max sub-agents running at once? (extra work queues)",
+			"Max sub-agents running at once (and per parallel call)? (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;
 	} else if (choice.startsWith("Change max fix")) {
 		const maxFixRounds = await pickCount(
 			ctx,

package/src/spawn.ts

@@ -15,15 +15,15 @@ import { existsSync, mkdirSync, unlinkSync, rmdirSync, writeFileSync } from "nod
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig, AgentSource } from "./agents.ts";
 import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
 
 /**
- * Limits are configurable: see maxConcurrency / maxParallelTasks /
- * maxSubagentDepth in config.ts (defaults 4 / 8 / 1, via /subagents-setup
- * or pi-subagents.json).
+ * Limits are configurable: see maxConcurrency in config.ts (default 4, 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;
@@ -135,7 +135,9 @@ export function writeResultArtifact(output: string, agentName: string): string {
 	const dir = join(tmpdir(), "pi-subagents-results");
 	mkdirSync(dir, { recursive: true });
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
-	const filePath = join(dir, `${Date.now()}-${safeName}.md`);
+	// A random suffix keeps same-millisecond writes from clobbering each other.
+	const unique = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+	const filePath = join(dir, `${unique}-${safeName}.md`);
 	writeFileSync(filePath, output, "utf8");
 	return filePath;
 }
@@ -458,8 +460,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			proc.stdin?.on("error", () => undefined);
 			proc.stdin?.end(`Task: ${task}`);
 
+			// Decode stdout through a StringDecoder so multi-byte UTF-8 characters
+			// (CJK, emoji) split across chunk boundaries never produce U+FFFD
+			// replacement characters — a corrupted JSON line would drop the whole
+			// message (including a reviewer's verdict line) from parsing.
+			const stdoutDecoder = new StringDecoder("utf8");
 			proc.stdout.on("data", (data) => {
-				buffer += data.toString();
+				buffer += stdoutDecoder.write(data);
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
 				for (const line of lines) processLine(line);
@@ -470,6 +477,9 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			});
 
 			proc.on("close", (code) => {
+				// Flush any bytes still held by the decoder (a trailing incomplete
+				// multi-byte sequence) before processing the final buffer.
+				buffer += stdoutDecoder.end();
 				if (buffer.trim()) processLine(buffer);
 				// A null exit code means the process was terminated by a signal and
 				// must be reported as failure, never as a false clean completion.