Gate addressing fleet verbs with subtree authority

Nested interrupt/close/resume/followup now share send_input's
assertCanTargetAgent check and fail closed without an actorId.
Soft-interrupt wait_agents collects so a later followup cannot
resurrect an already-observed interrupt as done.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -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`, `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.
+- **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`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `followup_task`, `read_agent_trace`, `search_agents`) so every 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. Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, and `followup_task`. Nested mounts pass `{actorId, tier, getNodes}` from `run.ts`; a missing `actorId` fails closed. Tier-1 primary omits authority and stays unrestricted. `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` / `send_input` with `interrupt:true` terminalize the wait mailbox immediately; the soft-interrupt wait path collects so a later followup cannot resurrect an already-observed interrupt. `close_agent` also terminalizes the wait mailbox before teardown.
 - `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/subagent/agent-fleet.test.ts

@@ -800,6 +800,35 @@ describe("interrupt_agent unblocks wait_agents", () => {
     expect(results[0]!.status).toBe("interrupted");
     expect(results[0]!.report).toContain("salvage");
   });
+
+  test("soft-interrupt wait collects so a later followup cannot resurrect done", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetRecords();
+    const worker = sessions.start({
+      id: "soft-int",
+      description: "looping",
+      agentId: "explorer",
+      brief: "b",
+      retained: true,
+    });
+    sessions.markRunning(worker.id);
+    // Running fleet record + soft-interrupted session (lifecycle only) —
+    // the wait soft path must interrupt+take before returning.
+    fleetRecords.register(worker.id);
+    sessions.registerInterrupt(worker.id, () => {});
+    sessions.interruptOne(worker.id);
+
+    const wait = createWaitAgentsTool({ sessions, fleetRecords });
+    const waited = await callTool(wait, { targets: [worker.id], timeout_ms: 1000 });
+    expect(waited.timed_out).toBe(false);
+    const results = waited.results as { status: string }[];
+    expect(results[0]!.status).toBe("interrupted");
+    expect(fleetRecords.peek(worker.id)?.collected).toBe(true);
+
+    fleetRecords.completeAfterInterrupt(worker.id, "resurrected reply");
+    expect(fleetRecords.peek(worker.id)?.status).toBe("interrupted");
+    expect(fleetRecords.peek(worker.id)?.collected).toBe(true);
+  });
 });
 
 describe("close_agent unblocks wait_agents", () => {

src/subagent/agent-fleet.ts

@@ -721,8 +721,9 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
         }
         const session = deps.sessions.get(id);
         if (isSoftInterrupted(session)) {
-          // Terminalize + collect so an omitted-targets re-wait does not keep
-          // seeing this id as uncollected / re-deliver soft-interrupt.
+          // Match the mailbox to what we report (include salvage report when
+          // present), then collect so a later completeAfterInterrupt cannot
+          // resurrect this wait as "done".
           deps.fleetRecords.interrupt(id, session.report);
           const taken = deps.fleetRecords.take(id);
           return {

src/subagent/authority.ts

@@ -107,15 +107,15 @@ function isDescendant(
 }
 
 /**
- * Live gate for `read_agent_trace` (and any future verb that addresses an
- * existing session). Callers that only spawn (`task`, `spawn_agent`) never
- * reach this check.
- *
  * Authority rule (root owns its tree; a child manages only its own
  * descendants): throws unless `actor` is Tier 1, or `targetId` is `actor.id`
  * itself, or a descendant of `actor.id` in `nodes`. A Tier 3 leaf holds no
  * fleet verbs at all and can never reach this check with a real call, so it
  * always fails closed here too.
+ *
+ * Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`,
+ * `close_agent`, `resume_agent`, and `followup_task` (nested mounts pass
+ * authority from run.ts; Tier-1 primary omits it and stays unrestricted).
  */
 export function assertCanTargetAgent(
   actor: { readonly id: string; readonly tier: SubagentTier },

src/subagent/lifecycle-tools.test.ts

@@ -397,4 +397,171 @@ describe("send_input", () => {
     );
     expect(denied.isError).toBe(true);
   });
+
+  test("fails closed when nested authority has no actorId", async () => {
+    const sessions = createSubAgentSessionStore();
+    const worker = sessions.start({
+      id: "worker",
+      description: "worker",
+      agentId: "a",
+      brief: "b",
+    });
+    sessions.markRunning(worker.id);
+    sessions.registerDeliver(worker.id, () => {});
+    const sendInput = createSendInputTool({
+      sessions,
+      authority: {
+        actorId: undefined,
+        tier: "nested-orchestrator",
+        getNodes: () => sessions.list(),
+      },
+    });
+    if (sendInput.kind !== "full") throw new Error("expected full tool");
+    const denied = await sendInput.handler(
+      { id: "no-actor", name: "send_input", arguments: { target: worker.id, message: "x" } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+    expect(String(denied.content)).toContain("no resolvable session");
+  });
+});
+
+describe("nested lifecycle authority", () => {
+  function nestAuthority(sessions: ReturnType<typeof createSubAgentSessionStore>, actorId: string) {
+    return {
+      actorId,
+      tier: "nested-orchestrator" as const,
+      getNodes: () => sessions.list(),
+    };
+  }
+
+  test("interrupt_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+    });
+    const sibling = sessions.start({ id: "sibling", description: "s", agentId: "a", brief: "b" });
+    for (const s of [child, sibling]) {
+      sessions.markRunning(s.id);
+      sessions.registerInterrupt(s.id, () => {});
+    }
+    const interrupt = createInterruptAgentTool({
+      sessions,
+      fleetRecords: createFleetRecords(),
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(interrupt, { target: child.id })).status).toBe("interrupted");
+    if (interrupt.kind !== "full") throw new Error("expected full tool");
+    const denied = await interrupt.handler(
+      { id: "d", name: "interrupt_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
+
+  test("close_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+    });
+    const sibling = sessions.start({ id: "sibling", description: "s", agentId: "a", brief: "b" });
+    for (const s of [child, sibling]) sessions.registerClose(s.id, async () => {});
+    const close = createCloseAgentTool({
+      sessions,
+      fleetRecords: createFleetRecords(),
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(close, { target: child.id })).status).toBe("shutdown");
+    if (close.kind !== "full") throw new Error("expected full tool");
+    const denied = await close.handler(
+      { id: "d", name: "close_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+    expect(sessions.get(sibling.id)?.lifecycleStatus).not.toBe("shutdown");
+  });
+
+  test("followup_task denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+      retained: true,
+    });
+    const sibling = sessions.start({
+      id: "sibling",
+      description: "s",
+      agentId: "a",
+      brief: "b",
+      retained: true,
+    });
+    for (const s of [child, sibling]) {
+      sessions.complete(s.id, "done");
+      sessions.registerFollowup(s.id, async () => "reply");
+    }
+    const followup = createFollowupTaskTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(followup, { target: child.id, message: "more" })).status).toBe(
+      "completed",
+    );
+    if (followup.kind !== "full") throw new Error("expected full tool");
+    const denied = await followup.handler(
+      {
+        id: "d",
+        name: "followup_task",
+        arguments: { target: sibling.id, message: "more" },
+      },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
+
+  test("resume_agent denies a sibling and allows a descendant", async () => {
+    const sessions = createSubAgentSessionStore();
+    const nested = sessions.start({ id: "nested", description: "n", agentId: "a", brief: "b" });
+    const child = sessions.start({
+      id: "child",
+      description: "c",
+      agentId: "a",
+      brief: "b",
+      parentSessionId: nested.id,
+      retained: true,
+    });
+    const sibling = sessions.start({
+      id: "sibling",
+      description: "s",
+      agentId: "a",
+      brief: "b",
+      retained: true,
+    });
+    sessions.complete(child.id, "done");
+    sessions.complete(sibling.id, "done");
+    const resume = createResumeAgentTool({
+      sessions,
+      authority: nestAuthority(sessions, nested.id),
+    });
+    expect((await callTool(resume, { target: child.id })).status).toBe("running");
+    if (resume.kind !== "full") throw new Error("expected full tool");
+    const denied = await resume.handler(
+      { id: "d", name: "resume_agent", arguments: { target: sibling.id } },
+      new AbortController().signal,
+    );
+    expect(denied.isError).toBe(true);
+  });
 });

src/subagent/lifecycle-tools.ts

@@ -96,10 +96,22 @@ function descendantsClosingOrder(
   return order;
 }
 
+/**
+ * Nested-orchestrator subtree gate for addressing verbs. When `authority` is
+ * omitted (Tier-1 primary mount), targeting is unrestricted. When present,
+ * a missing `actorId` fails closed — same rule as read_agent_trace.
+ */
+export interface LifecycleAuthority {
+  actorId: string | undefined;
+  tier: SubagentTier;
+  getNodes: () => readonly FleetNode[];
+}
+
 export interface LifecycleToolDeps {
   sessions: SubAgentSessionStore;
   /** Optional for resume/followup/send_input; close and interrupt require it (see CloseAgentToolDeps / InterruptAgentToolDeps). */
   fleetRecords?: FleetRecordsHandle;
+  authority?: LifecycleAuthority;
 }
 
 /** close_agent always terminalizes the wait mailbox — no silent skip. */
@@ -112,14 +124,33 @@ export type InterruptAgentToolDeps = LifecycleToolDeps & {
   fleetRecords: FleetRecordsHandle;
 };
 
-export interface SendInputAuthority {
-  actorId: string | undefined;
-  tier: SubagentTier;
-  getNodes: () => readonly FleetNode[];
-}
-
-export interface SendInputToolDeps extends LifecycleToolDeps {
-  authority?: SendInputAuthority;
+function gateTarget(
+  deps: LifecycleToolDeps,
+  toolName: string,
+  target: string,
+  callId: string,
+): ToolResult | undefined {
+  if (deps.authority === undefined) return undefined;
+  if (deps.authority.actorId === undefined) {
+    return lifecycleResult(
+      callId,
+      `Error: ${toolName} is unavailable for this worker (no resolvable session ` +
+        "id to scope descendant access).",
+    );
+  }
+  try {
+    assertCanTargetAgent(
+      { id: deps.authority.actorId, tier: deps.authority.tier },
+      target,
+      deps.authority.getNodes(),
+    );
+  } catch (cause) {
+    if (cause instanceof FleetAuthorityError) {
+      return lifecycleResult(callId, `Error: ${cause.message}`);
+    }
+    throw cause;
+  }
+  return undefined;
 }
 
 export function createCloseAgentTool(deps: CloseAgentToolDeps): AgentTool {
@@ -131,6 +162,8 @@ export function createCloseAgentTool(deps: CloseAgentToolDeps): AgentTool {
         return lifecycleResult(call.id, `Error: close_agent arguments invalid: ${parsed.summary}`);
       }
       const target = parsed.target.trim();
+      const denied = gateTarget(deps, "close_agent", target, call.id);
+      if (denied !== undefined) return denied;
       if (deps.sessions.get(target) === undefined) {
         return lifecycleResult(
           call.id,
@@ -173,6 +206,8 @@ export function createResumeAgentTool(deps: LifecycleToolDeps): AgentTool {
         return lifecycleResult(call.id, `Error: resume_agent arguments invalid: ${parsed.summary}`);
       }
       const target = parsed.target.trim();
+      const denied = gateTarget(deps, "resume_agent", target, call.id);
+      if (denied !== undefined) return denied;
       const outcome = deps.sessions.resumeOne(target);
       if (!outcome.ok) {
         const hint = outcome.hint !== undefined ? ` ${outcome.hint}` : "";
@@ -221,6 +256,8 @@ export function createInterruptAgentTool(deps: InterruptAgentToolDeps): AgentToo
         );
       }
       const target = parsed.target.trim();
+      const denied = gateTarget(deps, "interrupt_agent", target, call.id);
+      if (denied !== undefined) return denied;
       const outcome = deps.sessions.interruptOne(target);
       if (!outcome.ok) {
         return lifecycleResult(
@@ -273,6 +310,8 @@ export function createFollowupTaskTool(deps: LifecycleToolDeps): AgentTool {
         );
       }
       const target = parsed.target.trim();
+      const denied = gateTarget(deps, "followup_task", target, call.id);
+      if (denied !== undefined) return denied;
       const message = parsed.message.trim();
       if (message.length === 0) {
         return lifecycleResult(call.id, "Error: followup_task requires a non-empty message.");
@@ -327,7 +366,7 @@ export const sendInputToolDefinition: ToolDefinition = {
   },
 };
 
-export function createSendInputTool(deps: SendInputToolDeps): AgentTool {
+export function createSendInputTool(deps: LifecycleToolDeps): AgentTool {
   return tool({
     definition: sendInputToolDefinition,
     handler: async (call, _signal): Promise<ToolResult> => {
@@ -336,6 +375,8 @@ export function createSendInputTool(deps: SendInputToolDeps): AgentTool {
         return lifecycleResult(call.id, `Error: send_input arguments invalid: ${parsed.summary}`);
       }
       const target = parsed.target.trim();
+      const denied = gateTarget(deps, "send_input", target, call.id);
+      if (denied !== undefined) return denied;
       const message = parsed.message.trim();
       if (message.length === 0) {
         return lifecycleResult(call.id, "Error: send_input requires a non-empty message.");
@@ -347,27 +388,6 @@ export function createSendInputTool(deps: SendInputToolDeps): AgentTool {
             `(got ${message.length}).`,
         );
       }
-      if (deps.authority !== undefined) {
-        if (deps.authority.actorId === undefined) {
-          return lifecycleResult(
-            call.id,
-            "Error: send_input is unavailable for this worker (no resolvable session " +
-              "id to scope descendant access).",
-          );
-        }
-        try {
-          assertCanTargetAgent(
-            { id: deps.authority.actorId, tier: deps.authority.tier },
-            target,
-            deps.authority.getNodes(),
-          );
-        } catch (cause) {
-          if (cause instanceof FleetAuthorityError) {
-            return lifecycleResult(call.id, `Error: ${cause.message}`);
-          }
-          throw cause;
-        }
-      }
       const interrupt = parsed.interrupt === true;
       const outcome = deps.sessions.sendInputOne(target, message, {
         ...(interrupt ? { interrupt: true } : {}),