@guilz-dev/belay 0.9.0 → 0.9.1

package/README.md

@@ -122,7 +122,13 @@ approved shell action first, then lets the remaining prompt continue. CLI 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).
+`.codex/belay/audit.ndjson` (depending on the adapter). Schema v3 preserves ISO
+timestamps, fingerprints, and `approvalCorrelationId` for metrics joins. Dogfood
+readiness counts only the active cohort (runtime bundle + authorization-relevant
+config + boundary profile); legacy placeholder logs should be archived via
+`belay upgrade` before trusting readiness. See
+[config schema — audit log](./docs/config-schema.md#audit-log-ndjson-schema-v3) and
+[dogfood audit remediation](./docs/dogfood-audit-remediation-2026-08-22.ja.md).
 
 In **audit mode** (`mode: "audit"`), would-be denials are recorded
 (`wouldBlock: true`) but execution still continues, and no approval IDs are

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

@@ -162,6 +162,7 @@ export async function runShellGateHook() {
             command,
             payload,
             toolName: 'Bash',
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
     }
@@ -261,6 +262,7 @@ export async function runToolGateHook(_eventName) {
             cwd,
             payload: normalizedPayload,
             toolName,
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
     }

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

@@ -180,6 +180,7 @@ export async function runToolGateHook(eventName) {
             command: kind === 'shell' ? extractString(normalizedPayload.tool_input, 'command') : undefined,
             payload: normalizedPayload,
             toolName,
+            sourceEvent: eventName,
         });
         jsonResponse(gateVerdictToCodexPreToolUseResponse(verdict));
     }
@@ -209,6 +210,7 @@ export async function runShellGateHook() {
             command,
             payload,
             toolName: 'Shell',
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToCodexPreToolUseResponse(verdict));
     }

package/dist/adapters/cursor/hooks.d.ts

@@ -1,2 +1,6 @@
-import type { HooksFile } from '../../types.js';
+import type { HookEntry, HooksFile } from '../../types.js';
+/** Legacy Belay-managed Shell preToolUse gate duplicated beforeShellExecution. */
+export declare function legacyManagedShellPreToolUseEntry(platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HookEntry;
+export declare function removeLegacyManagedShellPreToolUse(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
 export declare function mergeCursorHooksFile(current: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
+export declare function hasDuplicateCursorShellGates(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): boolean;

package/dist/adapters/cursor/hooks.js

@@ -10,10 +10,37 @@ function mergeHookEntry(current, expected, placement) {
     }
     return [...filtered, expected];
 }
+/** Legacy Belay-managed Shell preToolUse gate duplicated beforeShellExecution. */
+export function legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot) {
+    const managed = getManagedHookEntries(platform, hooksDir, repoRoot);
+    const referencePreToolUse = managed.find((entry) => entry.event === 'preToolUse' && entry.definition.matcher === 'Write')?.definition;
+    if (!referencePreToolUse) {
+        throw new Error('managed hook definitions missing for legacy Shell migration');
+    }
+    return {
+        command: referencePreToolUse.command,
+        matcher: 'Shell',
+    };
+}
+export function removeLegacyManagedShellPreToolUse(hooks, platform, hooksDir, repoRoot) {
+    const legacy = legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot);
+    const preToolUse = hooks.hooks.preToolUse;
+    if (!Array.isArray(preToolUse)) {
+        return hooks;
+    }
+    return {
+        ...hooks,
+        hooks: {
+            ...hooks.hooks,
+            preToolUse: preToolUse.filter((entry) => !entryMatches(entry, legacy)),
+        },
+    };
+}
 export function mergeCursorHooksFile(current, platform, hooksDir, repoRoot) {
+    const withoutLegacyShell = removeLegacyManagedShellPreToolUse(current, platform, hooksDir, repoRoot);
     const next = {
-        version: current.version || 1,
-        hooks: { ...current.hooks },
+        version: withoutLegacyShell.version || 1,
+        hooks: { ...withoutLegacyShell.hooks },
     };
     const managedEntries = getManagedHookEntries(platform, hooksDir, repoRoot);
     for (const { event, definition } of managedEntries) {
@@ -24,3 +51,11 @@ export function mergeCursorHooksFile(current, platform, hooksDir, repoRoot) {
     }
     return next;
 }
+export function hasDuplicateCursorShellGates(hooks, platform, hooksDir, repoRoot) {
+    const legacy = legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot);
+    const preToolUse = hooks.hooks.preToolUse;
+    if (!Array.isArray(preToolUse)) {
+        return false;
+    }
+    return preToolUse.some((entry) => entryMatches(entry, legacy));
+}

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

@@ -65,6 +65,7 @@ export async function runShellGateHook() {
             kind: 'shell',
             cwd,
             command,
+            sourceEvent: 'beforeShellExecution',
         });
         jsonResponse(gateVerdictToCursorResponse(verdict));
     }
@@ -87,6 +88,7 @@ export async function runToolGateHook(eventName) {
                 kind: 'subagent',
                 cwd,
                 payload,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -97,6 +99,7 @@ export async function runToolGateHook(eventName) {
                 cwd,
                 payload,
                 toolName,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -107,6 +110,7 @@ export async function runToolGateHook(eventName) {
                 cwd,
                 payload,
                 toolName,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -116,6 +120,7 @@ export async function runToolGateHook(eventName) {
                 kind: 'subagent',
                 cwd,
                 payload,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;

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

@@ -46,6 +46,7 @@ export declare function evaluateGatedAction(ctx: GateRuntimeContext, deps: GateR
     command?: string;
     payload?: Record<string, unknown>;
     toolName?: string;
+    sourceEvent?: string;
 }): 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>;

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

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -7,6 +7,7 @@ import { buildReplayHint, buildRetryInstructionForConfig, canAutoReplay, getExec
 import { claimApprovedForReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
 import { buildAuditActionSnapshot, buildAuditReplayContext, } from '../../core/audit-replay-context.js';
+import { approvalCorrelationId, serializeAuditRecordV3 } from '../../core/audit-serialize.js';
 import { boundedUtf8Tail } from '../../core/bounded-output.js';
 import { mutateApprovalStateWithRetry } from '../../core/capability/approval-state-mutation.js';
 import { APPROVAL_STATE_VERSION_V3 } from '../../core/capability/approval-v3.js';
@@ -37,8 +38,8 @@ import { canonicalPath } from '../../core/path-utils.js';
 import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
 import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
 import { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
+import { buildAuditProvenanceFields } from '../../runtime-provenance.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,
@@ -47,34 +48,7 @@ const EMPTY_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 preservedContainedAuditMetadata(record) {
-    const safe = {};
-    if (record.wouldMediate === true)
-        safe.wouldMediate = true;
-    if (typeof record.receiptHash === 'string' && /^[a-f0-9]{64}$/.test(record.receiptHash)) {
-        safe.receiptHash = record.receiptHash;
-    }
-    if (typeof record.imageId === 'string' && /^sha256:[a-f0-9]{64}$/.test(record.imageId)) {
-        safe.imageId = record.imageId;
-    }
-    if (record.mirrorBackend === 'file_copy')
-        safe.mirrorBackend = record.mirrorBackend;
-    if (record.exitCode === null || Number.isSafeInteger(record.exitCode)) {
-        safe.exitCode = record.exitCode;
-    }
-    if (typeof record.timedOut === 'boolean')
-        safe.timedOut = record.timedOut;
-    return safe;
+    return buildAuditProvenanceFields(config, runtime);
 }
 function adapterIdFromContext(ctx) {
     if (ctx.config.adapter === 'cursor' ||
@@ -87,6 +61,14 @@ function adapterIdFromContext(ctx) {
     }
     return undefined;
 }
+function extractShellCommandFromPayload(payload) {
+    const toolInput = payload.tool_input;
+    if (!toolInput || typeof toolInput !== 'object') {
+        return '';
+    }
+    const input = toolInput;
+    return typeof input.command === 'string' ? input.command : '';
+}
 const REPLAY_AUDIT_FAILURE_NOTE = ' Audit recording failed; inspect audit storage before the next approval.';
 async function appendReplayAuditSafely(ctx, deps, event) {
     try {
@@ -117,15 +99,15 @@ export function createDefaultGateRuntimeDeps() {
             const provenance = auditProvenance(ctx.config);
             const record = {
                 timestamp: new Date().toISOString(),
+                mode: ctx.config.mode,
                 ...event,
                 ...provenance,
             };
             if (!ctx.config.audit.includeAssessment) {
                 delete record.assessment;
             }
-            const scrubbed = scrubValue(record, scrubOptionsFromConfig(ctx.config));
-            Object.assign(scrubbed, provenance, preservedContainedAuditMetadata(record));
-            await writeFile(auditPath, `${JSON.stringify(scrubbed)}\n`, {
+            const serialized = serializeAuditRecordV3(record, scrubOptionsFromConfig(ctx.config));
+            await writeFile(auditPath, `${JSON.stringify(serialized)}\n`, {
                 encoding: 'utf8',
                 flag: 'a',
             });
@@ -210,6 +192,22 @@ function gateAuditEventName(kind) {
     }
     return 'subagentGate';
 }
+function resolveGateAuditEvent(sourceEvent, kind) {
+    if (!sourceEvent) {
+        return gateAuditEventName(kind);
+    }
+    switch (sourceEvent.toLowerCase()) {
+        case 'beforeshellexecution':
+            return 'beforeShellExecution';
+        case 'pretooluse':
+            return 'preToolUse';
+        case 'subagentstart':
+        case 'subagentgate':
+            return 'subagentGate';
+        default:
+            return gateAuditEventName(kind);
+    }
+}
 async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, scopeHint) {
     const candidate = createApprovalRecordWithEnvelope({
         kind,
@@ -245,17 +243,6 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, sco
     }
     return outcome;
 }
-function approvalCorrelationId(approvalId) {
-    return createHash('sha256').update(approvalId).digest('hex').slice(0, 16);
-}
-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') {
@@ -408,10 +395,13 @@ function normalizeContainedFailure(error) {
     }
     return new ContainedExecutionFailureError('contained_execution_boundary_failed', { cause: error });
 }
-function containedAuditBase(kind, mode, result) {
+function containedAuditBase(kind, mode, result, sourceEvent) {
     const planFields = effectPlanAuditFields(result.effectPlan);
+    const rawSourceEvent = sourceEvent ?? gateAuditEventName(kind);
+    const auditEvent = resolveGateAuditEvent(rawSourceEvent, kind);
     return {
-        event: gateAuditEventName(kind),
+        event: auditEvent,
+        sourceEvent: rawSourceEvent,
         kind,
         fingerprint: result.fingerprint,
         mode,
@@ -426,11 +416,11 @@ function containedAuditBase(kind, mode, result) {
     };
 }
 async function mediateContainedUnknownExecution(params) {
-    const { ctx, deps, action, command } = params;
+    const { ctx, deps, action, command, sourceEvent } = params;
     const result = { ...params.result, wouldMediate: true };
     if (ctx.config.mode === 'audit') {
         await deps.appendAudit(ctx, {
-            ...containedAuditBase(action.kind, ctx.config.mode, result),
+            ...containedAuditBase(action.kind, ctx.config.mode, result, sourceEvent),
             verdict: result.verdict,
             reason: result.reason,
             wouldBlock: true,
@@ -505,7 +495,7 @@ async function mediateContainedUnknownExecution(params) {
             reason,
         };
         await deps.appendAudit(ctx, {
-            ...containedAuditBase(action.kind, ctx.config.mode, failedResult),
+            ...containedAuditBase(action.kind, ctx.config.mode, failedResult, sourceEvent),
             verdict: failedResult.verdict,
             reason,
             wouldBlock: true,
@@ -546,7 +536,7 @@ async function mediateContainedUnknownExecution(params) {
         mediatedExecution,
     };
     await deps.appendAudit(ctx, {
-        ...containedAuditBase(action.kind, ctx.config.mode, mediatedResult),
+        ...containedAuditBase(action.kind, ctx.config.mode, mediatedResult, sourceEvent),
         verdict: mediatedResult.verdict,
         reason,
         wouldBlock: false,
@@ -621,8 +611,10 @@ export async function evaluateGatedAction(ctx, deps, params) {
                 effectFree: false,
             }),
         };
+        const sourceEvent = params.sourceEvent ?? gateAuditEventName(params.kind);
         await deps.appendAudit(ctx, {
-            event: gateAuditEventName(params.kind),
+            event: resolveGateAuditEvent(sourceEvent, params.kind),
+            sourceEvent,
             kind: params.kind,
             fingerprint: verdict.fingerprint,
             verdict: verdict.verdict,
@@ -690,6 +682,7 @@ export async function evaluateGatedAction(ctx, deps, params) {
             action,
             command: action.command,
             result: predicted,
+            sourceEvent: params.sourceEvent,
         });
         if (mediated) {
             return mediated;
@@ -785,6 +778,7 @@ 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, {
+        sourceEvent: params.sourceEvent,
         predictedAssessment,
         observedAssessment,
         transactionalLayer,
@@ -904,8 +898,11 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             (kind === 'shell' ? auditExtras.approvalInput?.input : undefined),
         stateDir,
     });
+    const sourceEvent = auditExtras.sourceEvent ?? gateAuditEventName(kind);
+    const auditEvent = resolveGateAuditEvent(sourceEvent, kind);
     const gateBase = {
-        event: gateAuditEventName(kind),
+        event: auditEvent,
+        sourceEvent,
         kind,
         fingerprint: result.fingerprint,
         summary: result.normalizedCommand ?? result.summary ?? '',