pi-extended-teams 2.1.18 → 2.2.3

package/extensions/runtime/teammate-interrupt.ts

@@ -0,0 +1,222 @@
+import type { TerminalAdapter } from "../../src/utils/terminal-adapter.js";
+import * as teams from "../../src/utils/teams.js";
+import * as runtime from "../../src/utils/runtime.js";
+import type { Member } from "../../src/utils/models.js";
+import type { RunningReadAgent } from "./types.js";
+export const DEFAULT_INTERRUPT_SETTLE_TIMEOUT_MS = 1_500;
+export type TeammateInterruptStatus =
+  | "interrupted" | "interrupt_sent" | "no_command" | "not_found" | "pending" | "unsupported" | "failed";
+export interface TeammateInterruptResult {
+  status: TeammateInterruptStatus;
+  agentName: string;
+  message: string;
+  agentKind?: "read" | "write";
+  lifecycleRunId?: string;
+  mechanism?: "agent-session-abort" | "tmux-escape";
+  reason?: "no-active-session" | "session-not-created" | "lifecycle-closing"
+    | "missing-pane" | "missing-runtime-proof" | "terminal-interrupt-unavailable";
+  error?: string;
+}
+export interface TeammateInterrupterOptions {
+  terminal: Pick<TerminalAdapter, "interrupt"> | null | undefined;
+  runningReadAgents: Map<string, RunningReadAgent>;
+  readAgentKey(teamName: string, agentName: string): string;
+  getTeamName(): string | null | undefined;
+  settleTimeoutMs?: number;
+}
+
+type ResultFields = Omit<TeammateInterruptResult, "status" | "agentName" | "message">;
+type InterruptTeammate = (agentName: string) => Promise<TeammateInterruptResult>;
+
+function result(status: TeammateInterruptStatus, agentName: string, message: string, fields: ResultFields = {}): TeammateInterruptResult {
+  return { status, agentName, message, ...fields };
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function activeMember(members: Member[], agentName: string): Member | undefined {
+  return members.find(member => member.name === agentName && member.name !== "team-lead" && member.isActive !== false);
+}
+
+async function settleWithin(operation: Promise<void>, timeoutMs: number): Promise<"settled" | "timed_out" | unknown> {
+  let timeout: NodeJS.Timeout | undefined;
+  const observed = operation.then<"settled", unknown>(() => "settled", error => error);
+  const timedOut = new Promise<"timed_out">((resolve) => {
+    timeout = setTimeout(() => resolve("timed_out"), Math.max(0, timeoutMs));
+  });
+  const outcome = await Promise.race([observed, timedOut]);
+  if (timeout) clearTimeout(timeout);
+  return outcome;
+}
+
+function readLifecycleClosing(state: RunningReadAgent): boolean {
+  return state.stopRequested === true
+    || state.messageDeliveryClosed === true
+    || ["stopping", "quarantined", "persistence_failed", "finalized"].includes(state.teardownState || "");
+}
+
+async function interruptReadAgent(
+  state: RunningReadAgent, member: Member, options: TeammateInterrupterOptions,
+): Promise<TeammateInterruptResult> {
+  const fields = { agentKind: "read" as const, lifecycleRunId: state.runId };
+  if (member.lifecycleRunId !== state.runId || readLifecycleClosing(state)) {
+    return result("unsupported", state.name, `Cannot interrupt ${state.name}: its lifecycle is closing or has been replaced.`, {
+      ...fields, reason: "lifecycle-closing",
+    });
+  }
+  if (!state.session) {
+    return result("unsupported", state.name, `Cannot interrupt ${state.name}: its nested session has not started.`, {
+      ...fields, reason: "session-not-created",
+    });
+  }
+
+  const generation = state.activeOperationGeneration;
+  const toolName = state.activeToolName?.trim();
+  if (!generation || !toolName || state.status !== "working" || !state.session.isStreaming) {
+    return result("no_command", state.name, `Agent ${state.name} has no running tool command to interrupt.`, fields);
+  }
+  if (state.operationInterruptPromise) {
+    return result("pending", state.name, `An interrupt is already pending for ${state.name}'s running ${toolName} command.`, fields);
+  }
+
+  const operationSettlement = state.activeOperationSettlementPromise;
+  if (!operationSettlement) {
+    return result("no_command", state.name, `Agent ${state.name} has no running tool command to interrupt.`, fields);
+  }
+
+  state.interruptRequestedGeneration = generation;
+  let nativeAbort: Promise<void>;
+  try {
+    nativeAbort = Promise.resolve(state.session.abort());
+  } catch (error) {
+    if (state.interruptRequestedGeneration === generation) state.interruptRequestedGeneration = undefined;
+    const message = errorText(error);
+    return result("failed", state.name, `Could not interrupt ${state.name}'s running ${toolName} command: ${message}`, {
+      ...fields, error: message,
+    });
+  }
+  const operation = Promise.allSettled([nativeAbort, operationSettlement]).then((results) => {
+    const failedAbort = results[0];
+    if (failedAbort.status === "rejected") throw failedAbort.reason;
+  });
+
+  state.operationInterruptPromise = operation;
+  void operation.then(
+    () => { if (state.operationInterruptPromise === operation) state.operationInterruptPromise = undefined; },
+    () => {
+      if (state.operationInterruptPromise === operation) state.operationInterruptPromise = undefined;
+      if (state.interruptRequestedGeneration === generation) state.interruptRequestedGeneration = undefined;
+    },
+  );
+
+  const outcome = await settleWithin(operation, options.settleTimeoutMs ?? DEFAULT_INTERRUPT_SETTLE_TIMEOUT_MS);
+  if (outcome === "timed_out") {
+    return result("pending", state.name, `Sent an interrupt to ${state.name}'s running ${toolName} command, but cooperative cancellation is still pending. The agent was not stopped.`, fields);
+  }
+  if (outcome !== "settled") {
+    const message = errorText(outcome);
+    return result("failed", state.name, `Could not interrupt ${state.name}'s running ${toolName} command: ${message}`, {
+      ...fields, error: message,
+    });
+  }
+
+  const sameState = options.runningReadAgents.get(options.readAgentKey(state.teamName, state.name)) === state;
+  if (!sameState || state.runId !== fields.lifecycleRunId) {
+    const message = "The target lifecycle changed while the interrupt was settling.";
+    return result("failed", state.name, `The command interrupt settled, but ${state.name}'s lifecycle changed before it could be confirmed.`, {
+      ...fields, error: message,
+    });
+  }
+  return result("interrupted", state.name, `Interrupted ${state.name}'s running ${toolName} command. The agent is still active and can receive a follow-up message.`, {
+    ...fields, mechanism: "agent-session-abort",
+  });
+}
+
+async function interruptWriter(
+  teamName: string, member: Member, options: TeammateInterrupterOptions,
+): Promise<TeammateInterruptResult> {
+  const fields = { agentKind: "write" as const, lifecycleRunId: member.lifecycleRunId };
+  if (!member.lifecycleRunId) {
+    return result("unsupported", member.name, `Cannot interrupt ${member.name}: its lifecycle identity is unavailable.`, {
+      ...fields, reason: "missing-runtime-proof",
+    });
+  }
+  if (!member.tmuxPaneId) {
+    return result("unsupported", member.name, `Cannot interrupt ${member.name}: it has no tmux pane.`, {
+      ...fields, reason: "missing-pane",
+    });
+  }
+  if (typeof options.terminal?.interrupt !== "function") {
+    return result("unsupported", member.name, `Cannot interrupt ${member.name}: the terminal adapter cannot send Pi's interrupt key.`, {
+      ...fields, reason: "terminal-interrupt-unavailable",
+    });
+  }
+
+  const [latestConfig, latestRuntime] = await Promise.all([
+    teams.readConfig(teamName),
+    runtime.readRuntimeStatus(teamName, member.name).catch(() => null),
+  ]);
+  const latestMember = activeMember(latestConfig.members, member.name);
+  const heartbeatRecent = !!latestRuntime?.lastHeartbeatAt
+    && Date.now() - latestRuntime.lastHeartbeatAt <= runtime.HEARTBEAT_STALE_MS;
+  if (!latestMember
+    || latestMember.lifecycleRunId !== member.lifecycleRunId
+    || latestMember.tmuxPaneId !== member.tmuxPaneId
+    || latestRuntime?.lifecycleRunId !== member.lifecycleRunId
+    || latestRuntime.ready !== true
+    || !heartbeatRecent) {
+    return result("unsupported", member.name, `Cannot interrupt ${member.name}: current runtime proof does not match its active lifecycle.`, {
+      ...fields, reason: "missing-runtime-proof",
+    });
+  }
+
+  const toolName = latestRuntime.activeToolName?.trim();
+  if (latestRuntime.currentAction !== "working" || !toolName) {
+    return result("no_command", member.name, `Agent ${member.name} has no running tool command to interrupt.`, fields);
+  }
+
+  try {
+    if (!options.terminal.interrupt(member.tmuxPaneId)) {
+      const message = "tmux rejected the interrupt key.";
+      return result("failed", member.name, `Could not send Pi's Escape interrupt to ${member.name}'s running ${toolName} command. The agent was not stopped.`, {
+        ...fields, error: message,
+      });
+    }
+  } catch (error) {
+    const message = errorText(error);
+    return result("failed", member.name, `Could not send Pi's Escape interrupt to ${member.name}'s running ${toolName} command: ${message}`, {
+      ...fields, error: message,
+    });
+  }
+  return result("interrupt_sent", member.name, `Sent Pi's Escape interrupt to ${member.name}'s running ${toolName} command. tmux accepted the key; command settlement is not confirmed.`, {
+    ...fields, mechanism: "tmux-escape",
+  });
+}
+
+export function createTeammateInterrupter(options: TeammateInterrupterOptions): InterruptTeammate {
+  return async (agentNameInput: string): Promise<TeammateInterruptResult> => {
+    const agentName = agentNameInput.trim();
+    const teamName = options.getTeamName();
+    if (!teamName) return result("unsupported", agentName, "No active agent session is available to interrupt.", { reason: "no-active-session" });
+
+    try {
+      const config = await teams.readConfig(teamName);
+      const member = activeMember(config.members, agentName);
+      if (!member) return result("not_found", agentName, `Agent ${agentName} is not active in this session.`);
+
+      const state = options.runningReadAgents.get(options.readAgentKey(teamName, agentName));
+      if (state) return interruptReadAgent(state, member, options);
+      if (member.role === "write") return interruptWriter(teamName, member, options);
+      return result("unsupported", agentName, `Cannot interrupt ${agentName}: no live in-process session is available.`, {
+        agentKind: "read",
+        lifecycleRunId: member.lifecycleRunId,
+        reason: "session-not-created",
+      });
+    } catch (error) {
+      const message = errorText(error);
+      return result("failed", agentName, `Could not interrupt ${agentName}: ${message}`, { error: message });
+    }
+  };
+}

package/extensions/runtime/types.ts

@@ -13,6 +13,21 @@ export interface RunningReadAgent extends ManagedReadAgentLifecycleState {
   recentEvents: string[];
   lastActivityAt: number;
   activeToolName?: string;
+  /** Monotonic identity for the current nested AgentSession turn. */
+  operationGeneration?: number;
+  /** Present only while the matching AgentSession turn is active. */
+  activeOperationGeneration?: number;
+  /** Settles only after the exact active AgentSession turn has unwound. */
+  activeOperationSettlementPromise?: Promise<void>;
+  /** Marks the exact active turn for an expected command interruption. */
+  interruptRequestedGeneration?: number;
+  /** Coalesces cancellation of the active turn without exposing teardown state. */
+  operationInterruptPromise?: Promise<void>;
+  /** Latest settled turn observed by the runner while waiting for post-interrupt work. */
+  completedOperationGeneration?: number;
+  completedOperationInterrupted?: boolean;
+  completedOperationError?: unknown;
+  operationAwaitingResume?: boolean;
   lastError?: RuntimeError;
   idleNudgeLevel?: "soft" | "hard";
   role?: string;

package/extensions/team/team-contracts.json

@@ -13,7 +13,7 @@
     },
     {
       "id": "ui.agent-follow-navigation",
-      "description": "From an empty main editor, Down opens the first active agent in a full-window interactive live-follow view. Down moves to the next agent; Up moves to the previous agent and returns to main only from the first agent; Escape always returns to main. The view exposes transcript, thinking, progress, elapsed time, and tokens; pairs tool calls with their results in readable blocks; collapses large results with head/tail context and an expansion toggle; and provides an input for direct messages to the selected active agent. Pressing x stops the selected subagent while keeping the live view open."
+      "description": "From an empty main editor, Down opens the first active agent in a full-window interactive live-follow view. Down moves to the next agent; Up moves to the previous agent and returns to main only from the first agent; Escape always returns to main. The view exposes transcript, thinking, progress, elapsed time, and tokens; pairs tool calls with their results in readable blocks; collapses large results with head/tail context and an expansion toggle; and provides an input for direct messages to the selected active agent. Pressing i interrupts the selected subagent's running tool command while preserving its session and claims. Pressing x stops the selected subagent completely. Both actions keep the live view open."
     },
     {
       "id": "helpers.requested-by-writer",

package/extensions/tools/agent-status-tool.ts

@@ -0,0 +1,270 @@
+import { Type } from "@sinclair/typebox";
+import * as teams from "../../src/utils/teams";
+import * as runtime from "../../src/utils/runtime";
+import * as reportEvents from "../../src/utils/report-events";
+import { readLifecycleTombstone, type LifecycleTombstoneReadResult } from "../../src/utils/lifecycle-tombstone";
+import type { Member, TeamReportEvent } from "../../src/utils/models";
+import type { RunningReadAgent } from "../runtime/types";
+import { isWriteMemberAlive } from "../team/roster";
+import { describeReadAgentStatus } from "../ui/read-agent-status";
+import { formatElapsed } from "../ui/renderers";
+
+export type AgentStatusPhase =
+  | RunningReadAgent["status"]
+  | TeamReportEvent["status"]
+  | "queued"
+  | "stalled"
+  | "stopping"
+  | "quarantined"
+  | "persistence-failed";
+
+export interface QueuedAgentStatus {
+  name: string;
+  role: string;
+  queuedAt: number;
+  queuePosition: number;
+  parentAgentName?: string;
+  parentLifecycleRunId?: string;
+}
+
+export interface AgentStatusScope {
+  parentName: string;
+  parentRunId: string;
+  parentStartedAt: number;
+}
+
+export interface AgentStatusSnapshot {
+  name: string;
+  role: string;
+  phase: AgentStatusPhase;
+  progress?: string;
+  progressAgeMs?: number;
+  activeTool?: string;
+  activityAgeMs?: number;
+  heartbeatAgeMs?: number;
+  queuePosition?: number;
+  queuedAgeMs?: number;
+  completedAgeMs?: number;
+  summary?: string;
+  error?: string;
+}
+
+export interface AgentStatusToolOptions {
+  getTeamName(): string | null | undefined;
+  runningReadAgents: Map<string, RunningReadAgent>;
+  readAgentKey(teamName: string, agentName: string): string;
+  terminal: any;
+  listQueuedAgents(teamName: string): QueuedAgentStatus[] | Promise<QueuedAgentStatus[]>;
+  scope?: AgentStatusScope;
+}
+
+export const AGENT_WAIT_CONTRACT = "Reports arrive automatically as new turns. End this turn to wait. Use get_agent_status once for a current snapshot; do not poll.";
+
+function age(now: number, timestamp?: number): number | undefined {
+  return timestamp === undefined ? undefined : Math.max(0, now - timestamp);
+}
+
+function ownsMember(member: Member, scope?: AgentStatusScope): boolean {
+  if (member.name === "team-lead") return false;
+  if (!scope) return member.delegationDepth !== 1 && member.helperKind !== "read_helper";
+  return member.parentAgentName === scope.parentName
+    && member.parentLifecycleRunId === scope.parentRunId;
+}
+
+function ownsQueue(item: QueuedAgentStatus, scope?: AgentStatusScope): boolean {
+  if (!scope) return !item.parentAgentName;
+  return item.parentAgentName === scope.parentName
+    && item.parentLifecycleRunId === scope.parentRunId;
+}
+
+function ownsReport(report: TeamReportEvent, scope?: AgentStatusScope): boolean {
+  if (!scope) return !report.requestedBy;
+  const parentRunId = report.metadata?.parentLifecycleRunId;
+  return report.requestedBy === scope.parentName
+    && report.createdAt >= scope.parentStartedAt
+    && (typeof parentRunId !== "string" || parentRunId === scope.parentRunId);
+}
+
+function lifecycleMatches(member: Member, runId?: string): boolean {
+  return member.lifecycleRunId === runId;
+}
+
+function persistedLifecycleStatus(
+  member: Member,
+  result: LifecycleTombstoneReadResult,
+): Pick<AgentStatusSnapshot, "phase" | "error"> | undefined {
+  if (result.status === "absent") return undefined;
+  if (result.status === "corrupt") return { phase: "quarantined", error: result.error };
+
+  const tombstone = result.tombstone;
+  const runMismatch = member.lifecycleRunId && tombstone.runId !== member.lifecycleRunId
+    ? `Lifecycle fence belongs to run ${tombstone.runId}, not roster run ${member.lifecycleRunId}.`
+    : undefined;
+  const phase = tombstone.phase === "cleanup_failed" || tombstone.phase === "timed_out"
+    ? "quarantined"
+    : "stopping";
+  return { phase, error: runMismatch || tombstone.error };
+}
+
+function phaseForActiveAgent(
+  member: Member,
+  state: RunningReadAgent | undefined,
+  runtimeStatus: runtime.AgentRuntimeStatus | null,
+  persistedStatus: Pick<AgentStatusSnapshot, "phase" | "error"> | undefined,
+  now: number,
+  terminal: any,
+): AgentStatusPhase {
+  if (state?.teardownState === "persistence_failed") return "persistence-failed";
+  if (state?.teardownState === "quarantined") return "quarantined";
+  if (state?.teardownState === "stopping") return "stopping";
+  if (persistedStatus) return persistedStatus.phase;
+  if (state && state.teardownState !== "finalized") {
+    return describeReadAgentStatus(state, now).label === "hanging" ? "stalled" : state.status;
+  }
+
+  const heartbeatFresh = runtime.isHeartbeatFresh(runtimeStatus, now);
+  const paneAlive = member.isActive !== false && isWriteMemberAlive(member, terminal);
+  if (!heartbeatFresh && !paneAlive) {
+    if (member.isActive !== false && !runtimeStatus?.ready && now - member.joinedAt <= runtime.STARTUP_STALL_MS) return "starting";
+    return "stalled";
+  }
+
+  const action = runtimeStatus?.currentAction;
+  if (action) return action === "done" ? "finishing" : action;
+  return runtimeStatus?.ready ? "working" : "starting";
+}
+
+async function activeStatus(
+  teamName: string,
+  member: Member,
+  options: AgentStatusToolOptions,
+  now: number,
+): Promise<AgentStatusSnapshot> {
+  const candidateState = options.runningReadAgents.get(options.readAgentKey(teamName, member.name));
+  const [candidateRuntimeStatus, lifecycleResult] = await Promise.all([
+    runtime.readRuntimeStatus(teamName, member.name).catch(() => null),
+    readLifecycleTombstone(teamName, member.name).catch(error => ({
+      status: "corrupt" as const,
+      error: error instanceof Error ? error.message : String(error),
+    })),
+  ]);
+  const state = candidateState && lifecycleMatches(member, candidateState.runId)
+    ? candidateState
+    : undefined;
+  const runtimeStatus = candidateRuntimeStatus && lifecycleMatches(member, candidateRuntimeStatus.lifecycleRunId)
+    ? candidateRuntimeStatus
+    : null;
+  const persistedStatus = persistedLifecycleStatus(member, lifecycleResult);
+  const progress = state?.latestProgress || runtimeStatus?.latestProgress;
+  const progressUpdatedAt = state?.progressUpdatedAt || runtimeStatus?.progressUpdatedAt;
+  return {
+    name: member.name,
+    role: member.role || state?.role || "read",
+    phase: phaseForActiveAgent(member, state, runtimeStatus, persistedStatus, now, options.terminal),
+    progress,
+    progressAgeMs: age(now, progressUpdatedAt),
+    activeTool: state?.activeToolName || runtimeStatus?.activeToolName,
+    activityAgeMs: age(now, state?.lastActivityAt),
+    heartbeatAgeMs: age(now, runtimeStatus?.lastHeartbeatAt),
+    error: state?.lastError?.message || persistedStatus?.error || runtimeStatus?.lastError?.message,
+  };
+}
+
+function queuedStatus(item: QueuedAgentStatus, now: number): AgentStatusSnapshot {
+  return {
+    name: item.name,
+    role: item.role,
+    phase: "queued",
+    queuePosition: item.queuePosition,
+    queuedAgeMs: age(now, item.queuedAt),
+  };
+}
+
+function completedStatus(report: TeamReportEvent, now: number): AgentStatusSnapshot {
+  return {
+    name: report.agentName,
+    role: report.role || "read",
+    phase: report.status,
+    completedAgeMs: age(now, report.createdAt),
+    summary: report.summary,
+  };
+}
+
+function formatAge(label: string, value?: number): string | undefined {
+  return value === undefined ? undefined : `${label}: ${formatElapsed(value)} ago`;
+}
+
+export function formatAgentStatusesForModel(statuses: AgentStatusSnapshot[]): string {
+  if (statuses.length === 0) return "No active, queued, or recently completed agents in this scope.";
+
+  const blocks = statuses.map(status => {
+    const lines = [`${status.name}: ${status.phase} (${status.role})`];
+    if (status.progress) lines.push(`  progress: ${status.progress}${status.progressAgeMs === undefined ? "" : ` (${formatElapsed(status.progressAgeMs)} ago)`}`);
+    if (status.activeTool) lines.push(`  tool: ${status.activeTool}`);
+    const activity = formatAge("activity", status.activityAgeMs)
+      ?? formatAge("heartbeat", status.heartbeatAgeMs);
+    if (activity) lines.push(`  ${activity}`);
+    if (status.queuePosition !== undefined) lines.push(`  queue position: ${status.queuePosition}`);
+    const queued = formatAge("queued", status.queuedAgeMs);
+    if (queued) lines.push(`  ${queued}`);
+    const completed = formatAge(status.phase === "failed" ? "failed" : "completed", status.completedAgeMs);
+    if (completed) lines.push(`  ${completed}`);
+    if (status.summary) lines.push(`  summary: ${status.summary}`);
+    if (status.error) lines.push(`  error: ${status.error}`);
+    return lines.join("\n");
+  });
+
+  return `${blocks.join("\n\n")}\n\n${AGENT_WAIT_CONTRACT}`;
+}
+
+export function createAgentStatusTool(options: AgentStatusToolOptions): any {
+  return {
+    name: "get_agent_status",
+    label: "Get Agent Status",
+    description: "Get one read-only snapshot of one or all agents owned by this parent. Omit agent_name to inspect all. This call is allowed when current status is needed; it never waits, polls, stops, or changes agents. Do not call it repeatedly. Final reports arrive automatically and resume this agent.",
+    parameters: Type.Object({
+      agent_name: Type.Optional(Type.String({ description: "One owned agent to inspect. Omit to inspect all owned agents." })),
+    }),
+    async execute(_toolCallId: string, params: { agent_name?: string }) {
+      const teamName = options.getTeamName();
+      if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
+
+      const config = await teams.readConfig(teamName);
+      const now = Date.now();
+      const activeMembers = config.members.filter(member => ownsMember(member, options.scope));
+      const rosterNames = new Set(config.members.map(member => member.name));
+      const queued = (await options.listQueuedAgents(teamName))
+        .filter(item => ownsQueue(item, options.scope) && !rosterNames.has(item.name));
+      const reportSince = options.scope?.parentStartedAt ?? config.createdAt;
+      const reports = (await reportEvents.listTeamReportEvents(teamName, {
+        since: reportSince,
+        agentName: params.agent_name,
+      }).catch(() => []))
+        .filter(report => ownsReport(report, options.scope));
+
+      const activeStatuses = await Promise.all(activeMembers.map(member => activeStatus(teamName, member, options, now)));
+      const queuedStatuses = queued.map(item => queuedStatus(item, now));
+      const currentNames = new Set([...activeStatuses, ...queuedStatuses].map(status => status.name));
+      const completedByName = new Map<string, TeamReportEvent>();
+      for (const report of reports) {
+        if (currentNames.has(report.agentName)) continue;
+        completedByName.delete(report.agentName);
+        completedByName.set(report.agentName, report);
+      }
+      const completedStatuses = Array.from(completedByName.values()).slice(-20).map(report => completedStatus(report, now));
+      const statuses = [...activeStatuses, ...queuedStatuses, ...completedStatuses];
+      const selected = params.agent_name
+        ? statuses.filter(status => status.name === params.agent_name)
+        : statuses;
+
+      if (params.agent_name && selected.length === 0) {
+        throw new Error(`Agent ${params.agent_name} has no current status in this scope.`);
+      }
+
+      return {
+        content: [{ type: "text", text: formatAgentStatusesForModel(selected) }],
+        details: { teamName, statuses: selected },
+      };
+    },
+  };
+}

package/extensions/tools/task-runtime-tools.ts

@@ -10,18 +10,39 @@ import type { Member } from "../../src/utils/models";
 import type { ReadAgentTeardownResult } from "../agents/read-agent-session-lifecycle";
 import type { ShutdownTeammateOptions } from "../team/lifecycle";
 import { readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
+import type { TeammateInterruptResult } from "../runtime/teammate-interrupt";
 
 export interface TaskRuntimeToolsOptions {
   isTeammate: boolean;
   terminal: any;
   runningReadAgents: Map<string, RunningReadAgent>;
   readAgentKey(teamName: string, agentName: string): string;
+  interruptTeammate?(agentName: string): Promise<TeammateInterruptResult>;
   shutdownTeammate(teamName: string, member: Member, options?: ShutdownTeammateOptions): Promise<ReadAgentTeardownResult>;
   getTeamName(): string | null | undefined;
 }
 
 export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptions): void {
   if (!options.isTeammate) {
+    if (options.interruptTeammate) {
+      pi.registerTool({
+        name: "interrupt_teammate",
+        label: "Interrupt Agent Command",
+        description: "Interrupt one active agent's currently running tool command without stopping the agent, removing it from the roster, or releasing its claims. Cancellation is cooperative for in-process tools, so the result may remain pending. Use this only for a command that is actually stuck; normal agent silence is not a reason to interrupt.",
+        parameters: Type.Object({ agent_name: Type.String() }),
+        async execute(_toolCallId: string, params: any) {
+          const teamName = options.getTeamName();
+          if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
+
+          const result = await options.interruptTeammate!(params.agent_name);
+          return {
+            content: [{ type: "text", text: result.message }],
+            details: { session: teamName, ...result },
+          };
+        },
+      });
+    }
+
     pi.registerTool({
       name: "stop_teammate",
       label: "Stop Agent",
@@ -107,8 +128,8 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
     name: "check_teammate",
     label: "Check Agent",
     description: options.isTeammate
-      ? "Check one agent's active status in the current Pi session only for targeted diagnostics after it has been quiet for several minutes or appears unhealthy. Do not use immediately after sending a message or while waiting for normal work."
-      : "Check one agent's status in the current Pi session only for targeted diagnostics after it has been quiet for several minutes or appears unhealthy. If the agent already left the roster before its report reached you, this recovers its latest persisted report. Do not use immediately after sending a message, while waiting for normal work, or after a report has already arrived.",
+      ? "Diagnose one agent's lifecycle only after it has been quiet for several minutes or appears unhealthy. This may clean up an agent classified as dead, so do not use it for status polling."
+      : "Diagnose one agent's lifecycle only after get_agent_status shows a suspected stall or failure. This may clean up an agent classified as dead. It can also recover the latest persisted report after an agent leaves the roster.",
     parameters: Type.Object({ agent_name: Type.String() }),
     async execute(_toolCallId: string, params: any) {
       const teamName = options.getTeamName();
@@ -175,7 +196,7 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
       const unreadCount = (await messaging.readInbox(teamName, params.agent_name, true, false)).length;
       const runtimeStatus = await runtime.readRuntimeStatus(teamName, params.agent_name).catch(() => null);
       const now = Date.now();
-      const hasRecentHeartbeat = !!runtimeStatus?.lastHeartbeatAt && (now - runtimeStatus.lastHeartbeatAt) <= runtime.HEARTBEAT_STALE_MS;
+      const hasRecentHeartbeat = runtime.isHeartbeatFresh(runtimeStatus, now);
       const runningState = options.runningReadAgents.get(options.readAgentKey(teamName, member.name));
       const lifecycleHealth = runningState?.teardownState === "persistence_failed" ? "persistence-failed"
         : runningState?.teardownState === "quarantined" ? "quarantined"