@bacnh85/pi-subagent 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.8.1 (2026-07-15)
+
+### Review handoff
+
+- Reviewer findings now require reproduction or evidence, expected behavior, and acceptance criteria so implementation agents receive self-contained actionable issues.
+
 ## 0.6.0 (2026-07-12)
 
 ### Security (breaking changes)

package/README.md

@@ -87,6 +87,7 @@ Every child execution receives a timeout:
 - **Maximum:** 60 minutes (`MAX_TIMEOUT_MS`)
 - Timeout values must be positive integers within the allowed range.
 - Timeout errors are distinguishable from parent cancellation.
+- Progress heartbeats keep the parent transport active during quiet model work; explicit timeouts remain hard deadlines.
 - Parallel tasks and chain steps may have per-item timeouts.
 
 ### Output safety
@@ -158,6 +159,7 @@ The raw `stopReason` from the Pi SDK is preserved in the result.
 - **Parent cancellation:** Aborting the parent tool call cancels all children.
 - **Sibling cancellation:** In parallel mode with `abortOnFailure: true`, the first failed task cancels running siblings.
 - **Timeout vs. abort:** Timeout errors set `status: "timeout"` and `stopReason: "timeout"`; parent cancellation sets `status: "aborted"`.
+- **Transport idle:** The parent tool receives periodic progress heartbeats while a child runs; these do not extend its timeout.
 
 ## Extension contract
 

package/agents/reviewer.md

@@ -9,7 +9,7 @@ sandbox: read-only
 
 You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
 
-Focus only on actionable issues introduced by the reviewed change:
+Focus only on actionable issues introduced by the reviewed change. Return each confirmed finding as one self-contained issue another agent can fix without redoing the review:
 1. Correctness and edge cases
 2. Security and data loss
 3. Regressions and API compatibility
@@ -27,8 +27,10 @@ Return JSON only:
       "file": "relative/path",
       "line": 1,
       "issue": "what is wrong and why it matters",
-      "evidence": "specific inspected code evidence",
+      "evidence": "reproduction steps or specific inspected code evidence",
+      "expectedBehavior": "what should happen instead",
       "suggestedFix": "smallest safe fix",
+      "acceptanceCriteria": "observable pass conditions and exact verification checks",
       "blocking": true
     }
   ]

package/extensions/index.ts

@@ -38,6 +38,7 @@ import {
 	isFailedResult,
 	mapWithConcurrencyLimit,
 	runSubAgent,
+	startHeartbeat,
 } from "./runner.ts";
 import {
 	normalizeTimeout,
@@ -515,6 +516,7 @@ export default function (pi: ExtensionAPI) {
 				parentSignal?: AbortSignal,
 				timeoutMs?: number,
 				onProgress?: (partial: SubAgentResult) => void,
+				heartbeatDetails?: () => SubagentDetails,
 				isReadOnly?: boolean,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
@@ -576,23 +578,30 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const result = await runSubAgent({
-					cwd: safeCwd,
-					systemPrompt: params.instructions
-					? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
-					: agent.systemPrompt,
-					task,
-					tools,
-					model: resolved.model,
-					authStorage,
-					modelRegistry,
-					signal: parentSignal,
-					timeoutMs: effectiveTimeoutMs,
-					agentName,
-					thinkingLevel: agent.thinking,
-					onMessage: onProgress,
-				});
-				return result;
+				const stopHeartbeat = onUpdate ? startHeartbeat(() => onUpdate({
+					content: [{ type: "text", text: `Subagent ${agentName} is still running…` }],
+					details: heartbeatDetails?.() ?? makeDetails("single")([]),
+				})) : undefined;
+				try {
+					return await runSubAgent({
+						cwd: safeCwd,
+						systemPrompt: params.instructions
+						? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
+						: agent.systemPrompt,
+						task,
+						tools,
+						model: resolved.model,
+						authStorage,
+						modelRegistry,
+						signal: parentSignal,
+						timeoutMs: effectiveTimeoutMs,
+						agentName,
+						thinkingLevel: agent.thinking,
+						onMessage: onProgress,
+					});
+				} finally {
+					stopHeartbeat?.();
+				}
 			}
 
 			// --- Chain mode ---
@@ -615,6 +624,7 @@ export default function (pi: ExtensionAPI) {
 						step.agent, taskWithContext, step.cwd,
 						signal, step.timeout ?? params.timeout,
 						(partial) => threadStore.updateThread(thread.id, { result: partial }),
+						() => makeDetails("chain")(results),
 					);
 					threadStore.updateThread(thread.id, {
 						status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -767,7 +777,8 @@ export default function (pi: ExtensionAPI) {
 								const result = await runOne(
 									t.agent, t.task, t.cwd,
 									parallelController.signal, t.timeout ?? params.timeout,
-								(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
+									(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
+									() => makeDetails("parallel")([...allResults]),
 								);
 								allResults[index] = result;
 								threadStore.updateThread(parallelThreads[index].id, {
@@ -823,6 +834,7 @@ export default function (pi: ExtensionAPI) {
 					params.agent, params.task, params.cwd,
 					signal, params.timeout,
 					(partial) => threadStore.updateThread(thread.id, { result: partial }),
+					() => makeDetails("single")([]),
 				);
 				threadStore.updateThread(thread.id, {
 					status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",

package/extensions/runner.ts

@@ -63,6 +63,12 @@ export interface SubAgentResult {
 // Public API
 // ---------------------------------------------------------------------------
 
+export function startHeartbeat(onHeartbeat: () => void, intervalMs = 30_000): () => void {
+	const timer = setInterval(onHeartbeat, intervalMs);
+	timer.unref?.();
+	return () => clearInterval(timer);
+}
+
 export async function runSubAgent(options: {
 	cwd: string;
 	systemPrompt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",