evolcore 0.0.1 → 0.0.3

package/dist/core/permission/approval-gateway.js

@@ -0,0 +1,1017 @@
+import { createHash, randomUUID } from 'crypto';
+import { hasTrustedPrincipal } from '../auth/authenticated-actor.js';
+import { renderActionAsText } from '../interaction-router.js';
+import { buildEnvelope, sendInteractionPayload } from '../message/message-utils.js';
+import { logger } from '../../utils/logger.js';
+import { summarizeToolInput } from '../../utils/tool-summary.js';
+import { createRootCausation, deriveCausation, normalizeCausation } from '../causation/context.js';
+import { recordCausationSpan } from '../causation/audit.js';
+import { checkDangerousCommand } from './tool-policy.js';
+export async function requestDangerousCommandPermission(gateway, sessionId, toolName, input, sendPrompt, context, grantScope = 'default', mode = 'request') {
+    const dangerCheck = checkDangerousCommand(toolName, input);
+    if (!dangerCheck.isDangerous) {
+        return { matched: false };
+    }
+    if (mode === 'bypass' && dangerCheck.approvalScope === 'request') {
+        return { matched: true, decision: 'allow' };
+    }
+    if (!gateway || !sendPrompt) {
+        logger.warn(`[PermissionGateway] Dangerous operation denied because approval is unavailable: session=${sessionId} tool=${toolName}`);
+        return { matched: true, decision: 'deny' };
+    }
+    const decision = await gateway.requestPermission(sessionId, dangerCheck.cacheKey, input, sendPrompt, context, `⚠️ ${dangerCheck.command}`, dangerCheck.reason, grantScope, dangerCheck.kind === 'git-destructive' ? 'agent_manager' : undefined);
+    return { matched: true, decision };
+}
+const SESSION_GRANT_TTL_MS = 30 * 60 * 1000;
+const LOCAL_APPROVAL_TTL_MS = 20 * 60 * 1000;
+const MANAGEMENT_APPROVAL_REVALIDATION_INTERVAL_MS = 5_000;
+const APPROVAL_DETAIL_LIMIT = 800;
+function stablePermissionInput(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'bigint')
+        return `${value.toString()}n`;
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? String(value);
+    if (Array.isArray(value))
+        return `[${value.map(stablePermissionInput).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stablePermissionInput(record[key])}`).join(',')}}`;
+}
+function permissionInputFingerprint(input) {
+    return createHash('sha256').update(stablePermissionInput(input)).digest('hex');
+}
+function truncateApprovalDetail(value) {
+    const trimmed = value.trim();
+    return trimmed.length > APPROVAL_DETAIL_LIMIT
+        ? `${trimmed.slice(0, APPROVAL_DETAIL_LIMIT - 3)}...`
+        : trimmed;
+}
+function structuredApprovalAuditSummary(input) {
+    const fields = [...new Set(Object.keys(input)
+            .map(key => key.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 48))
+            .filter(Boolean))]
+        .sort()
+        .slice(0, 16);
+    return fields.length > 0 ? `input_fields=${fields.join(',')}` : 'input_withheld';
+}
+function requiredApproverRole(policy, routeKind) {
+    if (policy === 'requester')
+        return 'requester';
+    if (policy === 'agent_owner' || routeKind === 'handoff')
+        return 'owner';
+    return 'manager';
+}
+function formatApprovalTarget(toolName, input) {
+    if (toolName === 'Bash' || toolName.startsWith('dangerous:Bash:')) {
+        const command = typeof input.command === 'string' ? input.command : '';
+        if (command)
+            return truncateApprovalDetail(command);
+    }
+    const summary = summarizeToolInput(toolName, input);
+    if (summary)
+        return truncateApprovalDetail(summary);
+    return truncateApprovalDetail(stablePermissionInput(input));
+}
+function escapeApprovalMarkdown(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/([`*_{}[\]()])/g, '\\$1')
+        .replace(/^(\s*)(#{1,6}|>|[-+])(\s)/gm, '$1\\$2$3')
+        .replace(/^(\s*\d+)\.(\s)/gm, '$1\\.$2');
+}
+function approvalInlineCode(value) {
+    const text = value.replace(/\s+/g, ' ').trim();
+    const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map(run => run.length));
+    const fence = '`'.repeat(longestRun + 1);
+    return `${fence}${text}${fence}`;
+}
+function approvalCodeBlock(value) {
+    const longestRun = Math.max(0, ...(value.match(/`+/g) ?? []).map(run => run.length));
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return `${fence}text\n${value}\n${fence}`;
+}
+export function planApprovalRoute(challenge, context) {
+    if (!challenge.grantable) {
+        return { kind: 'unavailable', reason: 'challenge_not_grantable' };
+    }
+    const actor = context?.actor;
+    if (actor && context?.userId && actor.operatorId !== context.userId) {
+        return { kind: 'unavailable', reason: 'actor_operator_mismatch' };
+    }
+    if (actor && context?.adapter && actor.operatorChannelKey !== context.adapter.channelKey) {
+        return { kind: 'unavailable', reason: 'actor_channel_mismatch' };
+    }
+    const requesterId = actor?.operatorId || context?.userId || '';
+    if (!requesterId)
+        return { kind: 'unavailable', reason: 'no_requester_approver' };
+    const requesterChannelKey = actor?.operatorChannelKey || context?.adapter?.channelKey;
+    if (challenge.approverPolicy === 'requester') {
+        return {
+            kind: 'local',
+            approverOperatorId: requesterId,
+            approverChannelKey: requesterChannelKey,
+            approverPrincipalId: hasTrustedPrincipal(actor) ? actor.principalId : undefined,
+        };
+    }
+    const routing = context?.approvalRouting;
+    let candidateSnapshot;
+    if (routing?.resolveApproverCandidates) {
+        try {
+            candidateSnapshot = routing.resolveApproverCandidates();
+        }
+        catch {
+            return { kind: 'unavailable', reason: 'approver_candidates_unavailable' };
+        }
+    }
+    const owners = Array.from(new Set((candidateSnapshot?.owners ?? routing?.owners ?? []).filter(Boolean)));
+    const admins = Array.from(new Set((candidateSnapshot?.admins ?? routing?.admins ?? []).filter(Boolean)));
+    const eligibleLocalPrincipals = challenge.approverPolicy === 'agent_manager'
+        ? new Set([...owners, ...admins])
+        : new Set(owners);
+    const supportsAuthenticatedApproval = context?.adapter?.capabilities.authenticatedApproval === true;
+    const actorMatchesContext = !!actor
+        && actor.operatorId === requesterId
+        && (!context?.userId || actor.operatorId === context.userId)
+        && actor.operatorChannelKey === requesterChannelKey
+        && context?.adapter?.channelKey === actor.operatorChannelKey;
+    if (!routing?.forceHandoff
+        && context?.chatType !== 'group'
+        && supportsAuthenticatedApproval
+        && actorMatchesContext
+        && hasTrustedPrincipal(actor)
+        && eligibleLocalPrincipals.has(actor.principalId)) {
+        return {
+            kind: 'local',
+            approverOperatorId: actor.operatorId,
+            approverChannelKey: actor.operatorChannelKey,
+            approverPrincipalId: actor.principalId,
+        };
+    }
+    if (owners.length === 0) {
+        return { kind: 'unavailable', reason: 'no_agent_owner_configured' };
+    }
+    // Both management policies hand off to the first configured AUN owner.
+    // Admin handoff approval and implicit approver selection are intentionally
+    // out of scope; a future caller may explicitly select from the owner list.
+    const approverId = owners[0];
+    if (!approverId) {
+        return { kind: 'unavailable', reason: 'no_aun_owner_available' };
+    }
+    if (!routing?.ownerAdapter) {
+        return { kind: 'unavailable', reason: 'owner_approval_channel_unavailable' };
+    }
+    return {
+        kind: 'handoff',
+        approverOperatorId: approverId,
+        approverChannelKey: routing.ownerAdapter.channelKey,
+        approverPrincipalId: approverId,
+        channel: 'aun',
+        adapter: routing.ownerAdapter,
+    };
+}
+export class PermissionGateway {
+    pending = new Map();
+    crossSessionPending = new Map();
+    temporaryGrants = new Map();
+    managementRevalidationTimer;
+    eventBus;
+    setEventBus(eventBus) {
+        this.eventBus = eventBus;
+    }
+    hasManagementPending() {
+        return [...this.pending.values(), ...this.crossSessionPending.values()]
+            .some(pending => pending.requiredApproverRole !== 'requester');
+    }
+    syncManagementRevalidationTimer() {
+        if (!this.hasManagementPending()) {
+            if (this.managementRevalidationTimer)
+                clearTimeout(this.managementRevalidationTimer);
+            this.managementRevalidationTimer = undefined;
+            return;
+        }
+        if (this.managementRevalidationTimer)
+            return;
+        this.managementRevalidationTimer = setTimeout(() => {
+            this.managementRevalidationTimer = undefined;
+            this.revalidatePendingApprovals(undefined, 'periodic');
+            this.syncManagementRevalidationTimer();
+        }, MANAGEMENT_APPROVAL_REVALIDATION_INTERVAL_MS);
+        this.managementRevalidationTimer.unref?.();
+    }
+    clearPendingResources(pending) {
+        if (pending.timeout)
+            clearTimeout(pending.timeout);
+        if (pending.abortSignal && pending.abortListener) {
+            pending.abortSignal.removeEventListener('abort', pending.abortListener);
+        }
+    }
+    bindAbortSignal(pending, signal, onAbort) {
+        if (!signal)
+            return false;
+        pending.abortSignal = signal;
+        pending.abortListener = onAbort;
+        if (signal.aborted) {
+            onAbort();
+            return true;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        return false;
+    }
+    /** Clear all temporary grants when the permission context changes. */
+    clearAlwaysAllow() {
+        this.temporaryGrants.clear();
+    }
+    temporaryGrantKey(sessionId, toolName, inputFingerprint, grantScope) {
+        return `${sessionId}\u0000${grantScope}\u0000${toolName}\u0000${inputFingerprint}`;
+    }
+    pruneTemporaryGrants(now) {
+        for (const [key, grant] of this.temporaryGrants.entries()) {
+            if (grant.expiresAt <= now)
+                this.temporaryGrants.delete(key);
+        }
+    }
+    hasTemporaryGrant(sessionId, toolName, toolInput, grantScope = 'default') {
+        return !!this.getTemporaryGrant(sessionId, toolName, toolInput, grantScope);
+    }
+    getTemporaryGrant(sessionId, toolName, toolInput, grantScope = 'default') {
+        const now = Date.now();
+        this.pruneTemporaryGrants(now);
+        const key = this.temporaryGrantKey(sessionId, toolName, permissionInputFingerprint(toolInput), grantScope);
+        return this.temporaryGrants.get(key);
+    }
+    addTemporaryGrant(pending, causation) {
+        const now = Date.now();
+        this.pruneTemporaryGrants(now);
+        const expiresAt = now + SESSION_GRANT_TTL_MS;
+        const key = this.temporaryGrantKey(pending.sessionId, pending.toolName, pending.inputFingerprint, pending.grantScope);
+        this.temporaryGrants.set(key, { expiresAt, causation: normalizeCausation(causation) });
+        return expiresAt;
+    }
+    authorizePendingResponse(pending, operatorId, channelKey) {
+        if (!operatorId || operatorId !== pending.approverOperatorId) {
+            return { status: 'identity_mismatch' };
+        }
+        if (pending.approverChannelKey && channelKey !== pending.approverChannelKey) {
+            return { status: 'identity_mismatch' };
+        }
+        if (pending.requiredApproverRole === 'requester') {
+            return pending.approverPolicy === 'requester'
+                ? { status: 'authorized' }
+                : { status: 'revoked', reason: 'approver_role_requirement_invalid' };
+        }
+        if (pending.approverPolicy === 'requester') {
+            return { status: 'revoked', reason: 'approver_role_requirement_invalid' };
+        }
+        if (!pending.approverChannelKey || !pending.approverPrincipalId) {
+            return { status: 'revoked', reason: 'approver_identity_incomplete' };
+        }
+        if (!pending.reauthorizeApproval) {
+            return { status: 'revoked', reason: 'approver_reauthorization_unavailable' };
+        }
+        const request = {
+            approverPolicy: pending.approverPolicy,
+            operatorId,
+            operatorChannelKey: channelKey,
+            expectedPrincipalId: pending.approverPrincipalId,
+            selfAid: pending.selfAid,
+            originPrincipalId: pending.originPrincipalId,
+            originAuthRevision: pending.originAuthRevision,
+        };
+        let result;
+        try {
+            result = pending.reauthorizeApproval(request);
+        }
+        catch (error) {
+            logger.warn(`[PermissionGateway] Approval reauthorization failed: operator=${operatorId} policy=${pending.approverPolicy} error=${error instanceof Error ? error.message : String(error)}`);
+            return { status: 'revoked', reason: 'approver_reauthorization_failed' };
+        }
+        if (!result.ok)
+            return { status: 'revoked', reason: result.reason };
+        const actor = result.actor;
+        if (actor.operatorId !== operatorId || actor.operatorChannelKey !== channelKey) {
+            return { status: 'revoked', reason: 'approver_identity_changed' };
+        }
+        if (!hasTrustedPrincipal(actor)) {
+            const reason = actor.principalStatus === 'unmapped'
+                ? 'principal_mapping_removed'
+                : actor.principalStatus === 'conflict'
+                    ? 'principal_mapping_conflict'
+                    : 'approver_identity_untrusted';
+            return { status: 'revoked', reason };
+        }
+        if (actor.principalId !== pending.approverPrincipalId) {
+            return { status: 'revoked', reason: 'principal_mapping_changed' };
+        }
+        const owners = new Set(result.owners.filter(Boolean));
+        const admins = new Set(result.admins.filter(Boolean));
+        const eligible = pending.requiredApproverRole === 'owner'
+            ? owners.has(actor.principalId)
+            : owners.has(actor.principalId) || admins.has(actor.principalId);
+        if (!eligible) {
+            const stillAssigned = owners.has(actor.principalId) || admins.has(actor.principalId);
+            return {
+                status: 'revoked',
+                reason: stillAssigned ? 'approver_role_changed' : 'approver_revoked',
+            };
+        }
+        if (pending.originPrincipalId !== undefined
+            && result.originPrincipalId !== pending.originPrincipalId) {
+            return { status: 'revoked', reason: 'origin_authorization_changed' };
+        }
+        if (pending.originAuthRevision !== undefined
+            && result.originAuthRevision !== pending.originAuthRevision) {
+            return { status: 'revoked', reason: 'origin_authorization_changed' };
+        }
+        return { status: 'authorized' };
+    }
+    /** Legacy diagnostics alias. Grants are no longer tool-wide or permanent. */
+    getAlwaysAllowList() {
+        this.pruneTemporaryGrants(Date.now());
+        return [...this.temporaryGrants.keys()];
+    }
+    resolveCrossSessionPermission(sessionId, requestId, action, _values, operatorId, channelKey) {
+        const pending = this.crossSessionPending.get(requestId);
+        if (!pending || pending.sessionId !== sessionId)
+            return false;
+        const authorization = this.authorizePendingResponse(pending, operatorId, channelKey);
+        if (authorization.status === 'identity_mismatch')
+            return false;
+        if (authorization.status === 'revoked') {
+            logger.info(`[PermissionGateway] approval_revoked request=${requestId} policy=${pending.approverPolicy} reason=${authorization.reason}`);
+            this.expireCrossSessionPermission(sessionId, requestId, authorization.reason);
+            return false;
+        }
+        this.clearPendingResources(pending);
+        pending.interactionRouter?.cancel(requestId);
+        this.crossSessionPending.delete(requestId);
+        this.syncManagementRevalidationTimer();
+        const sessionGrant = action === 'approve_session_30m';
+        const approved = action === 'approve_once' || sessionGrant || action === 'allow';
+        const decision = approved ? 'allow' : 'deny';
+        const decisionCausation = deriveCausation(pending.causation);
+        if (sessionGrant)
+            this.addTemporaryGrant(pending, decisionCausation);
+        pending.resolve(decision);
+        void this.notifyPermissionState(pending, approved
+            ? { state: 'approved', requestId, toolName: pending.toolName }
+            : {
+                state: 'failed',
+                requestId,
+                toolName: pending.toolName,
+                reason: 'denied',
+                message: 'owner 已拒绝授权，任务已停止。',
+            });
+        recordCausationSpan(decisionCausation, 'permission.decision', {
+            status: approved ? 'completed' : 'failed',
+            refs: { permissionRequestId: requestId, sessionId },
+            reason: approved ? undefined : 'denied',
+        });
+        this.eventBus?.publish({ type: 'permission:resolved', sessionId, requestId, approved, causation: decisionCausation });
+        return true;
+    }
+    expireCrossSessionPermission(sessionId, requestId, reason, notifyState = true, cancelled = reason === 'cancelled') {
+        const pending = this.crossSessionPending.get(requestId);
+        if (!pending || pending.sessionId !== sessionId)
+            return false;
+        this.clearPendingResources(pending);
+        pending.interactionRouter?.cancel(requestId, reason);
+        this.crossSessionPending.delete(requestId);
+        this.syncManagementRevalidationTimer();
+        pending.resolve('deny');
+        if (notifyState) {
+            const failure = permissionFailure(reason);
+            void this.notifyPermissionState(pending, {
+                state: 'failed',
+                requestId,
+                toolName: pending.toolName,
+                reason,
+                message: failure,
+            });
+        }
+        const decisionCausation = deriveCausation(pending.causation);
+        recordCausationSpan(decisionCausation, 'permission.decision', {
+            status: 'failed',
+            refs: { permissionRequestId: requestId, sessionId },
+            reason,
+        });
+        if (cancelled) {
+            this.eventBus?.publish({
+                type: 'permission:cancelled',
+                sessionId,
+                requestId,
+                toolName: pending.toolName,
+                reason,
+                causation: decisionCausation,
+            });
+        }
+        else {
+            this.eventBus?.publish({
+                type: 'permission:resolved',
+                sessionId,
+                requestId,
+                toolName: pending.toolName,
+                reason,
+                approved: false,
+                causation: decisionCausation,
+            });
+        }
+        return true;
+    }
+    async requestCrossSessionPermission(sessionId, challenge, route, sendPrompt, context, grantScope, requestCausation) {
+        const approval = context.approvalRouting;
+        const interactionRouter = context.interactionRouter;
+        if (!approval || !interactionRouter) {
+            await sendPrompt('当前会话权限不足，且没有可用的 owner 审批通道。');
+            return 'deny';
+        }
+        const { id: requestId, toolName, toolInput, summary: displaySummary, reason } = challenge;
+        const ttlMs = approval.approvalTtlMs && approval.approvalTtlMs > 0
+            ? approval.approvalTtlMs
+            : 20 * 60 * 1000;
+        const expiresAt = Date.now() + ttlMs;
+        const originRole = approval.originRole || context.role || 'none';
+        const requesterId = approval.originPeerId || approval.originChannelId || 'unknown';
+        const requester = approval.originPeerName
+            ? `${approval.originPeerName} (${requesterId})`
+            : requesterId;
+        const originChannel = approval.originChannel || context.channel || 'unknown';
+        const distinctSource = approval.originChannelId
+            && approval.originChannelId !== requesterId
+            ? approval.originChannelId
+            : undefined;
+        const approvalDeadline = new Date(expiresAt).toLocaleString('zh-CN', { hour12: false });
+        const target = formatApprovalTarget(toolName, toolInput);
+        const body = [
+            '**申请信息**',
+            '',
+            `- **申请主体**：${approvalInlineCode(requester)} · role ${approvalInlineCode(originRole)} · via ${approvalInlineCode(originChannel)}`,
+            ...(distinctSource ? [`- **来源会话**：${approvalInlineCode(distinctSource)}`] : []),
+            '',
+            '**请求执行**',
+            '',
+            `- **申请能力**：${approvalInlineCode(`tool:${toolName}`)}`,
+            `- **预期动作**：${escapeApprovalMarkdown(displaySummary)}`,
+            `- **申请原因**：${escapeApprovalMarkdown(reason || '工具运行时要求人工授权')}`,
+            '',
+            '**目标 / 参数**',
+            '',
+            approvalCodeBlock(target),
+            '',
+            '**风险与有效期**',
+            '',
+            '- **风险：中** · 跨会话临时授权，请核对目标和参数',
+            `- **审批截止**：${escapeApprovalMarkdown(approvalDeadline)}（约 ${Math.round(ttlMs / 60000)} 分钟）`,
+        ].join('\n');
+        const interaction = {
+            type: 'interaction',
+            id: requestId,
+            kind: {
+                kind: 'action',
+                title: '临时授权申请',
+                body,
+                bodyFormat: 'markdown',
+                buttons: [
+                    { key: 'approve_once', label: '批准本次', style: 'primary' },
+                    { key: 'approve_session_30m', label: '本会话 30 分钟', style: 'default' },
+                    { key: 'deny', label: '拒绝', style: 'danger' },
+                ],
+            },
+            channelId: route.approverOperatorId,
+            sessionId,
+            initiatorId: route.approverOperatorId || undefined,
+            expiresAt,
+            fallback: {
+                command: 'perm',
+                buttonArgMap: {
+                    approve_once: `${requestId} allow`,
+                    approve_session_30m: `${requestId} always`,
+                    deny: `${requestId} deny`,
+                },
+            },
+        };
+        // Register before delivery. Some adapters can surface a user response as
+        // soon as send() completes; registering afterwards creates a narrow race
+        // where a valid approval is visible to the user but dropped by the router.
+        const decisionPromise = new Promise((resolve) => {
+            const pending = {
+                sessionId,
+                requestId,
+                toolName,
+                displaySummary,
+                reason,
+                resolve,
+                inputFingerprint: permissionInputFingerprint(toolInput),
+                grantScope,
+                approverPolicy: challenge.approverPolicy,
+                approvalRouteKind: route.kind,
+                requiredApproverRole: requiredApproverRole(challenge.approverPolicy, route.kind),
+                approverOperatorId: route.approverOperatorId,
+                approverChannelKey: route.approverChannelKey,
+                approverPrincipalId: route.approverPrincipalId,
+                selfAid: approval.selfAid,
+                originPrincipalId: approval.originPrincipalId,
+                originAuthRevision: approval.originAuthRevision,
+                reauthorizeApproval: approval.reauthorizeApproval,
+                interactionRouter,
+                causation: requestCausation,
+                permissionStateChanged: context.permissionStateChanged,
+            };
+            this.crossSessionPending.set(requestId, pending);
+            this.syncManagementRevalidationTimer();
+            interactionRouter.register(requestId, sessionId, (action, values, operatorId, channelKey) => {
+                return this.resolveCrossSessionPermission(sessionId, requestId, action, values, operatorId, channelKey);
+            }, {
+                initiatorId: route.approverOperatorId,
+                initiatorChannelKey: route.approverChannelKey,
+                timeoutMs: ttlMs,
+                timeoutCancelReason: 'expired',
+                onTimeout: () => this.expireCrossSessionPermission(sessionId, requestId, 'expired'),
+                onChannelCancel: reason => this.expireCrossSessionPermission(sessionId, requestId, reason),
+                onCancel: reason => route.adapter.invalidateInteraction?.(requestId, reason),
+                fallbackCommand: 'perm',
+            });
+        });
+        const crossPending = this.crossSessionPending.get(requestId);
+        if (!crossPending)
+            return decisionPromise;
+        if (this.bindAbortSignal(crossPending, context.abortSignal, () => this.expireCrossSessionPermission(sessionId, requestId, 'cancelled'))) {
+            return decisionPromise;
+        }
+        if (context.flushPending) {
+            try {
+                await context.flushPending();
+            }
+            catch {
+                // flush 失败不阻断审批请求
+            }
+        }
+        // The origin flush can yield long enough for an alias/config watcher or
+        // periodic revalidation to revoke this request. Do not deliver a stale card.
+        if (this.crossSessionPending.get(requestId) !== crossPending) {
+            return decisionPromise;
+        }
+        const currentAuthorization = this.authorizePendingResponse(crossPending, crossPending.approverOperatorId, crossPending.approverChannelKey);
+        if (currentAuthorization.status !== 'authorized') {
+            this.expireCrossSessionPermission(sessionId, requestId, currentAuthorization.status === 'revoked'
+                ? currentAuthorization.reason
+                : 'approver_identity_mismatch');
+            return decisionPromise;
+        }
+        const ownerReplyContext = {
+            metadata: {
+                source: 'handoff',
+                chatmode: 'interactive',
+                causation: crossPending.causation,
+            },
+        };
+        const envelope = buildEnvelope({
+            taskId: context.taskId,
+            sessionId,
+            channel: route.adapter.channelName,
+            channelId: route.approverOperatorId,
+            agentName: context.agentName,
+            chatmode: 'interactive',
+            replyContext: ownerReplyContext,
+            causation: crossPending.causation,
+        });
+        let sent = false;
+        try {
+            sent = !!await sendInteractionPayload(route.adapter, envelope, interaction, renderActionAsText(interaction), ownerReplyContext);
+        }
+        catch (error) {
+            logger.warn(`[PermissionGateway] Owner approval delivery failed: session=${sessionId} tool=${toolName} error=${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (this.crossSessionPending.get(requestId) !== crossPending) {
+            return decisionPromise;
+        }
+        if (!sent) {
+            this.expireCrossSessionPermission(sessionId, requestId, 'failed');
+            return decisionPromise;
+        }
+        void this.notifyPermissionState(this.crossSessionPending.get(requestId), {
+            state: 'waiting',
+            requestId,
+            toolName,
+            expiresAt,
+        });
+        return decisionPromise;
+    }
+    async notifyPermissionState(pending, event) {
+        if (!pending?.permissionStateChanged)
+            return;
+        try {
+            await pending.permissionStateChanged(event);
+        }
+        catch (error) {
+            logger.warn(`[PermissionGateway] permission state delivery failed: request=${event.requestId} state=${event.state} error=${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    failPendingPermission(sessionId, requestId, reason) {
+        const pending = this.pending.get(requestId);
+        if (!pending || pending.sessionId !== sessionId)
+            return false;
+        this.clearPendingResources(pending);
+        pending.interactionRouter?.cancel(requestId, reason);
+        this.pending.delete(requestId);
+        this.syncManagementRevalidationTimer();
+        pending.resolve('deny');
+        const decisionCausation = deriveCausation(pending.causation);
+        recordCausationSpan(decisionCausation, 'permission.decision', {
+            status: 'failed',
+            refs: { permissionRequestId: requestId, sessionId },
+            reason,
+        });
+        this.eventBus?.publish({
+            type: 'permission:resolved',
+            sessionId,
+            requestId,
+            toolName: pending.toolName,
+            reason,
+            approved: false,
+            causation: decisionCausation,
+        });
+        return true;
+    }
+    /**
+     * 请求人工审批。返回三态决策。
+     */
+    async requestPermission(sessionId, toolName, toolInput, sendPrompt, context, summary, reason, grantScope = 'default', approverPolicy) {
+        const effectiveApproverPolicy = approverPolicy
+            ?? context?.approvalRouting?.approverPolicy
+            ?? 'requester';
+        if (context?.approvalInteractionPolicy === 'deny') {
+            const anomaly = {
+                code: 'runtime_permission_denied',
+                severity: 'warning',
+                phase: 'execution',
+                occurredAt: Date.now(),
+                toolName,
+                policy: effectiveApproverPolicy,
+                summary: structuredApprovalAuditSummary(toolInput),
+                effect: 'operation_skipped',
+            };
+            try {
+                await context.recordExecutionAnomaly?.(anomaly);
+            }
+            catch (error) {
+                logger.warn(`[PermissionGateway] Failed to record unattended denial: session=${sessionId} tool=${toolName} error=${error instanceof Error ? error.message : String(error)}`);
+            }
+            logger.info(`[PermissionGateway] Unattended runtime permission denied: session=${sessionId} tool=${toolName} policy=${effectiveApproverPolicy}`);
+            return 'deny';
+        }
+        if (!context?.userId) {
+            await sendPrompt('当前操作需要授权，但无法验证申请人身份。');
+            return 'deny';
+        }
+        const temporaryGrant = this.getTemporaryGrant(sessionId, toolName, toolInput, grantScope);
+        if (temporaryGrant) {
+            const consumeCausation = deriveCausation(normalizeCausation(temporaryGrant.causation)
+                ?? normalizeCausation(context?.causation)
+                ?? createRootCausation());
+            recordCausationSpan(consumeCausation, 'permission.consume', {
+                status: 'completed',
+                refs: { taskId: context?.taskId, sessionId },
+                reason: 'temporary_grant',
+            });
+            return 'allow';
+        }
+        const requestId = `perm-${randomUUID()}`;
+        const displaySummary = summary || summarizeToolInput(toolName, toolInput);
+        const reasonLine = reason ? `\n原因：${reason}` : '';
+        const challenge = {
+            id: requestId,
+            sessionId,
+            toolName,
+            toolInput,
+            summary: displaySummary,
+            reason,
+            grantable: true,
+            approverPolicy: effectiveApproverPolicy,
+            createdAt: Date.now(),
+        };
+        const requestCausation = deriveCausation(normalizeCausation(context.causation) ?? createRootCausation());
+        recordCausationSpan(requestCausation, 'permission.request', {
+            status: 'started',
+            refs: { permissionRequestId: requestId, taskId: context.taskId, sessionId },
+        });
+        this.eventBus?.publish({ type: 'permission:requested', sessionId, requestId, toolName, input: displaySummary, causation: requestCausation });
+        const route = planApprovalRoute(challenge, context);
+        logger.info(`[PermissionGateway] approval_route request=${requestId} policy=${challenge.approverPolicy}`
+            + ` route=${route.kind}`
+            + ` operator=${route.kind === 'unavailable' ? '<none>' : route.approverOperatorId}`
+            + ` channel=${route.kind === 'unavailable' ? '<none>' : (route.approverChannelKey ?? '<legacy>')}`
+            + ` principal=${route.kind === 'unavailable' ? '<none>' : (route.approverPrincipalId ?? '<unmapped>')}`
+            + `${route.kind === 'unavailable' ? ` reason=${route.reason}` : ''}`);
+        if (route.kind === 'unavailable') {
+            await sendPrompt(`当前操作需要授权，但审批人不可用（${route.reason}）。`);
+            const decisionCausation = deriveCausation(requestCausation);
+            recordCausationSpan(decisionCausation, 'permission.decision', {
+                status: 'failed',
+                refs: { permissionRequestId: requestId, sessionId },
+                reason: route.reason,
+            });
+            this.eventBus?.publish({
+                type: 'permission:resolved',
+                sessionId,
+                requestId,
+                toolName,
+                reason: route.reason,
+                approved: false,
+                causation: decisionCausation,
+            });
+            return 'deny';
+        }
+        if (route.kind === 'handoff') {
+            return this.requestCrossSessionPermission(sessionId, challenge, route, sendPrompt, context, grantScope, requestCausation);
+        }
+        // 构造 ActionInteraction
+        const interaction = {
+            type: 'interaction',
+            id: requestId,
+            kind: {
+                kind: 'action',
+                title: '🔐 权限请求',
+                body: `工具：${toolName}\n操作：${displaySummary}${reasonLine}`,
+                buttons: [
+                    { key: 'allow', label: '✅ 允许本次', style: 'primary' },
+                    { key: 'always', label: '⏱ 同操作 30 分钟', style: 'default' },
+                    { key: 'deny', label: '❌ 拒绝', style: 'danger' },
+                ],
+            },
+            channelId: context?.channelId || '',
+            sessionId,
+            initiatorId: route.approverOperatorId,
+            expiresAt: Date.now() + LOCAL_APPROVAL_TTL_MS,
+            fallback: {
+                command: 'perm',
+                buttonArgMap: {
+                    allow: `${requestId} allow`,
+                    always: `${requestId} always`,
+                    deny: `${requestId} deny`,
+                },
+            },
+        };
+        // Register before delivery so an immediate card/text response cannot beat
+        // the pending approval handler. The UUID keeps this pre-delivery slot from
+        // being practically guessable.
+        const decisionPromise = new Promise((resolve) => {
+            const pending = {
+                sessionId,
+                toolName,
+                inputFingerprint: permissionInputFingerprint(toolInput),
+                grantScope,
+                approverPolicy: challenge.approverPolicy,
+                approvalRouteKind: route.kind,
+                requiredApproverRole: requiredApproverRole(challenge.approverPolicy, route.kind),
+                approverOperatorId: route.approverOperatorId,
+                approverChannelKey: route.approverChannelKey,
+                approverPrincipalId: route.approverPrincipalId,
+                selfAid: context?.approvalRouting?.selfAid,
+                originPrincipalId: context?.approvalRouting?.originPrincipalId,
+                originAuthRevision: context?.approvalRouting?.originAuthRevision,
+                reauthorizeApproval: context?.approvalRouting?.reauthorizeApproval,
+                resolve,
+                interactionRouter: context?.interactionRouter,
+                causation: requestCausation,
+                permissionStateChanged: context?.permissionStateChanged,
+            };
+            pending.timeout = setTimeout(() => {
+                this.failPendingPermission(sessionId, requestId, 'expired');
+            }, LOCAL_APPROVAL_TTL_MS);
+            pending.timeout.unref?.();
+            this.pending.set(requestId, pending);
+            this.syncManagementRevalidationTimer();
+            if (context?.interactionRouter) {
+                context.interactionRouter.register(requestId, sessionId, (action, _values, operatorId, channelKey) => {
+                    return this.resolvePermission(sessionId, requestId, action, operatorId, channelKey);
+                }, {
+                    initiatorId: route.approverOperatorId || undefined,
+                    initiatorChannelKey: route.approverChannelKey,
+                    onChannelCancel: reason => this.failPendingPermission(sessionId, requestId, reason),
+                    onCancel: reason => context?.adapter?.invalidateInteraction?.(requestId, reason),
+                    fallbackCommand: 'perm',
+                });
+            }
+        });
+        const localPending = this.pending.get(requestId);
+        if (localPending && this.bindAbortSignal(localPending, context?.abortSignal, () => this.failPendingPermission(sessionId, requestId, 'tool_cancelled'))) {
+            return decisionPromise;
+        }
+        // 尝试富交互（走统一 adapter.send 入口）
+        let interactionSent = false;
+        if (context?.flushPending) {
+            try {
+                await context.flushPending();
+            }
+            catch {
+                // flush 失败不应阻断权限请求发送
+            }
+        }
+        if (this.pending.get(requestId) !== localPending) {
+            return decisionPromise;
+        }
+        if (localPending && localPending.requiredApproverRole !== 'requester') {
+            const currentAuthorization = this.authorizePendingResponse(localPending, localPending.approverOperatorId, localPending.approverChannelKey);
+            if (currentAuthorization.status !== 'authorized') {
+                this.failPendingPermission(sessionId, requestId, currentAuthorization.status === 'revoked'
+                    ? currentAuthorization.reason
+                    : 'approver_identity_mismatch');
+                return decisionPromise;
+            }
+        }
+        if (context?.adapter && context.channelId) {
+            try {
+                const envelope = buildEnvelope({
+                    taskId: context.taskId,
+                    channel: context.channel ?? context.adapter.channelName,
+                    channelId: context.channelId,
+                    agentName: context.agentName,
+                    chatmode: context.chatmode,
+                    replyContext: context.replyContext,
+                    causation: requestCausation,
+                });
+                const fallbackText = `🔐 权限请求 - ${toolName}\n${displaySummary}${reasonLine}\n回复 /perm ${requestId} allow 允许本次 / /perm ${requestId} always 同操作授权 30 分钟 / /perm ${requestId} deny 拒绝`;
+                const result = await sendInteractionPayload(context.adapter, envelope, interaction, fallbackText, context.replyContext);
+                interactionSent = !!result;
+            }
+            catch (err) {
+                // sendInteractionPayload 已内部捕获，但保险起见再 try/catch
+            }
+        }
+        // Delivery can yield while the request is cancelled or resolved. Never
+        // emit a stale text fallback after the registered pending slot is gone.
+        if (this.pending.get(requestId) !== localPending) {
+            return decisionPromise;
+        }
+        // fallback 到文本
+        if (!interactionSent) {
+            try {
+                await sendPrompt(renderActionAsText(interaction));
+            }
+            catch (error) {
+                logger.warn(`[PermissionGateway] Approval delivery failed: session=${sessionId} tool=${toolName} error=${error instanceof Error ? error.message : String(error)}`);
+                this.failPendingPermission(sessionId, requestId, 'delivery_failed');
+            }
+        }
+        return decisionPromise;
+    }
+    resolvePermission(sessionId, requestId, decision, operatorId, channelKey) {
+        const pending = this.pending.get(requestId);
+        if (!pending || pending.sessionId !== sessionId)
+            return false;
+        const authorization = this.authorizePendingResponse(pending, operatorId, channelKey);
+        if (authorization.status === 'identity_mismatch')
+            return false;
+        if (authorization.status === 'revoked') {
+            logger.info(`[PermissionGateway] approval_revoked request=${requestId} policy=${pending.approverPolicy} reason=${authorization.reason}`);
+            this.failPendingPermission(sessionId, requestId, authorization.reason);
+            return false;
+        }
+        const normalizedDecision = decision === 'allow' || decision === 'always'
+            ? decision
+            : 'deny';
+        // Legacy "always" now means this exact operation in this session for 30 minutes.
+        // The backend receives a one-shot allow. Future identical operations must
+        // return through this gateway so the exact fingerprint and TTL are checked.
+        this.clearPendingResources(pending);
+        pending.interactionRouter?.cancel(requestId);
+        pending.resolve(normalizedDecision === 'deny' ? 'deny' : 'allow');
+        this.pending.delete(requestId);
+        this.syncManagementRevalidationTimer();
+        const decisionCausation = deriveCausation(pending.causation);
+        if (normalizedDecision === 'always') {
+            this.addTemporaryGrant(pending, decisionCausation);
+        }
+        recordCausationSpan(decisionCausation, 'permission.decision', {
+            status: normalizedDecision === 'deny' ? 'failed' : 'completed',
+            refs: { permissionRequestId: requestId, sessionId },
+            reason: normalizedDecision,
+        });
+        this.eventBus?.publish({ type: 'permission:resolved', sessionId, requestId, approved: normalizedDecision !== 'deny', causation: decisionCausation });
+        return true;
+    }
+    /**
+     * Resolve an explicitly named request from any channel/session. The request
+     * remains bound to its authenticated approver, so knowing a UUID alone is
+     * never sufficient to approve it.
+     */
+    resolvePermissionByRequestId(requestId, decision, operatorId, channelKey) {
+        const local = this.pending.get(requestId);
+        if (local) {
+            return this.resolvePermission(local.sessionId, requestId, decision, operatorId, channelKey);
+        }
+        const crossSession = this.crossSessionPending.get(requestId);
+        if (!crossSession)
+            return false;
+        const action = decision === 'always'
+            ? 'approve_session_30m'
+            : decision === 'allow'
+                ? 'approve_once'
+                : 'deny';
+        return this.resolveCrossSessionPermission(crossSession.sessionId, requestId, action, undefined, operatorId, channelKey);
+    }
+    /**
+     * Proactively cancel management approvals after an identity or Agent config
+     * write. Callers should invoke this for contact/owners/admins changes; the
+     * response path repeats the same check as a fail-closed backstop.
+     */
+    revalidatePendingApprovals(selfAid, source = 'config_write') {
+        let cancelled = 0;
+        for (const [requestId, pending] of [...this.pending.entries()]) {
+            if (pending.requiredApproverRole === 'requester')
+                continue;
+            if (selfAid && pending.selfAid !== selfAid)
+                continue;
+            const authorization = this.authorizePendingResponse(pending, pending.approverOperatorId, pending.approverChannelKey);
+            if (authorization.status !== 'revoked')
+                continue;
+            logger.info(`[PermissionGateway] approval_revoked request=${requestId} policy=${pending.approverPolicy} route=${pending.approvalRouteKind} required_role=${pending.requiredApproverRole} reason=${authorization.reason} source=${source}`);
+            if (this.failPendingPermission(pending.sessionId, requestId, authorization.reason))
+                cancelled++;
+        }
+        for (const [requestId, pending] of [...this.crossSessionPending.entries()]) {
+            if (pending.requiredApproverRole === 'requester')
+                continue;
+            if (selfAid && pending.selfAid !== selfAid)
+                continue;
+            const authorization = this.authorizePendingResponse(pending, pending.approverOperatorId, pending.approverChannelKey);
+            if (authorization.status !== 'revoked')
+                continue;
+            logger.info(`[PermissionGateway] approval_revoked request=${requestId} policy=${pending.approverPolicy} route=${pending.approvalRouteKind} required_role=${pending.requiredApproverRole} reason=${authorization.reason} source=${source}`);
+            if (this.expireCrossSessionPermission(pending.sessionId, requestId, authorization.reason))
+                cancelled++;
+        }
+        return cancelled;
+    }
+    /** 中断时取消指定会话的所有 pending 权限请求 */
+    cancelAll(sessionId, reason = 'cancelled', notifyState = true) {
+        for (const [requestId, pending] of this.pending.entries()) {
+            if (pending.sessionId === sessionId) {
+                this.clearPendingResources(pending);
+                pending.interactionRouter?.cancel(requestId, reason);
+                pending.resolve('deny');
+                this.pending.delete(requestId);
+                const decisionCausation = deriveCausation(pending.causation);
+                recordCausationSpan(decisionCausation, 'permission.decision', {
+                    status: 'failed',
+                    refs: { permissionRequestId: requestId, sessionId },
+                    reason,
+                });
+                this.eventBus?.publish({
+                    type: 'permission:cancelled',
+                    sessionId,
+                    requestId,
+                    toolName: pending.toolName,
+                    reason,
+                    causation: decisionCausation,
+                });
+            }
+        }
+        for (const requestId of [...this.crossSessionPending.keys()]) {
+            this.expireCrossSessionPermission(sessionId, requestId, reason, notifyState, true);
+        }
+        this.syncManagementRevalidationTimer();
+    }
+    async cancelAllPending(reason = 'daemon_restart') {
+        const crossSession = [...this.crossSessionPending.values()];
+        for (const pending of crossSession)
+            void this.notifyPermissionState(pending, {
+                state: 'failed',
+                requestId: pending.requestId,
+                toolName: pending.toolName,
+                reason,
+                message: reason === 'daemon_restart'
+                    ? 'daemon 已重启，审批任务已终止。'
+                    : '审批任务已终止。',
+            });
+        const sessionIds = new Set([
+            ...[...this.pending.values()].map(pending => pending.sessionId),
+            ...crossSession.map(pending => pending.sessionId),
+        ]);
+        for (const sessionId of sessionIds)
+            this.cancelAll(sessionId, reason, false);
+    }
+    /** 获取指定会话的所有 pending requestId */
+    getPendingRequests(sessionId) {
+        const ids = [];
+        for (const [requestId, pending] of this.pending.entries()) {
+            if (pending.sessionId === sessionId) {
+                ids.push(requestId);
+            }
+        }
+        for (const [requestId, pending] of this.crossSessionPending.entries()) {
+            if (pending.sessionId === sessionId) {
+                ids.push(requestId);
+            }
+        }
+        return ids;
+    }
+}
+function permissionFailure(reason) {
+    if (reason === 'expired')
+        return 'owner 审批超时，任务已停止。';
+    if (reason === 'cancelled')
+        return 'owner 审批已取消，任务已停止。';
+    return '向 owner 发送授权申请失败，任务已停止。';
+}