@dreb/coding-agent 2.45.4 → 2.46.0

package/docs/rpc.md

@@ -1243,17 +1243,18 @@ Note: with `summarize: true` the command is LLM-bound and can take a while. `Rpc
 
 ### Settings
 
-Persistent settings, backed by the settings file (see [settings.md](settings.md)). They are normally distinct from live session state, with one security-policy exception:
+Persistent settings, backed by the settings file (see [settings.md](settings.md)). They are normally distinct from live session state, with global-only control/security-policy exceptions:
 
 - **Persistent defaults** (`get_settings` / `set_settings`): provider/model, thinking level, queue modes, compaction/retry/image/skill/thinking-display/transport toggles, and per-agent model fallback lists seed fresh runtimes. Writing these ordinary defaults does **not** change a running session.
 - **Global nested-context trust policy** (`autoLoadNestedContext`, `trustedContextFolders`, `effectiveTrustedContextRoots`, and the trust commands below): this is read from `~/.dreb/agent/settings.json` only, never project settings. Active main/subagent processes observe it for **future lazy nested/out-of-cwd loads**; it cannot remove content already injected into a conversation. It does not govern the separate initial upward context scan from the launch cwd.
+- **Global Dispatch Arbiter policy** (`subagentArbiter`): the complete object is read/written globally and project settings cannot shadow it. Enabled runtimes consume it before future subagent spawns; it does not rewrite already-started children.
 - **Runtime state** (`get_state` / `set_model` / `set_thinking_level` / `set_steering_mode` / `set_follow_up_mode` / `set_auto_compaction` / `set_auto_retry`): the state of the live session. Note that the runtime setters also persist their values as new defaults as a side effect.
 
 A dashboard settings tab typically reads `get_state` for what is active now and `get_settings` for persistent defaults plus the current global context-trust policy.
 
 #### get_settings
 
-Get persistent settings. Before replying, RPC flushes pending settings writes, reloads durable global and project settings, and then reads the merged view; reopening dashboard Settings therefore sees external file edits. A pending write failure, unreadable file, parse error, or reload failure returns an explicit RPC error rather than a stale snapshot. Ordinary fields are the merged global + project view; the nested-context trust fields are always global-only.
+Get persistent settings. Before replying, RPC flushes pending settings writes, reloads durable global and project settings, and then reads the merged view; reopening dashboard Settings therefore sees external file edits. A pending write failure, unreadable file, parse error, or reload failure returns an explicit RPC error rather than a stale snapshot. Ordinary fields are the merged global + project view; nested-context trust and `subagentArbiter` are always global-only.
 
 ```json
 {"type": "get_settings"}
@@ -1283,6 +1284,12 @@ Response:
     "hideThinkingBlock": false,
     "agentModels": {
       "Explore": ["anthropic/sonnet", "openai/gpt-5"]
+    },
+    "subagentArbiter": {
+      "enabled": true,
+      "model": "anthropic/claude-sonnet-4-5",
+      "thinking": "medium",
+      "guidePath": "~/.dreb/agent/model-routing-guide.md"
     }
   }
 }
@@ -1292,6 +1299,8 @@ Response:
 
 `trustedContextFolders` is the raw global configured list, including invalid legacy paths that are ignored fail-closed. `effectiveTrustedContextRoots` is the canonical, existing root set actually enforced after `~` expansion, native `realpath`, deduplication, and ancestor subsumption. `autoLoadNestedContext` defaults to `false`; when `true` it is global expert trust-all for every resolvable target, not a project override. Project `.dreb/settings.json` cannot affect any of these three fields.
 
+`subagentArbiter` is absent when unconfigured. It is always the global object; project `.dreb/settings.json` cannot enable, disable, or alter it.
+
 #### set_settings
 
 Update persistent default settings. Takes a partial payload — only the supplied keys change. The whole payload is validated before anything is applied: on any invalid field, nothing changes and the response is an explicit error. Writes target the global settings file (same scope as every runtime setter).
@@ -1330,6 +1339,14 @@ Setting per-agent model fallback lists:
 
 For `agentModels`, a non-empty array writes the global fallback list for that agent. An empty array removes the global entry, so that agent uses its agent-definition default unless a project-level override exists.
 
+Replace the complete global-only Dispatch Arbiter policy (exact model is validated; explicit thinking is capability-validated):
+
+```json
+{"type":"set_settings","settings":{"subagentArbiter":{"enabled":true,"model":"anthropic/claude-sonnet-4-5","thinking":"medium","guidePath":"~/.dreb/agent/model-routing-guide.md"}}}
+```
+
+Set `subagentArbiter: null` to remove the global policy. Enabling requires `model`; `guidePath` defaults to the standard guide path and omitted thinking runs the arbiter call with thinking off. Runtime guide/scope validation still occurs at each spawn because the live explicit scope can change.
+
 Response is the full settings snapshot after the write (same shape as `get_settings`), plus `warnings` when the write was accepted but a project-level override shadows part of it:
 
 ```json
@@ -1406,6 +1423,7 @@ Valid keys and values:
 | `transport` | `"sse"`, `"websocket"`, `"auto"` |
 | `hideThinkingBlock` | boolean |
 | `agentModels` | Plain object mapping agent names to arrays of non-empty model id strings; empty arrays remove the global entry for that agent |
+| `subagentArbiter` | Complete global-only object or `null`. Keys: `enabled` boolean, exact available `model`, optional valid/capability-supported `thinking`, non-empty `guidePath`. Enabling requires `model`. Unknown nested keys are rejected. |
 
 Errors are explicit `success: false` responses (nothing is applied on any of them):
 
@@ -1419,6 +1437,7 @@ Errors are explicit `success: false` responses (nothing is applied on any of the
 - Invalid trusted-root list: `trustedContextFolders must be an array of non-empty path strings` or `Invalid trustedContextFolders[0]: path must be absolute after ~ expansion` / `path must be an existing directory`
 - Provider without model (or vice versa): `defaultProvider and defaultModel must be set together`
 - Unavailable model: `Model not found: provider/model-id`
+- Invalid arbiter policy: `Enabling subagentArbiter requires an exact provider/model`, `Arbiter model not found: ...`, or a nested-key/type/thinking capability error
 - Corrupt settings file: `Cannot write settings: the global settings file failed to load (fix or remove the corrupt settings.json first)` — without this guard the write would silently no-op
 - Write failure (I/O error): `Failed to persist settings: ...`
 
@@ -1584,7 +1603,7 @@ Response:
 
 | Event | Description |
 |-------|-------------|
-| `agent_start` | Agent begins processing |
+| `agent_start` | Agent begins processing (resolved model and effective thinking level) |
 | `agent_end` | Agent completes (includes all generated messages) |
 | `turn_start` | New turn begins |
 | `turn_end` | Turn completes (includes assistant message and tool results) |
@@ -1601,7 +1620,7 @@ Response:
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
 | `background_agent_start` | Background subagent launched (includes `sessionDir`) |
-| `background_agent_end` | Background subagent finished (includes `sessionFile` when known) |
+| `background_agent_end` | Background subagent finished (canonical model/thinking, per-step chain metadata, and `sessionFile` when known) |
 | `background_agent_event` | Relayed event from a background subagent's own stream |
 | `parent_paused_for_background_agents` | Parent paused waiting on background agents |
 | `session_name_changed` | Session display name changed (manual rename, extension rename, or auto-title) |
@@ -1615,10 +1634,10 @@ rather than validating against a closed list; new event types may be added.
 
 ### agent_start
 
-Emitted when the agent begins processing a prompt. Includes the resolved model.
+Emitted when the agent begins processing a prompt. Includes the resolved model and effective thinking level sent to the provider.
 
 ```json
-{"type": "agent_start", "model": {"provider": "anthropic", "id": "claude-sonnet-4-20250514"}}
+{"type": "agent_start", "model": {"provider": "anthropic", "id": "claude-sonnet-4-20250514"}, "thinkingLevel": "high"}
 ```
 
 ### agent_end
@@ -1806,9 +1825,9 @@ On final failure (max retries exceeded):
 }
 ```
 
-### background_agent_start / background_agent_end / background_agent_event
+### background_agent_start / subagent_arbitration / background_agent_end / background_agent_event
 
-Lifecycle and live-observability events for background subagents (the `subagent` tool's background mode).
+Lifecycle, pre-spawn routing, and live-observability events for background subagents (the `subagent` tool's background mode).
 
 `background_agent_start` fires at launch. `sessionDir` is the directory the child will write its session JSONL into (per-launch, known before spawn):
 
@@ -1822,7 +1841,22 @@ Lifecycle and live-observability events for background subagents (the `subagent`
 }
 ```
 
-`background_agent_end` fires after the result is delivered to the parent agent. `sessionFile` is the child's session JSONL path when one was written:
+When the global Dispatch Arbiter is enabled, `subagent_arbitration` fires after the requested route is made concrete and before child spawn/events. It appears for changed and unchanged successful decisions, and for failures that prevent spawn. Chain records include `step`; failures have `final: null` and bounded host-generated `errorCode`/`errorMessage`.
+
+```json
+{
+  "type": "subagent_arbitration",
+  "agentId": "a1b2c3d4e5f6",
+  "status": "success",
+  "proposed": {"agent": "Explore", "model": "provider/frontier", "thinking": "high"},
+  "final": {"agent": "feature-dev", "model": "provider/worker", "thinking": "medium"},
+  "changed": ["agent", "model", "thinking"]
+}
+```
+
+The event is deliberately safe and programmatic: it never contains the task, guide, conversation context, prompt, raw response, or model reasoning. The parent session persists the same fields as a non-context `custom` entry. Consumers should update displayed background-agent identity from `final.agent` before child events arrive.
+
+`background_agent_end` fires after the result is delivered to the parent agent. For a single child it includes the canonical resolved `provider/model` and effective thinking level when reported; `sessionFile` is the child's session JSONL path when one was written:
 
 ```json
 {
@@ -1830,10 +1864,27 @@ Lifecycle and live-observability events for background subagents (the `subagent`
   "agentId": "a1b2c3d4e5f6",
   "agentType": "Explore",
   "success": true,
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "thinking": "medium",
   "sessionFile": "/home/user/.dreb/agent/subagent-sessions/a1b2c3d4e5f6/2026-07-07T12-00-00-000Z_uuid.jsonl"
 }
 ```
 
+Chain completions omit ambiguous scalar model/thinking fields and instead include ordered per-step metadata, since steps may use different agents, providers, models, or thinking levels:
+
+```json
+{
+  "type": "background_agent_end",
+  "agentId": "a1b2c3d4e5f6",
+  "agentType": "Explore",
+  "success": true,
+  "steps": [
+    {"step": 1, "agent": "Explore", "success": true, "model": "anthropic/claude-sonnet-4-6", "thinking": "low"},
+    {"step": 2, "agent": "feature-dev", "success": true, "model": "openai/gpt-5.6-sol", "thinking": "high"}
+  ]
+}
+```
+
 `background_agent_event` relays every JSONL event the child process emits (the same event union documented here, plus the initial session header), verbatim, tagged with the child's `agentId`. This is the live-transcript transport for observers like the dashboard — no session-file tailing needed. Streaming children emit `message_update` deltas at high frequency; consumers that fan events out further (e.g. over a network) should batch or throttle:
 
 ```json

package/docs/session.md

@@ -261,7 +261,13 @@ Extension state persistence. Does NOT participate in LLM context.
 {"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
 ```
 
-Use `customType` to identify your extension's entries on reload.
+Use `customType` to identify your extension's entries on reload. Core host features can use the same non-context channel. When the Dispatch Arbiter is enabled, every attempted pre-spawn decision is stored as `customType: "subagent_arbitration"` with only safe host-validated metadata:
+
+```json
+{"type":"custom","customType":"subagent_arbitration","data":{"type":"subagent_arbitration","agentId":"a1b2c3","status":"success","proposed":{"agent":"Explore","model":"provider/frontier","thinking":"high"},"final":{"agent":"feature-dev","model":"provider/worker","thinking":"medium"},"changed":["agent","model","thinking"]}}
+```
+
+Failure records have `final: null` plus bounded host-generated `errorCode`/`errorMessage`; chain records include `step`. Arbiter prompts, raw responses, and reasoning are never stored. Because this is `custom`, replay/build-context skips it and neither the parent nor child model receives the record.
 
 ### CustomMessageEntry
 

package/docs/settings.md

@@ -224,6 +224,38 @@ Set `parentTurnGuardrail` to `false` to let the parent keep running with no turn
 }
 ```
 
+### Dispatch Arbiter
+
+The optional Dispatch Arbiter is a fully headless, tool-less model call in the subagent control path. It is disabled by default and can be configured **only** in global `~/.dreb/agent/settings.json` (or the global RPC settings API). A project `.dreb/settings.json` cannot enable, disable, or reconfigure it.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `subagentArbiter.enabled` | boolean | `false` | Run fail-closed arbitration before every actual child spawn |
+| `subagentArbiter.model` | string | - | Required when enabled; exact canonical `provider/model` used for the direct arbiter call |
+| `subagentArbiter.thinking` | string | `off` | Optional arbiter-call thinking: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`; explicit values are capability-validated |
+| `subagentArbiter.guidePath` | string | `~/.dreb/agent/model-routing-guide.md` | Routing guide generated by `/skill:model-routing-guide`; `~` expands normally and relative paths resolve against the child cwd |
+
+```json
+{
+  "subagentArbiter": {
+    "enabled": true,
+    "model": "provider/router-model",
+    "thinking": "medium",
+    "guidePath": "~/.dreb/agent/model-routing-guide.md"
+  }
+}
+```
+
+First-class controls are available in both interactive `/settings` and the web dashboard Settings screen. Each exposes enable/disable, an authenticated exact-model picker, thinking level, and guide path. The TUI validates current live scope and guide coverage before accepting enablement; the dashboard prevents model-less enablement, validates model/thinking through RPC, shows readiness guidance, and the runtime still revalidates live scope/guide before every dispatch. Validation errors are loud and do not silently persist an unusable enabled policy.
+
+Enabling also requires a non-empty **live explicit session model scope** from `--models` or `enabledModels`, plus a schema-valid guide whose canonical covered IDs and `## Model:` sections exactly match that live scope. The research skill cannot discover runtime `--models`; generate its guide with matching explicit skill arguments when needed.
+
+For each single child, parallel item, and post-substitution chain step, the arbiter may return only an existing agent name, an exact model in the live scope, and a thinking level supported by that model. Missing/invalid settings, auth, guide, scope, timeout/provider errors, malformed output, unknown agents, out-of-scope models, and unsupported thinking all stop the affected spawn. There is no fallback to the proposed route or parent model after arbitration is enabled.
+
+The arbiter receives the immutable child task/cwd, proposed route, available agent names/descriptions/effective tools/model defaults, validated guide, canonical live candidates, bounded first/latest user intent and recent labeled parent activity—including bounded tool outputs—parent model/session title, repository/cwd/branch/dirty-count metadata, and lineage identifiers where available. Following the title setter's rolling-context pattern, ordinary file contents, diffs, command output, and other useful tool-result content are intentional routing context rather than a separate security boundary; the package receives the existing secret scrubbing before inference. The arbiter itself receives no tools. Guide files are capped at 128 KiB; the complete serialized package is capped at 180,000 characters. Individual intent/description/activity fields also have fixed bounds. Required task/guide/scope/agent data is never silently truncated—exceeding the package cap stops inference. The real child's task and cwd are not modified by scrubbing or arbitration.
+
+Only host-validated decision metadata is persisted/emitted. Raw arbiter prompts, responses, and reasoning never enter the parent transcript, child context, session history, JSON/RPC events, or dashboard. See [Agent Model Settings](agent-models.md#dispatch-arbiter).
+
 ### Message Delivery
 
 | Setting | Type | Default | Description |
@@ -385,7 +417,7 @@ See [packages.md](packages.md) for package management details.
 
 ## Project Overrides
 
-Project settings (`.dreb/settings.json`) override global settings. Nested objects are merged. **Exception:** `context.trustedFolders` and `context.autoLoadNested` are global-only security policy: project settings cannot add, replace, override, or enable either one. Nested context from the initial startup upward scan remains separate from this lazy-load policy.
+Project settings (`.dreb/settings.json`) override global settings. Nested objects are merged. **Exceptions:** `context.trustedFolders`, `context.autoLoadNested`, and the complete `subagentArbiter` policy are global-only security/control-path settings. Project settings cannot add, replace, override, enable, or disable them. Nested context from the initial startup upward scan remains separate from the lazy-load policy.
 
 ```json
 // ~/.dreb/agent/settings.json (global)

package/docs/skills.md

@@ -285,11 +285,49 @@ dreb ships with **mach6**, a development workflow that orchestrates the full iss
 | `mach6-review` | Explicitly user-triggered multi-agent review with scope-aware independent assessment |
 | `mach6-implement` | Implement plans, fix review findings, or fix CI failures |
 | `mach6-publish` | Pre-merge checks, docs update, merge, tag, release |
+| `model-routing-guide` | Research scoped models and sanitized local subagent evidence into a validated routing guide |
 
 Built-in skills are always available and can be overridden by placing a skill with the same name in any [user or project location](#locations). `mach6-review` is model-invocable when the user directly asks an agent to run it, as well as user-invocable through its slash command. Agents must never start formal review autonomously; implementation must first be committed and pushed.
 
 See [docs/mach6.md](mach6.md) for full documentation.
 
+### model-routing-guide
+
+`model-routing-guide` is an explicit, potentially expensive research workflow with exactly two supported scope sources.
+
+Pass comma-separated model patterns directly to make them authoritative:
+
+```text
+/skill:model-routing-guide anthropic/claude-*,openai/gpt-5.6-sol
+```
+
+Or invoke it without arguments to use the effective non-empty `enabledModels` array:
+
+```text
+/skill:model-routing-guide
+```
+
+When model scope rotates, update the existing guide incrementally instead of regenerating every retained entry:
+
+```text
+/skill:model-routing-guide update
+/skill:model-routing-guide update anthropic/claude-*,openai/gpt-5.6-sol
+```
+
+`update` must be the first argument. The skill validates the existing guide against its own coverage, diffs that coverage against the newly resolved authoritative scope, preserves retained model sections, removes unscoped sections and summary references, and researches only newly added canonical models. It refreshes scope/local-evidence metadata and performs the same complete final validation before atomically replacing the guide. A missing or malformed existing guide fails loudly and requires normal generation.
+
+Model-pattern arguments after the optional `update` keyword take precedence over `enabledModels`; the skill selects one source and does not search for any other runtime or session scope. Because this Stage 1 workflow is implemented only as a skill, it cannot discover the current session's `--models` value or later in-session scope changes. To research that runtime scope, pass the same comma-separated patterns as skill arguments.
+
+The skill refuses missing/empty and effectively all-model scopes. It obtains available candidates with `dreb --list-models`, resolves the selected patterns to canonical provider/model IDs, snapshots existing files under `~/.dreb/agent/subagent-sessions/`, and combines sanitized aggregate local observations with official documentation, model cards, benchmarks, issue trackers, forums, and practitioner reports. Existing unreadable or malformed child logs fail the run; a genuinely empty history is labeled cold-start.
+
+The generated `~/.dreb/agent/model-routing-guide.md` is human-readable Markdown with schema-versioned YAML frontmatter and one validated section per canonical candidate. Evidence is labeled as vendor claims, measured benchmarks, community reports, or local observations, with dates, confidence, sample counts, contrary findings, and explicit unknowns. The workflow prohibits copied prompts, outputs, tool arguments, secrets, paths, and identifying project details.
+
+Semantic local-evidence assessment uses normal dreb tools, so inspected session content is processed by the active research model's configured provider. The persisted guide is sanitized and generalized, but invoking the skill is still a decision to send the inspected evidence to that provider.
+
+Its primary routing safeguards are practical: `Explore` is for factual collection and navigation, not planning or implementation; routine lookup, extraction, repetitive file inspection, and straightforward summarization should use the least expensive scoped model demonstrated adequate by the evidence.
+
+The optional global-only [Dispatch Arbiter](agent-models.md#dispatch-arbiter) now consumes this file before every subagent spawn. Its live scope is the current session's exact explicit candidate set, so guide frontmatter and model headings must match that set exactly. A guide generated from `enabledModels` will work when the session uses the same resolved scope; for runtime `--models`, pass those patterns to the skill. Missing/stale/malformed guide coverage fails the child launch rather than bypassing arbitration.
+
 ## Skill Repositories
 
 - [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.45.4",
+	"version": "2.46.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {

package/skills/model-routing-guide/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: model-routing-guide
+description: Research model patterns passed as skill arguments, or enabledModels when no arguments are supplied, and generate or update an evidence-based subagent routing guide. This is a user-triggered, potentially expensive workflow.
+argument-hint: "[update] [comma-separated model patterns]"
+disable-model-invocation: true
+user-invocable: true
+---
+
+# model-routing-guide — Generate or Update the Subagent Routing Guide
+
+**Mode and explicit model patterns, when supplied:** $ARGUMENTS
+
+Generate, replace, or incrementally update `~/.dreb/agent/model-routing-guide.md`. This is a deep research workflow, not a quick opinion. Use normal dreb tools (`read`, `bash`, `find`, `grep`, `web_search`, `web_fetch`, and the Reddit reader when applicable); no special runtime support is required.
+
+The optional first argument `update` selects UPDATE mode. Remove that keyword before parsing model patterns. Without it, use GENERATE mode. The candidate scope still has exactly two supported sources: non-empty model-pattern arguments after the optional mode keyword, or the effective non-empty `enabledModels` setting when no model patterns were supplied. Once one source is selected, it is authoritative. Do not search for a separate runtime, session, or "scoped models" value.
+
+## Non-negotiable routing goals
+
+The guide must help a later dispatcher make two especially important corrections:
+
+1. **Agent-role fit:** `Explore` is for factual collection, codebase navigation, file discovery, web research, and answering bounded questions. Planning, architecture ownership, implementation, editing, and feature development are not Explore work. Explicitly call out examples such as a planning workflow delegating its plan to Explore, or a feature-development task being sent to Explore.
+2. **Capability/cost fit:** routine fact checks, repetitive inspection of many mundane files, lookup, extraction, and straightforward summarization should use the least expensive/lowest-latency selected candidate that the evidence shows is adequate. Reserve frontier or strongest-tier models for tasks whose complexity, ambiguity, risk, or demonstrated failure rate justifies them.
+
+Do not turn the guide into a generalized policy engine. Research the selected canonical provider/model candidates and give practical recommendations for the existing dreb agent roles.
+
+## Step 1: Select the mode and one authoritative scope source
+
+First parse the invocation mode:
+
+- If the first whitespace-delimited argument is exactly `update` (case-insensitive), select UPDATE mode and remove only that keyword from the argument text.
+- Otherwise select GENERATE mode and leave the argument text unchanged.
+- UPDATE is a mode keyword, never a model pattern. An `update` token anywhere except first position is ordinary pattern text and should fail normally if unresolved.
+
+There are exactly two supported scope sources. Apply these rules in order, choose one source, and then stop looking for scope:
+
+1. Read the model-pattern argument text remaining after optional mode parsing.
+   - If it is non-empty after trimming, split it as a comma-separated model-pattern list.
+   - That argument list is the complete authoritative scope. Do not read `enabledModels` and do not search session state for another scope.
+2. Only when the skill arguments are empty, read the effective `enabledModels` value from the normal settings files:
+   - Start with `enabledModels` from `~/.dreb/agent/settings.json`, when present.
+   - If `.dreb/settings.json` in the current working directory explicitly defines `enabledModels`, that project array replaces the global array; if it does not define the key, retain the global array.
+   - A non-empty effective `enabledModels` array is the complete authoritative scope. Stop looking for scope as soon as it is found.
+3. This skill-only workflow does **not** receive the current session's runtime `--models` value or later in-session scope changes. Never try to discover them from session logs, process state, the current model, or another file. If the user wants the runtime `--models` scope, they must pass the same comma-separated patterns as skill arguments.
+4. Do not infer scope from the current model, agent-definition defaults, all authenticated models, `agentModels.models`, or subagent session history.
+5. If neither source provides a non-empty pattern list, **stop with an actionable error before researching or writing a guide**. Tell the user to pass skill arguments or configure `enabledModels`.
+6. Run `dreb --list-models` to obtain the complete available-model listing. If the command fails or returns no usable listing, stop loudly.
+7. Resolve every selected pattern against that listing using the same normal model-pattern semantics as `--models`, including case-insensitive canonical/exact matching, fuzzy single-model matching, and globs. Preserve provider identity: the same upstream model through two providers is two candidates.
+8. Fail loudly and name every selected pattern that resolves to no available candidate.
+9. Compare the resolved candidate set with the complete `dreb --list-models` set. If they are equal, or the selected patterns otherwise amount to unbounded all-model research (for example a bare `*`), **refuse and ask the user for a narrower scope**.
+
+Keep the canonical candidate list. It is the coverage checklist for every later step. From this point onward, "selected candidates" means only that list; it never means an undiscovered runtime/session scope.
+
+## Step 2: In UPDATE mode, validate and diff the existing guide
+
+Skip this step in GENERATE mode.
+
+1. Require `~/.dreb/agent/model-routing-guide.md` to exist and be readable. If it is absent, stop before research or writes and tell the user to rerun without `update` for initial generation.
+2. Read the existing guide once. Parse its YAML frontmatter and model sections using the same contract described in Steps 5 and 6, but validate its internal coverage against its own `covered_model_ids`, not the newly selected scope. Require schema version 1, unique canonical covered IDs, exactly one complete model section per covered ID, the root heading, and routing safeguards. A stale but internally valid scope is expected; malformed content is not. Stop loudly rather than trying to salvage malformed Markdown.
+3. Diff the selected canonical candidates against existing `covered_model_ids` and report three deterministic canonical-ID lists:
+   - **retained** — present in both;
+   - **removed** — present only in the existing guide;
+   - **added** — present only in the selected scope.
+4. Preserve retained model sections and their sourced external findings instead of rebuilding them. Remove every removed model section and any removed-model row or claim in cross-model summaries. Fully research every added canonical provider/model in Step 4 and add exactly one complete section for it.
+5. Refresh the scope/methodology summary, routing table, frontmatter timestamp and coverage, and local-evidence metadata/aggregates for the current evidence snapshot. Do not silently relabel old external retrieval dates as current; update a source date only when that source was actually revisited. If new local or contrary evidence materially changes a retained model's recommendation, amend that section while keeping unaffected sourced material.
+6. If the diff is empty, still run the evidence snapshot and full validation. Preserve the existing guide unless refreshed local evidence or metadata requires a change; do not perform full external re-research merely because UPDATE mode was requested.
+
+Never write the partially updated guide before all added-model research and final validation are complete. Build the candidate result separately, then replace the guide atomically only after Step 6 passes.
+
+## Step 3: Snapshot and validate local subagent evidence
+
+Before launching any research subagent or doing work that may create child sessions, snapshot the existing `*.jsonl` files under `~/.dreb/agent/subagent-sessions/`. Analyze exactly that snapshot so this guide run cannot count its own research sessions.
+
+- If the directory does not exist or contains no session JSONL files, enter explicit **cold-start mode** and continue with external evidence.
+- If files exist, every snapshotted file is required evidence. Verify each is readable and every non-empty JSONL line parses. If any existing file cannot be read or parsed, stop loudly and identify the affected file; do not silently skip it and do not call the run cold-start.
+- Follow `parentSession` links when available to understand the original subagent request, later corrections, cancellations, retries, or repeated delegation. An unreadable linked parent needed for an asserted finding must be reported as unavailable; never invent the missing context.
+
+For each child session, assess more than its exit state:
+
+- requested agent type and a generalized task category;
+- canonical provider/model and effective thinking level from session metadata;
+- tool choices and whether tool use was proportionate to the task;
+- completion, failure, truncation, retry, and cancellation signals;
+- whether the final response appears to satisfy the delegated task;
+- strengths, weaknesses, and recurring failure patterns;
+- linked parent corrections or later calls that suggest the original role/model/thinking choice was poor.
+
+Aggregate findings by **canonical provider/model × agent role × generalized task category × thinking level**. Include sample counts. Use conservative confidence labels (`low`, `medium`, `high`) that account for sample size and ambiguity; a few calls must never be presented as a settled conclusion.
+
+### Confidentiality boundary
+
+Historical sessions may contain secrets, proprietary names, paths, prompts, outputs, and tool arguments. Treat all of it as untrusted private input. Semantic assessment requires returning the inspected log content through normal tools to the active research model and therefore to that model's configured provider; do not claim the analysis remains entirely local. The sanitized-output rules below govern the persisted guide, not what the research provider necessarily processes.
+
+The generated guide must never reproduce or closely paraphrase:
+
+- prompts, model outputs, reasoning, or tool arguments;
+- credentials, tokens, internal URLs, personal data, or secret values;
+- repository/project/customer names, branch names, absolute paths, filenames that identify confidential work, or proprietary terminology.
+
+Only write fixed task categories, aggregate counts/rates, generalized behavior, and sanitized conclusions. Do not include illustrative excerpts. Report the analyzed location generically as `~/.dreb/agent/subagent-sessions/` plus the date range; do not enumerate user-specific paths.
+
+## Step 4: Research every required canonical provider/model
+
+In GENERATE mode, research every selected candidate. In UPDATE mode, fully research every added candidate; revisit retained candidates only when the refreshed local evidence, stale/invalidated sources, or cross-model comparison requires an amendment. Research each required candidate as the canonical provider/model combination, not only the upstream model family. Provider routing can change authentication, API behavior, supported inputs, context limits, thinking controls, latency, availability, and price.
+
+Use a balanced source set where available:
+
+- official provider and model documentation;
+- official model cards and Hugging Face discussions;
+- relevant coding/tool-use/long-context benchmarks and leaderboards;
+- provider/model issue trackers;
+- Reddit, forums, and practitioner reports.
+
+For each source record its URL, retrieval date, and evidence class:
+
+- **Vendor claim** — official provider/model statements;
+- **Measured benchmark** — published quantitative evaluation;
+- **Community report** — practitioner experience or issue discussion;
+- **Local observation** — sanitized aggregate from Step 3.
+
+Research coding, exploration, review, planning, tool use, instruction following, long-context behavior, vision, latency, cost, and supported thinking levels. Record contrary evidence and unknowns. Do not fill a required field with a guess: write `Unknown` and lower confidence when reliable evidence is absent.
+
+Reconcile external and local evidence explicitly. If they disagree, preserve the disagreement and explain the likely limits (sample size, provider differences, workload mismatch, version drift) rather than choosing the more flattering result.
+
+## Step 5: Write the guide
+
+In GENERATE mode, write a complete new guide. In UPDATE mode, assemble the validated retained sections plus researched additions, remove stale scope references everywhere, and atomically replace the old file only after the complete candidate passes Step 6.
+
+Write `~/.dreb/agent/model-routing-guide.md` as human-readable Markdown with this stable YAML frontmatter shape:
+
+```yaml
+---
+schema_version: 1
+generated_at: "YYYY-MM-DDTHH:MM:SSZ"
+covered_model_ids:
+  - "provider/model-id"
+local_evidence: "available" # or "cold-start"
+analyzed_session_directories:
+  - "~/.dreb/agent/subagent-sessions/"
+session_date_range:
+  start: "YYYY-MM-DD" # null in cold-start mode
+  end: "YYYY-MM-DD"   # null in cold-start mode
+---
+```
+
+After frontmatter include:
+
+1. `# Model Routing Guide`
+2. A scope/methodology summary and explicit cold-start warning when applicable.
+3. `## Routing safeguards` containing the two non-negotiable routing goals above.
+4. A compact cross-model routing table for dreb's available agent roles and common task categories.
+5. Exactly one `## Model: provider/model-id` section for every canonical candidate, using these required subsections:
+   - `### Capabilities and thinking support`
+   - `### Strengths`
+   - `### Weaknesses and failure modes`
+   - `### Recommended roles and tasks`
+   - `### Discouraged roles and tasks`
+   - `### Tool use, long context, and vision`
+   - `### Latency and cost`
+   - `### Local evidence`
+   - `### External evidence and contrary findings`
+   - `### Confidence and limitations`
+   - `### Sources`
+
+Every factual external claim needs a dated URL and evidence-class label. Every local claim needs its aggregation dimensions, sample count, and confidence without identifying session content.
+
+## Step 6: Validate before reporting success
+
+Re-read the completed guide and perform a final validation. Do not merely eyeball it.
+
+1. Parse the YAML frontmatter and require `schema_version: 1`, a valid generation timestamp, valid local-evidence mode, and the documented session fields.
+2. Compare sets exactly:
+   - resolved canonical candidates;
+   - `covered_model_ids`;
+   - canonical IDs in `## Model:` headings.
+   They must be identical with no duplicates, missing entries, or extras.
+3. Check every model section contains every required subsection.
+4. Check each model records thinking support, strengths, weaknesses/failure modes, recommended and discouraged roles, latency/cost, confidence, contrary evidence, and dated sources; `Unknown` is valid, omission is not.
+5. Check local-evidence sections contain sample counts/confidence when history exists, or explicitly say cold-start when it does not.
+6. Scan for accidental copied prompts/outputs, secrets, absolute paths, project names, or other identifying session material and remove it.
+7. If any validation fails, fix the guide and rerun validation. If it still cannot pass, fail loudly and list the unmet checks instead of claiming generation succeeded.
+
+On success, report the guide path, canonical covered models, local-evidence mode/date range, and validation result. Do not paste the full guide into the conversation.