@fradser/pi-agent-teams 0.9.2 → 1.0.0

package/src/agent-host.ts

@@ -0,0 +1,64 @@
+/**
+ * Publish this package as the `agent` tool's coordinator.
+ *
+ * `@fradser/pi-subagents` owns the child process and knows nothing about teams. It
+ * reaches a team spawn only through this seam, and without a host published it
+ * takes its standalone path and delivers a Session Result itself. A hosted child
+ * instead uses the team's attempt-bound report pipeline; exactly one path owns
+ * each result.
+ *
+ * Publishing also moves spawn to the team path as a side effect, and that is
+ * intended: the team path is the one that assigns work, records the attempt, and
+ * routes the result. The difference is observable — the team path refuses a name
+ * with no role, because a resident is a role with a process attached, while the
+ * standalone path will synthesise one — and `features/` pins it.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { setAgentHost, snapshotWorkContext, type AgentStartRequest } from "@fradser/pi-subagents";
+import { authorizeResidentInput, interruptResidentSequence, sendResidentSequence, shutdownAgentExact, spawnAgent } from "./team-machine.ts";
+
+/** Wire `agent` to this package's spawn and shutdown. Safe to call more than
+ *  once: a reload republishes rather than stacking hosts. */
+export function publishAgentHost(sessionManager?: ExtensionContext["sessionManager"]): void {
+  setAgentHost({
+    async start(request: AgentStartRequest) {
+      const spawned = spawnAgent({
+        name: request.name,
+        role: request.name,
+        ...(request.model ? { model: request.model } : {}),
+        ...(request.prompt ? { prompt: request.prompt } : {}),
+        ...(request.tools !== undefined ? { tools: request.tools } : {}),
+        // Resolve disk roles against the machine's project cwd, not this
+        // module's process.cwd(); the disk definition always wins inline input.
+        ...(request.definition ? { definition: request.definition } : {}),
+        // `fork` asks for a snapshot of the leader's active context. The snapshot
+        // is taken here rather than in the tool, because the tool has no session
+        // manager and the seam is what owns this package's spawn.
+        ...(request.fork && sessionManager
+          ? { context: snapshotWorkContext(sessionManager) }
+          : {}),
+      });
+      if (!spawned.ok) return spawned;
+      const agent = spawned.agent;
+      // Prompted starts await accepted input; idle starts await native readiness.
+      // Neither outcome is proof the child's work has completed.
+      if (spawned.readiness) {
+        const failure = await spawned.readiness;
+        if (failure) return { ok: false as const, error: failure };
+      }
+      return {
+        ok: true as const,
+        session: exactRoute(agent.name, agent.spawnId),
+      };
+    },
+    authorizeInput: authorizeResidentInput,
+    send: sendResidentSequence,
+    interrupt: interruptResidentSequence,
+    stop: (name, spawnId) => shutdownAgentExact(name, spawnId),
+  });
+}
+
+function exactRoute(name: string, spawnId: string): string {
+  return `session:${name}:${spawnId}`;
+}

package/src/capability-tools.ts

@@ -0,0 +1,34 @@
+/**
+ * The coordination capability set this package contributes to a spawned child,
+ * and the worker extension entry that registers it.
+ *
+ * These live in their own dependency-free module rather than beside the
+ * registrations in `worker.ts` because two consumers need them and one of them
+ * is imported by `worker.ts`: `tool-copy.ts` renders the effective grant, and
+ * `team-machine.ts` passes both to the spawner. Declaring them in `worker.ts`
+ * would make `tool-copy.ts` import it and close a cycle.
+ *
+ * The spawner hardcodes none of this. A consumer that loads only its own worker
+ * extension advertises only what it implements, which is what keeps
+ * `@fradser/pi-subagents` from granting `work` and `agent_event` when it is
+ * installed without this package.
+ */
+
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Tool ids registered by this package's worker extension inside a child.
+ *  Kept in sync with the `registerTool` calls in `worker.ts`. */
+export const WORKER_CAPABILITY_TOOLS: readonly string[] = [
+  "message",
+  "task",
+];
+
+/** This package's worker extension entry, passed to a spawned child with `-e`.
+ *  `--no-extensions` disables discovered extensions but still loads explicit
+ *  paths. `src/index.ts` is the extension module; the package-root `index.ts`
+ *  only re-exports it. */
+export const WORKER_EXTENSION_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "index.ts",
+);

package/src/guidance.ts

@@ -1,5 +1,5 @@
-import { AGENT_REFERENCE_PATH, formatAgentGuidance } from "./agents.ts";
-import { WORKER_BUILTIN_TOOLS } from "./worker-tools.ts";
+import { AGENT_REFERENCE_PATH, formatAgentGuidance } from "@fradser/pi-subagents";
+import { AGENT_BUILTIN_TOOLS } from "@fradser/pi-subagents";
 
 // One delivery contract for both idle and active Leader prompts.
 const LEADER_DELIVERY_GUIDANCE = `
@@ -39,16 +39,20 @@ is not a new broad review; broaden only when scope or risk changes.
 export const WORKER_GUIDANCE = `
 ## Agent Teams Worker Protocol
 
-You execute one current Work Item at a time. Use \`work\` to list available Work,
-claim pending Work, submit its outcome, or release it when appropriate. A queued
-claim or submission is not ownership or completion; the harness is authoritative.
-
-Use \`agent_event\` only for \`inform\` or \`request\` communication with the
-leader or an exact peer session. It arrives at the next safe tool boundary or wakes an idle leader. It cannot complete, release, reopen, or reassign
-Work. The runtime delivers ordinary final answers automatically for the current Work
+You execute one current Task at a time. Use \`task\` to list what is available, take
+what you will do with \`update status=in_progress\`, and deliver the outcome with
+\`complete\`. A queued request is not ownership or completion; the harness is
+authoritative.
+
+Use \`message\` only for \`inform\` or \`request\` communication with the
+leader or an exact peer session. It arrives at the next safe tool boundary or wakes an idle recipient. It cannot take, complete, reopen, or reassign
+a Task. Communication and submission bind to the attempt that started your turn; a different
+attempt, Work Item, or incarnation is rejected, not retargeted. After a submission or
+cancellation acknowledgement, end the turn.
+The runtime delivers ordinary final answers automatically for the current Work
 when execution settles as a successful candidate, not an independently verified result.
 If you cannot perform the requested work (including missing tools), you must use
-\`work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })\`.
+\`task({ action: "complete", outcome: "failed", result: "Blocker and unverified work" })\`.
 Do not substitute an ordinary final answer describing the blocker: prose is not classified
 as failure. Ungated acceptance is not independently verified. Send intermediate events only for blockers needing a decision, changed
 constraint, or decision request; never bare
@@ -69,18 +73,18 @@ completion or repeat unchanged findings.
 export function buildIdleLeaderGuidance(cwd?: string): string {
   return `## Agent Teams
 
-Use \`agent\` with an explicit action: \`delegate\` for new independent Work,
-\`start\` for an unassigned resident, \`inspect\` for Presence, and \`stop\` with
-an exact returned session handle. Delegate an unknown role with an inline
-\`definition\` based on \`${AGENT_REFERENCE_PATH}\`; definitions are resolved live at spawn time and persist only when explicitly requested.
+Use the selected subagent interface. The four intent tools are the only child
+tool surface: \`agent_start\` with a prompt, \`agent_input\` with delivery next or steer,
+\`agent_list\` for Presence, and \`agent_stop\` for exact-session close.
+Identity selects saved \`agent.md\`; label is display only, as one lowercase hyphenated token. Temporary instructions stay in memory. Role reference: \`${AGENT_REFERENCE_PATH}\`.
 
-Choose explicit minimal tools: ${WORKER_BUILTIN_TOOLS.join(", ")} are canonical built-ins.
+Choose minimal canonical tools: ${AGENT_BUILTIN_TOOLS.join(", ")}.
 Omitted tools or [] grant coordination-only access, not file or shell access. Check the returned effective grant.
 Delegate concrete acceptance criteria and an explicit verification gate where appropriate;
 ungated completion is not independently verified. An inform needs no acknowledgment unless
 a decision or action changes. Do not narrate repeated reports.
 
-Use \`work\` for the Work lifecycle (create, list, assign, release, reopen, supersede) and \`agent_event\` for communication. Claim and submit belong to the worker Work interface, not the leader one.
+Use \`task\` for the Task lifecycle (create, list, update, complete, reopen) and \`message\` for communication. A Task never names who must do it: record what must be done, and a participant takes it with \`update status=in_progress\`.
 ${LEADER_DELIVERY_GUIDANCE}
 Available agents:
 ${formatAgentGuidance(cwd)}`;
@@ -89,37 +93,45 @@ ${formatAgentGuidance(cwd)}`;
 export function buildTeamLeaderGuidance(cwd?: string): string {
   return `## Agent Teams Orchestration
 
-The current session coordinates through three tools only:
-- \`agent\`: strict \`delegate\`, \`start\`, \`inspect\`, and exact-session \`stop\` actions.
-- \`work\`: create (subject), list, assign (id, target.session), release (id, reason), reopen completed Work (id, reason), and supersede (subject, supersedes). Worker-only claim and submit are not leader actions.
-- \`agent_event\`: communication-only \`inform\` or \`request\` messages.
+The current session coordinates through three tool families:
+- Subagents: \`agent_start\`, \`agent_input\` (delivery next or steer), \`agent_stop\`, and \`agent_list\`. Disk \`agent.md\` supplies identity. Use exact sessions and reuse them for dependent follow-ups.
+- \`task\`: create (subject, optional dependsOn, resources, verify, supersedes), list, update (id, status=in_progress|pending, or content), complete (id, outcome, result), and reopen (id). One vocabulary for every participant.
+- \`message\`: \`inform\` or \`request\` messages.
 
 Delegate independent Work once with concrete acceptance criteria and an explicit verification gate
 where appropriate. Ungated completion is not independently verified. Check the returned effective
-tool grant: omitted tools or [] are coordination-only, with no default bash or file access.
-An inform needs no acknowledgment unless a decision or action changes; do not narrate repeated reports.
-Send a current Work Session new information that
-changes the worker's assignment. Do not ask for progress reports or repeat instructions.
-The worker autonomously completes its assignment. Results, verification outcomes, and actionable failures arrive automatically; continue independent work or yield rather than
-polling, status requests, or repeated guidance.
-
-Agent session handles are incarnation-bound. Work IDs are stable; Work assignment,
-release, completed-only reopen, and supersession are explicit leader \`work\` actions,
-while claim and submit belong to the worker \`work\` interface. Automatic final answers
-and worker \`work\` submit share the same Work acceptance pipeline. Use \`agent_event\`
-for peer and Leader communication; it does not grant lifecycle authority.
+tool grant: omitted tools or [] are coordination-only, with no bash or file access.
+An inform needs no acknowledgment unless a decision changes.
+Send a Work Session new information that changes its assignment; each message is the whole update.
+The worker autonomously completes its assignment. Results, verification outcomes and actionable failures
+arrive as messages; keep working on your own assignment while they come.
+
+Agent session handles are incarnation-bound. Task IDs are stable, and a Task names
+no owner: whoever acts on it holds it, and holding ends at \`complete\`, at process
+exit, or at exact-session stop — there is no release verb. Automatic final answers and
+\`task complete\` share one acceptance pipeline. \`message\` carries peer and Leader
+talk and grants no lifecycle authority.
 
 ${LEADER_DELIVERY_GUIDANCE}
 ### Teammates are autonomous: recover, never punish
 
-For recovery, keep the existing Work ID: request explicit \`work release\` and await authoritative release before \`work assign\` to the chosen exact session. A queued release or a no-write message is not released authority. Do not create a competing duplicate through \`agent delegate\`. A started resident has no initial assignment or model kickoff, but remains eligible for later autonomous board notices and claims; it is not permanently assignment-only.
+For recovery, keep the existing Task ID. Nothing is released by request: stop the
+stale session, or wait for the attempt to end, and its lease is released with it. Do
+not create a competing duplicate through another startup. A started
+resident with no prompt has no initial work and no model kickoff, but remains
+eligible for later tasks notices and takes work itself; it is not permanently idle.
+
+Observe stalled sessions in \`/agent-teams\`; the harness leaves every child to its Leader. Exact-session
+stop ends a child whose Work is delivered or abandoned — completion lives in the Work Item.
 
-Observe stalled sessions in \`/agent-teams\`. The harness never reclaims, restarts, or replaces a teammate. Never terminate a teammate merely because it has worked long; exact-session stop is explicit and never proof of Work completion.
+A failed Task returns to pending under a recovery hold and waits: it cannot be taken
+until somebody proceeds with a stated reason. Retired attempts' reports stop
+instructing you.
 
-### Yield while teammates work
+### Yield while agents work
 
-Continue independent work while teammates run. If none remains, end the turn; results resume the session automatically.
-Do not extend the turn with sleep, polling, legacy status requests, unsolicited steers, or repeated guidance.
+Continue independent work while agents run, and end the turn when the work in hand is done; a result
+resumes the session and opens the next one.
 
 Available agents:
 ${formatAgentGuidance(cwd)}

package/src/index.ts

@@ -1,3 +1,4 @@
+import { isTaskReplaced } from "@fradser/pi-tasks";
 /**
  * pi-agent-teams-fradser — Pi extension for Claude-style resident agent
  * teams. Composition only: worker capability registration, session lifecycle,
@@ -8,16 +9,17 @@
 import { getMarkdownTheme, keyHint, ToolExecutionComponent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildIdleLeaderGuidance, buildTeamLeaderGuidance, WORKER_GUIDANCE } from "./guidance.ts";
-import { clearSessionAgents } from "./agents.ts";
-import { getConfirmedStopTime, initTeamMachine, markTeammateFinished, removeRuntimeDir, shutdownTeamMachine, syncLeaderContext, teardownTeammates } from "./team-machine.ts";
+import { publishAgentHost } from "./agent-host.ts";
+import { getConfirmedStopTime, initTeamMachine, markTeammateFinished, onTaskChanged, onTaskCreated, onTaskTaken, removeRuntimeDir, shutdownTeamMachine, syncLeaderContext, teardownAgents } from "./team-machine.ts";
 import { cleanupExpiredStateDirs } from "./statefile.ts";
-import { livingTeammates, listTasks, resetState } from "./state.ts";
+import { getTask, getAgent, livingAgents, listTasks, resetState } from "./state.ts";
+import { configureTeamActivity } from "./activity.ts";
 import { ensureTeamWidget, refreshTeamUI, stopUiTimers } from "./ui.ts";
 import { registerLeaderTools, registerTeamCommand } from "./tools.ts";
-import { registerWorkerCapabilities, workerBinding } from "./worker.ts";
+import { registerChildCapabilities, workerBinding } from "./worker.ts";
 import { plainText } from "./tool-copy.ts";
-import { agentColor, bindLifecycleRenderers, clearPiStatus, createToolExecutionWrapper, eventToolLifecycle, formatAgentMessagePrefix, notifyPi, renderAgentMessageBand } from "@fradser/pi-kit";
-import { annotateReportDelivery, formatReports, groupReportsByTeammate, TEAMMATE_HARNESS_MESSAGE_TYPE, TEAMMATE_REPORT_MESSAGE_TYPE, type LeaderReport } from "./leader-reports.ts";
+import { agentColor, bindLifecycleRenderers, clearPiStatus, createToolExecutionWrapper, eventToolLifecycle, formatAgentMessagePrefix, hiddenThinkingEnabled, notifyPi, renderAgentMessageBand } from "@fradser/pi-kit";
+import { annotateReportDelivery, formatReports, groupReportsByAgent, AGENT_HARNESS_MESSAGE_TYPE, AGENT_REPORT_MESSAGE_TYPE, type LeaderReport } from "@fradser/pi-subagents";
 import { Box, Markdown, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 /** Geometry bound once: harness event rows share hint and wrapping. */
@@ -34,13 +36,52 @@ let leaderPi: ExtensionAPI | undefined;
 let leaderCtx: ExtensionContext | undefined;
 
 export const TEAMMATE_FINISHED_ENTRY_TYPE = "agent-teams-teammate-finished";
+/** Audit entry for a retired attempt's nonterminal report. The evidence stays in the
+ * session while the context projection stops treating it as a current instruction;
+ * without a renderer the retained entry would be invisible in the transcript. */
+export const TEAMMATE_HISTORICAL_ENTRY_TYPE = "agent-teams-historical-report";
+
+/** One entry per retained report, so a re-delivered report cannot multiply its own
+ * audit trail. Bounded the same way the finish announcements are. */
+const HISTORICAL_ENTRY_LIMIT = 512;
+const retainedHistoricalReports = new Set<string>();
+function rememberRetainedReport(report: LeaderReport): boolean {
+  const key = [
+    report.agent ?? "",
+    report.spawnId ?? "",
+    report.eventId ?? "",
+    report.timestamp ?? 0,
+  ].join(":");
+  if (retainedHistoricalReports.has(key)) return false;
+  retainedHistoricalReports.add(key);
+  while (retainedHistoricalReports.size > HISTORICAL_ENTRY_LIMIT) {
+    const oldest = retainedHistoricalReports.values().next().value;
+    if (oldest === undefined) break;
+    retainedHistoricalReports.delete(oldest);
+  }
+  return true;
+}
+
+/** Accepted outcomes remain evidence even after their process exits. Only
+ * nonterminal coordination loses current authority when its attempt retires; the
+ * source report stays in the session as the visible audit trail. */
+function isHistoricalReport(report: LeaderReport): boolean {
+  if (report.origin === "harness" || report.harnessEvent || report.finished
+    || report.status === "completed" || report.status === "failed") return false;
+  if (!report.spawnId || !report.agent) return false;
+  const worker = getAgent(report.agent);
+  if (!worker || worker.spawnId !== report.spawnId || worker.status === "stopped") return true;
+  if (report.assignmentId !== worker.assignment?.id || worker.assignment?.closed || worker.reportSequenceEnded) return true;
+  const task = worker.currentTaskId ? getTask(worker.currentTaskId) : undefined;
+  return isTaskReplaced(task) || task?.status === "completed";
+}
 
 function sendLeaderReport(report: LeaderReport): void {
   try {
     leaderPi?.sendMessage({
       customType: report.origin === "harness" || report.harnessEvent
-        ? TEAMMATE_HARNESS_MESSAGE_TYPE
-        : TEAMMATE_REPORT_MESSAGE_TYPE,
+        ? AGENT_HARNESS_MESSAGE_TYPE
+        : AGENT_REPORT_MESSAGE_TYPE,
       content: formatReports([report]),
       display: true,
       details: report,
@@ -54,7 +95,7 @@ function sendLeaderReport(report: LeaderReport): void {
 }
 
 export function hasActiveTeamState(): boolean {
-  return livingTeammates().length > 0 || listTasks().length > 0;
+  return livingAgents().length > 0 || listTasks().length > 0;
 }
 
 function extractHarnessReport(details: unknown): LeaderReport | undefined {
@@ -64,13 +105,19 @@ function extractHarnessReport(details: unknown): LeaderReport | undefined {
 
 export default function (pi: ExtensionAPI) {
   if (workerBinding()) {
-    const workerToolDisclosure = registerWorkerCapabilities(pi);
+    const workerToolDisclosure = registerChildCapabilities(pi);
     pi.on("session_start", async () => {
       workerToolDisclosure.reset();
     });
     pi.on("before_agent_start", async (event) => {
-      workerToolDisclosure.update(event.prompt);
-      return { systemPrompt: event.systemPrompt + WORKER_GUIDANCE };
+      // A custom start carries a message and no prompt, so the presence test keeps this correct
+      // against the event union; the disclosure tracks delivered text only.
+      workerToolDisclosure.update("prompt" in event ? event.prompt : undefined);
+      const options = event.systemPromptOptions;
+      if (!("sections" in options) || !options.sections || typeof options.sections !== "object") {
+        throw new Error("Agent Teams requires Pi structured prompt sections.");
+      }
+      Object.assign(options.sections, { agent_teams_worker: WORKER_GUIDANCE.trim() });
     });
     pi.on("session_shutdown", async () => {
       workerToolDisclosure.reset();
@@ -79,13 +126,20 @@ export default function (pi: ExtensionAPI) {
   }
 
   leaderPi = pi;
+  // The team widget and console rows share subagents' hidden-thinking policy.
+  configureTeamActivity(() => hiddenThinkingEnabled(pi));
   const deliveries = new WeakMap<object, LeaderReport[]>();
   pi.registerEntryRenderer(TEAMMATE_FINISHED_ENTRY_TYPE, (entry, _options, theme) => {
     const data = entry.data as { teammate?: string; agent?: string } | undefined;
     const name = data?.teammate ?? data?.agent ?? "teammate";
     return new Text(theme.fg("success", `Assignment for @${name} finished.`), 0, 0);
   });
-  pi.registerMessageRenderer(TEAMMATE_HARNESS_MESSAGE_TYPE, (message, { expanded }, theme) => {
+  pi.registerEntryRenderer(TEAMMATE_HISTORICAL_ENTRY_TYPE, (entry, _options, theme) => {
+    const data = entry.data as { teammate?: string; agent?: string } | undefined;
+    const name = data?.teammate ?? data?.agent ?? "teammate";
+    return new Text(theme.fg("dim", `Historical report from @${name} retained for audit; it no longer instructs.`), 0, 0);
+  });
+  pi.registerMessageRenderer(AGENT_HARNESS_MESSAGE_TYPE, (message, { expanded }, theme) => {
     const report = extractHarnessReport(message.details);
     if (!report) return new Text(String(message.content), 0, 0);
     const event = report.harnessEvent;
@@ -94,7 +148,7 @@ export default function (pi: ExtensionAPI) {
       { hostComponent: ToolExecutionComponent, ui: leaderCtx?.ui, cwd: leaderCtx?.cwd },
     )(message, { expanded }, theme);
   });
-  pi.registerMessageRenderer(TEAMMATE_REPORT_MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
+  pi.registerMessageRenderer(AGENT_REPORT_MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
     const reports = deliveries.get(message) ?? extractReports(message.details);
     if (reports.length === 0) {
       const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
@@ -106,9 +160,9 @@ export default function (pi: ExtensionAPI) {
       (opt, currentTheme) => {
         const effTheme = currentTheme ?? theme;
         if (!opt.expanded) {
-          const groups = groupReportsByTeammate(reports);
+          const groups = groupReportsByAgent(reports);
           const band = renderAgentMessageBand(
-            groups.map((group) => ({ direction: "from", teammate: group.teammate, count: group.reports.length })),
+            groups.map((group) => ({ direction: "from", teammate: group.agent, count: group.reports.length })),
             { theme: effTheme, fit: truncateToWidth, visibleWidth, wrapDetail: wrapTextWithAnsi, expandHint: keyHint("app.tools.expand", "to expand") },
           );
           if (!reports.some((report) => report.deliveredAfterStop)) return band;
@@ -119,9 +173,9 @@ export default function (pi: ExtensionAPI) {
         }
         const box = new Box(outputPad, 1, (text) => effTheme.bg("customMessageBg", text));
         for (const [index, report] of reports.entries()) {
-          const teammate = report.teammate ?? report.agent ?? "teammate";
+          const agent = report.agent ?? "agent";
           const prefix = effTheme.fg("customMessageLabel", effTheme.bold(formatAgentMessagePrefix("from")));
-          const name = effTheme.fg(agentColor(teammate), `@${teammate}`);
+          const name = effTheme.fg(agentColor(agent), `@${agent}`);
           const delivery = report.deliveredAfterStop ? effTheme.fg("warning", " (late delivery; process stopped)") : "";
           box.addChild(new Text(`${prefix}${name}${delivery}`, 0, 0));
           box.addChild(new Markdown(report.body, 0, 0, getMarkdownTheme(), {
@@ -144,8 +198,49 @@ export default function (pi: ExtensionAPI) {
   registerLeaderTools(pi);
   registerTeamCommand(pi);
 
+  // The tasks belongs to @fradser/pi-tasks, which registers the `task` tool
+  // itself. This package subscribes to what the tasks announces rather than
+  // being called by it, so pi-tasks never has to know a resident exists and a
+  // standalone tasks with nobody listening still works.
+  //
+  // Guarded because subscribing is optional: a host without an event bus must
+  // degrade to no coordination, not to a failed load. Tasks transitions still
+  // record correctly; only the noticing is skipped.
+  if (typeof pi.events?.on === "function") {
+    pi.events.on("pi-tasks:task-created", (payload) => {
+      onTaskCreated(payload as { id: string; replaced?: string[] });
+    });
+    pi.events.on("pi-tasks:task-taken", (payload) => {
+      onTaskTaken(payload as { id: string });
+    });
+    for (const channel of ["pi-tasks:task-completed", "pi-tasks:task-reopened", "pi-tasks:task-updated"]) {
+      pi.events.on(channel, () => onTaskChanged());
+    }
+  }
+
+  // Pi cannot retract one already-queued steer. The persisted record stays for
+  // audit, and this projection keeps a retired attempt's nonterminal text from
+  // acting as a current instruction. Deliberate trade-off: while such a record
+  // exists the projection is recomputed per request, so a session that retires a
+  // report pays a prompt/tool replay each turn. Correctness wins over cache
+  // warmth here; the alternative needs an SDK API to rewrite a stored message.
+  pi.on("context", (event) => {
+    let changed = false;
+    const messages = event.messages.flatMap((message) => {
+      if (message.role !== "custom" || message.customType !== AGENT_REPORT_MESSAGE_TYPE) return [message];
+      const reports = extractReports(message.details);
+      if (reports.length === 0) return [message];
+      const current = reports.filter((report) => !isHistoricalReport(report));
+      if (current.length === reports.length) return [message];
+      changed = true;
+      return current.length === 0 ? [] : [{ ...message, content: formatReports(current),
+        details: current.length === 1 ? current[0] : { reports: current } }];
+    });
+    return changed ? { messages } : undefined;
+  });
+
   pi.on("message_start", (event) => {
-    if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
+    if (event.message.role !== "custom" || event.message.customType !== AGENT_REPORT_MESSAGE_TYPE) return;
     const deliveredAt = Date.now();
     deliveries.set(event.message, extractReports(event.message.details).map((report) => annotateReportDelivery(
       report, deliveredAt, report.spawnId ? getConfirmedStopTime(report.spawnId) : undefined,
@@ -153,16 +248,34 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("message_end", async (event) => {
-    if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
+    if (event.message.role !== "custom" || event.message.customType !== AGENT_REPORT_MESSAGE_TYPE) return;
     const deliveredAt = Date.now();
     const reports = deliveries.get(event.message) ?? extractReports(event.message.details).map((report) => annotateReportDelivery(
       report, deliveredAt, report.spawnId ? getConfirmedStopTime(report.spawnId) : undefined,
     ));
     if (reports.length === 0) return;
     for (const report of reports) {
+      // A retired attempt's nonterminal report keeps its evidence in the session but must
+      // stop instructing the leader. The context projection already excludes it from
+      // future requests; this entry is what keeps the retained evidence visible rather
+      // than silently dropped, and is appended once per report at the delivery seam.
+      if (isHistoricalReport(report)) {
+        if (rememberRetainedReport(report)) {
+          pi.appendEntry(TEAMMATE_HISTORICAL_ENTRY_TYPE, {
+            agent: report.agent,
+            spawnId: report.spawnId,
+            assignmentId: report.assignmentId,
+            workId: report.workId,
+            eventId: report.eventId,
+            status: report.status,
+            timestamp: report.timestamp,
+            body: report.body,
+          });
+        }
+        continue;
+      }
       if (!markTeammateFinished(report)) continue;
       pi.appendEntry(TEAMMATE_FINISHED_ENTRY_TYPE, {
-        teammate: report.teammate ?? report.agent,
         agent: report.agent,
         assignmentId: report.assignmentId,
         workId: report.workId,
@@ -185,7 +298,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    clearSessionAgents();
+    // Session-only definitions belong to the execution extension. Clearing
+    // them here would discard temporary history under another package's owner.
     resetState();
     leaderCtx = ctx;
     ensureTeamWidget(ctx);
@@ -195,7 +309,10 @@ export default function (pi: ExtensionAPI) {
         refreshTeamUI(leaderCtx);
       },
     });
-    clearPiStatus(ctx.ui, "teammate");
+    // The execution extension owns the tool. Hosted incarnations use our
+    // report/controls; standalone incarnations keep their own result owner.
+    publishAgentHost(ctx.sessionManager);
+    clearPiStatus(ctx.ui, "agent");
     refreshTeamUI(ctx);
     void cleanupExpiredStateDirs(STATE_DIR_MAX_AGE_MS);
   });
@@ -203,16 +320,18 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx) => {
     leaderCtx = ctx;
     const teamIsActive = hasActiveTeamState();
-    return {
-      systemPrompt: event.systemPrompt + (teamIsActive
-        ? buildTeamLeaderGuidance(ctx?.cwd ?? process.cwd())
-        : buildIdleLeaderGuidance(ctx?.cwd ?? process.cwd())),
-    };
+    const options = event.systemPromptOptions;
+    if (!("sections" in options) || !options.sections || typeof options.sections !== "object") {
+      throw new Error("Agent Teams requires Pi structured prompt sections.");
+    }
+    Object.assign(options.sections, { agent_teams_leader: (teamIsActive
+      ? buildTeamLeaderGuidance(ctx?.cwd ?? process.cwd())
+      : buildIdleLeaderGuidance(ctx?.cwd ?? process.cwd())).trim() });
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
     stopUiTimers();
-    const diagnostics = await teardownTeammates();
+    const diagnostics = await teardownAgents();
     for (const message of diagnostics) {
       notifyPi(ctx.ui, message, "warning");
     }
@@ -228,6 +347,6 @@ function extractReports(details: unknown): LeaderReport[] {
   if (Array.isArray(details)) return details as LeaderReport[];
   const typed = details as LeaderReport | { reports?: LeaderReport[] } | undefined;
   if (typed && "reports" in typed && Array.isArray(typed.reports)) return typed.reports;
-  if (typed && "teammate" in typed) return [typed as LeaderReport];
+  if (typed && ("agent" in typed || "teammate" in typed)) return [typed as LeaderReport];
   return [];
 }

package/src/recipient.ts

@@ -1,4 +1,4 @@
-import type { Teammate } from "./types.ts";
+import type { Agent } from "./types.ts";
 
 export function sessionRoute(name: string): string {
   return `session:${name}`;
@@ -13,7 +13,7 @@ export function parseExactSessionRoute(route: string): { name: string; spawnId:
   return match ? { name: match[1], spawnId: match[2] } : undefined;
 }
 
-export function resolveExactSession(route: string, roster: readonly Teammate[]): Teammate | undefined {
+export function resolveExactSession(route: string, roster: readonly Agent[]): Agent | undefined {
   const parsed = parseExactSessionRoute(route);
   if (!parsed) return undefined;
   return roster.find((teammate) => teammate.name === parsed.name && teammate.spawnId === parsed.spawnId && teammate.status !== "stopped");
@@ -24,7 +24,7 @@ export function resolveExactSession(route: string, roster: readonly Teammate[]):
  *  name cannot consume mail addressed to its predecessor. */
 export function resolveRecipient(
   to: string,
-  roster: ReadonlyArray<{ name: string; agent: string; status: string; spawnId?: string }>,
+  roster: ReadonlyArray<{ name: string; role: string; status: string; spawnId?: string }>,
 ): { name: string; spawnId?: string } {
   const exact = parseExactSessionRoute(to);
   if (exact) {
@@ -35,7 +35,7 @@ export function resolveRecipient(
   const explicit = to.startsWith("session:");
   const name = explicit ? to.slice("session:".length) : to;
   const living = roster.filter((entry) => entry.status !== "stopped");
-  const recipients = living.filter((entry) => entry.name === name || (!explicit && entry.agent === to));
+  const recipients = living.filter((entry) => entry.name === name || (!explicit && entry.role === to));
   if (recipients.length > 1) {
     throw new Error(`Ambiguous Agent @${to}. Use a precise route: ${recipients.map((entry) => entry.spawnId ? exactSessionRoute(entry.name, entry.spawnId) : sessionRoute(entry.name)).join(", ")}.`);
   }