Define the subagents package and its three-tier tool surface

[TheGreatAxios]

Closes CL-6941.

The tier model

Every director package (src/agent/directors/types.ts) carries a required tier: SubagentTier:

• Tier 1 — orchestrator (skywalker): full fleet control over the whole tree.
• Tier 2 — nested-orchestrator (greybeard, or any package with spawn.maySpawn): same surface, scoped to its own subtree — may manage only its own descendants, never a sibling or anything above it.
• Tier 3 — leaf (every other director): no fleet verbs at all.

All 16 director packages were assigned a tier: skywalker → orchestrator, greybeard → nested-orchestrator, the other 14 → leaf.

Where enforcement lives, and how it fails closed

src/subagent/authority.ts is the authority module: assertTierMayMountFleetVerb(tier, toolName) throws if a Tier 3 leaf is about to receive a fleet verb (task, search_agents today; FLEET_VERBS also names the not-yet-built 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 gate).

A round of review caught that the first version of this gate failed open: runSubAgent only resolved a tier when params.directorId was set, which is true only for the 16 closed directors. Any project-local or plugin AgentProfile with orchestrator: true — which is a real, already-supported feature, not hypothetical — reached runSubAgent with directorId undefined, the tier check was skipped entirely, and task/search_agents mounted unconditionally. That defeated the epic's first settled decision (runtime enforcement, not advisory) for exactly the callers most likely to be user-authored.

Fixed: tier resolution now happens once, in task-tool.ts, for every dispatch path — closed director (DirectorPackage.tier) or profile (AgentProfile.fleetTier, a new opt-in field) — and is forwarded as RunSubAgentParams.orchestratorTier. runSubAgent treats a missing orchestratorTier as "leaf", not as "skip the check": denied by default, not silently trusted. A profile with orchestrator: true and no fleetTier (or fleetTier: "leaf") now gets a FleetAuthorityError instead of a mounted task tool; it must explicitly declare fleetTier: "nested-orchestrator" to opt in. (The field is named fleetTier, not tier — AgentProfile already has an unrelated tier used ad hoc by some profiles for model-speed selection (fast/standard/clever); reusing the name silently broke schema validation for those profiles, which the full test suite caught.)

assertCanTargetAgent(actor, targetId, nodes) — the "root owns its tree; a child manages only its own descendants" subtree rule — is a seam, not yet a live gate. It has no production call site in this PR: no verb today lets one live agent address another (task only spawns). It's landed now, explicitly marked as unwired in both the code comment above the function and in docs/ARCHITECTURE.md, so CL-6942 (split spawn from wait) and CL-6944 (send_input steering) — the first verbs that make an agent addressable — can call it from day one instead of each inventing its own check. Do not read this as enforced until one of those wires it in.

This distinction matters here specifically: four other mechanisms in this codebase (writePaths, report.requiredSections, a --config comment, the thrash matcher) were previously documented as enforced while enforcing nothing. Both the fail-open bug above and the unwired seam are called out explicitly so neither becomes a fifth instance.

Tests

• src/subagent/authority.test.ts: the assert functions throw/pass correctly in isolation (leaf denied a fleet verb; Tier 2 can target its own descendant and itself but not a sibling or ancestor; Tier 1 can target anyone; Tier 3 can target no one).
• src/subagent/run-authority.test.ts (new, gate-level): drives runSubAgent itself, not just the assert functions — proves (a) orchestrator: true with an unresolved tier (the profile-sourced shape) is denied with FleetAuthorityError, (b) an explicit orchestratorTier: "leaf" is denied, and (c) a resolved non-leaf tier passes the gate and fails later for an unrelated reason (missing nestedDispatch), not on authority. This is the test that would have caught the fail-open bug.
• src/agent/directors/registry.test.ts (new case): pins tier !== "leaf" against spawn.maySpawn for all 16 directors, since the two fields independently encode the same fact by hand and had nothing tying them together before this.

task() is untouched

Confirmed: task()'s behavior, argument schema, and wire contract are unchanged. It remains the only spawn verb. The tier check only governs which callers may have task / search_agents mounted at all — main stays shippable at every commit.

Docs

docs/ARCHITECTURE.md's "Fleet authority tiers" section now states plainly which check is live-and-fails-closed (assertTierMayMountFleetVerb) versus an unwired seam (assertCanTargetAgent), and covers the profile-sourced fleetTier opt-in and why it isn't named tier. CHANGELOG.md reflects the fail-closed behavior, not the earlier (incorrect) claim.

Gate

bun run check (lint + typecheck + build + test), run in the foreground: 5379 tests pass, 0 fail.

[linear-code]

CL-6941