@henryqw/pi-subagent 5.0.0 → 6.1.0

package/extensions/subagent.ts

@@ -1,6 +1,7 @@
+import { basename } from "node:path";
 import type { Usage } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, type TUI, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { type Component, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	availableTaskModels,
 	type ThinkingLevel,
@@ -21,6 +22,7 @@ import {
 	loadRoles,
 	resolveTaskRoute,
 	worktreeContextNote,
+	type EphemeralSubagentActivityEvent,
 	type EphemeralSubagentResult,
 	type EphemeralSubagentTimeout,
 	type Role,
@@ -29,6 +31,7 @@ import {
 } from "@henryqw/pi-subagent";
 import { DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
 import { registerDelegateFlow } from "./delegate-flow.ts";
+import { renderToolLines } from "./tool-render.ts";
 import { runDelegation } from "./delegation.ts";
 import {
 	formatBackgroundWorkflowResult,
@@ -55,6 +58,7 @@ const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
 const MAX_WIDGET_ROWS = 8;
+export const MAX_WIDGET_ACTIVE_TOOLS = 8;
 const DEFAULT_TIMEOUT_POLICY = {
 	idleMs: DEFAULT_TIMEOUT_CONFIG.idleMinutes * 60_000,
 	maxMs: DEFAULT_TIMEOUT_CONFIG.maxMinutes * 60_000,
@@ -71,6 +75,12 @@ export function resolveTimeoutPolicy(partial: SubagentTimeoutConfig | undefined)
 	};
 }
 type WidgetStatus = "working" | "success" | "failure" | "aborted";
+type WidgetActiveTool = {
+	toolName: string;
+	path?: string;
+	startedAt: number;
+	order: number;
+};
 type WidgetItem = {
 	role: string;
 	model: string;
@@ -80,6 +90,11 @@ type WidgetItem = {
 	startedAt: number;
 	status: WidgetStatus;
 	finishedAt?: number;
+	completedAssistantTurns: number;
+	startedToolCount: number;
+	activeTools: Map<string, WidgetActiveTool>;
+	activeToolId?: string;
+	activityOrder: number;
 };
 
 function taskSummary(task: string): string {
@@ -111,6 +126,34 @@ function statusLabel(status: WidgetStatus): string {
 	}
 }
 
+function activityLabel(item: WidgetItem, now: number): string {
+	if (item.status === "success") return "Done";
+	if (item.status === "failure") return "Failed";
+	if (item.status === "aborted") return "Stopped";
+	const activeTool = item.activeToolId === undefined ? undefined : item.activeTools.get(item.activeToolId);
+	if (!activeTool) return "thinking…";
+	return [
+		activeTool.toolName,
+		formatDuration(now - activeTool.startedAt),
+		...(activeTool.path === undefined ? [] : [activeTool.path]),
+	].join(" · ");
+}
+
+function activityMetrics(item: WidgetItem, now: number): string {
+	return [
+		...(item.completedAssistantTurns === 0
+			? []
+			: [`${item.completedAssistantTurns} turn${item.completedAssistantTurns === 1 ? "" : "s"}`]),
+		...(item.startedToolCount === 0
+			? []
+			: [`${item.startedToolCount} tool${item.startedToolCount === 1 ? "" : "s"}`]),
+		item.model,
+		item.thinkingLevel,
+		`${formatTokens(item.tokens)} tok`,
+		formatDuration((item.finishedAt ?? now) - item.startedAt),
+	].join(" · ");
+}
+
 function isWorkflowTransportDetails(value: unknown): value is WorkflowTransportDetails {
 	const isRecord = (candidate: unknown): candidate is Record<string, unknown> => typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 	const isOptionalString = (candidate: unknown) => candidate === undefined || typeof candidate === "string";
@@ -134,18 +177,34 @@ function isWorkflowTransportDetails(value: unknown): value is WorkflowTransportD
 		&& entries.every((entry, index) => index === 0 || (entry as { index: number }).index > (entries[index - 1] as { index: number }).index);
 }
 
-function renderWorkflowResult(details: WorkflowTransportDetails, width: number, theme: Theme): string[] {
+function workflowCallLabel(args: { tasks?: unknown; chain?: unknown }): string {
+	if (Array.isArray(args.chain)) return `delegate_task · working: chain · ${args.chain.length} task${args.chain.length === 1 ? "" : "s"}`;
+	if (Array.isArray(args.tasks)) return `delegate_task · working: parallel · ${args.tasks.length} task${args.tasks.length === 1 ? "" : "s"}`;
+	return "delegate_task · working: single · 1 task";
+}
+
+function workflowResultLines(details: WorkflowTransportDetails, theme: Theme): string[] {
 	if (details.entries.some(({ status }) => status === "pending" || status === "running")) return [];
-	return details.entries.flatMap((entry) => {
-		if (entry.status === "skipped") return [];
+	const entries = details.entries.filter(({ status }) => status !== "skipped");
+	const withRecovery = (entry: typeof entries[0]) => entry.worktree && !entry.worktree.pruned;
+	const isTerminalFailure = (entry: typeof entries[0]) => entry.status === "failed" || entry.status === "rejected";
+	const sorted = [...entries].sort((a, b) => {
+		const aFailure = isTerminalFailure(a);
+		const bFailure = isTerminalFailure(b);
+		if (aFailure !== bFailure) return aFailure ? -1 : 1;
+		const aRecovery = !aFailure && withRecovery(a);
+		const bRecovery = !bFailure && withRecovery(b);
+		if (aRecovery !== bRecovery) return aRecovery ? -1 : 1;
+		return 0;
+	});
+	return sorted.map((entry) => {
 		const summary = entry.summary || "(no output)";
 		const text = details.mode === "single" ? summary : `${entry.role}: ${summary}`;
 		const style = entry.status === "failed" || entry.status === "rejected" ? "error" : "text";
-		const recovery = entry.worktree && !entry.worktree.pruned ? `Recovery: ${entry.worktree.path}` : undefined;
-		return [
-			...wrapTextWithAnsi(theme.fg(style, text), Math.max(1, width)),
-			...(recovery ? wrapTextWithAnsi(theme.fg("warning", recovery), Math.max(1, width)) : []),
-		];
+		const recovery = withRecovery(entry) ? `Recovery: ${entry.worktree!.path}` : undefined;
+		return recovery === undefined
+			? theme.fg(style, text)
+			: `${theme.fg("warning", recovery)} · ${theme.fg(style, text)}`;
 	});
 }
 
@@ -159,13 +218,15 @@ function renderWidgetRows(
 	const visible = items.slice(0, MAX_WIDGET_ROWS);
 	if (!visible.length) return [];
 	const indent = " ".repeat(Math.min(2, Math.max(0, width - 1)));
-	const contentWidth = Math.max(1, width - indent.length);
+	const contentWidth = Math.max(0, width - indent.length);
 	const lines = visible.flatMap((item) => [
-		...wrapTextWithAnsi(`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} · ${statusLabel(item.status)}`, Math.max(1, width)),
-		...wrapTextWithAnsi(theme.fg("text", item.task), contentWidth).map((line) => `${indent}${line}`),
-		...wrapTextWithAnsi(theme.fg("muted", `${item.model} · ${item.thinkingLevel} · ${formatTokens(item.tokens)} tok · ${formatDuration((item.finishedAt ?? now) - item.startedAt)}`), contentWidth).map((line) => `${indent}${line}`),
+		truncateToWidth(
+			`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} · ${statusLabel(item.status)} · ${theme.fg("text", item.task)}`,
+			width,
+		),
+		`${indent}${truncateToWidth(`${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`, contentWidth)}`,
 	]);
-	if (items.length > visible.length) lines.push(...wrapTextWithAnsi(theme.fg("muted", `… ${items.length - visible.length} more`), Math.max(1, width)));
+	if (items.length > visible.length) lines.push(truncateToWidth(theme.fg("muted", `… ${items.length - visible.length} more`), width));
 	return lines;
 }
 
@@ -311,6 +372,10 @@ export default function subagentExtension(
 			tokens: 0,
 			startedAt: Date.now(),
 			status: "working",
+			completedAssistantTurns: 0,
+			startedToolCount: 0,
+			activeTools: new Map(),
+			activityOrder: 0,
 		});
 		startWidgetTimer();
 		requestWidgetRender();
@@ -323,11 +388,55 @@ export default function subagentExtension(
 		requestWidgetRender();
 	};
 
+	const updateWidgetActivity = (id: string, event: EphemeralSubagentActivityEvent) => {
+		const item = widgetItems.get(id);
+		if (!item || item.status !== "working") return;
+		switch (event.type) {
+			case "tool_execution_start": {
+				if (item.activeTools.has(event.toolCallId)) break;
+				if (item.activeTools.size >= MAX_WIDGET_ACTIVE_TOOLS) {
+					let oldest: [string, WidgetActiveTool] | undefined;
+					for (const candidate of item.activeTools) {
+						if (!oldest || candidate[1].order < oldest[1].order) oldest = candidate;
+					}
+					if (oldest) item.activeTools.delete(oldest[0]);
+				}
+				const path = event.path === undefined ? undefined : basename(event.path);
+				item.startedToolCount += 1;
+				item.activeTools.set(event.toolCallId, {
+					toolName: event.toolName,
+					...(path ? { path } : {}),
+					startedAt: Date.now(),
+					order: ++item.activityOrder,
+				});
+				item.activeToolId = event.toolCallId;
+				break;
+			}
+			case "tool_execution_end": {
+				item.activeTools.delete(event.toolCallId);
+				if (item.activeToolId === event.toolCallId) {
+					let latest: [string, WidgetActiveTool] | undefined;
+					for (const candidate of item.activeTools) {
+						if (!latest || candidate[1].order > latest[1].order) latest = candidate;
+					}
+					item.activeToolId = latest?.[0];
+				}
+				break;
+			}
+			case "message_end":
+				item.completedAssistantTurns += 1;
+				break;
+		}
+		requestWidgetRender();
+	};
+
 	const finishWidgetItem = (id: string, status: Exclude<WidgetStatus, "working">) => {
 		const item = widgetItems.get(id);
 		if (!item) return;
 		item.status = status;
 		item.finishedAt = Date.now();
+		item.activeTools.clear();
+		item.activeToolId = undefined;
 		if (![...widgetItems.values()].some(({ status }) => status === "working")) stopWidgetTimer();
 		requestWidgetRender();
 	};
@@ -443,15 +552,18 @@ export default function subagentExtension(
 		maxRuntimeMs: timeoutPolicy.maxMs,
 		getSessionGeneration: () => sessionEpoch,
 		loadRoles,
-		resolveLaunch: (role, ctx) => {
+		resolveLaunch: (role, modelClass, ctx) => {
 			const launchCtx = latestCtx ?? ctx;
 			return createRoleLaunch(pi, launchCtx, {
 				role,
-				route: resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK),
+				route: modelClass === undefined
+					? resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK)
+					: resolveTaskRoute(launchCtx, modelClass),
 			});
 		},
 		startWidget: startWidgetItem,
 		updateWidgetTokens,
+		updateWidgetActivity,
 		finishWidget: finishWidgetItem,
 	});
 
@@ -463,24 +575,24 @@ export default function subagentExtension(
 		promptGuidelines: [
 			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output.",
 			"Every delegate_task entry must state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; never pass the parent request unchanged.",
-			"For each delegate_task entry, use fav only when the user asks for their favorite model; otherwise choose fast for narrow work, balanced for normal work, and frontier only for ambiguous, cross-cutting, or high-risk work.",
+			"For each delegate_task entry, populate model and thinking only for an explicit user override; otherwise choose only modelClass: fast normally, or balanced upfront for obviously complex work. This is Main policy, not runtime enforcement.",
 			"Parallel delegate_task entries must own non-overlapping files. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.",
 			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",
 		],
 		parameters: WorkflowSchema,
-		renderResult(result, _options, theme, _context) {
+		renderShell: "self",
+		renderCall(args, theme, _context) {
+			return renderToolLines([theme.fg("toolTitle", workflowCallLabel(args))], theme);
+		},
+		renderResult(result, { isPartial }, theme, _context) {
+			if (isPartial) return renderToolLines([], theme);
 			const details = result.details;
-			if (isWorkflowTransportDetails(details)) {
-				return {
-					invalidate() {},
-					render: (width) => renderWorkflowResult(details, width, theme),
-				};
-			}
+			if (isWorkflowTransportDetails(details)) return renderToolLines(workflowResultLines(details, theme), theme);
 			if (typeof details === "object" && details !== null && (details as { background?: unknown }).background === true) {
-				return { invalidate() {}, render: (width) => wrapTextWithAnsi(theme.fg("muted", "Background workflow accepted."), Math.max(1, width)) };
+				return renderToolLines([theme.fg("muted", "Background workflow accepted.")], theme);
 			}
 			const text = result.content.find((part) => part.type === "text")?.text ?? "(no output)";
-			return { invalidate() {}, render: (width) => wrapTextWithAnsi(theme.fg("muted", text), Math.max(1, width)) };
+			return renderToolLines([theme.fg("muted", text)], theme);
 		},
 		prepareArguments(args) {
 			try {
@@ -591,6 +703,7 @@ export default function subagentExtension(
 								emitUpdate(emitToolUpdates);
 							},
 							onTokens: (tokens) => updateWidgetTokens(entry.id, tokens),
+							onActivity: (event) => updateWidgetActivity(entry.id, event),
 							prepare: async () => {
 								// Route and effective Role resources resolve only after this entry's
 								// shared executor permit, before isolated state is created.

package/extensions/tool-render.ts

@@ -0,0 +1,16 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+
+export const MAX_RENDERED_RESULT_LINES = 3;
+
+export function renderToolLines(lines: readonly string[], theme: Theme): Component {
+	return {
+		invalidate() {},
+		render: (width) => {
+			const shown = lines.length > MAX_RENDERED_RESULT_LINES
+				? [...lines.slice(0, MAX_RENDERED_RESULT_LINES - 1), theme.fg("muted", `… ${lines.length - MAX_RENDERED_RESULT_LINES + 1} more`)]
+				: lines;
+			return shown.map((line) => truncateToWidth(line.replace(/[\r\n]+/g, " "), width));
+		},
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "5.0.0",
+  "version": "6.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,6 +66,6 @@
   "dependencies": {
     "@henryqw/pi-herdr": "^0.4.0",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^1.0.0"
+    "@henryqw/pi-task-models": "^2.0.0"
   }
 }

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -5,28 +5,28 @@ description: Run bounded independent implementation through the runtime-managed
 
 # Delegated Development
 
-You are Main: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
+You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
 
 ## Slice
 
 Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute; combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Dependent work remains outside Flow, in one task or ordinary caller-controlled sequencing.
 
-Give every unit a bounded objective, owned scope and exclusions, acceptance criteria, and its direct validation command/argument array. Do not pass the parent request unchanged. Call `delegate_flow` with 1–8 units; the runtime supplies the effective Implementer and Reviewer Roles.
+Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array. Do not pass the parent request unchanged. Use `modelClass: "fast"` normally; use `"balanced"` upfront only for obviously complex work. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
 
 ## Runtime Flow
 
-The runtime owns the unit worktrees and all Git identity, rebasing, declared validation, exact read-only review, fast-forward integration, and cleanup. It records the clean committed Main state, runs independent Implementers in isolated unit worktrees, processes units in declared order, and integrates only the exact reviewed tip OID.
+The runtime owns the unit worktrees and all Git identity, rebasing, committed-state inspection, declared validation, conditional exact read-only review, fast-forward integration, and cleanup. Declared validation is the authority for objective verification. A validated unit without `review` skips review evidence and Reviewer launch, then integrates its exact validated tip. A unit with `review` receives the existing exact `{base, tip, patchPath}` protocol and must receive exactly `PASS` before integration.
 
 Trust the structured Flow outcome. Never edit a child worktree, manage its branches, prepare review evidence, reimplement Flow, or manually integrate its changes. Do not repeat Flow validation after it has completed or integrated a unit.
 
-A successful Flow owns integration and cleanup. A blocked outcome is repairable: provide one explicit continuation and no more:
+A successful Flow owns integration and cleanup. A blocked outcome is repairable once: provide one explicit continuation and no more:
 
 ```ts
-delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit." })
+delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit.", modelClass: "balanced" })
 ```
 
-Make the guidance specific to the reported implementation, validation, or review failure. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. A cleanup warning does not undo successful integration.
+Make the guidance specific to the reported implementation, validation, or review failure. Omit `modelClass` to retain the blocked unit's current class; supply it only to replace that one repair's class. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. A cleanup warning does not undo successful integration.
 
 ## Ordinary delegation
 
-Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Preserve ordinary Role selection and isolation behavior. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.
+Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Populate direct `model` and `thinking` only when the user explicitly asks for those overrides; otherwise choose only `modelClass` (`fast` normally, `balanced` upfront for obviously complex work). Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.