@rohaquinlop/pi-subagents 0.4.0 → 0.5.1

package/agents/worker.md

@@ -16,6 +16,7 @@ Guidelines:
 - Read files before editing to understand existing code
 - Make targeted edits, not wholesale rewrites
 - Use safe_bash for running commands (tests, builds, installs, etc.)
+- `safe_bash` has a 5-minute default timeout (300s). For long-running commands (builds, tests, installs), pass a larger `timeout`, e.g. `timeout: 600` for 10 minutes.
 - If something fails, diagnose and fix it
 - Report what you did and what changed when done
 

package/index.ts

@@ -17,6 +17,11 @@ import "./tools/safe-bash";
 import type { AgentConfig, AgentUsage, PipelineStepResult, PipelineResult, LoopIterationResult, LoopResult } from "./lib/types";
 import { discoverAgents, mergeAgents, substitutePlaceholders, formatConnectorContext } from "./lib/helpers";
 import { zeroUsage, accumulateUsage, validateAgents, MAX_LOOP_CONTEXT, parseJudgeVerdict } from "./lib/pipeline-helpers";
+import { buildSubagentErrorContent, buildPipelineErrorContent, buildLoopErrorContent } from "./lib/error-helpers";
+import { detectCycle } from "./lib/loop-detector";
+import { extractCycleSignature, LOOP_PRIOR_ITERATIONS_HEADER } from "./lib/cycle-signature";
+import { validateAgentGraphAcyclicity } from "./lib/agent-graph";
+import { checkDepth } from "./lib/depth-limit";
 
 interface ToolEvent {
 	tool: string;
@@ -55,6 +60,7 @@ interface AgentProgress {
 	durationMs: number;
 	lastMessage: string;
 	error?: string;
+	warning?: string;
 }
 
 interface AgentResult {
@@ -78,6 +84,9 @@ interface Details {
 
 interface ExtensionConfig {
 	maxConcurrency?: number;
+	subagentTimeoutMs?: number;      // wall-clock, default 600000 (10 min). 0 = disabled.
+	subagentIdleTimeoutMs?: number;  // no-stdout watchdog, default 300000 (5 min). 0 = disabled.
+	maxSubagentDepth?: number;       // max nesting depth, default 8. Hard backstop against recursion loops.
 }
 
 const EXT_DIR = path.dirname(new URL(import.meta.url).pathname);
@@ -85,6 +94,10 @@ const AGENTS_DIR = path.join(EXT_DIR, "agents");
 const TOOLS_DIR = path.join(EXT_DIR, "tools");
 const CONFIG_PATH = path.join(EXT_DIR, "config.json");
 const DEFAULT_MAX_CONCURRENCY = 4;
+const DEFAULT_SUBAGENT_TIMEOUT_MS = 600_000;     // 10 minutes
+const DEFAULT_SUBAGENT_IDLE_TIMEOUT_MS = 300_000; // 5 minutes
+
+let extensionConfig: ExtensionConfig = {};
 
 function loadConfig(): ExtensionConfig {
 	try {
@@ -370,6 +383,15 @@ async function buildPiArgs(
 	cwd: string,
 ): Promise<{ args: string[]; tempDir: string; childEnv: NodeJS.ProcessEnv }> {
 	const piBin = resolvePiBinary();
+
+	// Depth check (before resource allocation to avoid temp-dir leaks on throw)
+	const currentDepth = parseInt(process.env.PI_SUBAGENT_DEPTH || "0", 10);
+	const maxDepth = extensionConfig.maxSubagentDepth ?? 8;
+	const depthResult = checkDepth(currentDepth, maxDepth);
+	if (!depthResult.allowed) {
+		throw new Error(depthResult.error!);
+	}
+
 	const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-sub-"));
 
 	// Write system prompt to temp file
@@ -451,6 +473,8 @@ async function buildPiArgs(
 		childEnv.PI_SUBAGENT_ALLOWED = agent.subagentAgents.join(",");
 	}
 
+	childEnv.PI_SUBAGENT_DEPTH = String(depthResult.newDepth);
+
 	return { args: [piBin.command, ...args], tempDir, childEnv };
 }
 
@@ -479,6 +503,11 @@ function flatten(s: string): string {
 // doesn't need to read inline anyway.
 const MAX_ARG_PREVIEW = 4000;
 
+// Hard cap on recentTools entries to prevent unbounded memory growth in
+// long-running subagents. Generous for expanded-view history; matches the
+// callHistory trim pattern.
+const MAX_RECENT_TOOLS = 50;
+
 function extractToolArgsPreview(args: Record<string, unknown>): string {
 	const cap = (s: string) => (s.length > MAX_ARG_PREVIEW ? s.slice(0, MAX_ARG_PREVIEW) + "…" : s);
 	if (args.command) return cap(flatten(String(args.command)));
@@ -502,7 +531,7 @@ async function runSubagent(
 	task: string,
 	cwd: string,
 	signal: AbortSignal | undefined,
-	onUpdate?: (progress: AgentProgress, usage: AgentResult["usage"]) => void,
+	onUpdate?: (progress: AgentProgress, usage: AgentResult["usage"], finalExitCode?: number) => void,
 ): Promise<AgentResult> {
 	const { args, tempDir, childEnv } = await buildPiArgs(agent, task, cwd);
 	const command = args[0];
@@ -544,14 +573,80 @@ async function runSubagent(
 
 		let buf = "";
 		let stderrBuf = "";
+		let resolved = false;
+		let wallTimer: ReturnType<typeof setTimeout> | undefined;
+		let idleTimer: ReturnType<typeof setTimeout> | undefined;
+		let inFlightToolCount = 0;
+		let childClosed = false;
+		let sigkillTimer: ReturnType<typeof setTimeout> | undefined;
+		let callHistory: string[] = [];	// sliding window of tool-call signatures for cycle detection
+		// NOTE: Cycle detection is PER-CHILD — each runSubagent() call has its own
+		// fresh callHistory. Cross-step loops in pipeline (A→B→A→B) and cross-iteration
+		// re-delegation in loop are NOT caught by the tool-call detector. They are
+		// bounded instead by: pipeline's 2-5 step cap, loop's 2-5 iteration cap, the
+		// depth cap (default 8), and wall-clock (10 min) + idle (5 min) timeouts.
+		// This is a deliberate tradeoff — per-child detection avoids false positives
+		// from parallel siblings sharing history.
+
+		const safeResolve = (code: number) => {
+			if (resolved) return;
+			resolved = true;
+			clearTimeout(wallTimer);
+			clearTimeout(idleTimer);
+			clearTimeout(sigkillTimer);
+			if (signal) signal.removeEventListener("abort", abortKill);
+			resolve(code);
+		};
+
+		// Wall-clock timeout
+		const timeoutMs = extensionConfig.subagentTimeoutMs ?? DEFAULT_SUBAGENT_TIMEOUT_MS;
+		if (timeoutMs > 0) {
+			wallTimer = setTimeout(() => {
+				if (!progress.error) progress.error = `Subagent timed out after ${Math.round(timeoutMs / 1000)}s`;
+				proc.kill("SIGTERM");
+				clearTimeout(sigkillTimer);
+				sigkillTimer = setTimeout(() => {
+					if (!childClosed) proc.kill("SIGKILL");
+				}, 5000);
+			}, timeoutMs);
+		}
+
+		// Idle (no-stdout) watchdog
+		const idleMs = extensionConfig.subagentIdleTimeoutMs ?? DEFAULT_SUBAGENT_IDLE_TIMEOUT_MS;
+		const resetIdle = () => {
+			if (idleMs <= 0) return;
+			clearTimeout(idleTimer);
+			idleTimer = setTimeout(() => {
+				if (!progress.error) progress.error = `Subagent idle for ${Math.round(idleMs / 1000)}s — likely stuck`;
+				proc.kill("SIGTERM");
+				clearTimeout(sigkillTimer);
+				sigkillTimer = setTimeout(() => {
+					if (!childClosed) proc.kill("SIGKILL");
+				}, 5000);
+			}, idleMs);
+		};
+		resetIdle();
+
+		const pauseIdle = () => {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		};
+		const resumeIdle = () => {
+			if (inFlightToolCount === 0) resetIdle();
+		};
+
+		const MAX_STDERR_BYTES = 100_000;
 
 		const processLine = (line: string) => {
+			if (inFlightToolCount === 0) resetIdle();
 			if (!line.trim()) return;
 			try {
 				const evt = JSON.parse(line) as any;
 				progress.durationMs = Date.now() - startTime;
 
 				if (evt.type === "tool_execution_start") {
+					inFlightToolCount++;
+					pauseIdle();
 					progress.toolCount++;
 					progress.recentTools.push({
 						tool: evt.toolName,
@@ -559,6 +654,37 @@ async function runSubagent(
 						toolCallId: evt.toolCallId,
 						status: "running",
 					});
+					// Trim oldest completed entries, but never evict an in-flight tool —
+					// otherwise tool_execution_end's .find(toolCallId) would no-op and leave a
+					// permanently-"running" ghost.
+					while (progress.recentTools.length > MAX_RECENT_TOOLS) {
+						const idx = progress.recentTools.findIndex((t) => t.status !== "running");
+						if (idx === -1) break; // only running entries left — don't evict in-flight
+						progress.recentTools.splice(idx, 1);
+					}
+					// ── Cycle detection (parent-side, context-free) ──
+					// Signature = toolName + args preview. Two calls with different args
+					// (different file, or same file different content) → different sig.
+					const sig = extractCycleSignature(evt.toolName, (evt.args || {}) as Record<string, unknown>);
+					const cycleResult = detectCycle(callHistory, sig);
+					callHistory.push(sig);
+					if (callHistory.length > 24) callHistory = callHistory.slice(-24);
+
+					if (cycleResult.cycle) {
+						const toolNames = (cycleResult.pattern || []).map((s) => {
+							const colonIdx = s.indexOf(":");
+							return colonIdx >= 0 ? s.slice(0, colonIdx) : s;
+						});
+						const patternStr = toolNames.join("→");
+						if (!progress.error) {
+							progress.error = `Subagent stuck in a tool-call loop: repeating ${patternStr}`;
+						}
+						proc.kill("SIGTERM");
+						clearTimeout(sigkillTimer);
+						sigkillTimer = setTimeout(() => {
+							if (!childClosed) proc.kill("SIGKILL");
+						}, 5000);
+					}
 					fireUpdate();
 				}
 
@@ -593,6 +719,8 @@ async function runSubagent(
 							hit.children = finalChildren as AgentResult[];
 						}
 					}
+					inFlightToolCount = Math.max(0, inFlightToolCount - 1);
+					resumeIdle();
 					fireUpdate();
 				}
 
@@ -659,26 +787,37 @@ async function runSubagent(
 		});
 
 		proc.stderr.on("data", (d: Buffer) => {
+			if (stderrBuf.length >= MAX_STDERR_BYTES) return;
 			stderrBuf += d.toString();
+			if (stderrBuf.length >= MAX_STDERR_BYTES) {
+				stderrBuf = stderrBuf.slice(0, MAX_STDERR_BYTES) + "\n[stderr truncated]";
+			}
 		});
 
 		proc.on("close", (code) => {
+			childClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (code !== 0 && stderrBuf.trim() && !progress.error) {
 				progress.error = stderrBuf.trim();
+			} else if (code === 0 && stderrBuf.trim()) {
+				// Non-fatal: surface stderr (e.g. deprecation warnings) on a successful exit.
+				progress.warning = stderrBuf.trim().slice(0, 2000);
 			}
-			resolve(code ?? 1);
+			safeResolve(code ?? 1);
 		});
 
-		proc.on("error", () => resolve(1));
+		proc.on("error", () => safeResolve(1));
 
+		const abortKill = () => {
+			proc.kill("SIGTERM");
+			clearTimeout(sigkillTimer);
+			sigkillTimer = setTimeout(() => {
+				if (!childClosed) proc.kill("SIGKILL");
+			}, 3000);
+		};
 		if (signal) {
-			const kill = () => {
-				proc.kill("SIGTERM");
-				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
-			};
-			if (signal.aborted) kill();
-			else signal.addEventListener("abort", kill, { once: true });
+			if (signal.aborted) abortKill();
+			else signal.addEventListener("abort", abortKill, { once: true });
 		}
 	});
 
@@ -690,6 +829,13 @@ async function runSubagent(
 	result.exitCode = exitCode;
 	progress.status = exitCode === 0 && !progress.error ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;
+
+	// Push the terminal status to the live renderer so the TUI doesn't keep
+	// showing "running" after the child has exited. Pass exitCode so callers
+	// that hold a live result object (the subagent tool) can sync its exitCode
+	// and render the correct ✓/✗ icon instead of the -1 placeholder.
+	onUpdate?.(progress, result.usage, exitCode);
+
 	if (progress.error) result.output = result.output || `Error: ${progress.error}`;
 
 	// Truncate output if very large
@@ -900,6 +1046,10 @@ function renderAgentProgress(
 		addLine(theme.fg("error", `Error: ${prog.error}`));
 	}
 
+	if (prog.warning) {
+		addLine(theme.fg("warning", `Warning: ${prog.warning}`));
+	}
+
 	return c;
 }
 
@@ -959,10 +1109,13 @@ async function runPipeline(
 		totalUsage = accumulateUsage(totalUsage, result.usage);
 		previousOutput = result.output;
 
-		// Stop on error
+		// Stop on error — surface the failing step's error as finalOutput (the pipeline
+		// tool returns finalOutput as content, so the main LLM sees the actual failure,
+		// not the previous step's success text).
 		if (result.exitCode !== 0 || result.progress.error) {
+			const errorDetail = buildPipelineErrorContent(i, step.agent, result);
 			return {
-				steps: results, finalOutput: previousOutput,
+				steps: results, finalOutput: errorDetail,
 				stoppedAt: i, error: result.progress.error || `Agent ${step.agent} exited with code ${result.exitCode}`,
 				totalUsage, totalDurationMs: Date.now() - startTime,
 			};
@@ -1014,7 +1167,7 @@ async function runLoop(
 				}
 			}
 			const contextBlock = keptOutputs.join("\n\n");
-			fullTask = `${task}\n\n## Prior iterations:\n${contextBlock}`;
+			fullTask = `${task}\n\n${LOOP_PRIOR_ITERATIONS_HEADER}\n${contextBlock}`;
 		}
 
 		const iterStart = Date.now();
@@ -1062,8 +1215,9 @@ async function runLoop(
 
 		if (result.exitCode !== 0 || result.progress.error) {
 			stoppedBecause = "error";
+			const errorDetail = buildLoopErrorContent(i, agentName, result);
 			return {
-				iterations, finalOutput: result.output || "(error)",
+				iterations, finalOutput: errorDetail,
 				stoppedBecause, totalUsage, totalDurationMs: Date.now() - startTime,
 			};
 		}
@@ -1239,10 +1393,17 @@ function renderLoopResult(
 // ── Extension ─────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
-	const config = loadConfig();
-	semaphore = new Semaphore(config.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
+	extensionConfig = loadConfig();
+	semaphore = new Semaphore(extensionConfig.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
 	agents = loadAgents();
 
+	// Validate agent graph acyclicity (warning only — depth cap backstops recursion)
+	const cycleError = validateAgentGraphAcyclicity(agents);
+	if (cycleError) {
+		console.error(`[pi-subagents] WARNING: ${cycleError}`);
+		console.error(`[pi-subagents] The depth cap (maxSubagentDepth=${extensionConfig.maxSubagentDepth ?? 8}) prevents infinite recursion, but this agent configuration should be fixed.`);
+	}
+
 	// If spawned as a child by a parent subagent process, PI_SUBAGENT_ALLOWED
 	// pins which agents we're allowed to expose. Filter the registry now, before
 	// any tool description sees the agent list — the child LLM should not even
@@ -1262,6 +1423,7 @@ export default function (pi: ExtensionAPI) {
 			"Use subagent to delegate *reasoning and decisions*: codebase exploration (scout), web research (researcher), or isolated code changes (worker)",
 			"For multiple independent subagent tasks, emit multiple `subagent` tool calls in the same turn — they run in parallel automatically.",
 			"Subagents have NO context from the current conversation — include ALL necessary context in the task description",
+			"When a subagent returns an error, read it carefully. For transient failures (timeout, API/network), retry once with the same task plus 'Previous attempt failed with: {error}'. For structural failures (wrong approach, missing context), simplify the task or switch agents. If it persists after retry, report to the user with the specific error.",
 		],
 		parameters: Type.Object({
 			agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -1296,9 +1458,10 @@ export default function (pi: ExtensionAPI) {
 			};
 
 			const result = await semaphore.run(() =>
-				runSubagent(agent, params.task!, params.cwd ?? cwd, signal, (progress, usage) => {
+				runSubagent(agent, params.task!, params.cwd ?? cwd, signal, (progress, usage, finalExitCode) => {
 					liveResult.progress = progress;
 					liveResult.usage = { ...usage };
+					if (finalExitCode !== undefined) liveResult.exitCode = finalExitCode;
 					onUpdate?.({
 						content: [{ type: "text", text: "(running...)" }],
 						details: { results: [liveResult] },
@@ -1308,8 +1471,11 @@ export default function (pi: ExtensionAPI) {
 
 			result.contextWindow = contextWindow;
 			const isError = result.exitCode !== 0 || !!result.progress.error;
+			const contentText = isError
+				? buildSubagentErrorContent(result)
+				: (result.output || "(no output)");
 			return {
-				content: [{ type: "text", text: result.output || "(no output)" }],
+				content: [{ type: "text", text: contentText }],
 				details: { results: [result] },
 				...(isError ? { isError: true } : {}),
 			};
@@ -1403,7 +1569,8 @@ export default function (pi: ExtensionAPI) {
 		promptGuidelines: [
 			"Use pipeline when a task naturally decomposes into sequential agent roles (e.g. explore → plan → implement → review).",
 			"Each step receives the previous step's output automatically via {previous} placeholder substitution.",
-			"Pipelines stop on first error. The finalOutput is the last successful step's output.",
+			"Pipelines stop on first error. The finalOutput is the failing step's error detail.",
+			"When a pipeline fails at a step, the error identifies which step and why. Retry the failing step with a simpler task, or re-scope the pipeline. Early-step (exploration) failures → retry the whole pipeline with a more focused scope.",
 		],
 		parameters: Type.Object({
 			steps: Type.Array(
@@ -1535,6 +1702,7 @@ export default function (pi: ExtensionAPI) {
 			"Use loop for tasks that benefit from iterative refinement (e.g. drafting → reviewing → polishing).",
 			"Configure a judge agent to stop early when quality is sufficient, avoiding wasted iterations.",
 			"Each iteration receives all prior outputs as context, enabling progressive improvement.",
+			"When a loop iteration fails, the error shows which iteration. Reduce max_iterations or simplify the task; if the judge consistently rejects, refine the criteria or switch judge agent.",
 		],
 		parameters: Type.Object({
 			agent: Type.String({ description: "Agent name to run in the loop" }),

package/lib/agent-graph.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent graph validation — detects cycles in agent delegation graphs.
+ *
+ * Uses WHITE/GRAY/BLACK DFS coloring to detect back edges (GRAY neighbor = cycle).
+ * Returns null if acyclic, or a human-readable cycle string if cyclic.
+ */
+import type { AgentConfig } from "./types";
+
+type Color = "white" | "gray" | "black";
+
+/**
+ * Validate that the agent delegation graph is acyclic.
+ *
+ * Builds a directed graph from agent.subagentAgents references and runs
+ * DFS cycle detection. Handles: self-loops, 2-node cycles, N-node cycles,
+ * disconnected components, and references to agents not in the graph
+ * (skipped — they're external/leaf nodes).
+ *
+ * @param agents Array of agent configurations
+ * @returns null if acyclic, or a human-readable cycle string like
+ *          "Cycle detected in agent delegation graph: A → B → A"
+ */
+export function validateAgentGraphAcyclicity(agents: AgentConfig[]): string | null {
+    // Build adjacency list from agent configs
+    const agentNames = new Set(agents.map((a) => a.name));
+    const graph = new Map<string, string[]>();
+
+    for (const agent of agents) {
+        const targets = agent.subagentAgents ?? [];
+        // Filter out references to non-existent agents (external/leaf nodes)
+        graph.set(agent.name, targets.filter((t) => agentNames.has(t)));
+    }
+
+    // WHITE/GRAY/BLACK DFS coloring
+    const color = new Map<string, Color>();
+    const parent = new Map<string, string | null>();
+
+    for (const name of agentNames) {
+        color.set(name, "white");
+    }
+
+    // DFS from each unvisited node (handles disconnected components)
+    for (const start of agentNames) {
+        if (color.get(start) !== "white") continue;
+
+        // Iterative DFS using explicit stack
+        // Stack entries: [node, iterator index into neighbors]
+        const stack: Array<{ node: string; neighborIdx: number }> = [];
+        stack.push({ node: start, neighborIdx: 0 });
+        color.set(start, "gray");
+        parent.set(start, null);
+
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = graph.get(frame.node) ?? [];
+
+            if (frame.neighborIdx < neighbors.length) {
+                const neighbor = neighbors[frame.neighborIdx];
+                frame.neighborIdx++;
+
+                if (color.get(neighbor) === "gray") {
+                    // Back edge found — reconstruct cycle path
+                    const cyclePath = reconstructCyclePath(stack, neighbor);
+                    return `Cycle detected in agent delegation graph: ${cyclePath}`;
+                }
+
+                if (color.get(neighbor) === "white") {
+                    color.set(neighbor, "gray");
+                    parent.set(neighbor, frame.node);
+                    stack.push({ node: neighbor, neighborIdx: 0 });
+                }
+                // If black, it's a cross/forward edge — skip
+            } else {
+                // All neighbors explored — backtrack
+                color.set(frame.node, "black");
+                stack.pop();
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Reconstruct the cycle path from the DFS stack when a back edge is found.
+ * The back edge goes from the current top of stack to `target`.
+ * The cycle is: target → ... → top → target
+ */
+function reconstructCyclePath(
+    stack: Array<{ node: string; neighborIdx: number }>,
+    target: string,
+): string {
+    // Find target in the stack
+    let targetIdx = -1;
+    for (let i = 0; i < stack.length; i++) {
+        if (stack[i].node === target) {
+            targetIdx = i;
+            break;
+        }
+    }
+
+    if (targetIdx === -1) {
+        // Self-loop case: target is the current node
+        return `${target} → ${target}`;
+    }
+
+    // Build path from target to current top, then back to target
+    const path: string[] = [];
+    for (let i = targetIdx; i < stack.length; i++) {
+        path.push(stack[i].node);
+    }
+    path.push(target);
+
+    return path.join(" → ");
+}

package/lib/cycle-signature.ts

@@ -0,0 +1,153 @@
+/**
+ * Cycle-detection signature builder for tool calls.
+ *
+ * Unlike `extractToolArgsPreview` (optimized for TUI display), this module
+ * retains distinguishing arguments so that different calls doing different
+ * work produce different signatures (no false positives) while identical
+ * re-invocations collapse (true positives preserved).
+ */
+import * as crypto from "node:crypto";
+
+/**
+ * Header injected by the loop tool when accumulating prior iteration context
+ * into a subagent task. Shared here so normalizeTaskForSignature stays in sync
+ * with the injection site in index.ts — changing one without the other would
+ * silently break loop-context stripping (false-negative loop detection).
+ */
+export const LOOP_PRIOR_ITERATIONS_HEADER = "## Prior iterations:";
+
+/**
+ * Deterministic 48-bit fingerprint (12 hex chars) via SHA-256.
+ * Used for cycle-detection signatures: same input → same fingerprint,
+ * different inputs → different fingerprints (collision-resistant enough
+ * for a 24-entry sliding window).
+ */
+export function taskFingerprint(str: string): string {
+    return crypto.createHash("sha256").update(str, "utf8").digest("hex").slice(0, 12);
+}
+
+/**
+ * Conservatively normalize a subagent task string for cycle-signature hashing.
+ * Strips injected connector context (## Prior iterations:, ## Key findings,
+ * ## Implementation results, ## Research findings) which varies per invocation
+ * but is not the "real" task, then collapses whitespace and lowercases.
+ * Preserves the core task instruction.
+ *
+ * Limitation: only strips the 4 known headers. A user-defined agent with a
+ * connector header NOT in this set would leave its {previous} content in the
+ * task hash, causing two identical logical tasks with varying prior context to
+ * produce different hashes — the detector could miss a loop (false negative).
+ * This is a deliberate tradeoff (conservative normalization preserves real task
+ * instructions; aggressive stripping risks over-collapsing different tasks).
+ * Residual risk is bounded by loop/pipeline/depth/timeout caps.
+ */
+export function normalizeTaskForSignature(task: string): string {
+    const stripped = task
+        .replace(new RegExp(LOOP_PRIOR_ITERATIONS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "[\\s\\S]*$", "m"), "")
+        .replace(/## Key findings[\s\S]*$/m, "")
+        .replace(/## Implementation results[\s\S]*$/m, "")
+        .replace(/## Research findings[\s\S]*$/m, "");
+    return stripped.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+/** Collapse any whitespace run (incl. newlines) into a single space. */
+function flatten(s: string): string {
+    return s.replace(/\s+/g, " ").trim();
+}
+
+const MAX_CYCLE_SIG_COMPONENT = 120;
+
+/**
+ * Build a cycle-detection signature for a tool call. Unlike extractToolArgsPreview
+ * (optimized for TUI display), this retains distinguishing arguments so that
+ * different calls doing different work produce different signatures (no false
+ * positives) while identical re-invocations collapse (true positives preserved).
+ * Components are capped to bound memory in the 24-entry sliding window.
+ */
+export function extractCycleSignature(toolName: string, args: Record<string, unknown>): string {
+    const cap = (s: string, max: number = MAX_CYCLE_SIG_COMPONENT) =>
+        s.length > max ? s.slice(0, max) : s;
+
+    switch (toolName) {
+        case "bash":
+        case "safe_bash": {
+            const cmd = cap(flatten(String(args.command || "")));
+            const cwd = args.cwd ? `:${cap(flatten(String(args.cwd)), 60)}` : "";
+            return `${toolName}:${cmd}${cwd}`;
+        }
+        case "read": {
+            // Include offset (and limit) so pagination of the same file is progress, not a loop.
+            const p = cap(flatten(String(args.path || "")));
+            const offset = args.offset ?? 0;
+            const limit = args.limit ?? "";
+            return `read:${p}@${offset}${limit !== "" ? "/" + limit : ""}`;
+        }
+        case "write": {
+            const p = cap(flatten(String(args.path || "")));
+            const contentHash = args.content
+                ? taskFingerprint(String(args.content).slice(0, 1000))
+                : "nocontent";
+            return `write:${p}:${contentHash}`;
+        }
+        case "edit": {
+            const p = cap(flatten(String(args.path || "")));
+            let body = "";
+            if (Array.isArray(args.edits) && args.edits.length > 0) {
+                body = (args.edits as Array<{ newText?: string; new_string?: string }>)
+                    .map((e) => String(e?.newText || e?.new_string || ""))
+                    .join("\n");
+            } else {
+                body = String(args.newText || args.new_string || args.content || "");
+            }
+            const contentHash = body ? taskFingerprint(body.slice(0, 500)) : "noedit";
+            return `edit:${p}:${contentHash}`;
+        }
+        case "grep": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            const ex = args.exclude ? `!${cap(flatten(String(args.exclude)), 40)}` : "";
+            return `grep:${pat}${p}${ex}`;
+        }
+        case "find":
+        case "fffind": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            return `${toolName}:${pat}${p}`;
+        }
+        case "ffgrep": {
+            const pat = cap(flatten(String(args.pattern || "")));
+            const p = args.path ? `:${cap(flatten(String(args.path)), 60)}` : "";
+            return `ffgrep:${pat}${p}`;
+        }
+        case "ls": {
+            return `ls:${cap(flatten(String(args.path || ".")))}`;
+        }
+        case "web_search": {
+            return `web_search:${cap(flatten(String(args.query || "")))}`;
+        }
+        case "web_fetch": {
+            return `web_fetch:${cap(flatten(String(args.url || "")))}`;
+        }
+        case "subagent": {
+            // CRITICAL: include task fingerprint so different delegations are distinguishable.
+            const agent = flatten(String(args.agent || ""));
+            const taskHash = args.task
+                ? taskFingerprint(normalizeTaskForSignature(String(args.task)))
+                : "notask";
+            return `subagent:${agent}:${taskHash}`;
+        }
+        case "gh_cli": {
+            return `gh_cli:${cap(flatten(String(args.command || "")))}`;
+        }
+        case "read_pdf": {
+            return `read_pdf:${cap(flatten(String(args.path || "")))}`;
+        }
+        case "clarification_ui": {
+            return `clarification_ui:${cap(flatten(JSON.stringify(args)))}`;
+        }
+        default: {
+            const s = JSON.stringify(args);
+            return `${toolName}:${cap(flatten(s))}`;
+        }
+    }
+}

package/lib/depth-limit.ts

@@ -0,0 +1,35 @@
+/**
+ * Depth-limiting logic for subagent nesting.
+ *
+ * Pure helper functions for checking and propagating subagent depth.
+ * Extracted for testability — the actual depth enforcement happens in
+ * buildPiArgs() in index.ts.
+ */
+
+export interface DepthCheckResult {
+    allowed: boolean;
+    newDepth: number;
+    error?: string;
+}
+
+/**
+ * Check whether a new subagent spawn is allowed given the current depth and max.
+ *
+ * @param currentDepth The current nesting depth (from PI_SUBAGENT_DEPTH env var)
+ * @param maxDepth The maximum allowed depth (from config or default of 8)
+ * @returns DepthCheckResult with allowed flag, newDepth, and optional error message
+ */
+export function checkDepth(currentDepth: number, maxDepth: number): DepthCheckResult {
+    const newDepth = currentDepth + 1;
+    if (newDepth > maxDepth) {
+        return {
+            allowed: false,
+            newDepth,
+            error:
+                `Subagent depth limit exceeded (${newDepth} > ${maxDepth}). ` +
+                `This likely indicates a recursion loop in agent delegation. ` +
+                `Set maxSubagentDepth in config.json to increase the limit.`,
+        };
+    }
+    return { allowed: true, newDepth };
+}

package/lib/error-helpers.ts

@@ -0,0 +1,66 @@
+/**
+ * Error-message helpers for subagent tool returns.
+ *
+ * pi-agent-core drops the `isError` flag on normal tool returns, so `content`
+ * is the only reliable channel to communicate failure context back to the main
+ * LLM. These helpers build clear, actionable messages so the LLM can retry,
+ * redirect, or report.
+ */
+
+/** Minimal shape the helper needs from a subagent result. */
+interface SubagentErrorResult {
+	agent: string;
+	exitCode: number;
+	output: string;
+	progress: {
+		error?: string;
+		lastMessage?: string;
+	};
+}
+
+/**
+ * Build a clear, actionable error message for the main LLM when a single
+ * subagent fails. The `content` channel is the only reliable one (pi-agent-core
+ * drops a returned `isError` flag on normal tool returns), so this must carry
+ * enough context for the LLM to retry, redirect, or report.
+ */
+export function buildSubagentErrorContent(result: SubagentErrorResult): string {
+	const parts: string[] = [];
+	parts.push(`[Subagent error] Agent "${result.agent}" failed (exit code ${result.exitCode}).`);
+	if (result.progress.error) {
+		parts.push(`Error: ${result.progress.error}`);
+	}
+	if (result.progress.lastMessage) {
+		parts.push(`Last message: ${result.progress.lastMessage}`);
+	}
+	if (result.output && result.output !== "(no output)") {
+		parts.push(`Output:\n${result.output}`);
+	}
+	return parts.join("\n");
+}
+
+export function buildPipelineErrorContent(
+	stepIndex: number,
+	stepAgent: string,
+	result: { exitCode: number; output: string; progress: { error?: string } },
+): string {
+	return [
+		`Pipeline failed at step ${stepIndex + 1} (agent: ${stepAgent}).`,
+		`Exit code: ${result.exitCode}`,
+		result.progress.error ? `Error: ${result.progress.error}` : null,
+		result.output ? `Output:\n${result.output}` : "(no output)",
+	].filter(Boolean).join("\n");
+}
+
+export function buildLoopErrorContent(
+	iteration: number,
+	agentName: string,
+	result: { exitCode: number; output: string; progress: { error?: string } },
+): string {
+	return [
+		`Loop failed at iteration ${iteration + 1} (agent: ${agentName}).`,
+		`Exit code: ${result.exitCode}`,
+		result.progress.error ? `Error: ${result.progress.error}` : null,
+		result.output ? `Output:\n${result.output}` : "(no output)",
+	].filter(Boolean).join("\n");
+}

package/lib/loop-detector.ts

@@ -0,0 +1,40 @@
+/**
+ * Cycle detector for tool-call streams. Watches a sliding window of
+ * tool-call signatures for a sub-sequence of length P repeated 3 times
+ * (P in [2,8]). Catches an agent stuck in a tool-call loop without
+ * imposing any count cap on legitimate work. Purely parent-side.
+ */
+const WINDOW_SIZE = 24;
+const MIN_PATTERN_LEN = 2;
+const MAX_PATTERN_LEN = 8;
+const REPETITIONS = 3;
+
+export interface CycleResult {
+    cycle: boolean;
+    pattern?: string[];   // the repeating sub-sequence of signatures (length P)
+}
+
+/**
+ * Detect whether `newSig` completes a 3× cycle. Pure: does NOT mutate `history`.
+ * The caller pushes `newSig` onto its own history AFTER calling this.
+ */
+export function detectCycle(history: string[], newSig: string): CycleResult {
+    const window = [...history, newSig];
+    const start = Math.max(0, window.length - WINDOW_SIZE);
+    const w = window.slice(start);
+    for (let p = MIN_PATTERN_LEN; p <= MAX_PATTERN_LEN; p++) {
+        const needed = p * REPETITIONS;
+        if (w.length < needed) continue;
+        const tail = w.slice(-needed);
+        const pattern = tail.slice(0, p);
+        let isCycle = true;
+        for (let i = 0; i < p; i++) {
+            if (pattern[i] !== tail[p + i] || pattern[i] !== tail[2 * p + i]) {
+                isCycle = false;
+                break;
+            }
+        }
+        if (isCycle) return { cycle: true, pattern };
+    }
+    return { cycle: false };
+}

package/package.json

@@ -1,42 +1,42 @@
 {
-  "name": "@rohaquinlop/pi-subagents",
-  "version": "0.4.0",
-  "description": "Pi extension for delegating tasks to subagents — parallel execution, agent discovery, and TUI rendering",
-  "keywords": [
-    "pi-package",
-    "subagent",
-    "parallel",
-    "coding-agent",
-    "extension"
-  ],
-  "license": "MIT",
-  "author": "rohaquinlop",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rohaquinlop/pi-subagents.git"
-  },
-  "files": [
-    "index.ts",
-    "agents/",
-    "tools/",
-    "lib/",
-    "README.md"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "vitest": "^3.2.0"
-  }
+    "name": "@rohaquinlop/pi-subagents",
+    "version": "0.5.1",
+    "description": "Pi extension for delegating tasks to subagents — parallel execution, agent discovery, and TUI rendering",
+    "keywords": [
+        "pi-package",
+        "subagent",
+        "parallel",
+        "coding-agent",
+        "extension"
+    ],
+    "license": "MIT",
+    "author": "rohaquinlop",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rohaquinlop/pi-subagents.git"
+    },
+    "files": [
+        "index.ts",
+        "agents/",
+        "tools/",
+        "lib/",
+        "README.md"
+    ],
+    "pi": {
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*",
+        "@sinclair/typebox": "*"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "devDependencies": {
+        "vitest": "^3.2.0"
+    }
 }

package/tools/safe-bash.ts

@@ -6,6 +6,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createBashTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
+const DEFAULT_SAFE_BASH_TIMEOUT_S = 300; // 5 minutes — kills stuck commands instead of relying on the 10-min wall-clock
+
 const DANGEROUS_PATTERNS = [
 	/\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
 	/\brm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
@@ -46,7 +48,7 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			command: Type.String({ description: "Bash command to execute" }),
 			timeout: Type.Optional(
-				Type.Number({ description: "Timeout in seconds (optional)" }),
+				Type.Number({ description: "Timeout in seconds (default: 300s/5min; pass a larger value for builds/tests/installs)" }),
 			),
 		}),
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -54,7 +56,8 @@ export default function (pi: ExtensionAPI) {
 			if (danger) {
 				throw new Error(danger);
 			}
-			return bashTool.execute(toolCallId, params, signal, onUpdate);
+			const timeout = params.timeout ?? DEFAULT_SAFE_BASH_TIMEOUT_S;
+			return bashTool.execute(toolCallId, { ...params, timeout }, signal, onUpdate);
 		},
 	});
 }