pi-subagents 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-02-11
+
+### Added
+- Recursion depth guard (`PI_SUBAGENT_MAX_DEPTH`) to prevent runaway nested subagent spawning. Default max depth is 2 (main -> subagent -> sub-subagent). Deeper calls are blocked with guidance to the calling agent.
+
 ## [0.8.1] - 2026-02-10
 
 ### Added

package/README.md

@@ -595,6 +595,22 @@ Press **Ctrl+O** to expand the full streaming view with complete output per step
 
 > **Note:** Chain visualization (the `✓scout → ●planner` line) is only shown for sequential chains. Chains with parallel steps show per-step cards instead.
 
+## Nested subagent recursion guard
+
+Subagents can themselves call the `subagent` tool, which risks unbounded recursive spawning (slow, expensive, hard to observe). A depth guard prevents this.
+
+By default nesting is limited to **2 levels**: `main session → subagent → sub-subagent`. Any deeper `subagent` calls are blocked and return an error with guidance to the calling agent.
+
+Override the limit with `PI_SUBAGENT_MAX_DEPTH` **set before starting `pi`**:
+
+```bash
+export PI_SUBAGENT_MAX_DEPTH=3   # allow one more level (use with caution)
+export PI_SUBAGENT_MAX_DEPTH=1   # only allow direct subagents, no nesting
+export PI_SUBAGENT_MAX_DEPTH=0   # disable the subagent tool entirely
+```
+
+`PI_SUBAGENT_DEPTH` is an internal variable propagated automatically to child processes -- don't set it manually.
+
 ## Async observability
 
 Async runs write a dedicated observability folder:

package/execution.ts

@@ -20,6 +20,7 @@ import {
 	type SingleResult,
 	DEFAULT_MAX_OUTPUT,
 	truncateOutput,
+	getSubagentDepthEnv,
 } from "./types.js";
 import {
 	writePrompt,
@@ -150,7 +151,7 @@ export async function runSync(
 		}
 	}
 
-	const spawnEnv = { ...process.env };
+	const spawnEnv = { ...process.env, ...getSubagentDepthEnv() };
 	const mcpDirect = agent.mcpDirectTools;
 	if (mcpDirect?.length) {
 		spawnEnv.MCP_DIRECT_TOOLS = mcpDirect.join(",");

package/index.ts

@@ -38,6 +38,7 @@ import {
 	POLL_INTERVAL_MS,
 	RESULTS_DIR,
 	WIDGET_KEY,
+	checkSubagentDepth,
 } from "./types.js";
 import { readStatus, findByPrefix, getFinalOutput, mapConcurrent } from "./utils.js";
 import { runSync } from "./execution.js";
@@ -189,6 +190,24 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				}
 				return handleManagementAction(params.action, params, ctx);
 			}
+
+			const { blocked, depth, maxDepth } = checkSubagentDepth();
+			if (blocked) {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								`Nested subagent call blocked (depth=${depth}, max=${maxDepth}). ` +
+								"You are running at the maximum subagent nesting depth. " +
+								"Complete your current task directly without delegating to further subagents.",
+						},
+					],
+					isError: true,
+					details: { mode: "single" as const, results: [] },
+				};
+			}
+
 			const scope: AgentScope = params.agentScope ?? "user";
 			currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 			const agents = discoverAgents(ctx.cwd, scope).agents;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "pi-subagents",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nicobailon/pi-subagents.git"
@@ -26,10 +27,14 @@
   },
   "files": [
     "*.ts",
+    "!*.test.ts",
     "*.mjs",
     "README.md",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test recursion-guard.test.ts"
+  },
   "pi": {
     "extensions": [
       "./index.ts",

package/subagent-runner.ts

@@ -11,6 +11,7 @@ import {
 	DEFAULT_MAX_OUTPUT,
 	type MaxOutputConfig,
 	truncateOutput,
+	getSubagentDepthEnv,
 } from "./types.js";
 
 interface SubagentStep {
@@ -102,8 +103,8 @@ function runPiStreaming(
 ): Promise<{ stdout: string; exitCode: number | null }> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
-		const spawnEnv = env ? { ...process.env, ...env } : undefined;
-		const child = spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"], ...(spawnEnv && { env: spawnEnv }) });
+		const spawnEnv = { ...process.env, ...(env ?? {}), ...getSubagentDepthEnv() };
+		const child = spawn("pi", args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: spawnEnv });
 		let stdout = "";
 
 		child.stdout.on("data", (chunk: Buffer) => {

package/types.ts

@@ -242,6 +242,27 @@ export const ASYNC_DIR = "/tmp/pi-async-subagent-runs";
 export const WIDGET_KEY = "subagent-async";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+
+// ============================================================================
+// Recursion Depth Guard
+// ============================================================================
+
+export function checkSubagentDepth(): { blocked: boolean; depth: number; maxDepth: number } {
+	const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const maxDepth = Number(process.env.PI_SUBAGENT_MAX_DEPTH ?? String(DEFAULT_SUBAGENT_MAX_DEPTH));
+	const blocked = Number.isFinite(depth) && Number.isFinite(maxDepth) && depth >= maxDepth;
+	return { blocked, depth, maxDepth };
+}
+
+export function getSubagentDepthEnv(): Record<string, string> {
+	const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
+	return {
+		PI_SUBAGENT_DEPTH: String(nextDepth),
+		PI_SUBAGENT_MAX_DEPTH: process.env.PI_SUBAGENT_MAX_DEPTH ?? String(DEFAULT_SUBAGENT_MAX_DEPTH),
+	};
+}
 
 // ============================================================================
 // Utility Functions