@ouro.bot/cli 0.1.0-alpha.8 → 0.1.0-alpha.800

package/dist/heart/core.js

@@ -1,96 +1,198 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasToolIntent = exports.buildSystem = exports.toResponsesTools = exports.toResponsesInput = exports.streamResponsesApi = exports.streamChatCompletion = exports.getToolsForChannel = exports.summarizeArgs = exports.execTool = exports.tools = void 0;
+exports.MAX_PROVIDER_ITERATIONS = void 0;
+exports.validateToolCallBatchAtProductionBoundary = validateToolCallBatchAtProductionBoundary;
 exports.createProviderRegistry = createProviderRegistry;
 exports.resetProviderRuntime = resetProviderRuntime;
 exports.getModel = getModel;
 exports.getProvider = getProvider;
 exports.createSummarize = createSummarize;
 exports.getProviderDisplayLabel = getProviderDisplayLabel;
+exports.createHabitCallbackBuffer = createHabitCallbackBuffer;
+exports.resumeApprovalContinuation = resumeApprovalContinuation;
+exports.isChatStyleChannel = isChatStyleChannel;
+exports.buildPonderResult = buildPonderResult;
+exports.isExternalStateQuery = isExternalStateQuery;
+exports.getSettleRetryError = getSettleRetryError;
 exports.stripLastToolCalls = stripLastToolCalls;
-exports.isTransientError = isTransientError;
-exports.classifyTransientError = classifyTransientError;
+exports.repairOrphanedToolCalls = repairOrphanedToolCalls;
 exports.runAgent = runAgent;
 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 tool_arguments_1 = require("../repertoire/tool-arguments");
+const session_events_1 = require("./session-events");
+const friends_1 = require("@ouro.bot/friends");
+const tools_2 = require("../repertoire/tools");
+const streaming_1 = require("./streaming");
 const runtime_1 = require("../nerves/runtime");
+function validateToolCallBatchAtProductionBoundary(calls, activeTools) {
+    const callIdCounts = new Map();
+    for (const call of calls)
+        callIdCounts.set(call.id, (callIdCounts.get(call.id) ?? 0) + 1);
+    return calls.map((call) => {
+        if (callIdCounts.get(call.id) !== 1)
+            return { call, error: "duplicate tool call id" };
+        const advertised = activeTools.find((tool) => tool.function.name === call.name);
+        if (!advertised || !advertised.function.parameters || typeof advertised.function.parameters !== "object")
+            return { call, error: "tool was not advertised with a valid argument schema" };
+        const validated = (0, tool_arguments_1.validateAdvertisedToolArguments)(call.arguments, advertised.function.parameters);
+        return validated.ok ? { call, advertised, validated: validated.value } : { call, error: validated.reason };
+    });
+}
 const context_1 = require("../mind/context");
+const prompt_budget_1 = require("../mind/prompt-budget");
 const prompt_1 = require("../mind/prompt");
-const associative_recall_1 = require("../mind/associative-recall");
+const kept_notes_1 = require("./kept-notes");
+const error_classification_1 = require("./providers/error-classification");
 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;
-function createProviderRegistry() {
-    const factories = {
-        azure: azure_1.createAzureProviderRuntime,
-        anthropic: anthropic_1.createAnthropicProviderRuntime,
-        minimax: minimax_1.createMinimaxProviderRuntime,
-        "openai-codex": openai_codex_1.createOpenAICodexProviderRuntime,
+const github_copilot_1 = require("./providers/github-copilot");
+const openai_compatible_1 = require("./providers/openai-compatible");
+const orientation_frame_1 = require("./orientation-frame");
+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 packets_1 = require("../arc/packets");
+const tool_friction_1 = require("./tool-friction");
+const provider_models_1 = require("./provider-models");
+const provider_credentials_1 = require("./provider-credentials");
+const habit_session_1 = require("./habits/habit-session");
+const provider_attempt_1 = require("./provider-attempt");
+const openai_codex_token_1 = require("./providers/openai-codex-token");
+// Cache only immutable provider construction inputs. ProviderRuntime owns
+// mutable per-turn state (for example Responses nativeInput), so every caller
+// must receive a fresh instance even when its binding fingerprint is unchanged.
+const _providerRuntimeFactories = {
+    human: null,
+    agent: null,
+};
+function providerLaneForFacing(facing) {
+    return facing === "human" ? "outward" : "inner";
+}
+function resolveRuntimeProviderBinding(facing) {
+    const lane = providerLaneForFacing(facing);
+    const config = (0, identity_1.loadAgentConfig)();
+    const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
+    return { lane, provider: facingConfig.provider, model: facingConfig.model };
+}
+async function getProviderRuntimeFingerprint(facing) {
+    const agentName = (0, identity_2.getAgentName)();
+    const binding = resolveRuntimeProviderBinding(facing);
+    const credential = await (0, provider_credentials_1.readProviderCredentialRecord)(agentName, binding.provider);
+    if (!credential.ok) {
+        throw new Error([
+            `${binding.lane} provider ${binding.provider} (${binding.model}) has no credentials for ${agentName}.`,
+            credential.error,
+            `Run \`ouro auth --agent ${agentName} --provider ${binding.provider}\`.`,
+        ].join("\n"));
+    }
+    let record = credential.record;
+    if (binding.provider === "openai-codex") {
+        const refresh = await (0, openai_codex_token_1.refreshOpenAICodexProviderCredentials)(agentName, {
+            record,
+            reason: "runtime-init",
+        });
+        if (refresh.ok) {
+            record = refresh.record;
+        }
+    }
+    return {
+        binding,
+        fingerprint: JSON.stringify({
+            lane: binding.lane,
+            provider: binding.provider,
+            model: binding.model,
+            credentialRevision: record.revision,
+        }),
+        credential: record,
     };
+}
+function createProviderRegistry() {
     return {
-        resolve() {
-            const provider = (0, identity_1.loadAgentConfig)().provider;
-            return factories[provider]();
+        resolve(provider, model, credential) {
+            const providerConfig = { ...credential.config, ...credential.credentials };
+            switch (provider) {
+                case "azure":
+                    return (0, azure_1.createAzureProviderRuntime)(model, providerConfig);
+                case "anthropic":
+                    return (0, anthropic_1.createAnthropicProviderRuntime)(model, providerConfig);
+                case "minimax":
+                    return (0, minimax_1.createMinimaxProviderRuntime)(model, providerConfig);
+                case "openai-codex":
+                    return (0, openai_codex_1.createOpenAICodexProviderRuntime)(model, providerConfig);
+                case "github-copilot":
+                    return (0, github_copilot_1.createGithubCopilotProviderRuntime)(model, providerConfig);
+                case "openai-compatible":
+                case "openai-compatible-gemini":
+                    return (0, openai_compatible_1.createOpenAICompatibleProviderRuntime)(provider, model, providerConfig);
+            }
         },
     };
 }
-function getProviderRuntime() {
-    if (!_providerRuntime) {
-        try {
-            _providerRuntime = createProviderRegistry().resolve();
+async function getProviderRuntime(facing = "human") {
+    let runtime = null;
+    try {
+        const { binding, fingerprint, credential } = await getProviderRuntimeFingerprint(facing);
+        const cached = _providerRuntimeFactories[facing];
+        if (!cached || cached.fingerprint !== fingerprint) {
+            const create = () => createProviderRegistry().resolve(binding.provider, binding.model, credential);
+            runtime = create();
+            _providerRuntimeFactories[facing] = runtime ? { fingerprint, create } : null;
         }
-        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");
+        else {
+            runtime = cached.create();
         }
     }
-    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: { facing },
+        });
+        // eslint-disable-next-line no-console -- pre-boot guard: provider init failure
+        console.error(`\n[fatal] ${msg}\n`);
+        throw error instanceof Error ? error : new Error(msg);
+    }
+    if (!runtime) {
+        const msg = "provider runtime could not be initialized.";
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "engine.provider_init_error",
+            component: "engine",
+            message: msg,
+            meta: { facing },
+        });
+        // eslint-disable-next-line no-console -- pre-boot guard: provider init failure
+        console.error(`\n[fatal] ${msg}\n`);
+        throw new Error(msg);
+    }
+    return 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 cached provider construction inputs so the next access re-reads them
+ * from current config. Runtime instances are always per-caller and are never
+ * shared across turns.
  */
 function resetProviderRuntime() {
-    _providerRuntime = null;
+    _providerRuntimeFactories.human = null;
+    _providerRuntimeFactories.agent = null;
 }
-function getModel() {
-    return getProviderRuntime().model;
+function getModel(facing = "human") {
+    return resolveRuntimeProviderBinding(facing).model;
 }
-function getProvider() {
-    return getProviderRuntime().id;
+function getProvider(facing = "human") {
+    return resolveRuntimeProviderBinding(facing).provider;
 }
-function createSummarize() {
+function createSummarize(facing = "human") {
     return async (transcript, instruction) => {
-        const runtime = getProviderRuntime();
+        const runtime = await getProviderRuntime(facing);
         const client = runtime.client;
         const response = await client.chat.completions.create({
             model: runtime.model,
@@ -103,43 +205,590 @@ function createSummarize() {
         return response.choices?.[0]?.message?.content ?? transcript;
     };
 }
-function getProviderDisplayLabel() {
-    const model = getModel();
+function getProviderDisplayLabel(facing = "human") {
+    const binding = resolveRuntimeProviderBinding(facing);
+    const provider = binding.provider;
+    const model = binding.model || "unknown";
     const providerLabelBuilders = {
-        azure: () => `azure openai (${(0, config_1.getAzureConfig)().deployment || "default"}, model: ${model})`,
+        azure: () => {
+            return `azure openai (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})`,
+        "openai-compatible": () => `z.ai openai-compatible (${model})`,
+        "openai-compatible-gemini": () => `gemini openai-compatible (${model})`,
+    };
+    return providerLabelBuilders[provider]();
+}
+function createCallbackBuffer(callbacks, mode) {
+    const events = [];
+    const bufferedCallbacks = {
+        ...callbacks,
+        onTextChunk: (text) => { events.push({ kind: "text", text }); },
+        onClearText: () => { events.push({ kind: "clear" }); },
+        flushNow: () => { events.push({ kind: "flush" }); },
+    };
+    if (mode === "all") {
+        bufferedCallbacks.onModelStreamStart = () => { events.push({ kind: "stream-start" }); };
+        bufferedCallbacks.onReasoningChunk = (text) => { events.push({ kind: "reasoning", text }); };
+    }
+    return {
+        callbacks: bufferedCallbacks,
+        async flush() {
+            for (const event of events.splice(0)) {
+                switch (event.kind) {
+                    case "stream-start":
+                        callbacks.onModelStreamStart();
+                        break;
+                    case "text":
+                        callbacks.onTextChunk(event.text);
+                        break;
+                    case "reasoning":
+                        callbacks.onReasoningChunk(event.text);
+                        break;
+                    case "clear":
+                        callbacks.onClearText?.();
+                        break;
+                    case "flush":
+                        await callbacks.flushNow?.();
+                        break;
+                }
+            }
+        },
+        discard() {
+            events.splice(0);
+        },
     };
-    return providerLabelBuilders[getProvider()]();
-}
-// 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; } });
-// Re-export streaming functions for backward compat
-var streaming_1 = require("./streaming");
-Object.defineProperty(exports, "streamChatCompletion", { enumerable: true, get: function () { return streaming_1.streamChatCompletion; } });
-Object.defineProperty(exports, "streamResponsesApi", { enumerable: true, get: function () { return streaming_1.streamResponsesApi; } });
-Object.defineProperty(exports, "toResponsesInput", { enumerable: true, get: function () { return streaming_1.toResponsesInput; } });
-Object.defineProperty(exports, "toResponsesTools", { enumerable: true, get: function () { return streaming_1.toResponsesTools; } });
-// 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; } });
-// Re-export kick utilities for backward compat
-var kicks_1 = require("./kicks");
-Object.defineProperty(exports, "hasToolIntent", { enumerable: true, get: function () { return kicks_1.hasToolIntent; } });
-function upsertSystemPrompt(messages, systemText) {
+}
+function createHabitCallbackBuffer(callbacks) {
+    return createCallbackBuffer(callbacks, "all");
+}
+function createFinalOnlyTextBuffer(callbacks) {
+    return createCallbackBuffer(callbacks, "text-only");
+}
+exports.MAX_PROVIDER_ITERATIONS = 8;
+function continuationCallbacks(callbacks, text) {
+    const noop = () => undefined;
+    return {
+        onModelStart: callbacks.onModelStart ?? noop,
+        onModelStreamStart: callbacks.onModelStreamStart ?? noop,
+        onTextChunk: (chunk) => {
+            text.value += chunk;
+            callbacks.onTextChunk?.(chunk);
+        },
+        onReasoningChunk: callbacks.onReasoningChunk ?? noop,
+        onToolStart: callbacks.onToolStart ?? noop,
+        onToolEnd: callbacks.onToolEnd ?? noop,
+        onError: callbacks.onError ?? noop,
+        ...(callbacks.onClearText ? { onClearText: callbacks.onClearText } : {}),
+        ...(callbacks.flushNow ? { flushNow: callbacks.flushNow } : {}),
+        ...(callbacks.settleOutputMode ? { settleOutputMode: callbacks.settleOutputMode } : {}),
+    };
+}
+async function resumeApprovalContinuation(options) {
+    const claim = options.claimContinuation();
+    if (!claim.claimed) {
+        if (claim.interruptedAfterAttempt) {
+            const notice = "the approval continuation was interrupted after provider work began; its outcome is indeterminate and it will not be retried automatically";
+            await options.deliver(notice);
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "engine",
+                event: "engine.approval_continuation_indeterminate",
+                message: "approval continuation interrupted after provider attempt",
+                meta: { approvalId: options.record.approvalId, continuationState: claim.record.continuationState },
+            });
+            return { outcome: "terminal_notice", messages: structuredClone(options.sessionMessages) };
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.approval_continuation_duplicate",
+            message: "approval continuation was already consumed",
+            meta: { approvalId: options.record.approvalId },
+        });
+        return { outcome: "already_continued", messages: structuredClone(options.sessionMessages) };
+    }
+    const materialized = (0, session_events_1.materializeApprovalTerminal)({
+        messages: options.sessionMessages,
+        checkpoint: options.checkpoint,
+        record: options.record,
+        currentSessionRevision: options.currentSessionRevision,
+        materializedApprovalIds: options.materializedApprovalIds,
+    });
+    const recoveredMaterialization = claim.record.continuationState === "materialized";
+    if (!recoveredMaterialization) {
+        await options.persist(materialized.messages);
+        await options.markContinuationMaterialized();
+    }
+    if (!materialized.resumeProvider) {
+        await options.deliver(materialized.directNotice);
+        await options.completeContinuation();
+        return { outcome: "terminal_notice", messages: materialized.messages };
+    }
+    const outward = { value: "" };
+    const callbacks = continuationCallbacks(options.callbacks, outward);
+    await options.markContinuationAttempted();
+    const result = await options.runAgent(materialized.messages, callbacks, options.channel, options.signal, options.runAgentOptions);
+    if (result.outcome === "suspended") {
+        await options.completeContinuation();
+        return { outcome: result.outcome, messages: materialized.messages, suspension: result.suspension };
+    }
+    await options.persist(materialized.messages, result);
+    if (outward.value)
+        await options.deliver(outward.value);
+    await options.completeContinuation();
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.approval_continuation_completed",
+        message: "approval continuation completed through existing provider loop",
+        meta: { approvalId: options.record.approvalId, outcome: result.outcome },
+    });
+    return { outcome: result.outcome, messages: materialized.messages };
+}
+/**
+ * Strip <think>...</think> blocks for the violation-detection check at the
+ * end of a streaming turn. Used to tell legitimate text-only responses
+ * apart from the MiniMax-M2.7 "only thinking, no tool call" violation
+ * shape. Mirrors the more thorough stripThinkBlocks helper in
+ * senses/shared-turn.ts (which is for operator-facing output) — kept
+ * inline here to avoid pulling senses/ into the core module's import graph.
+ */
+function stripThinkBlocksForViolationCheck(input) {
+    let out = input;
+    for (;;) {
+        const open = out.indexOf("<think>");
+        if (open === -1)
+            break;
+        const close = out.indexOf("</think>", open + "<think>".length);
+        if (close === -1) {
+            out = out.slice(0, open);
+            break;
+        }
+        out = out.slice(0, open) + out.slice(close + "</think>".length);
+    }
+    return out.trim();
+}
+function hasFreshPendingWork(options) {
+    const pendingMessages = options?.pendingMessages;
+    if (!Array.isArray(pendingMessages))
+        return false;
+    return pendingMessages.some((message) => typeof message?.content === "string"
+        && message.content.trim().length > 0);
+}
+const HABIT_CONTROL_TOOLS = new Set(["rest", "ponder", "observe"]);
+function highRiskExternalMutation(profile) {
+    if (profile.risk !== "high")
+        return null;
+    const mutates = typeof profile.mutates === "string" ? [profile.mutates] : [...profile.mutates];
+    return mutates.includes("external_side_effect") ? mutates.join(", ") : null;
+}
+function recordBlockedHabitSurfaceAttempts(habitSession, toolCalls, reason) {
+    if (toolCalls.some((call) => call.name !== "send_message" && call.name !== "surface")) {
+        habitSession?.recordError?.(`blocked habit tool batch: ${reason}`);
+    }
+    if (!habitSession?.recordSurfaceAttempt)
+        return;
+    for (const call of toolCalls) {
+        if (call.name !== "send_message" && call.name !== "surface")
+            continue;
+        // The canonical pre-batch schema gate guarantees object arguments here.
+        const args = JSON.parse(call.arguments);
+        habitSession.recordSurfaceAttempt({
+            recipient: String(args.friendId ?? args.delegationId ?? "unknown"),
+            channel: String(args.channel ?? call.name),
+            reason: "blocked",
+            result: "blocked",
+            rawStatus: "blocked",
+            error: reason,
+        });
+    }
+}
+async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins) {
+    if (!habitSession)
+        return null;
+    const granted = new Set(habitSession.toolPolicy.grantedTools);
+    const denied = new Set(habitSession.toolPolicy.deniedTools);
+    for (const call of toolCalls) {
+        if (denied.has(call.name))
+            return `habit tool '${call.name}' is denied by this habit session`;
+        if (HABIT_CONTROL_TOOLS.has(call.name))
+            continue;
+        if (!granted.has(call.name))
+            return `habit tool '${call.name}' was not granted to this habit session`;
+        // The canonical pre-batch schema gate guarantees object arguments here.
+        const args = JSON.parse(call.arguments);
+        const riskProfile = (0, tools_1.riskProfileForToolName)(call.name, args);
+        if (!riskProfile)
+            return `habit tool '${call.name}' does not have a known executable risk profile`;
+        const externalMutation = highRiskExternalMutation(riskProfile);
+        if (externalMutation && call.name !== "send_message" && call.name !== "surface") {
+            return `habit tool '${call.name}' has high-risk executable mutation ${externalMutation}: ${riskProfile.reason}`;
+        }
+        if (call.name === "send_message" || call.name === "surface") {
+            const route = await (0, habit_session_1.resolveHabitReturnRoute)({
+                agentRoot: (0, identity_2.getAgentRoot)(),
+                envelope: habitSession.permissionEnvelope,
+                toolName: call.name,
+                args,
+                friendStore: habitSession.friendStore,
+                delegatedOrigins,
+            });
+            if (!route.allowed)
+                return route.reason;
+        }
+    }
+    return null;
+}
+/** Channels that deliberately support mid-turn delivery expose `speak`.
+ *  BlueBubbles is final-only: its adapter owns one accepted visibility boundary.
+ *  The private runtime has `ponder`; MCP returns synchronously; mail is batch. */
+function isChatStyleChannel(channel) {
+    return (0, friends_1.getChannelCapabilities)(channel).chatStyle;
+}
+function bindCurrentIngressEvidenceLocator(toolList, evidence) {
+    if (!evidence
+        || evidence.schemaVersion !== 1
+        || evidence.provider !== "bluebubbles"
+        || !/^[a-f0-9]{64}$/.test(evidence.captureKeyHash))
+        return toolList;
+    const locator = `capture:${evidence.captureKeyHash}`;
+    return toolList.map((tool) => {
+        if (tool.function.name !== "habit_cancel")
+            return tool;
+        const parameters = tool.function.parameters;
+        const properties = parameters.properties;
+        return {
+            ...tool,
+            function: {
+                ...tool.function,
+                parameters: {
+                    ...parameters,
+                    properties: {
+                        ...properties,
+                        evidence: {
+                            ...properties.evidence,
+                            enum: [locator],
+                        },
+                    },
+                },
+            },
+        };
+    });
+}
+// 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.",
+    rest: "rejected: rest must be the only tool call. finish your work first, then call rest alone.",
+};
+function parseSettlePayload(argumentsText) {
+    const parsed = JSON.parse(argumentsText);
+    // Provider finalization validates settle.answer as a string before this
+    // terminal handling path. Keep this parser focused on projection instead
+    // of carrying an unreachable second shape check.
+    const answer = parsed.answer;
+    const rawIntent = parsed.intent;
+    const intent = rawIntent === "complete" || rawIntent === "blocked" || rawIntent === "direct_reply"
+        ? rawIntent
+        : undefined;
+    return { answer, intent };
+}
+function parsePonderPayload(argumentsText) {
+    // The canonical pre-batch schema gate guarantees a valid object payload.
+    return JSON.parse(argumentsText);
+}
+function parseSuccessCriteria(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const criteria = raw
+        .split("\n")
+        .map((line) => line.replace(/^\s*[-*]\s*/, "").trim())
+        .filter((line) => line.length > 0);
+    return criteria.length > 0 ? criteria : null;
+}
+function parsePacketPayload(raw) {
+    if (typeof raw !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeLegacyPonderArgs(parsed) {
+    if (typeof parsed.thought !== "string" || parsed.thought.trim().length === 0) {
+        return parsed;
+    }
+    return {
+        action: "create",
+        kind: "reflection",
+        objective: parsed.thought.trim(),
+        summary: typeof parsed.say === "string" ? parsed.say.trim() : "",
+        success_criteria: "- preserve the thread for later work",
+        payload_json: "{}",
+    };
+}
+function messageContentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        if (typeof part === "string")
+            return part;
+        if (!part || typeof part !== "object")
+            return "";
+        const maybeText = part.text;
+        return typeof maybeText === "string" ? maybeText : "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function isHarnessCorrectiveUserText(text) {
+    return text.startsWith("no tool was called this turn. you must end every turn")
+        || text.startsWith("private-return acknowledgement claimed work was queued, but no ponder packet was created this turn.")
+        || text.startsWith("this exact request previously reached a tool that is advertised again now.");
+}
+function toolResultIndicatesFailure(content) {
+    const normalized = content.trim().toLowerCase();
+    return normalized.startsWith("error:")
+        || normalized.startsWith("invalid tool arguments:")
+        || normalized.startsWith("unknown:")
+        || normalized.startsWith("relationship authorization required:")
+        || normalized.startsWith("orientation hold:")
+        || normalized.startsWith("commerce authority required:")
+        || normalized.startsWith("blocked:")
+        || normalized.startsWith("rejected:");
+}
+function requiredToolResultSucceeded(name, content, args, validate) {
+    if (toolResultIndicatesFailure(content))
+        return false;
+    return validate?.(name, content, args) ?? true;
+}
+function effectFingerprint(name, rawArguments) {
+    let args;
+    try {
+        const parsed = JSON.parse(rawArguments);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        args = { ...parsed };
+    }
+    catch {
+        return null;
+    }
+    const profile = (0, tools_1.riskProfileForToolName)(name, args);
+    if (!profile || profile.mutates === "none")
+        return null;
+    delete args.expectedVersion;
+    return (0, tool_arguments_1.digestJson)({ name, args });
+}
+function historicalFailedEffectsForExactRepeatedRequest(messages) {
+    const userRequests = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message?.role !== "user")
+            continue;
+        const text = messageContentText(message.content).replace(/\s+/g, " ").trim();
+        if (!text || isHarnessCorrectiveUserText(text))
+            continue;
+        userRequests.push({ index, text });
+    }
+    const current = userRequests.at(-1);
+    if (!current)
+        return [];
+    const prior = userRequests.slice(0, -1).find((request) => request.text === current.text);
+    if (!prior)
+        return [];
+    const effectsByCallId = new Map();
+    const failedEffects = new Map();
+    for (let index = prior.index + 1; index < current.index; index += 1) {
+        const message = messages[index];
+        if (message?.role === "assistant" && Array.isArray(message.tool_calls)) {
+            for (const call of message.tool_calls) {
+                if (call.type !== "function" || !call.id || !call.function.name)
+                    continue;
+                const fingerprint = effectFingerprint(call.function.name, call.function.arguments);
+                if (fingerprint)
+                    effectsByCallId.set(call.id, { name: call.function.name, fingerprint });
+            }
+            continue;
+        }
+        if (message?.role !== "tool")
+            continue;
+        const content = messageContentText(message.content);
+        const effect = effectsByCallId.get(message.tool_call_id);
+        if (!effect)
+            continue;
+        if (toolResultIndicatesFailure(content)) {
+            failedEffects.set(effect.fingerprint, effect);
+        }
+        else {
+            failedEffects.delete(effect.fingerprint);
+        }
+    }
+    return [...failedEffects.values()];
+}
+function latestUserMessageText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role !== "user")
+            continue;
+        const text = messageContentText(message.content).trim();
+        if (isHarnessCorrectiveUserText(text))
+            continue;
+        if (text.length > 0)
+            return text;
+    }
+    return "";
+}
+function truncatePonderDelegatedContent(value) {
+    return value.length > 120 ? `${value.slice(0, 117)}...` : value;
+}
+function buildPonderDelegatedContent(input) {
+    const primary = (input.summary || input.objective).trim();
+    const sourceRequest = input.sourceRequest.trim();
+    if (!sourceRequest || sourceRequest === primary || sourceRequest === input.objective.trim()) {
+        return truncatePonderDelegatedContent(primary);
+    }
+    return truncatePonderDelegatedContent(`${primary}\nsource request: ${sourceRequest}`);
+}
+function looksLikePrivateReturnRequest(text) {
+    const normalized = text.toLowerCase();
+    return /\b(private|privately|private-attention|think|reflect|reflection)\b/.test(normalized)
+        && /\b(return|bring back|come back|surface|report back)\b/.test(normalized);
+}
+function extractPrivateReturnHeldTokens(text) {
+    const tokens = new Set();
+    for (const match of text.matchAll(/\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){2,}\b/g)) {
+        const token = match[0];
+        if (token.length >= 8)
+            tokens.add(token);
+    }
+    return [...tokens];
+}
+function privateReturnAckLeakError(answer, heldTokens) {
+    if (!answer || heldTokens.size === 0)
+        return null;
+    for (const token of heldTokens) {
+        if (answer.includes(token)) {
+            return "private return is queued; do not repeat private markers or requested private-return content in the outward acknowledgement. Say only that the private pass is queued and will return when ready.";
+        }
+    }
+    return null;
+}
+function claimsPrivateReturnQueued(answer) {
+    if (!answer)
+        return false;
+    const normalized = answer.toLowerCase();
+    return /\b(queued|queue|will return|return when|when .*complete|when .*completes|private pass|private runtime completes|inner dialog completes|later)\b/.test(normalized)
+        && /\b(private|inner|return|queued|later)\b/.test(normalized);
+}
+function privateReturnMissingPonderError(input) {
+    if (input.sawPonder)
+        return null;
+    if (!looksLikePrivateReturnRequest(input.latestUserRequest))
+        return null;
+    if (!claimsPrivateReturnQueued(input.answer))
+        return null;
+    return "private-return acknowledgement claimed work was queued, but no ponder packet was created this turn. Call ponder(action=create, ...) first so the return has a packet, return obligation, and private-runtime wake; then settle with only a queued acknowledgement. If you cannot create the packet, ask a blocking clarification without saying it is queued.";
+}
+function activeReturnObligationId(agentName, obligationId) {
+    if (!obligationId)
+        return null;
+    const obligation = (0, obligations_1.readReturnObligation)(agentName, obligationId);
+    return obligation?.status === "queued" || obligation?.status === "running" ? obligationId : null;
+}
+function ponderReturnSessionId(packet) {
+    const origin = packet.origin;
+    if (!origin)
+        return "unknown/unknown/unknown";
+    return `${origin.friendId}/${origin.channel}/${origin.key}`;
+}
+function buildPonderReturnPrivateWakeOptions(input) {
+    const sessionId = ponderReturnSessionId(input.packet);
+    return {
+        reason: "ponder return obligation private attention",
+        triggerSource: "ponder-return-obligation",
+        budgetClass: "interactive",
+        idempotencyKey: `ponder-return:${input.agentName}:${input.returnObligationId}:${input.packet.id}:${sessionId}`,
+        originRefs: [
+            { kind: "tool", id: "ponder" },
+            { kind: "ponder-packet", id: input.packet.id },
+            { kind: "return-obligation", id: input.returnObligationId },
+            { kind: "session", id: sessionId },
+        ],
+    };
+}
+function buildPonderResult(packet, action, returnObligationId) {
+    return JSON.stringify({
+        ok: true,
+        packet_id: packet.id,
+        action,
+        status: packet.status,
+        return_obligation_id: returnObligationId,
+        private_return_contract: returnObligationId
+            ? "queued for private-runtime attention; do not present the requested private answer as complete in this same outward turn. if you answer now, only say the private pass is queued and will return when ready."
+            : null,
+    }, null, 2);
+}
+/** 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.";
+    }
+    return null;
+}
+function upsertSystemPrompt(messages, systemText, protectedSystemMessages = []) {
     const systemMessage = { role: "system", content: systemText };
-    if (messages[0]?.role === "system") {
+    const protectedMessages = new Set(protectedSystemMessages.filter((message) => message.role === "system"));
+    if (messages[0]?.role === "system" && !protectedMessages.has(messages[0])) {
         messages[0] = systemMessage;
     }
     else {
         messages.unshift(systemMessage);
     }
 }
+/**
+ * A prompt refresh failure must not revive any generated text from an older
+ * turn or release. Even the nominally stable region contains actor-scoped trust,
+ * tool, and channel context, so it is not safe to reconstruct. Fail closed to a
+ * neutral base and put the freshly derived trigger first.
+ */
+function repairFallbackSystemPrompt(orientationFrame) {
+    return `${(0, orientation_frame_1.renderOrientationFrame)(orientationFrame)}\n\nYou are a helpful assistant.`;
+}
 // Remove orphan tool_calls from the last assistant message and any
 // trailing tool-result messages that lack a matching tool_call.
 // This keeps the conversation valid after an abort or tool-loop limit.
@@ -160,6 +809,83 @@ function stripLastToolCalls(messages) {
         }
     }
 }
+// Roles that end a tool-result scan. When scanning forward from an assistant
+// message, stop at the next assistant or user message (tool results must be
+// adjacent to their originating assistant message).
+const TOOL_SCAN_BOUNDARY_ROLES = new Set(["assistant", "user"]);
+// Repair orphaned tool_calls and tool results anywhere in the message history.
+// 1. If an assistant message has tool_calls but missing tool results, inject synthetic error results.
+// 2. If a tool result's tool_call_id doesn't match any tool_calls in a preceding assistant message, remove it.
+// This prevents 400 errors from the API after an aborted turn.
+//
+// Position-aware: a tool result is orphaned when its tool_call_id hasn't been
+// defined by an assistant message AT THIS POSITION yet. MiniMax-M2.7 reuses
+// canonical tool_call_ids across turns, so the global-set check that this
+// function used previously kept misordered tool results that MiniMax then
+// rejected with error 2013 ("tool result's tool id not found"). Walking
+// in order matches what MiniMax actually enforces.
+function repairOrphanedToolCalls(messages) {
+    // Pass 1: walk in order, accumulate seen tool_call_ids per-position, and
+    // mark tool results for removal if their id hasn't been defined yet.
+    const seenCallIds = new Set();
+    const removeIndices = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === "assistant") {
+            const asst = msg;
+            if (asst.tool_calls) {
+                for (const tc of asst.tool_calls)
+                    seenCallIds.add(tc.id);
+            }
+            continue;
+        }
+        if (msg.role === "tool") {
+            const toolMsg = msg;
+            if (!seenCallIds.has(toolMsg.tool_call_id)) {
+                removeIndices.push(i);
+            }
+        }
+    }
+    // Splice from the end so earlier indices stay valid.
+    for (let i = removeIndices.length - 1; i >= 0; i--) {
+        messages.splice(removeIndices[i], 1);
+    }
+    // Pass 3: inject synthetic results for tool_calls missing their tool results
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        const asst = msg;
+        if (!asst.tool_calls || asst.tool_calls.length === 0)
+            continue;
+        // Collect tool result IDs that follow this assistant message
+        const resultIds = new Set();
+        for (let j = i + 1; j < messages.length; j++) {
+            const following = messages[j];
+            if (following.role === "tool") {
+                resultIds.add(following.tool_call_id);
+            }
+            else if (TOOL_SCAN_BOUNDARY_ROLES.has(following.role)) {
+                break;
+            }
+        }
+        const missing = asst.tool_calls.filter((tc) => !resultIds.has(tc.id));
+        if (missing.length > 0) {
+            // AX rule: the agent must see what happened. Don't say "interrupted"
+            // — that's vague. Tell them the result was lost, possible causes,
+            // and what to do next.
+            const syntheticResults = missing.map((tc) => ({
+                role: "tool",
+                tool_call_id: tc.id,
+                content: "error: this tool call's result was lost — the previous turn ended before the tool finished (provider rejection, daemon interrupt, or the tool itself errored). if the work needs to be done, retry the tool call now.",
+            }));
+            let insertAt = i + 1;
+            while (insertAt < messages.length && messages[insertAt].role === "tool")
+                insertAt++;
+            messages.splice(insertAt, 0, ...syntheticResults);
+        }
+    }
+}
 // Detect context overflow errors from Azure or MiniMax
 function isContextOverflow(err) {
     if (!(err instanceof Error))
@@ -174,49 +900,72 @@ function isContextOverflow(err) {
         return true;
     return false;
 }
-// Detect transient network errors worth retrying
-function isTransientError(err) {
-    if (!(err instanceof Error))
-        return false;
-    const msg = err.message || "";
-    const code = err.code || "";
-    // Node.js network error codes
-    if (["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "EPIPE",
-        "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "ECONNABORTED"].includes(code))
-        return true;
-    // OpenAI SDK / fetch errors
-    if (msg.includes("fetch failed"))
-        return true;
-    if (msg.includes("network") && !msg.includes("context"))
-        return true;
-    if (msg.includes("ECONNRESET") || msg.includes("ETIMEDOUT"))
-        return true;
-    if (msg.includes("socket hang up"))
-        return true;
-    if (msg.includes("getaddrinfo"))
-        return true;
-    // HTTP 429 / 500 / 502 / 503 / 504
-    const status = err.status;
-    if (status === 429 || status === 500 || status === 502 || status === 503 || status === 504)
-        return true;
-    return false;
+const RETRY_LABELS = {
+    "auth-failure": "auth error",
+    "usage-limit": "usage limit",
+    "rate-limit": "rate limited",
+    "server-error": "server error",
+    "network-error": "network error",
+    "unknown": "error",
+};
+function waitForProviderRetry(delayMs, signal) {
+    if (!signal) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, delayMs);
+        });
+    }
+    return new Promise((resolve, reject) => {
+        let timer;
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new provider_attempt_1.ProviderAttemptAbortError());
+        };
+        timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, delayMs);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function buildAuthFailureGuidance(provider, model, agentName, detail) {
+    const mismatch = (0, provider_models_1.getProviderModelMismatchMessage)(provider, model);
+    const modelLabel = model
+        ? mismatch
+            ? `${provider} [configured model: ${model}]`
+            : `${provider} (${model})`
+        : provider;
+    const lines = [`${modelLabel} authentication failed.`];
+    const cleanDetail = detail.replace(/\s+/g, " ").trim();
+    if (cleanDetail)
+        lines.push(`provider detail: ${cleanDetail.length > 300 ? `${cleanDetail.slice(0, 297)}...` : cleanDetail}`);
+    lines.push("");
+    lines.push("To keep using this provider:");
+    lines.push(`  1. Run \`ouro auth --agent ${agentName} --provider ${provider}\``);
+    if (mismatch) {
+        const defaultModel = (0, provider_models_1.getDefaultModelForProvider)(provider);
+        lines.push("");
+        lines.push("Config warning:");
+        lines.push(`  - ${mismatch}`);
+        lines.push("  - Repair the configured model with:");
+        lines.push(`    \`ouro use --agent ${agentName} --lane outward --provider ${provider} --model ${defaultModel}\``);
+        lines.push(`    \`ouro use --agent ${agentName} --lane inner --provider ${provider} --model ${defaultModel}\``);
+    }
+    lines.push("");
+    lines.push(`To use another configured provider instead, run \`ouro use --agent ${agentName} --lane <outward|inner> --provider <provider> --model <model>\`.`);
+    return lines.join("\n");
 }
-function classifyTransientError(err) {
-    if (!(err instanceof Error))
-        return "unknown error";
-    const status = err.status;
-    if (status === 429)
-        return "rate limited";
-    if (status === 401 || status === 403)
-        return "auth error";
-    if (status && status >= 500)
-        return "server error";
-    return "network error";
-}
-const MAX_RETRIES = 3;
-const RETRY_BASE_MS = 2000;
 async function runAgent(messages, callbacks, channel, signal, options) {
-    const providerRuntime = getProviderRuntime();
+    const generatedMessages = [];
+    const pushGenerated = (...next) => {
+        messages.push(...next);
+        generatedMessages.push(...structuredClone(next));
+    };
+    const facing = (0, friends_1.channelToFacing)(channel);
+    let providerRuntime = options?.providerRuntimeOverride ?? await getProviderRuntime(facing);
     const provider = providerRuntime.id;
     const toolChoiceRequired = options?.toolChoiceRequired ?? true;
     const traceId = options?.traceId;
@@ -237,19 +986,88 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             currentContext = { ...currentContext, friend: freshFriend };
         }
     }
+    const turnOrientationFrame = options?.orientationFrame
+        ?? (channel ? (0, orientation_frame_1.buildOrientationFrame)({ channel, messages }) : undefined);
+    if (options?.requiredPromptEvidence) {
+        let structuralFloor;
+        try {
+            structuralFloor = (0, prompt_budget_1.assessRequiredPromptEvidenceBudget)({
+                messages,
+                requiredPromptEvidence: options.requiredPromptEvidence,
+                provider: providerRuntime.id,
+                model: providerRuntime.model,
+                contextWindowTokens: (0, config_1.getContextConfig)().maxTokens,
+            });
+        }
+        catch (error) {
+            const invalidEvidenceError = error instanceof Error ? error : new Error(String(error));
+            callbacks.onError(invalidEvidenceError, "terminal");
+            options.captureGeneratedMessages?.([]);
+            (0, runtime_1.emitNervesEvent)({
+                event: "engine.turn_end",
+                trace_id: traceId,
+                component: "engine",
+                message: "runAgent turn completed",
+                meta: { done: true, sawPonder: false, sawQuerySession: false, sawBridgeManage: false },
+            });
+            return {
+                outcome: "errored",
+                error: invalidEvidenceError,
+                errorClassification: "unknown",
+            };
+        }
+        if (structuralFloor.status === "required_evidence_over_budget") {
+            const budgetError = new Error(`required_evidence_over_budget: required current-turn evidence needs ${structuralFloor.estimatedTokens} tokens but the provider input limit is ${structuralFloor.budget.inputTokenLimit}`);
+            callbacks.onError(budgetError, "terminal");
+            options.captureGeneratedMessages?.([]);
+            (0, runtime_1.emitNervesEvent)({
+                event: "engine.turn_end",
+                trace_id: traceId,
+                component: "engine",
+                message: "runAgent turn completed",
+                meta: { done: true, sawPonder: false, sawQuerySession: false, sawBridgeManage: false },
+            });
+            return {
+                outcome: "errored",
+                error: budgetError,
+                errorClassification: "unknown",
+            };
+        }
+    }
     // Refresh system prompt at start of each turn when channel is provided.
-    // If refresh fails, keep existing system prompt (or inject a minimal safe fallback)
-    // so turn execution remains consistent and non-fatal.
+    // If refresh fails, retain only a recognised stable prefix (or inject a
+    // minimal safe fallback) so stale dynamic state cannot regain authority.
+    let structuredSystemPrompt;
     if (channel) {
         try {
-            const refreshed = await (0, prompt_1.buildSystem)(channel, options, currentContext);
-            upsertSystemPrompt(messages, refreshed);
+            const buildSystemOptions = {
+                ...options,
+                relationshipContextScopes: options?.toolContext?.relationshipAuthorization?.authorizedContextScopes,
+                relationshipProfileId: options?.toolContext?.relationshipAuthorization?.profileId,
+                relationshipToolNames: options?.toolContext?.relationshipAuthorization?.advertisedToolNames,
+                orientationFrame: turnOrientationFrame,
+                resumePriorWork: options?.resumePriorWork === true,
+                providerCapabilities: providerRuntime.capabilities,
+                supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+            };
+            const refreshed = await (0, prompt_1.buildSystem)(channel, buildSystemOptions, currentContext);
+            structuredSystemPrompt = refreshed;
+            upsertSystemPrompt(messages, (0, prompt_1.flattenSystemPrompt)(refreshed), [
+                ...(options?.promptOnlyEvidenceMessages ?? []),
+                ...(options?.requiredPromptEvidence?.verifiedPredecessorMessage
+                    ? [options.requiredPromptEvidence.verifiedPredecessorMessage]
+                    : []),
+            ]);
         }
         catch (error) {
             const hadExistingSystemPrompt = messages[0]?.role === "system" && typeof messages[0].content === "string";
-            const existingSystemText = hadExistingSystemPrompt ? messages[0].content : undefined;
-            const fallback = existingSystemText ?? "You are a helpful assistant.";
-            upsertSystemPrompt(messages, fallback);
+            const fallback = repairFallbackSystemPrompt(turnOrientationFrame);
+            upsertSystemPrompt(messages, fallback, [
+                ...(options?.promptOnlyEvidenceMessages ?? []),
+                ...(options?.requiredPromptEvidence?.verifiedPredecessorMessage
+                    ? [options.requiredPromptEvidence.verifiedPredecessorMessage]
+                    : []),
+            ]);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
                 event: "mind.step_error",
@@ -264,261 +1082,1362 @@ 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;
+    if (channel && options?.skipKeptNotes !== true) {
+        await (0, kept_notes_1.injectKeptNotes)(messages, {
+            channel,
+            friend: currentContext?.friend,
+            judge: async (input) => (0, kept_notes_1.createKeptNotesJudge)(await getProviderRuntime("agent"), signal)(input),
+            signal,
+            traceId,
+        });
+    }
     let done = false;
     let lastUsage;
     let overflowRetried = false;
-    let retryCount = 0;
+    let outcome = "settled";
+    let completion;
+    let suspension;
+    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 privateReturnHeldTokens = new Set();
+    // Once-per-turn flag for the fresh-work rest gate. Without this, an agent
+    // that called rest, was told "fresh work arrived", processed the items,
+    // and called rest again would get the same message forever — the gate
+    // condition is read from the turn-start snapshot of pendingMessages,
+    // which doesn't update mid-turn. The agent only needs to be told once;
+    // after that, repeated rest attempts mean they've acknowledged.
+    let freshWorkGateFired = false;
+    // Counter for no-tool-call violations. MiniMax reasoning models occasionally
+    // emit only a <think>...</think> block and stop, without any tool call — even
+    // when tool_choice is set to "required". Private-return requests also need
+    // a hard no-tool guard: a text-only "queued" acknowledgement is false unless
+    // a ponder packet created the return obligation in this turn.
+    let noToolCallRetries = 0;
+    const NO_TOOL_CALL_MAX_RETRIES = 2;
+    let unresolvedHistoricalEffects = historicalFailedEffectsForExactRepeatedRequest(messages);
+    let historicalToolFailureRetries = 0;
+    let providerIterations = 0;
+    const requiredToolCallNames = [...new Set(options?.requiredToolCalls?.names ?? [])];
+    const dispatchedRequiredToolCalls = new Set();
+    const requiredCorrectionMarker = Symbol("requiredCorrection");
+    const messagesWithoutRequiredCorrections = () => messages.filter((message) => message[requiredCorrectionMarker] !== true);
+    const removeRequiredCorrections = () => {
+        messages.splice(0, messages.length, ...messagesWithoutRequiredCorrections());
+    };
+    const pendingRequiredToolCalls = () => {
+        const missing = requiredToolCallNames.filter((name) => !dispatchedRequiredToolCalls.has(name));
+        return missing.length > 0
+            ? { missing, message: `${options.requiredToolCalls.retryMessage} Missing required tool calls: ${missing.join(", ")}.` }
+            : null;
+    };
+    const queueRequiredCorrection = (message, limitContext) => {
+        if (providerIterations >= exports.MAX_PROVIDER_ITERATIONS)
+            throw new Error(`provider iteration limit exhausted at response ${exports.MAX_PROVIDER_ITERATIONS} ${limitContext}`);
+        const correction = {
+            role: "user",
+            content: message,
+            [requiredCorrectionMarker]: true,
+        };
+        messages.push(correction);
+        providerRuntime.resetTurnState(messages);
+    };
+    const toolLoopState = (0, tool_loop_1.createToolLoopState)();
+    const toolFrictionLedger = (0, tool_friction_1.createToolFrictionLedger)();
+    const finishTerminalProviderError = (error, classification) => {
+        terminalError = error;
+        terminalErrorClassification = classification;
+        /* 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(buildAuthFailureGuidance(currentProvider, providerRuntime.model, agentName, terminalError.message)), "terminal");
+        }
+        else {
+            callbacks.onError(terminalError, "terminal");
+        }
+        /* v8 ignore stop */
+        const errorDetails = (0, error_classification_1.extractProviderErrorDetails)(terminalError);
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "engine.error",
+            trace_id: traceId,
+            component: "engine",
+            message: terminalError.message,
+            meta: {
+                provider: providerRuntime.id,
+                model: providerRuntime.model,
+                errorClassification: terminalErrorClassification,
+                ...(errorDetails.status !== undefined ? { httpStatus: errorDetails.status } : {}),
+                ...(errorDetails.bodyExcerpt ? { bodyExcerpt: errorDetails.bodyExcerpt } : {}),
+                summary: (0, error_classification_1.summarizeProviderError)(terminalError, terminalErrorClassification, providerRuntime.id, providerRuntime.model),
+            },
+        });
+        stripLastToolCalls(messages);
+        stripLastToolCalls(generatedMessages);
+        outcome = "errored";
+        done = true;
+    };
     // Prevent MaxListenersExceeded warning — each iteration adds a listener
     try {
         require("events").setMaxListeners(50, signal);
     }
     catch { /* unsupported */ }
     const toolPreferences = currentContext?.friend?.toolPreferences;
-    const baseTools = (0, tools_1.getToolsForChannel)(channel ? (0, channel_1.getChannelCapabilities)(channel) : undefined, toolPreferences && Object.keys(toolPreferences).length > 0 ? toolPreferences : undefined);
+    const unboundBaseTools = options?.tools ?? (0, tools_1.getToolsForChannel)(channel ? (0, friends_1.getChannelCapabilities)(channel) : undefined, toolPreferences && Object.keys(toolPreferences).length > 0 ? toolPreferences : undefined, currentContext, providerRuntime.capabilities, options?.mcpManager, providerRuntime.model);
+    const relationshipToolNames = options?.toolContext?.relationshipAuthorization?.advertisedToolNames;
+    const relationshipScopedTools = relationshipToolNames
+        ? unboundBaseTools.filter((tool) => relationshipToolNames.includes(tool.function.name))
+        : unboundBaseTools;
+    const baseTools = bindCurrentIngressEvidenceLocator(relationshipScopedTools, options?.toolContext?.currentIngressEvidence);
+    // Augment tool context with reasoning effort controls from provider
+    const baseToolContext = options?.toolContext
+        ?? (turnOrientationFrame ? { signin: async () => undefined, orientationFrame: turnOrientationFrame } : undefined);
+    const habitSession = options?.habitSession ?? baseToolContext?.habitSession;
+    const augmentedToolContext = baseToolContext
+        ? {
+            ...baseToolContext,
+            supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+            setReasoningEffort: (level) => { currentReasoningEffort = level; },
+            activeWorkFrame: options?.activeWorkFrame,
+            orientationFrame: turnOrientationFrame ?? baseToolContext.orientationFrame,
+            ...(habitSession ? { habitSession } : {}),
+        }
+        : habitSession
+            ? {
+                signin: async () => undefined,
+                habitSession,
+                supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+                setReasoningEffort: (level) => { currentReasoningEffort = level; },
+            }
+            : 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;
-        const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
-        if (steeringFollowUps.length > 0) {
-            for (const followUp of steeringFollowUps) {
-                messages.push({ role: "user", content: followUp.text });
+    try {
+        while (!done) {
+            // Channel-based tool filtering:
+            // - Private runtime: exclude send_message (delivery via surface), observe (no one to observe)
+            // - All outward channels (1:1, group, reaction): 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).
+            // Private runtime 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 isPrivateRuntimeChannel = channel === "inner";
+            const privateRuntimeHabitCanSendMessage = isPrivateRuntimeChannel
+                && habitSession?.toolPolicy.outwardMessagingAllowed === true
+                && habitSession.toolPolicy.grantedTools.includes("send_message");
+            const privateRuntimeHabitCanSurface = isPrivateRuntimeChannel
+                && (!habitSession || (habitSession.toolPolicy.outwardMessagingAllowed === true
+                    && habitSession.toolPolicy.grantedTools.includes("surface")));
+            const filteredBaseTools = isPrivateRuntimeChannel
+                ? baseTools.filter((t) => privateRuntimeHabitCanSendMessage || t.function.name !== "send_message")
+                : baseTools;
+            const unscopedOrdinaryActiveTools = [
+                ...filteredBaseTools,
+                ...(augmentedToolContext?.noSend === true ? [] : [tools_1.ponderTool]),
+                ...(isPrivateRuntimeChannel && privateRuntimeHabitCanSurface ? [tools_2.surfaceToolDef] : []),
+                ...(isPrivateRuntimeChannel ? [tools_1.restTool] : []),
+                ...(!isPrivateRuntimeChannel ? [tools_1.observeTool] : []),
+                ...(!isPrivateRuntimeChannel ? [tools_1.settleTool] : []),
+                ...(isChatStyleChannel(channel ?? "") ? [tools_1.speakTool] : []),
+            ];
+            const ordinaryActiveTools = relationshipToolNames
+                ? unscopedOrdinaryActiveTools.filter((tool) => relationshipToolNames.includes(tool.function.name))
+                : unscopedOrdinaryActiveTools;
+            const candidateActiveTools = options?.toolProfile === "sanctuary-health-private"
+                ? (() => {
+                    const sendTools = baseTools.filter((tool) => tool.function.name === "send_message");
+                    if (channel !== "inner" || sendTools.length !== 1 || baseTools.length !== 1) {
+                        throw new Error("sanctuary-health-private requires inner channel with exactly one canonical send_message definition");
+                    }
+                    return [sendTools[0], tools_1.restTool];
+                })()
+                : ordinaryActiveTools;
+            const candidateToolNames = new Set(candidateActiveTools.map((tool) => tool.function.name));
+            const unadvertisedRequiredTool = requiredToolCallNames.find((name) => !candidateToolNames.has(name));
+            if (unadvertisedRequiredTool) {
+                (0, runtime_1.emitNervesEvent)({ level: "error", component: "engine", event: "engine.required_tool_unadvertised", message: "required tool is not advertised for the active channel", meta: { toolName: unadvertisedRequiredTool, channel: String(channel) } });
+                throw new Error(`required tool is not advertised for this channel: ${unadvertisedRequiredTool}`);
             }
-            providerRuntime.resetTurnState(messages);
-        }
-        // Yield so pending I/O (stdin Ctrl-C) can be processed between iterations
-        await new Promise((r) => setImmediate(r));
-        if (signal?.aborted)
-            break;
-        try {
-            callbacks.onModelStart();
-            const result = await providerRuntime.streamTurn({
-                messages,
-                activeTools,
-                callbacks,
-                signal,
-                traceId,
-                toolChoiceRequired,
-            });
-            // Track usage from the latest API call
-            if (result.usage)
-                lastUsage = result.usage;
-            retryCount = 0; // reset on success
-            // SHARED: build CC-format assistant message from TurnResult
-            const msg = {
-                role: "assistant",
-            };
-            if (result.content)
-                msg.content = result.content;
-            if (result.toolCalls.length)
-                msg.tool_calls = result.toolCalls.map((tc) => ({
-                    id: tc.id,
-                    type: "function",
-                    function: { name: tc.name, arguments: tc.arguments },
-                }));
-            // Store reasoning items from the API response on the assistant message
-            // so they persist through session save/load and can be restored in toResponsesInput
-            const reasoningItems = result.outputItems.filter((item) => "type" in item && item.type === "reasoning");
-            if (reasoningItems.length > 0) {
-                msg._reasoning_items = reasoningItems;
+            const forcedHistoricalToolNames = new Set(unresolvedHistoricalEffects
+                .map((effect) => effect.name)
+                .filter((name) => candidateToolNames.has(name)));
+            const forcingHistoricalEffect = forcedHistoricalToolNames.size > 0;
+            const activeTools = forcingHistoricalEffect
+                ? candidateActiveTools.filter((tool) => forcedHistoricalToolNames.has(tool.function.name))
+                : candidateActiveTools;
+            const activeToolNames = new Set(activeTools.map((tool) => tool.function.name));
+            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 });
+                }
+                providerRuntime.resetTurnState(messages);
             }
-            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;
-                // }
-                messages.push(msg);
-                done = true;
+            // Yield so pending I/O (stdin Ctrl-C) can be processed between iterations
+            await new Promise((r) => setImmediate(r));
+            if (signal?.aborted) {
+                outcome = "aborted";
+                break;
             }
-            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 turnCallbackBufferRef = { current: null };
+                const callProviderTurn = async () => {
+                    callbacks.onModelStart();
+                    turnCallbackBufferRef.current = habitSession
+                        ? createHabitCallbackBuffer(callbacks)
+                        : callbacks.settleOutputMode === "final_only"
+                            ? createFinalOnlyTextBuffer(callbacks)
+                            : null;
                     try {
-                        const parsed = JSON.parse(result.toolCalls[0].arguments);
-                        if (typeof parsed === "string") {
-                            answer = parsed;
+                        const promptBudget = (0, prompt_budget_1.applyPromptBudget)({
+                            messages,
+                            requiredPromptEvidence: options?.requiredPromptEvidence,
+                            provider: providerRuntime.id,
+                            model: providerRuntime.model,
+                            contextWindowTokens: (0, config_1.getContextConfig)().maxTokens,
+                        });
+                        if (promptBudget.status !== "within_budget") {
+                            messages.splice(0, messages.length, ...promptBudget.messages);
+                            providerRuntime.resetTurnState(messages);
+                        }
+                        return await providerRuntime.streamTurn({
+                            messages,
+                            activeTools,
+                            callbacks: turnCallbackBufferRef.current?.callbacks ?? callbacks,
+                            signal,
+                            traceId,
+                            toolChoiceRequired: forcingHistoricalEffect || toolChoiceRequired,
+                            reasoningEffort: currentReasoningEffort,
+                            eagerSettleStreaming: true,
+                            systemPrompt: structuredSystemPrompt,
+                        });
+                    }
+                    catch (error) {
+                        turnCallbackBufferRef.current?.discard();
+                        turnCallbackBufferRef.current = null;
+                        if (signal?.aborted)
+                            throw new provider_attempt_1.ProviderAttemptAbortError();
+                        throw error;
+                    }
+                };
+                const callProviderTurnWithOverflowRecovery = async () => {
+                    try {
+                        return await callProviderTurn();
+                    }
+                    catch (error) {
+                        if (error instanceof provider_attempt_1.ProviderAttemptAbortError)
+                            throw error;
+                        if (isContextOverflow(error) && !overflowRetried) {
+                            overflowRetried = true;
+                            stripLastToolCalls(messages);
+                            stripLastToolCalls(generatedMessages);
+                            const { maxTokens, contextMargin } = (0, config_1.getContextConfig)();
+                            const trimmed = (0, context_1.trimMessages)(messages, maxTokens, contextMargin, maxTokens * 2);
+                            const requiredEvidence = options?.requiredPromptEvidence;
+                            const requiredMessages = new Set([
+                                ...(requiredEvidence?.verifiedPredecessorMessage ? [requiredEvidence.verifiedPredecessorMessage] : []),
+                                ...(requiredEvidence?.currentUserMessage ? [requiredEvidence.currentUserMessage] : []),
+                            ]);
+                            const trimmedMessages = new Set(trimmed);
+                            const overflowRetryMessages = requiredMessages.size === 0
+                                ? trimmed
+                                : messages.filter((message) => trimmedMessages.has(message) || requiredMessages.has(message));
+                            messages.splice(0, messages.length, ...overflowRetryMessages);
+                            providerRuntime.resetTurnState(messages);
+                            callbacks.onError(new Error("context trimmed, retrying..."), "transient");
+                            return callProviderTurn();
+                        }
+                        throw error;
+                    }
+                };
+                const attempt = await (0, provider_attempt_1.runProviderAttempt)({
+                    operation: "turn",
+                    provider: providerRuntime.id,
+                    model: providerRuntime.model,
+                    run: callProviderTurnWithOverflowRecovery,
+                    classifyError: (error) => providerRuntime.classifyError(error),
+                    onRetry: async (record, maxAttempts) => {
+                        const delayMs = record.delayMs;
+                        const seconds = delayMs / 1000;
+                        const cause = RETRY_LABELS[record.classification];
+                        try {
+                            if (record.provider === "openai-codex" && record.classification === "auth-failure") {
+                                await (0, openai_codex_token_1.refreshOpenAICodexProviderCredentials)((0, identity_2.getAgentName)(), {
+                                    force: true,
+                                    reason: "turn-auth-failure",
+                                });
+                            }
+                            await (0, provider_credentials_1.refreshProviderCredentialPool)((0, identity_2.getAgentName)(), {
+                                preserveCachedOnFailure: true,
+                                providers: [record.provider],
+                            });
+                            _providerRuntimeFactories[facing] = null;
+                            providerRuntime = await getProviderRuntime(facing);
+                            providerRuntime.resetTurnState(messages);
+                        }
+                        catch (refreshError) {
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.provider_retry_refresh_failed",
+                                message: "provider credential refresh failed during retry",
+                                meta: { provider: record.provider, model: record.model, reason: refreshError instanceof Error ? refreshError.message : String(refreshError) },
+                            });
+                        }
+                        callbacks.onError(new Error(`${cause}, retrying in ${seconds}s (${record.attempt}/${maxAttempts})...`), "transient");
+                    },
+                    sleep: async (delayMs) => {
+                        await waitForProviderRetry(delayMs, signal);
+                        providerRuntime.resetTurnState(messages);
+                    },
+                });
+                if (!attempt.ok) {
+                    finishTerminalProviderError(attempt.error, attempt.classification);
+                    continue;
+                }
+                const result = attempt.value;
+                providerIterations += 1;
+                if (providerIterations === exports.MAX_PROVIDER_ITERATIONS && result.toolCalls.length > 0) {
+                    throw new Error(`provider iteration limit exhausted at response ${exports.MAX_PROVIDER_ITERATIONS} before tool execution`);
+                }
+                const streamCallbackBuffer = turnCallbackBufferRef.current;
+                turnCallbackBufferRef.current = null;
+                if (result.settleFinalization && !result.settleFinalization.ok) {
+                    // A completed settle payload is terminal provider output, not a prompt
+                    // for another model turn. Retractable callbacks have already cleared;
+                    // core-owned callback buffers must be discarded before surfacing the exact
+                    // parser failure through the ordinary terminal-error path.
+                    streamCallbackBuffer?.discard();
+                    finishTerminalProviderError(new Error(result.settleFinalization.errorCode), "unknown");
+                    continue;
+                }
+                // Track usage from the latest API call
+                if (result.usage)
+                    lastUsage = result.usage;
+                // SHARED: build CC-format assistant message from TurnResult
+                const msg = {
+                    role: "assistant",
+                };
+                // Persist assistant content WITHOUT inline <think>...</think> blocks.
+                // Reasoning content already routed through onReasoningChunk for live
+                // surfacing and persisted separately as `_reasoning_items` for
+                // providers that support a reasoning channel; saving it inline AND
+                // alongside tool_calls causes MiniMax to reject the replayed turn
+                // with "tool result's tool id not found" (error code 2013) because
+                // it can't reconcile reasoning-with-tools in the same assistant
+                // message. Strip aggressively at persist so the next replay is
+                // clean; preserve the original reasoning trace on the message via
+                // `_inline_reasoning` so debug/audit paths can still see it.
+                if (result.content) {
+                    const stripped = stripThinkBlocksForViolationCheck(result.content);
+                    if (stripped.length > 0)
+                        msg.content = stripped;
+                    if (stripped.length !== result.content.length) {
+                        msg._inline_reasoning = result.content;
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "info",
+                            component: "engine",
+                            event: "engine.inline_reasoning_stripped",
+                            message: "stripped inline <think> blocks from persisted assistant message; preserved on _inline_reasoning",
+                            meta: {
+                                provider: providerRuntime.id,
+                                model: providerRuntime.model,
+                                originalLength: result.content.length,
+                                strippedLength: stripped.length,
+                            },
+                        });
+                    }
+                }
+                if (result.toolCalls.length)
+                    msg.tool_calls = result.toolCalls.map((tc) => ({
+                        id: tc.id,
+                        type: "function",
+                        function: { name: tc.name, arguments: tc.arguments },
+                    }));
+                // Store reasoning items from the API response on the assistant message
+                // so they persist through session save/load and can be restored in toResponsesInput
+                const reasoningItems = result.outputItems.filter((item) => "type" in item && item.type === "reasoning");
+                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";
+                }
+                // Detect the MiniMax "only-thinking, no tool call" violation: no tool
+                // calls returned, and the content is empty after stripping
+                // <think>...</think> blocks. This is a narrow check — legitimate
+                // content-only responses (text without think tags, or text outside
+                // think tags) still flow through the original "no tool calls →
+                // accept as-is" path so existing channels and tests are unaffected.
+                const onlyThinkContent = !result.toolCalls.length
+                    && typeof result.content === "string"
+                    && stripThinkBlocksForViolationCheck(result.content).length === 0
+                    && result.content.length > 0;
+                const privateReturnTextAckRetryError = !result.toolCalls.length
+                    ? privateReturnMissingPonderError({
+                        latestUserRequest: latestUserMessageText(messages),
+                        answer: stripThinkBlocksForViolationCheck(result.content),
+                        sawPonder,
+                    })
+                    : null;
+                if (!result.toolCalls.length) {
+                    if (forcingHistoricalEffect) {
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        const retryableHistoricalTools = [...forcedHistoricalToolNames];
+                        if (historicalToolFailureRetries >= NO_TOOL_CALL_MAX_RETRIES) {
+                            const blockedAnswer = `I could not complete the unresolved ${retryableHistoricalTools.join(", ")} effect because the provider repeatedly returned no tool call. I did not treat the requested change as complete.`;
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.historical_tool_failure_retry",
+                                message: "unresolved historical effect exhausted deterministic tool-call retries; failing closed",
+                                meta: { provider: providerRuntime.id, model: providerRuntime.model, toolNames: retryableHistoricalTools, cap: NO_TOOL_CALL_MAX_RETRIES },
+                            });
+                            msg.content = blockedAnswer;
+                            pushGenerated(msg);
+                            callbacks.onTextChunk(blockedAnswer);
+                            completion = { answer: blockedAnswer, intent: "blocked" };
+                            outcome = "blocked";
+                            done = true;
+                            continue;
+                        }
+                        historicalToolFailureRetries += 1;
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.historical_tool_failure_retry",
+                            message: "unresolved historical effect returned no tool call; forcing another exact-effect attempt",
+                            meta: {
+                                provider: providerRuntime.id,
+                                model: providerRuntime.model,
+                                toolNames: retryableHistoricalTools,
+                                attempt: historicalToolFailureRetries,
+                                cap: NO_TOOL_CALL_MAX_RETRIES,
+                            },
+                        });
+                        pushGenerated(msg);
+                        messages.push({
+                            role: "user",
+                            content: `this exact request previously reached a tool that is advertised again now. Its unresolved historical effect is through ${retryableHistoricalTools.join(", ")}. Only that tool is available now. Read current state if needed, then retry the exact failed effect. Do not report completion until the effect succeeds.`,
+                        });
+                        continue;
+                    }
+                    const requiredToolCallsGate = pendingRequiredToolCalls();
+                    if (requiredToolCallsGate) {
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        queueRequiredCorrection(requiredToolCallsGate.message, "before required tool calls completed");
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.required_tool_calls_pending",
+                            message: "terminal response rejected until required tool handlers dispatch",
+                            meta: { missingToolNames: requiredToolCallsGate.missing },
+                        });
+                        continue;
+                    }
+                    const requiredAnswerRejection = options?.requiredToolCalls?.validateTerminalAnswer?.(String(msg.content ?? ""));
+                    if (requiredAnswerRejection) {
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        queueRequiredCorrection(requiredAnswerRejection, "before required terminal answer validation completed");
+                        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.required_tool_answer_rejected", message: "unsupported terminal answer rejected after required reads", meta: { answerLength: String(msg.content ?? "").length } });
+                        continue;
+                    }
+                    if (privateReturnTextAckRetryError) {
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        if (noToolCallRetries < NO_TOOL_CALL_MAX_RETRIES) {
+                            noToolCallRetries++;
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.no_tool_call_retry",
+                                message: "model returned a text-only private-return acknowledgement without ponder; retrying with corrective nudge",
+                                meta: {
+                                    attempt: noToolCallRetries,
+                                    cap: NO_TOOL_CALL_MAX_RETRIES,
+                                    provider: providerRuntime.id,
+                                    model: providerRuntime.model,
+                                    reason: "private_return_missing_ponder",
+                                    contentLength: result.content.length,
+                                },
+                            });
+                            pushGenerated(msg);
+                            messages.push({
+                                role: "user",
+                                content: `${privateReturnTextAckRetryError} Emit the ponder(action=create, ...) tool call now, or ask a blocking clarification without saying the private work is queued.`,
+                            });
+                            continue;
+                        }
+                        const blockedAnswer = "I could not start the private pass. No private-attention packet was created, so no return work was queued.";
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "error",
+                            component: "engine",
+                            event: "engine.private_return_missing_ponder_blocked",
+                            message: "private-return text acknowledgement skipped ponder through the retry cap; failing closed",
+                            meta: {
+                                cap: NO_TOOL_CALL_MAX_RETRIES,
+                                provider: providerRuntime.id,
+                                model: providerRuntime.model,
+                                contentLength: result.content.length,
+                            },
+                        });
+                        msg.content = blockedAnswer;
+                        pushGenerated(msg);
+                        callbacks.onTextChunk(blockedAnswer);
+                        completion = { answer: blockedAnswer, intent: "blocked" };
+                        outcome = "blocked";
+                        done = true;
+                        continue;
+                    }
+                    if (onlyThinkContent && toolChoiceRequired && noToolCallRetries < NO_TOOL_CALL_MAX_RETRIES) {
+                        streamCallbackBuffer?.discard();
+                        // Provider-level violation: tool_choice was required, model emitted
+                        // only a <think>...</think> block (or empty content) with no tool
+                        // call. Retry with a corrective nudge up to NO_TOOL_CALL_MAX_RETRIES
+                        // times. After cap, accept as-is (the readback path strips think
+                        // tags and surfaces a clear diagnostic).
+                        noToolCallRetries++;
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.no_tool_call_retry",
+                            message: "model returned only <think> content with no tool call despite tool_choice=required; retrying with corrective nudge",
+                            meta: {
+                                attempt: noToolCallRetries,
+                                cap: NO_TOOL_CALL_MAX_RETRIES,
+                                provider: providerRuntime.id,
+                                model: providerRuntime.model,
+                                contentLength: result.content.length,
+                            },
+                        });
+                        pushGenerated(msg);
+                        messages.push({
+                            role: "user",
+                            content: isPrivateRuntimeChannel
+                                ? augmentedToolContext?.noSend === true
+                                    ? "no tool was called this turn. this is an immutable no-send turn; call rest now without creating a continuation."
+                                    : "no tool was called this turn. you must end every turn by calling rest (or surface, ponder, observe). emit the tool call now."
+                                : "no tool was called this turn. you must end every turn by calling settle with your answer (or ponder/observe). emit the tool call now.",
+                        });
+                        continue;
+                    }
+                    // Legitimate text-only response, or cap reached — accept as-is.
+                    await streamCallbackBuffer?.flush();
+                    pushGenerated(msg);
+                    done = true;
+                }
+                else {
+                    // Reset the retry counter on any successful tool call.
+                    noToolCallRetries = 0;
+                    const preCallMessages = structuredClone(messagesWithoutRequiredCorrections().filter((message) => message.role !== "system"));
+                    const validatedCalls = validateToolCallBatchAtProductionBoundary(result.toolCalls, activeTools);
+                    const invalidCall = validatedCalls.find((entry) => "error" in entry);
+                    if (invalidCall) {
+                        await streamCallbackBuffer?.flush();
+                        pushGenerated(msg);
+                        const unadvertisedCall = validatedCalls.find((entry) => !activeToolNames.has(entry.call.name));
+                        for (const entry of validatedCalls) {
+                            const detail = "error" in entry ? entry.error : "another call in this batch had invalid arguments";
+                            const rejection = unadvertisedCall
+                                ? `rejected: ${entry.call.name} was not advertised for this channel; no handler was executed.`
+                                : `invalid tool arguments: ${detail}`;
+                            pushGenerated({ role: "tool", tool_call_id: entry.call.id, content: rejection });
+                            providerRuntime.appendToolOutput(entry.call.id, rejection);
+                            options?.toolBoundaryObserver?.({
+                                name: entry.call.name,
+                                reason: activeToolNames.has(entry.call.name) ? "invalid_arguments" : "profile_excluded",
+                                globallyResolvable: typeof (0, tools_1.resolveToolDefinition)(entry.call.name)?.handler === "function",
+                                invoked: false,
+                                sideEffect: false,
+                            });
                         }
-                        else if (parsed.answer != null) {
-                            answer = parsed.answer;
+                        if (unadvertisedCall) {
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.unadvertised_tool_blocked",
+                                message: "blocked an unadvertised tool call before batch execution",
+                                meta: { channel: String(channel), toolName: unadvertisedCall.call.name },
+                            });
                         }
-                        // else: valid JSON but no answer field — answer stays undefined (retry)
+                        else {
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.tool_arguments_rejected",
+                                message: "tool batch rejected before execution because arguments were invalid",
+                                meta: { toolCallId: invalidCall.call.id, toolName: invalidCall.call.name },
+                            });
+                        }
+                        continue;
                     }
-                    catch {
-                        // JSON parsing failed (e.g. truncated output) — answer stays undefined (retry)
+                    const validCalls = validatedCalls;
+                    const validatedCallArguments = new Map(validCalls.map((entry) => [
+                        entry.call,
+                        entry.validated.arguments,
+                    ]));
+                    const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins);
+                    if (habitBlockReason) {
+                        streamCallbackBuffer?.discard();
+                        recordBlockedHabitSurfaceAttempts(habitSession, result.toolCalls, habitBlockReason);
+                        pushGenerated(msg);
+                        const blockedOutput = `blocked: ${habitBlockReason}. No tool side effects from this assistant message were executed.`;
+                        for (const call of result.toolCalls) {
+                            pushGenerated({ role: "tool", tool_call_id: call.id, content: blockedOutput });
+                            providerRuntime.appendToolOutput(call.id, blockedOutput);
+                        }
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.habit_tool_batch_blocked",
+                            message: "habit tool batch blocked before side effects",
+                            meta: { reason: habitBlockReason, toolCalls: result.toolCalls.map((call) => call.name) },
+                        });
+                        continue;
                     }
-                    if (answer != null) {
-                        if (result.finalAnswerStreamed) {
-                            // The streaming layer already parsed and emitted the answer
-                            // progressively via FinalAnswerParser. Skip clearing and
-                            // re-emitting to avoid double-delivery.
+                    const soleTerminalCall = result.toolCalls.length === 1
+                        ? result.toolCalls[0]
+                        : null;
+                    const soleTerminalProjection = soleTerminalCall
+                        ? (0, tools_1.resolveToolDefinition)(soleTerminalCall.name)?.terminalProjection
+                        : undefined;
+                    if (soleTerminalCall && soleTerminalProjection?.mode === "verbatim") {
+                        const terminalArgs = validatedCallArguments.get(soleTerminalCall);
+                        if (soleTerminalProjection.clearBufferedText
+                            || callbacks.settleOutputMode === "final_only") {
+                            streamCallbackBuffer?.discard();
                         }
                         else {
-                            // Clear any streamed noise (e.g. refusal text) before emitting.
+                            await streamCallbackBuffer?.flush();
+                        }
+                        if (soleTerminalProjection.clearBufferedText)
                             callbacks.onClearText?.();
-                            // Emit the answer through the callback pipeline so channels receive it.
-                            // Never truncate -- channel adapters handle splitting long messages.
-                            callbacks.onTextChunk(answer);
-                        }
-                        // 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)");
+                        callbacks.onToolStart(soleTerminalCall.name, terminalArgs);
+                        let terminalResult;
+                        try {
+                            const execToolFn = options?.execTool ?? tools_1.execTool;
+                            terminalResult = await execToolFn(soleTerminalCall.name, terminalArgs, augmentedToolContext);
+                        }
+                        catch (error) {
+                            callbacks.onToolEnd(soleTerminalCall.name, (0, tools_1.summarizeArgs)(soleTerminalCall.name, terminalArgs), false);
+                            pushGenerated(msg);
+                            const failure = error instanceof Error ? `error: ${error.message}` : `error: ${String(error)}`;
+                            pushGenerated({ role: "tool", tool_call_id: soleTerminalCall.id, content: failure });
+                            providerRuntime.appendToolOutput(soleTerminalCall.id, failure);
+                            callbacks.onTextChunk(failure);
+                            completion = { answer: failure, intent: "blocked" };
+                            outcome = "blocked";
+                            done = true;
+                            continue;
+                        }
+                        callbacks.onToolEnd(soleTerminalCall.name, (0, tools_1.summarizeArgs)(soleTerminalCall.name, terminalArgs), true);
+                        pushGenerated(msg);
+                        pushGenerated({ role: "tool", tool_call_id: soleTerminalCall.id, content: terminalResult });
+                        providerRuntime.appendToolOutput(soleTerminalCall.id, terminalResult);
+                        callbacks.onTextChunk(terminalResult);
+                        completion = { answer: terminalResult, intent: "complete" };
+                        outcome = "settled";
                         done = true;
+                        continue;
                     }
-                    else {
-                        // Answer is undefined -- the model's final_answer 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.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);
+                    // Check for settle sole call: intercept before tool execution
+                    if (isSoleSettle) {
+                        const settleArgs = validatedCallArguments.get(result.toolCalls[0]);
+                        callbacks.onToolStart("settle", settleArgs);
+                        const requiredToolCallsGate = pendingRequiredToolCalls();
+                        if (requiredToolCallsGate) {
+                            streamCallbackBuffer?.discard();
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                            callbacks.onClearText?.();
+                            queueRequiredCorrection(requiredToolCallsGate.message, "before required tool calls completed");
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.required_tool_calls_pending",
+                                message: "settle rejected until required tool handlers dispatch",
+                                meta: { missingToolNames: requiredToolCallsGate.missing },
+                            });
+                            continue;
+                        }
+                        // Private-runtime attention queue gate: reject settle if items remain
+                        const attentionQueue = augmentedToolContext?.delegatedOrigins;
+                        if (isPrivateRuntimeChannel && attentionQueue && attentionQueue.length > 0) {
+                            streamCallbackBuffer?.discard();
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                            callbacks.onClearText?.();
+                            pushGenerated(msg);
+                            const gateMessage = "current held-work frame still has unsurfaced items — return each listed item with surface(delegationId=...) before you settle. Older transcript claims are historical; only the current held-work frame is the gate.";
+                            pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: gateMessage });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, gateMessage);
+                            continue;
+                        }
+                        // Extract answer from the tool call arguments.
+                        // Supports: {"answer":"text","intent":"..."} or "text" (JSON string).
+                        const { answer, intent } = parseSettlePayload(result.toolCalls[0].arguments);
+                        const requiredAnswerRejection = options?.requiredToolCalls?.validateTerminalAnswer?.(answer);
+                        if (requiredAnswerRejection) {
+                            streamCallbackBuffer?.discard();
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                            callbacks.onClearText?.();
+                            queueRequiredCorrection(requiredAnswerRejection, "before required terminal answer validation completed");
+                            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.required_tool_answer_rejected", message: "unsupported settle answer rejected after required reads", meta: { answerLength: answer.length } });
+                            continue;
+                        }
+                        // Private-runtime settle: no CompletionMetadata, "(settled)" ack
+                        if (isPrivateRuntimeChannel) {
+                            streamCallbackBuffer?.discard();
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
+                            pushGenerated(msg);
+                            const settled = "(settled)";
+                            pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: settled });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, settled);
+                            outcome = "settled";
+                            done = true;
+                            continue;
+                        }
+                        // The provider finalizer has already established a top-level string
+                        // answer before ordinary settle handling reaches this point.
+                        const deliveredAnswer = answer;
+                        const retryError = privateReturnAckLeakError(deliveredAnswer, privateReturnHeldTokens)
+                            ?? privateReturnMissingPonderError({
+                                latestUserRequest: latestUserMessageText(messages),
+                                answer: deliveredAnswer,
+                                sawPonder,
+                            })
+                            ?? getSettleRetryError(mustResolveBeforeHandoffActive, intent, sawSteeringFollowUp, options?.delegationDecision, sawSendMessageSelf, sawPonder, sawQuerySession, options?.currentObligation ?? null, options?.activeWorkFrame?.inner?.job, sawExternalStateQuery);
+                        const validDirectReply = mustResolveBeforeHandoffActive && intent === "direct_reply" && sawSteeringFollowUp;
+                        if (retryError === null) {
+                            try {
+                                if (!result.settleStreamed) {
+                                    const acceptedOutputCallbacks = streamCallbackBuffer?.callbacks ?? callbacks;
+                                    acceptedOutputCallbacks.onTextChunk(deliveredAnswer);
+                                }
+                                await streamCallbackBuffer?.flush();
+                            }
+                            catch (error) {
+                                callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                                streamCallbackBuffer?.discard();
+                                finishTerminalProviderError(new streaming_1.SettleFinalizationCallbackError(error), "unknown");
+                                continue;
+                            }
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
+                            completion = {
+                                answer: deliveredAnswer,
+                                intent: validDirectReply ? "direct_reply" : intent === "blocked" ? "blocked" : "complete",
+                            };
+                            // Retractable owners already hold the validated answer. Final-only
+                            // owners receive it here, after every semantic continuation gate.
+                            pushGenerated(msg);
+                            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.";
+                                pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: resumeWork });
+                                providerRuntime.appendToolOutput(result.toolCalls[0].id, resumeWork);
+                            }
+                            else {
+                                const delivered = "(delivered)";
+                                pushGenerated({ 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 {
+                            // The payload is structurally final, but a semantic continuation
+                            // gate rejected it. Return that exact gate reason to the model.
+                            streamCallbackBuffer?.discard();
+                            callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
+                            callbacks.onClearText?.();
+                            pushGenerated(msg);
+                            const toolRetryMessage = retryError;
+                            pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: toolRetryMessage });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, toolRetryMessage);
+                        }
+                        continue;
                     }
-                    continue;
-                }
-                messages.push(msg);
-                // SHARED: execute tools (final_answer in mixed calls is 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);
+                    // Check for observe sole call: intercept before tool execution
+                    const isSoleObserve = result.toolCalls.length === 1 && result.toolCalls[0].name === "observe";
+                    if (isSoleObserve) {
+                        streamCallbackBuffer?.discard();
+                        const observeArgs = validatedCallArguments.get(result.toolCalls[0]);
+                        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);
+                        pushGenerated(msg);
+                        const silenced = "(silenced)";
+                        pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: silenced });
+                        providerRuntime.appendToolOutput(result.toolCalls[0].id, silenced);
+                        outcome = "observed";
+                        done = true;
                         continue;
                     }
-                    let args = {};
-                    try {
-                        args = JSON.parse(tc.arguments);
+                    // Check for rest sole call: intercept before tool execution
+                    const isSoleRest = result.toolCalls.length === 1 && result.toolCalls[0].name === "rest";
+                    if (isSoleRest) {
+                        streamCallbackBuffer?.discard();
+                        const restArgs = validatedCallArguments.get(result.toolCalls[0]);
+                        callbacks.onToolStart("rest", restArgs);
+                        // Attention queue gate: reject rest if items remain
+                        const attentionQueue = augmentedToolContext?.delegatedOrigins;
+                        if (attentionQueue && attentionQueue.length > 0) {
+                            callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), false);
+                            pushGenerated(msg);
+                            const gateMessage = "current held-work frame still has unsurfaced items — return each listed item with surface(delegationId=...) before you rest. Older transcript claims are historical; only the current held-work frame is the gate.";
+                            pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: gateMessage });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, gateMessage);
+                            continue;
+                        }
+                        if (hasFreshPendingWork(options) && !freshWorkGateFired) {
+                            freshWorkGateFired = true;
+                            callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), false);
+                            pushGenerated(msg);
+                            const gateMessage = "fresh work arrived for me this turn — inspect the pending messages above and take the next concrete action before you rest.";
+                            pushGenerated({ role: "tool", tool_call_id: result.toolCalls[0].id, content: gateMessage });
+                            providerRuntime.appendToolOutput(result.toolCalls[0].id, gateMessage);
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "info",
+                                component: "engine",
+                                event: "engine.fresh_work_gate_fired",
+                                message: "rest deferred once because pending work arrived this turn; agent has been notified",
+                                meta: { pendingCount: options.pendingMessages.length },
+                            });
+                            continue;
+                        }
+                        callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), true);
+                        pushGenerated(msg);
+                        const ack = "(resting)";
+                        pushGenerated({ 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: { ...(typeof restArgs?.status === "string" ? { status: restArgs.status } : {}) },
+                        });
+                        outcome = "rested";
+                        done = true;
+                        continue;
                     }
-                    catch {
-                        /* ignore */
+                    const requiredDispatchRejections = new Map();
+                    for (const entry of validCalls) {
+                        const requiredArgs = entry.validated.arguments;
+                        const rejection = options?.requiredToolCalls?.validateToolCallBeforeDispatch?.(entry.call.name, requiredArgs);
+                        if (rejection)
+                            requiredDispatchRejections.set(entry.call.id, { name: entry.call.name, args: requiredArgs, message: rejection });
                     }
-                    const argSummary = (0, tools_1.summarizeArgs)(tc.name, args);
-                    // Confirmation check for mutate tools
-                    if ((0, tools_1.isConfirmationRequired)(tc.name) && !options?.skipConfirmation) {
-                        let decision = "denied";
-                        if (callbacks.onConfirmAction) {
-                            decision = await callbacks.onConfirmAction(tc.name, args);
-                        }
-                        if (decision !== "confirmed") {
-                            const cancelled = "Action cancelled by user.";
-                            callbacks.onToolStart(tc.name, args);
-                            callbacks.onToolEnd(tc.name, argSummary, false);
-                            messages.push({ role: "tool", tool_call_id: tc.id, content: cancelled });
-                            providerRuntime.appendToolOutput(tc.id, cancelled);
+                    const approvalCalls = await Promise.all(validCalls.filter((entry) => !requiredDispatchRejections.has(entry.call.id)).map(async (entry) => {
+                        const classification = await (0, tools_1.classifyApprovalForInvocation)(entry.call.name, entry.validated.arguments, augmentedToolContext);
+                        return {
+                            ...entry,
+                            ...classification,
+                        };
+                    }));
+                    const protectedCall = approvalCalls.find((entry) => entry.policy.kind === "required");
+                    if (protectedCall && result.toolCalls.length !== 1) {
+                        streamCallbackBuffer?.discard();
+                        pushGenerated(msg);
+                        for (const call of result.toolCalls) {
+                            const rejection = "rejected: approval-eligible tool must be the sole call; no call in this batch was executed.";
+                            pushGenerated({ role: "tool", tool_call_id: call.id, content: rejection });
+                            providerRuntime.appendToolOutput(call.id, rejection);
+                        }
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "engine",
+                            event: "engine.approval_mixed_batch_rejected",
+                            message: "protected tool batch rejected before every handler",
+                            meta: { toolCallCount: result.toolCalls.length, protectedToolName: protectedCall.call.name },
+                        });
+                        continue;
+                    }
+                    if (protectedCall && protectedCall.policy.kind === "required") {
+                        if (!options?.approvalCoordinator) {
+                            streamCallbackBuffer?.discard();
+                            pushGenerated(msg);
+                            const rejection = "rejected: this protected tool requires approval, but the approval coordinator is unavailable; the handler was not invoked.";
+                            pushGenerated({ role: "tool", tool_call_id: protectedCall.call.id, content: rejection });
+                            providerRuntime.appendToolOutput(protectedCall.call.id, rejection);
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.approval_coordinator_unavailable",
+                                message: "protected tool failed closed before handler execution",
+                                meta: { toolName: protectedCall.call.name, toolCallId: protectedCall.call.id },
+                            });
                             continue;
                         }
+                        streamCallbackBuffer?.discard();
+                        pushGenerated(msg);
+                        const toolDigest = (0, tool_arguments_1.digestJson)({
+                            name: protectedCall.call.name,
+                            schemaDigest: protectedCall.validated.schemaDigest,
+                            policyId: protectedCall.policy.policyId,
+                        });
+                        const policyDigest = (0, tool_arguments_1.digestJson)({
+                            policyId: protectedCall.policy.policyId,
+                            actionClass: protectedCall.policy.actionClass,
+                            classification: "required",
+                        });
+                        const committed = await options.approvalCoordinator.propose({
+                            toolCall: structuredClone(msg.tool_calls[0]),
+                            arguments: structuredClone(protectedCall.validated.arguments),
+                            preCallMessages,
+                            frozenAssistantMessage: structuredClone(msg),
+                            schemaDigest: protectedCall.validated.schemaDigest,
+                            toolDigest,
+                            policyDigest,
+                            policyId: protectedCall.policy.policyId,
+                            actionClass: protectedCall.policy.actionClass,
+                        });
+                        suspension = {
+                            approvalId: committed.approvalId,
+                            toolCallId: protectedCall.call.id,
+                            checkpointDigest: committed.checkpointDigest,
+                            suspendedSessionRevision: committed.suspendedSessionRevision,
+                        };
+                        outcome = "suspended";
+                        done = true;
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "engine",
+                            event: "engine.approval_turn_suspended",
+                            message: "agent turn suspended before protected tool execution",
+                            meta: { approvalId: committed.approvalId, toolCallId: protectedCall.call.id },
+                        });
+                        continue;
                     }
-                    callbacks.onToolStart(tc.name, args);
-                    let toolResult;
-                    let success;
-                    try {
-                        toolResult = await (0, tools_1.execTool)(tc.name, args, options?.toolContext);
-                        success = true;
+                    const containsSoleCallOnlyViolation = result.toolCalls.length > 1
+                        && result.toolCalls.some((call) => {
+                            const terminalProjection = (0, tools_1.resolveToolDefinition)(call.name)?.terminalProjection;
+                            return SOLE_CALL_REJECTION[call.name] !== undefined
+                                || terminalProjection?.requiresSoleCall === true;
+                        });
+                    if (callbacks.settleOutputMode === "final_only" && containsSoleCallOnlyViolation) {
+                        streamCallbackBuffer?.discard();
                     }
-                    catch (e) {
-                        toolResult = `error: ${e}`;
-                        success = false;
+                    else {
+                        await streamCallbackBuffer?.flush();
+                    }
+                    pushGenerated(msg);
+                    // Execute tools (sole-call tools in mixed calls are rejected inline)
+                    for (const tc of result.toolCalls) {
+                        if (signal?.aborted)
+                            break;
+                        const requiredDispatchRejection = requiredDispatchRejections.get(tc.id);
+                        if (requiredDispatchRejection) {
+                            callbacks.onToolStart(tc.name, requiredDispatchRejection.args);
+                            callbacks.onToolEnd(tc.name, (0, tools_1.summarizeArgs)(tc.name, requiredDispatchRejection.args), false);
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: requiredDispatchRejection.message });
+                            providerRuntime.appendToolOutput(tc.id, requiredDispatchRejection.message);
+                            options?.toolBoundaryObserver?.({
+                                name: tc.name,
+                                reason: "dependency_rejected",
+                                globallyResolvable: typeof (0, tools_1.resolveToolDefinition)(tc.name)?.handler === "function",
+                                invoked: false,
+                                sideEffect: false,
+                            });
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.required_tool_dispatch_rejected",
+                                message: "required tool dependency rejected before approval and handler dispatch",
+                                meta: { toolName: tc.name },
+                            });
+                            continue;
+                        }
+                        // Reject sole-call tools when mixed with other tool calls
+                        const terminalProjection = (0, tools_1.resolveToolDefinition)(tc.name)?.terminalProjection;
+                        const soleCallRejection = SOLE_CALL_REJECTION[tc.name]
+                            ?? (terminalProjection?.requiresSoleCall
+                                ? `rejected: ${tc.name} must be the only tool call.`
+                                : undefined);
+                        if (soleCallRejection) {
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: soleCallRejection });
+                            providerRuntime.appendToolOutput(tc.id, soleCallRejection);
+                            continue;
+                        }
+                        const args = validatedCallArguments.get(tc);
+                        const currentEffectFingerprint = effectFingerprint(tc.name, tc.arguments);
+                        if (forcingHistoricalEffect
+                            && currentEffectFingerprint
+                            && !unresolvedHistoricalEffects.some((effect) => effect.fingerprint === currentEffectFingerprint)) {
+                            const rejection = "rejected: this turn is retrying an unresolved historical effect, and these mutation arguments do not match it. Read current state or retry the exact failed effect.";
+                            callbacks.onToolStart(tc.name, args);
+                            callbacks.onToolEnd(tc.name, (0, tools_1.summarizeArgs)(tc.name, args), false);
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: rejection });
+                            providerRuntime.appendToolOutput(tc.id, rejection);
+                            continue;
+                        }
+                        if (tc.name === "send_message" && args.friendId === "self") {
+                            const latestUserText = latestUserMessageText(messages);
+                            if (!isPrivateRuntimeChannel && looksLikePrivateReturnRequest(latestUserText)) {
+                                const argSummary = (0, tools_1.summarizeArgs)(tc.name, args);
+                                const rejection = "private-return requests must use ponder, not send_message(friendId=self). Create a typed ponder packet with the marker/source request preserved, then only acknowledge that the private pass is queued.";
+                                callbacks.onToolStart(tc.name, args);
+                                callbacks.onToolEnd(tc.name, argSummary, false);
+                                pushGenerated({ role: "tool", tool_call_id: tc.id, content: rejection });
+                                providerRuntime.appendToolOutput(tc.id, rejection);
+                                continue;
+                            }
+                            sawSendMessageSelf = true;
+                        }
+                        if (tc.name === "speak") {
+                            // The canonical pre-batch schema gate guarantees a required string.
+                            const speakArgs = JSON.parse(tc.arguments);
+                            const speakMessage = speakArgs.message;
+                            const argSummary = (0, tools_1.summarizeArgs)("speak", { message: speakMessage });
+                            callbacks.onToolStart("speak", { message: speakMessage });
+                            if (speakMessage.trim().length === 0) {
+                                const err = "speak requires a non-empty `message` string.";
+                                callbacks.onToolEnd("speak", argSummary, false);
+                                pushGenerated({ role: "tool", tool_call_id: tc.id, content: err });
+                                providerRuntime.appendToolOutput(tc.id, err);
+                                (0, runtime_1.emitNervesEvent)({
+                                    level: "warn",
+                                    component: "engine",
+                                    event: "engine.speak_invalid",
+                                    message: "speak rejected: missing or empty message",
+                                    meta: {},
+                                });
+                                continue;
+                            }
+                            callbacks.onTextChunk(speakMessage);
+                            let speakDeliveryError = null;
+                            try {
+                                await callbacks.flushNow?.();
+                            }
+                            catch (err) {
+                                speakDeliveryError = err instanceof Error ? err : new Error(String(err));
+                            }
+                            if (speakDeliveryError) {
+                                callbacks.onToolEnd("speak", argSummary, false);
+                                const failMsg = `speak delivery failed: ${speakDeliveryError.message}. the message did not reach your friend; do not assume they saw it.`;
+                                pushGenerated({ role: "tool", tool_call_id: tc.id, content: failMsg });
+                                providerRuntime.appendToolOutput(tc.id, failMsg);
+                                (0, runtime_1.emitNervesEvent)({
+                                    level: "error",
+                                    component: "engine",
+                                    event: "engine.speak_delivery_failed",
+                                    message: "speak delivery failed",
+                                    meta: { error: speakDeliveryError.message, messageLength: speakMessage.length },
+                                });
+                                continue;
+                            }
+                            callbacks.onToolEnd("speak", argSummary, true);
+                            const ack = "(spoken)";
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: ack });
+                            providerRuntime.appendToolOutput(tc.id, ack);
+                            (0, runtime_1.emitNervesEvent)({
+                                component: "engine",
+                                event: "engine.speak",
+                                message: "agent spoke mid-turn",
+                                meta: { messageLength: speakMessage.length },
+                            });
+                            continue;
+                        }
+                        if (tc.name === "ponder") {
+                            const parsedArgs = normalizeLegacyPonderArgs(parsePonderPayload(tc.arguments));
+                            const argSummary = (0, tools_1.summarizeArgs)(tc.name, parsedArgs);
+                            callbacks.onToolStart(tc.name, parsedArgs);
+                            let toolResult;
+                            let success = false;
+                            try {
+                                const action = parsedArgs.action ?? "create";
+                                const currentSession = augmentedToolContext?.currentSession;
+                                const currentOrigin = currentSession
+                                    ? { friendId: currentSession.friendId, channel: currentSession.channel, key: currentSession.key }
+                                    : undefined;
+                                const isInnerChannel = currentOrigin?.friendId === "self" && currentOrigin?.channel === "inner";
+                                const shouldCreateReturnObligation = !!currentOrigin && !isInnerChannel;
+                                const attentionQueue = augmentedToolContext?.delegatedOrigins ?? [];
+                                const successCriteria = parseSuccessCriteria(parsedArgs.success_criteria);
+                                const payload = parsePacketPayload(parsedArgs.payload_json);
+                                let packet;
+                                let returnObligationId = null;
+                                let resultAction = "created";
+                                let privateReturnSourceRequest = "";
+                                if (action === "create") {
+                                    if (isInnerChannel && attentionQueue.length > 0) {
+                                        throw new Error("private runtime already has held return work in the attention queue; surface the existing delegationId instead of creating a replacement ponder packet.");
+                                    }
+                                    const kind = parsedArgs.kind;
+                                    const objective = typeof parsedArgs.objective === "string" ? parsedArgs.objective.trim() : "";
+                                    const summary = typeof parsedArgs.summary === "string" ? parsedArgs.summary.trim() : "";
+                                    const sourceRequest = currentOrigin && !isInnerChannel ? latestUserMessageText(messages) : "";
+                                    privateReturnSourceRequest = sourceRequest;
+                                    if (!kind || !objective || !successCriteria || !payload) {
+                                        throw new Error("ponder create requires kind, objective, success_criteria, and valid payload_json.");
+                                    }
+                                    const packetPayload = sourceRequest
+                                        ? { ...payload, sourceRequest }
+                                        : payload;
+                                    const createLinkedReturnObligation = (id, packetId) => {
+                                        (0, obligations_1.createReturnObligation)((0, identity_2.getAgentName)(), {
+                                            id,
+                                            origin: currentOrigin,
+                                            status: "queued",
+                                            delegatedContent: buildPonderDelegatedContent({ summary, objective, sourceRequest }),
+                                            packetId,
+                                            createdAt: Date.now(),
+                                        });
+                                    };
+                                    const agentRoot = (0, identity_2.getAgentRoot)();
+                                    let relatedObligationId;
+                                    if (currentOrigin && !isInnerChannel) {
+                                        try {
+                                            const obligation = (0, obligations_1.createObligation)(agentRoot, {
+                                                origin: currentOrigin,
+                                                content: objective,
+                                            });
+                                            relatedObligationId = obligation.id;
+                                        }
+                                        catch {
+                                            relatedObligationId = undefined;
+                                        }
+                                    }
+                                    const frictionSignature = kind === "harness_friction" && typeof packetPayload.frictionSignature === "string"
+                                        ? packetPayload.frictionSignature
+                                        : null;
+                                    const existing = frictionSignature && currentOrigin
+                                        ? (0, packets_1.findHarnessFrictionPacket)(agentRoot, currentOrigin, frictionSignature)
+                                        : null;
+                                    if (existing) {
+                                        resultAction = "revised";
+                                        const existingActiveReturnId = shouldCreateReturnObligation
+                                            ? activeReturnObligationId((0, identity_2.getAgentName)(), existing.relatedReturnObligationId)
+                                            : null;
+                                        returnObligationId = existingActiveReturnId
+                                            ?? (shouldCreateReturnObligation ? (0, obligations_1.generateObligationId)(Date.now()) : null);
+                                        packet = existing.status === "drafting"
+                                            ? (0, packets_1.revisePonderPacket)(agentRoot, existing.id, {
+                                                kind,
+                                                objective,
+                                                summary,
+                                                successCriteria,
+                                                payload: packetPayload,
+                                            })
+                                            : existing;
+                                        if (returnObligationId && returnObligationId !== existing.relatedReturnObligationId) {
+                                            packet = (0, packets_1.advancePonderPacket)(agentRoot, packet.id, { relatedReturnObligationId: returnObligationId });
+                                            createLinkedReturnObligation(returnObligationId, packet.id);
+                                        }
+                                    }
+                                    else {
+                                        returnObligationId = shouldCreateReturnObligation ? (0, obligations_1.generateObligationId)(Date.now()) : null;
+                                        packet = (0, packets_1.createPonderPacket)(agentRoot, {
+                                            kind,
+                                            objective,
+                                            summary,
+                                            successCriteria,
+                                            ...(currentOrigin ? { origin: currentOrigin } : {}),
+                                            ...(relatedObligationId ? { relatedObligationId } : {}),
+                                            ...(returnObligationId ? { relatedReturnObligationId: returnObligationId } : {}),
+                                            ...(parsedArgs.follows_packet_id ? { followsPacketId: parsedArgs.follows_packet_id } : {}),
+                                            payload: packetPayload,
+                                        });
+                                        if (returnObligationId) {
+                                            createLinkedReturnObligation(returnObligationId, packet.id);
+                                        }
+                                    }
+                                }
+                                else {
+                                    const packetId = typeof parsedArgs.packet_id === "string" ? parsedArgs.packet_id.trim() : "";
+                                    const kind = parsedArgs.kind;
+                                    const objective = typeof parsedArgs.objective === "string" ? parsedArgs.objective.trim() : "";
+                                    const summary = typeof parsedArgs.summary === "string" ? parsedArgs.summary.trim() : "";
+                                    if (!packetId || !kind || !objective || !successCriteria || !payload) {
+                                        throw new Error("ponder revise requires packet_id, kind, objective, success_criteria, and valid payload_json.");
+                                    }
+                                    packet = (0, packets_1.revisePonderPacket)((0, identity_2.getAgentRoot)(), packetId, {
+                                        kind,
+                                        objective,
+                                        summary,
+                                        successCriteria,
+                                        payload,
+                                    });
+                                    returnObligationId = packet.relatedReturnObligationId
+                                        && !(packet.origin?.friendId === "self" && packet.origin.channel === "inner")
+                                        ? packet.relatedReturnObligationId
+                                        : null;
+                                    resultAction = "revised";
+                                }
+                                if (returnObligationId) {
+                                    for (const token of extractPrivateReturnHeldTokens(privateReturnSourceRequest)) {
+                                        privateReturnHeldTokens.add(token);
+                                    }
+                                    const agentName = (0, identity_2.getAgentName)();
+                                    await (0, socket_client_1.requestPrivateWake)(agentName, augmentedToolContext?.daemonSocketPath, buildPonderReturnPrivateWakeOptions({ agentName, packet, returnObligationId })).catch(() => undefined);
+                                }
+                                sawPonder = true;
+                                toolResult = buildPonderResult(packet, resultAction, returnObligationId);
+                                success = true;
+                                (0, runtime_1.emitNervesEvent)({
+                                    component: "engine",
+                                    event: "engine.ponder_packet",
+                                    message: "ponder packet touched",
+                                    meta: {
+                                        action: resultAction,
+                                        packetId: packet.id,
+                                        kind: packet.kind,
+                                        status: packet.status,
+                                    },
+                                });
+                            }
+                            catch (error) {
+                                toolResult = error instanceof Error ? error.message : String(error);
+                            }
+                            callbacks.onToolEnd(tc.name, argSummary, success);
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: toolResult });
+                            providerRuntime.appendToolOutput(tc.id, toolResult);
+                            continue;
+                        }
+                        /* 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);
+                        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);
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: rejection });
+                            providerRuntime.appendToolOutput(tc.id, rejection);
+                            continue;
+                        }
+                        callbacks.onToolStart(tc.name, args);
+                        let toolResult;
+                        let success;
+                        try {
+                            const execToolFn = options?.execTool ?? tools_1.execTool;
+                            const routineActionSelection = approvalCalls.find((entry) => entry.call.id === tc.id)?.routineActionSelection;
+                            const executionToolContext = routineActionSelection && augmentedToolContext ? { ...augmentedToolContext, routineActionSelection } : augmentedToolContext;
+                            if (requiredToolCallNames.includes(tc.name) && !options?.requiredToolCalls?.requireSuccessfulResults)
+                                dispatchedRequiredToolCalls.add(tc.name);
+                            toolResult = await execToolFn(tc.name, args, executionToolContext);
+                            success = true;
+                        }
+                        catch (e) {
+                            toolResult = `error: ${e}`;
+                            success = false;
+                            augmentedToolContext?.habitSession?.recordError?.(toolResult);
+                        }
+                        const validatedRequiredResult = success && requiredToolCallNames.includes(tc.name) && options?.requiredToolCalls?.requireSuccessfulResults
+                            ? requiredToolResultSucceeded(tc.name, toolResult, args, options.requiredToolCalls.validateRequiredToolResult)
+                            : false;
+                        if (validatedRequiredResult) {
+                            dispatchedRequiredToolCalls.add(tc.name);
+                            for (const requiredName of options?.requiredToolCalls?.requiredToolCallsAfterResult?.(tc.name, args, toolResult) ?? []) {
+                                if (!candidateToolNames.has(requiredName)) {
+                                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "engine", event: "engine.required_tool_unadvertised", message: "dependent required tool is not advertised for the active channel", meta: { toolName: requiredName, channel: String(channel) } });
+                                    throw new Error(`dependent required tool is not advertised for this channel: ${requiredName}`);
+                                }
+                                if (!requiredToolCallNames.includes(requiredName))
+                                    requiredToolCallNames.push(requiredName);
+                            }
+                        }
+                        if (success && currentEffectFingerprint && !toolResultIndicatesFailure(toolResult)) {
+                            unresolvedHistoricalEffects = unresolvedHistoricalEffects.filter((effect) => effect.fingerprint !== currentEffectFingerprint);
+                        }
+                        const resolvedRiskProfile = (0, tools_1.resolveToolDefinition)(tc.name)?.riskProfile;
+                        const toolRiskProfile = typeof resolvedRiskProfile === "function" ? resolvedRiskProfile(args) : resolvedRiskProfile;
+                        options?.toolBoundaryObserver?.({
+                            name: tc.name,
+                            reason: "dispatched",
+                            globallyResolvable: typeof (0, tools_1.resolveToolDefinition)(tc.name)?.handler === "function",
+                            invoked: true,
+                            sideEffect: success && toolRiskProfile?.mutates !== "none",
+                        });
+                        toolResult = (0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger);
+                        (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);
+                        pushGenerated({ role: "tool", tool_call_id: tc.id, content: toolResult });
+                        providerRuntime.appendToolOutput(tc.id, toolResult);
+                        callbacks.onToolResult?.(messagesWithoutRequiredCorrections());
                     }
-                    callbacks.onToolEnd(tc.name, argSummary, success);
-                    messages.push({ role: "tool", tool_call_id: tc.id, content: toolResult });
-                    providerRuntime.appendToolOutput(tc.id, toolResult);
                 }
             }
-        }
-        catch (e) {
-            // Abort is not an error — just stop cleanly
-            if (signal?.aborted) {
-                stripLastToolCalls(messages);
-                break;
-            }
-            // Context overflow: trim aggressively and retry once
-            if (isContextOverflow(e) && !overflowRetried) {
-                overflowRetried = true;
-                stripLastToolCalls(messages);
-                const { maxTokens, contextMargin } = (0, config_1.getContextConfig)();
-                const trimmed = (0, context_1.trimMessages)(messages, maxTokens, contextMargin, maxTokens * 2);
-                messages.splice(0, messages.length, ...trimmed);
-                providerRuntime.resetTurnState(messages);
-                callbacks.onError(new Error("context trimmed, retrying..."), "transient");
-                continue;
-            }
-            // Transient errors: retry with exponential backoff
-            if (isTransientError(e) && retryCount < MAX_RETRIES) {
-                retryCount++;
-                const delay = RETRY_BASE_MS * Math.pow(2, retryCount - 1);
-                const cause = classifyTransientError(e);
-                callbacks.onError(new Error(`${cause}, retrying in ${delay / 1000}s (${retryCount}/${MAX_RETRIES})...`), "transient");
-                // Wait with abort support
-                const aborted = await new Promise((resolve) => {
-                    const timer = setTimeout(() => resolve(false), delay);
-                    if (signal) {
-                        const onAbort = () => { clearTimeout(timer); resolve(true); };
-                        if (signal.aborted) {
-                            clearTimeout(timer);
-                            resolve(true);
-                            return;
-                        }
-                        signal.addEventListener("abort", onAbort, { once: true });
-                    }
-                });
-                if (aborted) {
+            catch (e) {
+                // Abort is not an error — just stop cleanly
+                if (e instanceof provider_attempt_1.ProviderAttemptAbortError || signal?.aborted) {
                     stripLastToolCalls(messages);
+                    stripLastToolCalls(generatedMessages);
+                    outcome = "aborted";
                     break;
                 }
-                providerRuntime.resetTurnState(messages);
-                continue;
+                const errorForClassification = e instanceof Error ? e : /* v8 ignore next -- defensive @preserve */ new Error(String(e));
+                let providerClassification;
+                try {
+                    providerClassification = providerRuntime.classifyError(errorForClassification);
+                }
+                catch {
+                    /* v8 ignore next -- defensive: classifyError should not throw @preserve */
+                    providerClassification = "unknown";
+                }
+                finishTerminalProviderError(errorForClassification, providerClassification);
             }
-            callbacks.onError(e instanceof Error ? e : new Error(String(e)), "terminal");
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "engine.error",
-                trace_id: traceId,
-                component: "engine",
-                message: e instanceof Error ? e.message : String(e),
-                meta: {},
-            });
-            stripLastToolCalls(messages);
-            done = true;
         }
     }
+    finally {
+        removeRequiredCorrections();
+    }
+    options?.captureGeneratedMessages?.(structuredClone(generatedMessages));
     (0, runtime_1.emitNervesEvent)({
         event: "engine.turn_end",
         trace_id: traceId,
         component: "engine",
         message: "runAgent turn completed",
-        meta: { done },
+        meta: { done, sawPonder, sawQuerySession, sawBridgeManage },
     });
-    return { usage: lastUsage };
+    return {
+        usage: lastUsage,
+        outcome,
+        completion,
+        ...(suspension ? { suspension } : {}),
+        ...(terminalError ? { error: terminalError, errorClassification: terminalErrorClassification } : {}),
+    };
 }