Add headless dispatch arbiter

README.md

@@ -10,7 +10,7 @@ Use dreb if you want a coding agent that can run against direct APIs, coding sub
 - **Model and provider freedom.** Authenticate with API keys or `/login` subscriptions, switch models at runtime with `/model`, scope model sets, tune thinking levels, route built-in providers through proxies, use cloud providers such as Bedrock/Vertex/Azure, or add local/proxy/custom models through [Custom Models](packages/coding-agent/docs/models.md) and [Custom Providers](packages/coding-agent/docs/custom-provider.md). See [Providers](packages/coding-agent/docs/providers.md) for the current setup list.
 - **A real development workflow.** [mach6](packages/coding-agent/docs/mach6.md) is a built-in issue-to-merge workflow: assess issues, plan work, open draft PRs, implement, push progress, run multi-agent reviews, independently assess findings, fix CI or review items, and publish. Plans, reviews, and progress live on GitHub as shared memory.
 - **Composable agent building blocks.** [Skills](packages/coding-agent/docs/skills.md) are markdown workflows loaded on demand; [extensions](packages/coding-agent/docs/extensions.md) are TypeScript modules for custom tools, commands, event hooks, UI components, renderers, keybindings, provider registration, permission gates, and workflow automation; [packages](packages/coding-agent/docs/packages.md) bundle skills, extensions, prompts, and themes for npm, git, or local sharing.
-- **Parallel and specialized agents.** The `subagent` tool runs independent child agents in single, parallel, or chain mode. Custom agent definitions can inherit models, record child-session metadata for audit trails, and power workflows such as mach6's specialized code, error, test, completeness, and simplification reviewers. Per-agent models can be overridden via the [`agentModels` setting](packages/coding-agent/docs/agent-models.md), while each request can explicitly set a validated child thinking level. The built-in [`model-routing-guide` skill](packages/coding-agent/docs/skills.md#model-routing-guide) researches model patterns passed to it—or `enabledModels` when invoked without arguments—and local subagent history to produce practical role/cost guidance, especially keeping planning and implementation away from `Explore` and routine lookup work away from unnecessarily expensive models. The parent session's running model is exposed in its own system prompt (`You are running on: provider/id`), enabling self-aware routing decisions such as delegating to a multimodal or differently-architected subagent. While background subagents run, a guardrail pauses the parent after a few turns and surfaces a friendly, non-error notification (in the TUI and Telegram) explaining the intentional pause — configurable or disable-able via [`backgroundAgents`](packages/coding-agent/docs/settings.md#background-agents).
+- **Parallel and specialized agents.** The `subagent` tool runs independent child agents in single, parallel, or chain mode. Custom agent definitions can inherit models, record child-session metadata for audit trails, and power workflows such as mach6's specialized reviewers. Per-agent models and per-request thinking remain explicit controls. The built-in [`model-routing-guide` skill](packages/coding-agent/docs/skills.md#model-routing-guide) researches scoped provider/model candidates and local child history, and its `update` mode preserves retained entries while removing stale scope and researching newly added models; the optional global-only [Dispatch Arbiter](packages/coding-agent/docs/agent-models.md#dispatch-arbiter) consumes that guide in a fully headless, tool-less call before every child spawn and may change only agent, scoped canonical model, and supported thinking. Its bounded rolling parent activity follows the title setter and includes useful tool outputs, with existing secret scrubbing applied before inference. It is disabled by default and fails closed—bad configuration, guide, inference, or decisions prevent the child from spawning rather than silently keeping the original route. TUI `/settings` and dashboard Settings expose its enable toggle, exact model, thinking, guide path, and validation/readiness feedback. Typed decisions are persisted and visible in the TUI, JSON/RPC, and dashboard. While background subagents run, a separate guardrail pauses the parent after a few turns, configurable via [`backgroundAgents`](packages/coding-agent/docs/settings.md#background-agents).
 - **Durable context.** [Sessions](packages/coding-agent/docs/session.md) are JSONL trees with resume/continue, `/tree` navigation, `/fork`, CLI `--fork`, compaction, HTML export, and JSONL import/export. [Memory](packages/coding-agent/README.md#memory) is file-based, global + project-scoped, survives sessions, can read Claude Code project memory, and can be maintained with `/dream` memory consolidation.
 - **A capable terminal workspace.** The TUI supports slash commands, file references with `@`, path completion, image paste/drag, bash shortcuts, hotkeys, settings, model cycling, steering/follow-up queues while the agent is working, token/cost/context status, custom themes, and extension-provided UI surfaces. Transcript prose, code, tool output, and agent results use terminal soft-wrap so copying from scrollback keeps long logical lines intact instead of injecting hard newlines.
 - **Optional local companion.** [`/buddy`](packages/coding-agent/docs/buddy.md) hatches an Ollama-powered terminal companion with persistent state, generated personality/backstory, event reactions, idle quips, name-call responses, pet/reroll/stats commands, and a sidebar presence while you work.
@@ -135,7 +135,7 @@ The dashboard is the visual face of dreb: every agent session on the host, live
 
 <!-- screenshot: session view with tool cards + subagent strip, desktop (dark) -->
 
-**Live subagent observability.** Background subagents are first-class: chips on the parent session, live counts on fleet cards, and a read-only drill-in transcript per agent that streams in real time and survives browser reloads.
+**Live subagent observability.** Background subagents are first-class: chips on the parent session, live counts on fleet cards, and a read-only drill-in transcript per agent that streams in real time and survives browser reloads. When the Dispatch Arbiter is enabled, those views also show its host-validated changed, unchanged, or failed pre-spawn decision and the final routed agent/model/thinking—never raw arbiter output.
 
 **Live connection recovery.** The top bar and persistent session header have an accessible, text-labelled connection indicator (connecting, connected, retrying, resyncing, disconnected, or auth failed). SSE uses bounded replay and an authoritative snapshot barrier to recover from browser reloads, server restarts, sequence gaps, slow-client backpressure, and stalls without duplicating state; task lists restore with the session snapshot. Named 25-second heartbeats and a foreground 60-second liveness watchdog detect a stuck stream. See [dashboard recovery details](packages/coding-agent/docs/dashboard.md#live-connection-and-recovery) and the [RPC ordering contract](packages/coding-agent/docs/rpc.md#get_dashboard_snapshot).
 

package.json

@@ -39,7 +39,7 @@
     "node": "22.x"
   },
   "packageManager": "npm@11.5.1",
-  "version": "2.45.4",
+  "version": "2.46.0",
   "dependencies": {
     "@dreb/coding-agent": "*",
     "@mariozechner/jiti": "^2.6.5",

packages/agent/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/agent-core",
-	"version": "2.45.4",
+	"version": "2.46.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"type": "module",
 	"main": "./dist/index.js",

packages/ai/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/ai",
-	"version": "2.45.4",
+	"version": "2.46.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"type": "module",
 	"main": "./dist/index.js",

packages/coding-agent/README.md

@@ -396,9 +396,11 @@ The `subagent` tool delegates tasks to independent child agent processes. Each s
 
 **Per-agent model overrides:** The model used by each agent type can be overridden via the `agentModels.models` setting (a map of agent name → ordered fallback list) without copying or editing the agent definition `.md` files. Configure it in `settings.json` or via `/settings` → **Agent Models**. Resolution order: per-invocation `model` override → `agentModels` setting → agent definition `model` → parent session model. See [docs/agent-models.md](docs/agent-models.md).
 
+**Optional Dispatch Arbiter:** A global-only `subagentArbiter` setting can enable a fully headless, direct model call after the proposal above resolves but before each child process spawns. It uses the validated routing guide, live explicit model scope, and bounded title-setter-style parent activity including useful tool outputs; existing secret scrubbing applies before inference. It may change only the existing agent type, exact scoped provider/model, and supported thinking level. It has no tools, cannot rewrite the task/cwd or agent definitions, and fails closed on configuration, guide, scope, inference, output, or validation errors. It runs once per single/parallel child and after `{previous}` substitution for every chain step. Interactive `/settings` and dashboard Settings both expose enable/disable, exact model selection, thinking, guide path, and loud readiness/validation feedback. Safe typed changed/unchanged/failure records are persisted outside parent model context and relayed to the TUI, JSON/RPC, and dashboard. See [Dispatch Arbiter](docs/agent-models.md#dispatch-arbiter) and [settings](docs/settings.md#dispatch-arbiter).
+
 **Model identity in system prompt:** The parent session's running model is exposed in its own system prompt as `You are running on: provider/id`. This lets the model make self-aware routing decisions (e.g. delegate vision tasks to a multimodal subagent, or use a differently-architected model as a critic). The line updates automatically on mid-session model switches.
 
-**Session and event metadata:** Each child process records its agent type in the session JSONL header (`agentType` field), providing an audit trail of which agent definition executed the work. Child `agent_start`, subagent results, and `background_agent_end` also expose the canonical resolved `provider/model` and effective thinking level, including defaults used when no override was supplied. Chain completion events expose ordered per-step metadata because steps may use different models or thinking levels.
+**Session and event metadata:** Each child process records its agent type in the session JSONL header (`agentType` field), providing an audit trail of which agent definition executed the work. Child `agent_start`, subagent results, and `background_agent_end` also expose the canonical resolved `provider/model` and effective thinking level, including defaults used when no override was supplied. Chain completion events expose ordered per-step metadata because steps may use different models or thinking levels. Enabled arbiter attempts add a separate `subagent_arbitration` event with proposed/final routes, changed fields, status, optional chain step, and safe host error metadata; raw prompts, responses, and reasoning are never included.
 
 **Background-agent guardrail:** Background subagents run asynchronously and return control to you while they work. To stop the parent agent from spinning ahead of results, a guardrail pauses it after `backgroundAgents.parentTurnLimit` turns (default 3) while subagents are still running. When this happens, dreb surfaces a friendly, non-error notification in the TUI and Telegram — explaining that background agents are still working and the parent paused intentionally, and that it resumes when they report back or when you send a message to steer it. This is a frontend/session event, not a model-context steer, so it can't go stale. Set `backgroundAgents.parentTurnGuardrail` to `false` to let the parent run unbounded while subagents work, or raise `parentTurnLimit` to relax the guardrail. See [settings](docs/settings.md#background-agents).
 
@@ -462,7 +464,7 @@ Place in `~/.dreb/agent/skills/`, `~/.agents/skills/`, `.dreb/skills/`, or `.age
 
 dreb ships with **mach6** — a built-in development workflow (issue → plan → push → review → fix → publish) that uses GitHub as shared memory and multi-agent code review. See [docs/mach6.md](docs/mach6.md).
 
-It also ships with the explicitly invoked **`model-routing-guide`** skill. Pass comma-separated model patterns as arguments, or run it without arguments to use the effective non-empty `enabledModels` array. Those are its only scope sources: it cannot discover a session's runtime `--models` value, so pass those same patterns explicitly when that is the intended scope. It researches canonical provider/model candidates, external evidence, and sanitized aggregate subagent history, then validates and writes `~/.dreb/agent/model-routing-guide.md`. See [docs/skills.md](docs/skills.md#model-routing-guide).
+It also ships with the explicitly invoked **`model-routing-guide`** skill. Pass comma-separated model patterns as arguments, or run it without arguments to use the effective non-empty `enabledModels` array. Prefix either form with `update` to diff an existing guide against the resolved scope, preserve retained entries, remove stale ones, and research newly added models instead of rebuilding everything. Those are its only scope sources: it cannot discover a session's runtime `--models` value, so pass those same patterns explicitly when that is the intended scope. It researches canonical provider/model candidates, external evidence, and sanitized aggregate subagent history, then validates and writes `~/.dreb/agent/model-routing-guide.md` atomically. The optional global Dispatch Arbiter consumes the guide only when its exact coverage matches the live explicit scope. See [docs/skills.md](docs/skills.md#model-routing-guide) and [docs/agent-models.md](docs/agent-models.md#dispatch-arbiter).
 
 ### Extensions
 

packages/coding-agent/docs/agent-models.md

@@ -48,7 +48,25 @@ The built-in `/skill:model-routing-guide` workflow has exactly two scope sources
 
 Because Stage 1 is a skill-only workflow, it cannot discover a session's runtime `--models` value or later in-session scope changes. Pass the same patterns as skill arguments when that runtime scope is the intended research set. The workflow resolves candidates against `dreb --list-models`, combines canonical provider/model documentation and public evidence with sanitized aggregate observations from local subagent session logs, then writes and validates `~/.dreb/agent/model-routing-guide.md`.
 
-The guide is intended to improve role and cost fit, especially keeping planning/implementation work out of `Explore` and reserving expensive frontier models for work that actually needs them. It does not change the model resolution order above. See [skills.md](skills.md#model-routing-guide).
+The guide is intended to improve role and cost fit, especially keeping planning/implementation work out of `Explore` and reserving expensive frontier models for work that actually needs them. Guide generation alone does not change routing; the optional Dispatch Arbiter below consumes it. See [skills.md](skills.md#model-routing-guide).
+
+## Dispatch Arbiter
+
+`subagentArbiter` is an opt-in, global-only pre-spawn control. Users configure it through interactive `/settings`, dashboard Settings, global `settings.json`, or the RPC settings API; both normal UIs expose enable/disable, exact model, thinking, guide path, and loud readiness/validation feedback. Project settings cannot shadow any field. The normal resolution order above first produces one concrete proposal. The arbiter then runs once before each actual child spawn—single, every parallel item, and every chain step after `{previous}` substitution—and returns exactly:
+
+```json
+{"agent":"feature-dev","model":"provider/model-id","thinking":"high"}
+```
+
+The host accepts only those three exact fields. The agent must already be available through the parent's `subagent` tool, the model must be an exact canonical member of the current live explicit scope, and thinking must be supported by that model. The selected existing definition supplies its system prompt and filtered tool configuration verbatim. Task, cwd, chain-substituted content, parent linkage, and every non-routing field remain unchanged.
+
+The arbiter follows the tab/session-title setter's small headless pattern: `AgentSession` maintains a bounded `RollingContextBuffer`, then the control path makes a direct `completeSimple()` call with the configured model/API key, timeout, and no tools or child process. There is no parent-model fallback. One malformed JSON response may be retried once; all configuration, guide, scope, auth/provider, timeout, parse, agent, model, and thinking failures prevent spawn.
+
+The validated input contains the immutable task/cwd, proposed route, safe summaries of all available definitions (name, description, effective tools, model defaults), exact live candidates, the matching guide, bounded first/latest user intent and recent labeled parent activity—including bounded tool outputs—parent model/session title, metadata-only repository/cwd/branch/dirty count, and lineage identifiers. Following the title setter's rolling-context pattern, ordinary file contents, diffs, command output, and other useful tool-result content are not categorically removed; the serialized package receives the existing secret scrubbing before remote inference. The arbiter itself receives no tools. The child still receives the original unsanitized task/cwd exactly as provided.
+
+Every enabled attempt emits and persists a safe `subagent_arbitration` record with proposed/final routes, changed fields, success/failure, optional chain step, and host-generated errors. Raw arbiter prompt/output/reasoning is never persisted or inserted into either model context. The TUI, JSON/RPC, and dashboard consume the same typed record; dashboard agent identity updates to the final selected agent before child events arrive.
+
+Configuration and failure details are in [settings.md](settings.md#dispatch-arbiter); event shapes are in [json.md](json.md) and [rpc.md](rpc.md).
 
 ## Parent Model Identity in System Prompt