pi-subagents 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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
+- **`chainDir` param** for persistent chain artifacts — specify a directory to keep artifacts beyond the default 24-hour `/tmp/` cleanup. Relative paths are resolved to absolute via `path.resolve()` for safe use in `{chain_dir}` template substitutions.
+
 ## [0.8.0] - 2026-02-09
 
 ### Added

package/README.md

@@ -474,6 +474,7 @@ Notes:
 | `model` | string | agent default | Override model for single agent |
 | `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
+| `chainDir` | string | `/tmp/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
 | `agentScope` | `"user" \| "project" \| "both"` | `user` | Agent discovery scope |
 | `async` | boolean | false | Background execution (requires `clarify: false` for chains) |
@@ -594,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/chain-execution.ts

@@ -76,6 +76,7 @@ export interface ChainExecutionParams {
 	clarify?: boolean;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
 	chainSkills?: string[];
+	chainDir?: string;
 }
 
 export interface ChainExecutionResult {
@@ -103,6 +104,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		clarify,
 		onUpdate,
 		chainSkills: chainSkillsParam,
+		chainDir: chainDirBase,
 	} = params;
 	const chainSkills = chainSkillsParam ?? [];
 
@@ -123,7 +125,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		?? (isParallelStep(firstStep) ? firstStep.parallel[0]!.task! : (firstStep as SequentialStep).task!);
 
 	// Create chain directory
-	const chainDir = createChainDir(runId);
+	const chainDir = createChainDir(runId, chainDirBase);
 
 	// Check if chain has any parallel steps
 	const hasParallelSteps = chainSteps.some(isParallelStep);

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;
@@ -377,6 +396,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					clarify: params.clarify,
 					onUpdate,
 					chainSkills,
+					chainDir: params.chainDir,
 				});
 			}
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "pi-subagents",
-  "version": "0.8.0",
+  "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/schemas.ts

@@ -75,6 +75,7 @@ export const SubagentParams = Type.Object({
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task}, ...]" })),
 	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. Use {task}, {previous}, {chain_dir} in task templates." })),
+	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: /tmp/pi-chain-runs/ (auto-cleaned after 24h)" })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'user')" })),
 	cwd: Type.Optional(Type.String()),

package/settings.ts

@@ -88,8 +88,8 @@ export function getStepAgents(step: ChainStep): string[] {
 // Chain Directory Management
 // =============================================================================
 
-export function createChainDir(runId: string): string {
-	const chainDir = path.join(CHAIN_RUNS_DIR, runId);
+export function createChainDir(runId: string, baseDir?: string): string {
+	const chainDir = path.join(baseDir ? path.resolve(baseDir) : CHAIN_RUNS_DIR, runId);
 	fs.mkdirSync(chainDir, { recursive: true });
 	return chainDir;
 }

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