pi-extended-teams 2.1.17 → 2.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo Pereira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,7 +6,15 @@ pi-extended-teams lets the lead split work into bounded lanes, watch agents live
 
 Read agents are the default. Edit agents are opt-in and should own isolated files.
 
-[![Three agents working in parallel inside Pi](assets/pi-extended-teams-in-action.png)](assets/pi-extended-teams-in-action.png)
+[![Three agents working in parallel inside Pi](https://raw.githubusercontent.com/dantetekanem/pi-extended-teams/main/assets/pi-extended-teams-in-action.png)](https://raw.githubusercontent.com/dantetekanem/pi-extended-teams/main/assets/pi-extended-teams-in-action.png)
+
+## Try without installing
+
+```bash
+pi -e npm:pi-extended-teams
+```
+
+This runs the published package for the current Pi invocation without adding it to your project configuration.
 
 ## Install and run
 
@@ -22,23 +30,22 @@ Or install directly from GitHub:
 pi install git:github.com/dantetekanem/pi-extended-teams
 ```
 
-Run `/agents-favorite-models` once in Pi and choose a model and thinking level for each intent tier.
-
 Then ask for help naturally:
 
 ```text
 Review the current changes with separate agents for correctness, test gaps, and security. Give me the evidence so I can make the final call.
 ```
 
-The current Pi session becomes the agent group automatically. There is no separate setup step.
+The current Pi session becomes the agent group automatically. There is no separate setup step. Until you configure a tier, it uses the current lead-session model and thinking level. Run `/agents-favorite-models` when you want particular tiers to use different models.
 
 ## How it works
 
-- Read and edit agents run in-process and stay connected to the current Pi session.
+- Read agents run in-process. Edit agents run in separate Pi sessions through the configured terminal adapter. Both stay connected to the lead session.
 - The activity card shows progress, intent tier, elapsed time, tokens, and tool activity.
-- You can open an agent's transcript, send it a message, or stop it.
+- You can open an agent's transcript, send it a message, interrupt a stuck tool command, or stop it.
 - Completed reports return to the lead automatically and remain recoverable when needed.
-- Every spawn uses a configured intent tier instead of ad hoc model settings.
+- `get_agent_status` gives the lead or an eligible nested parent one read-only snapshot of owned active, queued, stalled, or recently completed read and edit agents.
+- Every spawn names an intent tier instead of choosing ad hoc model settings. Configured favorites take priority; unset tiers inherit the current lead model and thinking.
 - Edit agents can claim isolated files. Claims coordinate cooperative agents; they are not access control.
 - Lazy session context and nested read helpers are available when a bounded task needs them.
 
@@ -46,17 +53,19 @@ This works well for multi-angle code review, root-cause investigation, parallel
 
 ## Live control
 
-With the editor empty, press Down to open agent navigation. Use Down/Up to move, `l` to expand large tool logs, `m` to message an agent, `x` to stop it, and Escape to return.
+With the editor empty, press Down to open agent navigation. Use Down/Up to move, `l` to expand large tool logs, `m` to message an agent, `i` to interrupt its currently running tool command, `x` to stop the whole agent, and Escape to return.
+
+The lead can invoke the same command-only behavior with `interrupt_teammate({ agent_name: "agent" })`. It keeps the agent's session, task context, and file claims intact so you can send follow-up work. In-process cancellation is cooperative and may report that it is still pending; for tmux-backed agents, success means Pi's Escape key was delivered, not that command settlement was independently confirmed.
 
-[![Inspecting and messaging a running agent](assets/pi-extended-teams-agent-navigation.png)](assets/pi-extended-teams-agent-navigation.png)
+[![Inspecting and messaging a running agent](https://raw.githubusercontent.com/dantetekanem/pi-extended-teams/main/assets/pi-extended-teams-agent-navigation.png)](https://raw.githubusercontent.com/dantetekanem/pi-extended-teams/main/assets/pi-extended-teams-agent-navigation.png)
 
-Completed reports wake the lead automatically. Do not poll with sleeps, loops, or repeated status checks. Use `check_teammate` only when one agent appears unhealthy or a persisted report needs recovery.
+Completed reports wake the lead automatically. End the current turn to wait. One `get_agent_status` snapshot is allowed when current status is needed; do not poll with sleeps, loops, or repeated checks. Use `check_teammate` only when `get_agent_status` shows a suspected lifecycle failure or a persisted report needs recovery.
 
 The lead owns decomposition, integration, and acceptance. Pi packages and spawned agents run with your system permissions, so review project-local instructions and configuration through Pi's normal trust flow.
 
 ## Intent tiers
 
-Every spawn uses a configured `model_slot`:
+Every spawn names a `model_slot`. Configured favorites take priority; otherwise the tier uses the current lead-session model and thinking level:
 
 | Tier | Use it for |
 | --- | --- |
@@ -89,10 +98,14 @@ For an edit, choose a write tier and name the files it may claim. Never run over
 
 ## Configuration
 
-Global settings live at `~/.pi/agent/pi-extended-teams/settings.json`. Project overrides live at `.pi/pi-extended-teams.json`. Favorite intent tiers are global so `/agents-favorite-models` and spawning use the same choices.
+Global settings live at `~/.pi/agent/pi-extended-teams/settings.json`. Project overrides live at `.pi/pi-extended-teams.json`. Favorite intent tiers are global so `/agents-favorite-models` and spawning use the same choices. Configuring favorites is optional; an unset tier falls back to the current lead-session model and thinking level.
 
 Spawned sessions are private by default under `~/.pi/teams/<team>/agent-sessions/` and stay out of Pi's normal `/resume` picker.
 
+## Security and data access
+
+Read [SECURITY.md](SECURITY.md) for private vulnerability reporting and [docs/access.md](docs/access.md) for the subprocess, filesystem, extension, hook, and network boundaries.
+
 ## Development
 
 ```bash

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made on the latest published version of `pi-extended-teams`.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/dantetekanem/pi-extended-teams/security/advisories/new) for this repository. Include a description, affected versions, reproduction steps, and impact.
+
+If private reporting is unavailable, contact the maintainer through the repository owner's GitHub profile. Do not include credentials, private prompts, or other sensitive data in a public issue.
+
+Reports are acknowledged after maintainer review. Disclosure timing and any fix will be coordinated with the reporter.
+
+## Trust boundary
+
+This package coordinates local Pi sessions. A spawned teammate receives the prompt, project working directory, configured model selection, and the capabilities of its child Pi process. Review the access disclosure before using it with a project or credentials you do not intend a teammate to access.
+
+See [docs/access.md](docs/access.md) for the process, file, extension, hook, and network boundaries.

package/docs/access.md

@@ -0,0 +1,35 @@
+# Access and execution disclosure
+
+`pi-extended-teams` is a local orchestration extension. It creates teammates that act in the working directory selected for the teammate. A teammate is not a sandbox or a security boundary.
+
+## Child processes
+
+- Read teammates run in the lead Pi process through Pi's `AgentSession` API. They do not receive a tmux pane.
+- Write teammates start a separate Pi process in a tmux pane. The extension builds and runs the local Pi launch command with the teammate's working directory, model and thinking configuration, selected extensions, and `PI_TEAM_NAME`, `PI_AGENT_NAME`, and `PI_LIFECYCLE_RUN_ID` environment variables.
+- Before launching a write teammate, the extension runs a bounded local `pi models --all` preflight through `sh -c` to determine whether the configured model is available.
+- On macOS, while at least one write teammate is active, the extension may run `/usr/bin/caffeinate -i -w <lead-pid>` to prevent idle system sleep. It terminates that helper when no write teammates remain or the extension is disposed.
+- In a Herdr session, the extension can invoke the configured `herdr` binary to split, start, and close panes when moving an agent. The binary path defaults to `herdr` and can be set with `HERDR_BIN_PATH`.
+
+## Files and local state
+
+The extension reads settings from `~/.pi/agent/pi-extended-teams/settings.json` and `<project>/.pi/pi-extended-teams.json`. Model-provider compatibility also reads the legacy `~/.pi/pi-extended-teams.json` path. Predefined agents can be read from `~/.pi/agent/agents/` and `<project>/.pi/agents/`; team templates can be read or written at `~/.pi/teams.yaml`, `~/.pi/agent/teams.yaml`, and `<project>/.pi/teams.yaml`.
+
+For a team named `<team>`, coordination state is stored under `~/.pi/teams/<team>/`. This includes `config.json`, inboxes, runtime status, session-context references, lifecycle quarantine and tombstones, file claims, write and read-helper queues, shared memory, report events, lead-session metadata, debug logs, and private child transcripts under `agent-sessions/`. Task records are stored under `~/.pi/tasks/<team>/`, and agent reports may also be written under `~/.pi/agent/reports/`. Cleanup removes lifecycle and queue files when they are no longer needed.
+
+The extension reads project extension sources only when Pi marks the same working directory trusted. Teammates receive the working directory supplied at spawn time. A write teammate can use any filesystem access granted to its child Pi process and enabled tools. A read teammate's tools are restricted by the extension, but it still receives prompt and project context supplied by the lead.
+
+## Extensions and hooks
+
+A child Pi process starts with `--no-extensions`, then receives `pi-extended-teams` plus only lead-session extensions selected by the extension policy. The package does not automatically grant every available extension to a child. Project trust is forwarded only when the child uses the same working directory as the trusted lead session. Enabled extensions can add their own tools, hooks, file access, subprocesses, or network behavior; review them separately.
+
+The package's documented project hook is `.pi/team-hooks/task_completed.sh`, which runs when a teammate marks a task complete. Hooks are project-supplied executable code and run with the permissions of the local Pi process. Do not enable or keep hooks you do not trust.
+
+## Network and model providers
+
+The extension does not make application network requests itself. Pi and any enabled extensions may make network requests. In particular, a child Pi process can send its prompt and tool context to the configured model provider, subject to Pi's provider configuration. The model provider, enabled extensions, and tools determine any additional network access.
+
+Use a model provider and extension set appropriate for the project data. Do not delegate secrets or data that you are not authorized to share with the configured provider or local tools.
+
+## Operator controls
+
+The lead controls teammate creation, messages, task assignment, and stop/interrupt actions. A teammate cannot access lead-only process-control tools. File claims coordinate edits but do not enforce operating-system access control.

package/extensions/agents/read-agent.ts

@@ -45,6 +45,45 @@ export { closeReadAgentMessageDelivery } from "./read-agent-session-lifecycle";
 
 const pendingParentWakeSignals = new WeakMap<RunningReadAgent, () => void>();
 
+interface ReadAgentWakeState {
+  generation: number;
+  waiters: Set<() => void>;
+}
+
+const readAgentWakeStates = new WeakMap<RunningReadAgent, ReadAgentWakeState>();
+
+function readAgentWakeState(agent: RunningReadAgent): ReadAgentWakeState {
+  let state = readAgentWakeStates.get(agent);
+  if (!state) {
+    state = { generation: 0, waiters: new Set() };
+    readAgentWakeStates.set(agent, state);
+  }
+  return state;
+}
+
+function readAgentWakeGeneration(agent: RunningReadAgent): number {
+  return readAgentWakeState(agent).generation;
+}
+
+function signalReadAgentWake(agent: RunningReadAgent): void {
+  const state = readAgentWakeState(agent);
+  state.generation += 1;
+  const waiters = Array.from(state.waiters);
+  state.waiters.clear();
+  for (const resolve of waiters) resolve();
+}
+
+function waitForReadAgentWake(agent: RunningReadAgent, generation: number): Promise<void> {
+  const state = readAgentWakeState(agent);
+  if (state.generation !== generation) return Promise.resolve();
+  return new Promise<void>((resolve) => { state.waiters.add(resolve); });
+}
+
+function disposeReadAgentWake(agent: RunningReadAgent): void {
+  signalReadAgentWake(agent);
+  readAgentWakeStates.delete(agent);
+}
+
 export interface RunReadAgentOptions {
   isTeammate: boolean;
   getTeamName(): string | null | undefined;
@@ -95,6 +134,52 @@ function markReadAgentActivity(
   pushReadAgentEvent(agent, text);
 }
 
+interface ReadAgentOperationOutcome {
+  generation: number;
+  interrupted: boolean;
+}
+
+async function runReadAgentSessionOperation(
+  state: RunningReadAgent,
+  operation: () => Promise<void>,
+): Promise<ReadAgentOperationOutcome> {
+  const generation = (state.operationGeneration ?? 0) + 1;
+  state.operationGeneration = generation;
+  state.activeOperationGeneration = generation;
+  state.completedOperationError = undefined;
+  let settleOperation!: () => void;
+  const operationSettlement = new Promise<void>((resolve) => { settleOperation = resolve; });
+  state.activeOperationSettlementPromise = operationSettlement;
+
+  try {
+    let failure: unknown;
+    try {
+      await operation();
+    } catch (error) {
+      failure = error;
+    }
+
+    if (state.activeOperationGeneration === generation) state.activeOperationGeneration = undefined;
+    const interrupted = state.interruptRequestedGeneration === generation;
+    if (interrupted) state.interruptRequestedGeneration = undefined;
+    state.completedOperationGeneration = generation;
+    state.completedOperationInterrupted = interrupted;
+    state.completedOperationError = interrupted ? undefined : failure;
+
+    if (interrupted) {
+      markReadAgentActivity(state, "command interrupted; waiting for lead", "thinking");
+      return { generation, interrupted: true };
+    }
+    if (failure) throw failure;
+    return { generation, interrupted: false };
+  } finally {
+    if (state.activeOperationSettlementPromise === operationSettlement) {
+      state.activeOperationSettlementPromise = undefined;
+    }
+    settleOperation();
+  }
+}
+
 function refreshReadAgentStats(agent: RunningReadAgent, session: AgentSession, activityAlreadyMarked = false): void {
   const stats = session.getSessionStats();
   const tokensUsed = stats.tokens.total;
@@ -265,12 +350,20 @@ export async function sendMessageToRunningReadAgent(agent: RunningReadAgent | un
   }
 
   const session = agent.session;
-  const delivery = session.isStreaming ? { deliverAs: "steer" as const } : undefined;
   const deliveryResult = enqueueReadAgentMessageDelivery(
     agent,
     agent.name,
-    () => session.sendUserMessage(content, delivery)
+    async () => {
+      const pendingInterrupt = agent.operationInterruptPromise;
+      if (pendingInterrupt) await pendingInterrupt.catch(() => {});
+      if (session.isStreaming) {
+        await session.sendUserMessage(content, { deliverAs: "steer" as const });
+        return;
+      }
+      await runReadAgentSessionOperation(agent, () => session.sendUserMessage(content, undefined));
+    }
   );
+  signalReadAgentWake(agent);
   pendingParentWakeSignals.get(agent)?.();
   await deliveryResult;
   markReadAgentActivity(agent, "received lead message", "thinking");
@@ -350,6 +443,7 @@ async function recordReadAgentReportEvent(
       metadata: {
         ...(member.prompt ? { initialPrompt: member.prompt } : {}),
         ...(modelSlot ? { modelSlot } : {}),
+        ...(member.parentLifecycleRunId ? { parentLifecycleRunId: member.parentLifecycleRunId } : {}),
         ...reportMetadata,
       },
     });
@@ -769,6 +863,7 @@ export async function runReadAgentInProcess(
             ? [
                 "This opted-in depth-0 write-feature/write-critical run may use restricted spawn_agent or spawn_swarm_agents for depth-1 read-only helpers. Choose any canonical read-* tier and any helper count, subject to the team's global read capacity and queue. Children report to you and cannot delegate.",
                 "Use spawn_agent with only name (optional), prompt, and model_slot. Use spawn_swarm_agents with optional defaults.model_slot plus agents using only name (optional), prompt, and model_slot.",
+                "When waiting on children, end your turn without calling report_and_exit; each child report resumes you automatically. One get_agent_status snapshot is allowed when current status is needed, but never call it repeatedly.",
                 "Do not request write tiers, cwd/team overrides, metadata, replacement of an active/queued name, or delegation outside your assigned scope.",
               ]
             : ["You cannot spawn or create other agents. If another agent is needed, use send_message to ask team-lead; only the lead decides and performs the spawn."]),
@@ -908,10 +1003,51 @@ export async function runReadAgentInProcess(
       );
     };
 
+    const waitForPostInterruptOperation = async (
+      interruptedGeneration: number,
+      initialWakeGeneration: number,
+    ): Promise<boolean> => {
+      state.operationAwaitingResume = true;
+      let observedOperationGeneration = interruptedGeneration;
+      let observedWakeGeneration = initialWakeGeneration;
+      try {
+        while (!state.stopRequested && options.isCurrentReadAgentRun(key, state)) {
+          const currentWakeGeneration = readAgentWakeGeneration(state);
+          if (currentWakeGeneration === observedWakeGeneration) {
+            const wake = waitForReadAgentWake(state, observedWakeGeneration);
+            await (state.finished ? Promise.race([wake, state.finished]) : wake);
+          }
+          observedWakeGeneration = readAgentWakeGeneration(state);
+          if (state.stopRequested || !options.isCurrentReadAgentRun(key, state)) return false;
+
+          const deliveryTail = state.messageDeliveryTail;
+          if (deliveryTail) await deliveryTail.catch(() => {});
+          const completedGeneration = state.completedOperationGeneration ?? 0;
+          if (completedGeneration <= observedOperationGeneration) continue;
+          observedOperationGeneration = completedGeneration;
+          if (state.completedOperationError) throw state.completedOperationError;
+          if (state.completedOperationInterrupted) continue;
+          return true;
+        }
+        return false;
+      } finally {
+        state.operationAwaitingResume = false;
+      }
+    };
+
     state.acceptingMessages = true;
     try {
-      await session.prompt(prompt, { source: "extension" as any });
+      const initialWakeGeneration = readAgentWakeGeneration(state);
+      const initialOperation = await runReadAgentSessionOperation(
+        state,
+        () => session.prompt(prompt, { source: "extension" as any }),
+      );
       refreshReadAgentStats(state, session);
+      if (initialOperation.interrupted) {
+        const resumed = await waitForPostInterruptOperation(initialOperation.generation, initialWakeGeneration);
+        if (!resumed) return;
+        refreshReadAgentStats(state, session);
+      }
       if (pendingChildController && pendingChildParent) {
         while (!submittedFinalReport && !state.stopRequested) {
           const snapshot = pendingChildController.observeParent(pendingChildParent);
@@ -945,8 +1081,20 @@ export async function runReadAgentInProcess(
           markReadAgentActivity(state, "recovering missing report", "thinking");
           options.renderReadAgentStatus();
           try {
-            await session.prompt(EMPTY_REPORT_RECOVERY_PROMPT, { source: "extension" as any });
+            const recoveryWakeGeneration = readAgentWakeGeneration(state);
+            const recoveryOperation = await runReadAgentSessionOperation(
+              state,
+              () => session.prompt(EMPTY_REPORT_RECOVERY_PROMPT, { source: "extension" as any }),
+            );
             refreshReadAgentStats(state, session);
+            if (recoveryOperation.interrupted) {
+              const resumed = await waitForPostInterruptOperation(
+                recoveryOperation.generation,
+                recoveryWakeGeneration,
+              );
+              if (!resumed) return;
+              refreshReadAgentStats(state, session);
+            }
           } catch (error) {
             throw unavailableReportError(
               `The report-only recovery turn failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -1105,6 +1253,7 @@ export async function runReadAgentInProcess(
     }
   } finally {
     pendingParentWakeSignals.delete(state);
+    disposeReadAgentWake(state);
     settleSessionCreation(state.session);
     // End run-owned activity even when persisted lifecycle cleanup is refused.
     if (state.heartbeatTimer) clearInterval(state.heartbeatTimer);

package/extensions/agents/write-agent.ts

@@ -3,7 +3,7 @@ import * as teams from "../../src/utils/teams";
 import * as messaging from "../../src/utils/messaging";
 import * as runtime from "../../src/utils/runtime";
 import * as writeQueue from "../../src/utils/write-queue";
-import { loadSettings, requireFavoriteModelLevel } from "../../src/utils/settings";
+import { loadSettings, normalizeFavoriteModelSlot, requireConfiguredFavoriteModel, roleForFavoriteModelSlot } from "../../src/utils/settings";
 import type { Member } from "../../src/utils/models";
 import { isTeamsDebugEnabled, teamDebugLogPath, writeTeamsDebugEvent } from "../internal/debug";
 import { buildPiCommand, checkChildPiModelAvailability, getPiExtendedTeamsExtensionSource, getPiLaunchCommand } from "../internal/pi-command";
@@ -60,12 +60,15 @@ function stopAndVerifySpawnedPane(terminal: any, paneId: string): string | null
 
 function assertWriterUsesConfiguredLevel(member: Member): void {
   const settings = loadSettings({ projectDir: member.cwd });
-  const level = requireFavoriteModelLevel(settings, member.modelSlot);
-  if (level.role !== "write" || member.role !== "write") {
+  const configured = requireConfiguredFavoriteModel(settings, member.modelSlot);
+  const slot = configured?.slot ?? normalizeFavoriteModelSlot(member.modelSlot);
+  if (!slot) throw new Error(`Unknown favorite model slot "${String(member.modelSlot)}".`);
+  const role = roleForFavoriteModelSlot(slot);
+  if (role !== "write" || member.role !== "write") {
     throw new Error(`Write agent ${member.name} must use a write-* intent tier configured via /agents-favorite-models. Spawn agents by intent tier only.`);
   }
-  if (member.model !== level.model || member.thinking !== level.thinking) {
-    throw new Error(`Write agent ${member.name} must use configured intent tier ${level.slot}; direct model/thinking overrides are not allowed.`);
+  if (configured && (member.model !== configured.config.model || member.thinking !== configured.config.thinking)) {
+    throw new Error(`Write agent ${member.name} must use configured intent tier ${configured.slot}; direct model/thinking overrides are not allowed.`);
   }
 }
 

package/extensions/events/register-events.ts

@@ -14,7 +14,7 @@ import { generateLifecycleRunId } from "../../src/utils/lifecycle-tombstone";
 import { cleanupStaleSessionContextReferences } from "../internal/session-context-reference";
 import { cleanupStalePrivateAgentSessions } from "../internal/agent-session-files";
 
-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, wait literally idle for the automatic report prompt. Do not sleep, poll, repeatedly call read_inbox/check 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, explicit user cancellation/change, or a genuinely finished agent that remains active.\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.
+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.`;
 
 export interface RegisterEventsOptions {

package/extensions/index.ts

@@ -22,6 +22,7 @@ import { formatAnimatedProgress, formatContextUsage, formatElapsed, formatModelL
 import type { CompletedAgentReport, RunningReadAgent } from "./runtime/types.js";
 import { createPendingChildController } from "./runtime/pending-child-controller.js";
 import { createActiveAgentSleepController, runWithActiveAgentSleepAssertion } from "./runtime/active-agent-sleep.js";
+import { createTeammateInterrupter } from "./runtime/teammate-interrupt.js";
 export { panelBgFill, framePanel, frameWidget, frameWidgetFullWidth, logWindowStart } from "./ui/frame.js";
 import * as messaging from "../src/utils/messaging";
 import * as teams from "../src/utils/teams";
@@ -62,6 +63,9 @@ export default function (pi: ExtensionAPI) {
     if (clearedTeamName === teamName) void drainReadHelperQueueOnce();
   });
   const runningReadAgents = new Map<string, RunningReadAgent>();
+  // Tmux writers have no nested AgentSession, but status rendering already
+  // maintains a lifecycle-fenced view of their active roster/runtime state.
+  const navigationWriterAgents = new Map<string, RunningReadAgent>();
   const completedAgentReports = new Map<string, CompletedAgentReport[]>();
   const TEAM_ACTIVITY_RENDER_DEBOUNCE_MS = 75;
   let readAgentStatusTimer: NodeJS.Timeout | null = null;
@@ -91,8 +95,8 @@ export default function (pi: ExtensionAPI) {
     getProjectTrusted: (cwd) => parentProjectTrustForSpawn(sessionCtx, cwd),
     createResourcePlan: createCurrentSpawnResourcePlan,
     sleepController: activeAgentSleepController,
-    onWriterActive: (tab) => upsertWriterScreenTab(writerScreenState, tab),
-    onWriterInactive: (targetTeamName, member) => removeWriterScreenTab(writerScreenState, { teamName: targetTeamName, name: member.name, paneId: member.tmuxPaneId }),
+    onWriterActive: (tab) => { upsertWriterScreenTab(writerScreenState, tab); markTeamActivityStatusDirty(0); },
+    onWriterInactive: (targetTeamName, member) => { removeWriterScreenTab(writerScreenState, { teamName: targetTeamName, name: member.name, paneId: member.tmuxPaneId }); markTeamActivityStatusDirty(0); },
   });
   const { shutdownTeammate, startLeadWatchdog, stopLeadWatchdog } = createLifecycleRuntime({
     isTeammate,
@@ -108,6 +112,7 @@ export default function (pi: ExtensionAPI) {
     onWriterInactive: (targetTeamName, member) => {
       releaseWriteAgentSleepAssertion(targetTeamName, member);
       removeWriterScreenTab(writerScreenState, { teamName: targetTeamName, name: member.name, paneId: member.tmuxPaneId });
+      markTeamActivityStatusDirty(0);
     },
     onTeammateClosing: (targetTeamName, member) => {
       if (!member.lifecycleRunId) return;
@@ -140,6 +145,13 @@ export default function (pi: ExtensionAPI) {
     return `${targetTeamName}:${targetAgentName}`;
   }
 
+  const interruptTeammate = createTeammateInterrupter({
+    terminal,
+    runningReadAgents,
+    readAgentKey,
+    getTeamName: () => teamName,
+  });
+
   function runInProcessAgentWithSleepAssertion(
     ...args: Parameters<typeof runReadAgentInProcess>
   ): ReturnType<typeof runReadAgentInProcess> {
@@ -232,6 +244,17 @@ export default function (pi: ExtensionAPI) {
       && runtimeHeartbeatIsRecent(runtimeStatus, now);
   }
 
+  function navigationWriterAgent(teamName: string, member: Member, status: runtime.AgentRuntimeStatus): RunningReadAgent {
+    return {
+      runId: member.lifecycleRunId!, name: member.name, teamName,
+      startedAt: status.startedAt || member.joinedAt, tokensUsed: 0, contextUsage: status.contextUsage,
+      status: status.currentAction === "thinking" ? "thinking" : status.currentAction === "starting" ? "starting" : "working",
+      recentEvents: [], lastActivityAt: status.lastHeartbeatAt || member.joinedAt, role: "write",
+      model: member.model, thinking: member.thinking, modelSlot: canonicalPersistedModelSlot(member.modelSlot),
+      latestProgress: status.latestProgress,
+    };
+  }
+
   function runtimeOnlyStatusLabel(status: runtime.AgentRuntimeStatus, now: number): string {
     if (!runtimeHeartbeatIsRecent(status, now)) return "stale";
     if (status.currentAction && status.currentAction !== "done") return status.currentAction;
@@ -496,12 +519,13 @@ export default function (pi: ExtensionAPI) {
     teamActivityWidgetMounted = true;
     sessionCtx.ui.setWidget(
       "01-pi-extended-teams-readers",
-      (tui: any) => {
+      (tui: any, theme: any) => {
         teamActivityWidgetTui = tui;
         return teamActivityStatusWidget(
           () => teamActivityStatusSnapshot,
           isTeamActivityExpanded,
-          () => tui.requestRender?.()
+          () => tui.requestRender?.(),
+          theme
         );
       },
       { placement: "belowEditor" }
@@ -591,6 +615,12 @@ export default function (pi: ExtensionAPI) {
         .filter(member => member.name !== "team-lead" && member.isActive !== false && memberActivityRole(member) === "write")
         .filter(member => !!(member.tmuxPaneId && terminal?.isAlive?.(member.tmuxPaneId)) && !runningReadAgents.has(readAgentKey(activityTeamName, member.name)) && !runtimeOnlyMemberNames.has(member.name)) ?? []
       : [];
+    navigationWriterAgents.clear();
+    for (const { member, runtimeStatus } of runtimeOnlyWriteMembers) {
+      if (member.tmuxPaneId && member.lifecycleRunId === runtimeStatus.lifecycleRunId) {
+        navigationWriterAgents.set(member.name, navigationWriterAgent(activityTeamName!, member, runtimeStatus));
+      }
+    }
     const unreadLeadMessages = activityTeamName ? await messaging.readInbox(activityTeamName, agentName, true, false).catch(() => []) : [];
     leadInboxUnreadCount = unreadLeadMessages.length;
     clearLeadInboxWidgetOnce();
@@ -1083,8 +1113,20 @@ export default function (pi: ExtensionAPI) {
   if (!isTeammate) {
     pi.on("session_start", async (_event: any, ctx: any) => {
       installAgentNavigation(ctx, {
-        getAgents: () => Array.from(runningReadAgents.values())
-          .filter(agent => !teamName || agent.teamName === teamName),
+        getAgents: () => {
+          const readers = Array.from(runningReadAgents.values())
+            .filter(agent => !teamName || agent.teamName === teamName);
+          return [...readers, ...Array.from(navigationWriterAgents.values())
+            .filter(agent => !teamName || agent.teamName === teamName)]
+            .filter((agent, index, agents) => agents.findIndex(candidate => candidate.name === agent.name) === index);
+        },
+        interruptAgent: async (name: string) => {
+          const result = await interruptTeammate(name);
+          const warning = result.status === "pending"
+            || result.status === "unsupported"
+            || result.status === "failed";
+          ctx.ui?.notify?.(result.message, warning ? "warning" : "info");
+        },
         stopAgent: async (name: string) => {
           const targetTeamName = teamName;
           if (!targetTeamName) return;
@@ -1221,6 +1263,7 @@ export default function (pi: ExtensionAPI) {
     terminal,
     runningReadAgents,
     readAgentKey,
+    interruptTeammate,
     shutdownTeammate,
     getTeamName: () => teamName,
   });

package/extensions/runtime/nested-read-agents.ts

@@ -9,7 +9,7 @@ export const NESTED_READ_MODEL_SLOTS = [
 
 export type NestedReadModelSlot = (typeof NESTED_READ_MODEL_SLOTS)[number];
 
-export const NESTED_DELEGATION_TOOL_NAMES = ["spawn_agent", "spawn_swarm_agents"] as const;
+export const NESTED_DELEGATION_TOOL_NAMES = ["get_agent_status", "spawn_agent", "spawn_swarm_agents"] as const;
 
 const ELIGIBLE_PARENT_MODEL_SLOTS = new Set(["write-feature", "write-critical"]);