@guilz-dev/belay 0.7.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
 
@@ -138,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`.
 
@@ -188,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,
@@ -214,10 +215,6 @@ load.
   "policy": {
     "unknownLocalEffect": "allow_flagged"
   },
-  "overrides": {
-    "allow": ["pnpm release:staging"],
-    "external": ["./scripts/release.sh"]
-  },
   "redaction": {
     "maskApprovalIds": true,
     "maskBearerTokens": true,
@@ -238,12 +235,15 @@ 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

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

@@ -32,11 +32,25 @@ import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
 import { loadStandingAllow, resolveStandingAllowMatch, standingAllowFile, } from '../../core/standing-allow.js';
 import { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
 import { egressStatus } from '../../services/egress-service.js';
+import { PACKAGE_VERSION } from '../../version.js';
 import { protectedArtifactRoots } from '../layouts/protected-paths.js';
 const EMPTY_APPROVALS = {
     version: 1,
     approvals: [],
 };
+const RUNTIME_PROVENANCE_KEY = Symbol.for('agent-belay.runtime-provenance');
+function auditProvenance(config) {
+    const runtime = globalThis[RUNTIME_PROVENANCE_KEY];
+    const runtimeVersion = typeof runtime?.runtimeVersion === 'string' ? runtime.runtimeVersion : PACKAGE_VERSION;
+    const runtimeBuildStamp = typeof runtime?.runtimeBuildStamp === 'string'
+        ? runtime.runtimeBuildStamp
+        : `${PACKAGE_VERSION}@source`;
+    return {
+        runtimeVersion,
+        runtimeBuildStamp,
+        configFingerprint: hashValue(canonicalStringify(config)),
+    };
+}
 function adapterIdFromContext(ctx) {
     if (ctx.config.adapter === 'cursor' ||
         ctx.config.adapter === 'claude' ||
@@ -75,11 +89,17 @@ export function createDefaultGateRuntimeDeps() {
         async appendAudit(ctx, event) {
             const auditPath = path.join(ctx.repoRoot, ctx.config.audit.logPath);
             await mkdir(path.dirname(auditPath), { recursive: true });
-            const record = { timestamp: new Date().toISOString(), ...event };
+            const provenance = auditProvenance(ctx.config);
+            const record = {
+                timestamp: new Date().toISOString(),
+                ...event,
+                ...provenance,
+            };
             if (!ctx.config.audit.includeAssessment) {
                 delete record.assessment;
             }
             const scrubbed = scrubValue(record, scrubOptionsFromConfig(ctx.config));
+            Object.assign(scrubbed, provenance);
             await writeFile(auditPath, `${JSON.stringify(scrubbed)}\n`, {
                 encoding: 'utf8',
                 flag: 'a',
@@ -767,7 +787,8 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             agent_message: agentMessage,
         });
     }
-    if (result.verdict === 'deny_pending_approval' &&
+    if (kind !== 'shell' &&
+        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));
@@ -784,9 +805,6 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
                 verdict: 'allow',
                 reason: 'standing_allow',
                 standingAllowSource: standingMatch.source,
-                ...(standingMatch.catalogCommand
-                    ? { standingAllowCatalogCommand: standingMatch.catalogCommand }
-                    : {}),
                 wouldBlock: false,
                 permission: 'allow',
             });