pi-open-agents 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -21,12 +21,12 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { AgentDefinition, ThinkingLevel } from "./types.ts";
 import { loadAgents, selectableAgents, spawnableAgents } from "./discovery/loader.ts";
 import { AgentManager } from "./primary/manager.ts";
-import { refreshAgentTools, buildSystemPrompt } from "./primary/executor.ts";
+import { refreshAgentTools, buildSystemPrompt, buildSubagentGuidance } from "./primary/executor.ts";
 import { updateBanner } from "./tui/banner.ts";
 import { registerTuiControls } from "./tui/selector.ts";
 import { registerAgentTools } from "./tui/tools.ts";
 import { registerSubagentTool } from "./subagent/tool.ts";
-import { isSubagentReplaceSystemPrompt } from "./subagent/env.ts";
+import { allowedAgentNames } from "./subagent/env.ts";
 
 // ─── Settings ────────────────────────────────────────────────────────────────
 
@@ -141,33 +141,40 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
     updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
   });
 
-  // ── Before Agent Start: Inject system prompt + refresh tools ───────────────
+  // ── Before Agent Start: Inject system prompt + subagent guidance ─────────
 
   pi.on("before_agent_start", async (event) => {
     const active = manager.getActive();
-    if (!active) return;
+    let prompt = event.systemPrompt;
 
-    // Re-evaluate tool set (catches async-registered tools like MCP)
-    refreshAgentTools(active, pi);
-
-    // Inject system prompt
-    const modifiedPrompt = buildSystemPrompt(active, event.systemPrompt);
-    if (modifiedPrompt) {
-      return { systemPrompt: modifiedPrompt };
+    // Primary agent: apply system prompt mode + refresh tools
+    if (active) {
+      refreshAgentTools(active, pi);
+      const modified = buildSystemPrompt(active, prompt);
+      if (modified !== undefined) prompt = modified;
     }
-  });
 
-  // ── Before Agent Start (subagent replace mode): Inject available subagents ─
+    // Inject subagent delegation guidance (if subagent tool is available)
+    const hasSubagentTool = pi.getAllTools().some((t) => t.name === "subagent");
+    if (hasSubagentTool) {
+      // Determine allowed agents: from active agent config or env vars (subagent process)
+      let allowedAgents: string[] | undefined;
+      if (active?.allowedAgents && active.allowedAgents.length > 0) {
+        allowedAgents = active.allowedAgents;
+      } else {
+        const envAllowed = allowedAgentNames(process.env);
+        if (envAllowed) allowedAgents = [...envAllowed];
+      }
 
-  pi.on("before_agent_start", async (event) => {
-    if (!isSubagentReplaceSystemPrompt(process.env)) return;
-    // In replace mode, append available subagent list to the system prompt
-    const agents = manager.getAgents();
-    const spawnable = spawnableAgents(agents);
-    if (spawnable.length === 0) return;
-    const names = spawnable.map((a: AgentDefinition) => a.name).sort().join(", ");
-    const block = `\n\nAvailable subagents:\n- ${names.split(", ").join("\n- ")}`;
-    return { systemPrompt: event.systemPrompt + block };
+      const guidance = buildSubagentGuidance(manager.getAgents(), allowedAgents);
+      if (guidance) {
+        prompt += guidance;
+      }
+    }
+
+    if (prompt !== event.systemPrompt) {
+      return { systemPrompt: prompt };
+    }
   });
 
   // ── Turn Start: Persist agent state (only on change) ───────────────────────

package/src/primary/executor.ts

@@ -13,6 +13,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentDefinition, ModelRef, PermissionRule } from "../types.ts";
 import { parsePermissionRules } from "../permission/parser.ts";
 import { getDisabledTools } from "../permission/evaluator.ts";
+import { spawnableAgents } from "../discovery/loader.ts";
 
 // ─── Model Resolution ────────────────────────────────────────────────────────
 
@@ -140,6 +141,41 @@ export function refreshAgentTools(agent: AgentDefinition, pi: ExtensionAPI): voi
   applyTools(agent, pi);
 }
 
+/**
+ * Build subagent delegation guidance to inject into the system prompt.
+ *
+ * Teaches the model HOW to delegate — specifically that subagent names
+ * are NOT CLI commands and must be invoked via the `subagent` tool.
+ * This is injected automatically, so agent authors don't need to explain
+ * the delegation mechanism in their prompts.
+ *
+ * Works for both primary agents and subagent child processes.
+ */
+export function buildSubagentGuidance(
+  agents: AgentDefinition[],
+  allowedAgents?: string[],
+): string | undefined {
+  const allSpawnable = spawnableAgents(agents);
+
+  // Filter by allowedAgents whitelist if specified
+  let available: AgentDefinition[];
+  if (allowedAgents && allowedAgents.length > 0) {
+    const allowed = new Set(allowedAgents);
+    available = allSpawnable.filter((a) => allowed.has(a.name));
+  } else {
+    available = allSpawnable;
+  }
+
+  if (available.length === 0) return undefined;
+
+  const list = available
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((a) => `- ${a.name}: ${a.description ?? "Subagent for delegated tasks."}`)
+    .join("\n");
+
+  return `\n\n## Subagent Delegation\n\nYou have ${available.length} subagent(s) available. Delegate isolated tasks using the \`subagent\` tool:\n\nsubagent({ agent: "<name>", task: "<task description>" })\n\nAvailable subagents:\n${list}\n\nIMPORTANT: Subagent names are NOT bash commands. Always use the \`subagent\` tool to delegate — never write scripts that call agent names as CLI commands.`;
+}
+
 /**
  * Build the system prompt injection for the active agent.
  *