@guilz-dev/belay 0.2.0 → 0.4.0

package/README.md

@@ -34,8 +34,8 @@ policy to maintain.
 | **Claude Code** | Supported | `.claude/settings.json` | `.claude/belay.config.json` |
 | **Codex** | Experimental | `.codex/config.toml` | `.codex/belay.config.json` |
 
-Pick the adapter at install time with `--adapter cursor|claude|codex` (or let
-`init-wizard` prompt). Hosts use different hook event names, but Belay registers
+Pick the adapter at install time with `--adapter cursor|claude|codex` (or use
+`belay config` interactively). Hosts use different hook event names, but Belay registers
 the same runners (`belay-tool-gate`, `belay-before-submit`, `belay-audit`) at
 equivalent lifecycle points:
 
@@ -68,8 +68,8 @@ audit instead of guessing.
 ## Quick start
 
 ```bash
-# Interactive setup (prompts for adapter, scope, skill, mode)
-npx @guilz-dev/belay init-wizard
+# Interactive setup (adapter, scope, skill, judge provider, credentials)
+belay config
 
 # Or non-interactive
 npx @guilz-dev/belay init --adapter claude   # Claude Code
@@ -131,6 +131,9 @@ Belay is a layered hook gate, not a static denylist. Higher layers are opt-in.
 - L3 command lists are **not security boundaries** by themselves — see
   [docs/ops/semver-policy.md](./docs/ops/semver-policy.md) and
   [docs/guarantee-table.md](./docs/guarantee-table.md).
+- At default L3, **local-recoverable mutations outside the repo** pass after Tier1
+  (e.g. IDE plan files). To deny repo-external writes at the OS boundary, enable L1-full
+  (`sandbox.runtime` ≠ `none`). Tier1 requires a working judge (local Ollama by default).
 - Adversarial resistance requires the full L1 stack:
   `belay init --preset l1-full-recommended`, verified with `belay sandbox status`.
 
@@ -236,20 +239,37 @@ Notable settings:
   current OS user. `upgrade` migrates repo-local approvals in; disabling merges
   them back. File-mutation tools and shell redirects cannot write control-plane
   paths while it is enabled.
-- **Cloud judge** — for `judge.provider: "openai-compatible"`, set
-  `judge.endpoint` and provide `BELAY_JUDGE_API_KEY` (or `OPENAI_API_KEY`), or
-  opt in with
-  `belay init --judge-provider openai-compatible --judge-endpoint <url> --accept-cloud-judge`.
-  Fresh installs default to local Ollama (`local-ollama`).
+- **Cloud judge** — configure with `belay config` (interactive) or `belay config set judge.providerId <id>`.
+  Providers: `ollama`, `codex`, `claude`, `cursor`. **Provider** is the vendor/service
+  (`judge.providerId`); **driver** is the API compatibility layer (`judge.provider`:
+  `ollama`, `openai-compatible`, or `anthropic`); **host** is where hooks install
+  (`config.adapter`: `cursor`, `claude`, `codex`). Set `judge.endpoint` when needed;
+  credentials via `belay config credential mode project|apiKey` or env vars. Record egress
+  consent during `belay config` or via `belay judge consent` → `belay approve` →
+  `belay judge use … --cloud-consent-approval-id`. Cloud providers can use native CLI
+  transport without `judge.endpoint` when the host CLI is available (`codex-cli`,
+  `cursor-cli`, `claude-cli`); HTTP transport still requires endpoint and recorded consent.
+  Fresh installs default to the
+  host-matched provider (`cursor` → `cursor`, etc.). `belay judge use` remains available
+  as a secondary path.
+
+  Legacy `judge.model: auto` in config files is normalized to the provider catalog default on load
+  (with a warning); new `auto` values are rejected on CLI, `belay config set`, and `belay judge use`.
+  On an installed repo, interactive `belay config` defaults to judge-only setup without re-running
+  `init`. Model discovery is covered by unit tests with mocks; set `BELAY_LIVE_CLI_DISCOVERY=1` locally
+  for optional live CLI probes. Cloud egress consent is enforced for HTTP transport; native CLI
+  transport uses the host session and does not require `judge.endpoint`. `BELAY_JUDGE_MODEL_RESOLVED`
+  applies only under Vitest (test overrides).
 
 ## Command reference
 
 ```bash
 belay init [--adapter cursor|claude|codex] [--scope project|global]
            [--preset strict|standard|audit-first|l1-full-recommended]
-           [--with-skill] [--dogfood]
-belay init-wizard                # interactive install
-belay upgrade                    # refresh hooks + runtime, migrate config
+           [--migrate-judge-default] [--with-skill] [--dogfood]
+belay config                     # interactive setup (primary)
+belay config list|get|set|unset|judge|credential …
+belay upgrade [--migrate-judge-default]   # refresh hooks + runtime, migrate config
 belay dogfood [--enforce]        # toggle audit / enforce mode
 belay doctor [--fix]             # check (and repair) floor health
 belay status                     # show install scope / skill-only state
@@ -263,6 +283,13 @@ belay egress <start|stop|status|env>
 belay sandbox status
 belay approve <approval-id> [--scope once|domain|path]
 belay revoke <approval-id>
+belay judge status
+belay judge list
+belay judge use <ollama|codex|claude|cursor> [--model <id>] [--endpoint <url>]
+           [--accept-cloud] [--cloud-consent-approval-id <id>]
+           [--credential project|apiKey] [--key-stdin] [--key-env <NAME>]
+belay judge test
+belay judge consent <provider-id> [--endpoint <url>]
 ```
 
 ## Coexisting with existing hooks

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, } 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,11 +429,75 @@ 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);
-    const approved = TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) ||
-        shouldSkipBrokerApprovedOnce(brokerActive, result.reason)
-        ? null
-        : await consumeApprovedApproval(ctx, deps, kind, result.fingerprint);
+    let approved = null;
+    if (!TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) &&
+        !shouldSkipBrokerApprovedOnce(brokerActive, result.reason)) {
+        const approvedState = await deps.loadApprovals(ctx, 'approved-approvals.json');
+        approvedState.state = compactApprovals(approvedState.state);
+        const matchedApproval = approvedState.state.approvals.find((entry) => entry.kind === kind &&
+            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);
+        }
+    }
     if (approved) {
         await deps.appendAudit(ctx, {
             ...gateBase,
@@ -373,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({
@@ -411,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.`,
     });
 }
@@ -420,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>.`;
@@ -440,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',
@@ -461,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) {
@@ -496,6 +760,7 @@ export function gateVerdictToClaudeUserPromptResponse(verdict) {
             hookEventName: 'UserPromptSubmit',
             continue: false,
             user_message: verdict.user_message,
+            ...(verdict.replay ? { replay: verdict.replay } : {}),
         },
     };
 }
@@ -512,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) {