@ouro.bot/cli 0.1.0-alpha.665 → 0.1.0-alpha.667

package/changelog.json

@@ -1,6 +1,19 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.667",
+      "changes": [
+        "Add stateful habit session summaries, summary tooling, mailbox APIs, nerves review, and habit history visibility.",
+        "Harden habit summary receipts as the canonical summary snapshot, validate agent-scoped Mailbox routes, await post-turn persistence, and preserve session-summary recovery through malformed locators and projected session edge cases."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.666",
+      "changes": [
+        "Close pre-merge habit session review gaps for route gating, executable risk policy, and Desk produced refs."
+      ]
+    },
     {
       "version": "0.1.0-alpha.665",
       "changes": [

package/dist/arc/flight-recorder.js

@@ -33,11 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHabitRunTrigger = isHabitRunTrigger;
 exports.flightRecorderLatestPath = flightRecorderLatestPath;
 exports.isFlightRecorderResume = isFlightRecorderResume;
 exports.readFlightRecorderResume = readFlightRecorderResume;
 exports.writeFlightRecorderResume = writeFlightRecorderResume;
 exports.recordFlightRecorderEvent = recordFlightRecorderEvent;
+exports.isSafeHabitRunId = isSafeHabitRunId;
+exports.readHabitRunReceipt = readHabitRunReceipt;
+exports.listHabitRunReceipts = listHabitRunReceipts;
 exports.writeHabitRunReceipt = writeHabitRunReceipt;
 exports.formatFlightRecorderResume = formatFlightRecorderResume;
 exports.createHabitRunId = createHabitRunId;
@@ -46,6 +50,13 @@ const path = __importStar(require("path"));
 const crypto_1 = require("crypto");
 const session_events_1 = require("../heart/session-events");
 const runtime_1 = require("../nerves/runtime");
+function isHabitRunTrigger(value) {
+    return value === "cron"
+        || value === "launchd"
+        || value === "poke"
+        || value === "overdue"
+        || value === "manual";
+}
 function flightRecorderDir(agentRoot) {
     return path.join(agentRoot, "arc", "flight-recorder");
 }
@@ -55,6 +66,9 @@ function eventsDir(agentRoot) {
 function receiptsDir(agentRoot) {
     return path.join(flightRecorderDir(agentRoot), "habit-receipts");
 }
+function habitReceiptPath(agentRoot, runId) {
+    return path.join(receiptsDir(agentRoot), `${runId}.json`);
+}
 function flightRecorderLatestPath(agentRoot) {
     return path.join(flightRecorderDir(agentRoot), "latest.json");
 }
@@ -311,26 +325,331 @@ function recordFlightRecorderEvent(agentRoot, input) {
     });
     return event;
 }
-function writeHabitRunReceipt(agentRoot, receipt) {
-    fs.mkdirSync(receiptsDir(agentRoot), { recursive: true });
-    const safeReceipt = {
+function isSafeHabitRunId(value) {
+    return typeof value === "string"
+        && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(value)
+        && !value.includes("..");
+}
+function isPlainRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isProducedRefArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && (entry.kind === "arc"
+                || entry.kind === "desk_task"
+                || entry.kind === "desk_record"
+                || entry.kind === "claim"
+                || entry.kind === "surface"
+                || entry.kind === "none")
+            && typeof entry.locator === "string");
+}
+function isHabitSurfaceAttemptArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && typeof entry.recipient === "string"
+            && typeof entry.channel === "string"
+            && (entry.reason === "needed_input"
+                || entry.reason === "status"
+                || entry.reason === "answer"
+                || entry.reason === "blocked"
+                || entry.reason === "other")
+            && (entry.result === "sent"
+                || entry.result === "delivered"
+                || entry.result === "delivered_now"
+                || entry.result === "queued"
+                || entry.result === "deferred"
+                || entry.result === "blocked"
+                || entry.result === "failed"
+                || entry.result === "unavailable")
+            && (entry.routeKind === undefined
+                || entry.routeKind === "family"
+                || entry.routeKind === "originator"
+                || entry.routeKind === "extra")
+            && (entry.rawStatus === undefined || typeof entry.rawStatus === "string")
+            && (entry.error === undefined || typeof entry.error === "string"));
+}
+function isHabitReturnRouteArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && (entry.kind === "family" || entry.kind === "originator" || entry.kind === "extra")
+            && typeof entry.recipient === "string"
+            && (entry.status === "allowed" || entry.status === "unresolved")
+            && (entry.friendId === undefined || typeof entry.friendId === "string")
+            && (entry.channel === undefined || typeof entry.channel === "string")
+            && (entry.key === undefined || typeof entry.key === "string")
+            && (entry.reason === undefined || typeof entry.reason === "string"));
+}
+function isHabitPermissionEnvelope(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.schemaVersion === 1
+        && typeof value.canMessageOutward === "boolean"
+        && isHabitReturnRouteArray(value.returnRoutes)
+        && isStringArray(value.deniedTools)
+        && isStringArray(value.warnings);
+}
+function isHabitToolPolicy(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return (value.requestedTools === null || isStringArray(value.requestedTools))
+        && isStringArray(value.grantedTools)
+        && isStringArray(value.deniedTools)
+        && typeof value.outwardMessagingAllowed === "boolean";
+}
+function defaultHabitRunSummarySnapshot(receipt) {
+    if (receipt.errors.length > 0) {
+        return {
+            summary: `Habit ${receipt.habitName} finished with errors: ${receipt.errors.join("; ")}`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const surface = receipt.surfaceAttempts.find((attempt) => attempt.result !== "blocked" && attempt.result !== "failed" && attempt.result !== "unavailable");
+    if (surface) {
+        return {
+            summary: `Habit ${receipt.habitName} surfaced via ${surface.recipient}/${surface.channel}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const produced = receipt.producedRefs.find((ref) => ref.kind !== "none");
+    if (produced) {
+        return {
+            summary: `Habit ${receipt.habitName} produced ${produced.kind}: ${produced.locator}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    return {
+        summary: `Habit ${receipt.habitName} finished with ${receipt.outcome}.`,
+        decisions: [],
+        nextLikelyStep: null,
+    };
+}
+function normalizeHabitRunSummarySnapshot(value, fallback) {
+    const snapshot = isPlainRecord(value) ? value : {};
+    const summary = typeof snapshot.summary === "string" && snapshot.summary.trim().length > 0
+        ? snapshot.summary
+        : fallback.summary;
+    const nextLikelyStep = snapshot.nextLikelyStep === null
+        ? null
+        : typeof snapshot.nextLikelyStep === "string" && snapshot.nextLikelyStep.trim().length > 0
+            ? snapshot.nextLikelyStep
+            : fallback.nextLikelyStep;
+    return {
+        summary: (0, session_events_1.capStructuredRecordString)(summary),
+        decisions: cappedArray(isStringArray(snapshot.decisions) ? snapshot.decisions : fallback.decisions),
+        nextLikelyStep: nextLikelyStep === null ? null : (0, session_events_1.capStructuredRecordString)(nextLikelyStep),
+    };
+}
+function isHabitRunReceipt(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.schemaVersion === 2
+        && isSafeHabitRunId(value.runId)
+        && typeof value.sessionId === "string"
+        && typeof value.habitName === "string"
+        && (value.trigger === "cron"
+            || value.trigger === "launchd"
+            || value.trigger === "poke"
+            || value.trigger === "overdue"
+            || value.trigger === "manual")
+        && typeof value.startedAt === "string"
+        && typeof value.endedAt === "string"
+        && (value.outcome === "no_change"
+            || value.outcome === "wrote_arc"
+            || value.outcome === "updated_desk"
+            || value.outcome === "wrote_record"
+            || value.outcome === "surfaced"
+            || value.outcome === "blocked"
+            || value.outcome === "error")
+        && typeof value.definitionLocator === "string"
+        && typeof value.sessionLocator === "string"
+        && typeof value.pendingLocator === "string"
+        && typeof value.runtimeStateLocator === "string"
+        && typeof value.receiptLocator === "string"
+        && (value.operationId === undefined || value.operationId === null || typeof value.operationId === "string")
+        && (value.nextRunAt === null || typeof value.nextRunAt === "string")
+        && isHabitPermissionEnvelope(value.permissionEnvelope)
+        && isHabitToolPolicy(value.toolPolicy)
+        && (value.summarySnapshot === undefined || isPlainRecord(value.summarySnapshot))
+        && isProducedRefArray(value.producedRefs)
+        && isHabitSurfaceAttemptArray(value.surfaceAttempts)
+        && isStringArray(value.errors);
+}
+function isLegacyHabitRunReceipt(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.schemaVersion === 1
+        && isSafeHabitRunId(value.runId)
+        && typeof value.habitName === "string"
+        && (value.trigger === "cron"
+            || value.trigger === "launchd"
+            || value.trigger === "poke"
+            || value.trigger === "overdue"
+            || value.trigger === "manual")
+        && typeof value.startedAt === "string"
+        && typeof value.endedAt === "string"
+        && (value.outcome === "no_change"
+            || value.outcome === "wrote_arc"
+            || value.outcome === "updated_desk"
+            || value.outcome === "wrote_record"
+            || value.outcome === "surfaced"
+            || value.outcome === "blocked"
+            || value.outcome === "error")
+        && isProducedRefArray(value.producedRefs)
+        && isHabitSurfaceAttemptArray(value.surfaceAttempts)
+        && isStringArray(value.errors);
+}
+function warnMalformedHabitReceipt(agentRoot, runId, reason) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "mind",
+        event: "mind.flight_recorder_habit_receipt_malformed",
+        message: "flight recorder habit receipt malformed",
+        meta: { agentRoot, runId: (0, session_events_1.capStructuredRecordString)(runId), reason },
+    });
+}
+function normalizeLegacyHabitRunReceipt(receipt) {
+    const sawSurface = receipt.surfaceAttempts.length > 0 || receipt.producedRefs.some((ref) => ref.kind === "surface");
+    return {
+        schemaVersion: 2,
+        runId: receipt.runId,
+        sessionId: receipt.runId,
+        habitName: receipt.habitName,
+        trigger: receipt.trigger,
+        startedAt: receipt.startedAt,
+        endedAt: receipt.endedAt,
+        outcome: receipt.outcome,
+        definitionLocator: `habits/${receipt.habitName}.md`,
+        sessionLocator: `state/habit-sessions/${receipt.runId}/session.json`,
+        pendingLocator: `state/habit-sessions/${receipt.runId}/pending`,
+        runtimeStateLocator: `state/habits/${receipt.habitName}.json`,
+        receiptLocator: `arc/flight-recorder/habit-receipts/${receipt.runId}.json`,
+        operationId: null,
+        nextRunAt: null,
+        permissionEnvelope: {
+            schemaVersion: 1,
+            canMessageOutward: sawSurface,
+            returnRoutes: [],
+            deniedTools: sawSurface ? [] : ["send_message", "surface"],
+            warnings: ["legacy receipt normalized without habit permission envelope"],
+        },
+        toolPolicy: {
+            requestedTools: null,
+            grantedTools: sawSurface ? ["surface"] : [],
+            deniedTools: sawSurface ? [] : ["send_message", "surface"],
+            outwardMessagingAllowed: sawSurface,
+        },
+        summarySnapshot: defaultHabitRunSummarySnapshot(receipt),
+        producedRefs: receipt.producedRefs,
+        surfaceAttempts: receipt.surfaceAttempts,
+        errors: receipt.errors,
+    };
+}
+function capHabitRunReceipt(receipt) {
+    const fallbackSnapshot = defaultHabitRunSummarySnapshot(receipt);
+    return {
         ...receipt,
         habitName: (0, session_events_1.capStructuredRecordString)(receipt.habitName),
+        definitionLocator: (0, session_events_1.capStructuredRecordString)(receipt.definitionLocator),
+        sessionLocator: (0, session_events_1.capStructuredRecordString)(receipt.sessionLocator),
+        pendingLocator: (0, session_events_1.capStructuredRecordString)(receipt.pendingLocator),
+        runtimeStateLocator: (0, session_events_1.capStructuredRecordString)(receipt.runtimeStateLocator),
+        receiptLocator: (0, session_events_1.capStructuredRecordString)(receipt.receiptLocator),
+        operationId: receipt.operationId ? (0, session_events_1.capStructuredRecordString)(receipt.operationId) : null,
+        permissionEnvelope: {
+            ...receipt.permissionEnvelope,
+            returnRoutes: receipt.permissionEnvelope.returnRoutes.map((route) => ({
+                ...route,
+                recipient: (0, session_events_1.capStructuredRecordString)(route.recipient),
+                ...(route.friendId ? { friendId: (0, session_events_1.capStructuredRecordString)(route.friendId) } : {}),
+                ...(route.channel ? { channel: (0, session_events_1.capStructuredRecordString)(route.channel) } : {}),
+                ...(route.key ? { key: (0, session_events_1.capStructuredRecordString)(route.key) } : {}),
+                ...(route.reason ? { reason: (0, session_events_1.capStructuredRecordString)(route.reason) } : {}),
+            })),
+            deniedTools: cappedArray(receipt.permissionEnvelope.deniedTools),
+            warnings: cappedArray(receipt.permissionEnvelope.warnings),
+        },
+        toolPolicy: {
+            requestedTools: receipt.toolPolicy.requestedTools ? cappedArray(receipt.toolPolicy.requestedTools) : null,
+            grantedTools: cappedArray(receipt.toolPolicy.grantedTools),
+            deniedTools: cappedArray(receipt.toolPolicy.deniedTools),
+            outwardMessagingAllowed: receipt.toolPolicy.outwardMessagingAllowed,
+        },
+        summarySnapshot: normalizeHabitRunSummarySnapshot(receipt.summarySnapshot, fallbackSnapshot),
         producedRefs: receipt.producedRefs.map((ref) => ({ ...ref, locator: (0, session_events_1.capStructuredRecordString)(ref.locator) })),
         surfaceAttempts: receipt.surfaceAttempts.map((attempt) => ({
             ...attempt,
             recipient: (0, session_events_1.capStructuredRecordString)(attempt.recipient),
             channel: (0, session_events_1.capStructuredRecordString)(attempt.channel),
+            ...(attempt.rawStatus ? { rawStatus: (0, session_events_1.capStructuredRecordString)(attempt.rawStatus) } : {}),
+            ...(attempt.error ? { error: (0, session_events_1.capStructuredRecordString)(attempt.error) } : {}),
         })),
         errors: receipt.errors.map((error) => (0, session_events_1.capStructuredRecordString)(error)),
     };
-    atomicWriteJson(path.join(receiptsDir(agentRoot), `${safeReceipt.runId}.json`), safeReceipt);
+}
+function normalizeHabitRunReceiptForWrite(receipt) {
+    return capHabitRunReceipt(receipt.schemaVersion === 1 ? normalizeLegacyHabitRunReceipt(receipt) : receipt);
+}
+function readHabitRunReceipt(agentRoot, runId) {
+    if (!isSafeHabitRunId(runId)) {
+        warnMalformedHabitReceipt(agentRoot, runId, "unsafe run id");
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(habitReceiptPath(agentRoot, runId), "utf-8"));
+        const receipt = isHabitRunReceipt(parsed)
+            ? parsed
+            : isLegacyHabitRunReceipt(parsed)
+                ? normalizeLegacyHabitRunReceipt(parsed)
+                : null;
+        if (!receipt) {
+            warnMalformedHabitReceipt(agentRoot, runId, "invalid habit receipt shape");
+            return null;
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.flight_recorder_habit_receipt_read",
+            message: "flight recorder habit receipt read",
+            meta: { agentRoot, runId },
+        });
+        return capHabitRunReceipt(receipt);
+    }
+    catch (error) {
+        warnMalformedHabitReceipt(agentRoot, runId, error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error));
+        return null;
+    }
+}
+function listHabitRunReceipts(agentRoot, options = {}) {
+    const dir = receiptsDir(agentRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const receipts = fs.readdirSync(dir)
+        .filter((fileName) => fileName.endsWith(".json"))
+        .map((fileName) => readHabitRunReceipt(agentRoot, path.basename(fileName, ".json")))
+        .filter((receipt) => receipt !== null)
+        .sort((left, right) => right.endedAt.localeCompare(left.endedAt) || right.runId.localeCompare(left.runId));
+    return typeof options.limit === "number" && options.limit >= 0 ? receipts.slice(0, options.limit) : receipts;
+}
+function writeHabitRunReceipt(agentRoot, receipt) {
+    fs.mkdirSync(receiptsDir(agentRoot), { recursive: true });
+    const safeReceipt = normalizeHabitRunReceiptForWrite(receipt);
+    if (!isSafeHabitRunId(safeReceipt.runId)) {
+        warnMalformedHabitReceipt(agentRoot, safeReceipt.runId, "unsafe run id");
+        throw new Error(`unsafe habit run id: ${safeReceipt.runId}`);
+    }
+    atomicWriteJson(habitReceiptPath(agentRoot, safeReceipt.runId), safeReceipt);
     recordFlightRecorderEvent(agentRoot, {
         kind: "habit_run",
         recordedAt: safeReceipt.endedAt,
         summary: `habit ${safeReceipt.habitName} finished with ${safeReceipt.outcome}`,
         producedRefs: safeReceipt.producedRefs,
-        meta: { receiptPath: path.join("arc", "flight-recorder", "habit-receipts", `${safeReceipt.runId}.json`) },
+        meta: {
+            receiptPath: path.join("arc", "flight-recorder", "habit-receipts", `${safeReceipt.runId}.json`),
+            operationId: safeReceipt.operationId ?? null,
+        },
     });
     (0, runtime_1.emitNervesEvent)({
         component: "mind",

package/dist/heart/core.js

@@ -6,6 +6,7 @@ exports.getModel = getModel;
 exports.getProvider = getProvider;
 exports.createSummarize = createSummarize;
 exports.getProviderDisplayLabel = getProviderDisplayLabel;
+exports.createHabitCallbackBuffer = createHabitCallbackBuffer;
 exports.isChatStyleChannel = isChatStyleChannel;
 exports.buildPonderResult = buildPonderResult;
 exports.isExternalStateQuery = isExternalStateQuery;
@@ -36,6 +37,7 @@ 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");
 const _providerRuntimes = {
@@ -185,6 +187,43 @@ function getProviderDisplayLabel(facing = "human") {
     };
     return providerLabelBuilders[provider]();
 }
+function createHabitCallbackBuffer(callbacks) {
+    const events = [];
+    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" }); },
+        },
+        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);
+        },
+    };
+}
 /**
  * Strip <think>...</think> blocks for the violation-detection check at the
  * end of a streaming turn. Used to tell legitimate text-only responses
@@ -215,6 +254,85 @@ function hasFreshPendingWork(options) {
     return pendingMessages.some((message) => typeof message?.content === "string"
         && message.content.trim().length > 0);
 }
+const HABIT_CONTROL_TOOLS = new Set(["rest", "ponder", "observe"]);
+function habitToolArgs(call) {
+    try {
+        const parsed = JSON.parse(call.arguments);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ok: false, reason: `habit tool '${call.name}' arguments must be a JSON object` };
+        }
+        return { ok: true, args: parsed };
+    }
+    catch {
+        return { ok: false, reason: `habit tool '${call.name}' has malformed JSON arguments` };
+    }
+}
+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;
+        const parsed = habitToolArgs(call);
+        const args = parsed.ok ? parsed.args : {};
+        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, activeToolNames) {
+    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 (!activeToolNames.has(call.name))
+            return `habit tool '${call.name}' was not advertised to this model turn`;
+        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`;
+        const parsed = habitToolArgs(call);
+        if (!parsed.ok)
+            return parsed.reason;
+        const riskProfile = (0, tools_1.riskProfileForToolName)(call.name, parsed.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: parsed.args,
+                friendStore: habitSession.friendStore,
+                delegatedOrigins,
+            });
+            if (!route.allowed)
+                return route.reason;
+        }
+    }
+    return null;
+}
 /** Chat-style channels expose the `speak` tool — outer human-conversation channels
  *  where mid-turn delivery is meaningful. Inner dialog has `ponder`. MCP returns
  *  synchronously. Mail is batch. Anything else (unknown channel) treats as non-chat. */
@@ -744,6 +862,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     // Augment tool context with reasoning effort controls from provider
     const baseToolContext = options?.toolContext
         ?? (options?.orientationFrame ? { signin: async () => undefined, orientationFrame: options.orientationFrame } : undefined);
+    const habitSession = options?.habitSession ?? baseToolContext?.habitSession;
     const augmentedToolContext = baseToolContext
         ? {
             ...baseToolContext,
@@ -751,8 +870,16 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             setReasoningEffort: (level) => { currentReasoningEffort = level; },
             activeWorkFrame: options?.activeWorkFrame,
             orientationFrame: options?.orientationFrame ?? baseToolContext.orientationFrame,
+            ...(habitSession ? { habitSession } : {}),
         }
-        : undefined;
+        : 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);
@@ -766,17 +893,25 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         // Inner dialog gets restTool instead of settleTool (rest = end turn, gated by attention queue).
         // toolChoiceRequired only controls whether tool_choice: "required" is set in the API call.
         const isInnerDialog = channel === "inner";
+        const innerHabitCanSendMessage = isInnerDialog
+            && habitSession?.toolPolicy.outwardMessagingAllowed === true
+            && habitSession.toolPolicy.grantedTools.includes("send_message");
+        const innerHabitCanSurface = isInnerDialog
+            && (!habitSession || (habitSession.toolPolicy.outwardMessagingAllowed === true
+                && habitSession.toolPolicy.grantedTools.includes("surface")));
         const filteredBaseTools = isInnerDialog
-            ? baseTools.filter((t) => t.function.name !== "send_message")
+            ? baseTools.filter((t) => innerHabitCanSendMessage || t.function.name !== "send_message")
             : baseTools;
         const activeTools = [
             ...filteredBaseTools,
             tools_1.ponderTool,
-            ...(isInnerDialog ? [tools_2.surfaceToolDef, tools_1.restTool] : []),
+            ...(isInnerDialog && innerHabitCanSurface ? [tools_2.surfaceToolDef] : []),
+            ...(isInnerDialog ? [tools_1.restTool] : []),
             ...(!isInnerDialog ? [tools_1.observeTool] : []),
             ...(!isInnerDialog ? [tools_1.settleTool] : []),
             ...(isChatStyleChannel(channel ?? "") ? [tools_1.speakTool] : []),
         ];
+        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");
@@ -803,13 +938,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             break;
         }
         try {
+            const habitCallbackBufferRef = { current: null };
             const callProviderTurn = async () => {
                 callbacks.onModelStart();
+                habitCallbackBufferRef.current = habitSession ? createHabitCallbackBuffer(callbacks) : null;
                 try {
                     return await providerRuntime.streamTurn({
                         messages,
                         activeTools,
-                        callbacks,
+                        callbacks: habitCallbackBufferRef.current?.callbacks ?? callbacks,
                         signal,
                         traceId,
                         toolChoiceRequired,
@@ -819,6 +956,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     });
                 }
                 catch (error) {
+                    habitCallbackBufferRef.current?.discard();
+                    habitCallbackBufferRef.current = null;
                     if (signal?.aborted)
                         throw new provider_attempt_1.ProviderAttemptAbortError();
                     throw error;
@@ -890,6 +1029,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 continue;
             }
             const result = attempt.value;
+            const streamCallbackBuffer = habitCallbackBufferRef.current;
+            habitCallbackBufferRef.current = null;
             // Track usage from the latest API call
             if (result.usage)
                 lastUsage = result.usage;
@@ -968,6 +1109,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 })
                 : null;
             if (!result.toolCalls.length) {
+                await streamCallbackBuffer?.flush();
                 if (privateReturnTextAckRetryError) {
                     callbacks.onClearText?.();
                     if (noToolCallRetries < NO_TOOL_CALL_MAX_RETRIES) {
@@ -1050,6 +1192,26 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             else {
                 // Reset the retry counter on any successful tool call.
                 noToolCallRetries = 0;
+                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins, activeToolNames);
+                if (habitBlockReason) {
+                    streamCallbackBuffer?.discard();
+                    recordBlockedHabitSurfaceAttempts(habitSession, result.toolCalls, habitBlockReason);
+                    messages.push(msg);
+                    const blockedOutput = `blocked: ${habitBlockReason}. No tool side effects from this assistant message were executed.`;
+                    for (const call of result.toolCalls) {
+                        messages.push({ 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;
+                }
+                await streamCallbackBuffer?.flush();
                 // Check for settle sole call: intercept before tool execution
                 if (isSoleSettle) {
                     /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
@@ -1501,6 +1663,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     catch (e) {
                         toolResult = `error: ${e}`;
                         success = false;
+                        augmentedToolContext?.habitSession?.recordError?.(toolResult);
                     }
                     toolResult = (0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger);
                     (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, toolResult, success);