@dreb/coding-agent 2.45.3 → 2.46.0

package/docs/json.md

@@ -17,8 +17,12 @@ type AgentSessionEvent =
   | { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
   | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
   | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
-  | { type: "background_agent_start"; agentId: string; agentType: string; taskSummary: string }
-  | { type: "background_agent_end"; agentId: string; agentType: string; success: boolean }
+  | { type: "background_agent_start"; agentId: string; agentType: string; taskSummary: string; sessionDir?: string }
+  | { type: "subagent_arbitration"; agentId: string; status: "success" | "failure"; proposed: DispatchRoute; final: DispatchRoute | null; changed: ("agent" | "model" | "thinking")[]; step?: number; errorCode?: string; errorMessage?: string }
+  | { type: "background_agent_end"; agentId: string; agentType: string; success: boolean; model?: string; thinking?: ThinkingLevel; steps?: SubagentStepMetadata[]; sessionFile?: string }
+  | { type: "background_agent_event"; agentId: string; event: Record<string, unknown> }
+  | { type: "parent_paused_for_background_agents"; runningAgentCount: number; turnsUsed: number; turnLimit: number }
+  | { type: "session_name_changed"; name: string }
   | { type: "tasks_update"; tasks: readonly SessionTask[] }
   | { type: "suggest_next"; command: string };
 
@@ -28,6 +32,20 @@ interface SessionTask {
   title: string;
   status: "pending" | "in_progress" | "completed";
 }
+
+interface SubagentStepMetadata {
+  step: number;
+  agent: string;
+  success: boolean;
+  model?: string; // canonical provider/model
+  thinking?: ThinkingLevel;
+}
+
+interface DispatchRoute {
+  agent: string;
+  model: string; // canonical provider/model
+  thinking: ThinkingLevel;
+}
 ```
 
 Base events from [`AgentEvent`](https://github.com/aebrer/dreb/blob/master/packages/agent/src/types.ts):
@@ -35,7 +53,7 @@ Base events from [`AgentEvent`](https://github.com/aebrer/dreb/blob/master/packa
 ```typescript
 type AgentEvent =
   // Agent lifecycle
-  | { type: "agent_start"; model?: { provider: string; id: string } }
+  | { type: "agent_start"; model?: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }
   | { type: "agent_end"; messages: AgentMessage[] }
   // Turn lifecycle
   | { type: "turn_start" }
@@ -75,7 +93,7 @@ Each line is a JSON object. The first line is the session header (`version` is t
 Followed by events as they occur:
 
 ```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"}
 {"type":"turn_start"}
 {"type":"message_start","message":{"role":"assistant","content":[],...}}
 {"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
@@ -84,6 +102,14 @@ Followed by events as they occur:
 {"type":"agent_end","messages":[...]}
 ```
 
+With global Dispatch Arbiter enabled, each background start is followed before child events/spawn by one safe structured decision. Unchanged decisions use an empty `changed`; failed decisions use `final: null`, prevent spawn, and carry only host-generated errors. Chain decisions also include `step`.
+
+```json
+{"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"]}
+```
+
+The event never contains the arbiter prompt, response, reasoning, guide, task, or conversation excerpt. The matching parent session persists the same safe fields as a non-context custom JSONL entry.
+
 ## Error handling
 
 Errors surface as events, not as broken JSON or exit codes:
@@ -104,7 +130,7 @@ Events are emitted in a predictable sequence:
 
 `message_update` events stream as chunks arrive — expect many per message. `tool_execution_update` events are optional (only emitted for tools that report progress).
 
-Auto-compaction and auto-retry events can appear between turns.
+Auto-compaction and auto-retry events can appear between turns. Background lifecycle events are asynchronous: `background_agent_start` is emitted immediately, then an enabled `subagent_arbitration` record appears before that child's first `background_agent_event`; a failed arbitration is followed by `background_agent_end` without any child event.
 
 ## Example
 

package/docs/models.md

@@ -110,7 +110,7 @@ Set `api` at provider level (default for all models) or model level (override pe
 | `api` | API type (see above) |
 | `apiKey` | API key (see value resolution below) |
 | `headers` | Custom headers (see value resolution below) |
-| `authHeader` | Set `true` to add `Authorization: Bearer <apiKey>` automatically |
+| `authHeader` | Set `true` to use the resolved `apiKey` as `Authorization: Bearer` instead of provider API-key auth |
 | `models` | Array of model configurations |
 | `modelOverrides` | Per-model overrides for built-in models on this provider |
 
@@ -132,6 +132,44 @@ The `apiKey` and `headers` fields support three formats:
   "apiKey": "sk-..."
   ```
 
+### Bearer Auth for Anthropic-Compatible Providers
+
+Third-party Anthropic-compatible endpoints use `x-api-key` by default. If an endpoint instead requires `Authorization: Bearer <key>`, set `authHeader: true`:
+
+```json
+{
+  "providers": {
+    "company-anthropic": {
+      "baseUrl": "https://ai.example.com/anthropic",
+      "api": "anthropic-messages",
+      "apiKey": "COMPANY_ANTHROPIC_TOKEN",
+      "authHeader": true,
+      "models": [
+        { "id": "company-claude" }
+      ]
+    }
+  }
+}
+```
+
+For the built-in `anthropic-messages` implementation, this selects Bearer-only auth: dreb sends the request-time resolved credential as `Authorization` and does not also send `x-api-key`. The credential can use any [value resolution](#value-resolution) format; the environment variable does not need a special Anthropic SDK name.
+
+The flag also works when redirecting a built-in provider without redefining its models:
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "baseUrl": "https://ai.example.com/anthropic",
+      "apiKey": "COMPANY_ANTHROPIC_TOKEN",
+      "authHeader": true
+    }
+  }
+}
+```
+
+Leave `authHeader` unset or `false` for endpoints that expect `x-api-key`.
+
 ### Custom Headers
 
 ```json

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/examples/extensions/custom-provider-anthropic/index.ts

@@ -6,6 +6,7 @@
  * - Custom streamSimple implementation
  * - OAuth support for /login
  * - API key support via environment variable
+ * - Explicit SDK API-key versus Bearer auth selection
  * - Two model definitions
  *
  * Usage:
@@ -359,9 +360,11 @@ function streamCustomAnthropic(
 
 		try {
 			const apiKey = options?.apiKey ?? "";
-			const isOAuth = isOAuthToken(apiKey);
+			const configuredBearer = model.authMode === "bearer";
+			const isOAuth = !configuredBearer && isOAuthToken(apiKey);
 
-			// Configure client based on auth type
+			// Configure exactly one SDK auth channel. Explicitly nulling the other
+			// prevents the SDK from injecting ANTHROPIC_AUTH_TOKEN from the environment.
 			const betaFeatures = ["fine-grained-tool-streaming-2025-05-14", "interleaved-thinking-2025-05-14"];
 			const clientOptions: any = {
 				baseURL: model.baseUrl,
@@ -379,7 +382,8 @@ function streamCustomAnthropic(
 					"x-app": "cli",
 				};
 			} else {
-				clientOptions.apiKey = apiKey;
+				clientOptions.apiKey = configuredBearer ? null : apiKey;
+				clientOptions.authToken = configuredBearer ? apiKey : null;
 				clientOptions.defaultHeaders = {
 					accept: "application/json",
 					"anthropic-dangerous-direct-browser-access": "true",

package/package.json

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