Add list_agents for this caller fleet

Parents reconstruct the fleet from memory or by waiting, then re-wait
the same ids after a timeout. list_agents reports this install's
spawn_agent mailbox without blocking and without listing siblings.

Author: TheGreatAxios

src/agent/directors/skywalker/package.ts

@@ -16,7 +16,7 @@ You do not do the specialists' jobs by default. For tiny bounded product edits,
 
 Do not run long-blocking jobs on the parent (evals, full test suites, long installs, long-running implementation). Dispatch intern (mechanical shell), tester (suite / repro), or builder (substantial code). Path tools (write_file/edit_file/delete_file) are the DIY surface; shell file-writes stay denied.
 
-Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and what happens next before you block. Prefer ending that turn (or calling wait_agents with a short timeout_ms) so Enter can land; do not immediately fuse into a long wait_agents / task() right after spawn. wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. task() still fuses spawn+wait and holds the parent until that one worker finishes. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents / task() holds those steers. A bare spawn_agent does not.
+Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and what happens next before you block. Prefer ending that turn (or calling wait_agents with a short timeout_ms) so Enter can land; do not immediately fuse into a long wait_agents / task() right after spawn. wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). list_agents shows that same fleet without blocking. Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. task() still fuses spawn+wait and holds the parent until that one worker finishes. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents / task() holds those steers. A bare spawn_agent does not.
 
 # Operator updates (mandatory while fleet is live)
 

src/agent/fleet-verbs-mount.test.ts

@@ -13,6 +13,7 @@ import { createSubAgentSessionStore } from "../subagent/session-store.js";
 const FLEET_VERBS = [
   "spawn_agent",
   "wait_agents",
+  "list_agents",
   "close_agent",
   "resume_agent",
   "interrupt_agent",

src/agent/tool-search.test.ts

@@ -83,11 +83,12 @@ describe("createToolIndex", () => {
     );
   });
 
-  test("orchestrator mode advertises the six fleet verbs", () => {
+  test("orchestrator mode advertises the fleet verbs", () => {
     const advertised = advertisedToolNamesForSessionMode("orchestrator", FULL_AVAILABILITY);
     for (const name of [
       "spawn_agent",
       "wait_agents",
+      "list_agents",
       "close_agent",
       "resume_agent",
       "interrupt_agent",
@@ -237,6 +238,7 @@ describe("advertisedTools", () => {
     for (const name of [
       "spawn_agent",
       "wait_agents",
+      "list_agents",
       "close_agent",
       "resume_agent",
       "interrupt_agent",

src/agent/tool-search.ts

@@ -45,6 +45,7 @@ export const CORE_TOOL_NAMES: readonly string[] = [
   // separate, deferred change.
   "spawn_agent",
   "wait_agents",
+  "list_agents",
   "close_agent",
   "resume_agent",
   "interrupt_agent",
@@ -56,6 +57,7 @@ const ORCHESTRATOR_ONLY_TOOL_NAMES: readonly string[] = [
   "task",
   "spawn_agent",
   "wait_agents",
+  "list_agents",
   "close_agent",
   "resume_agent",
   "interrupt_agent",

src/agent/tools.ts

@@ -43,6 +43,7 @@ import {
   createFleetRecords,
   createSpawnAgentTool,
   createWaitAgentsTool,
+  createListAgentsTool,
 } from "../subagent/agent-fleet.js";
 import {
   createCloseAgentTool,
@@ -344,6 +345,7 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
       orchestratorTools.push(
         createSpawnAgentTool(fleetDeps),
         createWaitAgentsTool({ sessions: fleetSessions, fleetRecords }),
+        createListAgentsTool({ sessions: fleetSessions, fleetRecords }),
         createCloseAgentTool({ sessions: fleetSessions, fleetRecords }),
         createResumeAgentTool({ sessions: fleetSessions }),
         createInterruptAgentTool({ sessions: fleetSessions, fleetRecords }),

src/subagent/agent-fleet.test.ts

@@ -4,6 +4,7 @@ import {
   createFleetRecords,
   createSpawnAgentTool,
   createWaitAgentsTool,
+  createListAgentsTool,
   MAX_FLEET_RECORDS,
   type AgentFleetDeps,
 } from "./agent-fleet.js";
@@ -766,3 +767,50 @@ describe("close_agent unblocks wait_agents", () => {
     expect(deps.fleetRecords.peek(id)?.status).toBe("interrupted");
   });
 });
+
+describe("list_agents", () => {
+  test("lists this fleet only, including director and lifecycle", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    const deps = makeDeps(async () => gate.promise);
+    deps.sessions.start({
+      id: "foreign-sibling",
+      description: "someone else's worker",
+      agentId: "explorer",
+      brief: "b",
+    });
+    const spawn = createSpawnAgentTool(deps);
+    const list = createListAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    const spawned = await callTool(spawn, {
+      description: "mine",
+      prompt: "do it",
+      intent: "explore",
+    });
+    if (list.kind !== "full") throw new Error("expected full tool");
+    const raw = await list.handler(
+      { id: "list-1", name: "list_agents", arguments: {} },
+      new AbortController().signal,
+    );
+    const content = typeof raw.content === "string" ? raw.content : JSON.stringify(raw.content);
+    const parsed = JSON.parse(content) as {
+      agents: {
+        agent_id: string;
+        status: string;
+        collected: boolean;
+        director?: string;
+        description?: string;
+        lifecycle?: string;
+      }[];
+    };
+    expect(parsed.agents).toHaveLength(1);
+    expect(parsed.agents[0]!.agent_id).toBe(spawned.agent_id as string);
+    expect(parsed.agents[0]!.status).toBe("running");
+    expect(parsed.agents[0]!.collected).toBe(false);
+    expect(parsed.agents[0]!.director).toBe("explorer");
+    expect(parsed.agents[0]!.description).toBe("mine");
+    expect(parsed.agents[0]!.lifecycle).toBe("pending_init");
+    gate.resolve({ report: "done" });
+  });
+});

src/subagent/agent-fleet.ts

@@ -157,6 +157,10 @@ class FleetRecords {
     this.notify();
   }
 
+  ids(): string[] {
+    return [...this.records.keys()];
+  }
+
   /** Running plus terminal-but-not-yet-handed-to-a-waiter. */
   uncollectedIds(): string[] {
     return [...this.records.entries()]
@@ -726,3 +730,40 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
     },
   });
 }
+
+export const listAgentsToolDefinition: ToolDefinition = {
+  name: "list_agents",
+  description:
+    "List the workers this session started with spawn_agent — the same fleet wait_agents " +
+    "collects. Does not list siblings or another orchestrator's workers. Each entry is id, " +
+    "director, description, wait status, lifecycle, and whether wait_agents already collected it.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+  },
+};
+
+export function createListAgentsTool(deps: WaitAgentsDeps): AgentTool {
+  return tool({
+    definition: listAgentsToolDefinition,
+    handler: async (call, _signal): Promise<ToolResult> => {
+      const agents = deps.fleetRecords.ids().map((id) => {
+        const record = deps.fleetRecords.peek(id);
+        const session = deps.sessions.get(id);
+        return {
+          agent_id: id,
+          status: record?.status ?? "unknown",
+          collected: record?.collected === true,
+          ...(session !== undefined
+            ? {
+                director: session.agentId,
+                description: session.description,
+                lifecycle: session.lifecycleStatus,
+              }
+            : {}),
+        };
+      });
+      return fleetResult(call.id, JSON.stringify({ agents }));
+    },
+  });
+}

src/subagent/authority.test.ts

@@ -33,13 +33,11 @@ describe("assertTierMayMountFleetVerb", () => {
 
   // CL-7051: fleet discovery is Skywalker (Tier 1) only — nested directors keep
   // task/spawn allowlists but must not discover the full fleet.
-  test("Tier 2 nested orchestrator cannot mount search_agents or list_agents", () => {
+  test("Tier 2 nested orchestrator cannot mount search_agents but may list its own fleet", () => {
     expect(() => assertTierMayMountFleetVerb("nested-orchestrator", "search_agents")).toThrow(
       FleetAuthorityError,
     );
-    expect(() => assertTierMayMountFleetVerb("nested-orchestrator", "list_agents")).toThrow(
-      FleetAuthorityError,
-    );
+    expect(() => assertTierMayMountFleetVerb("nested-orchestrator", "list_agents")).not.toThrow();
   });
 
   test("Tier 1 orchestrator may mount search_agents and list_agents", () => {

src/subagent/authority.ts

@@ -7,10 +7,10 @@
  *  - assertTierMayMountFleetVerb: a Tier 3 leaf may never mount a fleet verb
  *    (task, spawn_agent, wait_agents, interrupt_agent, close_agent,
  *    resume_agent, followup_task, read_agent_trace, search_agents; reserved:
- *    list_agents, send_input). Fleet *discovery* verbs (search_agents,
- *    list_agents) are further restricted to Tier 1 only (CL-7051) — nested
- *    orchestrators keep task/spawn allowlists but must not discover the
- *    full fleet.
+ *    list_agents, send_input). Fleet *discovery* of the director catalog
+ *    (search_agents) is Tier 1 only (CL-7051). list_agents is not catalog
+ *    discovery — it lists this install's own spawn_agent workers, the same
+ *    scoped mailbox wait_agents uses, so nested orchestrators may mount it.
  *  - assertCanTargetAgent: a Tier 2 nested orchestrator may act only on its
  *    own descendants, never a sibling or anything above it in the tree.
  *    Tier 1 (the primary orchestrator) may target anyone. Callers pass the
@@ -26,8 +26,7 @@ export type { SubagentTier } from "../agent/directors/types.js";
 /**
  * Every tool that grants control over other agents (spawn, list, steer,
  * observe). Tier 3 leaves may mount none of these — ever. Reserved names
- * (`list_agents`, `send_input`) stay in the set so a later mount site
- * inherits the gate instead of needing a second allowlist.
+ * `send_input` stays reserved so a later mount site inherits the gate.
  */
 export const FLEET_VERBS = new Set([
   "task",
@@ -47,7 +46,7 @@ export const FLEET_VERBS = new Set([
  * Fleet discovery — Tier 1 (skywalker) only. Nested orchestrators spawn from
  * a closed allowlist and must not index the full fleet (CL-7051).
  */
-export const ORCHESTRATOR_ONLY_FLEET_VERBS = new Set(["search_agents", "list_agents"]);
+export const ORCHESTRATOR_ONLY_FLEET_VERBS = new Set(["search_agents"]);
 
 export function isFleetVerb(toolName: string): boolean {
   return FLEET_VERBS.has(toolName);

src/subagent/run.ts

@@ -107,7 +107,12 @@ import {
   DEFAULT_CLOSE_DEADLINE_MS,
 } from "./dispose.js";
 import { createTaskTool } from "./task-tool.js";
-import { createFleetRecords, createSpawnAgentTool, createWaitAgentsTool } from "./agent-fleet.js";
+import {
+  createFleetRecords,
+  createSpawnAgentTool,
+  createWaitAgentsTool,
+  createListAgentsTool,
+} from "./agent-fleet.js";
 import {
   createCloseAgentTool,
   createResumeAgentTool,
@@ -500,6 +505,7 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
         "read_agent_trace",
         "spawn_agent",
         "wait_agents",
+        "list_agents",
         "close_agent",
         "resume_agent",
         "interrupt_agent",
@@ -595,6 +601,7 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<RunSubAgen
         ...tools,
         createSpawnAgentTool(fleetDeps),
         createWaitAgentsTool({ sessions: fleetSessions, fleetRecords }),
+        createListAgentsTool({ sessions: fleetSessions, fleetRecords }),
         createCloseAgentTool({ sessions: fleetSessions, fleetRecords }),
         createResumeAgentTool({ sessions: fleetSessions }),
         createInterruptAgentTool({ sessions: fleetSessions, fleetRecords }),