@guilz-dev/belay 0.3.0 → 0.4.0

package/dist/adapters/cursor/runtime-entry.js

@@ -44,6 +44,7 @@ export async function runBeforeSubmitPromptHook() {
         jsonResponse({
             continue: result.continue,
             ...(result.user_message ? { user_message: result.user_message } : {}),
+            ...(result.replay ? { replay: result.replay } : {}),
         });
     }
     catch {

package/dist/adapters/shared/gate-runtime.d.ts

@@ -1,9 +1,15 @@
+import { type ApprovalReplayHint } from '../../core/approval-replay.js';
 import type { GatedActionKind } from '../../core/gate-contract.js';
 import { type GatePermissionResponse, type GateVerdict } from '../../core/gate-contract.js';
 import { GateNormalizationError } from '../../core/gate-engine.js';
-import { type ApprovalStateFile, type BelayConfigV3 } from '../../core/index.js';
-import type { ClassifierOptions } from '../../core/types.js';
+import { type BelayConfigV3 } from '../../core/index.js';
+import type { ApprovalStateFile, ClassifierOptions } from '../../core/types.js';
 import type { AdapterLayout } from '../layouts/types.js';
+export interface ApprovalPromptResult {
+    continue: boolean;
+    user_message?: string;
+    replay?: ApprovalReplayHint;
+}
 export interface GateRuntimeContext {
     layout: AdapterLayout;
     repoRoot: string;
@@ -32,20 +38,11 @@ export declare function evaluateGatedAction(ctx: GateRuntimeContext, deps: GateR
 }): Promise<GateVerdict>;
 /** R39: unmapped Codex tools ask via pending approval — not hard deny without approval path. */
 export declare function gateUnmappedToolVerdict(ctx: GateRuntimeContext, deps: GateRuntimeDeps, toolName: string, payload: Record<string, unknown>): Promise<GateVerdict>;
-export declare function processApprovalPrompt(ctx: GateRuntimeContext, deps: GateRuntimeDeps, prompt: string): Promise<{
-    continue: boolean;
-    user_message?: string;
-}>;
+export declare function processApprovalPrompt(ctx: GateRuntimeContext, deps: GateRuntimeDeps, prompt: string): Promise<ApprovalPromptResult>;
 export declare function gateVerdictToCursorResponse(verdict: GateVerdict): GatePermissionResponse;
 export declare function gateVerdictToClaudePreToolUseResponse(verdict: GateVerdict): Record<string, unknown>;
-export declare function gateVerdictToClaudeUserPromptResponse(verdict: {
-    continue: boolean;
-    user_message?: string;
-}): Record<string, unknown>;
+export declare function gateVerdictToClaudeUserPromptResponse(verdict: ApprovalPromptResult): Record<string, unknown>;
 export declare function gateVerdictToCodexPreToolUseResponse(verdict: GateVerdict): Record<string, unknown>;
-export declare function gateVerdictToCodexUserPromptResponse(verdict: {
-    continue: boolean;
-    user_message?: string;
-}): Record<string, unknown>;
+export declare function gateVerdictToCodexUserPromptResponse(verdict: ApprovalPromptResult): Record<string, unknown>;
 export declare function appendObservedAudit(ctx: GateRuntimeContext, deps: GateRuntimeDeps, eventName: string, payload: Record<string, unknown>): Promise<void>;
 export { GateNormalizationError };

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

@@ -2,20 +2,37 @@ 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 { 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, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
 import { notifyDeny } from '../../core/notify.js';
+import { canonicalPath } from '../../core/path-utils.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 { 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');
@@ -90,11 +107,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 +125,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 &&
@@ -116,7 +135,7 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput) {
         await deps.writeApprovals(pending.filePath, pending.state);
         return existing;
     }
-    const approval = createApprovalRecord({
+    const approval = createApprovalRecordWithEnvelope({
         kind,
         fingerprint: result.fingerprint,
         repoRoot: ctx.repoRoot,
@@ -124,14 +143,70 @@ 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,
     });
     pending.state.version = 2;
     pending.state.approvals.push(approval);
     await deps.writeApprovals(pending.filePath, pending.state);
     return approval;
 }
+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);
@@ -149,7 +224,7 @@ async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
     }
     approved.state.approvals[index] = {
         ...approval,
-        executionLeaseExpiresAt: new Date(Date.now() + APPROVAL_EXECUTION_LEASE_MS).toISOString(),
+        executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
     };
     await deps.writeApprovals(approved.filePath, approved.state);
     return approval;
@@ -247,6 +322,8 @@ export async function evaluateGatedAction(ctx, deps, params) {
             };
         }
     }
+    const scrubOpts = scrubOptionsFromConfig(ctx.config);
+    const scrubbedPayload = fingerprintReplayPayload(params.kind, params.payload, scrubOpts);
     return gateDecisionToVerdict(ctx, deps, params.kind, result, {
         predictedAssessment,
         observedAssessment,
@@ -255,24 +332,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,
+        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 +378,23 @@ 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 gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {}) {
+    const replayContext = buildAuditReplayContext(kind, result, auditExtras.replayAction);
+    const actionSnapshot = buildAuditActionSnapshot(kind, result, auditExtras.replayAction);
     const gateBase = {
         event: gateAuditEventName(kind),
         kind,
@@ -301,6 +407,8 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         schemaVersion: result.axes ? 2 : 1,
         ...(result.axes ?? {}),
         ...auditExtras.transactionalLayer,
+        ...(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 +429,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,6 +470,31 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             entry.fingerprint === result.fingerprint &&
             entry.repoRoot === ctx.repoRoot);
         if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
+            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);
         }
     }
@@ -381,7 +545,12 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             wouldBlock: true,
         });
     }
-    const approval = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput);
+    const approval = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
+        result,
+        replayAction: auditExtras.replayAction,
+        payloadForScopeHint: auditExtras.scopeHintPayload,
+        options: auditExtras.classifierOptions ?? {},
+    }));
     let approvalToken;
     try {
         approvalToken = await issueApprovalToken({
@@ -419,7 +588,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 +597,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 +618,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 +638,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 +760,7 @@ export function gateVerdictToClaudeUserPromptResponse(verdict) {
             hookEventName: 'UserPromptSubmit',
             continue: false,
             user_message: verdict.user_message,
+            ...(verdict.replay ? { replay: verdict.replay } : {}),
         },
     };
 }
@@ -520,6 +777,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) {