oira666_pi-subagent 0.3.12 → 0.3.13

package/README.md

@@ -130,7 +130,9 @@ The Markdown body becomes the agent's system prompt (appended to Pi's default, n
 
 ## Delegation Guards
 
-Depth and cycle guards prevent runaway recursive delegation. Layer availability is evaluated for the child being launched: depth 1 is the first layer, and `PI_SUBAGENT_MAX_DEPTH` is the last layer. The bundled `team-lead` agent sets `last-layer: disabled` so it cannot consume the final delegation layer. Cycle checks are applied per task: in a mixed parallel call, cyclic tasks fail while legal siblings still run.
+Depth and cycle guards prevent runaway recursive delegation. Layer availability is evaluated for the child being launched: depth 1 is the first layer, and `PI_SUBAGENT_MAX_DEPTH` is the last layer. The bundled `team-lead` agent sets `last-layer: disabled` so it cannot consume the final delegation layer. When cycle prevention is enabled, agents already in the current delegation stack are omitted from the child model's available-agent list. The runner still checks every task as a safety boundary: in a mixed parallel call, cyclic tasks fail while legal siblings still run.
+
+A nested delegation failure is returned to its calling agent as a recoverable tool error. If that agent subsequently retries, completes the work itself, and produces a successful final answer, the earlier tool error does not incorrectly turn the completed agent—and all of its ancestors—into failures.
 
 | Config                         | Default | Description                                      |
 | ------------------------------ | ------- | ------------------------------------------------ |

package/agents.ts

@@ -200,6 +200,27 @@ export function isAgentEnabledAtLayer(
 	return true;
 }
 
+/**
+ * Return only agents that may be advertised for the next delegation.
+ *
+ * The runner still enforces cycle prevention as a final safety boundary, but
+ * forbidden agents must not be presented to the model as available choices.
+ */
+export function filterAdvertisedAgents(
+	agents: AgentConfig[],
+	targetDepth: number,
+	maxDepth: number,
+	delegationStack: string[],
+	preventCycles: boolean,
+): AgentConfig[] {
+	const blocked = preventCycles ? new Set(delegationStack) : null;
+	return agents.filter(
+		(agent) =>
+			isAgentEnabledAtLayer(agent, targetDepth, maxDepth) &&
+			!blocked?.has(agent.name),
+	);
+}
+
 /**
  * Discover all available agents according to the requested scope.
  *

package/index.ts

@@ -18,7 +18,12 @@ import {
   lazyStream,
 } from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
-import { type AgentConfig, discoverAgents, isAgentEnabledAtLayer } from "./agents.js";
+import {
+  type AgentConfig,
+  discoverAgents,
+  filterAdvertisedAgents,
+  isAgentEnabledAtLayer,
+} from "./agents.js";
 import { loadPiSubagentsConfig } from "./config.js";
 import {
   allocateSubagentNames,
@@ -430,6 +435,22 @@ function filterAgentsForCurrentLayer(
   return agents.filter((agent) => isAgentEnabledAtLayer(agent, targetDepth, maxDepth));
 }
 
+function filterAgentsForPrompt(
+  agents: AgentConfig[],
+  currentDepth: number,
+  maxDepth: number,
+  delegationStack: string[],
+  preventCycles: boolean,
+): AgentConfig[] {
+  return filterAdvertisedAgents(
+    agents,
+    currentDepth + 1,
+    maxDepth,
+    delegationStack,
+    preventCycles,
+  );
+}
+
 function formatAgentNames(agents: AgentConfig[]): string {
   return agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
 }
@@ -1424,7 +1445,13 @@ export default function (pi: ExtensionAPI) {
       if (!canDelegate) return;
 
       const discovery = discoverAgents(ctx.cwd, "both");
-      discoveredAgents = filterAgentsForCurrentLayer(discovery.agents, currentDepth, maxDepth);
+      discoveredAgents = filterAgentsForPrompt(
+        discovery.agents,
+        currentDepth,
+        maxDepth,
+        ancestorAgentStack,
+        preventCycles,
+      );
       currentSessionId = ctx.sessionManager.getSessionId?.() ?? "ephemeral";
       currentSubagentSessionRoot = getDefaultSubagentSessionRoot(ctx);
       if (resumableSubagentsDisabled()) {
@@ -1720,11 +1747,12 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event) => {
     try {
       if (!canDelegate) return;
-      if (discoveredAgents.length === 0) return;
 
-      const agentList = discoveredAgents
-        .map((a) => `- **${a.name}**: ${a.description}`)
-        .join("\n");
+      const agentList = discoveredAgents.length > 0
+        ? discoveredAgents
+            .map((a) => `- **${a.name}**: ${a.description}`)
+            .join("\n")
+        : "_No agents are available for the next delegation layer. Do not call the subagents tool._";
       const subagentsGuidance = configuredToolPrompts[SUBAGENT_TOOL_NAME] ?? `### How to call the subagents tool
 
 Each subagent runs in an **isolated process**.
@@ -1746,8 +1774,18 @@ calls one after another. Do NOT put dependent tasks in the same array.
 { "tasks": [{ "agent": "agent-a", "task": "..." }, { "agent": "agent-b", "task": "..." }] }
 \`\`\`
 
-- Max depth: current depth ${currentDepth}, max depth ${maxDepth}
 - Max subagents per tool call: ${maxParallelTasks}`;
+      const delegationStackText = ancestorAgentStack.length > 0
+        ? ancestorAgentStack.join(" -> ")
+        : "(root)";
+      const delegationGuardGuidance = `### Delegation guards
+
+- Current depth: ${currentDepth}; max depth: ${maxDepth}
+- Cycle prevention: ${preventCycles ? "enabled" : "disabled"}
+- Current delegation stack: ${delegationStackText}
+${preventCycles
+  ? "- Agents already in this stack are intentionally omitted from the available list. Do not request omitted agent names."
+  : "- Cyclic delegation is allowed by configuration."}`;
       const resumeGuidance = resumableSubagentsDisabled()
         ? ""
         : configuredToolPrompts[RESUME_SUBAGENTS_TOOL_NAME] ?? `### Resumable subagents
@@ -1772,7 +1810,7 @@ keeping their full previous context:
 
 The following subagents are available via the \`subagents\` tool:
 
-${agentList}\n\n${subagentsGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` : ""}`,
+${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` : ""}`,
       };
     } catch (err) {
       console.error("[pi-subagent] Error in before_agent_start:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.ts",

package/runner.ts

@@ -21,7 +21,6 @@ import {
   emptyUsage,
   extractToolCalls,
   getFinalOutput,
-  getNestedSubagentErrorSummary,
   isResultError,
   isResultSuccess,
   isSubagentDetails,
@@ -1239,16 +1238,11 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
       if (!result.stderr.trim()) result.stderr = result.errorMessage;
     }
 
-    if (result.exitCode === 0) {
-      const nestedErrorSummary = getNestedSubagentErrorSummary(result.messages);
-      if (nestedErrorSummary) {
-        result.exitCode = 1;
-        result.stopReason = "error";
-        result.errorMessage = nestedErrorSummary;
-        if (!result.stderr.trim()) result.stderr = nestedErrorSummary;
-      }
-    }
-
+    // A failed nested delegation is a recoverable tool error, just like a
+    // failed bash/read call. Pi returns that error to the calling model, which
+    // may retry, choose another approach, or finish the task itself. Do not
+    // overwrite a later successful terminal answer with an earlier nested
+    // tool failure.
     return result;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);