pi-extended-teams 2.3.0 → 2.3.2

package/extensions/tools/team-tools.ts

@@ -10,15 +10,14 @@ import * as teams from "../../src/utils/teams";
 import * as runtime from "../../src/utils/runtime";
 import * as messaging from "../../src/utils/messaging";
 import * as writeQueue from "../../src/utils/write-queue";
-import { ACCEPTED_FAVORITE_MODEL_SLOTS, FAVORITE_MODEL_SLOTS, canonicalPersistedModelSlot, isFavoriteModelSlot, loadSettings, normalizeFavoriteModelSlot, requireFavoriteModelLevel, resolveModel, roleForFavoriteModelSlot, type AgentRole, type CanonicalFavoriteModelSlot } from "../../src/utils/settings";
+import { FAVORITE_MODEL_SLOTS, canonicalPersistedModelSlot, isFavoriteModelSlot, loadSettings, normalizeFavoriteModelSlot, requireFavoriteModelLevel, resolveModel, roleForFavoriteModelSlot, type AgentRole, type CanonicalFavoriteModelSlot } from "../../src/utils/settings";
 import type { Member } from "../../src/utils/models";
-import { CheckPolicySchema, normalizeCheckPolicy } from "../../src/results/check-policy";
-import { RepairPolicySchema, normalizeRepairPolicy } from "../../src/results/repair-policy";
-import { CheckpointPolicySchema } from "../../src/results/checkpoint-policy";
+import { normalizeCheckPolicy } from "../../src/results/check-policy";
+import { normalizeRepairPolicy } from "../../src/results/repair-policy";
 import { createCheckpointAssignment, captureCheckpointAssignment, continuationPrompt } from "../../src/results/checkpoint-assignment";
 import { assertUnusedContinuationRecipient, freshContinuationName } from "../../src/results/continuation-recipient";
 import { readCheckpoint } from "../../src/results/specialist-checkpoint";
-import { CompletionGroup, CompletionGroupPolicySchema, completionGroupIdentity, normalizeCompletionGroupPolicy, type CompletionGroupBinding } from "../../src/results/completion-group";
+import { CompletionGroup, completionGroupIdentity, normalizeCompletionGroupPolicy, type CompletionGroupBinding } from "../../src/results/completion-group";
 import { listStoredTeamReportEvents } from "../../src/utils/report-events";
 import { enqueueCompletionGroupDeliveries } from "../../src/results/completion-group-delivery";
 import { shouldSuppressLeadReportInjection } from "../../src/utils/workflow-metadata";
@@ -48,6 +47,8 @@ import {
   type QueuedAgentStatus,
 } from "./agent-status-tool";
 
+import { publicTeamToolMetadata } from "./public-team-tools";
+
 export const CHILD_AGENT_LIFECYCLE_PROBE = "pi-extended-teams:child-agent-lifecycle-probe";
 
 interface ChildAgentLifecycleProbe {
@@ -74,6 +75,8 @@ export interface TeamToolsOptions {
   getSessionCtx?(): any;
   setSessionCtx?(ctx: any): void;
   pendingChildController?: PendingChildController;
+  isHostAttached?(): boolean;
+  waitForHost?(): Promise<void>;
 }
 
 export interface NestedReadAgentToolBinding {
@@ -92,6 +95,9 @@ export interface TeamToolsRuntime {
   createNestedReadAgentTools(binding: NestedReadAgentToolBinding): any[];
   nestedChildSnapshot(binding: NestedReadAgentToolBinding): NestedChildSnapshot;
   cancelQueuedAgent(teamName: string, agentName: string): boolean | Promise<boolean>;
+  hasPendingWork(): boolean;
+  closeAdmission(): void;
+  resumeQueues(): void;
 }
 
 interface SpawnTeammateOptions {
@@ -131,6 +137,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       createNestedReadAgentTools: () => [],
       nestedChildSnapshot: () => ({ running: 0, queued: 0 }),
       cancelQueuedAgent: () => false,
+      hasPendingWork: () => false,
+      closeAdmission: () => {},
+      resumeQueues: () => {},
     };
   }
 
@@ -389,10 +398,29 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     return pending?.settled;
   }
   let lifecycleProbeCleanedUp = false;
+  let shutdownStarted = false;
+  const closeAdmission = () => { lifecycleProbeCleanedUp = true; };
+  const admissions = new Set<Promise<void>>();
+  async function trackAdmission<T>(action: () => Promise<T>): Promise<T> {
+    if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+    let settle!: () => void;
+    const settled = new Promise<void>(resolve => {
+      settle = resolve;
+    });
+    admissions.add(settled);
+
+    try {
+      return await action();
+    } finally {
+      admissions.delete(settled);
+      settle();
+    }
+  }
   let pendingChildCancelUnsubscribe = (): void => {};
   pi.on?.("session_shutdown", async () => {
-    if (lifecycleProbeCleanedUp) return;
-    lifecycleProbeCleanedUp = true;
+    if (shutdownStarted) return;
+    shutdownStarted = true;
+    closeAdmission();
     const settlements: Promise<void>[] = [];
     for (const pending of checkpointAdmissions.values()) {
       pending.controller.abort(new Error("Checkpoint preparation cancelled: session is closing."));
@@ -404,8 +432,17 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         if (removed?.groupSettlement) settlements.push(removed.groupSettlement);
       }
     }
-    try { await Promise.all(settlements); }
+    let deadline: ReturnType<typeof setTimeout> | undefined;
+    const admissionSettlement = Promise.race([
+      Promise.all([...admissions]),
+      new Promise<never>((_resolve, reject) => {
+        deadline = setTimeout(() => reject(new Error("Agent admissions are still settling during shutdown.")), 2_500);
+        deadline.unref?.();
+      }),
+    ]);
+    try { await Promise.all([...settlements, admissionSettlement]); }
     finally {
+      clearTimeout(deadline);
       if (typeof lifecycleProbeUnsubscribe === "function") lifecycleProbeUnsubscribe();
       pendingChildCancelUnsubscribe();
       lifecycleFenceUnsubscribe();
@@ -864,7 +901,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   }
 
   async function drainQueuedReadSpawns(teamName: string): Promise<void> {
-    if (lifecycleProbeCleanedUp) return;
+    if (lifecycleProbeCleanedUp || options.isHostAttached?.() === false) return;
     if (readQueueDrainingTeams.has(teamName)) {
       pendingQueueDrains.add(teamName);
       return;
@@ -872,7 +909,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     readQueueDrainingTeams.add(teamName);
     try {
       let progressed = true;
-      while (progressed && !lifecycleProbeCleanedUp) {
+      while (progressed && !lifecycleProbeCleanedUp && options.isHostAttached?.() !== false) {
         progressed = false;
         for (const queued of readQueue(teamName)) {
           if (queued.admissionError) continue;
@@ -1274,39 +1311,17 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   }
   pi.events?.on?.("pi-extended-teams:orchestration-request", (payload: any) => {
     if (payload?.type !== "ensure_team" && payload?.type !== "spawn_teammate_once") return handleOrchestrationRequest(payload);
-    return withPublicScope(String(payload?.params?.team_name || ""), () => handleOrchestrationRequest(payload))
+    return trackAdmission(() => withPublicScope(String(payload?.params?.team_name || ""), () => handleOrchestrationRequest(payload)))
       .catch(error => emitOrchestrationResponse(payload?.requestId, payload?.type, { ok: false, error: error instanceof Error ? error.message : String(error) }));
   });
 
-  const levelDescription = "Required intent tier. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Read tiers: read-collect gathers bounded facts without owning the conclusion; read-review is the normal default for focused review, verification, and bounded synthesis; read-analyze explains behavior or root cause across connected evidence; read-critical is only for irreducible high-stakes security, architecture, concurrency, migration, or data-correctness reasoning. Write tiers: write-patch makes a narrow localized change; write-feature implements a bounded feature with a known design; write-system owns a cross-cutting integration or refactor within explicitly claimed files; write-critical is only for high-risk security, concurrency, recovery, migration, or data-integrity changes. Prefer canonical tiers; legacy reading-*/writing-* aliases remain accepted for this minor release. Do not pass role, model, or thinking directly; see README.md.";
-  const publicAgentBaseParams = {
-    name: Type.Optional(Type.String({ description: "Stable display name. Defaults to a generated agent name." })),
-    prompt: Type.String({ description: "The agent's assignment, relevant prior context, evidence already gathered, constraints, and report shape." }),
-    cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the lead session cwd." })),
-    checks: Type.Optional(CheckPolicySchema),
-    repair: Type.Optional(RepairPolicySchema),
-    checkpoint: Type.Optional(CheckpointPolicySchema),
-    continue_from: Type.Optional(Type.String({ description: "Continue this checkpoint as a fresh recipient/run with the current assignment and tier. name is a prefix, not a recipient to reuse." })),
-    session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Optional filtered snapshot of the lead's active session branch. Use lazy only when omitted session history may materially affect the lane; the child reads it on demand rather than receiving transcript content in its prompt.", default: "none" })),
-    metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
-    allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Opt in eligible depth-0 write-feature/write-critical agents to restricted read-only child spawning.", default: false })),
-  };
-  const publicAgentParams = {
-    ...publicAgentBaseParams,
-    model_slot: StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription, default: "read-review" }),
-  };
-  const publicSwarmAgentParams = {
-    ...publicAgentBaseParams,
-    model_slot: Type.Optional(StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription })),
-  };
-
   function generatedAgentName(index?: number): string {
     const position = index === undefined ? "" : `-${index + 1}`;
     return `agent-${Date.now().toString(36)}${position}-${crypto.randomUUID().slice(0, 8)}`;
   }
 
   function spawnPublicAgent(params: any, ctx: any, signal?: AbortSignal): Promise<{ content: any[]; details: any }> {
-    return withPublicScope(currentSessionAgentGroupName(ctx), () => spawnPublicAgentInScope(params, ctx, signal));
+    return trackAdmission(() => withPublicScope(currentSessionAgentGroupName(ctx), () => spawnPublicAgentInScope(params, ctx, signal)));
   }
 
   async function spawnPublicAgentInScope(params: any, ctx: any, signal?: AbortSignal): Promise<{ content: any[]; details: any }> {
@@ -1343,13 +1358,18 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     model_slot: Type.Optional(StringEnum(NESTED_READ_MODEL_SLOTS, { description: "Canonical read-* tier, or inherit defaults.model_slot." })),
   };
 
-  async function spawnNestedReadAgent(
+  function spawnNestedReadAgent(params: any, binding: NestedReadAgentToolBinding, context = "spawn_agent") {
+    return trackAdmission(() => spawnNestedReadAgentInScope(params, binding, context));
+  }
+
+  async function spawnNestedReadAgentInScope(
     params: any,
     binding: NestedReadAgentToolBinding,
     context = "spawn_agent"
   ): Promise<{ content: any[]; details: any }> {
     rejectUnexpectedNestedParams(params, ["name", "prompt", "model_slot"], context);
     requireNestedReadSpawnLevel(params, context);
+    if (options.isHostAttached?.() === false) await options.waitForHost?.();
     await assertNestedParentAuthorized(binding.teamName, binding.parent.name, binding.parentRunId, binding.parent.cwd);
     const name = params.name || generatedAgentName();
     const result = await spawnTeammate({
@@ -1358,7 +1378,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       model_slot: params.model_slot,
       team_name: binding.teamName,
       cwd: binding.parent.cwd,
-    }, binding.outerCtx, {
+    }, options.isHostAttached ? options.getSessionCtx?.() ?? binding.outerCtx : binding.outerCtx, {
       nestedParent: {
         teamName: binding.teamName,
         name: binding.parent.name,
@@ -1446,113 +1466,104 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   pi.registerTool(statusTool());
 
   pi.registerTool({
-    name: "spawn_agent",
-    label: "Spawn Agent",
-    description: "Spawn one agent by intent tier only. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Give it the relevant goal, decisions, prior attempts, inspected evidence, constraints, and expected delta rather than a context-free task. Use session_context=lazy only as an on-demand fallback when omitted session history may materially matter; it never replaces a good mission prompt. read-review is the normal read default; use read-collect for bounded fact gathering, read-analyze for connected explanation/root cause, and read-critical only for irreducible high-stakes reasoning. For edits, choose write-patch, write-feature, write-system, or the rare high-risk write-critical by scope and risk. After spawning, do not duplicate or take over its lane; work only on unrelated work, then end the turn so the automatic report can resume you. One get_agent_status snapshot is allowed when current status is needed; never sleep, busy-wait, repeatedly read inbox/status, or treat healthy silence as failure. Wait for the actual report before synthesizing; intervene only on a reported blocker/error, actual health failure, or explicit user cancellation. model_slot selects behavior, model, and thinking; do not pass role, model, or thinking directly.",
-    parameters: Type.Object(publicAgentParams),
+    ...publicTeamToolMetadata.spawn_agent,
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
       return spawnPublicAgent(params, ctx, _signal);
     },
   });
 
   pi.registerTool({
-    name: "spawn_swarm_agents",
-    label: "Spawn Swarm Agents",
-    description: "Spawn a batch by intent tier only. Configured favorites take priority; unconfigured tiers inherit the current lead model and thinking. Give each lane the relevant goal, decisions, prior attempts, inspected evidence, constraints, and expected delta. Use session_context=lazy selectively as an on-demand fallback, never instead of a good mission prompt. Use read-review as the normal default, read-collect for bounded collection lanes, read-analyze for connected explanation, and read-critical only for irreducible high-stakes reasoning; choose write-patch/feature/system/critical by edit scope and risk. Each spawned lane is delegation-locked: do not duplicate or take it over. After unrelated work is done, end the turn so automatic reports can resume you. One get_agent_status snapshot is allowed when current status is needed; never sleep, busy-wait, repeatedly read inbox/status, or intervene early. Synthesize only after actual reports; intervene only on blocker/error, actual failure, or explicit cancellation. Each agent gets model_slot directly or from defaults; do not pass role, model, or thinking directly.",
-    parameters: Type.Object({
-      defaults: Type.Optional(Type.Object({
-        cwd: Type.Optional(Type.String()),
-        checks: Type.Optional(CheckPolicySchema),
-        repair: Type.Optional(RepairPolicySchema),
-        checkpoint: Type.Optional(CheckpointPolicySchema),
-        model_slot: Type.Optional(StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription })),
-        metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
-        session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Shared lazy session-reference policy.", default: "none" })),
-        allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Shared opt-in for eligible depth-0 write-feature/write-critical agents.", default: false })),
-      })),
-      completion_group: Type.Optional(CompletionGroupPolicySchema),
-      agents: Type.Array(Type.Object(publicSwarmAgentParams), { description: "Agents to spawn as one batch. Each one must have model_slot directly or inherit it from defaults." }),
-    }),
+    ...publicTeamToolMetadata.spawn_swarm_agents,
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
-      if (options.isTeammate) throw new Error("Only the lead session can spawn agents.");
-      if (!ctx) throw new Error("No active Pi session context is available for spawn_swarm_agents.");
-      if (!Array.isArray(params.agents) || params.agents.length === 0) throw new Error("spawn_swarm_agents requires at least one agent.");
-
-      const groupPolicy = normalizeCompletionGroupPolicy(params.completion_group);
-      const sessionId = getPiSessionId(ctx);
-      if (groupPolicy && (!sessionId || !_toolCallId?.trim())) throw new Error("Completion groups require a bound session and runtime submission identity.");
-      const mergedAgents = params.agents.map((agent: any, index: number) => {
-        const merged = mergeSwarmAgentParams(params.defaults || {}, agent);
-        merged.checkpoint = createCheckpointAssignment(merged.checkpoint, merged.prompt, merged.continue_from)?.policy;
-        if (merged.continue_from !== undefined) merged.name = freshContinuationName(merged.name || "agent", JSON.stringify([sessionId, _toolCallId, index, merged.continue_from]));
-        return merged;
-      });
-      const defaultModel = configuredFavoriteModelForSpawn(mergedAgents[0], ctx, "spawn_swarm_agents");
-      for (let index = 0; index < mergedAgents.length; index += 1) {
-        configuredFavoriteModelForSpawn(mergedAgents[index], ctx, `spawn_swarm_agents agent ${mergedAgents[index].name || index + 1}`);
-      }
-      const sessionName = await ensureCurrentSessionAgentGroup(ctx, defaultModel);
-      let group: CompletionGroup | undefined;
-      if (groupPolicy && sessionId) {
-        const identity = { teamName: sessionName, sessionId, submissionId: `tool:${_toolCallId}` };
-        const groupId = completionGroupIdentity(identity);
-        options.onCompletionGroupUse?.(groupId);
-        const config = await teams.readConfig(sessionName);
-        const reports = await listStoredTeamReportEvents(sessionName);
-        const inbox = await messaging.readInbox(sessionName, "team-lead", false, false);
-        const entries = ctx.sessionManager?.getBranch?.() ?? [];
-        const references = [...config.members.map(member => member.completionGroup),
-          ...readQueue(sessionName).map(queued => queued.member.completionGroup),
-          ...reports.map(report => report.completionGroup), ...inbox.map(message => message.metadata?.completionGroup),
-          ...entries.map((entry: any) => entry.message?.details?.completionGroup)];
-        if (references.some(binding => binding?.groupId === groupId)) new CompletionGroup(sessionName, groupId).read();
-        group = await CompletionGroup.create({ ...identity, policy: groupPolicy, members: mergedAgents.map((agent: any, index: number) => ({
-          name: paths.sanitizeName(agent.name || `agent-${crypto.createHash("sha256").update(`${_toolCallId}:${index}`).digest("hex").slice(0, 12)}`),
-          assignmentKey: crypto.createHash("sha256").update(JSON.stringify([agent, ctx.cwd])).digest("hex"),
-          suppressed: sessionName.startsWith("prompt-build-") || shouldSuppressLeadReportInjection(agent),
-        })) });
-        if (group && !group.created) return {
-          content: [{ type: "text", text: `Completion group ${group.groupId} already exists; no assignments replayed. State: ${group.journalPath}\n${AGENT_WAIT_CONTRACT}` }],
-          details: { session: sessionName, completionGroup: { groupId: group.groupId, journalPath: group.journalPath },
-            idempotent: true, spawned: [], failed: [], members: group.read().members },
-        };
-      }
-      const spawned: any[] = [];
-      const failed: Array<{ name: string; error: string }> = [];
+      return trackAdmission(async () => {
+        if (options.isTeammate) throw new Error("Only the lead session can spawn agents.");
+        if (!ctx) throw new Error("No active Pi session context is available for spawn_swarm_agents.");
+        if (!Array.isArray(params.agents) || params.agents.length === 0) throw new Error("spawn_swarm_agents requires at least one agent.");
+
+        const groupPolicy = normalizeCompletionGroupPolicy(params.completion_group);
+        const sessionId = getPiSessionId(ctx);
+        if (groupPolicy && (!sessionId || !_toolCallId?.trim())) throw new Error("Completion groups require a bound session and runtime submission identity.");
+        const mergedAgents = params.agents.map((agent: any, index: number) => {
+          const merged = mergeSwarmAgentParams(params.defaults || {}, agent);
+          merged.checkpoint = createCheckpointAssignment(merged.checkpoint, merged.prompt, merged.continue_from)?.policy;
+          if (merged.continue_from !== undefined) merged.name = freshContinuationName(merged.name || "agent", JSON.stringify([sessionId, _toolCallId, index, merged.continue_from]));
+          return merged;
+        });
+        const defaultModel = configuredFavoriteModelForSpawn(mergedAgents[0], ctx, "spawn_swarm_agents");
+        for (let index = 0; index < mergedAgents.length; index += 1) {
+          configuredFavoriteModelForSpawn(mergedAgents[index], ctx, `spawn_swarm_agents agent ${mergedAgents[index].name || index + 1}`);
+        }
+        const sessionName = await ensureCurrentSessionAgentGroup(ctx, defaultModel);
+        let group: CompletionGroup | undefined;
+        if (groupPolicy && sessionId) {
+          const identity = { teamName: sessionName, sessionId, submissionId: `tool:${_toolCallId}` };
+          const groupId = completionGroupIdentity(identity);
+          options.onCompletionGroupUse?.(groupId);
+          const config = await teams.readConfig(sessionName);
+          const reports = await listStoredTeamReportEvents(sessionName);
+          const inbox = await messaging.readInbox(sessionName, "team-lead", false, false);
+          const entries = ctx.sessionManager?.getBranch?.() ?? [];
+          const references = [...config.members.map(member => member.completionGroup),
+            ...readQueue(sessionName).map(queued => queued.member.completionGroup),
+            ...reports.map(report => report.completionGroup), ...inbox.map(message => message.metadata?.completionGroup),
+            ...entries.map((entry: any) => entry.message?.details?.completionGroup)];
+          if (references.some(binding => binding?.groupId === groupId)) new CompletionGroup(sessionName, groupId).read();
+          group = await CompletionGroup.create({ ...identity, policy: groupPolicy, members: mergedAgents.map((agent: any, index: number) => ({
+            name: paths.sanitizeName(agent.name || `agent-${crypto.createHash("sha256").update(`${_toolCallId}:${index}`).digest("hex").slice(0, 12)}`),
+            assignmentKey: crypto.createHash("sha256").update(JSON.stringify([agent, ctx.cwd])).digest("hex"),
+            suppressed: sessionName.startsWith("prompt-build-") || shouldSuppressLeadReportInjection(agent),
+          })) });
+          if (group && !group.created) return {
+            content: [{ type: "text", text: `Completion group ${group.groupId} already exists; no assignments replayed. State: ${group.journalPath}\n${AGENT_WAIT_CONTRACT}` }],
+            details: { session: sessionName, completionGroup: { groupId: group.groupId, journalPath: group.journalPath },
+              idempotent: true, spawned: [], failed: [], members: group.read().members },
+          };
+        }
+        const spawned: any[] = [];
+        const failed: Array<{ name: string; error: string }> = [];
 
-      for (let index = 0; index < mergedAgents.length; index += 1) {
-        const merged = mergedAgents[index];
-        const name = group?.read().members[index].name || merged.name || generatedAgentName(index);
-        try {
-          const result = await spawnTeammate({
-            ...merged,
-            name,
-            team_name: sessionName,
-          }, ctx, { allowNestedReadAgents: merged.allow_nested_read_agents === true, completionGroup: group?.binding(index), signal: _signal });
-          spawned.push({ ...result.details, name });
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          failed.push({ name, error: message });
-          if (group) await group.apply({ type: "rejected", ...group.binding(index), runId: group.read().members[index].runId, reason: message });
+        for (let index = 0; index < mergedAgents.length; index += 1) {
+          const merged = mergedAgents[index];
+          const name = group?.read().members[index].name || merged.name || generatedAgentName(index);
+          try {
+            const result = await spawnTeammate({
+              ...merged,
+              name,
+              team_name: sessionName,
+            }, ctx, { allowNestedReadAgents: merged.allow_nested_read_agents === true, completionGroup: group?.binding(index), signal: _signal });
+            spawned.push({ ...result.details, name });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            failed.push({ name, error: message });
+            if (group) await group.apply({ type: "rejected", ...group.binding(index), runId: group.read().members[index].runId, reason: message });
+          }
+        }
+        if (group) {
+          await group.seal();
+          await enqueueCompletionGroupDeliveries(group);
         }
-      }
-      if (group) {
-        await group.seal();
-        await enqueueCompletionGroupDeliveries(group);
-      }
 
-      const lines = [`Spawned ${spawned.length}/${params.agents.length} agents in the current Pi session.`];
-      for (const item of spawned) lines.push(`- ${item.name}: ${item.queued ? `queued at position ${item.queuePosition}` : `${item.role}, ${item.mode || "in-process"}`}`);
-      for (const item of failed) lines.push(`- ${item.name}: failed — ${item.error}`);
-      lines.push(AGENT_WAIT_CONTRACT);
-      return { content: [{ type: "text", text: lines.join("\n") }], details: { session: sessionName, spawned, failed,
-        ...(group ? { completionGroup: { groupId: group.groupId, journalPath: group.journalPath } } : {}) } };
+        const lines = [`Spawned ${spawned.length}/${params.agents.length} agents in the current Pi session.`];
+        for (const item of spawned) lines.push(`- ${item.name}: ${item.queued ? `queued at position ${item.queuePosition}` : `${item.role}, ${item.mode || "in-process"}`}`);
+        for (const item of failed) lines.push(`- ${item.name}: failed — ${item.error}`);
+        lines.push(AGENT_WAIT_CONTRACT);
+        return { content: [{ type: "text", text: lines.join("\n") }], details: { session: sessionName, spawned, failed,
+          ...(group ? { completionGroup: { groupId: group.groupId, journalPath: group.journalPath } } : {}) } };
+      });
     },
   });
 
   return {
     createNestedReadAgentTools,
     nestedChildSnapshot,
+    closeAdmission,
+    hasPendingWork: () => (
+      admissions.size > 0
+      || queuedReadSpawnsByTeam.size > 0
+      || checkpointAdmissions.size > 0
+      || readQueueDrainingTeams.size > 0
+    ),
+    resumeQueues: () => { for (const teamName of queuedReadSpawnsByTeam.keys()) void drainQueuedReadSpawns(teamName); },
     cancelQueuedAgent: (teamName, agentName) => {
       // Retain the entry for admission bookkeeping, but let active teardown own cancellation after launch commits.
       if (readQueue(teamName).some(queued => queued.member.name === agentName && queued.launchCommitted)) return false;

package/extensions/ui/activity-colors.ts

@@ -1,35 +1,26 @@
-import { canonicalPersistedModelSlot } from "../../src/utils/settings";
+import { canonicalPersistedModelSlot, loadSettings, type ActivityColors } from "../../src/utils/settings";
 
 export const CONTEXT_USAGE_STATUS_SUFFIX = /^(?:\?|[\d.]+[kM]?) tok(?: \((?:\?|[\d.]+)%\))?$/;
 
-const ACTIVITY_COLORS = {
-  name: "51;153;255",
-  model: "255;215;0",
-  thinking: "255;242;168",
-  tier: "255;146;200",
-  text: "248;248;242",
-  message: "150;156;171",
-  warning: "255;215;0",
-  error: "255;85;85",
-} as const;
-
-const TIER_PINKS: Record<string, string> = {
-  "read-collect": "255;214;235",
-  "write-patch": "255;214;235",
-  "read-review": "255;189;222",
-  "write-feature": "255;189;222",
-  "read-analyze": "255;167;211",
-  "write-system": "255;167;211",
-  "read-critical": ACTIVITY_COLORS.tier,
-  "write-critical": ACTIVITY_COLORS.tier,
+const TIER_COLORS: Record<string, keyof ActivityColors> = {
+  "read-collect": "tierCollect",
+  "write-patch": "tierCollect",
+  "read-review": "tierReview",
+  "write-feature": "tierReview",
+  "read-analyze": "tierAnalyze",
+  "write-system": "tierAnalyze",
 };
 
-// The shared activity palette is fixed; each view's surrounding chrome stays theme-owned.
+// Views share settings; surrounding chrome remains theme-owned.
 export function createActivityColors(enabled: boolean) {
-  const foreground = (rgb: string, text: string): string =>
-    enabled ? `\x1b[38;2;${rgb}m${text}\x1b[39m` : text;
-  const color = (token: keyof typeof ACTIVITY_COLORS, text: string): string => foreground(ACTIVITY_COLORS[token], text);
-  const tier = (text: string): string => foreground(TIER_PINKS[canonicalPersistedModelSlot(text)] ?? ACTIVITY_COLORS.tier, text);
+  const palette = loadSettings({ projectDir: process.cwd() }).activityColors;
+  const color = (token: keyof ActivityColors, text: string): string => {
+    if (!enabled) return text;
+    const hex = palette[token];
+    const rgb = [1, 3, 5].map(offset => parseInt(hex.slice(offset, offset + 2), 16)).join(";");
+    return `\x1b[38;2;${rgb}m${text}\x1b[39m`;
+  };
+  const tier = (text: string): string => color(TIER_COLORS[canonicalPersistedModelSlot(text)] ?? "tier", text);
   const metadata = (text: string, name: string): string => {
     const identity = `(${name})`;
     return text.split(" · ").map((part, index) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extended-teams",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Control-first, session-connected subagents for Pi with live navigation and intent-tier routing",
   "repository": {
     "type": "git",
@@ -52,7 +52,9 @@
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "docs/access.md"
+    "docs/access.md",
+    "docs/reference.md",
+    "assets/pi-extended-teams-demo.gif"
   ],
   "dependencies": {
     "uuid": "^11.1.0"

package/src/utils/settings.ts

@@ -116,7 +116,23 @@ export interface AgentSessionsConfig {
   showInResume: boolean;
 }
 
+export const DEFAULT_ACTIVITY_COLORS = {
+  name: "#50FA7B",
+  model: "#FFD700",
+  thinking: "#FFF2A8",
+  tier: "#FF92C8",
+  tierCollect: "#FFD6EB",
+  tierReview: "#FFBDDE",
+  tierAnalyze: "#FFA7D3",
+  text: "#F8F8F2",
+  message: "#969CAB",
+  warning: "#FFD700",
+  error: "#FF5555",
+};
+export type ActivityColors = typeof DEFAULT_ACTIVITY_COLORS;
+
 export interface PiExtendedTeamsSettings {
+  activityColors: ActivityColors;
   watchdog: WatchdogConfig;
   writeAgents: WriteAgentsConfig;
   readAgents: ReadAgentsConfig;
@@ -134,6 +150,7 @@ export const DEFAULT_READ_AGENT_MAX_CONCURRENT = 25;
 export const DEFAULT_READ_HELPER_MAX_CONCURRENT = 10;
 
 export const DEFAULT_SETTINGS: PiExtendedTeamsSettings = {
+  activityColors: DEFAULT_ACTIVITY_COLORS,
   watchdog: { bufferSeconds: 30 },
   writeAgents: { maxConcurrent: DEFAULT_WRITE_AGENT_MAX_CONCURRENT, queueOverflow: true },
   readAgents: { maxConcurrent: DEFAULT_READ_AGENT_MAX_CONCURRENT, queueOverflow: true },
@@ -269,6 +286,13 @@ function applyLayer(acc: PiExtendedTeamsSettings, raw: any, options: { favoriteM
   if (!raw || typeof raw !== "object") return;
   const includeFavoriteModels = options.favoriteModels !== false;
 
+  if (raw.activityColors && typeof raw.activityColors === "object" && !Array.isArray(raw.activityColors)) {
+    for (const key of Object.keys(DEFAULT_ACTIVITY_COLORS) as Array<keyof ActivityColors>) {
+      const value = raw.activityColors[key];
+      if (typeof value === "string" && /^#[\da-f]{6}$/i.test(value)) acc.activityColors[key] = value;
+    }
+  }
+
   if (raw.watchdog && typeof raw.watchdog === "object") {
     const b = Number(raw.watchdog.bufferSeconds);
     if (Number.isFinite(b) && b >= 0) acc.watchdog.bufferSeconds = b;