@henryqw/pi-subagent 14.0.1 → 15.0.1

package/CONTEXT.md

@@ -23,7 +23,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns` is a safe integer >= 10; default 50) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. Role launches, including `delegate_task` and each `delegate_flow` Implementer or Reviewer launch, reserve the final allowed turn for a response-only handoff: after a continuing penultimate `turn_end` and its tools, they disable every tool and steer one structured final report. Its fixed decision packet is the default, but exact output required by the assigned task or Role takes precedence and is returned alone. A terminal penultimate response gets no handoff. This does not extend the executor limit. Raw `createEphemeralSubagentExecutor` launches do not guarantee a handoff, and timeout, provider, or child-process failures can prevent one. Before the final boundary, the Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/config.json` (`maxTurns` default 50 and minimum 10; `timeout.idleMinutes`/`maxMinutes` defaults 10/30).
+- One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns` is a safe integer >= 1; default 50) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. When Role launches, including `delegate_task` and each `delegate_flow` Implementer or Reviewer launch, reach a continuing penultimate `turn_end`, they reserve the final allowed turn for a response-only handoff: after its tools, they disable every tool and steer one structured final report. With `maxTurns` set to 1, they disable tools during `session_start`, and the sole provider turn is the response-only handoff. Its fixed decision packet is the default, but exact output required by the assigned task or Role takes precedence and is returned alone. A terminal penultimate response gets no handoff. This does not extend the executor limit. Raw `createEphemeralSubagentExecutor` launches do not guarantee a handoff, and timeout, provider, or child-process failures can prevent one. Before the final boundary, the Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/config.json` (`maxTurns` is a safe integer >= 1 and defaults to 50; `timeout.idleMinutes`/`maxMinutes` default to 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/config.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
 - Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.

package/README.md

@@ -64,7 +64,9 @@ An explicit `model` (`provider/modelId`) replaces only the route model and must
 
 Parallel tasks start together, settle together, and report in input order. Chains are sequential and fail at the first failure. `{previous}` passes only the immediately preceding successful assistant output.
 
-Foreground failures throw after keeping bounded sibling and recovery evidence. One call has one aggregate 50 KiB cap for Main-visible text. Live updates show task names and statuses without opaque IDs. Final results show summaries first and full evidence below.
+Foreground failures throw after keeping bounded sibling and recovery evidence. One call has one aggregate 50 KiB cap for Main-visible text. Final results show summaries first and full evidence below.
+
+The status widget shows each task group name above at most three indented child rows. Each row shows a one-letter Role badge, status, activity, usage, and duration. Flow stages for one unit share that unit's heading.
 
 Background work belongs to its launching session. Shutdown or reload aborts it and may leave only recoverable-work evidence or no follow-up message.
 
@@ -107,19 +109,21 @@ pi-subagent owns `~/.pi/agent/config/pi-subagent/config.json`. It is optional. A
 | Field | Valid value | Default |
 | --- | --- | --- |
 | `maxSubagents` | Safe integer ≥ 1 | `5` |
-| `maxTurns` | Safe integer ≥ 10 | `50` |
+| `maxTurns` | Safe integer ≥ 1 | `50` |
 | `timeout.idleMinutes` | Positive minutes; minutes × 60,000 ≤ 2,147,483,647 ms | `10` |
 | `timeout.maxMinutes` | Positive minutes greater than `idleMinutes`; minutes × 60,000 ≤ 2,147,483,647 ms | `30` |
 
-`maxTurns` defaults to 50. Its minimum is 10.
+`maxTurns` defaults to 50.
 
 Excess children wait FIFO without using a child timeout. A terminal response on turn 50 succeeds; an attempted continuation rejects with `turn_limit`.
 
 ### Final response handoff
 
-Role launches reserve the final allowed turn for a response-only handoff. This includes `delegate_task` and every Implementer or Reviewer launch within `delegate_flow`.
+When a Role launch reaches a continuing penultimate turn, Pi reserves the final allowed turn for a response-only handoff. This includes `delegate_task` and every Implementer or Reviewer launch within `delegate_flow`.
+
+With `maxTurns` set to 1, Pi disables tools at startup. The sole provider turn is the response-only handoff.
 
-After a continuing penultimate turn, Pi waits for its tools. It then disables all tools and requests a final report. The final allowed provider request has no tools. A terminal penultimate response gets no handoff.
+Pi waits for the penultimate turn's tools. It then disables all tools and requests a final report. The final allowed provider request has no tools. A terminal penultimate response gets no handoff.
 
 The fixed decision packet asks for Status (completed, blocked, or incomplete), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence. The child returns only that output, such as a Flow Reviewer's exact `PASS` or caller-required structured output. It reserves a turn within the existing hard limit; it never adds a model turn. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
 

package/dist/ephemeral.d.ts

@@ -1,6 +1,5 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import type { PiLaunch } from "./index.ts";
-export declare const MIN_MAX_TURNS: 10;
 export declare const DEFAULT_MAX_TURNS = 50;
 export declare const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 export interface EphemeralSubagentTimeout {

package/dist/ephemeral.js

@@ -5,7 +5,6 @@ import { StringDecoder } from "node:string_decoder";
 import { hasDisplayControlCharacters } from "./display-text.js";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
-export const MIN_MAX_TURNS = 10;
 export const DEFAULT_MAX_TURNS = 50;
 export const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 const MAX_ACTIVITY_TEXT_BYTES = 4 * 1024;
@@ -68,8 +67,8 @@ function validateOptions(options) {
         throw new RangeError("maxConcurrency must be a positive safe integer.");
     }
     const maxTurns = options.maxTurns === undefined ? DEFAULT_MAX_TURNS : options.maxTurns;
-    if (!Number.isSafeInteger(maxTurns) || maxTurns < MIN_MAX_TURNS) {
-        throw new RangeError(`maxTurns must be a safe integer >= ${MIN_MAX_TURNS}.`);
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new RangeError("maxTurns must be a safe integer >= 1.");
     }
     if (!options.timeout || typeof options.timeout !== "object")
         throw new TypeError("timeout is required.");

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.ts";
-export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, MIN_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";

package/dist/index.js

@@ -6,7 +6,7 @@ import { extensionConfigDir } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
-export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, MIN_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;

package/docs/orchestration.md

@@ -146,6 +146,8 @@ Role Skill names resolve through Main's effective Pi Skill registry at launch. M
 
 Role launches made by `createRoleLaunch` reserve the final allowed turn for a response-only handoff. This includes `delegate_task` and every Implementer or Reviewer launch from `delegate_flow`. A raw `createEphemeralSubagentExecutor` launch does not guarantee a handoff.
 
+With `maxTurns` set to 1, Pi disables tools during `session_start`. The sole provider turn is the response-only handoff.
+
 After a continuing penultimate turn, Pi completes its tools. It then disables every active tool and queues one structured final handoff. The final allowed provider request has no tools. A terminal penultimate response gets no handoff.
 
 The handoff requests a fixed Markdown decision packet with Status (`completed`, `blocked`, or `incomplete`), one-sentence Outcome, up to three concrete Evidence facts, Blocker, one material Risk, and one Suggested next action. It is the default. Exact output required by the assigned task or Role takes precedence, and the child replies only with it. This preserves a Flow Reviewer's exact `PASS` and caller-required structured output. It reserves a turn inside the executor's existing hard limit. It never adds a model turn. A timeout, provider failure, or child-process failure can end a Role launch before handoff. Commits, validation, and retained-worktree facts from executor/Flow structured evidence remain authoritative; the model handoff supplies semantic context and a suggested next action.
@@ -183,7 +185,7 @@ const executorOptions = {
 };
 ```
 
-Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency` must be a safe integer >= 1. `maxTurns` must be a safe integer >= 10. `idleMs` and `maxMs` must be positive. `maxMs` must exceed `idleMs`. Omitted `maxTurns` defaults to 50.
+Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency` and `maxTurns` must be safe integers >= 1. `idleMs` and `maxMs` must be positive. `maxMs` must exceed `idleMs`. Omitted `maxTurns` defaults to 50.
 
 The executor is **active-Pi-only**. It reuses the currently running Pi invocation and does not locate or support a standalone Node.js Pi installation. Once direct Pi exits, stdout/stderr drain normally until EOF; an escaped descendant retaining either stream is cut off after short output inactivity or a one-second hard deadline so it cannot retain the FIFO permit.
 

package/extensions/config.ts

@@ -1,6 +1,5 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { createConfigStore, extensionConfigPath } from "@henryqw/pi-config-store";
-import { MIN_MAX_TURNS } from "@henryqw/pi-subagent";
 
 export interface SubagentTimeoutConfig {
 	/** Minutes a child may stay idle before it is asked to stop. */
@@ -62,10 +61,10 @@ function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfi
 
 	const maxTurns = record.maxTurns;
 	if (maxTurns !== undefined) {
-		if (typeof maxTurns === "number" && Number.isSafeInteger(maxTurns) && maxTurns >= MIN_MAX_TURNS) {
+		if (typeof maxTurns === "number" && Number.isSafeInteger(maxTurns) && maxTurns >= 1) {
 			config.maxTurns = maxTurns;
 		} else {
-			problems.push(`maxTurns must be a safe integer >= ${MIN_MAX_TURNS}, got ${JSON.stringify(maxTurns)}`);
+			problems.push(`maxTurns must be a safe integer >= 1, got ${JSON.stringify(maxTurns)}`);
 		}
 	}
 

package/extensions/delegate-flow.ts

@@ -65,6 +65,7 @@ type ChildSettlement =
 type UnitState = {
 	request: FlowUnitRequest;
 	modelClass: FlowModelClass;
+	widgetTaskId: string;
 	worktree: WorktreeInfo;
 	base: string;
 	implementation?: ChildSettlement;
@@ -125,12 +126,14 @@ export interface DelegateFlowRuntime {
 	resolveLaunch: (role: Role, modelClass: FlowModelClass, ctx: ExtensionContext) => ResolvedRoleLaunch;
 	startWidget: (
 		id: string,
+		taskId: string,
 		role: string,
 		model: string,
 		thinkingLevel: string | undefined,
 		name: string,
 		ctx: ExtensionContext,
 	) => void;
+	setWidgetTaskRetained: (taskId: string, retained: boolean) => void;
 	updateWidgetTokens: (id: string, tokens: number) => void;
 	updateWidgetActivity: (id: string, event: EphemeralSubagentActivityEvent) => void;
 	finishWidget: (id: string, status: WidgetStatus) => void;
@@ -262,6 +265,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		signal ? AbortSignal.any([signal, flow.sessionController.signal]) : flow.sessionController.signal;
 
 	const invalidateActive = (): void => {
+		if (active?.blocked) runtime.setWidgetTaskRetained(active.blocked.unit.widgetTaskId, false);
 		active?.sessionController.abort(new Error("Flow session ended."));
 		active = undefined;
 	};
@@ -346,6 +350,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		modelClass: FlowModelClass,
 		task: string,
 		widgetName: string,
+		widgetTaskId: string,
 		cwd: string,
 		widgetId: string,
 		signal: AbortSignal | undefined,
@@ -365,7 +370,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					if (launch.missingSkills.length) {
 						ctx.ui.notify(`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`, "warning");
 					}
-					runtime.startWidget(widgetId, role.name, launch.model.id, launch.thinkingLevel, widgetName, ctx);
+					runtime.startWidget(widgetId, widgetTaskId, role.name, launch.model.id, launch.thinkingLevel, widgetName, ctx);
 					started = true;
 					return { launch, task, cwd };
 				},
@@ -506,6 +511,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		diagnostic: string,
 		meter: UsageMeter,
 	) => {
+		if (flow.blocked) runtime.setWidgetTaskRetained(flow.blocked.unit.widgetTaskId, false);
 		if (active === flow) active = undefined;
 		return response(flow, "failed", meter, { classification, diagnostic: capOutput(diagnostic) });
 	};
@@ -521,6 +527,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		if (unit.repairUsed) return terminal(flow, classification, bounded, meter);
 		flow.phase = "blocked";
 		flow.blocked = { unit, classification, diagnostic: bounded };
+		runtime.setWidgetTaskRetained(unit.widgetTaskId, true);
 		return response(flow, "blocked", meter);
 	};
 
@@ -687,6 +694,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 						unit.modelClass,
 						reviewerTask(unit.request, reviewCriterion, { base: evidence.base, tip: evidence.tip, patchPath: evidence.patchPath }),
 						unit.request.name,
+						unit.widgetTaskId,
 						unit.worktree.cwd,
 						`${toolCallId}:flow:${flow.index}:review`,
 						signal,
@@ -820,6 +828,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					flow.units.push({
 						request: unit,
 						modelClass: unit.modelClass,
+						widgetTaskId: `${toolCallId}:flow:${index}`,
 						worktree,
 						base: worktree.baseCommit,
 						repairUsed: false,
@@ -839,6 +848,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					unit.modelClass,
 					implementerTask(unit.request),
 					unit.request.name,
+					unit.widgetTaskId,
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${index}:implement`,
 					operationSignal,
@@ -884,6 +894,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			const blocked = flow.blocked;
 			const unit = blocked.unit;
 			if (unit.repairUsed) throw new Error("delegate_flow_continue repair was already used for this Unit.");
+			runtime.setWidgetTaskRetained(unit.widgetTaskId, false);
 			flow.phase = "running";
 			flow.blocked = undefined;
 			unit.repairUsed = true;
@@ -901,6 +912,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					unit.modelClass,
 					repairTask(unit.request, blocked, guidance),
 					unit.request.name,
+					unit.widgetTaskId,
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${flow.index}:repair`,
 					operationSignal,

package/extensions/role-tools.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CHILD_EXCLUDED_TOOL_NAMES, EXECUTION_BUDGET_ENV, MIN_MAX_TURNS, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
+import { CHILD_EXCLUDED_TOOL_NAMES, EXECUTION_BUDGET_ENV, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
 
 const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
 const WARNING_RATIO = 0.8;
@@ -37,7 +37,7 @@ function executionBudget(value: string | undefined): { maxTurns: number; maxMs:
 	}
 	const budget = parsed as Record<string, unknown>;
 	if (Object.keys(budget).length !== 3 || !("maxTurns" in budget) || !("maxMs" in budget) || !("startedAt" in budget)
-		|| !Number.isSafeInteger(budget.maxTurns) || (budget.maxTurns as number) < MIN_MAX_TURNS
+		|| !Number.isSafeInteger(budget.maxTurns) || (budget.maxTurns as number) < 1
 		|| typeof budget.maxMs !== "number" || !Number.isFinite(budget.maxMs) || budget.maxMs <= 0
 		|| !Number.isSafeInteger(budget.startedAt) || (budget.startedAt as number) < 0) {
 		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
@@ -59,6 +59,7 @@ export default function roleTools(pi: ExtensionAPI): void {
 		type: "string",
 	});
 	const budget = executionBudget(process.env[EXECUTION_BUDGET_ENV]);
+	let handoffSent = false;
 	pi.on("session_start", () => {
 		const selected = configuredTools(pi.getFlag(ROLE_TOOL_POLICY_FLAG));
 		const allTools = pi.getAllTools();
@@ -72,12 +73,16 @@ export default function roleTools(pi: ExtensionAPI): void {
 		if (unavailable.length) {
 			throw new Error(`Subagent requested unavailable tools: ${unavailable.join(", ")}. Check spelling and load the provider extension that registers them.`);
 		}
+		if (budget?.maxTurns === 1 && !handoffSent) {
+			pi.setActiveTools([]);
+			pi.sendMessage(FINAL_HANDOFF_MESSAGE, { deliverAs: "steer", triggerTurn: false });
+			handoffSent = true;
+		}
 	});
 
 	if (!budget) return;
 	const warningTurn = Math.ceil(budget.maxTurns * WARNING_RATIO);
 	let completedTurns = 0;
-	let handoffSent = false;
 	let turnWarningSent = false;
 	let runtimeWarningSent = false;
 	pi.on("turn_end", (event) => {

package/extensions/subagent.ts

@@ -60,6 +60,7 @@ const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
 const MAX_WIDGET_ITEMS = 8;
 const MAX_WIDGET_LINES = 6;
+const MAX_WIDGET_GROUP_ROWS = 3;
 export const MAX_WIDGET_ACTIVE_TOOLS = 8;
 const DEFAULT_TIMEOUT_POLICY = {
 	idleMs: DEFAULT_TIMEOUT_CONFIG.idleMinutes * 60_000,
@@ -87,6 +88,7 @@ type WidgetItem = {
 	role: string;
 	model: string;
 	thinkingLevel: string;
+	taskId: string;
 	name: string;
 	tokens: number;
 	startedAt: number;
@@ -164,13 +166,35 @@ function renderWidgetRows(
 	theme: Theme,
 ): string[] {
 	const ordered = [...items.filter(({ status }) => status === "working"), ...items.filter(({ status }) => status !== "working")];
-	const visible = ordered.slice(0, ordered.length > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES);
-	if (!visible.length) return [];
-	const hidden = ordered.slice(visible.length);
-	const lines = visible.map((item) => truncateToWidth(
-		`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} ${theme.fg("text", item.name)} · ${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`,
-		width,
-	));
+	if (!ordered.length) return [];
+	const groups = new Map<string, { name: string; items: WidgetItem[] }>();
+	for (const item of ordered) {
+		const group = groups.get(item.taskId);
+		if (group) group.items.push(item);
+		else groups.set(item.taskId, { name: item.name, items: [item] });
+	}
+	const maxVisibleLines = ordered.length + groups.size > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES;
+	const workingGroups = [...groups.values()].filter(({ items }) => items.some(({ status }) => status === "working"));
+	const visibleWorkingGroups = new Set(workingGroups.slice(0, Math.floor(maxVisibleLines / 2)));
+	let remainingWorkingGroups = visibleWorkingGroups.size;
+	const visible = new Set<WidgetItem>();
+	const lines: string[] = [];
+	for (const group of groups.values()) {
+		const working = group.items.some(({ status }) => status === "working");
+		if (working && !visibleWorkingGroups.has(group)) continue;
+		const reservedLines = working ? --remainingWorkingGroups * 2 : 0;
+		const childCount = Math.min(MAX_WIDGET_GROUP_ROWS, group.items.length, maxVisibleLines - lines.length - reservedLines - 1);
+		if (childCount < 1) continue;
+		lines.push(truncateToWidth(theme.fg("text", group.name), width));
+		for (const item of group.items.slice(0, childCount)) {
+			visible.add(item);
+			lines.push(truncateToWidth(
+				`  ${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} ${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`,
+				width,
+			));
+		}
+	}
+	const hidden = ordered.filter((item) => !visible.has(item));
 	if (hidden.length) {
 		const counts: Record<WidgetStatus, number> = { working: 0, success: 0, failure: 0, aborted: 0 };
 		for (const { status } of hidden) counts[status] += 1;
@@ -250,6 +274,7 @@ export default function subagentExtension(
 		].join("\n"), outputPad, 0);
 	});
 	const widgetItems = new Map<string, WidgetItem>();
+	const retainedWidgetTaskIds = new Set<string>();
 	// Each child is a full Pi process issuing its own model calls; cap parallel
 	// spend. Precedence: PI_SUBAGENT_MAX_SUBAGENTS env > config/pi-subagent/config.json
 	// maxSubagents > default 5. Invalid present config falls back to the default
@@ -301,6 +326,11 @@ export default function subagentExtension(
 
 	const requestWidgetRender = () => activeTui?.requestRender();
 
+	const setWidgetTaskRetained = (taskId: string, retained: boolean) => {
+		if (retained) retainedWidgetTaskIds.add(taskId);
+		else retainedWidgetTaskIds.delete(taskId);
+	};
+
 	const startWidgetTimer = () => {
 		if (widgetTimer) return;
 		widgetTimer = setInterval(() => {
@@ -324,6 +354,7 @@ export default function subagentExtension(
 
 	const startWidgetItem = (
 		id: string,
+		taskId: string,
 		role: string,
 		model: string,
 		thinkingLevel: string | undefined,
@@ -334,15 +365,23 @@ export default function subagentExtension(
 		ensureWidget(ctx);
 		if (!widgetItems.has(id) && widgetItems.size >= MAX_WIDGET_ITEMS) {
 			for (const [oldestId, item] of widgetItems) {
-				if (item.status === "working") continue;
+				if (item.status === "working" || retainedWidgetTaskIds.has(item.taskId) || item.taskId === taskId) continue;
 				widgetItems.delete(oldestId);
 				if (widgetItems.size < MAX_WIDGET_ITEMS) break;
 			}
+			if (widgetItems.size >= MAX_WIDGET_ITEMS) {
+				for (const [oldestId, item] of widgetItems) {
+					if (item.status === "working" || retainedWidgetTaskIds.has(item.taskId)) continue;
+					widgetItems.delete(oldestId);
+					if (widgetItems.size < MAX_WIDGET_ITEMS) break;
+				}
+			}
 		}
 		widgetItems.set(id, {
 			role: roleBadge(role),
 			model,
 			thinkingLevel: thinkingLevel ?? "default",
+			taskId,
 			name,
 			tokens: 0,
 			startedAt: Date.now(),
@@ -434,6 +473,7 @@ export default function subagentExtension(
 		failedToolPatches.clear();
 		stopWidgetTimer();
 		widgetItems.clear();
+		retainedWidgetTaskIds.clear();
 		activeTui = undefined;
 		widgetInstalled = false;
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
@@ -451,7 +491,7 @@ export default function subagentExtension(
 	pi.on("input", (event) => {
 		if (event.source === "extension") return;
 		for (const [id, item] of widgetItems) {
-			if (item.status !== "working") widgetItems.delete(id);
+			if (item.status !== "working" && !retainedWidgetTaskIds.has(item.taskId)) widgetItems.delete(id);
 		}
 		requestWidgetRender();
 	});
@@ -550,6 +590,7 @@ export default function subagentExtension(
 			...(modelClass === undefined ? {} : { modelClass }),
 		}),
 		startWidget: startWidgetItem,
+		setWidgetTaskRetained,
 		updateWidgetTokens,
 		updateWidgetActivity,
 		finishWidget: finishWidgetItem,
@@ -695,7 +736,7 @@ export default function subagentExtension(
 								if (role.isolation === "worktree") {
 									worktree = await createChildWorktree(ctx.cwd, entry.id, undefined, workflowSignal);
 								}
-								startWidgetItem(entry.id, role.name, launch.model.id, launch.thinkingLevel, entry.delegation.name, ctx);
+								startWidgetItem(entry.id, entry.id, role.name, launch.model.id, launch.thinkingLevel, entry.delegation.name, ctx);
 								setState("running", "");
 								emitUpdate(emitToolUpdates);
 								return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "14.0.1",
+  "version": "15.0.1",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",