@adonis-agora/agent 0.60.1 → 0.61.0

package/dist/src/agent-loop.js

@@ -1,9 +1,14 @@
+import { createHash } from 'node:crypto';
+import { resolveActionProposalApproval } from './action-proposal-approval.js';
+import { prepareActionProposal } from './action-proposal-preparation.js';
+import { actionProposalReceipt } from './action-proposal-receipt.js';
 import { danglingToolCallIds, settleDanglingToolCalls } from './dangling-tool-calls.js';
 import { detachedDelivered, detachedStarted, } from './delegation.js';
 import { publishAgentDelegated, publishAgentMessage, publishAgentRetrieved, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, spannedAgent, } from './diagnostics.js';
 import { ASK_TOOL_NAME, askInputSchema, askToolDefinition, DEFAULT_INTAKE_PREAMBLE, isHumanDecision, normalizeElicitationReply, settleElicitation, } from './elicitation.js';
 import { buildMemoryBlock, offerMemories, REMEMBER_TOOL_NAME, rememberInputSchema, rememberToolDefinition, writeMemory, } from './memory.js';
-import { intersectAllowLists, personaFromTurn } from './personas.js';
+import { createNegotiatedUiCollector } from './negotiated-tool-ui.js';
+import { personaFromTurn } from './personas.js';
 import { createFrameBuffer, createIncrementalGate, gateTail, releaseGatedFrames, resolveGateLookback, resolveOutputGateMode, runInputProcessors, runOutputProcessors, } from './processors.js';
 import { isReplayIntegrityError } from './replay-integrity.js';
 import { buildSkillsBlock, loadSkill, offerSkills, SKILL_TOOL_NAME, skillInputSchema, skillToolDefinition, } from './skills.js';
@@ -12,9 +17,9 @@ import { withSelectedModel } from './spi/model-catalog.js';
 import { estimateCost, resolveModelPrice, } from './spi/pricing-store.js';
 import { OutputRejectedError, } from './spi/processors.js';
 import { DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, repairInstruction, StructuredOutputError, validateStructured, } from './structured-output.js';
-import { ToolForbiddenError, ToolInputInvalidError } from './tool-registry.js';
+import { ToolForbiddenError, ToolInputInvalidError, ToolPreflightDeniedError, } from './tool-registry.js';
 import { invokeWithTransientRetry } from './tool-retry.js';
-import { createNoopEmitUi, createUiCollector, mergeUi, unwrapToolStepOutput, wrapToolStepOutput, } from './tool-ui.js';
+import { createNoopEmitUi, escapeUnsafeToolUiText, mergeUi, unwrapToolStepOutput, wrapToolStepOutput, } from './tool-ui.js';
 import { observeTurnFrames, withTurnFrames } from './turn-frames.js';
 /** Renders retrieved passages as a numbered, citable context block appended to the system prompt. */
 function buildContextBlock(passages) {
@@ -93,6 +98,7 @@ function promptContext(input, persona) {
         actor: input.actor,
         ...(persona !== undefined ? { persona: personaFromTurn(persona) } : {}),
         ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+        ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
     };
 }
 /**
@@ -313,6 +319,7 @@ function threadForTurn(recorded) {
     const messages = settleDanglingToolCalls((recorded?.messages ?? []).map(toModelMessage));
     return {
         messages,
+        actionApprovalMode: recorded?.actionApprovalMode ?? 'blocking',
         title: recorded?.title ?? null,
         hasAssistantMessage: recorded?.hasAssistantMessage ?? messages.some((message) => message.role === 'assistant'),
     };
@@ -622,6 +629,7 @@ function elicitationContext(deps, input, hooks) {
         ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
         ...personaContext(input),
         ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+        ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
         ...(deps.host !== undefined ? { host: deps.host } : {}),
     };
 }
@@ -653,6 +661,20 @@ const MESSAGE_TOOL_RESULTS_PATCH = 'agent:message-tool-results';
 async function claimToolCall(turn, call) {
     const { deps, input, hooks, messageId, writer } = turn;
     const persona = personaOf(input);
+    const ctx = {
+        actor: input.actor,
+        threadId: input.threadId,
+        runId: hooks.runId,
+        requestId: hooks.runId,
+        // Replaced by the call's own collector inside its `tool:` step (see invokeClaimedTool); a
+        // kind that never reaches a handler keeps this no-op.
+        emitUi: createNoopEmitUi(call.id),
+        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+        ...(persona !== undefined ? { persona } : {}),
+        ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+        ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
+        ...(deps.host !== undefined ? { host: deps.host } : {}),
+    };
     const persisted = (await hooks.step(`persist:toolcall:${call.id}`, async () => {
         // The kind the llm checkpoint stamped WINS: it came from the process that offered the tool,
         // whereas this one is only the process claiming the call — and the two disagree exactly when
@@ -682,15 +704,138 @@ async function claimToolCall(turn, call) {
         // set can both change while a run is parked, and the branch below (park or run) has to be the
         // one the journal recorded. A run claimed before this existed reads `approval` back as
         // undefined and waits on the requester, exactly as it did.
-        const approval = kind === 'action' ? await claimApproval(turn, call) : undefined;
-        const parks = kind === 'ask' || approval?.mode === 'ask';
+        let actionApproval = call.actionApproval;
+        if (kind === 'action' &&
+            turn.actionApprovalMode === 'independent' &&
+            actionApproval === undefined)
+            actionApproval = await resolveActionProposalApproval({
+                actor: input.actor,
+                thread: {
+                    threadId: input.threadId,
+                    runId: hooks.runId,
+                    ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                },
+                tool: {
+                    name: call.name,
+                    kind: 'action',
+                    ...(deps.registry.spec(call.name) !== undefined
+                        ? { spec: deps.registry.spec(call.name) }
+                        : {}),
+                },
+                store: deps.store,
+                ...(deps.approvalPolicy !== undefined ? { policy: deps.approvalPolicy } : {}),
+            });
+        let preflight = call.preflight;
+        let prepared = call.prepared;
+        if (kind === 'action' && preflight === undefined && deps.registry.has(call.name)) {
+            try {
+                const allowedTools = intersectAllow(persona?.allowedTools, deps.toolAllowList);
+                if (turn.actionApprovalMode === 'independent' && actionApproval?.mode === 'ask') {
+                    prepared = await prepareActionProposal(deps.registry, call.name, call.input, { ...ctx, toolCallId: call.id, idempotencyKey: `${hooks.runId}:${call.id}` }, deps.rolesPolicy, allowedTools === undefined ? {} : { allowedTools });
+                    preflight = prepared.preflight;
+                }
+                else
+                    preflight = await deps.registry.prepare(call.name, call.input, {
+                        ...ctx,
+                        toolCallId: call.id,
+                        idempotencyKey: `${hooks.runId}:${call.id}`,
+                    }, deps.rolesPolicy, allowedTools === undefined ? {} : { allowedTools });
+            }
+            catch (error) {
+                if (isReplayIntegrityError(error) || hooks.isControlFlowError?.(error) === true)
+                    throw error;
+                preflight = {
+                    status: 'failed',
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        const early = preflight !== undefined && preflight.status !== 'ready';
+        let confirmation = preflight?.status === 'ready' ? preflight.confirmation : undefined;
+        const approval = kind === 'action' && !early
+            ? (actionApproval ?? (await claimApproval(turn, call)))
+            : undefined;
+        let proposalId;
+        if (turn.actionApprovalMode === 'independent' && approval?.mode === 'ask') {
+            if (!prepared)
+                throw new Error('Independent action lacks trusted prepared input');
+            const store = deps.store;
+            if (typeof store.createActionProposal !== 'function')
+                throw new Error('Independent proposal store unavailable');
+            proposalId = `proposal-${createHash('sha256')
+                .update(JSON.stringify([hooks.runId, call.id]))
+                .digest('hex')}`;
+            const display = confirmation ??
+                deps.registry.spec(call.name)?.presentation?.confirm ?? {
+                title: `Allow ${call.name}?`,
+                verb: 'Approve',
+            };
+            const fill = (value) => value.replace(/\{([^}]+)\}/g, (_match, path) => {
+                let current = prepared.input;
+                for (const part of path.split('.'))
+                    current =
+                        current !== null && typeof current === 'object'
+                            ? current[part]
+                            : undefined;
+                return current === undefined ? '' : String(current);
+            });
+            const create = prepared.replacementKey === undefined
+                ? store.createActionProposal.bind(store)
+                : store.createReplacingActionProposal.bind(store);
+            const created = await create({
+                ...(prepared.replacementKey !== undefined
+                    ? { replacementKey: prepared.replacementKey }
+                    : {}),
+                id: proposalId,
+                tenantRef: input.actor.tenantRef ?? null,
+                actorRef: input.actor.id,
+                threadId: input.threadId,
+                originRunId: hooks.runId,
+                originMessageId: messageId,
+                originToolCallId: call.id,
+                toolName: call.name,
+                input: prepared.input,
+                preparationInput: prepared.preparationInput,
+                executionContext: {
+                    requestId: hooks.runId,
+                    ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                    ...(persona !== undefined ? { persona: persona.id } : {}),
+                    ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+                    ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
+                },
+                confirmation: confirmation ?? {
+                    title: fill(display.title),
+                    verb: fill(display.verb),
+                    ...(display.detail !== undefined ? { detail: fill(display.detail) } : {}),
+                },
+                approver: approval.approver,
+                expiresAt: approval.expiresAt === undefined ? null : Date.parse(approval.expiresAt),
+                idempotencyKey: `${hooks.runId}:${call.id}`,
+            });
+            if (created.status === 'conflict')
+                throw new Error('Action proposal replay payload conflict');
+            confirmation = created.proposal?.confirmation ?? confirmation;
+        }
+        const parks = kind === 'ask' || (approval?.mode === 'ask' && proposalId === undefined);
         await deps.store.recordToolCall({
             toolCallId: call.id,
             messageId,
             toolName: call.name,
             toolType: awaitsHuman ? 'action' : 'read',
             input: call.input,
-            status: parks ? 'pending_approval' : 'auto_executed',
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            status: proposalId !== undefined
+                ? 'proposed'
+                : early
+                    ? preflight?.status === 'denied'
+                        ? 'rejected'
+                        : preflight?.status === 'failed'
+                            ? 'failed'
+                            : 'executed'
+                    : parks
+                        ? 'pending_approval'
+                        : 'auto_executed',
+            ...(confirmation !== undefined ? { confirmation } : {}),
             runId: hooks.runId,
             ...(approval !== undefined && approval.mode !== 'auto'
                 ? { approver: approval.approver }
@@ -699,6 +844,19 @@ async function claimToolCall(turn, call) {
                 ? { expiresAt: approval.expiresAt }
                 : {}),
         });
+        if (early) {
+            await deps.store.updateToolCall({
+                toolCallId: call.id,
+                status: preflight?.status === 'denied'
+                    ? 'rejected'
+                    : preflight?.status === 'failed'
+                        ? 'failed'
+                        : 'executed',
+                ...(preflight?.status === 'completed' ? { output: preflight.output } : {}),
+                ...(preflight?.status === 'denied' ? { error: preflight.reason } : {}),
+                ...(preflight?.status === 'failed' ? { error: preflight.error } : {}),
+            });
+        }
         // Written from INSIDE this checkpoint, so the frame is streamed once and a replay — which
         // returns the memoized result without re-running the body — never re-posts a form for a
         // decision already made. That is also why it spends no position of its own.
@@ -708,11 +866,15 @@ async function claimToolCall(turn, call) {
         if (approval?.mode === 'ask') {
             await writer.write({
                 t: 'approval',
+                ...(proposalId !== undefined
+                    ? { target: { kind: 'proposal', proposalId } }
+                    : {}),
                 runId: hooks.runId,
                 id: call.id,
                 toolName: call.name,
                 input: call.input,
                 approver: approval.approver,
+                ...(confirmation !== undefined ? { confirmation } : {}),
                 ...(approval.expiresAt !== undefined ? { expiresAt: approval.expiresAt } : {}),
             });
         }
@@ -721,6 +883,8 @@ async function claimToolCall(turn, call) {
         const terminal = deps.registry.spec(call.name)?.terminal === true;
         return {
             kind,
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(preflight !== undefined ? { preflight } : {}),
             ...(approval !== undefined ? { approval } : {}),
             ...(terminal ? { terminal: true } : {}),
         };
@@ -732,24 +896,14 @@ async function claimToolCall(turn, call) {
     return {
         call,
         toolType,
+        ...(persisted?.preflight !== undefined ? { preflight: persisted.preflight } : {}),
         ...(persisted?.terminal === true ? { terminal: true } : {}),
+        ...(persisted?.proposalId !== undefined ? { proposalId: persisted.proposalId } : {}),
         ...(persisted?.delegation !== undefined ? { delegation: persisted.delegation } : {}),
         ...(toolType === 'action' && persisted?.approval !== undefined
             ? { approval: persisted.approval }
             : {}),
-        ctx: {
-            actor: input.actor,
-            threadId: input.threadId,
-            runId: hooks.runId,
-            requestId: hooks.runId,
-            // Replaced by the call's own collector inside its `tool:` step (see invokeClaimedTool); a
-            // kind that never reaches a handler keeps this no-op.
-            emitUi: createNoopEmitUi(call.id),
-            ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
-            ...(persona !== undefined ? { persona } : {}),
-            ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
-            ...(deps.host !== undefined ? { host: deps.host } : {}),
-        },
+        ctx,
     };
 }
 /**
@@ -814,17 +968,19 @@ function spanToolType(kind) {
 async function invokeClaimedTool(turn, claimed) {
     const { deps, hooks } = turn;
     const { call, ctx, toolType } = claimed;
-    // Under a persona with an allow-list, the same narrowing the offer had — agent ∩ persona — is what
-    // `invoke` holds the call to. Without one, nothing new is checked.
-    const personaAllow = personaOf(turn.input)?.allowedTools;
-    const invokeOptions = personaAllow === undefined
-        ? {}
-        : { allowedTools: intersectAllowLists(deps.toolAllowList, personaAllow) ?? [] };
+    // Execution retains every narrowing the offer and preparation had, including an agent-only list.
+    const allowedTools = intersectAllow(personaOf(turn.input)?.allowedTools, deps.toolAllowList);
+    const invokeOptions = allowedTools === undefined ? {} : { allowedTools };
     try {
         const raw = await hooks.step(`tool:${call.id}`, async () => {
             // Pushed components stream as they happen and ride this step's RESULT into the journal (see
             // `wrapToolStepOutput`), so a replay neither re-streams nor re-persists them.
-            const ui = createUiCollector(call.id, turn.writer);
+            const ui = createNegotiatedUiCollector(call.id, {
+                actor: ctx.actor,
+                threadId: ctx.threadId,
+                ...(ctx.agentName !== undefined ? { agentName: ctx.agentName } : {}),
+                ...(ctx.uiCapabilities !== undefined ? { uiCapabilities: ctx.uiCapabilities } : {}),
+            }, deps.resolveUiCatalog, turn.writer);
             const toolCtx = {
                 ...ctx,
                 // The same for every execution of THIS call (a replay after a crash, a transient retry).
@@ -838,31 +994,50 @@ async function invokeClaimedTool(turn, claimed) {
                         : { value: data });
                 },
             };
-            const output = await spannedAgent('tool.execution', hooks.runId, {
-                runId: hooks.runId,
-                toolCallId: call.id,
-                toolName: call.name,
-                toolType: spanToolType(toolType),
-            }, () => invokeWithTransientRetry(() => {
-                ui.restart();
-                return deps.registry.invoke(call.name, call.input, toolCtx, deps.rolesPolicy, invokeOptions);
-            }, deps.toolTransientRetry ?? {}, {
-                ...(hooks.isControlFlowError !== undefined
-                    ? { isControlFlowError: hooks.isControlFlowError }
-                    : {}),
-                onRetry: (attempt, retryError) => {
-                    publishAgentToolRetry({
-                        runId: hooks.runId,
-                        toolName: call.name,
-                        toolCallId: call.id,
-                        attempt,
-                        message: retryError instanceof Error ? retryError.message : String(retryError),
-                    });
-                },
-            }), () => ({}));
-            return wrapToolStepOutput(output, ui.components());
+            let output;
+            try {
+                output = await spannedAgent('tool.execution', hooks.runId, {
+                    runId: hooks.runId,
+                    toolCallId: call.id,
+                    toolName: call.name,
+                    toolType: spanToolType(toolType),
+                }, () => invokeWithTransientRetry(() => {
+                    ui.restart();
+                    return deps.registry.invoke(call.name, call.input, toolCtx, deps.rolesPolicy, invokeOptions);
+                }, deps.toolTransientRetry ?? {}, {
+                    ...(hooks.isControlFlowError !== undefined
+                        ? { isControlFlowError: hooks.isControlFlowError }
+                        : {}),
+                    onRetry: (attempt, retryError) => {
+                        publishAgentToolRetry({
+                            runId: hooks.runId,
+                            toolName: call.name,
+                            toolCallId: call.id,
+                            attempt,
+                            message: retryError instanceof Error ? retryError.message : String(retryError),
+                        });
+                    },
+                }), () => ({}));
+            }
+            catch (error) {
+                // A domain refusal is a settled result, so a durable replay must not re-run the check.
+                if (!(error instanceof ToolPreflightDeniedError))
+                    throw error;
+                return { '@@adonis-agent/tool-preflight-denied': 1, reason: error.reason };
+            }
+            return wrapToolStepOutput(output, ui.components(), ui.text());
         });
-        const { output, ui } = unwrapToolStepOutput(raw);
+        if (typeof raw === 'object' &&
+            raw !== null &&
+            '@@adonis-agent/tool-preflight-denied' in raw &&
+            raw['@@adonis-agent/tool-preflight-denied'] === 1 &&
+            'reason' in raw &&
+            typeof raw.reason === 'string') {
+            return { status: 'failed', error: raw.reason, denied: true };
+        }
+        const { output, ui, text } = unwrapToolStepOutput(raw);
+        if (text)
+            turn.toolText.set(call.id, text);
         if (ui.length > 0) {
             turn.toolUi.set(call.id, ui);
         }
@@ -875,7 +1050,11 @@ async function invokeClaimedTool(turn, claimed) {
         if (isReplayIntegrityError(error) || hooks.isControlFlowError?.(error) === true) {
             throw error;
         }
-        return { status: 'failed', error: error instanceof Error ? error.message : String(error) };
+        return {
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+            ...(error instanceof ToolPreflightDeniedError ? { denied: true } : {}),
+        };
     }
 }
 /** Persist one settled invocation and shape the result the model is fed. */
@@ -922,7 +1101,13 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef = turn.input
             await settle();
         });
         publishAgentToolCall({ runId: hooks.runId, toolName: call.name, toolType, status: 'failed' });
-        return { id: call.id, name: call.name, output: null, error: outcome.error };
+        return {
+            id: call.id,
+            name: call.name,
+            output: outcome.denied ? { reason: outcome.error } : null,
+            error: outcome.error,
+            ...(outcome.denied ? { denied: true } : {}),
+        };
     }
     await hooks.step(`persist:toolexec:${call.id}`, async () => {
         await deps.store.updateToolCall({
@@ -986,14 +1171,95 @@ async function delegateToolCall(turn, claimed) {
  * what puts the kind in the journal — so the branch a call takes is a fact about the turn rather
  * than about whichever process happened to replay it (see {@link claimToolCall}).
  *
- * Only unstamped calls are touched: a kind already on a call was settled upstream, and a process
- * further down never second-guesses it.
+ * Provider-supplied preparation is discarded. The trusted result rides this same model checkpoint
+ * so a process that first claims the call without its handler still follows the offering process's verdict.
  */
-function stampToolKinds(result, deps) {
-    return {
-        ...result,
-        toolCalls: result.toolCalls.map((call) => call.kind === undefined ? { ...call, kind: declaredKind(deps, call.name) } : call),
-    };
+async function stampToolKinds(result, deps, input, hooks) {
+    const persona = personaOf(input);
+    const allowedTools = intersectAllow(persona?.allowedTools, deps.toolAllowList);
+    const toolCalls = [];
+    for (const incoming of result.toolCalls) {
+        // The provider cannot supply trusted preparation. Resolve it only where the tool was offered.
+        const { preflight: _untrusted, prepared: _untrustedPrepared, actionApproval: _untrustedApproval, ...call } = incoming;
+        const kind = declaredKind(deps, call.name);
+        let preflight;
+        let prepared;
+        let actionApproval;
+        if (kind === 'action') {
+            try {
+                if (deps.actionApprovalMode === 'independent')
+                    actionApproval = await resolveActionProposalApproval({
+                        actor: input.actor,
+                        thread: {
+                            threadId: input.threadId,
+                            runId: hooks.runId,
+                            ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                        },
+                        tool: {
+                            name: call.name,
+                            kind: 'action',
+                            ...(deps.registry.spec(call.name) !== undefined
+                                ? { spec: deps.registry.spec(call.name) }
+                                : {}),
+                        },
+                        store: deps.store,
+                        ...(deps.approvalPolicy !== undefined ? { policy: deps.approvalPolicy } : {}),
+                    });
+                if (deps.actionApprovalMode === 'independent' && actionApproval?.mode === 'ask') {
+                    prepared = await prepareActionProposal(deps.registry, call.name, call.input, {
+                        actor: input.actor,
+                        threadId: input.threadId,
+                        runId: hooks.runId,
+                        requestId: hooks.runId,
+                        toolCallId: call.id,
+                        idempotencyKey: `${hooks.runId}:${call.id}`,
+                        emitUi: createNoopEmitUi(call.id),
+                        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                        ...(persona !== undefined ? { persona } : {}),
+                        ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+                        ...(input.uiCapabilities !== undefined
+                            ? { uiCapabilities: input.uiCapabilities }
+                            : {}),
+                        ...(deps.host !== undefined ? { host: deps.host } : {}),
+                    }, deps.rolesPolicy, allowedTools === undefined ? {} : { allowedTools });
+                    preflight = prepared.preflight;
+                }
+                else
+                    preflight = await deps.registry.prepare(call.name, call.input, {
+                        actor: input.actor,
+                        threadId: input.threadId,
+                        runId: hooks.runId,
+                        requestId: hooks.runId,
+                        toolCallId: call.id,
+                        idempotencyKey: `${hooks.runId}:${call.id}`,
+                        emitUi: createNoopEmitUi(call.id),
+                        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+                        ...(persona !== undefined ? { persona } : {}),
+                        ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+                        ...(input.uiCapabilities !== undefined
+                            ? { uiCapabilities: input.uiCapabilities }
+                            : {}),
+                        ...(deps.host !== undefined ? { host: deps.host } : {}),
+                    }, deps.rolesPolicy, allowedTools === undefined ? {} : { allowedTools });
+            }
+            catch (error) {
+                if (isReplayIntegrityError(error) || hooks.isControlFlowError?.(error) === true)
+                    throw error;
+                preflight = {
+                    status: 'failed',
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        toolCalls.push({
+            ...call,
+            ...(actionApproval !== undefined ? { actionApproval } : {}),
+            kind,
+            ...(prepared !== undefined ? { prepared } : {}),
+            ...(preflight !== undefined ? { preflight } : {}),
+        });
+    }
+    return { ...result, toolCalls };
 }
 /**
  * A call's declared kind, resolved from this process's own configuration and registry.
@@ -1077,6 +1343,7 @@ function skillContext(input) {
         threadId: input.threadId,
         ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
         ...(input.pageContext !== undefined ? { pageContext: input.pageContext } : {}),
+        ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
     };
 }
 /**
@@ -1200,6 +1467,26 @@ function invokeClaimed(turn, claimed) {
 async function runClaimedToolCall(turn, claimed) {
     const { deps, hooks } = turn;
     const { call, toolType, ctx } = claimed;
+    if (claimed.proposalId !== undefined) {
+        turn.halt.independentProposal = true;
+        return { id: call.id, name: call.name, output: actionProposalReceipt(claimed.proposalId) };
+    }
+    if (claimed.preflight !== undefined && claimed.preflight.status !== 'ready') {
+        const result = claimed.preflight;
+        if (result.status === 'completed') {
+            if (claimed.terminal === true)
+                turn.halt.terminal = true;
+            return { id: call.id, name: call.name, output: result.output };
+        }
+        const reason = result.status === 'denied' ? result.reason : result.error;
+        return {
+            id: call.id,
+            name: call.name,
+            output: result.status === 'denied' ? { reason } : null,
+            error: reason,
+            ...(result.status === 'denied' ? { denied: true } : {}),
+        };
+    }
     if (toolType === 'agent') {
         return delegateToolCall(turn, claimed);
     }
@@ -1704,7 +1991,9 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
             ...(input.attachments !== undefined ? { attachments: input.attachments } : {}),
         }));
     }
-    const thread = threadForTurn(await hooks.step('load:thread', () => readThreadForTurn(deps, input.threadId, turnMessageLimit(deps.historyWindow))));
+    const thread = threadForTurn(await hooks.step('load:thread', () => readThreadForTurn(deps, input.threadId, turnMessageLimit(deps.historyWindow)).then((loaded) => loaded === null
+        ? { messages: [], actionApprovalMode: deps.actionApprovalMode ?? 'blocking' }
+        : { ...loaded, actionApprovalMode: deps.actionApprovalMode ?? 'blocking' })));
     // With no window configured this whole block is skipped, so an existing deployment sends the
     // messages `load:thread` returned and records byte-identical checkpoints.
     let modelMessages = thread.messages;
@@ -1884,6 +2173,7 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
         const tools = withBuiltInTools({
             tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, intersectAllow(persona?.allowedTools, deps.toolAllowList), {
                 threadId: input.threadId,
+                ...(input.uiCapabilities !== undefined ? { uiCapabilities: input.uiCapabilities } : {}),
                 ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
             }),
             ask: deps.ask,
@@ -1945,7 +2235,7 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
             outputTokens: result.usage.outputTokens,
             textLength: result.text.length,
             toolCalls: result.toolCalls.length,
-        })), deps));
+        })), { ...deps, actionApprovalMode: thread.actionApprovalMode ?? 'blocking' }, input, hooks));
         // The gate runs before ANYTHING downstream: before the held frames reach the subscriber, before
         // the assistant message is persisted, before this text becomes the next step's context.
         let rejection;
@@ -2171,7 +2461,9 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
             messageId: assistant.id,
             writer,
             toolUi: new Map(),
+            toolText: new Map(),
             halt: { terminal: false },
+            actionApprovalMode: thread.actionApprovalMode ?? 'blocking',
             ...(skillOffer !== undefined ? { skills: skillOffer } : {}),
             ...(memoryDigest !== undefined ? { memory: memoryDigest } : {}),
         };
@@ -2231,6 +2523,16 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
                 await deps.store.setMessageToolResults(assistant.id, [...results, ...syntheticResults]);
                 // What the tools pushed joins what the model turn streamed, on the same message, in call
                 // order. Every list here was read off a checkpoint above, so a replay writes the same value.
+                const fallbackText = escapeUnsafeToolUiText(turn.toolCalls
+                    .map((call) => turnCalls.toolText.get(call.id))
+                    .filter(Boolean)
+                    .join('\n'));
+                if (fallbackText)
+                    await deps.store.appendMessage({
+                        threadId: input.threadId,
+                        role: 'assistant',
+                        content: fallbackText,
+                    });
                 const toolUi = turn.toolCalls.flatMap((call) => turnCalls.toolUi.get(call.id) ?? []);
                 if (toolUi.length > 0) {
                     await deps.store.setMessageUi?.(assistant.id, mergeUi(turn.ui, toolUi));
@@ -2244,9 +2546,17 @@ export async function runAgentLoop(boundDeps, requested, hooks) {
             });
         }
         modelMessages.push({ role: 'user', content: '', toolResults: results });
+        const toolText = escapeUnsafeToolUiText(turn.toolCalls
+            .map((call) => turnCalls.toolText.get(call.id))
+            .filter(Boolean)
+            .join('\n'));
+        if (toolText) {
+            modelMessages.push({ role: 'assistant', content: toolText });
+            lastText += `\n${toolText}`;
+        }
         // A `terminal` tool succeeded: its effect is the answer, so no model call narrates it. Read off
         // the calls' `persist:toolcall` checkpoints and their outcomes, so a replay ends here too.
-        if (turnCalls.halt.terminal) {
+        if (turnCalls.halt.terminal || turnCalls.halt.independentProposal) {
             break;
         }
     }