feat(subagent): reject tier-gated requires_tools before spawn

Author: TheGreatAxios

src/subagent/agent-fleet-requires-tools.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import {
   createFleetMailbox,
   createSpawnAgentTool,
+  tierGateRequiresTools,
   type AgentFleetDeps,
 } from "./agent-fleet.js";
 import { unlimitedAdmissionQueue } from "./admission.js";
@@ -31,6 +32,11 @@ const READ_ONLY_PROFILE: AgentProfile = {
   capabilities: { mode: "allow", tools: ["read_file"] },
 };
 
+const FULL_MOUNT_PROFILE: AgentProfile = {
+  id: "full-worker",
+  systemPromptRole: "You do anything.",
+};
+
 function makeDeps(
   run: (params: RunSubAgentParams) => Promise<RunSubAgentResult>,
   capturedTelemetry: TelemetryEvent[],
@@ -45,7 +51,7 @@ function makeDeps(
     sessions,
     fleetRecords: createFleetMailbox(sessions),
     admission: unlimitedAdmissionQueue(),
-    profiles: [READ_ONLY_PROFILE],
+    profiles: [READ_ONLY_PROFILE, FULL_MOUNT_PROFILE],
     telemetry: {
       ...NOOP_TELEMETRY,
       capture: (event: TelemetryEvent) => {
@@ -192,4 +198,128 @@ describe("spawn_agent requires_tools preflight", () => {
     expect(session?.requiresTools).toBeUndefined();
     expect(session?.snapshotRevision).toBeUndefined();
   });
+
+  test("manage_tasks survives dispatch under a narrow allowlist and stamps canonically", async () => {
+    const telemetry: TelemetryEvent[] = [];
+    let seenRequires: readonly string[] | undefined;
+    const deps = makeDeps(async (params) => {
+      seenRequires = params.requiresTools;
+      return { report: "done" };
+    }, telemetry);
+    const spawn = createSpawnAgentTool(deps);
+
+    const result = await callSpawn(spawn, {
+      description: "plan job",
+      prompt: "track the work",
+      agent: "read-only-worker",
+      requires_tools: ["manage_tasks"],
+    });
+
+    expect(result.isError).not.toBe(true);
+    const body = JSON.parse(result.content) as { agent_id: string };
+    expect(deps.sessions.get(body.agent_id)?.requiresTools).toEqual([
+      "manage_tasks",
+    ]);
+    expect(seenRequires).toEqual(["manage_tasks"]);
+  });
+
+  test("update_plan alias survives dispatch and stamps manage_tasks", async () => {
+    const telemetry: TelemetryEvent[] = [];
+    const deps = makeDeps(async () => ({ report: "done" }), telemetry);
+    const spawn = createSpawnAgentTool(deps);
+
+    const result = await callSpawn(spawn, {
+      description: "alias plan job",
+      prompt: "track the work",
+      agent: "read-only-worker",
+      requires_tools: ["update_plan"],
+    });
+
+    expect(result.isError).not.toBe(true);
+    const body = JSON.parse(result.content) as { agent_id: string };
+    expect(deps.sessions.get(body.agent_id)?.requiresTools).toEqual([
+      "manage_tasks",
+    ]);
+  });
+
+  test("leaf requires_tools=[spawn_agent] rejects pre-spawn as missing_tool naming the leaf restriction", async () => {
+    const telemetry: TelemetryEvent[] = [];
+    let runCalled = false;
+    const deps = makeDeps(async () => {
+      runCalled = true;
+      return { report: "done" };
+    }, telemetry);
+    const spawn = createSpawnAgentTool(deps);
+
+    const result = await callSpawn(spawn, {
+      description: "fleet job",
+      prompt: "spawn more workers",
+      agent: "full-worker",
+      requires_tools: ["spawn_agent"],
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content.startsWith("Error:")).toBe(true);
+    expect(result.content).toContain("spawn_agent");
+    expect(result.content).toContain("Tier 3 leaf");
+    expect(result.content).toMatch(/Re-dispatch|drop the requirement/);
+    expect(result.content).not.toContain("stale_snapshot");
+    expect(runCalled).toBe(false);
+    expect(deps.sessions.list()).toEqual([]);
+    expect(telemetry).toEqual([]);
+  });
+});
+
+describe("tierGateRequiresTools", () => {
+  test("leaf requiring a fleet verb rejects as missing_tool naming the leaf restriction", () => {
+    const gated = tierGateRequiresTools(["spawn_agent"], "leaf");
+    expect(gated?.code).toBe("missing_tool");
+    expect(gated?.tool).toBe("spawn_agent");
+    expect(gated?.detail).toContain("Tier 3 leaf");
+  });
+
+  test("orchestrator requiring a fleet verb passes", () => {
+    expect(
+      tierGateRequiresTools(["spawn_agent"], "orchestrator"),
+    ).toBeUndefined();
+    expect(
+      tierGateRequiresTools(["spawn_agent"], "nested-orchestrator"),
+    ).toBeUndefined();
+  });
+
+  test("nested-orchestrator requiring fleet discovery rejects pre-spawn", () => {
+    const gated = tierGateRequiresTools(
+      ["search_agents"],
+      "nested-orchestrator",
+    );
+    expect(gated?.code).toBe("missing_tool");
+    expect(gated?.detail).toContain("Tier 2");
+  });
+
+  test("non-leaf requiring the leaf reporting channel rejects pre-spawn", () => {
+    for (const engine of ["submit_result", "ask_director"]) {
+      const gated = tierGateRequiresTools([engine], "orchestrator");
+      expect(gated?.code).toBe("missing_tool");
+      expect(gated?.tool).toBe(engine);
+      expect(gated?.detail).toContain("Tier 3 leaf workers only");
+    }
+  });
+
+  test("leaf requiring the leaf reporting channel passes", () => {
+    expect(
+      tierGateRequiresTools(["submit_result", "ask_director"], "leaf"),
+    ).toBeUndefined();
+  });
+
+  test("ordinary tools pass on every tier", () => {
+    for (const tier of [
+      "leaf",
+      "orchestrator",
+      "nested-orchestrator",
+    ] as const) {
+      expect(
+        tierGateRequiresTools(["read_file", "manage_tasks"], tier),
+      ).toBeUndefined();
+    }
+  });
 });

src/subagent/agent-fleet.ts

@@ -72,6 +72,8 @@ import {
   DEFAULT_KNOWN_ENGINES,
   formatCapabilityUnavailable,
   preflightCapabilities,
+  rerouteAlternatives,
+  type CapabilityUnavailable,
 } from "./capability-preflight.js";
 import { isCodexProviderName } from "../config/codex-providers.js";
 import { buildDispatchBrief, type TaskIntent } from "./report.js";
@@ -107,6 +109,7 @@ import type { DirectorPackage, ModelRole } from "../agent/directors/types.js";
 import { SPAWN_AGENT_TOOL_NAME } from "./tool-taxonomy.js";
 import {
   assertCanTargetAgent,
+  assertTierMayMountFleetVerb,
   FleetAuthorityError,
   type FleetNode,
   type SubagentTier,
@@ -723,6 +726,44 @@ function fleetJson(value: unknown): string {
   return JSON.stringify(value, null, 2);
 }
 
+/**
+ * Tier gate for stamped requires_tools (CL-9476). run.ts mounts submit_result
+ * and ask_director on Tier 3 leaves only, and fleet verbs on orchestrator
+ * tiers only — a requirement the dispatch tier can never mount rejects here
+ * as missing_tool (pre-spawn) instead of surviving to the mount-time stale
+ * echo. Returns the rejection, or undefined when the tier mounts everything
+ * required.
+ */
+export function tierGateRequiresTools(
+  canonical: readonly string[],
+  tier: SubagentTier,
+): CapabilityUnavailable | undefined {
+  for (const engine of canonical) {
+    if (
+      (engine === "submit_result" || engine === "ask_director") &&
+      tier !== "leaf"
+    ) {
+      return {
+        code: "missing_tool",
+        tool: engine,
+        detail: `"${engine}" mounts on Tier 3 leaf workers only, never on ${tier} directors`,
+      };
+    }
+    try {
+      assertTierMayMountFleetVerb(tier, engine);
+    } catch (error) {
+      if (!(error instanceof FleetAuthorityError)) throw error;
+      return {
+        code: "missing_tool",
+        tool: engine,
+        alternatives: rerouteAlternatives(engine),
+        detail: error.message.split(". ")[0] ?? error.message,
+      };
+    }
+  }
+  return undefined;
+}
+
 interface ResolvedAgentDispatch {
   directorId: string;
   agentLabel: string;
@@ -1106,6 +1147,19 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
           );
         }
         requiresTools = preflight.canonical;
+        // Tier-gated mounts (fleet verbs, the Tier 3 leaf reporting channel)
+        // reject here as missing_tool when the dispatch tier can never mount
+        // them — pre-spawn, never surviving to the mount-time stale echo.
+        const dispatchTier: SubagentTier = resolved.orchestrator
+          ? (resolved.orchestratorTier ?? resolved.pkg?.tier ?? "orchestrator")
+          : "leaf";
+        const gated = tierGateRequiresTools(preflight.canonical, dispatchTier);
+        if (gated !== undefined) {
+          return fleetResult(
+            call.id,
+            formatCapabilityUnavailable(gated, resolved.agentLabel),
+          );
+        }
         snapshotRevision = currentProfileSnapshotRevision();
       }