pi-extended-teams 2.4.0 → 2.4.2

package/extensions/agents/read-agent-session-lifecycle.ts

@@ -16,6 +16,7 @@ export interface ReadAgentDeliveryState {
   acceptingMessages?: boolean;
   messageDeliveryClosed?: boolean;
   messageDeliveryTail?: Promise<void>;
+  messageAdmissionTail?: Promise<void>;
   messageDeliveryGeneration?: number;
   messageDeliveryCancellation?: Promise<void>;
   cancelMessageDelivery?: () => void;
@@ -163,7 +164,8 @@ export function closeReadAgentMessageDelivery(state: ReadAgentDeliveryState): Re
 export async function enqueueReadAgentMessageDelivery(
   state: ReadAgentDeliveryState,
   agentName: string,
-  send: () => Promise<void>
+  send: () => Promise<void>,
+  received?: Promise<void>
 ): Promise<DeliveryOutcome> {
   if (!state.acceptingMessages || state.messageDeliveryClosed) {
     throw new Error(`Cannot send message to ${agentName}: agent is finishing.`);
@@ -175,7 +177,8 @@ export async function enqueueReadAgentMessageDelivery(
   state.pendingMessageDeliveries = (state.pendingMessageDeliveries ?? 0) + 1;
 
   const previousDelivery = state.messageDeliveryTail ?? Promise.resolve();
-  const rawOutcome = previousDelivery.catch(() => {}).then(async (): Promise<DeliveryOutcome> => {
+  const previousAdmission = state.messageAdmissionTail ?? previousDelivery;
+  const rawOutcome = previousAdmission.catch(() => {}).then(async (): Promise<DeliveryOutcome> => {
     if (state.messageDeliveryClosed || state.messageDeliveryGeneration !== generation) {
       return { status: "cancelled" };
     }
@@ -192,7 +195,10 @@ export async function enqueueReadAgentMessageDelivery(
     await rawDelivery;
     return { status: "delivered" };
   });
-  state.messageDeliveryTail = rawOutcome.then(() => {}, () => {});
+  const settled = rawOutcome.then(() => {}, () => {});
+  // Receipt releases the next send, not ownership of the model run it started.
+  state.messageAdmissionTail = received ? Promise.race([received, settled]) : settled;
+  state.messageDeliveryTail = Promise.all([previousDelivery, settled]).then(() => {});
 
   try {
     const outcome = await Promise.race([

package/extensions/agents/read-agent.ts

@@ -20,6 +20,7 @@ import { loadNativeCheckOperations } from "../internal/pi-check-operations";
 import type { AgentReportSource, CompletedAgentReport, RunningReadAgent } from "../runtime/types";
 import { extractTextParts, sanitizeTuiLine } from "../ui/renderers";
 import { createAgentCommunicationTools, formatRepairRequest, type SubmittedAgentReport } from "../tools/agent-communication-tools";
+import { registerSpawnedAgentCommunicationGuard, SPAWNED_AGENT_COMMUNICATION_GUIDANCE, USER_INTERACTION_TOOLS } from "../tools/spawned-agent-policy";
 import { requireWriteAgentTeam } from "../team/roster";
 import { isPiPromptPlanningMember, shouldSuppressLeadReportInjection } from "../../src/utils/workflow-metadata";
 import { canonicalPersistedModelSlot, loadSettings, requireFavoriteModelLevel } from "../../src/utils/settings";
@@ -389,31 +390,33 @@ export async function sendMessageToRunningReadAgent(
       const pendingInterrupt = agent.operationInterruptPromise;
       if (pendingInterrupt) await pendingInterrupt.catch(() => {});
       if (agent.messageDeliveryClosed || agent.stopRequested) throw new ReadAgentDeliveryCancelledError(agent.name);
-      if (requireReceipt) {
-        unsubscribe = session.subscribe(event => {
-          if (event.type !== "message_end" || event.message.role !== "user") return;
-          const body = event.message.content;
-          const text = typeof body === "string"
-            ? body
-            : body.filter(part => part.type === "text").map(part => part.text).join("\n");
-          if (text === content) {
-            received = true;
-            acknowledge();
-          }
-        });
-      }
+      if (agent.completedOperationError) throw agent.completedOperationError;
+      unsubscribe = session.subscribe(event => {
+        if (event.type !== "message_end" || event.message.role !== "user") return;
+        const body = event.message.content;
+        const text = typeof body === "string"
+          ? body
+          : body.filter(part => part.type === "text").map(part => part.text).join("\n");
+        if (text === content) {
+          received = true;
+          acknowledge();
+        }
+      });
       if (session.isStreaming) {
         await session.sendUserMessage(content, { deliverAs: "steer" as const });
       } else {
         await runReadAgentSessionOperation(agent, () => session.sendUserMessage(content, undefined));
         if (requireReceipt && !received) throw new Error(`Requester ${agent.name} finished without receiving the report.`);
       }
-    }
+    },
+    receipt
   );
   signalReadAgentWake(agent);
   pendingParentWakeSignals.get(agent)?.();
   try {
-    await deliveryResult;
+    // A normal send acknowledges receipt, not completion of the recipient's work.
+    // The delivery tail still owns that work for finalization and error handling.
+    await (requireReceipt ? deliveryResult : Promise.race([receipt, deliveryResult]));
     if (requireReceipt && !received) {
       // Keep the receipt wait outside the raw tail so parent finalization can cancel an unconsumed steer.
       await Promise.race([receipt, agent.messageDeliveryCancellation!.then(() => {
@@ -1056,6 +1059,7 @@ export async function runReadAgentInProcess(
       settingsManager: childSettingsManager,
       noExtensions: true,
       additionalExtensionPaths: [...resourcePlan.extensionPaths],
+      extensionFactories: [registerSpawnedAgentCommunicationGuard],
       noSkills: false,
       appendSystemPrompt: [
         `You are ${roleLabel} agent '${member.name}' in Pi session '${readTeamName}', running in-process so the lead can follow and control you from Pi.`,
@@ -1065,7 +1069,7 @@ export async function runReadAgentInProcess(
         role === "write"
           ? "Use read/bash/edit/write as needed for the assignment. Prefer precise edits. Stop and report if you need broader product or architecture approval."
           : "Even though the edit/write tools are available, do not use them: do not edit or write files, install or remove packages, start long-running services, commit, push, deploy, or make any other mutating or destructive change. Investigate and report; if a change is needed, recommend it to the lead instead of applying it.",
-        "Use send_message for direct communication and read_inbox only when you were told a reply is waiting. Do not coordinate a peer-agent society; the lead controls orchestration.",
+        SPAWNED_AGENT_COMMUNICATION_GUIDANCE,
         "Progress reporting is required, not optional UI polish. Call report_progress before your first work tool with a concise phrase describing what you are starting. Call it again whenever you change phase or evidence source, hit a blocker, or begin synthesis; never make more than 3 work-tool calls without a fresh progress update. Use a new phrase describing what you are doing now. It updates the activity widget without messaging or waking the lead; do not use it as a heartbeat.",
         ...(member.requestedBy
           ? [`You are a depth-1 read helper requested by '${member.requestedBy}'. Your report_and_exit deliverable goes to that requesting writer; the lead receives only a classified completion notice. You cannot delegate.`]
@@ -1138,7 +1142,9 @@ export async function runReadAgentInProcess(
     const communicationToolNameSet = new Set(communicationToolNames);
     const delegationToolNameSet = new Set<string>(NESTED_DELEGATION_TOOL_NAMES);
     const extensionToolNames = loader.getExtensions().extensions.flatMap(extension => {
-      return Array.from(extension.tools.keys()).filter(name => !communicationToolNameSet.has(name) && !delegationToolNameSet.has(name));
+      return Array.from(extension.tools.keys()).filter(name =>
+        !communicationToolNameSet.has(name) && !delegationToolNameSet.has(name) && !USER_INTERACTION_TOOLS.includes(name)
+      );
     });
     const nestedReadAgentToolNames = nestedReadAgentTools.map(tool => tool.name);
     const activeToolNames = Array.from(new Set([
@@ -1179,6 +1185,7 @@ export async function runReadAgentInProcess(
       modelRuntime: parentModelRuntime,
       modelRegistry: ctx.modelRegistry,
       tools: activeToolNames,
+      excludeTools: USER_INTERACTION_TOOLS,
       customTools: [...communicationTools, ...nestedReadAgentTools],
       resourceLoader: loader,
       settingsManager: childSettingsManager,
@@ -1418,6 +1425,7 @@ export async function runReadAgentInProcess(
           // its continuation may accept or settle another child wave.
           const deliveryTail = state.messageDeliveryTail;
           if (deliveryTail) await deliveryTail.catch(() => {});
+          if (state.completedOperationError) throw state.completedOperationError;
         }
       } else if (!state.stopRequested && options.isCurrentReadAgentRun(key, state)) {
         completionResolution = resolveCurrentReport();

package/extensions/events/register-events.ts

@@ -15,6 +15,7 @@ import { generateLifecycleRunId } from "../../src/utils/lifecycle-tombstone";
 import { cleanupStaleSessionContextReferences } from "../internal/session-context-reference";
 import { cleanupStalePrivateAgentSessions } from "../internal/agent-session-files";
 import { expireCheckpoints } from "../../src/results/checkpoint-retention";
+import { registerSpawnedAgentCommunicationGuard, SPAWNED_AGENT_COMMUNICATION_GUIDANCE } from "../tools/spawned-agent-policy";
 
 export const LEAD_ORCHESTRATION_GUIDANCE = `\n\npi-extended-teams lead orchestration rules:\n- Choose tiers by the agent's intended outcome, not by vague task importance. read-review is the normal default for focused review, verification, and bounded synthesis.\n- Use read-collect when the lane gathers bounded facts without owning the conclusion. Use read-analyze when it must explain behavior or root cause across connected evidence. Reserve read-critical for irreducible high-stakes security, architecture, concurrency, migration, or data-correctness reasoning.\n- For edits, use write-patch for a narrow localized change, write-feature for a bounded feature with a known design, write-system for a cross-cutting integration/refactor within explicitly claimed files, and write-critical only for high-risk security, concurrency, recovery, migration, or data-integrity changes.\n- Prefer the canonical read-*/write-* tiers. Legacy reading-*/writing-* names are compatibility aliases for this minor release, not intent guidance.\n- A spawned agent owns its assigned lane until it reports, blocks, fails, or the user cancels it. Do not duplicate, take over, test, edit, or synthesize that same lane in parallel; work only on clearly unrelated lanes.\n- When no unrelated work remains, end the turn. The extension resumes you when a report arrives. One get_agent_status snapshot is allowed when current status is needed; do not repeatedly call it, sleep, busy-wait, loop on inbox/status, send nudges, do dummy work, or treat healthy silence as failure.\n- Wait for the actual report before synthesizing. Intervene only on a reported blocker/error, actual health failure, or explicit user cancellation/change.\n- For durable bug, security, or testing claims from an agent report or backlog, concrete, reproducible findings with file/line evidence or a focused failing regression may proceed directly to TDD repair.
 - Use a separate read-only confirmation only when evidence is missing or weak, the claim is disputed, or irreducible high-risk uncertainty remains; never reconfirm an already confirmed finding.`;
@@ -66,6 +67,7 @@ export function registerAgentReportRenderer(pi: any): void {
 }
 
 export function registerExtensionEvents(pi: any, options: RegisterEventsOptions): void {
+  if (options.isTeammate) registerSpawnedAgentCommunicationGuard(pi);
   let teammateWakeIfUnread: (() => Promise<void>) | null = null;
   let teammatePendingInboxWake = false;
   let teammateInboxWakeTimer: NodeJS.Timeout | null = null;
@@ -387,6 +389,7 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
     if (!options.isTeammate) {
       return { systemPrompt: event.systemPrompt + LEAD_ORCHESTRATION_GUIDANCE };
     }
+    const systemPrompt = `${event.systemPrompt}\n\n${SPAWNED_AGENT_COMMUNICATION_GUIDANCE}`;
     if (firstTurn) {
       firstTurn = false;
 
@@ -430,8 +433,9 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
       }
 
       return {
-        systemPrompt: event.systemPrompt + `\n\nYou are spawned agent '${options.agentName}' in Pi session '${teamName}'.\nYour lead is 'team-lead'.${modelInfo}\n\nCore rules for every spawned agent:\n- NEVER sleep, busy-wait, or poll. Do not use bash sleep, while-true, or any wait/poll loop. The extension wakes you when messages arrive.\n- You cannot spawn, promote, or create other agents. If another agent is needed, use send_message to ask team-lead to decide and spawn.\n- Use send_message for direct communication and read_inbox when the extension wakes you or you expect a reply.\n- Progress reporting is required, not optional UI polish. After reading your initial instructions, call report_progress before your first work tool with a concise phrase describing what you are starting. Call it again whenever you change phase or evidence source, hit a blocker, or begin synthesis; never make more than 3 work-tool calls without a fresh progress update. Use a new phrase describing what you are doing now. It updates the activity widget without messaging or waking the lead; do not use it as a heartbeat.\n- When your work is done, report and exit cleanly. Do not wait for the lead to shut you down.${roleSpecificGuidance}${rosterInfo}\nStart by calling read_inbox to get your initial instructions.`,
+        systemPrompt: systemPrompt + `\n\nYou are spawned agent '${options.agentName}' in Pi session '${teamName}'.\nYour lead is 'team-lead'.${modelInfo}\n\nCore rules for every spawned agent:\n- NEVER sleep, busy-wait, or poll. Do not use bash sleep, while-true, or any wait/poll loop. The extension wakes you when messages arrive.\n- You cannot spawn, promote, or create other agents. If another agent is needed, use send_message to ask team-lead to decide and spawn.\n- Use send_message for direct communication and read_inbox when the extension wakes you or you expect a reply.\n- Progress reporting is required, not optional UI polish. After reading your initial instructions, call report_progress before your first work tool with a concise phrase describing what you are starting. Call it again whenever you change phase or evidence source, hit a blocker, or begin synthesis; never make more than 3 work-tool calls without a fresh progress update. Use a new phrase describing what you are doing now. It updates the activity widget without messaging or waking the lead; do not use it as a heartbeat.\n- When your work is done, report and exit cleanly. Do not wait for the lead to shut you down.${roleSpecificGuidance}${rosterInfo}\nStart by calling read_inbox to get your initial instructions.`,
       };
     }
+    return { systemPrompt };
   });
 }

package/extensions/prompts/spawned-agent-communication.md

@@ -0,0 +1 @@
+You are a spawned agent. Communicate only with team-lead through send_message. Never ask or address the user directly, open a user-question dialog, or use Orb to contact them. If you need a decision or permission, send the question and relevant context to team-lead. Do not treat a tool error or timeout as approval. Continue independent assigned work if possible. If you cannot continue without an answer, use report_and_exit with outcome blocked and include your questions; do not claim success or poll for a reply. Use report_and_exit for your final deliverable; nested helper reports still go to the requesting writer.

package/extensions/tools/agent-communication-tools.ts

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { requireLeadRecipient } from "./spawned-agent-policy";
 import * as messaging from "../../src/utils/messaging";
 import * as runtime from "../../src/utils/runtime";
 import * as claims from "../../src/utils/claims";
@@ -104,7 +105,7 @@ export function createAgentCommunicationTools(options: AgentCommunicationToolsOp
     {
       name: "send_message",
       label: "Send Message",
-      description: "Send a direct message in the current Pi session. Spawned agents default to messaging the lead.",
+      description: "Send a direct message in the current Pi session. Spawned agents may message only team-lead.",
       parameters: Type.Object({
         recipient: Type.Optional(Type.String({ description: "Recipient agent name. Defaults to team-lead for spawned agents." })),
         content: Type.String(),
@@ -114,6 +115,7 @@ export function createAgentCommunicationTools(options: AgentCommunicationToolsOp
         const teamName = requireCurrentSession(options);
         const recipient = params.recipient || (options.isTeammate ? "team-lead" : undefined);
         if (!recipient) throw new Error("recipient is required when the lead sends a message.");
+        if (options.isTeammate) requireLeadRecipient(recipient);
         await messaging.sendPlainMessageIfRunning(teamName, options.agentName, recipient, params.content, params.summary || "Message");
         return { content: [{ type: "text", text: `Message sent to ${recipient}.` }], details: { session: teamName, recipient } };
       },

package/extensions/tools/coordination-tools.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Type } from "@sinclair/typebox";
+import { requireLeadRecipient } from "./spawned-agent-policy";
 import * as paths from "../../src/utils/paths";
 import * as teams from "../../src/utils/teams";
 import * as messaging from "../../src/utils/messaging";
@@ -309,7 +310,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
   pi.registerTool({
     name: "send_message",
     label: "Send Message",
-    description: "Send a direct message in the current Pi session. Spawned agents default to messaging the lead.",
+    description: "Send a direct message in the current Pi session. Spawned agents may message only team-lead.",
     parameters: Type.Object({
       recipient: Type.Optional(Type.String({ description: "Recipient agent name. Defaults to team-lead for spawned agents." })),
       content: Type.String(),
@@ -319,6 +320,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
       const targetTeamName = requireCurrentSession(options);
       const recipient = params.recipient || (options.isTeammate ? "team-lead" : undefined);
       if (!recipient) throw new Error("recipient is required when the lead sends a message.");
+      if (options.isTeammate) requireLeadRecipient(recipient);
       const deliveredDirectly = await options.deliverMessageToActiveAgent?.(targetTeamName, recipient, params.content) === true;
       if (!deliveredDirectly) {
         await messaging.sendPlainMessageIfRunning(targetTeamName, options.agentName, recipient, params.content, params.summary || "Message");

package/extensions/tools/spawned-agent-policy.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export const USER_INTERACTION_TOOLS = ["ask_user", "ask_user_batch", "orb_ask", "orb_say"];
+export const SPAWNED_AGENT_COMMUNICATION_GUIDANCE = readFileSync(
+  path.join(__dirname, "../prompts/spawned-agent-communication.md"), "utf8"
+).trim();
+
+export function requireLeadRecipient(recipient: string): void {
+  if (recipient !== "team-lead") {
+    throw new Error("Spawned agents may send messages only to team-lead.");
+  }
+}
+
+export function registerSpawnedAgentCommunicationGuard(pi: Pick<ExtensionAPI, "on">): void {
+  pi.on("tool_call", event => {
+    if (USER_INTERACTION_TOOLS.includes(event.toolName)) {
+      return { block: true, reason: "Spawned agents cannot contact the user. Send your question to team-lead using send_message." };
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extended-teams",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Control-first, session-connected subagents for Pi with live navigation and intent-tier routing",
   "repository": {
     "type": "git",