@dreb/coding-agent 2.45.4 → 2.47.0

package/dist/core/tools/subagent.js

@@ -11,11 +11,12 @@ import { keyHint } from "../../modes/interactive/components/keybinding-hints.js"
 import { attachJsonlLineReader } from "../../modes/rpc/jsonl.js";
 import { log } from "../logger.js";
 import { resolveCliModel } from "../model-resolver.js";
-import { resolveEffectiveThinkingLevel, thinkingLevelToReasoning } from "../thinking.js";
+import { resolveEffectiveThinkingLevel, thinkingLevelToReasoning, validateThinkingLevelForModel } from "../thinking.js";
 import { getTextOutput, invalidArgText, str } from "./render-utils.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
 import { DEFAULT_MAX_BYTES, formatSize } from "./truncate.js";
 const DEFAULT_AGENT = "Explore";
+const SUBAGENT_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 export const DEFAULT_MODEL_AVAILABILITY_PROBE_TIMEOUT_MS = 120_000;
 export function parseAgentFrontmatter(content) {
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
@@ -123,6 +124,7 @@ const SUBAGENT_EXCLUDED_TOOLS = ["wait", "subagent", "suggest_next"];
 // the child process adds them unconditionally regardless of --tools.
 // Internal tools (tmp_read) are also excluded.
 const SUBAGENT_DEFAULT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls", "web_search", "web_fetch"];
+const SUBAGENT_ALWAYS_ACTIVE_TOOLS = ["search", "skill", "tasks_update"];
 /**
  * Filter a comma-separated tools string, removing any tools in SUBAGENT_EXCLUDED_TOOLS.
  * Returns the filtered tools as a comma-separated string (always non-empty — falls
@@ -138,11 +140,38 @@ export function filterSubagentTools(tools) {
         .join(",");
     return filtered || SUBAGENT_DEFAULT_TOOLS.join(",");
 }
+function summarizeAgentsForArbitration(agents, getAgentModelsForAgent) {
+    return [...agents.values()].map((agent) => {
+        const settingsModels = getAgentModelsForAgent?.(agent.name);
+        return {
+            name: agent.name,
+            description: agent.description,
+            tools: [
+                ...new Set([
+                    ...filterSubagentTools(agent.tools).split(",").filter(Boolean),
+                    ...SUBAGENT_ALWAYS_ACTIVE_TOOLS,
+                ]),
+            ],
+            modelDefaults: settingsModels && settingsModels.length > 0
+                ? [...settingsModels]
+                : agent.model
+                    ? Array.isArray(agent.model)
+                        ? [...agent.model]
+                        : [agent.model]
+                    : [],
+        };
+    });
+}
 // TODO: Support PATH-based binary discovery.
 // Currently returns the captured argv[1].
 function findDrebBinary() {
     return DREB_SCRIPT;
 }
+function canonicalModelRef(provider, modelId) {
+    if (!provider || modelId.startsWith(`${provider}/`))
+        return modelId;
+    return `${provider}/${modelId}`;
+}
 /**
  * Handle one line of a subagent child's JSONL stdout. Parses the line and
  * dispatches to the sinks: full-event relay, assistant-message collection,
@@ -175,8 +204,15 @@ export function handleChildJsonlLine(line, sinks) {
     if (typeof event.type === "string") {
         sinks.onEvent?.(event);
     }
-    if (event.type === "agent_start" && event.model) {
-        sinks.onModel(event.model.id);
+    if (event.type === "agent_start") {
+        if (typeof event.model?.id === "string") {
+            const provider = typeof event.model.provider === "string" ? event.model.provider : undefined;
+            sinks.onModel(canonicalModelRef(provider, event.model.id));
+        }
+        if (typeof event.thinkingLevel === "string" &&
+            SUBAGENT_THINKING_LEVELS.includes(event.thinkingLevel)) {
+            sinks.onThinking?.(event.thinkingLevel);
+        }
     }
     if (event.type === "message_end" && event.message?.role === "assistant") {
         sinks.onAssistantMessage(event.message);
@@ -189,7 +225,7 @@ export function handleChildJsonlLine(line, sinks) {
         sinks.onProgress(`${sinks.toolNameRef.current} done`);
     }
 }
-async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent) {
+async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent, thinkingOverride) {
     const drebBin = findDrebBinary();
     log.debug(`[subagent] spawn: agent=${agentConfig.name} cwd=${cwd}`);
     // Validate cwd exists — spawn() throws a misleading ENOENT blaming the
@@ -216,13 +252,16 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
     const modelStr = Array.isArray(agentConfig.model) ? agentConfig.model[0] : agentConfig.model;
     if (modelStr) {
         args.push("--model", modelStr);
-        // When the model string doesn't already specify a provider (no "/"),
-        // inherit the parent's provider to prevent fuzzy matching from picking
-        // an unauthenticated provider (e.g. Bedrock instead of Anthropic).
-        if (parentProvider && !modelStr.includes("/")) {
+        // executeSingle resolves the model and provider independently. Always pass
+        // that exact provider because raw model IDs may themselves contain slashes
+        // (for example, OpenRouter IDs such as "openai/gpt-oss-120b").
+        if (parentProvider) {
             args.push("--provider", parentProvider);
         }
     }
+    if (thinkingOverride) {
+        args.push("--thinking", thinkingOverride);
+    }
     // Always pass --tools to ensure wait/subagent/suggest_next are excluded from child processes.
     // filterSubagentTools always returns a non-empty string.
     args.push("--tools", filterSubagentTools(agentConfig.tools));
@@ -272,6 +311,7 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         const plainStdoutLines = [];
         const toolNameRef = { current: "" };
         let resolvedModel;
+        let resolvedThinking;
         // Drain stderr concurrently to avoid pipe deadlock (capped to prevent OOM from verbose subagents)
         proc.stderr?.on("data", (chunk) => {
             if (stderrSize < MAX_STDERR_BYTES) {
@@ -293,8 +333,11 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                     onEvent: onChildEvent,
                     onAssistantMessage: (message) => collectedMessages.push(message),
                     onProgress,
-                    onModel: (modelId) => {
-                        resolvedModel = modelId;
+                    onModel: (modelRef) => {
+                        resolvedModel = modelRef;
+                    },
+                    onThinking: (thinkingLevel) => {
+                        resolvedThinking = thinkingLevel;
                     },
                     onPlainLine: (plain) => plainStdoutLines.push(plain),
                     toolNameRef,
@@ -390,15 +433,13 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
             }
             // Discover the session file written by the child process
             const sessionFile = sessionDir ? discoverSessionFile(sessionDir, agentConfig.name) : undefined;
+            const configuredModel = Array.isArray(agentConfig.model) ? agentConfig.model[0] : agentConfig.model;
             resolvePromise({
                 agent: agentConfig.name,
                 task,
                 model: resolvedModel ??
-                    (exitCode === 0
-                        ? Array.isArray(agentConfig.model)
-                            ? agentConfig.model[0]
-                            : agentConfig.model
-                        : undefined),
+                    (exitCode === 0 && configuredModel ? canonicalModelRef(parentProvider, configuredModel) : undefined),
+                thinking: resolvedThinking ?? (exitCode === 0 ? thinkingOverride : undefined),
                 exitCode,
                 output,
                 stderr: stderr.slice(0, 2000), // cap stderr
@@ -747,14 +788,17 @@ logPrefix = "[subagent]") {
         ].join(", ")}. Last error: ${lastError || "all probes failed"}`,
     };
 }
-export function formatModelFallbackSummary(skippedModels, selectedModel) {
+export function formatModelFallbackSummary(skippedModels, proposalModel, finalModel) {
     if (skippedModels.length === 0)
         return undefined;
     const skipped = skippedModels.map((s) => `- ${s.model}: ${s.reason}`).join("\n");
-    return `[MODEL FALLBACK: skipped ${skippedModels.length} unavailable model(s); using "${selectedModel ?? "unknown"}".]\n${skipped}`;
+    const routeSummary = finalModel && finalModel !== proposalModel
+        ? `proposal resolved to "${proposalModel ?? "unknown"}" before arbitration selected "${finalModel}".`
+        : `using "${finalModel ?? proposalModel ?? "unknown"}".`;
+    return `[MODEL FALLBACK: skipped ${skippedModels.length} unavailable model(s); ${routeSummary}]\n${skipped}`;
 }
-export function prependModelFallbackSummary(output, skippedModels, selectedModel) {
-    const fallbackSummary = formatModelFallbackSummary(skippedModels, selectedModel);
+export function prependModelFallbackSummary(output, skippedModels, proposalModel, finalModel) {
+    const fallbackSummary = formatModelFallbackSummary(skippedModels, proposalModel, finalModel);
     return fallbackSummary ? `${fallbackSummary}\n\n${output}` : output;
 }
 function formatSkippedModelFailureDetails(skippedModels) {
@@ -765,6 +809,10 @@ function formatSkippedModelFailureDetails(skippedModels) {
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const MAX_TASK_LENGTH = 32_768; // 32 KB — prevent E2BIG from oversized argv
+/** Resolve per-task thinking precedence for parallel and chain modes. */
+export function resolveSubagentThinkingOverride(taskThinking, topLevelThinking) {
+    return taskThinking ?? topLevelThinking;
+}
 // Semaphore for background task concurrency — shared across all background launches
 let bgRunning = 0;
 const bgWaiters = [];
@@ -804,9 +852,9 @@ function clampCwd(defaultCwd, itemCwd) {
     }
     return { ok: true, cwd: resolved };
 }
-export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile, onChildEvent) {
-    const name = agentName || DEFAULT_AGENT;
-    const config = agents.get(name);
+export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile, onChildEvent, thinkingOverride, arbitration) {
+    let name = agentName || DEFAULT_AGENT;
+    let config = agents.get(name);
     if (!config) {
         return {
             agent: name,
@@ -817,7 +865,6 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
             errorMessage: `Unknown agent type "${name}". Available: ${[...agents.keys()].join(", ")}. If you expected "${name}" to exist, check the .md file in ~/.dreb/agents/ or .dreb/agents/ for syntax errors.`,
         };
     }
-    // Validate task length for all modes (single, parallel items, chain steps)
     if (task.length > MAX_TASK_LENGTH) {
         return {
             agent: name,
@@ -828,21 +875,18 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
             errorMessage: `Task prompt too long (${task.length} chars, max ${MAX_TASK_LENGTH}). Shorten the prompt.`,
         };
     }
-    // Per-invocation model override takes precedence over agent settings, which take precedence over agent definition model.
-    // Override is always a single string; agentModels and agent config may be arrays.
-    const modelSpec = modelOverride || (agentModels && agentModels.length > 0 ? agentModels : undefined) || config.model;
+    // Phase 1: resolve the parent's proposal with the existing precedence and
+    // fallback behavior so the arbiter receives one concrete canonical route.
+    const configuredModelSpec = modelOverride || (agentModels && agentModels.length > 0 ? agentModels : undefined) || config.model;
+    const modelSpec = configuredModelSpec || parentModel;
     let effectiveConfig = modelOverride ? { ...config, model: modelOverride } : config;
     let resolvedProvider = parentProvider;
+    let resolvedModel;
     let warning;
     let skippedModels = [];
-    // Resolve and validate the model against the registry before spawning.
-    // This catches typos and invalid model names immediately instead of failing
-    // silently in the child process. Also passes the canonical model ID to the
-    // child, avoiding fuzzy matching entirely. Agent definition fallback lists get
-    // an additional best-effort 1-token probe before spawn so runtime-unavailable
-    // models are skipped before committing to a child process.
     if (modelSpec) {
-        const resolved = await resolveModelForSubagentSpawn(modelSpec, parentProvider, registry, parentModel, signal);
+        const parentFallback = configuredModelSpec ? parentModel : undefined;
+        const resolved = await resolveModelForSubagentSpawn(modelSpec, parentProvider, registry, parentFallback, signal);
         skippedModels = resolved.skippedModels;
         if (!resolved.ok) {
             const skippedDetails = formatSkippedModelFailureDetails(skippedModels);
@@ -856,21 +900,201 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
             };
         }
         effectiveConfig = { ...effectiveConfig, model: resolved.modelId };
-        if (resolved.provider) {
+        if (resolved.provider)
             resolvedProvider = resolved.provider;
-        }
+        if (registry && resolvedProvider)
+            resolvedModel = registry.find(resolvedProvider, resolved.modelId);
         warning = resolved.warning;
     }
+    if (thinkingOverride && thinkingOverride !== "off" && !modelSpec) {
+        return {
+            agent: name,
+            task,
+            exitCode: 1,
+            output: "",
+            stderr: "",
+            errorMessage: `Cannot validate thinking level "${thinkingOverride}" because agent "${name}" has no configured model and no parent model is available. Set a model on the agent or pass a per-call model override.`,
+        };
+    }
+    const proposalModelId = Array.isArray(effectiveConfig.model) ? effectiveConfig.model[0] : effectiveConfig.model;
+    const proposalSelectedModel = proposalModelId ? canonicalModelRef(resolvedProvider, proposalModelId) : undefined;
+    let finalThinking = thinkingOverride;
+    let arbitrationEnabled = false;
+    if (arbitration) {
+        const proposed = {
+            agent: name,
+            model: proposalSelectedModel ?? "",
+            thinking: resolveEffectiveThinkingLevel(resolvedModel, thinkingOverride, arbitration.defaultThinkingLevel),
+        };
+        let arbitrationResult;
+        try {
+            arbitrationResult = await arbitration.arbitrate({
+                task,
+                cwd,
+                proposed,
+                agents: summarizeAgentsForArbitration(agents, arbitration.getAgentModelsForAgent),
+                parentSessionFile,
+                step: arbitration.step,
+            }, signal);
+        }
+        catch {
+            const errorMessage = "Dispatch arbiter failed internally before child spawn.";
+            try {
+                arbitration.onRecord({
+                    status: "failure",
+                    proposed,
+                    final: null,
+                    changed: [],
+                    step: arbitration.step,
+                    errorCode: "internal_error",
+                    errorMessage,
+                });
+            }
+            catch { }
+            return {
+                agent: name,
+                task,
+                exitCode: 1,
+                output: "",
+                stderr: "",
+                errorMessage,
+            };
+        }
+        if (arbitrationResult.enabled) {
+            arbitrationEnabled = true;
+            if (!arbitrationResult.ok) {
+                const record = {
+                    status: "failure",
+                    proposed,
+                    final: null,
+                    changed: [],
+                    step: arbitration.step,
+                    errorCode: arbitrationResult.code,
+                    errorMessage: arbitrationResult.error,
+                };
+                try {
+                    arbitration.onRecord(record);
+                }
+                catch {
+                    // The original failure still prevents spawn; do not replace it with an observer error.
+                }
+                return {
+                    agent: name,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "",
+                    errorMessage: `Dispatch arbitration failed: ${arbitrationResult.error}`,
+                };
+            }
+            const decision = arbitrationResult.decision;
+            const selectedConfig = agents.get(decision.agent);
+            const slash = decision.model.indexOf("/");
+            const selectedProvider = slash > 0 ? decision.model.slice(0, slash) : "";
+            const selectedModelId = slash > 0 ? decision.model.slice(slash + 1) : "";
+            const selectedModel = registry?.find(selectedProvider, selectedModelId);
+            if (!selectedConfig || !selectedModel) {
+                const errorMessage = !selectedConfig
+                    ? "Arbiter selected an unknown agent."
+                    : "Arbiter selected an unavailable model.";
+                const record = {
+                    status: "failure",
+                    proposed,
+                    final: null,
+                    changed: [],
+                    step: arbitration.step,
+                    errorCode: !selectedConfig ? "unknown_agent" : "out_of_scope_model",
+                    errorMessage,
+                };
+                try {
+                    arbitration.onRecord(record);
+                }
+                catch { }
+                return {
+                    agent: name,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "",
+                    errorMessage: `Dispatch arbitration failed: ${errorMessage}`,
+                };
+            }
+            const finalThinkingValidation = validateThinkingLevelForModel(selectedModel, decision.thinking);
+            if (!finalThinkingValidation.ok) {
+                const record = {
+                    status: "failure",
+                    proposed,
+                    final: null,
+                    changed: [],
+                    step: arbitration.step,
+                    errorCode: "unsupported_thinking",
+                    errorMessage: finalThinkingValidation.error,
+                };
+                try {
+                    arbitration.onRecord(record);
+                }
+                catch { }
+                return {
+                    agent: name,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "",
+                    errorMessage: `Dispatch arbitration failed: ${finalThinkingValidation.error}`,
+                };
+            }
+            name = decision.agent;
+            config = selectedConfig;
+            effectiveConfig = { ...config, model: selectedModel.id };
+            resolvedProvider = selectedModel.provider;
+            resolvedModel = selectedModel;
+            finalThinking = decision.thinking;
+            try {
+                arbitration.onRecord({
+                    status: "success",
+                    proposed,
+                    final: decision,
+                    changed: arbitrationResult.changed,
+                    step: arbitration.step,
+                });
+            }
+            catch (error) {
+                return {
+                    agent: name,
+                    task,
+                    exitCode: 1,
+                    output: "",
+                    stderr: "",
+                    errorMessage: `Dispatch arbitration observability failed before spawn: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+    }
+    if (finalThinking) {
+        const validation = validateThinkingLevelForModel(resolvedModel, finalThinking);
+        if (!validation.ok) {
+            return {
+                agent: name,
+                task,
+                exitCode: 1,
+                output: "",
+                stderr: "",
+                errorMessage: validation.error,
+            };
+        }
+    }
     const usedModel = effectiveConfig.model?.toString();
     onProgress?.(`Running ${name} agent${usedModel ? ` (${usedModel})` : ""}...`);
-    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent);
-    result.output = prependModelFallbackSummary(result.output, skippedModels, result.model ?? usedModel);
+    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent, finalThinking);
+    const finalSelectedModel = result.model ?? (usedModel ? canonicalModelRef(resolvedProvider, usedModel) : undefined);
+    result.output = prependModelFallbackSummary(result.output, skippedModels, arbitrationEnabled ? proposalSelectedModel : finalSelectedModel, arbitrationEnabled ? finalSelectedModel : undefined);
     if (warning) {
-        result.output = `[WARNING: ${warning}]\n\n${result.output}`;
+        const warningContext = arbitrationEnabled ? `Proposal resolution: ${warning}` : warning;
+        result.output = `[WARNING: ${warningContext}]\n\n${result.output}`;
     }
     return result;
 }
-async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent) {
+async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, defaultThinking, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent, arbitration) {
     const results = [];
     let previousOutput = "";
     for (let i = 0; i < chain.length; i++) {
@@ -907,7 +1131,7 @@ async function executeChain(agents, chain, defaultCwd, signal, onProgress, paren
         const stepSessionDir = sessionBaseDir ? join(sessionBaseDir, `step-${i + 1}`) : undefined;
         const stepAgentName = step.agent || defaultAgent || DEFAULT_AGENT;
         const stepMach6Models = getAgentModelsForAgentFn?.(stepAgentName);
-        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile, onChildEvent);
+        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile, onChildEvent, resolveSubagentThinkingOverride(step.thinking, defaultThinking), arbitration ? { ...arbitration, step: i + 1 } : undefined);
         results.push(result);
         if (result.exitCode !== 0) {
             break; // stop chain on error
@@ -1201,13 +1425,19 @@ export function rehydrateBackgroundAgentsFromDisk(parentSessionFile, subagentSes
     }
     return registered;
 }
+function cloneBackgroundAgentInfo(info) {
+    return {
+        ...info,
+        arbitrations: info.arbitrations?.map((record) => structuredClone(record)),
+    };
+}
 /** Get a snapshot of all tracked background agents (running and recently completed). Returns readonly clones. */
 export function getBackgroundAgents() {
-    return [...backgroundAgentRegistry.values()].map((a) => ({ ...a }));
+    return [...backgroundAgentRegistry.values()].map(cloneBackgroundAgentInfo);
 }
 /** Get only currently running background agents. Returns readonly clones. */
 export function getRunningBackgroundAgents() {
-    return [...backgroundAgentRegistry.values()].filter((a) => a.status === "running").map((a) => ({ ...a }));
+    return [...backgroundAgentRegistry.values()].filter((a) => a.status === "running").map(cloneBackgroundAgentInfo);
 }
 /** Abort all running background agents. */
 export function abortBackgroundAgents() {
@@ -1233,6 +1463,14 @@ export function pruneBackgroundAgents(maxAgeMs = 5 * 60 * 1000) {
 // ---------------------------------------------------------------------------
 // Tool schema and definition
 // ---------------------------------------------------------------------------
+const thinkingLevelSchema = Type.Union([
+    Type.Literal("off"),
+    Type.Literal("minimal"),
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+    Type.Literal("xhigh"),
+], { description: "Thinking level override for the child model." });
 const taskItemSchema = Type.Object({
     agent: Type.Optional(Type.String({ description: "Agent type name (default: 'Explore')" })),
     task: Type.String({ description: "The task prompt for this subagent" }),
@@ -1242,6 +1480,7 @@ const taskItemSchema = Type.Object({
     model: Type.Optional(Type.String({
         description: "Model override for this task. Takes precedence over agent definition model. Note: a single-string override discards the agent's fallback list.",
     })),
+    thinking: Type.Optional(thinkingLevelSchema),
 });
 const subagentSchema = Type.Object({
     agent: Type.Optional(Type.String({ description: "Agent type name (default: 'Explore')" })),
@@ -1249,6 +1488,16 @@ const subagentSchema = Type.Object({
     model: Type.Optional(Type.String({
         description: "Model override. Takes precedence over agent definition model. Note: a single-string override discards the agent's fallback list. For parallel/chain, set per-task instead.",
     })),
+    thinking: Type.Optional(Type.Union([
+        Type.Literal("off"),
+        Type.Literal("minimal"),
+        Type.Literal("low"),
+        Type.Literal("medium"),
+        Type.Literal("high"),
+        Type.Literal("xhigh"),
+    ], {
+        description: "Thinking level override. Per-task values take precedence in parallel and chain modes. Omit to preserve child defaults.",
+    })),
     tasks: Type.Optional(Type.Array(taskItemSchema, {
         description: "Array of tasks to run in parallel (max 8)",
         minItems: 1,
@@ -1322,7 +1571,13 @@ function formatSubagentResult(result, options, theme, showImages) {
     return text;
 }
 export function formatSingleResult(result) {
-    let text = `## Agent: ${result.agent}${result.model ? ` (model: ${result.model})` : ""}\n`;
+    const metadata = [
+        result.model ? `model: ${result.model}` : undefined,
+        result.thinking ? `thinking: ${result.thinking}` : undefined,
+    ]
+        .filter((value) => value !== undefined)
+        .join(", ");
+    let text = `## Agent: ${result.agent}${metadata ? ` (${metadata})` : ""}\n`;
     if (result.exitCode !== 0) {
         text += `**Error** (exit ${result.exitCode}): ${result.errorMessage || "Unknown error"}\n`;
         if (result.stderr) {
@@ -1353,6 +1608,9 @@ export function createSubagentToolDefinition(cwd, options) {
     const getParentSessionFile = options?.parentSessionFile ?? (() => undefined);
     const modelRegistry = options?.modelRegistry;
     const getAgentModelsForAgent = options?.getAgentModelsForAgent;
+    const arbitrate = options?.arbitrate;
+    const onArbitration = options?.onArbitration;
+    const getDefaultThinkingLevel = options?.defaultThinkingLevel;
     // Discover agents at definition time to build the prompt guidelines.
     // This is cheap (reads .md files) and the same call happens on every execute().
     const knownAgents = discoverAgentTypes(cwd);
@@ -1382,6 +1640,7 @@ export function createSubagentToolDefinition(cwd, options) {
             "Each agent notifies independently when done — completion messages include a list of any still-running agents. If you need their results before proceeding, end your current turn with no tool calls (as if you were asking the user a question and waiting for their reply). This emits `agent_end` and lets the framework deliver the completion as a new message that resumes your turn automatically. Do not call `sleep` or any other waiting action, and do not launch filler work.",
             "Agent definitions specify a `model` field with a provider fallback list (comma-separated or YAML list). The spawner tries each in order and uses the first one that resolves for the current provider. This makes agents portable across providers.",
             "Per-invocation `model` overrides take precedence but **discard the entire fallback list** — if the single override model isn't available on the current provider, the agent fails. Only override when you have a specific reason (e.g. escalating to a stronger tier for a complex task).",
+            "Optional `thinking` overrides accept off/minimal/low/medium/high/xhigh. Per-task values override a top-level value; unsupported levels fail before spawn. Omit thinking to preserve the child's configured default.",
             "**Model routing** — agent definitions already specify the right tier for their role. Most subagent tasks (exploration, file discovery, grep, navigation, summarization) are handled well by the defaults. Do not override the model unless the task genuinely requires a different capability tier than what the agent definition provides.",
             "**Model identity** — Your current model is stated in the system prompt as `You are running on: provider/id`. Use this for explicit routing decisions — e.g. delegate vision tasks if you're on a text-only model, or use a differently-architected model as a critic for tasks where diverse model perspectives improve reliability.",
         ],
@@ -1426,9 +1685,9 @@ export function createSubagentToolDefinition(cwd, options) {
                  * Shared lifecycle for all background launches: generates agent ID,
                  * sets up registry/abort/notification, gates on the concurrency
                  * semaphore, and handles errors. The caller provides the actual
-                 * work via `runFn(signal, onChildEvent)` which must return a
-                 * SubagentResult; `onChildEvent` (when defined) must be forwarded to
-                 * the spawn so the child's JSONL events reach the relay.
+                 * work via `runFn(signal, onChildEvent, onArbitrationRecord)` which must
+                 * return a SubagentResult. Child events are relayed live; arbitration
+                 * records update the registry before being persisted/emitted.
                  */
                 const launchBackgroundLifecycle = (agentName, taskSummary, sessionDir, agentCwd, runFn) => {
                     const agentId = generateAgentId();
@@ -1456,6 +1715,16 @@ export function createSubagentToolDefinition(cwd, options) {
                             }
                         }
                         : undefined;
+                    const onArbitrationRecord = (record) => {
+                        const entry = backgroundAgentRegistry.get(agentId);
+                        if (entry) {
+                            entry.arbitrations ??= [];
+                            entry.arbitrations.push(record);
+                            if (record.status === "success" && record.final)
+                                entry.agentType = record.final.agent;
+                        }
+                        onArbitration?.({ type: "subagent_arbitration", agentId, ...record });
+                    };
                     const bgSignal = bgAbort.signal;
                     const safeNotify = (result) => {
                         try {
@@ -1468,7 +1737,7 @@ export function createSubagentToolDefinition(cwd, options) {
                     const run = async () => {
                         await bgAcquire();
                         try {
-                            const result = await runFn(bgSignal, onChildEvent);
+                            const result = await runFn(bgSignal, onChildEvent, onArbitrationRecord);
                             const entry = backgroundAgentRegistry.get(agentId);
                             if (entry && !bgSignal.aborted)
                                 entry.status = result.exitCode === 0 ? "completed" : "failed";
@@ -1519,18 +1788,25 @@ export function createSubagentToolDefinition(cwd, options) {
                 };
                 // Helper to launch a single background task
                 const subagentSessionsBase = getSubagentSessionsDir();
-                const launchBackgroundTask = (agentName, task, taskLabel, taskCwd, modelOverride) => {
+                const launchBackgroundTask = (agentName, task, taskLabel, taskCwd, modelOverride, thinkingOverride) => {
                     const resolvedCwd = taskCwd ?? cwd;
                     // Each background agent gets its own session subdirectory
                     const sessionId = generateAgentId();
                     const sessionDir = join(subagentSessionsBase, sessionId);
                     const agentModels = getAgentModelsForAgent?.(agentName || DEFAULT_AGENT);
-                    return launchBackgroundLifecycle(agentName, taskLabel, sessionDir, resolvedCwd, (signal, onChildEvent) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile(), onChildEvent));
+                    return launchBackgroundLifecycle(agentName, taskLabel, sessionDir, resolvedCwd, (signal, onChildEvent, onArbitrationRecord) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile(), onChildEvent, thinkingOverride, arbitrate
+                        ? {
+                            arbitrate,
+                            onRecord: onArbitrationRecord,
+                            defaultThinkingLevel: getDefaultThinkingLevel?.(),
+                            getAgentModelsForAgent,
+                        }
+                        : undefined));
                 };
                 if (params.task) {
                     // Single background task
                     const agentName = params.agent || DEFAULT_AGENT;
-                    const agentId = launchBackgroundTask(agentName, params.task, `${agentName} task`, undefined, params.model);
+                    const agentId = launchBackgroundTask(agentName, params.task, `${agentName} task`, undefined, params.model, params.thinking);
                     return {
                         content: [
                             {
@@ -1554,7 +1830,7 @@ export function createSubagentToolDefinition(cwd, options) {
                             skipped.push({ taskText: item.task, error: cwdResult.error });
                             continue;
                         }
-                        const agentId = launchBackgroundTask(agentName, item.task, `${agentName} task ${i + 1}/${params.tasks.length}`, cwdResult.cwd, item.model || params.model);
+                        const agentId = launchBackgroundTask(agentName, item.task, `${agentName} task ${i + 1}/${params.tasks.length}`, cwdResult.cwd, item.model || params.model, resolveSubagentThinkingOverride(item.thinking, params.thinking));
                         launched.push({ id: agentId, agentName, taskText: item.task });
                     }
                     const listing = launched
@@ -1590,8 +1866,15 @@ export function createSubagentToolDefinition(cwd, options) {
                     const taskSummary = `${params.chain.length}-step chain`;
                     const chainSteps = params.chain;
                     const chainSessionDir = join(subagentSessionsBase, `chain-${generateAgentId()}`);
-                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, chainSessionDir, cwd, async (signal, onChildEvent) => {
-                        const results = await executeChain(agents, chainSteps, cwd, signal, undefined, getParentProvider(), modelRegistry, chainSessionDir, params.agent, params.model, getParentModel(), getAgentModelsForAgent, getParentSessionFile(), onChildEvent);
+                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, chainSessionDir, cwd, async (signal, onChildEvent, onArbitrationRecord) => {
+                        const results = await executeChain(agents, chainSteps, cwd, signal, undefined, getParentProvider(), modelRegistry, chainSessionDir, params.agent, params.model, params.thinking, getParentModel(), getAgentModelsForAgent, getParentSessionFile(), onChildEvent, arbitrate
+                            ? {
+                                arbitrate,
+                                onRecord: onArbitrationRecord,
+                                defaultThinkingLevel: getDefaultThinkingLevel?.(),
+                                getAgentModelsForAgent,
+                            }
+                            : undefined);
                         const resultText = results
                             .map((r, i) => `### Step ${i + 1}\n${formatSingleResult(r)}`)
                             .join("\n\n---\n\n");
@@ -1600,6 +1883,13 @@ export function createSubagentToolDefinition(cwd, options) {
                         return {
                             agent: agentName,
                             task: taskSummary,
+                            steps: results.map((result, index) => ({
+                                step: index + 1,
+                                agent: result.agent,
+                                success: result.exitCode === 0,
+                                model: result.model,
+                                thinking: result.thinking,
+                            })),
                             exitCode: failed.length > 0 ? 1 : 0,
                             output: resultText,
                             stderr: "",