@ouro.bot/cli 0.1.0-alpha.724 → 0.1.0-alpha.725

package/dist/heart/core.js

@@ -19,6 +19,7 @@ const identity_1 = require("./identity");
 const tools_1 = require("../repertoire/tools");
 const friends_1 = require("@ouro.bot/friends");
 const tools_2 = require("../repertoire/tools");
+const streaming_1 = require("./streaming");
 const runtime_1 = require("../nerves/runtime");
 const context_1 = require("../mind/context");
 const prompt_budget_1 = require("../mind/prompt-budget");
@@ -30,6 +31,7 @@ const azure_1 = require("./providers/azure");
 const minimax_1 = require("./providers/minimax");
 const openai_codex_1 = require("./providers/openai-codex");
 const github_copilot_1 = require("./providers/github-copilot");
+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");
@@ -188,17 +190,20 @@ function getProviderDisplayLabel(facing = "human") {
     };
     return providerLabelBuilders[provider]();
 }
-function createHabitCallbackBuffer(callbacks) {
+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: {
-            ...callbacks,
-            onModelStreamStart: () => { events.push({ kind: "stream-start" }); },
-            onTextChunk: (text) => { events.push({ kind: "text", text }); },
-            onReasoningChunk: (text) => { events.push({ kind: "reasoning", text }); },
-            onClearText: () => { events.push({ kind: "clear" }); },
-            flushNow: () => { events.push({ kind: "flush" }); },
-        },
+        callbacks: bufferedCallbacks,
         async flush() {
             for (const event of events.splice(0)) {
                 switch (event.kind) {
@@ -225,6 +230,12 @@ function createHabitCallbackBuffer(callbacks) {
         },
     };
 }
+function createHabitCallbackBuffer(callbacks) {
+    return createCallbackBuffer(callbacks, "all");
+}
+function createFinalOnlyTextBuffer(callbacks) {
+    return createCallbackBuffer(callbacks, "text-only");
+}
 /**
  * Strip <think>...</think> blocks for the violation-detection check at the
  * end of a streaming turn. Used to tell legitimate text-only responses
@@ -295,7 +306,10 @@ function recordBlockedHabitSurfaceAttempts(habitSession, toolCalls, reason) {
         });
     }
 }
-async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins, activeToolNames) {
+async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins, activeToolNames, noSend) {
+    if (noSend && toolCalls.some((call) => call.name === "ponder")) {
+        return "habit tool 'ponder' cannot create continuations under immutable no-send authority";
+    }
     if (!habitSession)
         return null;
     const granted = new Set(habitSession.toolPolicy.grantedTools);
@@ -340,6 +354,36 @@ async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigi
 function isChatStyleChannel(channel) {
     return channel === "cli" || channel === "teams" || channel === "bluebubbles" || channel === "voice";
 }
+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 = {
@@ -350,14 +394,8 @@ const SOLE_CALL_REJECTION = {
 function parseSettlePayload(argumentsText) {
     try {
         const parsed = JSON.parse(argumentsText);
-        if (typeof parsed === "string") {
-            return { answer: parsed };
-        }
-        if (!parsed || typeof parsed !== "object") {
-            return {};
-        }
-        const answer = typeof parsed.answer === "string" ? parsed.answer : undefined;
-        const rawIntent = parsed.intent;
+        const answer = typeof parsed?.answer === "string" ? parsed.answer : undefined;
+        const rawIntent = parsed?.intent;
         const intent = rawIntent === "complete" || rawIntent === "blocked" || rawIntent === "direct_reply"
             ? rawIntent
             : undefined;
@@ -367,6 +405,23 @@ function parseSettlePayload(argumentsText) {
         return {};
     }
 }
+function matchesRegisteredToolArgumentSchema(tool, args) {
+    const parameters = tool.function.parameters;
+    for (const requiredKey of parameters.required ?? []) {
+        if (!(requiredKey in args))
+            return false;
+    }
+    for (const [key, property] of Object.entries(parameters.properties)) {
+        const value = args[key];
+        if (value === undefined)
+            continue;
+        if (property.type === "string" && typeof value !== "string")
+            return false;
+        if (property.enum && !property.enum.includes(value))
+            return false;
+    }
+    return true;
+}
 function parsePonderPayload(argumentsText) {
     try {
         const parsed = JSON.parse(argumentsText);
@@ -574,6 +629,15 @@ function upsertSystemPrompt(messages, systemText) {
         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.
@@ -747,7 +811,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     const facing = (0, friends_1.channelToFacing)(channel);
     let providerRuntime = await getProviderRuntime(facing);
     const provider = providerRuntime.id;
-    const toolChoiceRequired = options?.toolChoiceRequired ?? true;
+    const restrictedReactionFeedback = options?.restrictedReactionFeedback === true;
+    const toolChoiceRequired = restrictedReactionFeedback ? true : options?.toolChoiceRequired ?? true;
     const traceId = options?.traceId;
     (0, runtime_1.emitNervesEvent)({
         event: "engine.turn_start",
@@ -766,14 +831,18 @@ 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);
     // 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 buildSystemOptions = {
                 ...options,
+                orientationFrame: turnOrientationFrame,
+                resumePriorWork: options?.resumePriorWork === true,
                 providerCapabilities: providerRuntime.capabilities,
                 supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
             };
@@ -783,8 +852,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         }
         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.";
+            const fallback = repairFallbackSystemPrompt(turnOrientationFrame);
             upsertSystemPrompt(messages, fallback);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
@@ -874,16 +942,25 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         outcome = "errored";
         done = true;
     };
+    const finishRestrictedReactionFeedbackViolation = (reason) => {
+        callbacks.onClearText?.();
+        finishTerminalProviderError(new Error(`restricted reaction feedback failed closed: ${reason}`), "unknown");
+    };
     // Prevent MaxListenersExceeded warning — each iteration adds a listener
     try {
         require("events").setMaxListeners(50, signal);
     }
     catch { /* unsupported */ }
     const toolPreferences = currentContext?.friend?.toolPreferences;
-    const baseTools = options?.tools ?? (0, tools_1.getToolsForChannel)(channel ? (0, friends_1.getChannelCapabilities)(channel) : undefined, toolPreferences && Object.keys(toolPreferences).length > 0 ? toolPreferences : undefined, currentContext, providerRuntime.capabilities, options?.mcpManager, providerRuntime.model);
+    const unboundBaseTools = restrictedReactionFeedback
+        ? (0, tools_1.getRestrictedReactionFeedbackTools)()
+        : 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 baseTools = restrictedReactionFeedback
+        ? unboundBaseTools
+        : bindCurrentIngressEvidenceLocator(unboundBaseTools, options?.toolContext?.currentIngressEvidence);
     // Augment tool context with reasoning effort controls from provider
     const baseToolContext = options?.toolContext
-        ?? (options?.orientationFrame ? { signin: async () => undefined, orientationFrame: options.orientationFrame } : undefined);
+        ?? (turnOrientationFrame ? { signin: async () => undefined, orientationFrame: turnOrientationFrame } : undefined);
     const habitSession = options?.habitSession ?? baseToolContext?.habitSession;
     const augmentedToolContext = baseToolContext
         ? {
@@ -891,7 +968,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
             setReasoningEffort: (level) => { currentReasoningEffort = level; },
             activeWorkFrame: options?.activeWorkFrame,
-            orientationFrame: options?.orientationFrame ?? baseToolContext.orientationFrame,
+            orientationFrame: turnOrientationFrame ?? baseToolContext.orientationFrame,
             ...(habitSession ? { habitSession } : {}),
         }
         : habitSession
@@ -924,17 +1001,21 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         const filteredBaseTools = isPrivateRuntimeChannel
             ? baseTools.filter((t) => privateRuntimeHabitCanSendMessage || t.function.name !== "send_message")
             : baseTools;
-        const activeTools = [
-            ...filteredBaseTools,
-            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 activeTools = restrictedReactionFeedback
+            ? filteredBaseTools
+            : [
+                ...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 activeToolNames = new Set(activeTools.map((tool) => tool.function.name));
-        const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
+        const steeringFollowUps = restrictedReactionFeedback
+            ? []
+            : options?.drainSteeringFollowUps?.() ?? [];
         if (steeringFollowUps.length > 0) {
             const hasSupersedingFollowUp = steeringFollowUps.some((followUp) => followUp.effect === "clear_and_supersede");
             if (hasSupersedingFollowUp) {
@@ -960,10 +1041,14 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             break;
         }
         try {
-            const habitCallbackBufferRef = { current: null };
+            const turnCallbackBufferRef = { current: null };
             const callProviderTurn = async () => {
                 callbacks.onModelStart();
-                habitCallbackBufferRef.current = habitSession ? createHabitCallbackBuffer(callbacks) : null;
+                turnCallbackBufferRef.current = habitSession
+                    ? createHabitCallbackBuffer(callbacks)
+                    : callbacks.settleOutputMode === "final_only"
+                        ? createFinalOnlyTextBuffer(callbacks)
+                        : null;
                 try {
                     const promptBudget = (0, prompt_budget_1.applyPromptBudget)({
                         messages,
@@ -978,18 +1063,18 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     return await providerRuntime.streamTurn({
                         messages,
                         activeTools,
-                        callbacks: habitCallbackBufferRef.current?.callbacks ?? callbacks,
+                        callbacks: turnCallbackBufferRef.current?.callbacks ?? callbacks,
                         signal,
                         traceId,
                         toolChoiceRequired,
                         reasoningEffort: currentReasoningEffort,
-                        eagerSettleStreaming: true,
+                        eagerSettleStreaming: !restrictedReactionFeedback,
                         systemPrompt: structuredSystemPrompt,
                     });
                 }
                 catch (error) {
-                    habitCallbackBufferRef.current?.discard();
-                    habitCallbackBufferRef.current = null;
+                    turnCallbackBufferRef.current?.discard();
+                    turnCallbackBufferRef.current = null;
                     if (signal?.aborted)
                         throw new provider_attempt_1.ProviderAttemptAbortError();
                     throw error;
@@ -1019,8 +1104,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 operation: "turn",
                 provider: providerRuntime.id,
                 model: providerRuntime.model,
-                run: callProviderTurnWithOverflowRecovery,
+                run: restrictedReactionFeedback ? callProviderTurn : callProviderTurnWithOverflowRecovery,
                 classifyError: (error) => providerRuntime.classifyError(error),
+                ...(restrictedReactionFeedback ? { policy: { maxAttempts: 1 } } : {}),
                 onRetry: async (record, maxAttempts) => {
                     const delayMs = record.delayMs;
                     const seconds = delayMs / 1000;
@@ -1061,8 +1147,17 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 continue;
             }
             const result = attempt.value;
-            const streamCallbackBuffer = habitCallbackBufferRef.current;
-            habitCallbackBufferRef.current = null;
+            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;
@@ -1123,6 +1218,100 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             if (hasPhaseAnnotation) {
                 msg.phase = isSoleSettle ? "settle" : "commentary";
             }
+            if (restrictedReactionFeedback) {
+                if (result.toolCalls.length !== 1) {
+                    streamCallbackBuffer?.discard();
+                    finishRestrictedReactionFeedbackViolation(result.toolCalls.length === 0
+                        ? "the provider returned no terminal tool"
+                        : "the provider returned a mixed or multiple-tool batch");
+                    continue;
+                }
+                const restrictedCall = result.toolCalls[0];
+                if (!activeToolNames.has(restrictedCall.name)) {
+                    streamCallbackBuffer?.discard();
+                    finishRestrictedReactionFeedbackViolation(`the provider returned unregistered tool ${JSON.stringify(restrictedCall.name)}`);
+                    continue;
+                }
+                let restrictedArgs = null;
+                try {
+                    const parsed = JSON.parse(restrictedCall.arguments);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        restrictedArgs = parsed;
+                    }
+                }
+                catch {
+                    restrictedArgs = null;
+                }
+                const registeredTool = activeTools.find((tool) => tool.function.name === restrictedCall.name);
+                const argumentsMatchSchema = restrictedArgs !== null
+                    && matchesRegisteredToolArgumentSchema(registeredTool, restrictedArgs);
+                const callbackArgs = (restrictedArgs ?? {});
+                if (restrictedCall.name === "settle") {
+                    const { answer, intent } = parseSettlePayload(restrictedCall.arguments);
+                    callbacks.onToolStart("settle", callbackArgs);
+                    if (!argumentsMatchSchema || answer === undefined || intent === "direct_reply") {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", callbackArgs), false);
+                        streamCallbackBuffer?.discard();
+                        finishRestrictedReactionFeedbackViolation("settle arguments were malformed or requested continuation");
+                        continue;
+                    }
+                    streamCallbackBuffer?.discard();
+                    callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", callbackArgs), true);
+                    const completionIntent = intent === "blocked" ? "blocked" : "complete";
+                    completion = { answer, intent: completionIntent };
+                    callbacks.onClearText?.();
+                    callbacks.onTextChunk(answer);
+                    messages.push(msg);
+                    const delivered = "(delivered)";
+                    messages.push({ role: "tool", tool_call_id: restrictedCall.id, content: delivered });
+                    providerRuntime.appendToolOutput(restrictedCall.id, delivered);
+                    outcome = completionIntent === "blocked" ? "blocked" : "settled";
+                    done = true;
+                    continue;
+                }
+                if (!argumentsMatchSchema) {
+                    streamCallbackBuffer?.discard();
+                    finishRestrictedReactionFeedbackViolation(`${restrictedCall.name} arguments were malformed`);
+                    continue;
+                }
+                if (restrictedCall.name === "observe") {
+                    streamCallbackBuffer?.discard();
+                    callbacks.onClearText?.();
+                    callbacks.onToolStart("observe", callbackArgs);
+                    const reason = typeof callbackArgs.reason === "string" ? callbackArgs.reason : undefined;
+                    (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", callbackArgs), true);
+                    messages.push(msg);
+                    const silenced = "(silenced)";
+                    messages.push({ role: "tool", tool_call_id: restrictedCall.id, content: silenced });
+                    providerRuntime.appendToolOutput(restrictedCall.id, silenced);
+                    outcome = "observed";
+                    done = true;
+                    continue;
+                }
+                callbacks.onClearText?.();
+                callbacks.onToolStart("orientation_get", callbackArgs);
+                let orientationReadSucceeded = false;
+                try {
+                    const execToolFn = options?.execTool ?? tools_1.execTool;
+                    await execToolFn("orientation_get", callbackArgs, augmentedToolContext);
+                    orientationReadSucceeded = true;
+                }
+                catch {
+                    orientationReadSucceeded = false;
+                }
+                callbacks.onToolEnd("orientation_get", (0, tools_1.summarizeArgs)("orientation_get", callbackArgs), orientationReadSucceeded);
+                streamCallbackBuffer?.discard();
+                finishRestrictedReactionFeedbackViolation(orientationReadSucceeded
+                    ? "orientation_get completed but no terminal response can follow the single invocation"
+                    : "orientation_get failed");
+                continue;
+            }
             // 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
@@ -1141,8 +1330,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 })
                 : null;
             if (!result.toolCalls.length) {
-                await streamCallbackBuffer?.flush();
                 if (privateReturnTextAckRetryError) {
+                    streamCallbackBuffer?.discard();
                     callbacks.onClearText?.();
                     if (noToolCallRetries < NO_TOOL_CALL_MAX_RETRIES) {
                         noToolCallRetries++;
@@ -1189,6 +1378,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     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
@@ -1212,19 +1402,22 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     messages.push({
                         role: "user",
                         content: isPrivateRuntimeChannel
-                            ? "no tool was called this turn. you must end every turn by calling rest (or surface, ponder, observe). emit the tool call now."
+                            ? 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();
                 messages.push(msg);
                 done = true;
             }
             else {
                 // Reset the retry counter on any successful tool call.
                 noToolCallRetries = 0;
-                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins, activeToolNames);
+                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins, activeToolNames, augmentedToolContext?.noSend === true);
                 if (habitBlockReason) {
                     streamCallbackBuffer?.discard();
                     recordBlockedHabitSurfaceAttempts(habitSession, result.toolCalls, habitBlockReason);
@@ -1243,7 +1436,60 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     });
                     continue;
                 }
-                await streamCallbackBuffer?.flush();
+                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") {
+                    let terminalArgs = {};
+                    try {
+                        const parsed = JSON.parse(soleTerminalCall.arguments);
+                        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                            terminalArgs = parsed;
+                        }
+                    }
+                    catch {
+                        // The registered handler owns exact argument validation.
+                    }
+                    if (soleTerminalProjection.clearBufferedText
+                        || callbacks.settleOutputMode === "final_only") {
+                        streamCallbackBuffer?.discard();
+                    }
+                    else {
+                        await streamCallbackBuffer?.flush();
+                    }
+                    if (soleTerminalProjection.clearBufferedText)
+                        callbacks.onClearText?.();
+                    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);
+                        messages.push(msg);
+                        const failure = error instanceof Error ? `error: ${error.message}` : `error: ${String(error)}`;
+                        messages.push({ 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);
+                    messages.push(msg);
+                    messages.push({ 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;
+                }
                 // Check for settle sole call: intercept before tool execution
                 if (isSoleSettle) {
                     /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
@@ -1255,8 +1501,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     } })();
                     callbacks.onToolStart("settle", settleArgs);
                     // Private-runtime attention queue gate: reject settle if items remain
-                    const attentionQueue = (augmentedToolContext ?? options?.toolContext)?.delegatedOrigins;
+                    const attentionQueue = augmentedToolContext?.delegatedOrigins;
                     if (isPrivateRuntimeChannel && attentionQueue && attentionQueue.length > 0) {
+                        streamCallbackBuffer?.discard();
                         callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
                         callbacks.onClearText?.();
                         messages.push(msg);
@@ -1270,6 +1517,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     const { answer, intent } = parseSettlePayload(result.toolCalls[0].arguments);
                     // Private-runtime settle: no CompletionMetadata, "(settled)" ack
                     if (isPrivateRuntimeChannel) {
+                        streamCallbackBuffer?.discard();
                         callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
                         messages.push(msg);
                         const settled = "(settled)";
@@ -1279,6 +1527,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         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({
@@ -1288,28 +1538,27 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         })
                         ?? getSettleRetryError(mustResolveBeforeHandoffActive, intent, sawSteeringFollowUp, options?.delegationDecision, sawSendMessageSelf, sawPonder, sawQuerySession, options?.currentObligation ?? null, options?.activeWorkFrame?.inner?.job, sawExternalStateQuery);
                     const validDirectReply = mustResolveBeforeHandoffActive && intent === "direct_reply" && sawSteeringFollowUp;
-                    const validTerminalIntent = intent === "complete" || intent === "blocked";
-                    const validClosure = deliveredAnswer != null
-                        && !retryError
-                        && (!mustResolveBeforeHandoffActive || validDirectReply || validTerminalIntent);
-                    if (validClosure) {
+                    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",
                         };
-                        if (result.settleStreamed) {
-                            // The streaming layer already parsed and emitted the answer
-                            // progressively via SettleParser. Skip clearing and
-                            // re-emitting to avoid double-delivery.
-                        }
-                        else {
-                            // Clear any streamed noise (e.g. refusal text) before emitting.
-                            callbacks.onClearText?.();
-                            // Emit the answer through the callback pipeline so channels receive it.
-                            // Never truncate -- channel adapters handle splitting long messages.
-                            callbacks.onTextChunk(deliveredAnswer);
-                        }
+                        // Retractable owners already hold the validated answer. Final-only
+                        // owners receive it here, after every semantic continuation gate.
                         messages.push(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.";
@@ -1325,14 +1574,13 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         }
                     }
                     else {
-                        // Answer is undefined -- the model's settle was incomplete or
-                        // malformed. Clear any partial streamed text or noise, then push the
-                        // assistant msg + error tool result and let the model try again.
+                        // 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?.();
                         messages.push(msg);
-                        const toolRetryMessage = retryError
-                            ?? "your settle was incomplete or malformed. call settle again with your complete response.";
+                        const toolRetryMessage = retryError;
                         messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: toolRetryMessage });
                         providerRuntime.appendToolOutput(result.toolCalls[0].id, toolRetryMessage);
                     }
@@ -1341,6 +1589,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 // Check for observe sole call: intercept before tool execution
                 const isSoleObserve = result.toolCalls.length === 1 && result.toolCalls[0].name === "observe";
                 if (isSoleObserve) {
+                    streamCallbackBuffer?.discard();
                     /* v8 ignore next -- defensive: JSON.parse catch for malformed observe args @preserve */
                     const observeArgs = (() => { try {
                         return JSON.parse(result.toolCalls[0].arguments);
@@ -1370,6 +1619,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 // 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 = (() => { try {
                         return JSON.parse(result.toolCalls[0].arguments);
                     }
@@ -1378,7 +1628,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     } })();
                     callbacks.onToolStart("rest", restArgs);
                     // Attention queue gate: reject rest if items remain
-                    const attentionQueue = (augmentedToolContext ?? options?.toolContext)?.delegatedOrigins;
+                    const attentionQueue = augmentedToolContext?.delegatedOrigins;
                     if (attentionQueue && attentionQueue.length > 0) {
                         callbacks.onToolEnd("rest", (0, tools_1.summarizeArgs)("rest", restArgs), false);
                         messages.push(msg);
@@ -1418,13 +1668,29 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     done = true;
                     continue;
                 }
+                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();
+                }
+                else {
+                    await streamCallbackBuffer?.flush();
+                }
                 messages.push(msg);
                 // Execute tools (sole-call tools in mixed calls are rejected inline)
                 for (const tc of result.toolCalls) {
                     if (signal?.aborted)
                         break;
                     // Reject sole-call tools when mixed with other tool calls
-                    const soleCallRejection = SOLE_CALL_REJECTION[tc.name];
+                    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) {
                         messages.push({ role: "tool", tool_call_id: tc.id, content: soleCallRejection });
                         providerRuntime.appendToolOutput(tc.id, soleCallRejection);
@@ -1515,13 +1781,13 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         let success = false;
                         try {
                             const action = parsedArgs.action ?? "create";
-                            const currentSession = (augmentedToolContext ?? options?.toolContext)?.currentSession;
+                            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 ?? options?.toolContext)?.delegatedOrigins ?? [];
+                            const attentionQueue = augmentedToolContext?.delegatedOrigins ?? [];
                             const successCriteria = parseSuccessCriteria(parsedArgs.success_criteria);
                             const payload = parsePacketPayload(parsedArgs.payload_json);
                             let packet;
@@ -1690,7 +1956,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     let success;
                     try {
                         const execToolFn = options?.execTool ?? tools_1.execTool;
-                        toolResult = await execToolFn(tc.name, args, augmentedToolContext ?? options?.toolContext);
+                        toolResult = await execToolFn(tc.name, args, augmentedToolContext);
                         success = true;
                     }
                     catch (e) {