@guilz-dev/belay 0.4.0 → 0.7.0

package/README.md

@@ -109,6 +109,16 @@ When an action is denied, approve the **next matching action once** by sending:
 /belay-approve <approval-id>
 ```
 
+With the default `approval.flow: one_step`, an editor approval immediately replays the exact denied
+shell action; no follow-up prompt is required. Tool and subagent approvals still require retrying
+the original action unchanged. The one-shot grant is claimed before shell replay, so a failed or
+timed-out replay requires a fresh approval. Replay runs through the configured `BoundaryDriver`.
+After replay succeeds, the approval prompt continues the current host turn so the agent can report
+the result and resume its workflow without another user message.
+You may put a follow-up instruction on the lines after `/belay-approve <id>`; Belay replays the
+approved shell action first, then lets the remaining prompt continue. CLI replay remains explicit:
+`belay approve <approval-id> --replay`.
+
 Approvals are one-shot and expire after 15 minutes by default. Every decision is
 written to `.cursor/belay/audit.ndjson`, `.claude/belay/audit.ndjson`, or
 `.codex/belay/audit.ndjson` (depending on the adapter).
@@ -239,12 +249,23 @@ 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.
+- **`policy.transactional.checkpoint.enabled: true`** — after enabling the
+  transactional git-worktree runner, persist repo-local pre-images and expose them through
+  `belay recover list`. Restore is conflict-checked and always requires a signed
+  out-of-band, exact one-shot approval. Network, remote Git, databases, processes, and
+  repo-external effects are outside this guarantee.
 - **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
+  credentials via `belay config credential mode project|apiKey` or env vars. **`project`**
+  reads API keys from the shell environment at runtime (`BELAY_JUDGE_API_KEY`, then provider
+  vars such as `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `CURSOR_API_KEY`); Belay does **not**
+  load `.env` files for Judge. When the native CLI is available, `project` can also use the
+  host login session without a stored key. **`apiKey`** stores a key in Belay's credential store
+  (`credentials.json`, mode `0600`; under `~/.config/belay/` when control plane is enabled).
+  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`,
@@ -275,7 +296,11 @@ belay doctor [--fix]             # check (and repair) floor health
 belay status                     # show install scope / skill-only state
 belay metrics                    # would-block / verdict summary
 belay report                     # audit log report
-belay recover [--command "rm important.ts"]   # find recovery candidates
+belay recover [advice] [--command "rm important.ts"] # advisory candidates only
+belay recover status                          # checkpoint backend and state counts
+belay recover list                            # proven repo-local recovery points
+belay recover show <checkpoint-id>
+belay recover apply <checkpoint-id>           # signed OOB exact one-shot approval required
 belay explain -- <shell-command>              # inspect a verdict
 belay explain --kind subagent -- "deploy to production"
 belay explain --kind tool --tool Write -- .env

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

@@ -1,4 +1,7 @@
 import process from 'node:process';
+import { effectPlanAuditFields } from '../../core/effect-ir/audit.js';
+import { buildCapabilityEffectPlan } from '../../core/effect-ir/build.js';
+import { hashValue, toolFingerprint } from '../../core/fingerprint.js';
 import { unnormalizedGateVerdict } from '../../core/gate-contract.js';
 import { claudeLayout } from '../layouts/claude.js';
 import { appendObservedAudit, createDefaultGateRuntimeDeps, evaluateGatedAction, gateVerdictToClaudePreToolUseResponse, gateVerdictToClaudeUserPromptResponse, processApprovalPrompt, resolveGateConfig, } from '../shared/gate-runtime.js';
@@ -22,6 +25,23 @@ async function readStdinJson() {
 function jsonResponse(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
 }
+function claudeFallbackToolVerdict(params) {
+    return {
+        ...unnormalizedGateVerdict({
+            reason: params.reason,
+            mode: params.mode,
+            user_message: params.userMessage,
+            agent_message: params.agentMessage,
+        }),
+        effectPlan: buildCapabilityEffectPlan({
+            actionKind: 'tool',
+            summary: params.toolName,
+            inputFingerprint: hashValue(`claude-fallback:${params.reason}:${toolFingerprint(params.toolName, params.payload, params.repoRoot)}`),
+            requests: [],
+            effectFree: false,
+        }),
+    };
+}
 async function loadRuntimeContext(cwd) {
     const repoRoot = findRepoRoot(cwd, claudeLayout);
     const configPath = claudeLayout.configPath(repoRoot);
@@ -120,13 +140,10 @@ export async function runBeforeSubmitPromptHook() {
         jsonResponse(gateVerdictToClaudeUserPromptResponse(result));
     }
     catch {
-        jsonResponse({
-            hookSpecificOutput: {
-                hookEventName: 'UserPromptSubmit',
-                continue: false,
-                user_message: 'belay failed while processing approval state. Run belay doctor, then retry.',
-            },
-        });
+        jsonResponse(gateVerdictToClaudeUserPromptResponse({
+            continue: false,
+            user_message: 'belay failed while processing approval state. Run belay doctor, then retry.',
+        }));
     }
 }
 export async function runShellGateHook() {
@@ -167,6 +184,15 @@ export async function runToolGateHook(_eventName) {
         const toolName = String(payload.tool_name ?? '');
         const mappedKind = mapClaudeToolName(toolName);
         if (mappedKind === 'mcp') {
+            const verdict = claudeFallbackToolVerdict({
+                toolName,
+                payload,
+                repoRoot: ctx.repoRoot,
+                reason: 'unsupported_mcp_tool',
+                mode: ctx.config.mode,
+                userMessage: 'belay blocked this MCP tool because Claude MCP payloads are not normalized safely yet.',
+                agentMessage: 'Belay denied this MCP tool because its payload shape is unsupported.',
+            });
             await deps.appendAudit(ctx, {
                 event: 'preToolUse',
                 kind: 'tool',
@@ -176,17 +202,21 @@ export async function runToolGateHook(_eventName) {
                 wouldBlock: true,
                 permission: 'deny',
                 summary: toolName,
-            });
-            const verdict = unnormalizedGateVerdict({
-                reason: 'unsupported_mcp_tool',
-                mode: ctx.config.mode,
-                user_message: 'belay blocked this MCP tool because Claude MCP payloads are not normalized safely yet.',
-                agent_message: 'Belay denied this MCP tool because its payload shape is unsupported.',
+                ...effectPlanAuditFields(verdict.effectPlan),
             });
             jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
             return;
         }
         if (!mappedKind) {
+            const verdict = claudeFallbackToolVerdict({
+                toolName,
+                payload,
+                repoRoot: ctx.repoRoot,
+                reason: 'unmapped_tool',
+                mode: ctx.config.mode,
+                userMessage: 'belay does not recognize this tool action. Run belay doctor, then retry.',
+                agentMessage: 'Belay denied this action because the tool could not be normalized.',
+            });
             await deps.appendAudit(ctx, {
                 event: 'preToolUse',
                 kind: 'tool',
@@ -196,18 +226,22 @@ export async function runToolGateHook(_eventName) {
                 wouldBlock: true,
                 permission: 'deny',
                 summary: toolName,
-            });
-            const verdict = unnormalizedGateVerdict({
-                reason: 'unmapped_tool',
-                mode: ctx.config.mode,
-                user_message: 'belay does not recognize this tool action. Run belay doctor, then retry.',
-                agent_message: 'Belay denied this action because the tool could not be normalized.',
+                ...effectPlanAuditFields(verdict.effectPlan),
             });
             jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
             return;
         }
         const normalizedPayload = normalizeClaudeToolPayload(toolName, payload);
         if (!normalizedPayload) {
+            const verdict = claudeFallbackToolVerdict({
+                toolName,
+                payload,
+                repoRoot: ctx.repoRoot,
+                reason: 'normalization_failed',
+                mode: ctx.config.mode,
+                userMessage: 'belay could not normalize this Claude tool payload. Run belay doctor, then retry.',
+                agentMessage: 'Belay denied this action because the Claude tool payload could not be normalized.',
+            });
             await deps.appendAudit(ctx, {
                 event: 'preToolUse',
                 kind: 'tool',
@@ -217,12 +251,7 @@ export async function runToolGateHook(_eventName) {
                 wouldBlock: true,
                 permission: 'deny',
                 summary: toolName,
-            });
-            const verdict = unnormalizedGateVerdict({
-                reason: 'normalization_failed',
-                mode: ctx.config.mode,
-                user_message: 'belay could not normalize this Claude tool payload. Run belay doctor, then retry.',
-                agent_message: 'Belay denied this action because the Claude tool payload could not be normalized.',
+                ...effectPlanAuditFields(verdict.effectPlan),
             });
             jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
             return;

package/dist/adapters/layouts/scope.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import { isPathOutsideRoot } from '../../core/path-utils.js';
 function agentHomeDir(adapter) {
     const home = os.homedir();
     if (adapter === 'cursor') {
@@ -23,13 +24,13 @@ export function isPathInside(child, parent) {
     const resolvedChild = path.resolve(child);
     const resolvedParent = path.resolve(parent);
     const relative = path.relative(resolvedParent, resolvedChild);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    return relative === '' || (!isPathOutsideRoot(relative) && !path.isAbsolute(relative));
 }
 export function buildRunnerInvocation(platform, hooksDir, repoRoot, hookScript, ...args) {
     const runnerFile = platform === 'win32' ? 'belay-runner.cmd' : 'belay-runner';
     const runnerAbs = path.resolve(hooksDir, runnerFile);
     const relative = path.relative(path.resolve(repoRoot), runnerAbs);
-    const useRelative = relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative);
+    const useRelative = relative.length > 0 && !isPathOutsideRoot(relative) && !path.isAbsolute(relative);
     const runnerRef = useRelative
         ? platform === 'win32'
             ? `.\\${relative.split(path.sep).join('\\')}`

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

@@ -1,6 +1,5 @@
 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 { type GatedActionKind, type GatePermissionResponse, type GateVerdict } from '../../core/gate-contract.js';
 import { GateNormalizationError } from '../../core/gate-engine.js';
 import { type BelayConfigV3 } from '../../core/index.js';
 import type { ApprovalStateFile, ClassifierOptions } from '../../core/types.js';
@@ -24,6 +23,13 @@ export interface GateRuntimeDeps {
         state: ApprovalStateFile;
     }>;
     writeApprovals: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    replayApprovedShell: (ctx: GateRuntimeContext, command: string, cwd: string, timeoutMs: number) => Promise<{
+        exitCode: number | null;
+        timedOut: boolean;
+        signal: string | null;
+        stdout?: string;
+        stderr?: string;
+    }>;
 }
 export declare function createDefaultGateRuntimeDeps(): GateRuntimeDeps;
 export declare function resolveGateConfig(ctx: Pick<GateRuntimeContext, 'layout' | 'repoRoot' | 'configPath'>, deps: GateRuntimeDeps): Promise<BelayConfigV3>;