Add fleet authority tiers to the subagents package

Every director package now carries a required tier (orchestrator /
nested-orchestrator / leaf), enforced in code at runSubAgent's existing
tool-mount point via src/subagent/authority.ts, not by prompt wording.
A Tier 3 leaf can never mount a fleet verb, and a Tier 2 nested
orchestrator can only target its own descendants. task() is unchanged.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,18 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Agent
+
+- **Fleet authority tiers are now runtime-enforced, not documented in a prompt.**
+  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.
+
 ## [0.2.107] - 2026-08-24
 
 ### Agent

docs/ARCHITECTURE.md

@@ -227,9 +227,25 @@ When profiles exist (local `.agents/agents/` and/or enabled **`kind: "agent"`**
 
 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.
 
+#### Fleet authority tiers (`src/subagent/authority.ts`) (CL-6941)
+
+Every director package carries a required `tier: SubagentTier` field (`src/agent/directors/types.ts`) — data on the package, never a prompt instruction:
+
+| Tier                      | Who                                             | Fleet surface                                                                                                    |
+| ------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 1 — `orchestrator`        | skywalker (primary)                             | Full fleet control over the whole tree.                                                                          |
+| 2 — `nested-orchestrator` | greybeard, or any package with `spawn.maySpawn` | Same fleet surface, scoped to its own subtree: may manage only its own descendants, never a sibling or ancestor. |
+| 3 — `leaf`                | every other director                            | No fleet verbs at all.                                                                                           |
+
+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.** `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.
+- **Subtree authority.** `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 (walked over the same `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks — no parallel tree), Tier 3 holds no fleet verbs and always fails closed. This is the authority primitive the fleet-targeting verbs land against in later child issues (CL-6942, CL-6951, CL-6945, CL-6946); CL-6941 lands the boundary and its tests, not the verbs.
+- `task()` is unaffected and remains the only spawn verb until the new verbs land beside it (deprecated-not-deleted per the CL-6940 epic).
+
 #### Closed director fleet (`src/agent/directors/`)
 
-Every shipped specialist is a **director package** — a prompt-first `DirectorPackage` (system prompt, tool envelope, spawn rights, nudge budget, report contract, `modelRole`) registered in a **closed** set of 16 ids. There is no catch-all worker: `task` without `agent` or non-general `intent`, and `task(intent="general")`, fail closed so the primary reclassifies. Nested directors with a spawn allowlist reject off-list children at `createTaskTool` (not prompt-only). Skywalker is the primary session identity: `task(agent="skywalker")` is refused, and `directorProfiles()` omits it from the spawn catalog.
+Every shipped specialist is a **director package** — a prompt-first `DirectorPackage` (system prompt, tool envelope, spawn rights, nudge budget, report contract, `modelRole`, fleet authority `tier`) registered in a **closed** set of 16 ids. There is no catch-all worker: `task` without `agent` or non-general `intent`, and `task(intent="general")`, fail closed so the primary reclassifies. Nested directors with a spawn allowlist reject off-list children at `createTaskTool` (not prompt-only). Skywalker is the primary session identity: `task(agent="skywalker")` is refused, and `directorProfiles()` omits it from the spawn catalog.
 
 **Primary**
 

src/agent/directors/brand-reviewer/package.ts

@@ -16,6 +16,7 @@ export const brandReviewerPackage: DirectorPackage = {
   description: "DESIGN.md brand gate",
   tools: { allow: DOCS_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 40 },
   modelRole: "docs",
   systemPrompt: `You are BrandReviewerDirector, a specialist in Corbits Code.

src/agent/directors/bruckheimer/package.ts

@@ -17,6 +17,7 @@ export const bruckheimerPackage: DirectorPackage = {
   description: "Product discovery specialist — user/product shape docs, not code",
   tools: { allow: DOCS_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 40 },
   modelRole: "docs",
   systemPrompt: `You are BruckheimerDirector, a specialist in Corbits Code.

src/agent/directors/build/package.ts

@@ -15,6 +15,7 @@ export const buildDirectorPackage: DirectorPackage = {
   optionalSkills: ["style", "philosophy", "typescript"],
   tools: { allow: BUILD_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 60 },
   modelRole: "implement",
   systemPrompt: `You are BuildDirector, a specialist in Corbits Code.

src/agent/directors/critique/package.ts

@@ -19,6 +19,7 @@ export const critiquePackage: DirectorPackage = {
   optionalSkills: ["style", "philosophy"],
   tools: { allow: REVIEW_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 45 },
   modelRole: "review",
   systemPrompt: `You are CritiqueDirector, a specialist in Corbits Code.

src/agent/directors/draper/package.ts

@@ -18,6 +18,7 @@ export const draperPackage: DirectorPackage = {
   // Read-only critique — product write tools not mounted.
   tools: { allow: REVIEW_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 40 },
   modelRole: "review",
   systemPrompt: `You are DraperDirector, a specialist in Corbits Code.

src/agent/directors/emil/package.ts

@@ -18,6 +18,7 @@ export const emilPackage: DirectorPackage = {
   // Critique only — write tools not mounted.
   tools: { allow: REVIEW_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 40 },
   modelRole: "review",
   systemPrompt: `You are EmilDirector, a specialist in Corbits Code.

src/agent/directors/explore/package.ts

@@ -24,6 +24,7 @@ FINDINGS SHAPE: Findings must be a scannable map — key paths, symbols, call fl
 OUT OF LANE → report Blockers naming the right director: build, plan, critique, greybeard, intern.`,
   tools: { allow: READ_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 35 },
   modelRole: "explore",
 };

src/agent/directors/gaasbot/package.ts

@@ -19,6 +19,7 @@ export const gaasbotPackage: DirectorPackage = {
   optionalSkills: ["philosophy"],
   tools: { allow: REVIEW_TOOLS },
   spawn: { maySpawn: false },
+  tier: "leaf",
   nudge: { maxTurns: 35 },
   modelRole: "plan",
   systemPrompt: `You are GaasbotDirector, a specialist in Corbits Code.