pi-fast-subagent 0.7.0 → 0.8.0

package/README.md

@@ -69,6 +69,7 @@ You are code exploration specialist. Read relevant files, trace data flow, summa
 | `description` | yes | One-line description shown in `/fast-subagent:agent` |
 | `model` | no | Model override, format `provider/model-id` (e.g. `anthropic/claude-haiku-4-5`) |
 | `tools` | no | Tool allowlist (see below) |
+| `maxDepth` | no | Nested subagent depth this agent may spawn. Default `0` means this agent cannot call `subagent`. |
 
 ### `tools:` field
 
@@ -125,6 +126,28 @@ tools: all
 
 **YAML comments** (`# …`) are allowed inside the frontmatter — handy for documenting *why* a particular tool set was chosen. See `agents/general.md` and `agents/scout.md` for examples.
 
+### `maxDepth:` field
+
+Subagents cannot spawn other subagents by default, even when `tools` exposes the `subagent` tool.
+
+```md
+---
+name: planner
+description: Can delegate one level deeper
+maxDepth: 1
+---
+```
+
+Depth counts nested generations from that agent:
+
+| Value | Behavior |
+|-------|----------|
+| *(omitted)* / `0` | This agent cannot spawn subagents |
+| `1` | This agent may spawn subagents, but those children cannot spawn again unless their own `maxDepth` allows it |
+| `2` | Allows two nested generations, subject to each child agent's own `maxDepth` |
+
+Aliases accepted: `max_depth`, `depth`, `subagentDepth`.
+
 ## Background Agents
 
 Every foreground subagent can be moved to background at any time. Background jobs run concurrently while you continue chatting. When a job finishes, pi automatically posts the result as a follow-up message.

package/agents/general.md

@@ -11,6 +11,9 @@ model: anthropic/claude-haiku-4-5
 #   comma-separated list → explicit allowlist, e.g. `read, grep, web_search`
 # General is meant to be a do-anything fallback, so it keeps everything explicit.
 tools: all
+
+# Subagents cannot spawn subagents by default. Set maxDepth: 1+ to opt in.
+maxDepth: 0
 ---
 
 You are general-purpose subagent.

package/agents/scout.md

@@ -11,6 +11,9 @@ model: anthropic/claude-haiku-4-5
 #   comma-separated list → explicit allowlist
 # Scout is read-only: no `edit`, no `write`, no extension tools. Keeps the agent from mutating the codebase.
 tools: read, bash, grep, find, ls
+
+# Subagents cannot spawn subagents by default. Keep scout focused on exploration only.
+maxDepth: 0
 ---
 
 You are code exploration specialist.

package/agents.ts

@@ -31,6 +31,8 @@ export interface AgentConfig {
   description: string;
   model?: string;
   tools: AgentTools;
+  /** Number of nested subagent generations this agent may spawn. Default: 0. */
+  maxDepth: number;
   systemPrompt: string;
   source: "user" | "project";
   filePath: string;
@@ -58,6 +60,13 @@ function parseToolsField(raw: unknown): AgentTools {
   return list.length ? list : "all";
 }
 
+function parseMaxDepthField(raw: unknown): number {
+  if (raw === undefined || raw === null || raw === "") return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.floor(n);
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
   if (!fs.existsSync(dir)) return [];
   let entries: fs.Dirent[];
@@ -77,11 +86,15 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
       const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
       if (!frontmatter?.name || !frontmatter?.description) continue;
       const tools = parseToolsField(frontmatter.tools);
+      const maxDepth = parseMaxDepthField(
+        frontmatter.maxDepth ?? frontmatter.max_depth ?? frontmatter.depth ?? frontmatter.subagentDepth,
+      );
       agents.push({
         name: frontmatter.name,
         description: frontmatter.description,
         model: frontmatter.model,
         tools,
+        maxDepth,
         systemPrompt: body.trim(),
         source,
         filePath,

package/index.ts

@@ -257,8 +257,9 @@ const _fgJobs = new Map<string, ForegroundDetachEntry>();
 
 // ─── In-process runner ───────────────────────────────────────────────────────
 
-const MAX_DEPTH = 2;
+const DEFAULT_MAX_DEPTH = 0;
 const DEPTH_ENV = "PI_FAST_SUBAGENT_DEPTH";
+const MAX_DEPTH_ENV = "PI_FAST_SUBAGENT_MAX_DEPTH";
 
 interface ToolCallEntry {
   id: string;
@@ -330,8 +331,9 @@ function formatBgJobDetails(job: BackgroundSubagentJob, now = Date.now()): strin
   return lines.join("\n");
 }
 
-// Module-level depth counter — avoids process.env race conditions in parallel mode
+// Module-level depth counters for nested in-process subagent calls.
 let _currentDepth = 0;
+let _currentMaxDepth = DEFAULT_MAX_DEPTH;
 
 async function runAgent(
   agent: AgentConfig,
@@ -343,11 +345,12 @@ async function runAgent(
   parentDepth?: number,
 ): Promise<RunResult> {
   const depth = parentDepth ?? _currentDepth;
-  if (depth >= MAX_DEPTH) {
+  const isNestedCall = depth > 0;
+  if (isNestedCall && depth > _currentMaxDepth) {
     return {
       output: "",
       exitCode: 1,
-      error: `Max subagent depth (${MAX_DEPTH}) exceeded. Increase PI_FAST_SUBAGENT_DEPTH env to allow deeper nesting.`,
+      error: `Nested subagents are disabled by default. Set maxDepth: ${depth} (or higher) in the parent agent frontmatter to allow this call.`,
       toolCalls: [],
       usage: { input: 0, output: 0, cost: 0, turns: 0 },
     };
@@ -543,10 +546,17 @@ async function runAgent(
     });
   });
 
-  // Propagate depth to nested calls — use module counter (safe for parallel) + env for subprocess compat
+  // Propagate depth to nested calls. `maxDepth` is per-agent and defaults to 0,
+  // so subagents cannot spawn subagents unless their frontmatter opts in.
   const prevEnvDepth = process.env[DEPTH_ENV];
-  process.env[DEPTH_ENV] = String(depth + 1);
+  const prevEnvMaxDepth = process.env[MAX_DEPTH_ENV];
+  const prevDepth = _currentDepth;
+  const prevMaxDepth = _currentMaxDepth;
+  const maxDepth = Math.max(DEFAULT_MAX_DEPTH, agent.maxDepth ?? DEFAULT_MAX_DEPTH);
   _currentDepth = depth + 1;
+  _currentMaxDepth = depth + maxDepth;
+  process.env[DEPTH_ENV] = String(_currentDepth);
+  process.env[MAX_DEPTH_ENV] = String(_currentMaxDepth);
 
   let exitCode = 0;
   let error: string | undefined;
@@ -572,7 +582,10 @@ async function runAgent(
     loaderLease.release();
     if (prevEnvDepth === undefined) delete process.env[DEPTH_ENV];
     else process.env[DEPTH_ENV] = prevEnvDepth;
-    _currentDepth = depth;
+    if (prevEnvMaxDepth === undefined) delete process.env[MAX_DEPTH_ENV];
+    else process.env[MAX_DEPTH_ENV] = prevEnvMaxDepth;
+    _currentDepth = prevDepth;
+    _currentMaxDepth = prevMaxDepth;
   }
 
   return { output: lastOutput, exitCode, error, model: detectedModel, toolCalls, usage };
@@ -769,6 +782,7 @@ export default function (pi: ExtensionAPI) {
           `Description: ${agent.description}`,
           agent.model ? `Model: ${agent.model}` : "",
           `Tools: ${formatTools(agent.tools)}`,
+          `Max subagent depth: ${agent.maxDepth}`,
           agent.systemPrompt ? `\nSystem prompt:\n${agent.systemPrompt}` : "",
         ].filter(Boolean).join("\n");
         ctx.ui.notify(lines, "info");
@@ -781,7 +795,7 @@ export default function (pi: ExtensionAPI) {
           "Add .md files to:\n" +
           "  ~/.pi/agent/agents/   (user-level)\n" +
           "  .pi/agents/           (project-level)\n" +
-          "\nFrontmatter required: name, description. Optional: model, tools.",
+          "\nFrontmatter required: name, description. Optional: model, tools, maxDepth.",
           "info"
         );
         return;
@@ -1181,6 +1195,7 @@ export default function (pi: ExtensionAPI) {
           `**Description:** ${agent.description}`,
           agent.model ? `**Model:** ${agent.model}` : null,
           `**Tools:** ${formatTools(agent.tools)}`,
+          `**Max subagent depth:** ${agent.maxDepth}`,
           agent.systemPrompt ? `\n**System prompt:**\n${agent.systemPrompt}` : null,
         ].filter(Boolean).join("\n");
         return { content: [{ type: "text", text: info }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fast-subagent",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [