@dreb/coding-agent 2.45.4 → 2.46.0

package/README.md

@@ -388,7 +388,7 @@ The `subagent` tool delegates tasks to independent child agent processes. Each s
 - **Parallel** (`tasks`): Up to 8 concurrent agents (max 4 at a time)
 - **Chain** (`chain`): Sequential pipeline where each step can reference the previous step's output via `{previous}`
 
-**Agent type inheritance:** The top-level `agent` parameter is inherited by parallel tasks and chain steps that don't specify their own. Precedence: per-task `agent` > top-level `agent` > default (`"Explore"`). The `model` parameter follows the same inheritance.
+**Agent type and override inheritance:** The top-level `agent` parameter is inherited by parallel tasks and chain steps that don't specify their own. Precedence: per-task `agent` > top-level `agent` > default (`"Explore"`). The `model` and optional `thinking` parameters follow the same per-task-over-top-level inheritance. Explicit thinking accepts `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`; unsupported levels for the resolved model fail before spawn. Omit `thinking` to preserve the child's normal settings/default behavior.
 
 **Agent definitions** live in `~/.dreb/agents/` (global) and `.dreb/agents/` (project). Each is a markdown file with YAML frontmatter specifying `name`, `model` (with provider fallback list), and optional `systemPrompt`. Built-in agents include `Explore` (read-only codebase exploration), `Sandbox` (restricted to `/tmp`), `feature-dev` (strong-tier coding), and several review agents.
 
@@ -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 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.
+**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,6 +464,8 @@ 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. 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
 
 <p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>

package/dist/core/agent-session.d.ts

@@ -16,6 +16,7 @@ import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLe
 import type { ImageContent, Model, TextContent } from "@dreb/ai";
 import { type BashResult } from "./bash-executor.js";
 import { type CompactionResult } from "./compaction/index.js";
+import { type DispatchArbiterDeps } from "./dispatch-arbiter.js";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, ExtensionRunner, type ExtensionUIContext, type InputSource, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.js";
 import type { CustomMessage } from "./messages.js";
 import type { ModelRegistry } from "./model-registry.js";
@@ -25,7 +26,7 @@ import type { ResourceLoader } from "./resource-loader.js";
 import type { BranchSummaryEntry, SessionManager } from "./session-manager.js";
 import { type SettingsManager } from "./settings-manager.js";
 import type { BashOperations } from "./tools/bash.js";
-import { type SessionTask, type SubagentResult } from "./tools/index.js";
+import { type SessionTask, type SubagentArbitrationEvent, type SubagentResult, type SubagentStepMetadata } from "./tools/index.js";
 /** Parsed skill block from a user message */
 export interface ParsedSkillBlock {
     name: string;
@@ -39,7 +40,7 @@ export interface ParsedSkillBlock {
  */
 export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
 /** Session-specific events that extend the core AgentEvent */
-export type AgentSessionEvent = AgentEvent | {
+export type AgentSessionEvent = AgentEvent | SubagentArbitrationEvent | {
     type: "auto_compaction_start";
     reason: "threshold" | "overflow";
 } | {
@@ -70,6 +71,9 @@ export type AgentSessionEvent = AgentEvent | {
     agentId: string;
     agentType: string;
     success: boolean;
+    model?: string;
+    thinking?: ThinkingLevel;
+    steps?: SubagentStepMetadata[];
     sessionFile?: string;
 } | {
     type: "background_agent_event";
@@ -126,6 +130,8 @@ export interface AgentSessionConfig {
     uiType?: string;
     /** Optional performance tracker override, primarily for isolated tests. */
     performanceTracker?: PerformanceTracker;
+    /** Inject the headless arbiter completion seam for deterministic, offline integration tests. */
+    dispatchArbiterComplete?: DispatchArbiterDeps["complete"];
 }
 export interface ExtensionBindings {
     uiContext?: ExtensionUIContext;
@@ -234,11 +240,13 @@ export declare class AgentSession {
     private performanceTracker;
     private _ownsPerformanceTracker;
     private _gitRepoState;
+    private _dispatchArbiter;
     constructor(config: AgentSessionConfig);
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
     /** Performance tracker for recording and querying model throughput */
     getPerformanceTracker(): PerformanceTracker;
+    private _compileExtraSecretPatterns;
     /**
      * Install tool hooks once on the Agent instance.
      *