Document list_agents as a mounted mailbox fleet verb

ARCHITECTURE and authority still called list_agents reserved after it
shipped. Nested orchestrators may mount it because it lists this
install's spawn mailbox, not the director catalog.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -205,7 +205,7 @@ The **`task`** tool **spawns a sub-agent** on a separate inference source (tier/
 
 When profiles exist (local `.agents/agents/` and/or enabled **`kind: "agent"`** plugins, including **data-only** markdown plugins with no `index.ts`), the chat model also receives **`search_agents`** — a lexical index over profile id, description, and role text so the model can discover ids before calling `task(agent=...)`. Results include each match's full loaded system prompt / body so the parent can inspect plugin or Claude marketplace agents without `read_file` on paths outside the session cwd (path-escape blocks those roots by design; writes remain blocked). `task` and `search_agents` are core tools on the primary session.
 
-Profiles with `orchestrator: true` may themselves call `task` (one hop only): nested dispatch installs `task` + `search_agents` with `allowOrchestrator: false` so the tree bottoms out. Unknown `agent` ids fail closed.
+Profiles with `orchestrator: true` may themselves call `task` (one hop only): nested dispatch installs `task` and the mailbox-scoped fleet verbs (`spawn_agent`, `wait_agents`, `list_agents`, …) with `allowOrchestrator: false` so the tree bottoms out. Fleet discovery (`search_agents`) stays Tier 1 only. Unknown `agent` ids fail closed.
 
 #### Fleet authority tiers (`src/subagent/authority.ts`) (CL-6941)
 
@@ -219,8 +219,8 @@ Every director package carries a required `tier: SubagentTier` field (`src/agent
 
 Enforcement is runtime code at the existing tool-mount point, not prompt wording — this is the fix for four prior mechanisms (`writePaths`, `report.requiredSections`, a `--config` comment, the thrash matcher) that were documented-as-enforced while enforcing nothing:
 
-- **Mount-time gate — live today, and fails closed.** `task-tool.ts` resolves the caller's tier at dispatch time — a closed director's `DirectorPackage.tier` — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing fleet verbs, treating a **missing** `orchestratorTier` as `"leaf"` — deny, not skip. This is the case that matters most: a project-local or plugin `AgentProfile` with `orchestrator: true` is outside the closed director set and is **not** trusted with fleet verbs just because `orchestrator: true` is set — there is no profile-level opt-in today, so the mount always throws `FleetAuthorityError` for a profile-sourced orchestrator. `FLEET_VERBS` in `authority.ts` names the live verbs (`task`, `spawn_agent`, `wait_agents`, `interrupt_agent`, `close_agent`, `resume_agent`, `followup_task`, `read_agent_trace`, `search_agents`) plus reserved names (`list_agents`, `send_input`) so a later mount site inherits the same gate.
-- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. `read_agent_trace` is a production call site. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's own `fleetRecords`, not every running session in the shared store. `interrupt_agent` and `close_agent` terminalize the wait mailbox immediately.
+- **Mount-time gate — live today, and fails closed.** `task-tool.ts` resolves the caller's tier at dispatch time — a closed director's `DirectorPackage.tier` — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing fleet verbs, treating a **missing** `orchestratorTier` as `"leaf"` — deny, not skip. This is the case that matters most: a project-local or plugin `AgentProfile` with `orchestrator: true` is outside the closed director set and is **not** trusted with fleet verbs just because `orchestrator: true` is set — there is no profile-level opt-in today, so the mount always throws `FleetAuthorityError` for a profile-sourced orchestrator. `FLEET_VERBS` in `authority.ts` names the live verbs (`task`, `spawn_agent`, `wait_agents`, `list_agents`, `interrupt_agent`, `close_agent`, `resume_agent`, `followup_task`, `read_agent_trace`, `search_agents`) plus reserved name (`send_input`) so a later mount site inherits the same gate. `list_agents` is the non-blocking mailbox-scoped list of this install's own `spawn_agent` workers (same scope as `wait_agents`); nested orchestrators may mount it. Fleet discovery (`search_agents`) remains Tier 1 only.
+- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. `read_agent_trace` is a production call site. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's own `fleetRecords`, not every running session in the shared store. `list_agents` reports that same mailbox without blocking. `interrupt_agent` and `close_agent` terminalize the wait mailbox immediately.
 - `task()` remains the deprecated fused spawn+wait fallback. `spawn_agent` + `wait_agents` is the supported parallel path. The tier check still gates which packages may mount any fleet verb.
 
 #### Closed director fleet (`src/agent/directors/`)

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

@@ -1,5 +1,5 @@
 /**
- * Primary createAgentToolset mounts the six fleet verbs beside task /
+ * Primary createAgentToolset mounts the seven fleet verbs beside task /
  * search_agents / read_agent_trace when subAgent (with the shared TUI
  * sessions store) is wired. Leaves / no-subAgent toolsets stay without them.
  */
@@ -21,7 +21,7 @@ const FLEET_VERBS = [
 ] as const;
 
 describe("primary fleet verb mount", () => {
-  test("createAgentToolset registers the six fleet verbs when subAgent + sessions are set", async () => {
+  test("createAgentToolset registers the seven fleet verbs when subAgent + sessions are set", async () => {
     const cwd = mkdtempSync(join(tmpdir(), "corbits-fleet-mount-"));
     const { createAgentToolset } = await import("./tools.js");
     const permissionGate = {

src/subagent/authority.ts

@@ -5,9 +5,9 @@
  * in a prompt. This module owns two checks:
  *
  *  - assertTierMayMountFleetVerb: a Tier 3 leaf may never mount a fleet verb
- *    (task, spawn_agent, wait_agents, interrupt_agent, close_agent,
+ *    (task, spawn_agent, wait_agents, list_agents, interrupt_agent, close_agent,
  *    resume_agent, followup_task, read_agent_trace, search_agents; reserved:
- *    list_agents, send_input). Fleet *discovery* of the director catalog
+ *    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.

src/subagent/run-authority.test.ts

@@ -213,3 +213,45 @@ describe("runSubAgent passes parentSessionId into spawn_agent mount", () => {
     expect(capturedParentSessionId).toBe("greybeard-session");
   });
 });
+
+describe("runSubAgent list_agents mount (mailbox-scoped, nested ok)", () => {
+  test("nested-orchestrator mounts list_agents", async () => {
+    const cwd = await tmpCwd();
+    let listAgentsMounts = 0;
+
+    await withMockedModuleDuring(
+      import.meta.resolve("./agent-fleet.js"),
+      (real: typeof import("./agent-fleet.js")) => ({
+        ...real,
+        createListAgentsTool: (deps: never) => {
+          listAgentsMounts++;
+          return real.createListAgentsTool(deps);
+        },
+      }),
+      async () => {
+        const { runSubAgent: run } = await import("./run.js");
+        try {
+          await run({
+            ...baseParams(cwd, join(cwd, ".ctx")),
+            id: "greybeard-session",
+            orchestrator: true,
+            orchestratorTier: "nested-orchestrator",
+            nestedDispatch: {
+              permissionGate: testPermissionGate,
+              getWorkdirBase: () => join(cwd, ".ctx"),
+              provider: {
+                providerName: "test",
+                baseURL: "http://localhost",
+                model: "test-model",
+              },
+            },
+          });
+        } catch {
+          // Inference/agent construction may fail; mount decisions run first.
+        }
+      },
+    );
+
+    expect(listAgentsMounts).toBe(1);
+  });
+});