@bacnh85/pi-subagent 0.7.1 → 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/agents.ts

@@ -48,6 +48,7 @@ interface AgentCache {
 	scope: AgentScope;
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	diagnostics: AgentDiscoveryDiagnostic[];
 	/** File-level signature per directory (name:mtime:size for each .md file) */
 	dirSignatures: Map<string, string>;
 }
@@ -104,7 +105,22 @@ function loadAgentsFromDir(
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+
+
+		let frontmatter: Record<string, unknown>;
+		let body: string;
+		try {
+			const parsed = parseFrontmatter<Record<string, unknown>>(content);
+			frontmatter = parsed.frontmatter;
+			body = parsed.body;
+		} catch (err) {
+			diagnostics.push({
+				filePath,
+				issue: `Failed to parse YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+				severity: "error",
+			});
+			continue;
+		}
 
 		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
 			if (typeof frontmatter.name !== "string" && typeof frontmatter.description !== "string") {
@@ -225,8 +241,12 @@ function dirSignature(dir: string): string {
 			.filter((e) => e.name.endsWith(".md") && (e.isFile() || e.isSymbolicLink()))
 			.map((e) => {
 				const file = path.join(dir, e.name);
-				const st = fs.statSync(file);
-				return `${e.name}:${st.mtimeMs}:${st.size}`;
+				try {
+					const st = fs.statSync(file);
+					return `${e.name}:${st.mtimeMs}:${st.size}`;
+				} catch {
+					return `${e.name}:broken`;
+				}
 			})
 			.sort();
 		return `exists:${entries.join("|")}`;
@@ -277,7 +297,7 @@ export function discoverAgents(
 			}
 		}
 		if (!stale) {
-			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: [] };
+			return { agents: _cache.agents, projectAgentsDir: _cache.projectAgentsDir, diagnostics: _cache.diagnostics };
 		}
 		// Cache is stale — rebuild below
 		_cache = null;
@@ -316,6 +336,7 @@ export function discoverAgents(
 		scope,
 		agents,
 		projectAgentsDir,
+		diagnostics,
 		dirSignatures,
 	};
 

package/extensions/index.ts

@@ -38,6 +38,7 @@ import {
 	isFailedResult,
 	mapWithConcurrencyLimit,
 	runSubAgent,
+	startHeartbeat,
 } from "./runner.ts";
 import {
 	normalizeTimeout,
@@ -209,11 +210,15 @@ export default function (pi: ExtensionAPI) {
 				status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
 				result,
 			});
-			if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
-			else request.respond({ id: request.id, ok: true, result });
+			try {
+				if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
+				else request.respond({ id: request.id, ok: true, result });
+			} catch { /* respond channel closed */ }
 		}, (error) => {
 			threadStore.updateThread(thread.id, { status: "failed" });
-			request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+			try {
+				request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+			} catch { /* respond channel closed */ }
 		});
 	});
 
@@ -230,9 +235,12 @@ export default function (pi: ExtensionAPI) {
 				const list = formatAgentList(fresh.agents, 20);
 				const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 				const dirs = fresh.projectAgentsDir ? `project: ${fresh.projectAgentsDir}` : "no project agents dir";
+				const diagText = fresh.diagnostics.length > 0
+					? "\n\nWarnings:\n" + fresh.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+					: "";
 				pi.sendMessage({
 					customType: "pi-subagent",
-					content: `Agent definitions reloaded.\n\nAvailable agents (${fresh.agents.length}):\n  ${list.text}${extra}\n\nDirectories searched:\n  user: ${path.join(getAgentDir(), "agents")}\n  ${dirs}\n  bundled: ${bundledAgentsDir}`,
+					content: `Agent definitions reloaded.\n\nAvailable agents (${fresh.agents.length}):\n  ${list.text}${extra}${diagText}\n\nDirectories searched:\n  user: ${path.join(getAgentDir(), "agents")}\n  ${dirs}\n  bundled: ${bundledAgentsDir}`,
 					display: true,
 				});
 				ctx.ui.notify("Agent definitions reloaded", "info");
@@ -244,9 +252,12 @@ export default function (pi: ExtensionAPI) {
 				const list = formatAgentList(discovery.agents, 20);
 				const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 				const dirs = discovery.projectAgentsDir ? `\n  project: ${discovery.projectAgentsDir}` : "";
+				const diagText = discovery.diagnostics.length > 0
+					? "\n\nWarnings:\n" + discovery.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+					: "";
 				pi.sendMessage({
 					customType: "pi-subagent",
-					content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
+					content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}${diagText}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
 					display: true,
 				});
 				return;
@@ -283,9 +294,12 @@ export default function (pi: ExtensionAPI) {
 			const list = formatAgentList(discovery.agents, 20);
 			const extra = list.remaining > 0 ? `\n  ... +${list.remaining} more` : "";
 			const dirs = discovery.projectAgentsDir ? `\n  project: ${discovery.projectAgentsDir}` : "";
+			const diagText = discovery.diagnostics.length > 0
+				? "\n\nWarnings:\n" + discovery.diagnostics.map(d => `  - [${d.severity}] ${d.filePath}: ${d.issue}`).join("\n")
+				: "";
 			pi.sendMessage({
 				customType: "pi-subagent",
-				content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
+				content: `Available agents (${discovery.agents.length}):\n  ${list.text}${extra}${diagText}\n\nScopes searched:\n  user: ${path.join(getAgentDir(), "agents")}${dirs}\n  bundled: ${bundledAgentsDir}\n\nUse /subagent <name> for agent details, /subagent reload to refresh.`,
 				display: true,
 			});
 		},
@@ -502,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);
@@ -512,6 +527,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Unknown agent: "${agentName}". Available: ${available}.`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -527,6 +544,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Model not found for agent "${agentName}". Tried: ${tried}. Parent model: ${parentInfo}. Check agent definition and pi model configuration.`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -550,6 +569,8 @@ export default function (pi: ExtensionAPI) {
 						agent: agentName,
 						task,
 						exitCode: 1,
+						status: "error",
+						stopReason: "error",
 						messages: [],
 						stderr: `Validation error: ${errorMsg}`,
 						usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -557,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 ---
@@ -583,7 +611,7 @@ export default function (pi: ExtensionAPI) {
 
 				for (let i = 0; i < params.chain.length; i++) {
 					const step = params.chain[i];
-					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
+					const taskWithContext = step.task.replace(/\{previous\}/g, () => previousOutput);
 
 					const thread = threadStore.createThread({
 						agentName: step.agent,
@@ -596,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",
@@ -725,6 +754,7 @@ export default function (pi: ExtensionAPI) {
 										agent: t.agent,
 										task: t.task,
 										exitCode: 1,
+										status: "error",
 										messages: [],
 										stderr: "",
 										usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -747,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, {
@@ -803,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;
@@ -148,6 +154,8 @@ export async function runSubAgent(options: {
 			result.stopReason = isTimeout ? "timeout" : "aborted";
 			result.errorMessage = combinedSignal.reason instanceof Error ? combinedSignal.reason.message : "Sub-agent aborted before start";
 			result.status = classifyStopReason(result.stopReason, !isTimeout, isTimeout);
+			cleanupCombined?.();
+			if (timeoutId) clearTimeout(timeoutId);
 			return result;
 		}
 
@@ -167,6 +175,7 @@ export async function runSubAgent(options: {
 		let cleanupEventAbort: (() => void) | undefined;
 		let abortedBySignal = false;
 		let timedOut = false;
+		let eventUnsubscribe: (() => void) | undefined;
 
 		try {
 			// Wire combined abort signal to session
@@ -191,7 +200,8 @@ export async function runSubAgent(options: {
 					fn();
 				};
 
-				const unsubscribe = session.subscribe((event) => {
+				let unsubscribe: (() => void) | undefined;
+				unsubscribe = session.subscribe((event) => {
 					try {
 						switch (event.type) {
 							case "message_end": {
@@ -223,7 +233,7 @@ export async function runSubAgent(options: {
 									result.messages = event.messages as unknown as Message[];
 								}
 								finish(() => {
-									unsubscribe();
+									unsubscribe?.();
 									resolve();
 								});
 								break;
@@ -231,18 +241,19 @@ export async function runSubAgent(options: {
 						}
 					} catch (err) {
 						finish(() => {
-							unsubscribe();
+							unsubscribe?.();
 							reject(err);
 						});
 					}
 				});
+				eventUnsubscribe = unsubscribe;
 
 				// Resolve on abort so the eventPromise doesn't hang
 				const onAbortResolve = () => {
 					finish(() => {
 						result.exitCode = 1;
 						if (!result.errorMessage) result.errorMessage = "Sub-agent aborted";
-						unsubscribe();
+						unsubscribe?.();
 						resolve();
 					});
 				};
@@ -279,6 +290,7 @@ export async function runSubAgent(options: {
 			cleanupAbort?.();
 			cleanupEventAbort?.();
 			cleanupCombined();
+			eventUnsubscribe?.();
 			if (timeoutId) clearTimeout(timeoutId);
 			try {
 				session.dispose();

package/extensions/service.ts

@@ -7,6 +7,7 @@ import {
 	normalizeTimeout,
 	resolveSafeCwd,
 	MAX_INSTRUCTIONS_LENGTH,
+	READ_ONLY_TOOLS,
 } from "./security.ts";
 
 export const SUBAGENT_REQUEST_EVENT = "pi-subagent:run";
@@ -53,8 +54,13 @@ export async function runNamedAgent(options: {
 	const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
 
 	// Security: validate tools against allowlist.
-	const rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
-	const toolValidation = validateAgentTools({ tools: rawTools });
+	let rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+	// Enforce read-only sandbox: strip mutating and execution tools
+	if (options.agent.sandbox === "read-only") {
+		rawTools = rawTools.filter(t => READ_ONLY_TOOLS.includes(t));
+		if (rawTools.length === 0) rawTools = [...READ_ONLY_TOOLS];
+	}
+	const toolValidation = validateAgentTools({ tools: rawTools, readOnly: options.agent.sandbox === "read-only" });
 	if (toolValidation.errors.length > 0) {
 		throw new Error(`Tool validation errors for agent "${options.agent.name}": ${toolValidation.errors.join("; ")}`);
 	}

package/extensions/thread-viewer.ts

@@ -226,6 +226,7 @@ export class ThreadViewer {
 				? Math.max(0, total - (maxVisible - 1))
 				: 0;
 		const offset = Math.max(0, Math.min(this.scrollOffset, maxOffset));
+		this.scrollOffset = offset;
 
 		// Reserve space for scroll indicators
 		const aboveShown = offset > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.7.1",
+  "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",