@guilz-dev/belay 0.6.0 → 0.8.0

package/README.md

@@ -86,7 +86,8 @@ npx @guilz-dev/belay status
 
 Fresh installs default to **fail-closed** shell policy: unknown or unparseable
 shell commands are denied until approved. Use `belay explain` to inspect a
-verdict and `overrides.allow` to whitelist commands you trust.
+verdict. Correct inaccurate EffectPlan semantics or resource scope; otherwise
+approve the exact request for one-shot, resource-scoped authorization.
 
 ## How it works
 
@@ -109,6 +110,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).
@@ -128,12 +139,12 @@ Belay is a layered hook gate, not a static denylist. Higher layers are opt-in.
 | **L3** Prediction | Policy rules + command heuristics | default |
 | **L4** Approval | Human one-shot / scoped approvals | default |
 
-- 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).
+- Normalized shell authorization uses only canonical `EffectPlan` requirements.
+  Command lists, legacy overrides, corpus labels, and shell standing allows are inert.
+- Payload-free reads are `allow`; reversible repository-local writes (including implicit
+  download output) are `allow_flagged`. Outside-repository writes, external mutation,
+  explicit payload/file/secret sends, high-stakes effects, and partial/indeterminate plans
+  require approval. See [ADR-004](./docs/adr/ADR-004-effectplan-shell-authority.md).
 - Adversarial resistance requires the full L1 stack:
   `belay init --preset l1-full-recommended`, verified with `belay sandbox status`.
 
@@ -178,18 +189,18 @@ npx @guilz-dev/belay dogfood            # mode: audit, unknownLocalEffect: deny
 # ...run normal agent work...
 npx @guilz-dev/belay metrics           # review what would have been blocked
 npx @guilz-dev/belay status            # check readiness
-# tune overrides.allow with `belay explain`, then:
+# inspect EffectPlan semantics and resource scope with `belay explain`, then:
 npx @guilz-dev/belay dogfood --enforce
 ```
 
 ## Configuration
 
-`belay.config.json` uses `version: 3`. v1/v2 configs migrate automatically on
+`belay.config.json` uses `version: 4`. v1/v2/v3 configs migrate automatically on
 load.
 
 ```json
 {
-  "version": 3,
+  "version": 4,
   "mode": "enforce",
   "gates": {
     "shell": true,
@@ -204,10 +215,6 @@ load.
   "policy": {
     "unknownLocalEffect": "allow_flagged"
   },
-  "overrides": {
-    "allow": ["pnpm release:staging"],
-    "external": ["./scripts/release.sh"]
-  },
   "redaction": {
     "maskApprovalIds": true,
     "maskBearerTokens": true,
@@ -228,17 +235,25 @@ load.
 
 Notable settings:
 
-- **`policy.unknownLocalEffect: "allow_flagged"`** (fresh default) — after Tier1
-  says recoverable, structurally unknown local commands run with an audit flag. Use
-  `"deny"` (via `belay dogfood`) to ask on those commands instead.
+- **`policy.unknownLocalEffect: "allow_flagged"`** (fresh default) — compatibility fallback
+  for legacy, non-EffectPlan classification paths. It cannot loosen a normalized shell
+  EffectPlan: partial/indeterminate plans and outside-repository writes still ask. Use
+  `"deny"` (via `belay dogfood`) for a stricter fallback.
 - **`classifier.strictChains: true`** (default) — scans every `&&`, `|`, and `;`
-  segment and keeps the strictest verdict. Override lists match exact command or
-  segment keys only.
+  segment into the EffectPlan and keeps the strictest policy projection. Legacy
+  `overrides.allow` / `overrides.external` lists are accepted only for config
+  compatibility; shell authorization ignores them and `belay doctor` warns when
+  either list is non-empty.
 - **`controlPlane.enabled: true`** — stores approval state under
   `~/.config/belay/` (or `XDG_CONFIG_HOME/belay`), shared across repos for the
   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`:
@@ -281,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/shared/gate-runtime.d.ts

@@ -23,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>;