@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/node_modules/@happier-dev/protocol/dist/actions/actionExecutor.js

@@ -1,18 +1,142 @@
-import { findActionInputFieldHint, filterResolvedActionOptions, getActionSpecForCatalogSurface, getSerializedActionSpecForSurface, searchSerializedActionSpecsForSurface, serializeActionFieldOptions, } from './actionCatalog.js';
+import { findActionInputFieldHint, filterResolvedActionOptions, searchSerializedActionSpecsForSurface, serializeActionFieldOptions, serializeActionSpec, } from './actionCatalog.js';
+import { resolveActionApprovalRouting } from './actionApprovalPolicy.js';
+import { resolveActionOptionSourceRoute } from './actionOptionSources.js';
 import { resolveRequestedSessionModeId } from './sessionModeIds.js';
-import { ActionSurfaceSchema, getActionSpec, isActionSpecSurfacedOn } from './actionSpecs.js';
-import { ApprovalRequestV1Schema } from '../approvals/approvalRequestV1.js';
-import { BackendTargetKeySchema, buildBackendTargetKey, parseBackendTargetKey } from '../backendTargets/backendTargetRef.js';
+import { ActionSurfaceSchema, getActionSpec, } from './actionSpecs.js';
+import { resolveActionSurfaceAvailability } from './actionSurfaceAvailability.js';
+import { resolveActionApprovalFlow } from './actionApprovalMetadata.js';
+import { ApprovalRequestOriginV1Schema, ApprovalRequestV1Schema } from '../approvals/approvalRequestV1.js';
+import { BackendTargetKeySchema, BackendTargetRefSchema, buildBackendTargetKey, parseBackendTargetKey } from '../backendTargets/backendTargetRef.js';
 import { SessionHandoffWorkspaceTransferSchema, } from '../sessionControl/handoff/handoffSchemas.js';
-import { SessionControlErrorCodeSchema } from '../sessionControl/contract.js';
+import { SessionControlErrorCodeSchema, normalizeSessionUsageLimitRecoveryOperationResultV1, } from '../sessionControl/contract.js';
+import { assertNonEscalatingPermissionMode, resolveNearestPermissionModeAtOrBelow, } from './permissionPrivilege.js';
+import { PendingRequestedActionV1Schema, } from '../sessionMessages/pendingRequestedActionV1.js';
+import { normalizeConnectedServiceSelectionInput } from '../connect/normalizeConnectedServiceSelectionInput.js';
+import { mergeSpawnConfigOptionAliases, } from './sessionSpawnConfigOptions.js';
+import { EXECUTION_RUN_ACTION_PERMISSION_MODES } from './executionRunActionPermissionMode.js';
+/**
+ * Resolve the canonical run-start model + config-option selection from an agent-facing action
+ * input, reusing the SAME merge owner as session spawn (`mergeSpawnConfigOptionAliases`). Returns
+ * the canonical `sessionConfigOptionOverrides` (merging any `configOptions` shorthand) plus the
+ * `modelId`. A conflicting value supplied in both the shorthand and canonical forms is a typed
+ * `invalid_parameters` rejection — never a silent drop.
+ */
+function resolveRunStartModelAndConfig(input) {
+    const modelIdRaw = input.modelId;
+    const modelId = typeof modelIdRaw === 'string' && modelIdRaw.trim().length > 0 ? modelIdRaw : undefined;
+    const merged = mergeSpawnConfigOptionAliases({
+        sessionConfigOptionOverrides: input.sessionConfigOptionOverrides ?? null,
+        configOptions: input.configOptions ?? null,
+    });
+    if (!merged.ok) {
+        const optionIds = merged.conflicts.map((conflict) => conflict.optionId).join(', ');
+        return { ok: false, error: `configOptions must agree with sessionConfigOptionOverrides (${optionIds})` };
+    }
+    return {
+        ok: true,
+        ...(modelId ? { modelId } : {}),
+        ...(merged.value ? { sessionConfigOptionOverrides: merged.value } : {}),
+    };
+}
 function normalizeId(raw) {
     return String(raw ?? '').trim();
 }
+function resolveExecutionRunLaunchOrigin(ctx) {
+    if (ctx.surface === 'session_agent') {
+        const sessionId = normalizeId(ctx.approvalOrigin?.sessionId) || normalizeId(ctx.defaultSessionId);
+        return sessionId ? { kind: 'session', sessionId } : { kind: 'external' };
+    }
+    if (ctx.surface === 'cli' || ctx.surface === 'mcp') {
+        return { kind: 'external', source: ctx.surface };
+    }
+    return ctx.surface ? { kind: 'external', source: 'action' } : { kind: 'external' };
+}
+function readOpaqueIdentifier(raw) {
+    return typeof raw === 'string' && raw.trim().length > 0 ? raw : '';
+}
+function normalizeUsageLimitActionResult(result, sessionId) {
+    return normalizeSessionUsageLimitRecoveryOperationResultV1(result, { sessionId });
+}
+function resolveApprovalOriginForRequest(rawOrigin, expectedSessionId) {
+    if (rawOrigin == null)
+        return null;
+    const parsed = ApprovalRequestOriginV1Schema.safeParse(rawOrigin);
+    if (!parsed.success)
+        return null;
+    const normalizedExpectedSessionId = normalizeId(expectedSessionId);
+    if (normalizedExpectedSessionId && parsed.data.sessionId !== normalizedExpectedSessionId) {
+        return null;
+    }
+    return parsed.data;
+}
+function resolvePolicyApprovalRequestingSessionId(rawOrigin, ctx, targetSessionId) {
+    const origin = resolveApprovalOriginForRequest(rawOrigin, null);
+    const originSessionId = normalizeId(origin?.sessionId);
+    if (originSessionId)
+        return originSessionId;
+    const defaultSessionId = normalizeId(ctx.defaultSessionId);
+    if (defaultSessionId)
+        return defaultSessionId;
+    return targetSessionId;
+}
+function resolveExplicitApprovalRequestingSessionId(rawOrigin, ctx, targetSessionId) {
+    const defaultSessionId = normalizeId(ctx.defaultSessionId);
+    if (defaultSessionId)
+        return defaultSessionId;
+    const origin = resolveApprovalOriginForRequest(rawOrigin, null);
+    const originSessionId = normalizeId(origin?.sessionId);
+    if (originSessionId)
+        return originSessionId;
+    return targetSessionId;
+}
+function pickBoolean(input, key) {
+    return typeof input?.[key] === 'boolean' ? input[key] : undefined;
+}
+function hasOwn(input, key) {
+    return Boolean(input && Object.prototype.hasOwnProperty.call(input, key));
+}
 const ActionSurfaceKeySchema = ActionSurfaceSchema.keyof();
 function parseActionSurfaceKey(value) {
     const parsed = ActionSurfaceKeySchema.safeParse(value);
     return parsed.success ? parsed.data : null;
 }
+function isSessionAgentCaller(ctx) {
+    return ctx.surface === 'session_agent';
+}
+function createPermissionPolicyResult(ctx, decision) {
+    const errorCode = decision.reason;
+    return {
+        ok: false,
+        errorCode,
+        error: errorCode,
+        details: {
+            reason: errorCode,
+            surface: ctx.surface ?? null,
+            requestedMode: decision.requestedMode,
+            requestedOrdinal: decision.requestedOrdinal,
+            callerMode: decision.callerMode,
+            callerOrdinal: decision.callerOrdinal,
+        },
+    };
+}
+function assertSessionAgentPermission(ctx, requestedMode, supportedModes) {
+    if (!isSessionAgentCaller(ctx))
+        return null;
+    return assertNonEscalatingPermissionMode({
+        requestedMode,
+        callerMode: ctx.callerPermissionMode ?? 'default',
+        supportedModes,
+    });
+}
+function resolveSessionAgentPermission(ctx, requestedMode, supportedModes) {
+    if (!isSessionAgentCaller(ctx))
+        return null;
+    return resolveNearestPermissionModeAtOrBelow({
+        requestedMode,
+        callerMode: ctx.callerPermissionMode,
+        supportedModes,
+    });
+}
 function resolveSessionIdFromInput(input, ctx) {
     const sessionId = normalizeId(input?.sessionId);
     if (sessionId)
@@ -36,6 +160,24 @@ function buildApprovalSummary(spec, sessionId) {
     const base = String(spec.title ?? '').trim() || String(spec.id);
     return sessionId ? `${base} — ${sessionId}` : base;
 }
+function buildApprovalMetadata(spec) {
+    return {
+        flow: resolveActionApprovalFlow(spec.approval),
+        result: spec.approval.result,
+    };
+}
+function isApprovalActionId(actionId) {
+    return actionId === 'approval.request.create' || actionId === 'approval.request.decide';
+}
+function isBlockingApprovalRequest(request) {
+    return request.approval?.flow === 'blocking';
+}
+function hasRecordedApprovalDecision(request) {
+    return request.status === 'approved' && request.decision?.kind === 'approve';
+}
+function hasRecordedRejectionDecision(request) {
+    return request.status === 'rejected' && request.decision?.kind === 'reject';
+}
 function extractListedSessions(value) {
     const sessions = Array.isArray(value?.sessions)
         ? value.sessions
@@ -124,9 +266,108 @@ function normalizeExecutionBackendOptionValue(value) {
         return parsed.data;
     return buildBackendTargetKey({ kind: 'builtInAgent', agentId: value });
 }
+function normalizeSpawnTargetOptionAlias(value) {
+    const trimmed = value.trim();
+    return trimmed === 'customAcp' ? trimmed : normalizeExecutionBackendOptionValue(trimmed);
+}
+function resolveSpawnTargetSelection(input) {
+    const targetKeys = [];
+    const agentId = normalizeId(input.agentId);
+    for (const field of ['backend', 'target']) {
+        const rawAlias = normalizeId(input[field]);
+        if (rawAlias)
+            targetKeys.push(normalizeSpawnTargetOptionAlias(rawAlias));
+    }
+    const backendTargetKeyRaw = normalizeId(input.backendTargetKey);
+    if (backendTargetKeyRaw) {
+        const parsedKey = BackendTargetKeySchema.safeParse(backendTargetKeyRaw);
+        if (!parsedKey.success)
+            return { ok: false };
+        targetKeys.push(parsedKey.data);
+    }
+    const backendTargetParsed = BackendTargetRefSchema.safeParse(input.backendTarget);
+    if (backendTargetParsed.success) {
+        targetKeys.push(buildBackendTargetKey(backendTargetParsed.data));
+    }
+    else if (input.backendTarget !== undefined) {
+        return { ok: false };
+    }
+    const concreteTargetKeys = targetKeys.filter((targetKey) => targetKey !== 'customAcp');
+    const uniqueConcreteTargetKeys = [...new Set(concreteTargetKeys)];
+    if (uniqueConcreteTargetKeys.length > 1)
+        return { ok: false };
+    const hasCustomAcpAlias = targetKeys.includes('customAcp');
+    const backendTargetKey = uniqueConcreteTargetKeys[0];
+    if ((agentId === 'customAcp' || hasCustomAcpAlias) && backendTargetKey?.startsWith('agent:'))
+        return { ok: false };
+    if (hasCustomAcpAlias && agentId && agentId !== 'customAcp')
+        return { ok: false };
+    if (!backendTargetKey)
+        return { ok: true, ...((agentId || hasCustomAcpAlias) ? { agentId: agentId || 'customAcp' } : {}) };
+    const parsedTarget = parseBackendTargetKey(backendTargetKey);
+    const derivedAgentId = parsedTarget.kind === 'builtInAgent' ? parsedTarget.agentId : 'customAcp';
+    if (hasCustomAcpAlias && derivedAgentId !== 'customAcp')
+        return { ok: false };
+    if (agentId && agentId !== derivedAgentId)
+        return { ok: false };
+    return { ok: true, agentId: derivedAgentId, backendTargetKey };
+}
+function resolveAgentInventoryRequest(input) {
+    const targetSelection = resolveSpawnTargetSelection(input);
+    if (!targetSelection.ok)
+        return { ok: false };
+    const resolvedAgentId = targetSelection.agentId;
+    const backendTargetKey = targetSelection.backendTargetKey;
+    if (resolvedAgentId === 'customAcp' && !backendTargetKey) {
+        return { ok: false };
+    }
+    if (!resolvedAgentId) {
+        return { ok: false };
+    }
+    const modelId = readOpaqueIdentifier(input.modelId);
+    return {
+        ok: true,
+        value: {
+            agentId: resolvedAgentId,
+            ...(input.machineId ? { machineId: String(input.machineId) } : {}),
+            ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
+            ...(backendTargetKey ? { backendTargetKey } : {}),
+            ...(modelId ? { modelId } : {}),
+        },
+    };
+}
+function resolveSpawnDiscoveryRequest(input) {
+    const targetSelection = resolveSpawnTargetSelection(input);
+    if (!targetSelection.ok)
+        return { ok: false };
+    const path = normalizeId(input.path);
+    const directory = normalizeId(input.directory);
+    if (path && directory && path !== directory)
+        return { ok: false };
+    return {
+        ok: true,
+        value: {
+            ...(targetSelection.agentId ? { agentId: targetSelection.agentId } : {}),
+            ...(targetSelection.backendTargetKey ? { backendTargetKey: targetSelection.backendTargetKey } : {}),
+            ...(input.machineId ? { machineId: String(input.machineId) } : {}),
+            ...(input.serverId ? { serverId: String(input.serverId) } : {}),
+            ...(path ? { path } : {}),
+            ...(directory ? { directory } : {}),
+            ...(typeof input.includeDisabled === 'boolean' ? { includeDisabled: input.includeDisabled } : {}),
+            ...(typeof input.includeUnavailable === 'boolean' ? { includeUnavailable: input.includeUnavailable } : {}),
+            ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
+            ...((input.mcpSelection) ? { mcpSelection: input.mcpSelection } : {}),
+            ...((input.selection) ? { selection: input.selection } : {}),
+        },
+    };
+}
 async function resolveDynamicActionOptions(params) {
     const { deps, ctx, optionsSourceId, input } = params;
-    if (optionsSourceId === 'execution.backends.enabled') {
+    const route = resolveActionOptionSourceRoute(optionsSourceId);
+    if (!route) {
+        return { ok: false, errorCode: 'options_source_not_supported', error: 'options_source_not_supported' };
+    }
+    if (route.kind === 'executionBackends') {
         const result = await deps.agentsBackendsList({
             ...(typeof input.includeDisabled === 'boolean' ? { includeDisabled: input.includeDisabled } : { includeDisabled: false }),
             ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
@@ -139,7 +380,7 @@ async function resolveDynamicActionOptions(params) {
             })),
         };
     }
-    if (optionsSourceId === 'review.engines.available') {
+    if (route.kind === 'reviewEngines') {
         const sessionId = resolveSessionIdFromInput(input, ctx);
         if (!sessionId)
             return { ok: false, errorCode: 'session_not_selected', error: 'session_not_selected' };
@@ -149,13 +390,58 @@ async function resolveDynamicActionOptions(params) {
         });
         return { ok: true, result: normalizeResolvedOptions(result) };
     }
-    if (optionsSourceId === 'session.modes.available') {
+    if (route.kind === 'sessionModes') {
         const sessionId = resolveSessionIdFromInput(input, ctx);
         if (!sessionId)
             return { ok: false, errorCode: 'session_not_selected', error: 'session_not_selected' };
         const result = await deps.sessionModesList({ sessionId });
         return { ok: true, result: normalizeResolvedOptions(result) };
     }
+    if (route.kind === 'agentInventory') {
+        const handler = deps[route.depsKey];
+        if (!handler) {
+            return {
+                ok: false,
+                errorCode: 'unsupported_action',
+                error: `unsupported_action:${route.unsupportedActionId}`,
+            };
+        }
+        const resolved = resolveAgentInventoryRequest(input);
+        if (!resolved.ok)
+            return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+        const result = await handler(resolved.value);
+        return { ok: true, result: normalizeResolvedOptions(result) };
+    }
+    if (route.kind === 'localInventory') {
+        const handler = deps[route.depsKey];
+        if (!handler) {
+            return {
+                ok: false,
+                errorCode: 'unsupported_action',
+                error: `unsupported_action:${route.unsupportedActionId}`,
+            };
+        }
+        const result = await handler({
+            ...(input.machineId ? { machineId: String(input.machineId) } : {}),
+            ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
+        });
+        return { ok: true, result: normalizeResolvedOptions(result) };
+    }
+    if (route.kind === 'spawnDiscovery') {
+        const handler = deps[route.depsKey];
+        if (!handler) {
+            return {
+                ok: false,
+                errorCode: 'unsupported_action',
+                error: `unsupported_action:${route.unsupportedActionId}`,
+            };
+        }
+        const resolved = resolveSpawnDiscoveryRequest(input);
+        if (!resolved.ok)
+            return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+        const result = await handler(resolved.value);
+        return { ok: true, result: normalizeResolvedOptions(result) };
+    }
     return { ok: false, errorCode: 'options_source_not_supported', error: 'options_source_not_supported' };
 }
 function normalizeSuccessfulFanoutStartResult(result) {
@@ -223,6 +509,43 @@ async function fanoutStarts(params) {
     }));
     return results;
 }
+async function composeExecutionRunStartResult(params) {
+    const start = normalizeSuccessfulFanoutStartResult(params.rawStart);
+    if (!start
+        || typeof start !== 'object'
+        || start.ok === false
+        || typeof start.runId !== 'string') {
+        return params.rawStart;
+    }
+    let wait;
+    if (params.waitForCompletion) {
+        try {
+            wait = await params.deps.executionRunWait(params.sessionId, {
+                runId: start.runId,
+                ...(typeof params.waitTimeoutSeconds === 'number'
+                    ? { timeoutSeconds: params.waitTimeoutSeconds }
+                    : {}),
+            }, params.opts);
+        }
+        catch (error) {
+            const failure = normalizeActionExecutorThrownError(error);
+            wait = { ok: false, code: failure.errorCode, message: failure.error };
+        }
+    }
+    const enrichedStart = {
+        ...start,
+        permissionMode: params.permissionMode,
+        ...(params.waitForCompletion ? { wait } : {}),
+    };
+    if (params.rawStart
+        && typeof params.rawStart === 'object'
+        && params.rawStart.ok === true
+        && params.rawStart.data
+        && typeof params.rawStart.data === 'object') {
+        return { ...params.rawStart, data: enrichedStart };
+    }
+    return enrichedStart;
+}
 function buildApprovalDecisionResult(request) {
     return {
         ok: true,
@@ -233,6 +556,21 @@ function buildApprovalDecisionResult(request) {
         },
     };
 }
+function buildActionExecuteResultFromRecordedApprovalExecution(request) {
+    const execution = request.execution;
+    if (!execution || (request.status !== 'executed' && request.status !== 'failed'))
+        return null;
+    if (execution.ok) {
+        return { ok: true, result: execution.result };
+    }
+    const errorCode = typeof execution.errorCode === 'string' && execution.errorCode.trim().length > 0
+        ? execution.errorCode
+        : 'action_failed';
+    const error = typeof execution.error === 'string' && execution.error.trim().length > 0
+        ? execution.error
+        : errorCode;
+    return { ok: false, errorCode, error };
+}
 function resolveApprovalRequestExecutionSurface(createdBySurface) {
     if (createdBySurface === 'session_agent')
         return 'session_agent';
@@ -246,6 +584,13 @@ function resolveApprovalRequestExecutionSurface(createdBySurface) {
 }
 function normalizeActionExecutorThrownError(error) {
     const anyErr = error;
+    const rawDetails = anyErr?.details;
+    const details = rawDetails && typeof rawDetails === 'object'
+        && Object.hasOwn(rawDetails, 'spawnResponse')
+        && typeof rawDetails.spawnNonce === 'string'
+        && rawDetails.spawnNonce.trim().length > 0
+        ? { spawnNonce: rawDetails.spawnNonce.trim(), accepted: true }
+        : undefined;
     const rawCode = typeof anyErr?.code === 'string' ? String(anyErr.code).trim() : '';
     const message = error instanceof Error
         ? error.message
@@ -255,43 +600,176 @@ function normalizeActionExecutorThrownError(error) {
                 ? String(anyErr.message)
                 : '';
     if (rawCode && SessionControlErrorCodeSchema.safeParse(rawCode).success) {
-        return { errorCode: rawCode, error: message || rawCode };
+        return {
+            errorCode: rawCode,
+            error: message || rawCode,
+            ...(details !== undefined ? { details } : {}),
+        };
     }
     // Common network failures from axios/node.
     if (rawCode && ['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT'].includes(rawCode)) {
-        return { errorCode: 'server_unreachable', error: message || 'server_unreachable' };
+        return {
+            errorCode: 'server_unreachable',
+            error: message || 'server_unreachable',
+            ...(details !== undefined ? { details } : {}),
+        };
     }
-    return { errorCode: 'action_failed', error: message || 'action_failed' };
+    return {
+        errorCode: 'action_failed',
+        error: message || 'action_failed',
+        ...(details !== undefined ? { details } : {}),
+    };
+}
+function readActionExecuteFailure(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const record = result;
+    if (record.ok !== false)
+        return null;
+    const errorCode = typeof record.errorCode === 'string' && record.errorCode.trim().length > 0
+        ? record.errorCode
+        : 'action_failed';
+    const error = typeof record.error === 'string' && record.error.trim().length > 0
+        ? record.error
+        : errorCode;
+    return { errorCode, error };
 }
 export function createActionExecutor(deps) {
+    const liveBlockingApprovalArtifactIds = new Set();
     const policyAllowsAction = deps.isActionEnabled ?? ((_id, _ctx) => true);
-    const isActionEnabledByPolicy = (spec, ctx) => policyAllowsAction(spec.id, ctx);
-    const isActionEnabledBySurface = (spec, ctx) => isActionSpecSurfacedOn(spec, ctx.surface);
-    const isActionEnabled = (spec, ctx) => isActionEnabledBySurface(spec, ctx) && isActionEnabledByPolicy(spec, ctx);
-    const execute = async (actionId, input, context) => {
-        const ctx = context ?? {};
-        const spec = getActionSpec(actionId);
-        const approvalRequired = ctx.bypassApprovals ? false : deps.isActionApprovalRequired?.(actionId, ctx) === true;
-        const isApprovalAction = actionId === 'approval.request.create' || actionId === 'approval.request.decide';
-        if (!isActionEnabled(spec, ctx)) {
-            return { ok: false, errorCode: 'action_disabled', error: 'action_disabled' };
+    const resolveAvailability = (spec, ctx) => resolveActionSurfaceAvailability({
+        actionId: spec.id,
+        surface: ctx.surface ?? null,
+        settings: ctx.actionsSettings ?? null,
+        isActionEnabled: (id) => policyAllowsAction(id, ctx),
+    });
+    const isActionEnabled = (spec, ctx) => resolveAvailability(spec, ctx).available;
+    const actionDisabled = (availability) => ({
+        ok: false,
+        errorCode: 'action_disabled',
+        error: 'action_disabled',
+        details: availability,
+    });
+    async function executeApprovedActionForRequest(args) {
+        if (!deps.approvalsUpdate) {
+            return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:approvals' };
+        }
+        const latestRequest = deps.approvalsGet
+            ? await deps.approvalsGet({ artifactId: args.artifactId, serverId: args.effectiveServerId })
+            : null;
+        if (latestRequest) {
+            const recordedExecutionResult = buildActionExecuteResultFromRecordedApprovalExecution(latestRequest);
+            if (recordedExecutionResult) {
+                return { ok: true, request: latestRequest, exec: recordedExecutionResult };
+            }
         }
-        const parsed = spec.inputSchema.safeParse(input ?? {});
+        const requestSurface = parseActionSurfaceKey(args.request.requestedSurface)
+            ?? resolveApprovalRequestExecutionSurface(args.request.createdBy.surface);
+        const requestDefaultSessionId = typeof args.request.createdBy.sessionId === 'string' ? args.request.createdBy.sessionId.trim() : '';
+        const exec = requestSurface
+            ? args.runApprovedAction
+                ? await args.runApprovedAction()
+                : await execute(args.request.actionId, args.request.actionArgs, {
+                    ...args.ctx,
+                    ...(args.effectiveServerId ? { serverId: args.effectiveServerId } : {}),
+                    ...(requestDefaultSessionId ? { defaultSessionId: requestDefaultSessionId } : {}),
+                    surface: requestSurface,
+                    placement: null,
+                    bypassApprovals: true,
+                })
+            : { ok: false, errorCode: 'approval_execution_surface_invalid', error: 'approval_execution_surface_invalid' };
+        const executedAtMs = Date.now();
+        const nextExecuted = {
+            ...args.request,
+            status: exec.ok ? 'executed' : 'failed',
+            updatedAtMs: executedAtMs,
+            execution: exec.ok
+                ? { executedAtMs, ok: true, result: exec.result }
+                : { executedAtMs, ok: false, errorCode: exec.errorCode, error: exec.error },
+        };
+        const updated = await deps.approvalsUpdate({ artifactId: args.artifactId, request: nextExecuted, serverId: args.effectiveServerId });
+        if (updated?.ok === false)
+            return { ok: false, errorCode: updated.errorCode, error: updated.error };
+        return { ok: true, request: nextExecuted, exec };
+    }
+    async function resolveBlockingDecisionWaiter(args) {
+        if (!isBlockingApprovalRequest(args.request))
+            return false;
+        const resolved = await deps.approvalsResolveBlockingDecision?.({
+            artifactId: args.artifactId,
+            request: args.request,
+            decision: args.decision,
+            serverId: args.effectiveServerId,
+        });
+        return liveBlockingApprovalArtifactIds.has(args.artifactId) || resolved?.resolved === true;
+    }
+    const createOneShotInvocation = (runOnce) => {
+        let resultPromise = null;
+        return Object.freeze({
+            run: (options) => {
+                resultPromise ??= Promise.resolve().then(() => runOnce(options));
+                return resultPromise;
+            },
+        });
+    };
+    const executeOrPrepare = async (actionId, input, context, options) => {
+        const existingAdmission = options?.prepared;
+        const ctx = existingAdmission?.context ?? context ?? {};
+        const spec = existingAdmission?.spec ?? getActionSpec(actionId);
+        if (!existingAdmission) {
+            const availability = resolveAvailability(spec, ctx);
+            if (!availability.available)
+                return actionDisabled(availability);
+        }
+        const approvalRouting = existingAdmission
+            ? null
+            : resolveActionApprovalRouting({
+                actionId,
+                spec,
+                context: ctx,
+                requiredByPolicy: ctx.bypassApprovals ? false : deps.isActionApprovalRequired?.(actionId, ctx) === true,
+            });
+        const isApprovalAction = isApprovalActionId(actionId);
+        const parsed = existingAdmission
+            ? { success: true, data: existingAdmission.input }
+            : spec.inputSchema.safeParse(input ?? {});
         if (!parsed.success) {
             return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
         }
+        const admission = existingAdmission ?? { spec, input: parsed.data, context: ctx };
+        const runPreparedAdmission = async (prepared, runOptions) => {
+            const executionAdmission = runOptions?.signal
+                ? { ...prepared, context: { ...prepared.context, signal: runOptions.signal } }
+                : prepared;
+            const result = await executeOrPrepare(actionId, executionAdmission.input, executionAdmission.context, { prepared: executionAdmission });
+            if ('kind' in result)
+                throw new Error('Prepared Action invocation unexpectedly prepared twice');
+            return result;
+        };
+        const ready = (prepared, runOnce = (options) => runPreparedAdmission(prepared, options)) => ({
+            kind: 'ready',
+            invocation: createOneShotInvocation(runOnce),
+        });
         try {
-            if (approvalRequired && !isApprovalAction) {
+            if (approvalRouting?.required && !isApprovalAction) {
                 if (!deps.approvalsCreate) {
                     return { ok: false, errorCode: 'approvals_not_supported', error: 'approvals_not_supported' };
                 }
                 const now = Date.now();
-                const sessionId = resolveSessionIdFromInput(parsed.data, ctx);
+                const targetSessionId = resolveSessionIdFromInput(parsed.data, ctx);
+                const requestingSessionId = resolvePolicyApprovalRequestingSessionId(ctx.approvalOrigin, ctx, targetSessionId);
+                const approvalOrigin = resolveApprovalOriginForRequest(ctx.approvalOrigin, requestingSessionId);
                 const requestedSurface = parseActionSurfaceKey(ctx.surface);
                 const createdBy = {
                     surface: mapApprovalCreatedBySurface(ctx.surface ?? null),
-                    ...(sessionId ? { sessionId } : {}),
+                    ...(requestingSessionId ? { sessionId: requestingSessionId } : {}),
                 };
+                // A prepared invocation has a live custodian waiting to own the
+                // mutation. Convert the Action's ordinary deferred presentation into
+                // the existing blocking decision handoff so approval cannot later
+                // execute outside that custodian. Direct execute() retains the Action's
+                // declared deferred behavior.
+                const approvalFlow = options?.prepareOnly ? 'blocking' : approvalRouting.flow;
                 const request = {
                     v: 1,
                     status: 'open',
@@ -301,11 +779,113 @@ export function createActionExecutor(deps) {
                     ...(requestedSurface ? { requestedSurface } : {}),
                     actionId,
                     actionArgs: parsed.data,
-                    summary: buildApprovalSummary(spec, sessionId),
+                    approval: {
+                        flow: approvalFlow,
+                        result: approvalRouting.result,
+                    },
+                    ...(approvalOrigin ? { origin: approvalOrigin } : {}),
+                    summary: buildApprovalSummary(spec, targetSessionId),
                     preview: { actionId, actionArgs: parsed.data },
                     ...(normalizeId(ctx.serverId) ? { serverId: normalizeId(ctx.serverId) } : {}),
                 };
                 const res = await deps.approvalsCreate({ request, serverId: normalizeId(ctx.serverId) || null });
+                if (approvalFlow === 'blocking') {
+                    if (!deps.approvalsWaitForDecision || !deps.approvalsUpdate) {
+                        return { ok: false, errorCode: 'approvals_not_supported', error: 'approvals_not_supported' };
+                    }
+                    const artifactId = res?.artifactId;
+                    const effectiveServerId = normalizeId(ctx.serverId) || null;
+                    let releaseBlockingOwnershipOnPrepareReturn = true;
+                    liveBlockingApprovalArtifactIds.add(artifactId);
+                    try {
+                        const decision = await deps.approvalsWaitForDecision({
+                            artifactId,
+                            request,
+                            serverId: effectiveServerId,
+                        });
+                        const now = Date.now();
+                        if (decision.decision === 'reject' || decision.decision === 'canceled') {
+                            const nextRequest = decision.decision === 'reject' && hasRecordedRejectionDecision(decision.request)
+                                ? decision.request
+                                : {
+                                    ...decision.request,
+                                    status: decision.decision === 'reject' ? 'rejected' : 'canceled',
+                                    updatedAtMs: now,
+                                    ...(decision.decision === 'reject' ? { decision: { kind: 'reject', decidedAtMs: now } } : {}),
+                                };
+                            if (nextRequest !== decision.request) {
+                                const updated = await deps.approvalsUpdate({ artifactId, request: nextRequest, serverId: effectiveServerId });
+                                if (updated?.ok === false)
+                                    return { ok: false, errorCode: updated.errorCode, error: updated.error };
+                            }
+                            const errorCode = decision.decision === 'reject' ? 'approval_rejected' : 'approval_canceled';
+                            return { ok: false, errorCode, error: errorCode };
+                        }
+                        const recordedExecutionResult = buildActionExecuteResultFromRecordedApprovalExecution(decision.request);
+                        if (recordedExecutionResult)
+                            return recordedExecutionResult;
+                        const approvedRequest = hasRecordedApprovalDecision(decision.request)
+                            ? decision.request
+                            : {
+                                ...decision.request,
+                                status: 'approved',
+                                updatedAtMs: now,
+                                decision: { kind: 'approve', decidedAtMs: now },
+                            };
+                        if (approvedRequest !== decision.request) {
+                            const approved = await deps.approvalsUpdate({ artifactId, request: approvedRequest, serverId: effectiveServerId });
+                            if (approved?.ok === false)
+                                return { ok: false, errorCode: approved.errorCode, error: approved.error };
+                        }
+                        if (options?.prepareOnly) {
+                            releaseBlockingOwnershipOnPrepareReturn = false;
+                            const requestSurface = parseActionSurfaceKey(approvedRequest.requestedSurface)
+                                ?? resolveApprovalRequestExecutionSurface(approvedRequest.createdBy.surface);
+                            const requestDefaultSessionId = typeof approvedRequest.createdBy.sessionId === 'string'
+                                ? approvedRequest.createdBy.sessionId.trim()
+                                : '';
+                            const approvedAdmission = {
+                                spec,
+                                input: parsed.data,
+                                context: {
+                                    ...ctx,
+                                    ...(effectiveServerId ? { serverId: effectiveServerId } : {}),
+                                    ...(requestDefaultSessionId ? { defaultSessionId: requestDefaultSessionId } : {}),
+                                    ...(requestSurface ? { surface: requestSurface } : {}),
+                                    placement: null,
+                                    bypassApprovals: true,
+                                },
+                            };
+                            return ready(approvedAdmission, async (runOptions) => {
+                                try {
+                                    const executed = await executeApprovedActionForRequest({
+                                        artifactId,
+                                        request: approvedRequest,
+                                        ctx,
+                                        effectiveServerId,
+                                        runApprovedAction: () => runPreparedAdmission(approvedAdmission, runOptions),
+                                    });
+                                    return executed.ok ? executed.exec : executed;
+                                }
+                                finally {
+                                    liveBlockingApprovalArtifactIds.delete(artifactId);
+                                }
+                            });
+                        }
+                        const executed = await executeApprovedActionForRequest({
+                            artifactId,
+                            request: approvedRequest,
+                            ctx,
+                            effectiveServerId,
+                        });
+                        return executed.ok ? executed.exec : executed;
+                    }
+                    finally {
+                        if (releaseBlockingOwnershipOnPrepareReturn) {
+                            liveBlockingApprovalArtifactIds.delete(artifactId);
+                        }
+                    }
+                }
                 return {
                     ok: true,
                     result: {
@@ -315,6 +895,8 @@ export function createActionExecutor(deps) {
                     },
                 };
             }
+            if (options?.prepareOnly)
+                return ready(admission);
             // Switch by actionId; keep substrate generic.
             if (actionId === 'review.start') {
                 const sessionId = resolveSessionIdFromInput(parsed.data, ctx);
@@ -322,20 +904,59 @@ export function createActionExecutor(deps) {
                     return { ok: false, errorCode: 'session_not_selected', error: 'session_not_selected' };
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
                 const opts = serverId ? { serverId } : undefined;
-                const engineIds = Array.isArray(parsed.data.engineIds) ? parsed.data.engineIds : [];
-                const instructions = String(parsed.data.instructions ?? '').trim();
-                const intentInputBase = { ...parsed.data };
+                const reviewInput = parsed.data;
+                const engineIds = reviewInput.engineIds;
+                const instructions = reviewInput.instructions.trim();
+                const permissionDecision = resolveSessionAgentPermission(ctx, reviewInput.permissionMode, EXECUTION_RUN_ACTION_PERMISSION_MODES);
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
+                const permissionMode = permissionDecision?.ok === true
+                    ? permissionDecision.requestedMode
+                    : reviewInput.permissionMode;
+                const intentInputBase = { ...reviewInput, permissionMode };
+                const runLocation = reviewInput.runLocation;
+                if (runLocation === 'current_session') {
+                    if (engineIds.length !== 1) {
+                        return {
+                            ok: false,
+                            errorCode: 'inline_review_requires_single_engine',
+                            error: 'inline_review_requires_single_engine',
+                        };
+                    }
+                    if (!deps.reviewStartInline) {
+                        return {
+                            ok: false,
+                            errorCode: 'inline_review_not_supported',
+                            error: 'inline_review_not_supported',
+                        };
+                    }
+                    const engineId = engineIds[0];
+                    const result = await deps.reviewStartInline({
+                        sessionId,
+                        engineId,
+                        backendTarget: parseBackendTargetKey(normalizeExecutionBackendOptionValue(engineId)),
+                        instructions,
+                        input: intentInputBase,
+                        ...(serverId ? { serverId } : {}),
+                    });
+                    const failure = readActionExecuteFailure(result);
+                    if (failure)
+                        return { ok: false, ...failure };
+                    return { ok: true, result };
+                }
                 const results = await fanoutStarts({
                     keys: engineIds,
                     startOne: async (engineId) => deps.executionRunStart(sessionId, {
                         intent: 'review',
                         backendTarget: parseBackendTargetKey(normalizeExecutionBackendOptionValue(engineId)),
                         instructions,
-                        permissionMode: parsed.data.permissionMode ?? 'read_only',
+                        permissionMode,
                         retentionPolicy: 'resumable',
                         runClass: 'bounded',
                         // Reviews should stream sidechain progress (and tool traffic) into the parent session.
                         ioMode: 'streaming',
+                        launchOrigin: resolveExecutionRunLaunchOrigin(ctx),
                         intentInput: { ...intentInputBase, engineId },
                     }, opts),
                 });
@@ -353,18 +974,85 @@ export function createActionExecutor(deps) {
                 const instructions = String(parsed.data.instructions ?? '').trim();
                 const intent = actionId === 'subagents.plan.start' ? 'plan' : actionId === 'subagents.delegate.start' ? 'delegate' : 'voice_agent';
                 const permissionModeDefault = intent === 'delegate' ? 'workspace_write' : 'read_only';
+                const requestedPermissionMode = parsed.data.permissionMode;
+                const permissionDecision = resolveSessionAgentPermission(ctx, requestedPermissionMode, EXECUTION_RUN_ACTION_PERMISSION_MODES);
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
+                const permissionMode = permissionDecision?.ok === true
+                    ? permissionDecision.requestedMode
+                    : requestedPermissionMode ?? permissionModeDefault;
+                // Connected-services selection: a per-target override wins over the blanket selection.
+                // Normalize the simple/object forms to canonical bindings at this ONE boundary; a malformed
+                // selection is a typed rejection, never a silent drop.
+                const blanketConnectedServices = parsed.data.connectedServices;
+                const connectedServicesByBackendTargetKey = parsed.data.connectedServicesByBackendTargetKey &&
+                    typeof parsed.data.connectedServicesByBackendTargetKey === 'object'
+                    ? parsed.data.connectedServicesByBackendTargetKey
+                    : {};
+                const connectedServicesByTarget = new Map();
+                for (const backendTargetKey of backendTargetKeys) {
+                    const rawSelection = Object.prototype.hasOwnProperty.call(connectedServicesByBackendTargetKey, backendTargetKey)
+                        ? connectedServicesByBackendTargetKey[backendTargetKey]
+                        : blanketConnectedServices;
+                    // Preserve bare per-service defaults (RO-F5): the run-start owner resolves them and merges
+                    // UNDER explicit pins, so a mixed bare+explicit selection resolves instead of failing closed.
+                    const normalized = normalizeConnectedServiceSelectionInput(rawSelection);
+                    if (!normalized.ok) {
+                        return { ok: false, errorCode: 'invalid_parameters', error: normalized.error };
+                    }
+                    connectedServicesByTarget.set(backendTargetKey, {
+                        bindings: normalized.bindings,
+                        defaultServiceIds: normalized.defaultServiceIds,
+                    });
+                }
+                // Model + config-option (reasoning effort) selection: reuse the SAME canonical merge owner
+                // as session spawn. A conflicting shorthand/canonical value is a typed rejection here.
+                const runOptions = resolveRunStartModelAndConfig(parsed.data);
+                if (!runOptions.ok) {
+                    return { ok: false, errorCode: 'invalid_parameters', error: runOptions.error };
+                }
+                const { waitForCompletion: _waitForCompletion, waitTimeoutSeconds: _waitTimeoutSeconds, ...intentInput } = parsed.data;
                 const results = await fanoutStarts({
                     keys: backendTargetKeys,
-                    startOne: async (backendTargetKey) => deps.executionRunStart(sessionId, {
-                        intent,
-                        backendTarget: parseBackendTargetKey(backendTargetKey),
-                        instructions,
-                        permissionMode: parsed.data.permissionMode ?? permissionModeDefault,
-                        retentionPolicy: parsed.data.retentionPolicy ?? 'ephemeral',
-                        runClass: parsed.data.runClass ?? 'bounded',
-                        ioMode: parsed.data.ioMode ?? 'request_response',
-                        intentInput: { ...parsed.data, backendTargetKey },
-                    }, opts),
+                    startOne: async (backendTargetKey) => {
+                        const targetSelection = connectedServicesByTarget.get(backendTargetKey);
+                        const connectedServices = targetSelection?.bindings;
+                        const connectedServicesDefaultServiceIds = targetSelection?.defaultServiceIds ?? [];
+                        const rawStart = await deps.executionRunStart(sessionId, {
+                            intent,
+                            ...(ctx.actionRequestId
+                                ? { startRequestId: `${ctx.actionRequestId}:${backendTargetKey}` }
+                                : {}),
+                            backendTarget: parseBackendTargetKey(backendTargetKey),
+                            instructions,
+                            permissionMode,
+                            retentionPolicy: parsed.data.retentionPolicy ?? 'ephemeral',
+                            runClass: parsed.data.runClass ?? 'bounded',
+                            ioMode: parsed.data.ioMode ?? 'request_response',
+                            launchOrigin: resolveExecutionRunLaunchOrigin(ctx),
+                            ...(connectedServices ? { connectedServices } : {}),
+                            ...(connectedServicesDefaultServiceIds.length > 0
+                                ? { connectedServicesDefaultServiceIds }
+                                : {}),
+                            ...(runOptions.modelId ? { modelId: runOptions.modelId } : {}),
+                            ...(runOptions.sessionConfigOptionOverrides
+                                ? { sessionConfigOptionOverrides: runOptions.sessionConfigOptionOverrides }
+                                : {}),
+                            intentInput: { ...intentInput, backendTargetKey },
+                        }, opts);
+                        return await composeExecutionRunStartResult({
+                            rawStart,
+                            sessionId,
+                            permissionMode,
+                            waitForCompletion: parsed.data.waitForCompletion === true,
+                            ...(typeof parsed.data.waitTimeoutSeconds === 'number'
+                                ? { waitTimeoutSeconds: parsed.data.waitTimeoutSeconds }
+                                : {}),
+                            opts,
+                            deps,
+                        });
+                    },
                 });
                 return { ok: true, result: { intent, sessionId, results } };
             }
@@ -383,15 +1071,11 @@ export function createActionExecutor(deps) {
             }
             if (actionId === 'action.spec.get') {
                 try {
-                    const requested = getSerializedActionSpecForSurface({
-                        id: String(parsed.data.id),
-                        surface: ctx.surface ?? null,
-                        isActionEnabled: (id) => isActionEnabled(getActionSpec(id), ctx),
-                    });
-                    if (!requested) {
-                        return { ok: false, errorCode: 'action_disabled', error: 'action_disabled' };
-                    }
-                    return { ok: true, result: { actionSpec: requested } };
+                    const requestedSpec = getActionSpec(String(parsed.data.id));
+                    const requestedAvailability = resolveAvailability(requestedSpec, ctx);
+                    if (!requestedAvailability.available)
+                        return actionDisabled(requestedAvailability);
+                    return { ok: true, result: { actionSpec: serializeActionSpec(requestedSpec) } };
                 }
                 catch {
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
@@ -409,14 +1093,10 @@ export function createActionExecutor(deps) {
                     catch {
                         return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
                     }
-                    const requestedSpec = getActionSpecForCatalogSurface({
-                        id: actionIdRaw,
-                        surface: ctx.surface ?? null,
-                        isActionEnabled: (id) => isActionEnabled(getActionSpec(id), ctx),
-                    });
-                    if (!requestedSpec) {
-                        return { ok: false, errorCode: 'action_disabled', error: 'action_disabled' };
-                    }
+                    const requestedSpec = getActionSpec(actionIdRaw);
+                    const requestedAvailability = resolveAvailability(requestedSpec, ctx);
+                    if (!requestedAvailability.available)
+                        return actionDisabled(requestedAvailability);
                     const field = findActionInputFieldHint(requestedSpec, fieldPath);
                     if (!field) {
                         return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
@@ -438,11 +1118,31 @@ export function createActionExecutor(deps) {
                 if (!optionsSourceId) {
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
                 }
+                const draftInput = parsed.data.draftInput;
+                const dependencyInput = draftInput && typeof draftInput === 'object' && !Array.isArray(draftInput)
+                    ? { ...draftInput, ...parsed.data }
+                    : parsed.data;
+                if (!dependencyInput.backendTargetKey && Array.isArray(dependencyInput.backendTargetKeys) && dependencyInput.backendTargetKeys.length === 1) {
+                    dependencyInput.backendTargetKey = dependencyInput.backendTargetKeys[0];
+                }
+                const requiresRunBackendDependency = ((actionIdRaw === 'subagents.plan.start' || actionIdRaw === 'subagents.delegate.start')
+                    && fieldPath === 'modelId');
+                if (requiresRunBackendDependency && !dependencyInput.backendTargetKey) {
+                    return {
+                        ok: false,
+                        errorCode: 'missing_option_dependency',
+                        error: 'Select one backend target in draftInput before resolving dependent options.',
+                        details: {
+                            requiredDraftPath: 'backendTargetKeys',
+                            example: { draftInput: { backendTargetKeys: ['agent:pi'] } },
+                        },
+                    };
+                }
                 const dynamic = await resolveDynamicActionOptions({
                     deps,
                     ctx,
                     optionsSourceId,
-                    input: parsed.data,
+                    input: dependencyInput,
                 });
                 if (!dynamic.ok)
                     return dynamic;
@@ -462,9 +1162,71 @@ export function createActionExecutor(deps) {
                     return { ok: false, errorCode: 'session_not_selected', error: 'session_not_selected' };
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
                 const opts = serverId ? { serverId } : undefined;
-                const { sessionId: _ignored, ...request } = parsed.data;
-                const res = await deps.executionRunStart(sessionId, request, opts);
-                return { ok: true, result: res };
+                const { sessionId: _ignored, waitForCompletion, waitTimeoutSeconds, ...request } = parsed.data;
+                request.launchOrigin = resolveExecutionRunLaunchOrigin(ctx);
+                // Model + config-option (reasoning effort) selection: merge the `configOptions` shorthand
+                // into the canonical `sessionConfigOptionOverrides` using the SAME owner as session spawn.
+                // A conflicting shorthand/canonical value is a typed rejection.
+                const runOptions = resolveRunStartModelAndConfig(request);
+                if (!runOptions.ok) {
+                    return { ok: false, errorCode: 'invalid_parameters', error: runOptions.error };
+                }
+                delete request.configOptions;
+                if (runOptions.sessionConfigOptionOverrides) {
+                    request.sessionConfigOptionOverrides = runOptions.sessionConfigOptionOverrides;
+                }
+                else {
+                    delete request.sessionConfigOptionOverrides;
+                }
+                if (runOptions.modelId) {
+                    request.modelId = runOptions.modelId;
+                }
+                else {
+                    delete request.modelId;
+                }
+                // Normalize the agent-friendly connected-services selection (simple string / object) to
+                // canonical bindings at this ONE boundary; malformed input is a typed rejection.
+                if (request.connectedServices !== undefined) {
+                    // Preserve bare per-service defaults (RO-F5) alongside explicit pins; the run-start owner
+                    // resolves + merges them (mixed bare+explicit resolves instead of failing closed).
+                    const normalized = normalizeConnectedServiceSelectionInput(request.connectedServices);
+                    if (!normalized.ok) {
+                        return { ok: false, errorCode: 'invalid_parameters', error: normalized.error };
+                    }
+                    if (normalized.bindings) {
+                        request.connectedServices = normalized.bindings;
+                    }
+                    else {
+                        delete request.connectedServices;
+                    }
+                    if (normalized.defaultServiceIds.length > 0) {
+                        request.connectedServicesDefaultServiceIds = normalized.defaultServiceIds;
+                    }
+                    else {
+                        delete request.connectedServicesDefaultServiceIds;
+                    }
+                }
+                const permissionDecision = resolveSessionAgentPermission(ctx, request.permissionMode, EXECUTION_RUN_ACTION_PERMISSION_MODES);
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
+                if (permissionDecision?.ok === true) {
+                    request.permissionMode = permissionDecision.requestedMode;
+                }
+                if (ctx.actionRequestId) {
+                    request.startRequestId = ctx.actionRequestId;
+                }
+                const rawStart = await deps.executionRunStart(sessionId, request, opts);
+                const result = await composeExecutionRunStartResult({
+                    rawStart,
+                    sessionId,
+                    permissionMode: request.permissionMode,
+                    waitForCompletion: waitForCompletion === true,
+                    ...(typeof waitTimeoutSeconds === 'number' ? { waitTimeoutSeconds } : {}),
+                    opts,
+                    deps,
+                });
+                return { ok: true, result };
             }
             if (actionId === 'execution.run.list') {
                 const sessionId = resolveSessionIdFromInput(parsed.data, ctx);
@@ -548,7 +1310,19 @@ export function createActionExecutor(deps) {
                 if (!sessionId)
                     return { ok: false, errorCode: 'session_not_selected', error: 'session_not_selected' };
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
-                const res = await deps.sessionFork({ sessionId, ...(serverId ? { serverId } : {}) });
+                const forkInput = parsed.data;
+                const contextRequestId = normalizeId(ctx.actionRequestId);
+                const requestId = forkInput.requestId ?? (contextRequestId || undefined);
+                const res = await deps.sessionFork({
+                    sessionId,
+                    ...(serverId ? { serverId } : {}),
+                    ...(forkInput.forkPoint !== undefined ? { forkPoint: forkInput.forkPoint } : {}),
+                    ...(forkInput.strategy !== undefined ? { strategy: forkInput.strategy } : {}),
+                    ...(forkInput.replaySummaryRunner !== undefined ? { replaySummaryRunner: forkInput.replaySummaryRunner } : {}),
+                    ...(forkInput.replayMaxSeedChars !== undefined ? { replayMaxSeedChars: forkInput.replayMaxSeedChars } : {}),
+                    ...(requestId !== undefined ? { requestId } : {}),
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
+                });
                 return { ok: true, result: res };
             }
             if (actionId === 'session.rollback') {
@@ -575,27 +1349,42 @@ export function createActionExecutor(deps) {
                 const targetSessionStorageMode = parsed.data.targetSessionStorageMode === 'direct' || parsed.data.targetSessionStorageMode === 'persisted'
                     ? parsed.data.targetSessionStorageMode
                     : undefined;
+                const targetPath = normalizeId(parsed.data.targetPath);
                 const workspaceTransferParsed = SessionHandoffWorkspaceTransferSchema.safeParse(parsed.data.workspaceTransfer);
                 const workspaceTransfer = workspaceTransferParsed.success ? workspaceTransferParsed.data : undefined;
+                const requestId = normalizeId(ctx.actionRequestId);
                 const res = await deps.sessionHandoffStart({
                     sessionId,
                     targetMachineId,
+                    ...(targetPath ? { targetPath } : {}),
+                    ...(requestId ? { requestId } : {}),
                     ...(targetSessionStorageMode ? { targetSessionStorageMode } : {}),
                     ...(workspaceTransfer ? { workspaceTransfer } : {}),
                     ...(serverId ? { serverId } : {}),
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
                 });
                 return { ok: true, result: res };
             }
             if (actionId === 'session.spawn_new') {
+                const spawnInput = parsed.data;
+                const permissionDecision = typeof spawnInput.permissionMode === 'string' && spawnInput.permissionMode.trim().length > 0
+                    ? assertSessionAgentPermission(ctx, spawnInput.permissionMode)
+                    : null;
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
+                const effectiveSpawnInput = permissionDecision?.ok === true
+                    ? { ...spawnInput, permissionMode: permissionDecision.normalizedMode }
+                    : spawnInput;
                 const res = await deps.sessionSpawnNew({
-                    ...((parsed.data.tag) ? { tag: String(parsed.data.tag) } : {}),
-                    ...((parsed.data.agentId) ? { agentId: String(parsed.data.agentId) } : {}),
-                    ...((parsed.data.modelId) ? { modelId: String(parsed.data.modelId) } : {}),
-                    ...((parsed.data.backendTargetKey) ? { backendTargetKey: String(parsed.data.backendTargetKey) } : {}),
-                    ...((parsed.data.title) ? { title: String(parsed.data.title) } : {}),
-                    ...((parsed.data.path) ? { path: String(parsed.data.path) } : {}),
-                    ...((parsed.data.host) ? { host: String(parsed.data.host) } : {}),
-                    ...((parsed.data.initialMessage) ? { initialMessage: String(parsed.data.initialMessage) } : {}),
+                    ...effectiveSpawnInput,
+                    surface: ctx.surface ?? null,
+                    ...(ctx.actionRequestId ? { actionRequestId: ctx.actionRequestId } : {}),
+                    ...(ctx.resumeActionRequest === true ? { resumeActionRequest: true } : {}),
+                    ...(ctx.signal ? { signal: ctx.signal } : {}),
+                    ...(isSessionAgentCaller(ctx)
+                        ? { callerSurface: 'session_agent', callerPermissionMode: ctx.callerPermissionMode ?? null }
+                        : {}),
                 });
                 return { ok: true, result: res };
             }
@@ -645,28 +1434,55 @@ export function createActionExecutor(deps) {
                 return { ok: true, result: res };
             }
             if (actionId === 'agents.models.list') {
-                const backendTargetKey = normalizeId(parsed.data.backendTargetKey);
-                let resolvedAgentId = normalizeId(parsed.data.agentId);
-                if (backendTargetKey) {
-                    const parsedTarget = parseBackendTargetKey(backendTargetKey);
-                    const derivedAgentId = parsedTarget.kind === 'builtInAgent' ? parsedTarget.agentId : 'customAcp';
-                    if (resolvedAgentId && resolvedAgentId !== derivedAgentId) {
-                        return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
-                    }
-                    resolvedAgentId = derivedAgentId;
-                }
-                if (resolvedAgentId === 'customAcp' && !backendTargetKey) {
+                const resolved = resolveAgentInventoryRequest(parsed.data);
+                if (!resolved.ok)
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
-                }
-                if (!resolvedAgentId) {
+                const res = await deps.agentsModelsList(resolved.value);
+                return { ok: true, result: res };
+            }
+            if (actionId === 'agents.session_modes.list') {
+                if (!deps.agentsSessionModesList)
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:agents.session_modes.list' };
+                const resolved = resolveAgentInventoryRequest(parsed.data);
+                if (!resolved.ok)
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
-                }
-                const res = await deps.agentsModelsList({
-                    agentId: resolvedAgentId,
-                    ...((parsed.data.machineId) ? { machineId: String(parsed.data.machineId) } : {}),
-                    ...(typeof parsed.data.limit === 'number' ? { limit: parsed.data.limit } : {}),
-                    ...(backendTargetKey ? { backendTargetKey } : {}),
-                });
+                const res = await deps.agentsSessionModesList(resolved.value);
+                return { ok: true, result: res };
+            }
+            if (actionId === 'agents.config_options.list') {
+                if (!deps.agentsConfigOptionsList)
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:agents.config_options.list' };
+                const resolved = resolveAgentInventoryRequest(parsed.data);
+                if (!resolved.ok)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const res = await deps.agentsConfigOptionsList(resolved.value);
+                return { ok: true, result: res };
+            }
+            if (actionId === 'sessions.spawn.profiles.list') {
+                if (!deps.sessionsSpawnProfilesList)
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:sessions.spawn.profiles.list' };
+                const resolved = resolveSpawnDiscoveryRequest(parsed.data);
+                if (!resolved.ok)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const res = await deps.sessionsSpawnProfilesList(resolved.value);
+                return { ok: true, result: res };
+            }
+            if (actionId === 'sessions.spawn.connected_services.list') {
+                if (!deps.sessionsSpawnConnectedServicesList)
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:sessions.spawn.connected_services.list' };
+                const resolved = resolveSpawnDiscoveryRequest(parsed.data);
+                if (!resolved.ok)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const res = await deps.sessionsSpawnConnectedServicesList(resolved.value);
+                return { ok: true, result: res };
+            }
+            if (actionId === 'sessions.spawn.mcp_servers.preview') {
+                if (!deps.sessionsSpawnMcpServersPreview)
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:sessions.spawn.mcp_servers.preview' };
+                const resolved = resolveSpawnDiscoveryRequest(parsed.data);
+                if (!resolved.ok)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const res = await deps.sessionsSpawnMcpServersPreview(resolved.value);
                 return { ok: true, result: res };
             }
             if (actionId === 'session.message.send') {
@@ -677,19 +1493,39 @@ export function createActionExecutor(deps) {
                 const modelOverrideRaw = Object.prototype.hasOwnProperty.call(parsed.data, 'modelOverride')
                     ? parsed.data.modelOverride
                     : undefined;
+                const permissionOverrideRaw = parsed.data.permissionModeOverride;
+                const permissionModeForAgent = isSessionAgentCaller(ctx)
+                    && !(typeof permissionOverrideRaw === 'string' && permissionOverrideRaw.trim().length > 0)
+                    ? ctx.callerPermissionMode ?? 'default'
+                    : permissionOverrideRaw;
+                const permissionDecision = typeof permissionModeForAgent === 'string' && permissionModeForAgent.trim().length > 0
+                    ? assertSessionAgentPermission(ctx, permissionModeForAgent)
+                    : null;
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
                 const res = await deps.sessionSendMessage({
                     sessionId,
                     message: parsed.data.message,
-                    ...((parsed.data.permissionModeOverride) ? { permissionModeOverride: parsed.data.permissionModeOverride } : {}),
+                    requestedAction: PendingRequestedActionV1Schema.parse(parsed.data.requestedAction ?? { v: 1, kind: 'steer_if_active' }),
+                    ...(permissionDecision?.ok === true
+                        ? { permissionModeOverride: permissionDecision.normalizedMode }
+                        : permissionOverrideRaw ? { permissionModeOverride: permissionOverrideRaw } : {}),
                     ...(modelOverrideRaw === null
                         ? { modelOverride: null }
                         : typeof modelOverrideRaw === 'string' && modelOverrideRaw.trim().length > 0
-                            ? { modelOverride: modelOverrideRaw.trim() }
+                            ? { modelOverride: modelOverrideRaw }
                             : {}),
                     ...(typeof parsed.data.wait === 'boolean' ? { wait: parsed.data.wait } : {}),
                     ...(typeof parsed.data.timeoutSeconds === 'number' ? { timeoutSeconds: parsed.data.timeoutSeconds } : {}),
                     ...(serverId ? { serverId } : {}),
+                    ...(isSessionAgentCaller(ctx)
+                        ? { callerSurface: 'session_agent', callerPermissionMode: ctx.callerPermissionMode ?? null }
+                        : {}),
                 });
+                const failure = readActionExecuteFailure(res);
+                if (failure)
+                    return { ok: false, ...failure };
                 return { ok: true, result: res };
             }
             if (actionId === 'session.title.set') {
@@ -715,6 +1551,21 @@ export function createActionExecutor(deps) {
                 }
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
                 const res = await deps.sessionStop({ sessionId, ...(serverId ? { serverId } : {}) });
+                const stopFailed = 'success' in res ? res.success === false : res.ok === false;
+                if (stopFailed) {
+                    const errorCode = res.code?.trim()
+                        || ('errorCode' in res ? res.errorCode?.trim() : undefined)
+                        || 'session_stop_failed';
+                    const error = ('error' in res ? res.error?.trim() : undefined)
+                        || res.message?.trim()
+                        || errorCode;
+                    return {
+                        ok: false,
+                        errorCode,
+                        error,
+                        details: res,
+                    };
+                }
                 return { ok: true, result: res };
             }
             if (actionId === 'session.permission_mode.set') {
@@ -727,8 +1578,19 @@ export function createActionExecutor(deps) {
                 const permissionMode = normalizeId(parsed.data.permissionMode);
                 if (!permissionMode)
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const permissionDecision = assertSessionAgentPermission(ctx, permissionMode);
+                if (permissionDecision?.ok === false) {
+                    return createPermissionPolicyResult(ctx, permissionDecision);
+                }
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
-                const res = await deps.sessionPermissionModeSet({ sessionId, permissionMode, ...(serverId ? { serverId } : {}) });
+                const res = await deps.sessionPermissionModeSet({
+                    sessionId,
+                    permissionMode: permissionDecision?.ok === true ? permissionDecision.normalizedMode : permissionMode,
+                    ...(serverId ? { serverId } : {}),
+                    ...(isSessionAgentCaller(ctx)
+                        ? { callerSurface: 'session_agent', callerPermissionMode: ctx.callerPermissionMode ?? null }
+                        : {}),
+                });
                 return { ok: true, result: res };
             }
             if (actionId === 'session.model.set') {
@@ -738,7 +1600,7 @@ export function createActionExecutor(deps) {
                 if (!deps.sessionModelSet) {
                     return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.model.set' };
                 }
-                const modelId = normalizeId(parsed.data.modelId);
+                const modelId = readOpaqueIdentifier(parsed.data.modelId);
                 if (!modelId)
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
@@ -772,6 +1634,212 @@ export function createActionExecutor(deps) {
                 const res = await deps.sessionStatusGet({ sessionId, live, ...(serverId ? { serverId } : {}) });
                 return { ok: true, result: res };
             }
+            if (actionId === 'session.work_state.get') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionWorkStateGet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.work_state.get' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionWorkStateGet({ sessionId, ...(serverId ? { serverId } : {}) });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.goal.get') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionGoalGet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.goal.get' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionGoalGet({ sessionId, ...(serverId ? { serverId } : {}) });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.goal.set') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionGoalSet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.goal.set' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const data = parsed.data;
+                const tokenBudget = data.tokenBudget;
+                const res = await deps.sessionGoalSet({
+                    sessionId,
+                    ...(typeof data.objective === 'string' ? { objective: data.objective } : {}),
+                    ...(typeof data.status === 'string' ? { status: data.status } : {}),
+                    ...(Object.prototype.hasOwnProperty.call(data, 'tokenBudget') && (typeof tokenBudget === 'number' || tokenBudget === null)
+                        ? { tokenBudget }
+                        : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.goal.clear') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionGoalClear) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.goal.clear' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionGoalClear({ sessionId, ...(serverId ? { serverId } : {}) });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.terminalComposer.clear') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionTerminalComposerClear) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.terminalComposer.clear' };
+                }
+                const expectedStateAtMs = parsed.data.expectedStateAtMs;
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionTerminalComposerClear({
+                    sessionId,
+                    ...(typeof expectedStateAtMs === 'number' ? { expectedStateAtMs } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.pendingInput.interruptAndRun') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                const localId = normalizeId(parsed.data.localId);
+                if (!sessionId || !localId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionPendingInputInterruptAndRun) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.pendingInput.interruptAndRun' };
+                }
+                const expectedStateAtMs = parsed.data.expectedStateAtMs;
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionPendingInputInterruptAndRun({
+                    sessionId,
+                    localId,
+                    ...(typeof expectedStateAtMs === 'number' ? { expectedStateAtMs } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.vendor_plugin_catalog.list') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionVendorPluginCatalogList) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.vendor_plugin_catalog.list' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionVendorPluginCatalogList({
+                    sessionId,
+                    ...(typeof parsed.data.cwd === 'string' ? { cwd: parsed.data.cwd } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.skill_catalog.list') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionSkillCatalogList) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.skill_catalog.list' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionSkillCatalogList({
+                    sessionId,
+                    ...(typeof parsed.data.cwd === 'string' ? { cwd: parsed.data.cwd } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.usageLimit.waitResume.enable') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionUsageLimitWaitResumeEnable) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.usageLimit.waitResume.enable' };
+                }
+                const data = parsed.data;
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionUsageLimitWaitResumeEnable({
+                    sessionId,
+                    ...(typeof data.issueFingerprint === 'string' ? { issueFingerprint: data.issueFingerprint } : {}),
+                    ...(data.remember === true ? { remember: true } : {}),
+                    ...(data.resumePromptMode === 'standard' || data.resumePromptMode === 'off' || data.resumePromptMode === 'custom'
+                        ? { resumePromptMode: data.resumePromptMode }
+                        : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: normalizeUsageLimitActionResult(res, sessionId) };
+            }
+            if (actionId === 'session.usageLimit.waitResume.cancel') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionUsageLimitWaitResumeCancel) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.usageLimit.waitResume.cancel' };
+                }
+                const data = parsed.data;
+                const issueFingerprint = data.issueFingerprint;
+                const armedAtMs = data.armedAtMs;
+                const runtimeAuthRecoveryAttemptId = data.runtimeAuthRecoveryAttemptId;
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionUsageLimitWaitResumeCancel({
+                    sessionId,
+                    ...(typeof issueFingerprint === 'string' || issueFingerprint === null ? { issueFingerprint } : {}),
+                    ...(typeof armedAtMs === 'number' ? { armedAtMs } : {}),
+                    ...(typeof runtimeAuthRecoveryAttemptId === 'string' ? { runtimeAuthRecoveryAttemptId } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: normalizeUsageLimitActionResult(res, sessionId) };
+            }
+            if (actionId === 'session.usageLimit.checkNow') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                const data = parsed.data;
+                const operation = data.operation === 'switch_account_now'
+                    ? 'switch_account_now'
+                    : 'check_now';
+                if (operation === 'switch_account_now' && !deps.sessionUsageLimitSwitchAccountNow) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.usageLimit.checkNow' };
+                }
+                if (operation === 'check_now' && !deps.sessionUsageLimitCheckNow) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.usageLimit.checkNow' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const handler = operation === 'switch_account_now'
+                    ? deps.sessionUsageLimitSwitchAccountNow
+                    : deps.sessionUsageLimitCheckNow;
+                const res = await handler?.({
+                    sessionId,
+                    ...(typeof data.provider === 'string' && data.provider.trim().length > 0 ? { provider: data.provider.trim() } : {}),
+                    ...(data.resumePromptMode === 'standard' || data.resumePromptMode === 'off' || data.resumePromptMode === 'custom'
+                        ? { resumePromptMode: data.resumePromptMode }
+                        : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: normalizeUsageLimitActionResult(res, sessionId) };
+            }
+            if (actionId === 'session.usageLimit.consumeResetCredit') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionUsageLimitConsumeResetCredit) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.usageLimit.consumeResetCredit' };
+                }
+                const data = parsed.data;
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const res = await deps.sessionUsageLimitConsumeResetCredit({
+                    sessionId,
+                    ...(typeof data.provider === 'string' && data.provider.trim().length > 0 ? { provider: data.provider.trim() } : {}),
+                    ...(data.resumePromptMode === 'standard' || data.resumePromptMode === 'off' || data.resumePromptMode === 'custom'
+                        ? { resumePromptMode: data.resumePromptMode }
+                        : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: normalizeUsageLimitActionResult(res, sessionId) };
+            }
             if (actionId === 'session.history.get') {
                 const sessionId = normalizeId(parsed.data.sessionId);
                 if (!sessionId)
@@ -779,14 +1847,14 @@ export function createActionExecutor(deps) {
                 if (!deps.sessionHistoryGet) {
                     return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.history.get' };
                 }
-                const limit = typeof parsed.data.limit === 'number' ? parsed.data.limit : 50;
+                const limit = typeof parsed.data.limit === 'number' ? parsed.data.limit : undefined;
                 const format = parsed.data.format === 'raw' ? 'raw' : 'compact';
                 const includeMeta = parsed.data.includeMeta === true;
                 const includeStructuredPayload = parsed.data.includeStructuredPayload === true;
                 const serverId = resolveServerIdForSession(deps, ctx, sessionId);
                 const res = await deps.sessionHistoryGet({
                     sessionId,
-                    limit,
+                    ...(typeof limit === 'number' ? { limit } : {}),
                     format,
                     includeMeta,
                     includeStructuredPayload,
@@ -794,6 +1862,63 @@ export function createActionExecutor(deps) {
                 });
                 return { ok: true, result: res };
             }
+            if (actionId === 'session.transcript.get') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionTranscriptGet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.transcript.get' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const data = parsed.data;
+                const res = await deps.sessionTranscriptGet({
+                    sessionId,
+                    ...(typeof data.limit === 'number' ? { limit: data.limit } : {}),
+                    ...(hasOwn(data, 'cursor') ? { cursor: (data.cursor ?? null) } : {}),
+                    ...(data.direction === 'before' || data.direction === 'after' ? { direction: data.direction } : {}),
+                    ...(data.scope === 'main' || data.scope === 'sidechain' || data.scope === 'all' ? { scope: data.scope } : {}),
+                    ...(hasOwn(data, 'sidechainId') ? { sidechainId: (data.sidechainId ?? null) } : {}),
+                    ...(Array.isArray(data.roles) ? { roles: data.roles } : {}),
+                    ...(pickBoolean(data, 'includeTools') !== undefined ? { includeTools: pickBoolean(data, 'includeTools') } : {}),
+                    ...(pickBoolean(data, 'includeReasoning') !== undefined ? { includeReasoning: pickBoolean(data, 'includeReasoning') } : {}),
+                    ...(pickBoolean(data, 'includeEvents') !== undefined ? { includeEvents: pickBoolean(data, 'includeEvents') } : {}),
+                    ...(pickBoolean(data, 'includeMeta') !== undefined ? { includeMeta: pickBoolean(data, 'includeMeta') } : {}),
+                    ...(pickBoolean(data, 'includeStructuredPayload') !== undefined ? { includeStructuredPayload: pickBoolean(data, 'includeStructuredPayload') } : {}),
+                    ...(pickBoolean(data, 'includeRaw') !== undefined ? { includeRaw: pickBoolean(data, 'includeRaw') } : {}),
+                    ...(hasOwn(data, 'maxCharsPerMessage') ? { maxCharsPerMessage: (data.maxCharsPerMessage ?? null) } : {}),
+                    ...(hasOwn(data, 'maxRawPayloadChars') ? { maxRawPayloadChars: (data.maxRawPayloadChars ?? null) } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
+            if (actionId === 'session.events.get') {
+                const sessionId = normalizeId(parsed.data.sessionId);
+                if (!sessionId)
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                if (!deps.sessionEventsGet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.events.get' };
+                }
+                const serverId = resolveServerIdForSession(deps, ctx, sessionId);
+                const data = parsed.data;
+                const res = await deps.sessionEventsGet({
+                    sessionId,
+                    ...(typeof data.limit === 'number' ? { limit: data.limit } : {}),
+                    ...(hasOwn(data, 'cursor') ? { cursor: (data.cursor ?? null) } : {}),
+                    ...(data.direction === 'before' || data.direction === 'after' ? { direction: data.direction } : {}),
+                    ...(data.scope === 'main' || data.scope === 'sidechain' || data.scope === 'all' ? { scope: data.scope } : {}),
+                    ...(hasOwn(data, 'sidechainId') ? { sidechainId: (data.sidechainId ?? null) } : {}),
+                    ...(Array.isArray(data.roles) ? { roles: data.roles } : {}),
+                    ...(Array.isArray(data.kinds) ? { kinds: data.kinds } : {}),
+                    ...(data.format === 'raw' || data.format === 'compact' ? { format: data.format } : {}),
+                    ...(pickBoolean(data, 'includeMeta') !== undefined ? { includeMeta: pickBoolean(data, 'includeMeta') } : {}),
+                    ...(pickBoolean(data, 'includeStructuredPayload') !== undefined ? { includeStructuredPayload: pickBoolean(data, 'includeStructuredPayload') } : {}),
+                    ...(pickBoolean(data, 'includeRaw') !== undefined ? { includeRaw: pickBoolean(data, 'includeRaw') } : {}),
+                    ...(typeof data.maxTextChars === 'number' ? { maxTextChars: data.maxTextChars } : {}),
+                    ...(typeof data.maxPayloadChars === 'number' ? { maxPayloadChars: data.maxPayloadChars } : {}),
+                    ...(serverId ? { serverId } : {}),
+                });
+                return { ok: true, result: res };
+            }
             if (actionId === 'session.wait.idle') {
                 const sessionId = normalizeId(parsed.data.sessionId);
                 if (!sessionId)
@@ -835,7 +1960,11 @@ export function createActionExecutor(deps) {
                     requestId: Object.prototype.hasOwnProperty.call(parsed.data, 'requestId') ? (parsed.data.requestId ?? null) : null,
                     answers: Array.isArray(parsed.data.answers) ? (parsed.data.answers.map((entry) => ({
                         question: String(entry?.question ?? ''),
-                        answer: String(entry?.answer ?? ''),
+                        values: Array.isArray(entry?.values)
+                            ? entry.values.map((value) => String(value))
+                            : typeof entry?.answer === 'string'
+                                ? [entry.answer]
+                                : [],
                     }))) : [],
                     ...(typeof parsed.data.decision === 'string' ? { decision: parsed.data.decision } : {}),
                     ...(typeof parsed.data.reason === 'string' ? { reason: parsed.data.reason } : {}),
@@ -887,6 +2016,7 @@ export function createActionExecutor(deps) {
                     ...(typeof parsed.data.archivedOnly === 'boolean' ? { archivedOnly: parsed.data.archivedOnly } : {}),
                     ...(typeof parsed.data.includeSystem === 'boolean' ? { includeSystem: parsed.data.includeSystem } : {}),
                     ...(typeof parsed.data.resumableOnly === 'boolean' ? { resumableOnly: parsed.data.resumableOnly } : {}),
+                    ...(typeof parsed.data.includeRows === 'boolean' ? { includeRows: parsed.data.includeRows } : {}),
                 });
                 return { ok: true, result: res };
             }
@@ -904,13 +2034,21 @@ export function createActionExecutor(deps) {
                 const sessionId = normalizeId(parsed.data.sessionId);
                 if (!sessionId)
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
-                const res = await deps.sessionRecentMessagesGet({
+                if (!deps.sessionTranscriptGet) {
+                    return { ok: false, errorCode: 'unsupported_action', error: 'unsupported_action:session.transcript.get' };
+                }
+                const includeUser = parsed.data.includeUser !== false;
+                const includeAssistant = parsed.data.includeAssistant !== false;
+                const roles = [];
+                if (includeUser)
+                    roles.push('user');
+                if (includeAssistant)
+                    roles.push('assistant');
+                const res = await deps.sessionTranscriptGet({
                     sessionId,
-                    defaultSessionId: normalizeId(ctx.defaultSessionId) || null,
                     ...(typeof parsed.data.limit === 'number' ? { limit: parsed.data.limit } : {}),
                     ...(Object.prototype.hasOwnProperty.call(parsed.data, 'cursor') ? { cursor: (parsed.data.cursor ?? null) } : {}),
-                    ...(typeof parsed.data.includeUser === 'boolean' ? { includeUser: parsed.data.includeUser } : {}),
-                    ...(typeof parsed.data.includeAssistant === 'boolean' ? { includeAssistant: parsed.data.includeAssistant } : {}),
+                    roles,
                     ...(Object.prototype.hasOwnProperty.call(parsed.data, 'maxCharsPerMessage') ? { maxCharsPerMessage: (parsed.data.maxCharsPerMessage ?? null) } : {}),
                 });
                 return { ok: true, result: res };
@@ -1099,22 +2237,32 @@ export function createActionExecutor(deps) {
                 }
                 const now = Date.now();
                 const targetActionId = parsed.data.actionId;
-                if (targetActionId === 'approval.request.create' || targetActionId === 'approval.request.decide') {
+                if (isApprovalActionId(targetActionId)) {
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
                 }
                 // Approvals eligibility is policy-driven (settings/surface), not safety-driven.
                 // Safety metadata remains useful for UI copy and defaults, but it is not a hard gate here.
-                getActionSpec(targetActionId);
+                const targetSpec = getActionSpec(targetActionId);
+                const parsedTargetArgs = targetSpec.inputSchema.safeParse(parsed.data.actionArgs ?? {});
+                if (!parsedTargetArgs.success) {
+                    return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
+                }
                 const rawCreatedBy = parsed.data.createdBy;
                 const forcedSurface = mapApprovalCreatedBySurface(ctx.surface ?? null);
-                const actionArgsSessionId = normalizeId(parsed.data.actionArgs?.sessionId);
+                const actionArgsSessionId = normalizeId(parsedTargetArgs.data?.sessionId);
                 const ctxDefaultSessionId = normalizeId(ctx.defaultSessionId);
+                const targetSessionId = actionArgsSessionId || ctxDefaultSessionId || null;
+                const rawApprovalOrigin = Object.prototype.hasOwnProperty.call(parsed.data, 'origin')
+                    ? parsed.data.origin
+                    : ctx.approvalOrigin;
+                const requestSessionId = resolveExplicitApprovalRequestingSessionId(rawApprovalOrigin, ctx, targetSessionId);
+                const approvalOrigin = resolveApprovalOriginForRequest(rawApprovalOrigin, requestSessionId);
                 const rawAgentId = rawCreatedBy && typeof rawCreatedBy === 'object' ? normalizeId(rawCreatedBy.agentId) : null;
                 const requestedSurface = parseActionSurfaceKey(ctx.surface);
                 const createdBy = {
                     surface: forcedSurface,
                     ...(rawAgentId ? { agentId: rawAgentId } : {}),
-                    ...(actionArgsSessionId ? { sessionId: actionArgsSessionId } : ctxDefaultSessionId ? { sessionId: ctxDefaultSessionId } : {}),
+                    ...(requestSessionId ? { sessionId: requestSessionId } : {}),
                 };
                 const summary = String(parsed.data.summary ?? '').trim();
                 if (!summary)
@@ -1127,7 +2275,9 @@ export function createActionExecutor(deps) {
                     createdBy,
                     ...(requestedSurface ? { requestedSurface } : {}),
                     actionId: targetActionId,
-                    actionArgs: parsed.data.actionArgs,
+                    actionArgs: parsedTargetArgs.data,
+                    approval: buildApprovalMetadata(targetSpec),
+                    ...(approvalOrigin ? { origin: approvalOrigin } : {}),
                     summary,
                     ...(normalizeId(ctx.serverId) ? { serverId: normalizeId(ctx.serverId) } : {}),
                     ...(Object.prototype.hasOwnProperty.call(parsed.data, 'preview') ? { preview: parsed.data.preview } : {}),
@@ -1151,7 +2301,7 @@ export function createActionExecutor(deps) {
                 const existing = existingParsed.data;
                 const effectiveServerId = normalizeId(ctx.serverId) || normalizeId(existing.serverId) || null;
                 const decision = parsed.data.decision;
-                if (existing.actionId === 'approval.request.create' || existing.actionId === 'approval.request.decide') {
+                if (isApprovalActionId(existing.actionId)) {
                     return { ok: false, errorCode: 'invalid_parameters', error: 'invalid_parameters' };
                 }
                 const isRecoverableApproved = decision === 'approve'
@@ -1181,6 +2331,12 @@ export function createActionExecutor(deps) {
                     const updated = await deps.approvalsUpdate({ artifactId, request: nextRejected, serverId: effectiveServerId });
                     if (updated?.ok === false)
                         return { ok: false, errorCode: updated.errorCode, error: updated.error };
+                    await resolveBlockingDecisionWaiter({
+                        artifactId,
+                        request: nextRejected,
+                        decision: 'reject',
+                        effectiveServerId,
+                    });
                     return buildApprovalDecisionResult(nextRejected);
                 }
                 let approvedRequest = existing;
@@ -1200,41 +2356,52 @@ export function createActionExecutor(deps) {
                         return { ok: false, errorCode: approved.errorCode, error: approved.error };
                     }
                 }
-                const requestSurface = parseActionSurfaceKey(approvedRequest.requestedSurface)
-                    ?? resolveApprovalRequestExecutionSurface(existing.createdBy.surface);
-                const requestDefaultSessionId = typeof existing.createdBy.sessionId === 'string' ? existing.createdBy.sessionId.trim() : '';
-                const exec = requestSurface
-                    ? await execute(existing.actionId, existing.actionArgs, {
-                        ...ctx,
-                        ...(effectiveServerId ? { serverId: effectiveServerId } : {}),
-                        ...(requestDefaultSessionId ? { defaultSessionId: requestDefaultSessionId } : {}),
-                        surface: requestSurface,
-                        placement: null,
-                        bypassApprovals: true,
-                    })
-                    : { ok: false, errorCode: 'approval_execution_surface_invalid', error: 'approval_execution_surface_invalid' };
-                const executedAtMs = Date.now();
-                const nextExecuted = {
-                    ...approvedRequest,
-                    status: exec.ok ? 'executed' : 'failed',
-                    updatedAtMs: executedAtMs,
-                    execution: exec.ok
-                        ? { executedAtMs, ok: true, result: exec.result }
-                        : { executedAtMs, ok: false, errorCode: exec.errorCode, error: exec.error },
-                };
-                const updated = await deps.approvalsUpdate({ artifactId, request: nextExecuted, serverId: effectiveServerId });
-                if (updated?.ok === false)
-                    return { ok: false, errorCode: updated.errorCode, error: updated.error };
-                return buildApprovalDecisionResult(nextExecuted);
+                const delegatedToBlockingWaiter = await resolveBlockingDecisionWaiter({
+                    artifactId,
+                    request: approvedRequest,
+                    decision: 'approve',
+                    effectiveServerId,
+                });
+                if (delegatedToBlockingWaiter) {
+                    return buildApprovalDecisionResult(approvedRequest);
+                }
+                const executed = await executeApprovedActionForRequest({
+                    artifactId,
+                    request: approvedRequest,
+                    ctx,
+                    effectiveServerId,
+                });
+                if (!executed.ok)
+                    return executed;
+                return buildApprovalDecisionResult(executed.request);
             }
             return { ok: false, errorCode: 'unsupported_action', error: `unsupported_action:${actionId}` };
         }
         catch (error) {
+            if (ctx.signal?.aborted && error instanceof Error && error.name === 'AbortError') {
+                throw error;
+            }
             const normalized = normalizeActionExecutorThrownError(error);
-            return { ok: false, errorCode: normalized.errorCode, error: normalized.error };
+            return {
+                ok: false,
+                errorCode: normalized.errorCode,
+                error: normalized.error,
+                ...(normalized.details !== undefined ? { details: normalized.details } : {}),
+            };
         }
     };
+    const prepare = async (actionId, input, context) => {
+        const result = await executeOrPrepare(actionId, input, context, { prepareOnly: true });
+        return 'kind' in result ? result : { kind: 'settled', result };
+    };
+    const execute = async (actionId, input, context) => {
+        const result = await executeOrPrepare(actionId, input, context);
+        if ('kind' in result)
+            throw new Error('Direct Action execution unexpectedly returned a prepared invocation');
+        return result;
+    };
     return {
+        prepare,
         execute,
     };
 }