@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/adapters/shared/gate-runtime.js

@@ -2,20 +2,48 @@ import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { recordApproval } from '../../core/approval-service.js';
+import { compactApprovals, createApprovalRecordWithEnvelope } from '../../core/approval.js';
+import { buildReplayHint, buildRetryInstructionForConfig, getExecutionLeaseMs, replayShellCommand, validateReplayEnvelope, } from '../../core/approval-replay.js';
+import { consumeApprovedAfterCliReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
-import { fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from '../../core/capability/index.js';
+import { buildAuditActionSnapshot, buildAuditReplayContext, } from '../../core/audit-replay-context.js';
+import { mutateApprovalStateWithRetry } from '../../core/capability/approval-state-mutation.js';
+import { APPROVAL_STATE_VERSION_V3 } from '../../core/capability/approval-v3.js';
+import { isEgressProxyActive } from '../../core/capability/boundary-egress.js';
+import { resolveBoundaryDriverContext } from '../../core/capability/boundary-session.js';
+import { hashCapabilityRequests } from '../../core/capability/capability-request-hash.js';
+import { recordGateApprovalAsk, scheduleGateShadowAudit, } from '../../core/capability/gate-shadow-audit.js';
+import { consumeGrantLease, findMatchingGrant, grantsFromApprovedState, } from '../../core/capability/grant-lease.js';
+import { loadClassifierAuthorization } from '../../core/capability/grant-loader.js';
+import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, loadTrustedWorkspaceRootsSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from '../../core/capability/index.js';
 import { resolveLayeredConfig, teamConfigPath } from '../../core/config-layers.js';
 import { classifyResultToGateVerdict, unnormalizedGateVerdict, } from '../../core/gate-contract.js';
 import { classifyGatedActionAsync, extractAgentAssessment, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from '../../core/gate-engine.js';
-import { APPROVAL_EXECUTION_LEASE_MS, approvalCommandMatch, approvedApprovalsFile, buildRetryInstruction, canonicalStringify, classifierOptionsFromConfig, compactApprovals, configuredControlPlaneDir, createApprovalRecord, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { approvalCommandMatch, approvedApprovalsFile, belayStateDir, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { extractJudgeFallbackReason, formatJudgeInfrastructureDenyMessage, inferProviderIdFromFallbackReason, isJudgeInfrastructureFailure, } from '../../core/judge-fallback-hints.js';
 import { notifyDeny } from '../../core/notify.js';
+import { canonicalPath } from '../../core/path-utils.js';
+import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
+import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
+import { loadStandingAllow, resolveStandingAllowMatch, standingAllowFile, } from '../../core/standing-allow.js';
 import { isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
+import { egressStatus } from '../../services/egress-service.js';
 import { protectedArtifactRoots } from '../layouts/protected-paths.js';
 const EMPTY_APPROVALS = {
     version: 1,
     approvals: [],
 };
+function adapterIdFromContext(ctx) {
+    if (ctx.config.adapter === 'cursor' ||
+        ctx.config.adapter === 'claude' ||
+        ctx.config.adapter === 'codex') {
+        return ctx.config.adapter;
+    }
+    if (ctx.layout.name === 'cursor' || ctx.layout.name === 'claude' || ctx.layout.name === 'codex') {
+        return ctx.layout.name;
+    }
+    return undefined;
+}
 async function loadJsonFile(filePath, fallback) {
     try {
         const raw = await readFile(filePath, 'utf8');
@@ -49,10 +77,12 @@ export function createDefaultGateRuntimeDeps() {
                 ? pendingApprovalsFile(ctx.config, repoLocalStateDir)
                 : approvedApprovalsFile(ctx.config, repoLocalStateDir);
             const loaded = await loadJsonFile(filePath, EMPTY_APPROVALS);
+            const version = loaded.version === 3 ? 3 : loaded.version === 2 ? 2 : 1;
             return {
                 filePath,
                 state: {
-                    version: loaded.version === 2 ? 2 : 1,
+                    version,
+                    ...(loaded.revision !== undefined ? { revision: loaded.revision } : {}),
                     approvals: Array.isArray(loaded.approvals) ? loaded.approvals : [],
                 },
             };
@@ -90,11 +120,13 @@ export function repoShellClassifierOptions(config, repoRoot, layout, extras = {}
 export function runtimeClassifierOptions(ctx, config) {
     const repoLocalStateDir = ctx.layout.repoLocalStateDir(ctx.repoRoot);
     const brokerFsScope = isCapabilityBrokerDemotionActive(config);
+    const trustedRoots = loadTrustedWorkspaceRootsSync(trustedWorkspaceRootsPath(config, repoLocalStateDir));
     return repoShellClassifierOptions(config, ctx.repoRoot, ctx.layout, {
         brokerFsScope,
         fsScopeAllowlist: brokerFsScope
             ? loadFsScopeAllowlistSync(fsScopeAllowlistPath(config, repoLocalStateDir))
             : undefined,
+        trustedWorkspaceRoots: trustedRoots.roots.map((entry) => entry.path),
     });
 }
 function gateAuditEventName(kind) {
@@ -106,7 +138,7 @@ function gateAuditEventName(kind) {
     }
     return 'subagentGate';
 }
-async function ensurePendingApproval(ctx, deps, kind, result, approvalInput) {
+async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, scopeHint) {
     const pending = await deps.loadApprovals(ctx, 'pending-approvals.json');
     pending.state = compactApprovals(pending.state);
     const existing = pending.state.approvals.find((approval) => approval.kind === kind &&
@@ -114,9 +146,9 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput) {
         approval.repoRoot === ctx.repoRoot);
     if (existing) {
         await deps.writeApprovals(pending.filePath, pending.state);
-        return existing;
+        return { approval: existing, created: false };
     }
-    const approval = createApprovalRecord({
+    const approval = createApprovalRecordWithEnvelope({
         kind,
         fingerprint: result.fingerprint,
         repoRoot: ctx.repoRoot,
@@ -124,35 +156,120 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput) {
         summary: result.normalizedCommand ?? result.summary ?? '',
         approvalTtlMinutes: ctx.config.approvalTtlMinutes,
         approvalId: `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`,
-        input: approvalInput?.input,
-        inputKind: approvalInput?.inputKind,
+        approvalInput,
+        scopeHint,
+        capabilityRequests: result.capabilityRequests,
     });
-    pending.state.version = 2;
+    pending.state.version = APPROVAL_STATE_VERSION_V3;
+    pending.state.revision = (pending.state.revision ?? 0) + 1;
     pending.state.approvals.push(approval);
     await deps.writeApprovals(pending.filePath, pending.state);
-    return approval;
+    return { approval, created: true };
+}
+function extractShellCommandFromPayload(payload) {
+    const toolInput = payload.tool_input;
+    if (!toolInput || typeof toolInput !== 'object') {
+        return '';
+    }
+    const input = toolInput;
+    return typeof input.command === 'string' ? input.command : '';
+}
+function deriveWorkspaceRootScopeHint(params) {
+    if (params.result.reason !== 'outside_repo_mutation' &&
+        params.result.reason !== 'outside_repo_redirect') {
+        return undefined;
+    }
+    const action = params.replayAction;
+    if (!action?.cwd) {
+        return undefined;
+    }
+    const outsidePaths = new Set();
+    if (action.kind === 'shell' && action.command) {
+        for (const resolved of collectOutsideRepoPaths(action.command, action.cwd, action.repoRoot, params.options.trustedWorkspaceRoots)) {
+            outsidePaths.add(resolved);
+        }
+    }
+    else if (action.kind === 'tool') {
+        const toolPayload = params.payloadForScopeHint ?? action.payload ?? {};
+        for (const resolved of collectOutsideRepoPathsFromToolPayload(toolPayload, action.cwd, action.repoRoot, params.options.trustedWorkspaceRoots)) {
+            outsidePaths.add(resolved);
+        }
+        const command = extractShellCommandFromPayload(toolPayload);
+        if (command) {
+            for (const resolved of collectOutsideRepoPaths(command, action.cwd, action.repoRoot, params.options.trustedWorkspaceRoots)) {
+                outsidePaths.add(resolved);
+            }
+        }
+    }
+    if (outsidePaths.size !== 1) {
+        return undefined;
+    }
+    const targetPath = [...outsidePaths][0];
+    if (!targetPath) {
+        return undefined;
+    }
+    const candidateRoot = canonicalPath(path.dirname(targetPath));
+    const validation = validateTrustedWorkspaceRootCandidate({
+        candidatePath: candidateRoot,
+        repoRoot: action.repoRoot,
+        controlPlaneDir: params.options.controlPlaneDir ?? undefined,
+        protectedRoots: params.options.protectedArtifactRoots ?? [],
+        requireExistingDirectory: true,
+        requireNonGit: true,
+    });
+    if (!validation.ok) {
+        return undefined;
+    }
+    return { scope: 'workspace-root', path: validation.normalizedPath };
 }
 async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
-    const approved = await deps.loadApprovals(ctx, 'approved-approvals.json');
-    approved.state = compactApprovals(approved.state);
-    const index = approved.state.approvals.findIndex((approval) => approval.kind === kind &&
+    const loaded = await deps.loadApprovals(ctx, 'approved-approvals.json');
+    loaded.state = compactApprovals(loaded.state);
+    const index = loaded.state.approvals.findIndex((approval) => approval.kind === kind &&
         approval.fingerprint === fingerprint &&
         approval.repoRoot === ctx.repoRoot);
     if (index === -1) {
-        await deps.writeApprovals(approved.filePath, approved.state);
+        await deps.writeApprovals(loaded.filePath, loaded.state);
         return null;
     }
-    const approval = approved.state.approvals[index];
+    const approval = loaded.state.approvals[index];
     if (approval.executionLeaseExpiresAt) {
-        await deps.writeApprovals(approved.filePath, approved.state);
-        return approval;
+        await deps.writeApprovals(loaded.filePath, loaded.state);
+        return { approval, firstExecution: false };
     }
-    approved.state.approvals[index] = {
-        ...approval,
-        executionLeaseExpiresAt: new Date(Date.now() + APPROVAL_EXECUTION_LEASE_MS).toISOString(),
-    };
-    await deps.writeApprovals(approved.filePath, approved.state);
-    return approval;
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const matchIndex = compacted.approvals.findIndex((approval) => approval.kind === kind &&
+                approval.fingerprint === fingerprint &&
+                approval.repoRoot === ctx.repoRoot);
+            if (matchIndex === -1) {
+                return null;
+            }
+            const approval = compacted.approvals[matchIndex];
+            if (approval.grant && approval.grant.usesRemaining <= 0) {
+                compacted.approvals.splice(matchIndex, 1);
+                return { state: compacted, result: null };
+            }
+            compacted.approvals[matchIndex] = {
+                ...approval,
+                executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
+                grant: approval.grant
+                    ? {
+                        ...approval.grant,
+                        usesRemaining: Math.max(0, approval.grant.usesRemaining - 1),
+                    }
+                    : undefined,
+            };
+            return { state: compacted, result: approval };
+        },
+    });
+    if (!consumed) {
+        return null;
+    }
+    return { approval: consumed, firstExecution: true };
 }
 export async function evaluateGatedAction(ctx, deps, params) {
     let action;
@@ -205,15 +322,42 @@ export async function evaluateGatedAction(ctx, deps, params) {
         });
     }
     const classifierOptions = runtimeClassifierOptions(ctx, ctx.config);
-    const predicted = await classifyGatedActionAsync(action, ctx.config, classifierOptions);
+    const approvedForAuth = await deps.loadApprovals(ctx, 'approved-approvals.json');
+    const authorization = await loadClassifierAuthorization({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        approvedState: compactApprovals(approvedForAuth.state),
+    });
+    const egress = await egressStatus({ targetDir: ctx.repoRoot });
+    const egressProxyActive = isEgressProxyActive({
+        config: ctx.config,
+        running: egress.running,
+        foreignProxy: egress.foreignProxy,
+        repoRootMismatch: egress.repoRootMismatch,
+    });
+    const enrichedClassifierOptions = {
+        ...classifierOptions,
+        ...authorization,
+        egressProxyActive,
+    };
+    const predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
     let result = predicted;
     let predictedAssessment;
     let observedAssessment;
     let transactionalLayer;
-    if (isTransactionalEligible(ctx.config, params.kind, predicted) &&
+    const recoveryCandidate = isTransactionalEligible(ctx.config, params.kind, predicted) &&
         params.kind === 'shell' &&
-        params.command) {
+        Boolean(params.command);
+    if (recoveryCandidate && params.command) {
         const transactional = ctx.config.policy.transactional;
+        const boundaryDriverId = ctx.config.capability?.boundaryDriver ??
+            (ctx.config.sandbox.runtime === 'container' ? 'container' : 'host-integration');
+        const boundaryContext = await resolveBoundaryDriverContext({
+            repoRoot: ctx.repoRoot,
+            config: ctx.config,
+            driverId: boundaryDriverId,
+            egressProxyRunning: egressProxyActive,
+        });
         const txResult = await runTransactionalExecution({
             command: params.command,
             cwd: params.cwd,
@@ -224,9 +368,11 @@ export async function evaluateGatedAction(ctx, deps, params) {
             diffContext: {
                 repoRoot: ctx.repoRoot,
                 sensitivePaths: ctx.config.classifier.sensitivePaths,
-                protectedRoots: classifierOptions.protectedArtifactRoots ?? [],
+                protectedRoots: enrichedClassifierOptions.protectedArtifactRoots ?? [],
                 maxDeletionCount: transactional.maxDeletionCount,
             },
+            boundaryContext,
+            dirtyIgnoreRoots: protectedArtifactRoots(ctx.layout, ctx.repoRoot, ctx.config.controlPlane.enabled ? configuredControlPlaneDir(ctx.config) : null),
         });
         if (!txResult.skipped && txResult.observed) {
             result = txResult.result;
@@ -240,13 +386,20 @@ export async function evaluateGatedAction(ctx, deps, params) {
                 transactionalTimedOut: txResult.timedOut === true,
             };
         }
-        else if (txResult.skipReason) {
+        else {
+            const skipReason = txResult.skipReason ?? 'recovery_observation_failed';
+            result = recoveryFailClosedResult(predicted, recoveryFailReasonFromSkip(skipReason), [
+                skipReason,
+            ]);
             transactionalLayer = {
                 transactional: false,
-                transactionalSkipReason: txResult.skipReason,
+                transactionalSkipReason: skipReason,
+                recoveryFailClosed: true,
             };
         }
     }
+    const scrubOpts = scrubOptionsFromConfig(ctx.config);
+    const scrubbedPayload = fingerprintReplayPayload(params.kind, params.payload, scrubOpts);
     return gateDecisionToVerdict(ctx, deps, params.kind, result, {
         predictedAssessment,
         observedAssessment,
@@ -255,24 +408,40 @@ export async function evaluateGatedAction(ctx, deps, params) {
             ? {
                 input: params.command ?? result.normalizedCommand ?? result.summary ?? '',
                 inputKind: 'shell',
+                cwd: params.cwd,
             }
             : {
                 input: params.command ??
                     result.normalizedCommand ??
                     result.summary ??
-                    canonicalStringify(params.payload ?? {}),
+                    canonicalStringify(scrubbedPayload ?? {}),
                 inputKind: params.kind,
+                cwd: params.cwd,
+                toolName: params.toolName,
+                payload: scrubbedPayload,
             },
+        replayAction: {
+            kind: params.kind,
+            cwd: params.cwd,
+            toolName: params.toolName,
+            command: params.command,
+            payload: scrubbedPayload,
+            fingerprint: result.fingerprint,
+            repoRoot: ctx.repoRoot,
+        },
+        classifierOptions: enrichedClassifierOptions,
+        scopeHintPayload: params.payload,
     });
 }
 /** R39: unmapped Codex tools ask via pending approval — not hard deny without approval path. */
 export async function gateUnmappedToolVerdict(ctx, deps, toolName, payload) {
-    const scrubbed = scrubValue(payload, scrubOptionsFromConfig(ctx.config));
+    const scrubOpts = scrubOptionsFromConfig(ctx.config);
+    const replayPayload = fingerprintReplayPayload('tool', payload, scrubOpts) ?? {};
     const result = {
         verdict: 'deny_pending_approval',
         reason: 'unmapped_tool',
         summary: toolName,
-        fingerprint: toolFingerprint(toolName, scrubbed, ctx.repoRoot),
+        fingerprint: toolFingerprint(toolName, replayPayload, ctx.repoRoot),
         assessment: {
             reversibility: 'irreversible',
             external: false,
@@ -285,10 +454,61 @@ export async function gateUnmappedToolVerdict(ctx, deps, toolName, payload) {
         approvalInput: {
             input: toolName,
             inputKind: 'tool',
+            cwd: ctx.repoRoot,
+            toolName,
+            payload: replayPayload,
+        },
+        replayAction: {
+            kind: 'tool',
+            cwd: ctx.repoRoot,
+            toolName,
+            payload: replayPayload,
+            fingerprint: result.fingerprint,
+            repoRoot: ctx.repoRoot,
+        },
+    });
+}
+async function consumeCapabilityGrantIfUsed(ctx, deps, result) {
+    if (result.reason !== 'capability_grant' &&
+        result.authorizationDecision?.matchedRule !== 'grant.exact') {
+        return true;
+    }
+    const request = result.capabilityRequests?.[0];
+    if (!request) {
+        return false;
+    }
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const grant = findMatchingGrant(grantsFromApprovedState(compacted, ctx.repoRoot), request);
+            if (!grant) {
+                return null;
+            }
+            const lease = consumeGrantLease(compacted, grant.grantId);
+            if (!lease.consumed) {
+                return null;
+            }
+            return { state: lease.state, result: true };
         },
     });
+    return consumed === true;
 }
 async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {}) {
+    const replayContext = buildAuditReplayContext(kind, result, auditExtras.replayAction);
+    const actionSnapshot = buildAuditActionSnapshot(kind, result, auditExtras.replayAction);
+    const providerId = String(ctx.config.judge?.providerId ?? 'cursor');
+    const stateDir = belayStateDir(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot));
+    const capabilityAudit = scheduleGateShadowAudit({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        providerId,
+        result,
+        command: auditExtras.replayAction?.command ??
+            (kind === 'shell' ? auditExtras.approvalInput?.input : undefined),
+        stateDir,
+    });
     const gateBase = {
         event: gateAuditEventName(kind),
         kind,
@@ -301,6 +521,9 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         schemaVersion: result.axes ? 2 : 1,
         ...(result.axes ?? {}),
         ...auditExtras.transactionalLayer,
+        ...capabilityAudit,
+        ...(replayContext ? { replayContext } : {}),
+        ...(actionSnapshot ? { actionSnapshot } : {}),
     };
     if (result.reason === TRANSACTIONAL_ALREADY_APPLIED) {
         const userMessage = 'Belay executed this command safely in an isolated git worktree. Observed-safe file changes are already applied; do not retry the same command.';
@@ -321,6 +544,37 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             agent_message: agentMessage,
         });
     }
+    if (result.verdict === 'deny_pending_approval' &&
+        ctx.config.mode === 'enforce' &&
+        !TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason)) {
+        const standingAllowPath = standingAllowFile(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot));
+        const standingState = await loadStandingAllow(standingAllowPath);
+        const standingMatch = resolveStandingAllowMatch({
+            kind,
+            result,
+            repoRoot: ctx.repoRoot,
+            state: standingState,
+        });
+        if (standingMatch) {
+            await deps.appendAudit(ctx, {
+                ...gateBase,
+                verdict: 'allow',
+                reason: 'standing_allow',
+                standingAllowSource: standingMatch.source,
+                ...(standingMatch.catalogCommand
+                    ? { standingAllowCatalogCommand: standingMatch.catalogCommand }
+                    : {}),
+                wouldBlock: false,
+                permission: 'allow',
+            });
+            return classifyResultToGateVerdict({
+                result: { ...result, verdict: 'allow', reason: 'standing_allow' },
+                mode: ctx.config.mode,
+                permission: 'allow',
+                wouldBlock: false,
+            });
+        }
+    }
     const brokerActive = isCapabilityBrokerDemotionActive(ctx.config);
     let approved = null;
     if (!TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) &&
@@ -331,15 +585,69 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             entry.fingerprint === result.fingerprint &&
             entry.repoRoot === ctx.repoRoot);
         if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
+            if (matchedApproval &&
+                matchedApproval.capabilityRequestHash &&
+                result.capabilityRequests?.length &&
+                matchedApproval.capabilityRequestHash !== hashCapabilityRequests(result.capabilityRequests)) {
+                await deps.appendAudit(ctx, {
+                    ...gateBase,
+                    verdict: 'deny_pending_approval',
+                    reason: 'approval_replay_mismatch',
+                    approvalId: matchedApproval.approvalId,
+                    wouldBlock: true,
+                    permission: 'deny',
+                });
+                return classifyResultToGateVerdict({
+                    result: {
+                        ...result,
+                        verdict: 'deny_pending_approval',
+                        reason: 'approval_replay_mismatch',
+                    },
+                    mode: ctx.config.mode,
+                    permission: 'deny',
+                    wouldBlock: true,
+                    approvalId: matchedApproval.approvalId,
+                    user_message: 'Belay denied this action because capability requests changed after approval. Re-approve the exact action or run belay explain.',
+                    agent_message: 'Belay denied this action because capability requests changed after approval.',
+                });
+            }
+            if (matchedApproval &&
+                auditExtras.replayAction &&
+                !validateReplayEnvelope(matchedApproval, auditExtras.replayAction)) {
+                await deps.appendAudit(ctx, {
+                    ...gateBase,
+                    verdict: 'deny_pending_approval',
+                    reason: 'approval_replay_mismatch',
+                    approvalId: matchedApproval.approvalId,
+                    wouldBlock: true,
+                    permission: 'deny',
+                });
+                return classifyResultToGateVerdict({
+                    result: {
+                        ...result,
+                        verdict: 'deny_pending_approval',
+                        reason: 'approval_replay_mismatch',
+                    },
+                    mode: ctx.config.mode,
+                    permission: 'deny',
+                    wouldBlock: true,
+                    approvalId: matchedApproval.approvalId,
+                    user_message: 'Belay denied this action because it does not match the approved replay envelope. Re-approve the exact action or run belay explain.',
+                    agent_message: 'Belay denied this action because cwd, tool, or payload changed after approval.',
+                });
+            }
             approved = await consumeApprovedApproval(ctx, deps, kind, result.fingerprint);
         }
     }
     if (approved) {
+        if (approved.firstExecution) {
+            await recordGateApprovalAsk(stateDir, result.reason, true);
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: 'allow',
             reason: 'approved_once',
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
             wouldBlock: false,
             permission: 'allow',
         });
@@ -348,10 +656,32 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             mode: ctx.config.mode,
             permission: 'allow',
             wouldBlock: false,
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
         });
     }
     if (result.verdict === 'allow' || result.verdict === 'allow_flagged') {
+        const grantConsumed = await consumeCapabilityGrantIfUsed(ctx, deps, result);
+        if (!grantConsumed) {
+            await deps.appendAudit(ctx, {
+                ...gateBase,
+                verdict: 'deny_pending_approval',
+                reason: 'capability_grant_unavailable',
+                wouldBlock: true,
+                permission: 'deny',
+            });
+            return classifyResultToGateVerdict({
+                result: {
+                    ...result,
+                    verdict: 'deny_pending_approval',
+                    reason: 'capability_grant_unavailable',
+                },
+                mode: ctx.config.mode,
+                permission: 'deny',
+                wouldBlock: true,
+                user_message: 'Belay denied this action because the capability grant could not be consumed. Re-approve or run belay explain.',
+                agent_message: 'Belay denied this action because the capability grant was missing, expired, or already used.',
+            });
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: result.verdict,
@@ -381,7 +711,44 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             wouldBlock: true,
         });
     }
-    const approval = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput);
+    if (isJudgeInfrastructureFailure(result)) {
+        const fallbackReason = extractJudgeFallbackReason(result);
+        const providerId = inferProviderIdFromFallbackReason(fallbackReason, String(ctx.config.judge.providerId ?? 'cursor'));
+        const denyMessages = formatJudgeInfrastructureDenyMessage({
+            providerId,
+            fallbackReason,
+            command: result.normalizedCommand ?? result.summary,
+        });
+        await deps.appendAudit(ctx, {
+            ...gateBase,
+            verdict: result.verdict,
+            reason: 'judge_transport_unavailable',
+            judgeFallbackReason: fallbackReason,
+            wouldBlock: true,
+            permission: 'deny',
+        });
+        return classifyResultToGateVerdict({
+            result: {
+                ...result,
+                verdict: 'deny_pending_approval',
+                reason: 'judge_transport_unavailable',
+            },
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            user_message: denyMessages.user_message,
+            agent_message: denyMessages.agent_message,
+        });
+    }
+    const { approval, created } = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
+        result,
+        replayAction: auditExtras.replayAction,
+        payloadForScopeHint: auditExtras.scopeHintPayload,
+        options: auditExtras.classifierOptions ?? {},
+    }));
+    if (created) {
+        await recordGateApprovalAsk(stateDir, result.reason, false);
+    }
     let approvalToken;
     try {
         approvalToken = await issueApprovalToken({
@@ -419,7 +786,7 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         permission: 'deny',
         wouldBlock: true,
         approvalId: approval.approvalId,
-        user_message: `Belay blocked this high-risk action. Approval ID: ${approval.approvalId}. ${buildRetryInstruction(ctx.config.tokenPrefix, approval.approvalId)} For details, run belay explain or /belay why.`,
+        user_message: `Belay blocked this high-risk action. Approval ID: ${approval.approvalId}. ${buildRetryInstructionForConfig(ctx.config, ctx.config.tokenPrefix, approval.approvalId)} For details, run belay explain or /belay why.`,
         agent_message: `Belay denied this action as ${result.reason}. Wait for approval, then retry the exact same action once.`,
     });
 }
@@ -428,6 +795,7 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
     if (!approvalId) {
         return { continue: true };
     }
+    const adapter = adapterIdFromContext(ctx);
     if (ctx.config.approvalSigning.required) {
         const message = `Signed approval token required for ${approvalId}. Editor prompt approval is disabled in this configuration. ` +
             `Use belay approve --approval-id ${approvalId} --token <signed-token>.`;
@@ -448,12 +816,11 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
         approvalId,
         config: ctx.config,
         requireSignedToken: ctx.config.approvalSigning.required,
-        store: {
-            loadPending: () => deps.loadApprovals(ctx, 'pending-approvals.json'),
-            loadApproved: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
-            writePending: (filePath, state) => deps.writeApprovals(filePath, state),
-            writeApproved: (filePath, state) => deps.writeApprovals(filePath, state),
-        },
+        adapter,
+        store: gateApprovalStoreFromDeps({
+            loadApprovals: (fileName) => deps.loadApprovals(ctx, fileName),
+            writeApprovals: (filePath, state) => deps.writeApprovals(filePath, state),
+        }),
     });
     await deps.appendAudit(ctx, {
         event: 'approval',
@@ -469,9 +836,96 @@ export async function processApprovalPrompt(ctx, deps, prompt) {
             user_message: recorded.message,
         };
     }
+    const replay = recorded.approval ? buildReplayHint(ctx.config, recorded.approval, adapter) : null;
+    const shouldFallbackReplay = adapter === 'cursor' &&
+        replay?.kind === 'shell' &&
+        replay.autoReplay === true &&
+        Boolean(recorded.approval?.input) &&
+        (!process.env.VITEST || process.env.BELAY_TEST_APPROVAL_REPLAY === '1');
+    if (shouldFallbackReplay && recorded.approval) {
+        const approvalStore = gateApprovalStoreFromDeps({
+            loadApprovals: (fileName) => deps.loadApprovals(ctx, fileName),
+            writeApprovals: (filePath, state) => deps.writeApprovals(filePath, state),
+        });
+        let replayResult;
+        try {
+            replayResult = await replayShellCommand(recorded.approval.input ?? '', recorded.approval.cwd ?? ctx.repoRoot, getExecutionLeaseMs(ctx.config));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            await deps.appendAudit(ctx, {
+                event: 'approval',
+                kind: 'approval',
+                verdict: 'allow',
+                approvalId,
+                reason: 'approval_replay_error',
+                summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
+            });
+            return {
+                continue: false,
+                user_message: `Belay approval recorded for ${approvalId}, but one-step shell replay could not start (${detail}). ` +
+                    'Approval remains active for one hook retry.',
+            };
+        }
+        const output = [replayResult.stdout, replayResult.stderr].filter(Boolean).join('\n').trim();
+        if (replayResult.exitCode === 0) {
+            try {
+                await consumeApprovedAfterCliReplay({
+                    approvalId: approvalId,
+                    store: approvalStore,
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                await deps.appendAudit(ctx, {
+                    event: 'approval',
+                    kind: 'approval',
+                    verdict: 'allow',
+                    approvalId,
+                    reason: 'approval_replay_consume_error',
+                    summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
+                });
+                return {
+                    continue: false,
+                    user_message: `Belay approval recorded for ${approvalId}, and one-step shell replay succeeded, but approval finalization failed (${detail}). ` +
+                        'Approval remains active for one hook retry.' +
+                        (output ? `\n${output}` : ''),
+                };
+            }
+            await deps.appendAudit(ctx, {
+                event: 'approval',
+                kind: 'approval',
+                verdict: 'allow',
+                approvalId,
+                reason: 'approval_replay_succeeded',
+                summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
+            });
+            return {
+                continue: false,
+                user_message: `Belay approval recorded for ${approvalId}. One-step shell replay succeeded; no manual retry required.` +
+                    (output ? `\n${output}` : ''),
+            };
+        }
+        await deps.appendAudit(ctx, {
+            event: 'approval',
+            kind: 'approval',
+            verdict: 'allow',
+            approvalId,
+            reason: 'approval_replay_failed',
+            summary: recorded.approval.input ?? recorded.approval.summary ?? prompt,
+        });
+        const timeoutNote = replayResult.timedOut ? ' Replay timed out.' : '';
+        return {
+            continue: false,
+            user_message: `Belay approval recorded for ${approvalId}, but one-step shell replay failed (exit ${replayResult.exitCode}).${timeoutNote} ` +
+                `Approval remains active for one hook retry.` +
+                (output ? `\n${output}` : ''),
+        };
+    }
     return {
         continue: false,
         user_message: recorded.message,
+        ...(replay ? { replay } : {}),
     };
 }
 export function gateVerdictToCursorResponse(verdict) {
@@ -504,6 +958,7 @@ export function gateVerdictToClaudeUserPromptResponse(verdict) {
             hookEventName: 'UserPromptSubmit',
             continue: false,
             user_message: verdict.user_message,
+            ...(verdict.replay ? { replay: verdict.replay } : {}),
         },
     };
 }
@@ -520,6 +975,7 @@ export function gateVerdictToCodexUserPromptResponse(verdict) {
     return {
         decision: 'block',
         reason: verdict.user_message,
+        ...(verdict.replay ? { replay: verdict.replay } : {}),
     };
 }
 export async function appendObservedAudit(ctx, deps, eventName, payload) {