Merge pull request #767 from corbitsdev/cl-7088-drop-leaf-language-fleet-agents-ask-skywalker-not-a-human

Let fleet agents ask their parent, not a human

Author: TheGreatAxios

CHANGELOG.md

@@ -50,7 +50,9 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 - Workers can ask their spawning director via `ask_director` when a brief is
   ambiguous. `wait_agents` returns `awaiting_director` with the question;
   soft `send_input` answers it. The operator is not in that loop unless the
-  director escalates. Leaves still cannot call `ask_operator`.
+  director escalates. Workers still cannot call `ask_operator`.
+- Spawned workers are called fleet agents, not leaves. Director packages still
+  use `tier: "leaf"` as the runtime mount key.
 - Agents and contributor docs move Linear issues to In Review when a PR is ready
   for review.
 

docs/ARCHITECTURE.md

@@ -160,7 +160,7 @@ Sixteen packages under `src/agent/directors/<id>/` register in `DIRECTOR_REGISTR
 4. `directorProfiles()` is the spawn catalog (`default-agents.ts`) — closed set minus skywalker. Plugin and local `.agents/agents/` profiles still load, but closed `DIRECTOR_IDS` cannot be overridden or aliased.
 5. Primary chat role is Skywalker: `buildChatRole()` → `createSkywalkerSystemPrompt()`. Product mutation tools (`write_file` / `edit_file` / `delete_file`) live in CORE (and `SKYWALKER_TOOLS`) so they are advertised on the primary without a `tool_search` round-trip. DIY tiny/bounded edits on the parent; spawn builder/docs directors for substantial work — a prompt judgment call, not a toolset strip. `PRIMARY_DENIED_PRODUCT_TOOLS` is gone. Shell file-writes stay denied; MCP tools are not re-filtered by a product-write deny list. There is no static per-profile write-path lock (CL-6952).
 
-   **Codex tool proxies.** When the active provider is Codex (`isCodexProviderName`), `createAgentToolset` and `runSubAgent` mount `apply_patch`, `shell`, and `update_plan` stringTools from `createCodexToolProxies`, all forwarding through the same posix `ToolRunner` seam (`runTool`) so permission plugins still apply. `apply_patch` parses the Codex envelope and forwards each op (`write_file` / `delete_file` / `read_file`). `shell` — the native Codex name is `shell`, not `exec_command`, per the pinned base-instructions text quoted in `codex-responses-adapter.ts`'s bridge message — normalizes Codex's `command` (string or `["bash","-lc",script]`-style argv array), `workdir`, and `timeout_ms` onto `run_shell`'s `{command, cwd?, timeout?}` and is gated by `allowShellFromCapabilities` (mirrors `allowDeleteFromCapabilities` against `run_shell`). `update_plan` maps Codex's `plan: [{step, status}]` onto `manage_tasks(action: "create")`; `pending`/`in_progress`/`completed` map to `todo`/`doing`/`done` — `manage_tasks`'s `cancelled` status has no Codex equivalent and is never produced by this proxy. Primary strips `apply_patch` after mount (Corbits DIY stays on `write_file` / `edit_file` / `delete_file`); `shell` and `update_plan` stay on primary (same classification as `run_shell` / `manage_tasks`). Build and docs leaf allowlists (`BUILD_TOOLS` / `DOCS_TOOLS`) include `apply_patch` so Codex workers keep the proxy after the capability filter. `CORE_TOOL_NAMES` does not list it.
+   **Codex tool proxies.** When the active provider is Codex (`isCodexProviderName`), `createAgentToolset` and `runSubAgent` mount `apply_patch`, `shell`, and `update_plan` stringTools from `createCodexToolProxies`, all forwarding through the same posix `ToolRunner` seam (`runTool`) so permission plugins still apply. `apply_patch` parses the Codex envelope and forwards each op (`write_file` / `delete_file` / `read_file`). `shell` — the native Codex name is `shell`, not `exec_command`, per the pinned base-instructions text quoted in `codex-responses-adapter.ts`'s bridge message — normalizes Codex's `command` (string or `["bash","-lc",script]`-style argv array), `workdir`, and `timeout_ms` onto `run_shell`'s `{command, cwd?, timeout?}` and is gated by `allowShellFromCapabilities` (mirrors `allowDeleteFromCapabilities` against `run_shell`). `update_plan` maps Codex's `plan: [{step, status}]` onto `manage_tasks(action: "create")`; `pending`/`in_progress`/`completed` map to `todo`/`doing`/`done` — `manage_tasks`'s `cancelled` status has no Codex equivalent and is never produced by this proxy. Primary strips `apply_patch` after mount (Corbits DIY stays on `write_file` / `edit_file` / `delete_file`); `shell` and `update_plan` stay on primary (same classification as `run_shell` / `manage_tasks`). Build and docs worker allowlists (`BUILD_TOOLS` / `DOCS_TOOLS`) include `apply_patch` so Codex workers keep the proxy after the capability filter. `CORE_TOOL_NAMES` does not list it.
 
 6. There is no static write-path declaration on packages or profiles (CL-6952 removed it — no shipped director ever set one). Instead, `agent-fleet.ts` tracks each running dispatch by cwd; a new dispatch that lands on the same cwd as a still-running lane records a `concurrent-lane-overlap` entry in `intervention-log.ts` (class `conflict`). This is advisory only — it never blocks the spawn, since cwd overlap does not prove the two lanes touch the same files.
 7. Spawn effort: pin > package `modelRole` default (`defaultEffortForDirector`; intern=low; plan/review/orchestrator=high; implement/explore/docs/test=medium) > orchestrator/worker binary > parent inheritance. Optional skills are listed in the identity header for awareness; workers do not mount `use_skill` (guidance is baked into package system prompts). Primary mounts `use_skill` for its own skill list.

docs/IMPLEMENTATION.md

@@ -146,7 +146,7 @@ The kind-specific export is the implementation hook:
 | `command`  | `commandPlugin`                             | slash-command registry                     | slash commands                                              |
 | `workflow` | `workflowPlugin` + optional `commandPlugin` | workflow registry + slash-command registry | named workflow recipes behind an integration command prefix |
 | `tool`     | `toolPlugin` (factory)                      | posix toolset                              | add new agent tools (highest trust)                         |
-| `agent`    | `agentPlugin`                               | sub-agent profiles                         | contribute `spawn_agent`-dispatchable agent profiles        |
+| `agent`    | `agentPlugin`                               | fleet-agent profiles                       | contribute `spawn_agent`-dispatchable agent profiles        |
 
 A module with no valid manifest is ignored (not silently half-loaded).
 

docs/PLUGINS.md

@@ -35,7 +35,7 @@ The evidence is in how the product fails today: the personas already produce exc
 ## Key Value Propositions
 
 1. **Deterministic progress** — Every turn must produce a tool call. No idle thinking; the director aborts a stalled run rather than spinning.
-2. **Task tracking** — The agent can maintain a `manage_tasks` checklist for multi-step work; non-interactive `submit_output` is blocked while checklist items remain open. (A "task" here is a work item, not a child agent — spawning uses the separate `spawn_agent` / `wait_agents` sub-agent surface.)
+2. **Task tracking** — The agent can maintain a `manage_tasks` checklist for multi-step work; non-interactive `submit_output` is blocked while checklist items remain open. (A "task" here is a work item, not a child agent — spawning uses the separate `spawn_agent` / `wait_agents` fleet-agent surface.)
 3. **Stall detection** — The director detects idle cycles and intervenes.
 4. **Safe by default** — Consequential actions (writes, edits, shell) pass a permission gate; secret files and catastrophic commands are denied outright, regardless of intent.
 5. **Resume capability** — Runs persist to a git-backed store and resume from the last point after interruption.
@@ -151,7 +151,7 @@ Capabilities beyond the core toolset are opt-in plugins, enabled per workspace t
 
 - **Web search and fetch** — `web_search`/`web_fetch` are always-on built-in core tools, no plugin or API key required. `web_fetch` runs in-process (Bun native `fetch()`) with SSRF guarding, a 5 MB response cap, and HTML-to-markdown conversion; `web_search` calls a keyless hosted MCP provider (Exa by default, Parallel optional). See `docs/ARCHITECTURE.md` for details.
 
-## Multi-agent (sub-agents)
+## Multi-agent (fleet agents)
 
 The primary session is always **orchestrator** (single-agent mode is gone). Its identity is **Skywalker** (product name remains Corbits Code; when asked its name, answer Skywalker): classify work, DIY tiny/single-file/one-route product edits, dispatch a **closed fleet of 16 directors** for substantial work, track the fleet, and synthesize. Product mutation tools (`write_file` / `edit_file` / `delete_file`) are mounted on the primary (CORE / `SKYWALKER_TOOLS`) — path tools are the DIY surface; spawn remains the default for substantial, multi-file, parallel, or specialist work. Shell file-writes stay denied. MCP tools are not re-filtered by a product-write deny list (that list is gone). There is no static per-package write-path declaration (CL-6952 removed it — no shipped director ever set one). A concurrent dispatch landing on the same working directory as another still-running lane is recorded as a `conflict` intervention, not blocked. Operator slash recipes (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`, `/ast-grep`) tell Skywalker which directors to spawn for substantial work; tiny/bounded edits may run on the primary.
 
@@ -164,11 +164,11 @@ The primary session is always **orchestrator** (single-agent mode is gone). Its
 
 There is **no catch-all worker**. `spawn_agent` requires `agent=…` or a non-general `intent` (implement/explore/plan/review→critic); bare dispatch and `intent=general` are refused. Named `spawn_agent(agent=…)` selects a director package without requiring a plugin profile, except `skywalker` which is the primary session identity and is refused as a spawned worker. Nested spawn is runtime-enforced: only skywalker (full fleet allowlist) and greybeard (intern/explorer/critic) may spawn; other workers have no fleet tools. Primary omits an allowlist so plugin profiles remain reachable from the main session.
 
-Corbits Code fans work out to short-lived **sub-agents** — child agents with their own loop, tools, and checklist — while the primary session stays focused.
+Corbits Code fans work out to short-lived **fleet agents** — workers with their own loop, tools, and checklist — while the primary session stays focused.
 
 - **Agents** are runtime entities (primary session or child).
 - **Tasks** are checklist items owned by one agent via `manage_tasks`.
-- **Sub-agents** are spawned with `spawn_agent` / `wait_agents`.
+- **Fleet agents** are spawned with `spawn_agent` / `wait_agents`. Workers ask the parent with `ask_director`. When `wait_agents` returns status `running` plus a question payload, the parent answers with `send_input`, then `wait_agents` again. Escalate to the human only with `ask_operator`.
 
 Dispatch uses a structured brief (context / goal / optional goals seed) and returns a structured report. The TUI Agents strip and fleet board show who is running; live tool progress updates the status bar without dumping the child transcript into the parent chat. There is no turn budget. A tool-less final turn completes only with the four-heading report envelope; without it, one nudge is given and a second tool-less turn without the envelope salvages as `incomplete-report-stop`. A silent worker (no activity for `stallTimeoutMs`, opt-in) gets one continuation nudge, then salvages as `stalled` if a second consecutive check finds no activity. An opt-in `deadlineMs`, or an operator cancel, can also end a run early. Each of these returns a salvage report so a runaway or idle child cannot quietly burn a large token budget or look done after prose alone.
 

docs/PRODUCT.md

@@ -106,7 +106,7 @@ milliseconds and converts.
 (`tool_call_count`, `tool_error_count`, `subagent_call_count`). Per-call
 `$ai_span` events are **off by default**. Set `CORBITS_TELEMETRY_AI_SPANS` to
 a truthy value (`1`, `true`, …) to restore per-call spans for debugging.
-Leaf `runSubAgent` workers do not emit `$ai_*`; worker rollups travel on
+`runSubAgent` workers do not emit `$ai_*`; worker rollups travel on
 `subagent_end` instead. Both TUI and exec install the same turn observer, so a
 worker ending during an active parent turn carries that turn's `parent_trace_id`.
 Pre-progress operator aborts settle with `status=cancelled` and

docs/TELEMETRY.md

@@ -72,7 +72,7 @@ prose into a hard-capped inset paragraph (`LIVE_THINKING_MAX_LINES`, currently 1
 (assistant text, a tool call, or settle), the row collapses to its opening
 clause with the rest behind expand. Mid-turn thinking bursts fold onto that
 same one row per turn (`reasoning-fold`); `inference.text.delta` grows the
-open assistant streaming row in place. Sub-agent spawn_agent-row thinking is a
+open assistant streaming row in place. Worker spawn_agent-row thinking is a
 separate path and is unchanged by this preview.
 
 The prompt box's border carries the metadata that would otherwise cost a
@@ -120,15 +120,15 @@ printed identically, so the only way to tell them apart was to wait.
 waiting on something outside itself — and are told apart by motion: `blocked`
 holds perfectly still, which is the signal that the session is waiting on _you_.
 
-While sub-agents are running, the slot reports the _fleet_, not the parent.
+While fleet agents are running, the slot reports the _fleet_, not the parent.
 `resolveTurnLabel` and `resolveRampPhase` take a `FleetProgress` roll-up and
 rank it above the parent's own stall clock: with live lanes the parent is
 idle by design, so its silence says nothing about whether the session is
 progressing, and reporting it was how a session with every lane wedged still
 read as `working`. A fleet with no stalled lane reads `working`; one
 stalled lane makes the whole indicator read `stalled`, which is the state that
 should pull an operator's eye to the panel. A blocked gate and a stopping turn
-still outrank the fleet. With zero running sub-agents the roll-up is empty and
+still outrank the fleet. With zero running fleet agents the roll-up is empty and
 every path through both functions behaves exactly as it does for a plain
 single-agent turn.
 
@@ -249,7 +249,7 @@ when non-zero, e.g. `N done, M failed, K cancelled · nothing running`).
 Per-lane `done — summary` walls and live `dispatched` re-announcements
 are never printed.
 
-`src/subagent/fleet-report.ts` is pure: it reads the same sub-agent session
+`src/subagent/fleet-report.ts` is pure: it reads the same fleet-agent session
 store and the same `agentProgress()` stall definition. Store changes drive it;
 a `FLEET_REPORT_SETTLE_MS` (400ms) timer lets a parallel dispatch settle into
 one observation. Quiet detection uses `FLEET_STALL_POLL_MS` (5s). Past
@@ -553,13 +553,13 @@ at the interrupt itself (`doInterrupt` drains after `port.interrupt()`), not
 left waiting on an idle event the stop may never produce (`interrupt` in
 `session-queue.ts` no longer clears `items`).
 
-**Sub-agent lanes on redirect.** Soft steer (Enter mid-run) and follow-up
+**Fleet agent lanes on redirect.** Soft steer (Enter mid-run) and follow-up
 (queued drain) leave running workers alone — they never call
 `runner.ts`'s `interrupt()`, so the parent's operation signal stays live and
 spawned workers keep running. Ctrl+C is the explicit fleet teardown:
 `doInterrupt` → `port.interrupt()` → `currentAgent.close()` aborts the shared
 operation signal and routes cancellation through the fleet/session-store
-teardown path, so in-flight sub-agent dispatch reports back as cancelled by
+teardown path, so in-flight fleet-agent dispatch reports back as cancelled by
 the operator rather than being left to finish silently detached. `/clear` and
 session exit still call `subAgentSessions.cancelAll` for an explicit
 session-wide cancel; that path is separate from interrupt and must stay off
@@ -616,7 +616,7 @@ Ctrl+C within a 2-second window (`CTRL_C_EXIT_WINDOW_MS`) quits — this
 replaced an Ink-era yes/no exit-confirm modal with the same intent (an
 explicit second confirmation) without adding a modal (`handleCtrlC`,
 `shell.ts`). See "Soft steer vs. follow-up" above for the two
-mid-run gestures and what interrupting does to sub-agent lanes. The interrupt
+mid-run gestures and what interrupting does to fleet-agent lanes. The interrupt
 keeps whatever is sitting in the queue rather than discarding it — the
 operator typed those messages meaning them delivered, not meaning "cancel
 this run and also throw away what I typed"; the transcript row says so