@ouro.bot/cli 0.1.0-alpha.21 → 0.1.0-alpha.211

package/dist/heart/core.js

@@ -7,6 +7,8 @@ exports.getModel = getModel;
 exports.getProvider = getProvider;
 exports.createSummarize = createSummarize;
 exports.getProviderDisplayLabel = getProviderDisplayLabel;
+exports.isExternalStateQuery = isExternalStateQuery;
+exports.getSettleRetryError = getSettleRetryError;
 exports.stripLastToolCalls = stripLastToolCalls;
 exports.repairOrphanedToolCalls = repairOrphanedToolCalls;
 exports.isTransientError = isTransientError;
@@ -16,9 +18,7 @@ const config_1 = require("./config");
 const identity_1 = require("./identity");
 const tools_1 = require("../repertoire/tools");
 const channel_1 = require("../mind/friends/channel");
-// Kick detection preserved but disabled — see comment in agent loop below.
-// import { detectKick } from "./kicks";
-// import type { KickReason } from "./kicks";
+const tools_2 = require("../repertoire/tools");
 const runtime_1 = require("../nerves/runtime");
 const context_1 = require("../mind/context");
 const prompt_1 = require("../mind/prompt");
@@ -27,71 +27,96 @@ const anthropic_1 = require("./providers/anthropic");
 const azure_1 = require("./providers/azure");
 const minimax_1 = require("./providers/minimax");
 const openai_codex_1 = require("./providers/openai-codex");
-let _providerRuntime = null;
+const github_copilot_1 = require("./providers/github-copilot");
+const pending_1 = require("../mind/pending");
+const identity_2 = require("./identity");
+const socket_client_1 = require("./daemon/socket-client");
+const obligations_1 = require("../arc/obligations");
+const tool_loop_1 = require("./tool-loop");
+const _providerRuntimes = {
+    human: null,
+    agent: null,
+};
+function getProviderRuntimeFingerprint(facing) {
+    const config = (0, identity_1.loadAgentConfig)();
+    const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
+    const provider = facingConfig.provider;
+    const model = facingConfig.model;
+    const providerConfig = (0, config_1.getProviderConfig)(provider);
+    return JSON.stringify({ provider, model, ...providerConfig });
+}
 function createProviderRegistry() {
     const factories = {
         azure: azure_1.createAzureProviderRuntime,
         anthropic: anthropic_1.createAnthropicProviderRuntime,
         minimax: minimax_1.createMinimaxProviderRuntime,
         "openai-codex": openai_codex_1.createOpenAICodexProviderRuntime,
+        "github-copilot": github_copilot_1.createGithubCopilotProviderRuntime,
     };
     return {
-        resolve() {
-            const provider = (0, identity_1.loadAgentConfig)().provider;
-            return factories[provider]();
+        resolve(provider, model) {
+            const resolvedProvider = provider ?? (0, identity_1.loadAgentConfig)().humanFacing.provider;
+            const resolvedModel = model ?? (0, identity_1.loadAgentConfig)().humanFacing.model;
+            return factories[resolvedProvider](resolvedModel);
         },
     };
 }
-function getProviderRuntime() {
-    if (!_providerRuntime) {
-        try {
-            _providerRuntime = createProviderRegistry().resolve();
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "engine.provider_init_error",
-                component: "engine",
-                message: msg,
-                meta: {},
-            });
-            // eslint-disable-next-line no-console -- pre-boot guard: provider init failure
-            console.error(`\n[fatal] ${msg}\n`);
-            process.exit(1);
-            throw new Error("unreachable");
-        }
-        if (!_providerRuntime) {
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "engine.provider_init_error",
-                component: "engine",
-                message: "provider runtime could not be initialized.",
-                meta: {},
-            });
-            process.exit(1);
-            throw new Error("unreachable");
+function getProviderRuntime(facing = "human") {
+    try {
+        const fingerprint = getProviderRuntimeFingerprint(facing);
+        const cached = _providerRuntimes[facing];
+        if (!cached || cached.fingerprint !== fingerprint) {
+            const config = (0, identity_1.loadAgentConfig)();
+            const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
+            const runtime = createProviderRegistry().resolve(facingConfig.provider, facingConfig.model);
+            _providerRuntimes[facing] = runtime ? { fingerprint, runtime } : null;
         }
     }
-    return _providerRuntime;
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "engine.provider_init_error",
+            component: "engine",
+            message: msg,
+            meta: {},
+        });
+        // eslint-disable-next-line no-console -- pre-boot guard: provider init failure
+        console.error(`\n[fatal] ${msg}\n`);
+        process.exit(1);
+        throw new Error("unreachable");
+    }
+    if (!_providerRuntimes[facing]) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "engine.provider_init_error",
+            component: "engine",
+            message: "provider runtime could not be initialized.",
+            meta: {},
+        });
+        process.exit(1);
+        throw new Error("unreachable");
+    }
+    return _providerRuntimes[facing].runtime;
 }
 /**
- * Clear the cached provider runtime so the next call to getProviderRuntime()
- * re-creates it from current config. Used by the adoption specialist to
- * switch provider context without restarting the process.
+ * Clear the cached provider runtime so the next access re-creates it from
+ * current config. Runtime access also auto-refreshes when the selected
+ * provider fingerprint changes on disk.
  */
 function resetProviderRuntime() {
-    _providerRuntime = null;
+    _providerRuntimes.human = null;
+    _providerRuntimes.agent = null;
 }
-function getModel() {
-    return getProviderRuntime().model;
+function getModel(facing = "human") {
+    return getProviderRuntime(facing).model;
 }
-function getProvider() {
-    return getProviderRuntime().id;
+function getProvider(facing = "human") {
+    return getProviderRuntime(facing).id;
 }
-function createSummarize() {
+function createSummarize(facing = "human") {
     return async (transcript, instruction) => {
-        const runtime = getProviderRuntime();
+        const runtime = getProviderRuntime(facing);
         const client = runtime.client;
         const response = await client.chat.completions.create({
             model: runtime.model,
@@ -104,22 +129,30 @@ function createSummarize() {
         return response.choices?.[0]?.message?.content ?? transcript;
     };
 }
-function getProviderDisplayLabel() {
-    const model = getModel();
+function getProviderDisplayLabel(facing = "human") {
+    const config = (0, identity_1.loadAgentConfig)();
+    const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
+    const provider = facingConfig.provider;
+    const model = facingConfig.model || "unknown";
     const providerLabelBuilders = {
-        azure: () => `azure openai (${(0, config_1.getAzureConfig)().deployment || "default"}, model: ${model})`,
+        azure: () => {
+            const azureCfg = (0, config_1.getAzureConfig)();
+            return `azure openai (${azureCfg.deployment || "default"}, model: ${model})`;
+        },
         anthropic: () => `anthropic (${model})`,
         minimax: () => `minimax (${model})`,
         "openai-codex": () => `openai codex (${model})`,
+        /* v8 ignore next -- branch: tested via display label unit test @preserve */
+        "github-copilot": () => `github copilot (${model})`,
     };
-    return providerLabelBuilders[getProvider()]();
+    return providerLabelBuilders[provider]();
 }
 // Re-export tools, execTool, summarizeArgs from ./tools for backward compat
-var tools_2 = require("../repertoire/tools");
-Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_2.tools; } });
-Object.defineProperty(exports, "execTool", { enumerable: true, get: function () { return tools_2.execTool; } });
-Object.defineProperty(exports, "summarizeArgs", { enumerable: true, get: function () { return tools_2.summarizeArgs; } });
-Object.defineProperty(exports, "getToolsForChannel", { enumerable: true, get: function () { return tools_2.getToolsForChannel; } });
+var tools_3 = require("../repertoire/tools");
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_3.tools; } });
+Object.defineProperty(exports, "execTool", { enumerable: true, get: function () { return tools_3.execTool; } });
+Object.defineProperty(exports, "summarizeArgs", { enumerable: true, get: function () { return tools_3.summarizeArgs; } });
+Object.defineProperty(exports, "getToolsForChannel", { enumerable: true, get: function () { return tools_3.getToolsForChannel; } });
 // Re-export streaming functions for backward compat
 var streaming_1 = require("./streaming");
 Object.defineProperty(exports, "streamChatCompletion", { enumerable: true, get: function () { return streaming_1.streamChatCompletion; } });
@@ -129,6 +162,108 @@ Object.defineProperty(exports, "toResponsesTools", { enumerable: true, get: func
 // Re-export prompt functions for backward compat
 var prompt_2 = require("../mind/prompt");
 Object.defineProperty(exports, "buildSystem", { enumerable: true, get: function () { return prompt_2.buildSystem; } });
+// Sole-call tools must be the only tool call in a turn. When they appear
+// alongside other tools, the sole-call tool is rejected with this message.
+const SOLE_CALL_REJECTION = {
+    settle: "rejected: settle must be the only tool call. finish your work first, then call settle alone.",
+    observe: "rejected: observe must be the only tool call. call observe alone when you want to stay silent.",
+    ponder: "rejected: ponder must be the only tool call. finish your other work first, then call ponder alone.",
+    rest: "rejected: rest must be the only tool call. finish your work first, then call rest alone.",
+};
+const DELEGATION_REASON_PROSE_HANDOFF = {
+    explicit_reflection: "something in the conversation called for reflection",
+    cross_session: "this touches other conversations",
+    bridge_state: "there's shared work spanning sessions",
+    task_state: "there are active tasks that relate to this",
+    non_fast_path_tool: "this needs tools beyond a simple reply",
+    unresolved_obligation: "there's an unresolved commitment from an earlier conversation",
+};
+function buildPonderHandoffPacket(params) {
+    const reasons = params.delegationDecision?.reasons ?? [];
+    const reasonProse = reasons.length > 0
+        ? reasons.map((r) => DELEGATION_REASON_PROSE_HANDOFF[r]).join("; ")
+        : "this felt like it needed more thought";
+    const whoAsked = params.currentSession
+        ? params.currentSession.friendId
+        : "no one -- just thinking";
+    let holdingLine;
+    if (params.outwardClosureRequired && params.currentSession) {
+        holdingLine = `i'm holding something for ${params.currentSession.friendId}`;
+    }
+    else {
+        holdingLine = "nothing -- just thinking";
+    }
+    return [
+        "## what i need to think about",
+        params.topic,
+        "",
+        "## why this came up",
+        reasonProse,
+        "",
+        "## who asked",
+        whoAsked,
+        "",
+        "## what i'm holding",
+        holdingLine,
+        "",
+        "## thinking mode",
+        params.mode,
+    ].join("\n");
+}
+function parseSettlePayload(argumentsText) {
+    try {
+        const parsed = JSON.parse(argumentsText);
+        if (typeof parsed === "string") {
+            return { answer: parsed };
+        }
+        if (!parsed || typeof parsed !== "object") {
+            return {};
+        }
+        const answer = typeof parsed.answer === "string" ? parsed.answer : undefined;
+        const rawIntent = parsed.intent;
+        const intent = rawIntent === "complete" || rawIntent === "blocked" || rawIntent === "direct_reply"
+            ? rawIntent
+            : undefined;
+        return { answer, intent };
+    }
+    catch {
+        return {};
+    }
+}
+/** Returns true when a tool call queries external state (GitHub, npm registry). */
+function isExternalStateQuery(toolName, args) {
+    if (toolName !== "shell")
+        return false;
+    const cmd = String(args.command ?? "");
+    return /\bgh\s+(pr|run|api|issue)\b/.test(cmd) || /\bnpm\s+(view|info|show)\b/.test(cmd);
+}
+function getSettleRetryError(mustResolveBeforeHandoff, intent, sawSteeringFollowUp, _delegationDecision, sawSendMessageSelf, sawPonder, _sawQuerySession, currentObligation, innerJob, sawExternalStateQuery) {
+    // Delegation adherence removed: the delegation decision is surfaced in the
+    // system prompt as a suggestion. Hard-gating settle caused infinite
+    // rejection loops where the agent couldn't respond to the user at all.
+    // The agent is free to follow or ignore the delegation hint.
+    // 2. Pending obligation not addressed
+    if (innerJob?.obligationStatus === "pending" && !sawSendMessageSelf && !sawPonder) {
+        return "you're still holding something from an earlier conversation -- someone is waiting for your answer. finish the thought first, or ponder to keep working on it privately.";
+    }
+    // 3. mustResolveBeforeHandoff + missing intent
+    if (mustResolveBeforeHandoff && !intent) {
+        return "your settle is missing required intent. when you must keep going until done or blocked, call settle again with answer plus intent=complete, blocked, or direct_reply.";
+    }
+    // 4. mustResolveBeforeHandoff + direct_reply without follow-up
+    if (mustResolveBeforeHandoff && intent === "direct_reply" && !sawSteeringFollowUp) {
+        return "your settle used intent=direct_reply without a newer steering follow-up. continue the unresolved work, or call settle again with intent=complete or blocked when appropriate.";
+    }
+    // 5. mustResolveBeforeHandoff + complete while a live return loop is still active
+    if (mustResolveBeforeHandoff && intent === "complete" && currentObligation && !sawSteeringFollowUp) {
+        return "you still owe the live session a visible return on this work. don't end the turn yet — continue until you've brought back the external-state update, or use intent=blocked with the concrete blocker.";
+    }
+    // 6. External-state grounding: obligation + complete requires fresh external verification
+    if (intent === "complete" && currentObligation && !sawExternalStateQuery && !sawSteeringFollowUp) {
+        return "you're claiming this work is complete, but the external state hasn't been verified this turn. ground your claim with a fresh check (gh pr view, npm view, gh run view, etc.) before calling settle.";
+    }
+    return null;
+}
 // Re-export kick utilities for backward compat
 var kicks_1 = require("./kicks");
 Object.defineProperty(exports, "hasToolIntent", { enumerable: true, get: function () { return kicks_1.hasToolIntent; } });
@@ -278,8 +413,17 @@ function classifyTransientError(err) {
 }
 const MAX_RETRIES = 3;
 const RETRY_BASE_MS = 2000;
+const TRANSIENT_RETRY_LABELS = {
+    "auth-failure": "auth error",
+    "usage-limit": "usage limit",
+    "rate-limit": "rate limited",
+    "server-error": "server error",
+    "network-error": "network error",
+    "unknown": "error",
+};
 async function runAgent(messages, callbacks, channel, signal, options) {
-    const providerRuntime = getProviderRuntime();
+    const facing = (0, channel_1.channelToFacing)(channel);
+    const providerRuntime = getProviderRuntime(facing);
     const provider = providerRuntime.id;
     const toolChoiceRequired = options?.toolChoiceRequired ?? true;
     const traceId = options?.traceId;
@@ -305,7 +449,12 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     // so turn execution remains consistent and non-fatal.
     if (channel) {
         try {
-            const refreshed = await (0, prompt_1.buildSystem)(channel, options, currentContext);
+            const buildSystemOptions = {
+                ...options,
+                providerCapabilities: providerRuntime.capabilities,
+                supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+            };
+            const refreshed = await (0, prompt_1.buildSystem)(channel, buildSystemOptions, currentContext);
             upsertSystemPrompt(messages, refreshed);
         }
         catch (error) {
@@ -328,31 +477,77 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         }
     }
     await (0, associative_recall_1.injectAssociativeRecall)(messages);
-    // kickCount and lastKickReason preserved but unused while kick detection is disabled.
-    // let kickCount = 0;
-    // let lastKickReason: KickReason | null = null;
     let done = false;
     let lastUsage;
     let overflowRetried = false;
     let retryCount = 0;
+    let outcome = "settled";
+    let completion;
+    let terminalError;
+    let terminalErrorClassification;
+    let sawSteeringFollowUp = false;
+    let mustResolveBeforeHandoffActive = options?.mustResolveBeforeHandoff === true;
+    let currentReasoningEffort = "medium";
+    let sawSendMessageSelf = false;
+    let sawPonder = false;
+    let sawQuerySession = false;
+    let sawBridgeManage = false;
+    let sawExternalStateQuery = false;
+    const toolLoopState = (0, tool_loop_1.createToolLoopState)();
     // Prevent MaxListenersExceeded warning — each iteration adds a listener
     try {
         require("events").setMaxListeners(50, signal);
     }
     catch { /* unsupported */ }
     const toolPreferences = currentContext?.friend?.toolPreferences;
-    const baseTools = options?.tools ?? (0, tools_1.getToolsForChannel)(channel ? (0, channel_1.getChannelCapabilities)(channel) : undefined, toolPreferences && Object.keys(toolPreferences).length > 0 ? toolPreferences : undefined, currentContext);
+    const baseTools = options?.tools ?? (0, tools_1.getToolsForChannel)(channel ? (0, channel_1.getChannelCapabilities)(channel) : undefined, toolPreferences && Object.keys(toolPreferences).length > 0 ? toolPreferences : undefined, currentContext, providerRuntime.capabilities);
+    // Augment tool context with reasoning effort controls from provider
+    const augmentedToolContext = options?.toolContext
+        ? {
+            ...options.toolContext,
+            supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+            setReasoningEffort: (level) => { currentReasoningEffort = level; },
+            activeWorkFrame: options?.activeWorkFrame,
+        }
+        : undefined;
     // Rebase provider-owned turn state from canonical messages at user-turn start.
     // This prevents stale provider caches from replaying prior-turn context.
     providerRuntime.resetTurnState(messages);
     while (!done) {
-        // When toolChoiceRequired is true (the default), include final_answer
-        // so the model can signal completion. With tool_choice: required, the
-        // model must call a tool every turn — final_answer is how it exits.
-        // Overridable via options.toolChoiceRequired = false (e.g. CLI).
-        const activeTools = toolChoiceRequired ? [...baseTools, tools_1.finalAnswerTool] : baseTools;
+        // Channel-based tool filtering:
+        // - Inner dialog: exclude send_message (delivery via surface), observe (no one to observe)
+        // - 1:1 sessions: exclude observe (can't ignore someone talking directly to you)
+        // - Group chats: observe available
+        //
+        // ponder, settle/rest, surface, and observe are always assembled based on channel context.
+        // ponder is available in ALL channels (outer: think privately, inner: keep turning).
+        // Inner dialog gets restTool instead of settleTool (rest = end turn, gated by attention queue).
+        // toolChoiceRequired only controls whether tool_choice: "required" is set in the API call.
+        const isInnerDialog = channel === "inner";
+        const filteredBaseTools = isInnerDialog
+            ? baseTools.filter((t) => t.function.name !== "send_message")
+            : baseTools;
+        const activeTools = [
+            ...filteredBaseTools,
+            tools_1.ponderTool,
+            ...(isInnerDialog ? [tools_2.surfaceToolDef, tools_1.restTool] : []),
+            ...((currentContext?.isGroupChat || options?.isReactionSignal) && !isInnerDialog ? [tools_1.observeTool] : []),
+            ...(!isInnerDialog ? [tools_1.settleTool] : []),
+        ];
         const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
         if (steeringFollowUps.length > 0) {
+            const hasSupersedingFollowUp = steeringFollowUps.some((followUp) => followUp.effect === "clear_and_supersede");
+            if (hasSupersedingFollowUp) {
+                mustResolveBeforeHandoffActive = false;
+                options?.setMustResolveBeforeHandoff?.(false);
+                outcome = "superseded";
+                break;
+            }
+            if (steeringFollowUps.some((followUp) => followUp.effect === "set_no_handoff")) {
+                mustResolveBeforeHandoffActive = true;
+                options?.setMustResolveBeforeHandoff?.(true);
+            }
+            sawSteeringFollowUp = true;
             for (const followUp of steeringFollowUps) {
                 messages.push({ role: "user", content: followUp.text });
             }
@@ -360,8 +555,10 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         }
         // Yield so pending I/O (stdin Ctrl-C) can be processed between iterations
         await new Promise((r) => setImmediate(r));
-        if (signal?.aborted)
+        if (signal?.aborted) {
+            outcome = "aborted";
             break;
+        }
         try {
             callbacks.onModelStart();
             const result = await providerRuntime.streamTurn({
@@ -371,6 +568,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 signal,
                 traceId,
                 toolChoiceRequired,
+                reasoningEffort: currentReasoningEffort,
+                eagerSettleStreaming: true,
             });
             // Track usage from the latest API call
             if (result.usage)
@@ -394,52 +593,76 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             if (reasoningItems.length > 0) {
                 msg._reasoning_items = reasoningItems;
             }
+            // Store thinking blocks (Anthropic) on the assistant message for round-tripping
+            const thinkingItems = result.outputItems.filter((item) => "type" in item && (item.type === "thinking" || item.type === "redacted_thinking"));
+            if (thinkingItems.length > 0) {
+                msg._thinking_blocks = thinkingItems;
+            }
+            // Phase annotation for Codex provider
+            const hasPhaseAnnotation = providerRuntime.capabilities.has("phase-annotation");
+            const isSoleSettle = result.toolCalls.length === 1 && result.toolCalls[0].name === "settle";
+            if (hasPhaseAnnotation) {
+                msg.phase = isSoleSettle ? "settle" : "commentary";
+            }
             if (!result.toolCalls.length) {
-                // Kick detection is disabled while tool_choice: required + final_answer
-                // is the primary loop control mechanism. The model should never reach
-                // this path (tool_choice: required forces a tool call), but if it does,
-                // accept the response as-is rather than risk false-positive kicks.
-                //
-                // Preserved for future use — re-enable by uncommenting:
-                // const kick = detectKick(result.content, options);
-                // if (kick) {
-                //   kickCount++;
-                //   lastKickReason = kick.reason;
-                //   callbacks.onKick?.();
-                //   const kickContent = result.content
-                //     ? result.content + "\n\n" + kick.message
-                //     : kick.message;
-                //   messages.push({ role: "assistant", content: kickContent });
-                //   providerRuntime.resetTurnState(messages);
-                //   continue;
-                // }
+                // No tool calls — accept response as-is.
+                // (Kick detection disabled; tool_choice: required + settle
+                // is the primary loop control. See src/heart/kicks.ts to re-enable.)
                 messages.push(msg);
                 done = true;
             }
             else {
-                // Check for final_answer sole call: intercept before tool execution
-                const isSoleFinalAnswer = result.toolCalls.length === 1 && result.toolCalls[0].name === "final_answer";
-                if (isSoleFinalAnswer) {
-                    // Extract answer from the tool call arguments.
-                    // Supports: {"answer":"text"}, "text" (JSON string), retry on failure.
-                    let answer;
-                    try {
-                        const parsed = JSON.parse(result.toolCalls[0].arguments);
-                        if (typeof parsed === "string") {
-                            answer = parsed;
-                        }
-                        else if (parsed.answer != null) {
-                            answer = parsed.answer;
-                        }
-                        // else: valid JSON but no answer field — answer stays undefined (retry)
+                // Check for settle sole call: intercept before tool execution
+                if (isSoleSettle) {
+                    /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
+                    const settleArgs = (() => { try {
+                        return JSON.parse(result.toolCalls[0].arguments);
                     }
                     catch {
-                        // JSON parsing failed (e.g. truncated output) — answer stays undefined (retry)
+                        return {};
+                    } })();
+                    callbacks.onToolStart("settle", settleArgs);
+                    // Inner dialog attention queue gate: reject settle if items remain
+                    const attentionQueue = (augmentedToolContext ?? options?.toolContext)?.delegatedOrigins;
+                    if (isInnerDialog && attentionQueue && attentionQueue.length > 0) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                        callbacks.onClearText?.();
+                        messages.push(msg);
+                        const gateMessage = "you're holding thoughts someone is waiting for — surface them before you settle.";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: gateMessage });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, gateMessage);
+                        continue;
                     }
-                    if (answer != null) {
-                        if (result.finalAnswerStreamed) {
+                    // Extract answer from the tool call arguments.
+                    // Supports: {"answer":"text","intent":"..."} or "text" (JSON string).
+                    const { answer, intent } = parseSettlePayload(result.toolCalls[0].arguments);
+                    // Inner dialog settle: no CompletionMetadata, "(settled)" ack
+                    if (isInnerDialog) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
+                        messages.push(msg);
+                        const settled = "(settled)";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: settled });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, settled);
+                        outcome = "settled";
+                        done = true;
+                        continue;
+                    }
+                    const retryError = getSettleRetryError(mustResolveBeforeHandoffActive, intent, sawSteeringFollowUp, options?.delegationDecision, sawSendMessageSelf, sawPonder, sawQuerySession, options?.currentObligation ?? null, options?.activeWorkFrame?.inner?.job, sawExternalStateQuery);
+                    const deliveredAnswer = answer;
+                    const validDirectReply = mustResolveBeforeHandoffActive && intent === "direct_reply" && sawSteeringFollowUp;
+                    const validTerminalIntent = intent === "complete" || intent === "blocked";
+                    const validClosure = deliveredAnswer != null
+                        && !retryError
+                        && (!mustResolveBeforeHandoffActive || validDirectReply || validTerminalIntent);
+                    if (validClosure) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
+                        completion = {
+                            answer: deliveredAnswer,
+                            intent: validDirectReply ? "direct_reply" : intent === "blocked" ? "blocked" : "complete",
+                        };
+                        if (result.settleStreamed) {
                             // The streaming layer already parsed and emitted the answer
-                            // progressively via FinalAnswerParser. Skip clearing and
+                            // progressively via SettleParser. Skip clearing and
                             // re-emitting to avoid double-delivery.
                         }
                         else {
@@ -447,37 +670,229 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                             callbacks.onClearText?.();
                             // Emit the answer through the callback pipeline so channels receive it.
                             // Never truncate -- channel adapters handle splitting long messages.
-                            callbacks.onTextChunk(answer);
+                            callbacks.onTextChunk(deliveredAnswer);
                         }
-                        // Keep the full assistant message (with tool_calls) for debuggability,
-                        // plus a synthetic tool response so the conversation stays valid on resume.
                         messages.push(msg);
-                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: "(delivered)" });
-                        providerRuntime.appendToolOutput(result.toolCalls[0].id, "(delivered)");
-                        done = true;
+                        if (validDirectReply) {
+                            const resumeWork = "direct reply delivered. resume the unresolved obligation now and keep working until you can finish or clearly report that you are blocked.";
+                            messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: resumeWork });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, resumeWork);
+                        }
+                        else {
+                            const delivered = "(delivered)";
+                            messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: delivered });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, delivered);
+                            outcome = intent === "blocked" ? "blocked" : "settled";
+                            done = true;
+                        }
                     }
                     else {
-                        // Answer is undefined -- the model's final_answer was incomplete or
+                        // Answer is undefined -- the model's settle was incomplete or
                         // malformed. Clear any partial streamed text or noise, then push the
                         // assistant msg + error tool result and let the model try again.
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
                         callbacks.onClearText?.();
-                        const retryError = "your final_answer was incomplete or malformed. call final_answer again with your complete response.";
                         messages.push(msg);
-                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: retryError });
-                        providerRuntime.appendToolOutput(result.toolCalls[0].id, retryError);
+                        const toolRetryMessage = retryError
+                            ?? "your settle was incomplete or malformed. call settle again with your complete response.";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: toolRetryMessage });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, toolRetryMessage);
+                    }
+                    continue;
+                }
+                // Check for observe sole call: intercept before tool execution
+                const isSoleObserve = result.toolCalls.length === 1 && result.toolCalls[0].name === "observe";
+                if (isSoleObserve) {
+                    /* v8 ignore next -- defensive: JSON.parse catch for malformed observe args @preserve */
+                    const observeArgs = (() => { try {
+                        return JSON.parse(result.toolCalls[0].arguments);
                     }
+                    catch {
+                        return {};
+                    } })();
+                    let reason;
+                    if (typeof observeArgs?.reason === "string")
+                        reason = observeArgs.reason;
+                    callbacks.onToolStart("observe", observeArgs);
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "engine",
+                        event: "engine.observe",
+                        message: "agent observed without responding",
+                        meta: { ...(reason ? { reason } : {}) },
+                    });
+                    callbacks.onToolEnd("observe", (0, tools_1.summarizeArgs)("observe", observeArgs), true);
+                    messages.push(msg);
+                    const silenced = "(silenced)";
+                    messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: silenced });
+                    providerRuntime.appendToolOutput(result.toolCalls[0].id, silenced);
+                    outcome = "observed";
+                    done = true;
+                    continue;
+                }
+                // Check for ponder sole call: intercept before tool execution
+                const isSolePonder = result.toolCalls.length === 1 && result.toolCalls[0].name === "ponder";
+                if (isSolePonder) {
+                    let parsedArgs = {};
+                    try {
+                        parsedArgs = JSON.parse(result.toolCalls[0].arguments);
+                    }
+                    catch { /* ignore */ }
+                    callbacks.onToolStart("ponder", parsedArgs);
+                    const currentSession = options?.toolContext?.currentSession;
+                    const isInnerChannel = currentSession?.friendId === "self" && currentSession?.channel === "inner";
+                    if (!isInnerChannel) {
+                        // Outer session: thought and say are required
+                        const thought = typeof parsedArgs.thought === "string" ? parsedArgs.thought : undefined;
+                        const say = typeof parsedArgs.say === "string" ? parsedArgs.say : undefined;
+                        if (!thought || !say) {
+                            callbacks.onToolEnd("ponder", (0, tools_1.summarizeArgs)("ponder", parsedArgs), false);
+                            messages.push(msg);
+                            const errorMsg = "ponder requires both thought and say when called from a conversation. thought is what needs more thinking; say is what you tell them before going quiet.";
+                            messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: errorMsg });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, errorMsg);
+                            continue;
+                        }
+                        // Emit outward say text
+                        callbacks.onClearText?.();
+                        callbacks.onTextChunk(say);
+                        // Build handoff packet and enqueue
+                        const handoffContent = buildPonderHandoffPacket({
+                            topic: thought,
+                            mode: "reflect",
+                            delegationDecision: options?.delegationDecision,
+                            currentSession: currentSession ?? null,
+                            currentObligation: options?.currentObligation ?? null,
+                            outwardClosureRequired: options?.delegationDecision?.outwardClosureRequired ?? false,
+                        });
+                        const pendingDir = (0, pending_1.getInnerDialogPendingDir)((0, identity_2.getAgentName)());
+                        // Create obligation FIRST so we can attach its ID to the pending message
+                        let createdObligationId;
+                        if (currentSession) {
+                            try {
+                                const obligation = (0, obligations_1.createObligation)((0, identity_2.getAgentRoot)(), {
+                                    origin: {
+                                        friendId: currentSession.friendId,
+                                        channel: currentSession.channel,
+                                        key: currentSession.key,
+                                    },
+                                    content: thought,
+                                });
+                                createdObligationId = obligation.id;
+                            }
+                            catch {
+                                /* v8 ignore next -- defensive: obligation store write failure should not break ponder @preserve */
+                            }
+                        }
+                        const envelope = {
+                            from: (0, identity_2.getAgentName)(),
+                            friendId: "self",
+                            channel: "inner",
+                            key: "dialog",
+                            content: handoffContent,
+                            timestamp: Date.now(),
+                            ...(currentSession ? {
+                                delegatedFrom: {
+                                    friendId: currentSession.friendId,
+                                    channel: currentSession.channel,
+                                    key: currentSession.key,
+                                },
+                                obligationStatus: "pending",
+                                /* v8 ignore next -- defensive: createdObligationId is undefined only when obligation store write fails @preserve */
+                                ...(createdObligationId ? { obligationId: createdObligationId } : {}),
+                            } : {}),
+                        };
+                        (0, pending_1.queuePendingMessage)(pendingDir, envelope);
+                        try {
+                            await (0, socket_client_1.requestInnerWake)((0, identity_2.getAgentName)());
+                        }
+                        catch { /* daemon may not be running */ }
+                        callbacks.onToolEnd("ponder", (0, tools_1.summarizeArgs)("ponder", parsedArgs), true);
+                        sawPonder = true;
+                        messages.push(msg);
+                        const ack = "(pondering)";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: ack });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, ack);
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "engine",
+                            event: "engine.pondered",
+                            message: "pondering",
+                            meta: { hasThought: true, hasSay: true, contentSnippet: thought.slice(0, 80) },
+                        });
+                    }
+                    else {
+                        // Inner dialog: parameterless, enqueue synthetic pending WITHOUT delegatedFrom
+                        const pendingDir = (0, pending_1.getInnerDialogPendingDir)((0, identity_2.getAgentName)());
+                        const envelope = {
+                            from: (0, identity_2.getAgentName)(),
+                            friendId: "self",
+                            channel: "inner",
+                            key: "dialog",
+                            content: "continuing to think...",
+                            timestamp: Date.now(),
+                        };
+                        (0, pending_1.queuePendingMessage)(pendingDir, envelope);
+                        callbacks.onToolEnd("ponder", (0, tools_1.summarizeArgs)("ponder", parsedArgs), true);
+                        sawPonder = true;
+                        messages.push(msg);
+                        const ack = "(pondering)";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: ack });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, ack);
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "engine",
+                            event: "engine.pondered",
+                            message: "pondering from inner dialog",
+                            meta: { inner: true },
+                        });
+                    }
+                    outcome = "pondered";
+                    done = true;
+                    continue;
+                }
+                // Check for rest sole call: intercept before tool execution
+                const isSoleRest = result.toolCalls.length === 1 && result.toolCalls[0].name === "rest";
+                if (isSoleRest) {
+                    const restArgs = (() => { try {
+                        return JSON.parse(result.toolCalls[0].arguments);
+                    }
+                    catch {
+                        return {};
+                    } })();
+                    callbacks.onToolStart("rest", restArgs);
+                    // Attention queue gate: reject rest if items remain
+                    const attentionQueue = (augmentedToolContext ?? options?.toolContext)?.delegatedOrigins;
+                    if (attentionQueue && attentionQueue.length > 0) {
+                        callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), false);
+                        messages.push(msg);
+                        const gateMessage = "you're holding thoughts someone is waiting for — surface them before you rest.";
+                        messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: gateMessage });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, gateMessage);
+                        continue;
+                    }
+                    callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), true);
+                    messages.push(msg);
+                    const ack = "(resting)";
+                    messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: ack });
+                    providerRuntime.appendToolOutput(result.toolCalls[0].id, ack);
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "engine",
+                        event: "engine.rested",
+                        message: "resting until next heartbeat",
+                        meta: {},
+                    });
+                    outcome = "rested";
+                    done = true;
                     continue;
                 }
                 messages.push(msg);
-                // SHARED: execute tools (final_answer in mixed calls is rejected inline)
+                // Execute tools (sole-call tools in mixed calls are rejected inline)
                 for (const tc of result.toolCalls) {
                     if (signal?.aborted)
                         break;
-                    // Intercept final_answer in mixed call: reject it
-                    if (tc.name === "final_answer") {
-                        const rejection = "rejected: final_answer must be the only tool call. Finish your work first, then call final_answer alone.";
-                        messages.push({ role: "tool", tool_call_id: tc.id, content: rejection });
-                        providerRuntime.appendToolOutput(tc.id, rejection);
+                    // Reject sole-call tools when mixed with other tool calls
+                    const soleCallRejection = SOLE_CALL_REJECTION[tc.name];
+                    if (soleCallRejection) {
+                        messages.push({ role: "tool", tool_call_id: tc.id, content: soleCallRejection });
+                        providerRuntime.appendToolOutput(tc.id, soleCallRejection);
                         continue;
                     }
                     let args = {};
@@ -487,9 +902,32 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     catch {
                         /* ignore */
                     }
+                    if (tc.name === "send_message" && args.friendId === "self") {
+                        sawSendMessageSelf = true;
+                    }
+                    /* v8 ignore next -- flag tested via truth-check integration tests @preserve */
+                    if (tc.name === "query_session")
+                        sawQuerySession = true;
+                    /* v8 ignore next -- flag tested via truth-check integration tests @preserve */
+                    if (tc.name === "bridge_manage")
+                        sawBridgeManage = true;
+                    /* v8 ignore next -- flag tested via truth-check integration tests @preserve */
+                    if (isExternalStateQuery(tc.name, args))
+                        sawExternalStateQuery = true;
                     const argSummary = (0, tools_1.summarizeArgs)(tc.name, args);
-                    // Confirmation check for mutate tools
-                    if ((0, tools_1.isConfirmationRequired)(tc.name) && !options?.skipConfirmation) {
+                    const toolLoop = (0, tool_loop_1.detectToolLoop)(toolLoopState, tc.name, args);
+                    if (toolLoop.stuck) {
+                        const rejection = `loop guard: ${toolLoop.message}`;
+                        callbacks.onToolStart(tc.name, args);
+                        callbacks.onToolEnd(tc.name, argSummary, false);
+                        messages.push({ role: "tool", tool_call_id: tc.id, content: rejection });
+                        providerRuntime.appendToolOutput(tc.id, rejection);
+                        continue;
+                    }
+                    // Confirmation check for mutate tools.
+                    // confirmationAlwaysRequired tools cannot be bypassed by skipConfirmation.
+                    const needsConfirmation = (0, tools_1.isConfirmationRequired)(tc.name) && (!options?.skipConfirmation || (0, tools_1.isConfirmationAlwaysRequired)(tc.name));
+                    if (needsConfirmation) {
                         let decision = "denied";
                         if (callbacks.onConfirmAction) {
                             decision = await callbacks.onConfirmAction(tc.name, args);
@@ -508,14 +946,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     let success;
                     try {
                         const execToolFn = options?.execTool ?? tools_1.execTool;
-                        toolResult = await execToolFn(tc.name, args, options?.toolContext);
+                        toolResult = await execToolFn(tc.name, args, augmentedToolContext ?? options?.toolContext);
                         success = true;
                     }
                     catch (e) {
                         toolResult = `error: ${e}`;
                         success = false;
                     }
-                    callbacks.onToolEnd(tc.name, argSummary, success);
+                    (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, toolResult, success);
+                    callbacks.onToolEnd(tc.name, (0, tools_1.buildToolResultSummary)(tc.name, args, toolResult, success), success);
                     messages.push({ role: "tool", tool_call_id: tc.id, content: toolResult });
                     providerRuntime.appendToolOutput(tc.id, toolResult);
                 }
@@ -525,6 +964,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             // Abort is not an error — just stop cleanly
             if (signal?.aborted) {
                 stripLastToolCalls(messages);
+                outcome = "aborted";
                 break;
             }
             // Context overflow: trim aggressively and retry once
@@ -542,7 +982,16 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             if (isTransientError(e) && retryCount < MAX_RETRIES) {
                 retryCount++;
                 const delay = RETRY_BASE_MS * Math.pow(2, retryCount - 1);
-                const cause = classifyTransientError(e);
+                let classification;
+                try {
+                    classification = providerRuntime.classifyError(e instanceof Error ? e : /* v8 ignore next -- defensive: errors are always Error instances @preserve */ new Error(String(e)));
+                }
+                catch {
+                    /* v8 ignore next -- defensive: classifyError should not throw @preserve */
+                    classification = classifyTransientError(e);
+                }
+                /* v8 ignore next -- defensive: all classifications have labels @preserve */
+                const cause = TRANSIENT_RETRY_LABELS[classification] ?? classification;
                 callbacks.onError(new Error(`${cause}, retrying in ${delay / 1000}s (${retryCount}/${MAX_RETRIES})...`), "transient");
                 // Wait with abort support
                 const aborted = await new Promise((resolve) => {
@@ -559,21 +1008,42 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 });
                 if (aborted) {
                     stripLastToolCalls(messages);
+                    outcome = "aborted";
                     break;
                 }
                 providerRuntime.resetTurnState(messages);
                 continue;
             }
-            callbacks.onError(e instanceof Error ? e : new Error(String(e)), "terminal");
+            terminalError = e instanceof Error ? e : new Error(String(e));
+            try {
+                terminalErrorClassification = providerRuntime.classifyError(terminalError);
+            }
+            catch {
+                /* v8 ignore next -- defensive: classifyError should not throw @preserve */
+                terminalErrorClassification = "unknown";
+            }
+            /* v8 ignore start — auth-failure guidance: tested via provider error classification tests @preserve */
+            if (terminalErrorClassification === "auth-failure") {
+                const agentName = (0, identity_2.getAgentName)();
+                const currentProvider = providerRuntime.id;
+                callbacks.onError(new Error(`${currentProvider} (${providerRuntime.model}) encountered an error. ` +
+                    `Run \`ouro auth --agent ${agentName} --provider ${currentProvider}\` to refresh credentials, ` +
+                    `or \`ouro auth switch --agent ${agentName} --provider <other>\` to switch providers.`), "terminal");
+            }
+            else {
+                callbacks.onError(terminalError, "terminal");
+            }
+            /* v8 ignore stop */
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 event: "engine.error",
                 trace_id: traceId,
                 component: "engine",
-                message: e instanceof Error ? e.message : String(e),
-                meta: {},
+                message: terminalError.message,
+                meta: { errorClassification: terminalErrorClassification },
             });
             stripLastToolCalls(messages);
+            outcome = "errored";
             done = true;
         }
     }
@@ -582,7 +1052,12 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         trace_id: traceId,
         component: "engine",
         message: "runAgent turn completed",
-        meta: { done },
+        meta: { done, sawPonder, sawQuerySession, sawBridgeManage },
     });
-    return { usage: lastUsage };
+    return {
+        usage: lastUsage,
+        outcome,
+        completion,
+        ...(terminalError ? { error: terminalError, errorClassification: terminalErrorClassification } : {}),
+    };
 }