Fail closed on unresolvable fleet tier at the mount point

The tier gate in runSubAgent only checked closed-director dispatches:
a project-local or plugin AgentProfile with orchestrator: true has no
directorId, so the gate was skipped and both task and search_agents
mounted unconditionally. That is the exact "advisory, not binding"
failure mode this epic exists to remove.

task-tool.ts now resolves an explicit tier for every dispatch (closed
DirectorPackage.tier, or a profile's opt-in fleetTier field — never
"tier", which collides with the existing model-speed tier some
profiles already set) and forwards it as orchestratorTier.
runSubAgent treats a missing orchestratorTier as "leaf" and denies
task/search_agents instead of skipping the check.

Added: a gate-level test driving runSubAgent itself (not just the
assert functions) to prove an unresolvable tier and an explicit leaf
tier are both denied, and that a resolved non-leaf tier passes the
gate; a registry-wide test pinning tier against spawn.maySpawn for all
16 directors so the two hand-maintained fields cannot silently drift.

Author: TheGreatAxios

CHANGELOG.md

@@ -19,11 +19,15 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
   Every director package carries a required `tier` (`orchestrator` /
   `nested-orchestrator` / `leaf`): skywalker gets full fleet control, greybeard
   (and any package with `spawn.maySpawn`) is scoped to its own subtree, and every
-  other director gets no fleet verbs at all. The check lives in code
-  (`src/subagent/authority.ts`, wired into `runSubAgent`'s tool-mount point) so a
-  leaf cannot obtain a fleet verb and a nested orchestrator cannot reach a
-  sibling or ancestor — this is the foundation the next fleet-control verbs land
-  against. `task()` is unchanged and still the only spawn verb.
+  other director gets no fleet verbs at all. The gate lives in code
+  (`src/subagent/authority.ts`, wired into `runSubAgent`'s tool-mount point) and
+  fails closed: a caller whose tier cannot be resolved — including a
+  project-local or plugin agent profile with `orchestrator: true` that has not
+  explicitly opted in via `fleetTier: "nested-orchestrator"` — is denied
+  `task`/`search_agents` rather than silently trusted. This is the foundation
+  the next fleet-control verbs (spawn/list/steer a live agent) land against;
+  the subtree-scoping rule for those is written and tested but not yet wired to
+  a live call site. `task()` is unchanged and still the only spawn verb.
 
 ## [0.2.107] - 2026-08-24
 

docs/ARCHITECTURE.md

@@ -239,7 +239,7 @@ 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.** `runSubAgent` (`src/subagent/run.ts`) resolves the spawned director's tier via `tierForDirectorId` (`src/agent/directors/registry.ts`) and calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing `task` / `search_agents`. A Tier 3 leaf can never receive a fleet verb even if `orchestrator: true` is passed by mistake — the mount throws instead of silently installing the tool. `FLEET_VERBS` in `authority.ts` also names the not-yet-implemented verbs (`spawn_agent`, `wait_agents`, `list_agents`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `read_agent_trace`, `followup_task`) so their future mount sites inherit the same gate.
+- **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`, or an explicit non-leaf `AgentProfile.fleetTier` opt-in for a profile-sourced orchestrator — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing `task` / `search_agents`, 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 — it must also declare `fleetTier: "nested-orchestrator"`, or the mount throws `FleetAuthorityError`. (`AgentProfile.fleetTier` is deliberately not named `tier` — that name is already used, ad hoc, by some profiles for an unrelated model-speed selector; reusing it would have silently broken schema validation for those profiles, which is exactly what happened during review and was caught by the full test suite, not by inspection.) `FLEET_VERBS` in `authority.ts` also names the not-yet-implemented verbs (`spawn_agent`, `wait_agents`, `list_agents`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `read_agent_trace`, `followup_task`) so their future mount sites inherit the same gate.
 - **Subtree authority — a seam, not yet wired.** `assertCanTargetAgent(actor, targetId, nodes)` (`src/subagent/authority.ts`) implements the "root owns its tree; a child manages only its own descendants" rule (Tier 1 may target anyone, Tier 2 may target only its own descendants over the same `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks, Tier 3 always fails closed) — but **it has no production call site yet**. No verb today lets one live agent address another (`task` only spawns), so this rule is exercised only by `authority.test.ts` and is not enforced at runtime in this PR. It exists so CL-6942 (split spawn from wait) and CL-6944 (`send_input` steering) — the first verbs that make an agent addressable by another — can call it from day one instead of each inventing its own check. Treat it as unenforced until one of those wires a call site.
 - `task()` is unaffected and remains the only spawn verb until the new verbs land beside it (deprecated-not-deleted per the CL-6940 epic). Its argument schema and wire contract are unchanged; the tier check only gates which packages may have it mounted at all.
 

src/agent/directors/registry.test.ts

@@ -9,6 +9,7 @@ import {
   listDirectors,
   packageToProfile,
   resolveDirector,
+  tierForDirectorId,
 } from "./registry.js";
 
 describe("director registry", () => {
@@ -170,6 +171,20 @@ describe("director registry", () => {
     expect(s.spawn.allowlist).toHaveLength(15);
   });
 
+  // CL-6941: tier and spawn.maySpawn independently encode "may this package
+  // spawn", hand-set across 16 files. This pins their agreement so drift
+  // (adding maySpawn: true without bumping tier, or vice versa) fails a test
+  // instead of surfacing as an unexplained FleetAuthorityError at dispatch.
+  test("tier agrees with spawn.maySpawn for every director", () => {
+    for (const id of DIRECTOR_IDS) {
+      const pkg = DIRECTOR_REGISTRY[id];
+      expect(pkg.tier !== "leaf").toBe(pkg.spawn.maySpawn);
+      expect(tierForDirectorId(id)).toBe(pkg.tier);
+    }
+    expect(DIRECTOR_REGISTRY.skywalker.tier).toBe("orchestrator");
+    expect(DIRECTOR_REGISTRY.greybeard.tier).toBe("nested-orchestrator");
+  });
+
   test("every director profile declares matching agent id in system prompt", () => {
     for (const id of DIRECTOR_IDS) {
       const profile = packageToProfile(DIRECTOR_REGISTRY[id]);

src/agent/profile-types.ts

@@ -68,6 +68,18 @@ export interface AgentProfile {
   // coordinators (e.g. a planning agent that fans work out to specialists);
   // leaf-task agents should leave this unset.
   orchestrator?: boolean;
+  // Fleet authority tier (CL-6941) for a profile-sourced orchestrator. Only
+  // meaningful alongside orchestrator: true. Named `fleetTier`, not `tier` —
+  // `tier` is already an established profile field for model speed selection
+  // ("fast" | "standard" | "clever", resolved via task(tier=...)); reusing
+  // the name silently broke schema validation for profiles that set it. A
+  // profile is outside the closed director set, so it is NOT trusted with
+  // fleet verbs by default even when orchestrator: true is set — this must
+  // be declared explicitly as "nested-orchestrator" to opt in.
+  // Runtime-enforced at the tool-mount point (src/subagent/run.ts /
+  // src/subagent/authority.ts): an orchestrator=true profile with no
+  // fleetTier (or fleetTier: "leaf") is denied task/search_agents, fail-closed.
+  fleetTier?: "orchestrator" | "nested-orchestrator" | "leaf";
   // Optional inference-turn budget when this profile is dispatched via task(agent=...).
   // Floor-sanitized (≥1) at dispatch time; task(maxTurns) overrides when set.
   maxTurns?: number;

src/agent/profiles.ts

@@ -51,6 +51,7 @@ const AgentProfileSchema = type({
   "systemPromptRole?": "string",
   "systemPromptPath?": "string",
   "orchestrator?": "boolean",
+  "fleetTier?": "'orchestrator' | 'nested-orchestrator' | 'leaf'",
   "maxTurns?": "number",
 });
 

src/subagent/run-authority.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Gate-level proof for CL-6941: authority.test.ts proves the assert
+ * functions throw when called directly, which is necessary but not
+ * sufficient — it does not prove runSubAgent itself cannot be talked into
+ * mounting a fleet verb for a caller whose tier cannot be established. These
+ * tests drive runSubAgent (the real mount point) end to end.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { mkdtemp } from "node:fs/promises";
+import { join } from "node:path";
+
+import { createPermissionGate } from "../permission/gate.js";
+import { FleetAuthorityError } from "./authority.js";
+import { runSubAgent } from "./run.js";
+import type { RunSubAgentParams } from "./types.js";
+
+const testPermissionGate = createPermissionGate({
+  approvals: [],
+  interactive: false,
+  skipPermissions: true,
+});
+
+async function tmpCwd(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "cl6941-run-authority-"));
+}
+
+function baseParams(cwd: string, workdirBase: string): Omit<RunSubAgentParams, "orchestrator"> {
+  return {
+    cwd,
+    workdirBase,
+    permissionGate: testPermissionGate,
+    provider: { providerName: "test", baseURL: "http://localhost", model: "test-model" },
+    description: "gate probe",
+    prompt: "no-op",
+  };
+}
+
+describe("runSubAgent fleet-verb mount gate (CL-6941, fails closed)", () => {
+  test("orchestrator=true with no resolvable tier (non-closed-director profile shape) is denied", async () => {
+    const cwd = await tmpCwd();
+    await expect(
+      runSubAgent({
+        ...baseParams(cwd, join(cwd, ".ctx")),
+        orchestrator: true,
+        // No directorId, no orchestratorTier — this is exactly the shape a
+        // project/plugin AgentProfile with orchestrator: true produces.
+        // nestedDispatch is deliberately omitted: the tier gate must reject
+        // before that later "requires nestedDispatch" check is even reached.
+      }),
+    ).rejects.toBeInstanceOf(FleetAuthorityError);
+  });
+
+  test("orchestrator=true with an explicit leaf tier is denied", async () => {
+    const cwd = await tmpCwd();
+    await expect(
+      runSubAgent({
+        ...baseParams(cwd, join(cwd, ".ctx")),
+        orchestrator: true,
+        orchestratorTier: "leaf",
+      }),
+    ).rejects.toBeInstanceOf(FleetAuthorityError);
+  });
+
+  test("orchestrator=true with a resolved non-leaf tier passes the gate (fails later, not on authority)", async () => {
+    const cwd = await tmpCwd();
+    try {
+      await runSubAgent({
+        ...baseParams(cwd, join(cwd, ".ctx")),
+        orchestrator: true,
+        orchestratorTier: "nested-orchestrator",
+        // Deliberately still omit nestedDispatch: a tier that passes the gate
+        // must reach the *next* check (nestedDispatch required) instead of
+        // being denied by assertTierMayMountFleetVerb.
+      });
+      throw new Error("expected runSubAgent to reject (missing nestedDispatch)");
+    } catch (err) {
+      expect(err).not.toBeInstanceOf(FleetAuthorityError);
+      expect(String((err as Error).message)).toContain("nestedDispatch");
+    }
+  });
+});

src/subagent/run.ts

@@ -105,7 +105,6 @@ import {
 } from "./stop-policy.js";
 import { SubAgentDirector } from "./nudge-director.js";
 import { assertTierMayMountFleetVerb } from "./authority.js";
-import { tierForDirectorId } from "../agent/directors/registry.js";
 import {
   abortError,
   createSubAgentSpawnRegistryPlugin,
@@ -427,17 +426,17 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
     // the prompt. Nested dispatch always forbids further orchestration so the
     // tree bottoms out after one hop.
     if (params.orchestrator === true) {
-      // Tier enforcement at the mount point (CL-6941), not the prompt: a
-      // closed director resolved to Tier 3 must never reach here holding
-      // orchestrator=true — fail closed instead of silently installing fleet
-      // verbs on a leaf. Non-director profiles (params.directorId unset)
-      // are outside the closed-director tier system and are not checked here.
-      const tier =
-        params.directorId !== undefined ? tierForDirectorId(params.directorId) : undefined;
-      if (tier !== undefined) {
-        for (const verb of ["task", "search_agents"]) {
-          assertTierMayMountFleetVerb(tier, verb);
-        }
+      // Tier enforcement at the mount point (CL-6941), not the prompt: FAILS
+      // CLOSED. The caller (task-tool.ts) resolves orchestratorTier from
+      // either the closed DirectorPackage.tier or an explicit
+      // AgentProfile.tier opt-in; an unresolved tier defaults to "leaf" here,
+      // not to "skip the check" — a caller that cannot be identified must be
+      // denied, never silently trusted. This is what stops a project/plugin
+      // AgentProfile with orchestrator: true from mounting task/search_agents
+      // just because it is outside the closed director set.
+      const tier = params.orchestratorTier ?? "leaf";
+      for (const verb of ["task", "search_agents"]) {
+        assertTierMayMountFleetVerb(tier, verb);
       }
       if (params.nestedDispatch === undefined) {
         throw new Error(

src/subagent/task-tool.ts

@@ -20,7 +20,7 @@ import {
   defaultEffortForDirector,
   formatDirectorSystemPrompt,
 } from "../agent/directors/identity.js";
-import type { DirectorPackage } from "../agent/directors/types.js";
+import type { DirectorPackage, SubagentTier } from "../agent/directors/types.js";
 import type { Settings } from "../config/settings.js";
 import {
   resolveSubAgentMaxTurns,
@@ -348,6 +348,14 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
       let capabilities: CapabilityFilter | undefined;
       let systemPromptRole: string | undefined;
       let orchestrator = false;
+      /**
+       * Fleet authority tier (CL-6941) for this dispatch — forwarded to
+       * runSubAgent, which fails closed (denies task/search_agents) when
+       * orchestrator is true and this is left undefined or resolves to
+       * "leaf". Set alongside `orchestrator = true` in every branch below;
+       * never left to default once orchestrator is true.
+       */
+      let orchestratorTier: SubagentTier | undefined;
       let profileMaxTurns: number | undefined;
       let resolvedDirectorId: string | undefined;
       let resolvedPackage: DirectorPackage | undefined;
@@ -423,6 +431,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
           if (pkg.nudge?.maxTurns !== undefined) profileMaxTurns = pkg.nudge.maxTurns;
           if (pkg.spawn.maySpawn && deps.allowOrchestrator !== false) {
             orchestrator = true;
+            orchestratorTier = pkg.tier;
             if (pkg.spawn.allowlist !== undefined && pkg.spawn.allowlist.length > 0) {
               nestedSpawnAllowlist = pkg.spawn.allowlist;
             }
@@ -476,6 +485,15 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
           // even if their profile is marked orchestrator — recursion bottoms out.
           if (profile.orchestrator === true && deps.allowOrchestrator !== false) {
             orchestrator = true;
+            // Fail closed (CL-6941): a profile is outside the closed director
+            // set, so orchestrator: true alone does not grant a tier. Only an
+            // explicit non-leaf profile.fleetTier opts in; anything else
+            // (absent, or "leaf") leaves orchestratorTier undefined, which
+            // runSubAgent treats as "leaf" and denies task/search_agents.
+            orchestratorTier =
+              profile.fleetTier !== undefined && profile.fleetTier !== "leaf"
+                ? profile.fleetTier
+                : undefined;
           }
           // Per-agent pinned inference (provider/model/effort), if declared.
           // Resolution uses policy (mode: pin / agentModelFallback: none) so a
@@ -510,6 +528,7 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
         if (pkg.nudge?.maxTurns !== undefined) profileMaxTurns = pkg.nudge.maxTurns;
         if (pkg.spawn.maySpawn && deps.allowOrchestrator !== false) {
           orchestrator = true;
+          orchestratorTier = pkg.tier;
           if (pkg.spawn.allowlist !== undefined && pkg.spawn.allowlist.length > 0) {
             nestedSpawnAllowlist = pkg.spawn.allowlist;
           }
@@ -802,7 +821,13 @@ export function createTaskTool(deps: TaskToolDeps): AgentTool {
             ...(capabilities !== undefined ? { capabilities } : {}),
             ...(systemPromptRole !== undefined ? { systemPromptRole } : {}),
             ...(resolvedDirectorId !== undefined ? { directorId: resolvedDirectorId } : {}),
-            ...(orchestrator ? { orchestrator: true, nestedDispatch: nestedDispatch! } : {}),
+            ...(orchestrator
+              ? {
+                  orchestrator: true,
+                  ...(orchestratorTier !== undefined ? { orchestratorTier } : {}),
+                  nestedDispatch: nestedDispatch!,
+                }
+              : {}),
             maxTurns: resolvedMaxTurns,
             ...(deps.deadlineMs !== undefined ? { deadlineMs: deps.deadlineMs } : {}),
           };

src/subagent/types.ts

@@ -16,6 +16,7 @@ import type { PermissionGate } from "../permission/gate.js";
 import type { ReasoningEffort } from "../provider/reasoning-effort.js";
 import type { SubAgentSessionStore } from "./session-store.js";
 import type { TaskIntent } from "./report.js";
+import type { SubagentTier } from "../agent/directors/types.js";
 
 export interface SubAgentProvider {
   providerName: string;
@@ -106,6 +107,15 @@ export type RunSubAgentParams = {
   // Requires nestedDispatch so the task tool can actually be installed —
   // advertising permission without the tool is a hard break.
   orchestrator?: boolean;
+  /**
+   * Fleet authority tier (CL-6941) for this dispatch, resolved by the caller
+   * (task-tool.ts) from either the closed DirectorPackage.tier or an explicit
+   * AgentProfile.tier opt-in. Required whenever orchestrator is true:
+   * runSubAgent fails closed (denies task/search_agents) when orchestrator is
+   * true and this is undefined or "leaf" — an unrecognized or unresolved tier
+   * must never mount a fleet verb. See src/subagent/authority.ts.
+   */
+  orchestratorTier?: SubagentTier;
   // Present only when orchestrator is true. Installs task + search_agents so
   // the orchestrator can actually dispatch workers.
   nestedDispatch?: NestedDispatchDeps;