@guilz-dev/belay 0.9.4 → 0.10.0

package/README.md

@@ -342,7 +342,7 @@ Notable settings:
   uses `git_worktree`; dirty Git and non-Git directories use `file_checkpoint` when separately
   enabled (`policy.transactional.fileCheckpoint.enabled` and, for non-Git roots,
   `allowNonGit: true`) with an attested workspace-isolating boundary. Restore is conflict-checked
-  and always requires a signed out-of-band, exact one-shot approval. Network, remote Git,
+  and always requires a signed local-control-plane, 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
@@ -390,7 +390,8 @@ belay recover [advice] [--command "rm important.ts"] # advisory candidates only
 belay recover status                          # checkpoint backend, eligibility, 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 recover apply <checkpoint-id>           # signed exact one-shot approval required
+belay approval-token <approval-id>             # operator terminal only; agent shell must ask
 belay explain -- <shell-command>              # inspect a verdict
 belay explain --kind subagent -- "deploy to production"
 belay explain --kind tool --tool Write -- .env

package/dist/adapters/cursor/hook-dispatch-entry.d.ts

@@ -4,4 +4,7 @@ export interface DispatchCursorHookParams {
     kind: CursorHookKind;
     eventName: string;
 }
+type CursorResponse = Record<string, unknown>;
+declare function dispatchCursorHookResponse(params: DispatchCursorHookParams): Promise<CursorResponse>;
 export declare function dispatchCursorHook(params: DispatchCursorHookParams): Promise<void>;
+export { dispatchCursorHookResponse };

package/dist/adapters/cursor/hook-dispatch-entry.js

@@ -97,7 +97,17 @@ async function dispatchCursorHookResponse(params) {
     if (!input.ok) {
         return failClosedResponse(params.kind, 'belay received malformed Cursor hook input.');
     }
+    if (params.kind === 'tool-gate' &&
+        (params.eventName === 'preToolUse' || params.eventName === 'PreToolUse') &&
+        input.payload.tool_name === 'Shell') {
+        return neutralResponse(params.kind);
+    }
     if (!isRecognizedPayload(params, input.payload)) {
+        if (params.kind === 'tool-gate' &&
+            (params.eventName === 'preToolUse' || params.eventName === 'PreToolUse') &&
+            isNonEmptyString(input.payload.tool_name)) {
+            return failClosedResponse(params.kind, 'belay received a malformed preToolUse payload. Run belay doctor, then retry.');
+        }
         return neutralResponse(params.kind);
     }
     try {
@@ -124,3 +134,4 @@ export async function dispatchCursorHook(params) {
     const response = await dispatchCursorHookResponse(params);
     process.stdout.write(`${JSON.stringify(response)}\n`);
 }
+export { dispatchCursorHookResponse };

package/dist/adapters/cursor/hook-router.js

@@ -1,6 +1,7 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { resolveCursorActionCwdDetails } from './cwd-resolution.js';
+import { isTrustedCursorRoutingConfig } from './routing-config-trust.js';
 import { cursorRoutingConfigPath, cursorRoutingHooksDir, cursorRoutingHooksSettingsPath, cursorRoutingRuntimeDir, findCursorRoutingRepoRoot, } from './routing-layout.js';
 function canonicalExistingPath(value) {
     if (!existsSync(value)) {
@@ -103,18 +104,24 @@ function commandInvokesProjectHook(command, runnerPath, kind, eventName) {
     ].join(' ');
     return Buffer.from(encoded, 'base64').toString('utf16le') === expected;
 }
-function expectedMatcher(eventName, payload) {
+function expectedMatchers(eventName, payload) {
     if (eventName === 'preToolUse') {
-        return typeof payload.tool_name === 'string' ? payload.tool_name : undefined;
+        // Managed preToolUse is intentionally unfiltered. Keep the legacy matcher variant so older
+        // installed hooks still route through the same owner until upgrade.
+        const values = [undefined];
+        if (typeof payload.tool_name === 'string') {
+            values.push(payload.tool_name);
+        }
+        return values;
     }
     if (eventName === 'subagentStart') {
-        return typeof payload.subagent_type === 'string' ? payload.subagent_type : undefined;
+        return [typeof payload.subagent_type === 'string' ? payload.subagent_type : undefined];
     }
-    return undefined;
+    return [undefined];
 }
 function hasManagedProjectHookEntry(repoRoot, runnerPath, params) {
     const eventName = eventNameFor(params);
-    const matcher = expectedMatcher(eventName, params.payload);
+    const matchers = new Set(expectedMatchers(eventName, params.payload));
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(cursorRoutingHooksSettingsPath(repoRoot), 'utf8'));
@@ -139,7 +146,7 @@ function hasManagedProjectHookEntry(repoRoot, runnerPath, params) {
         }
         const definition = entry;
         return (definition.failClosed === true &&
-            definition.matcher === matcher &&
+            matchers.has(definition.matcher) &&
             typeof definition.command === 'string' &&
             commandInvokesProjectHook(definition.command, runnerPath, params.kind, eventName));
     });
@@ -213,7 +220,7 @@ function readInstallScope(repoRoot) {
             typeof parsed === 'object' &&
             !Array.isArray(parsed) &&
             parsed.installScope === 'global') {
-            return 'global';
+            return isTrustedCursorRoutingConfig(repoRoot, parsed) ? 'global' : 'project';
         }
     }
     catch {

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

@@ -1,5 +1,5 @@
 import type { HookEntry, HooksFile } from '../../types.js';
-/** Managed Shell preToolUse gate for Cursor Agent Shell tool invocations. */
+/** Legacy managed Shell preToolUse gate matcher (upgrade/uninstall migration only). */
 export declare function managedShellPreToolUseEntry(platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HookEntry;
 /** @deprecated Use {@link managedShellPreToolUseEntry}. */
 export declare const legacyManagedShellPreToolUseEntry: typeof managedShellPreToolUseEntry;

package/dist/adapters/cursor/hooks.js

@@ -16,13 +16,24 @@ function legacyManagedEntries(platform, hooksDir, repoRoot) {
             entries.push(...getManagedHookEntries(platform, canonicalHooksDir, repoRoot, 'legacy-absolute'));
         }
     }
-    return entries;
+    const legacyMatchedToolNames = ['Task', 'Write', 'StrReplace', 'Delete'];
+    return [
+        ...entries,
+        ...entries.flatMap(({ event, definition }) => event === 'preToolUse' && definition.matcher === undefined
+            ? legacyMatchedToolNames.map((matcher) => ({
+                event,
+                definition: { ...definition, matcher },
+            }))
+            : []),
+    ];
 }
 function variantsForDefinition(legacyEntries, event, definition) {
     return [
         definition,
         ...legacyEntries
-            .filter((entry) => entry.event === event && entry.definition.matcher === definition.matcher)
+            .filter((entry) => entry.event === event &&
+            (entry.definition.matcher === definition.matcher ||
+                (event === 'preToolUse' && definition.matcher === undefined)))
             .map((entry) => entry.definition),
     ];
 }
@@ -34,10 +45,10 @@ function mergeHookEntry(current, expected, managedVariants, placement) {
     }
     return [...filtered, expected];
 }
-/** Managed Shell preToolUse gate for Cursor Agent Shell tool invocations. */
+/** Legacy managed Shell preToolUse gate matcher (upgrade/uninstall migration only). */
 export function managedShellPreToolUseEntry(platform, hooksDir, repoRoot) {
     const managed = getManagedHookEntries(platform, hooksDir, repoRoot);
-    const referencePreToolUse = managed.find((entry) => entry.event === 'preToolUse' && entry.definition.matcher === 'Write')?.definition;
+    const referencePreToolUse = managed.find((entry) => entry.event === 'preToolUse' && entry.definition.matcher === undefined)?.definition;
     if (!referencePreToolUse) {
         throw new Error('managed hook definitions missing for Shell preToolUse gate');
     }
@@ -91,7 +102,7 @@ export function legacyManagedShellPreToolUseVariants(platform, hooksDir, repoRoo
     const legacyEntries = legacyManagedEntries(platform, hooksDir, repoRoot);
     const commands = new Set([shellEntry.command]);
     for (const entry of legacyEntries) {
-        if (entry.event === 'preToolUse' && entry.definition.matcher === 'Write') {
+        if (entry.event === 'preToolUse') {
             commands.add(entry.definition.command);
         }
     }

package/dist/adapters/cursor/routing-config-trust.d.ts

@@ -0,0 +1 @@
+export declare function isTrustedCursorRoutingConfig(repoRoot: string, rawConfig: unknown): boolean;

package/dist/adapters/cursor/routing-config-trust.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalStringify(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalStringify(child)}`).join(',')}}`;
+}
+function hashValue(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function defaultControlPlaneDir() {
+    if (process.platform === 'win32' && process.env.APPDATA?.trim()) {
+        return path.join(process.env.APPDATA.trim(), 'agent-belay');
+    }
+    const base = process.env.XDG_CONFIG_HOME?.trim() || path.join(process.env.HOME ?? '', '.config');
+    return path.join(base, 'agent-belay');
+}
+function canonicalRepoRoot(repoRoot) {
+    try {
+        return realpathSync(repoRoot);
+    }
+    catch {
+        return path.resolve(repoRoot);
+    }
+}
+export function isTrustedCursorRoutingConfig(repoRoot, rawConfig) {
+    const canonicalRoot = canonicalRepoRoot(repoRoot);
+    const identity = hashValue(`${canonicalRoot}\u0000cursor`);
+    const recordPath = path.join(defaultControlPlaneDir(), 'config-trust', `${identity}.json`);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(recordPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return false;
+    }
+    const record = parsed;
+    const expectedKeys = new Set([
+        'schemaVersion',
+        'repoRoot',
+        'adapter',
+        'repoConfigFingerprint',
+        'trustedAt',
+    ]);
+    if (Object.keys(record).length !== expectedKeys.size ||
+        !Object.keys(record).every((key) => expectedKeys.has(key)) ||
+        record.schemaVersion !== 1 ||
+        record.adapter !== 'cursor' ||
+        typeof record.repoRoot !== 'string' ||
+        canonicalRepoRoot(record.repoRoot) !== canonicalRoot ||
+        typeof record.repoConfigFingerprint !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(record.repoConfigFingerprint) ||
+        typeof record.trustedAt !== 'string' ||
+        !Number.isFinite(Date.parse(record.trustedAt))) {
+        return false;
+    }
+    return record.repoConfigFingerprint === hashValue(canonicalStringify(rawConfig));
+}

package/dist/adapters/cursor/runtime-entry.d.ts

@@ -12,10 +12,10 @@ export declare function handleShellGateHook(payload: Record<string, unknown>): P
 export declare function runShellGateHook(): Promise<void>;
 export declare function handleToolGateHook(eventName: string, payload: Record<string, unknown>): Promise<import("../../core/gate-contract.js").GatePermissionResponse | {
     permission: string;
-    user_message: string;
+    user_message?: undefined;
 } | {
     permission: string;
-    user_message?: undefined;
+    user_message: string;
 }>;
 export declare function runToolGateHook(eventName: string): Promise<void>;
 export declare function handleAuditHook(eventName: string, payload: Record<string, unknown>): Promise<{}>;

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

@@ -3,6 +3,7 @@ import process from 'node:process';
 import { approvalCommandMatch } from '../../core/approval.js';
 import { findApprovalRepoRoots, formatAmbiguousApprovalRepoMessage, } from '../../core/approval-repo-lookup.js';
 import { DEFAULT_CONFIG_V4 } from '../../core/config.js';
+import { isRepoConfigTrustError } from '../../core/repo-config-trust.js';
 import { cursorLayout } from '../layouts/cursor.js';
 import { appendObservedAudit, createDefaultGateRuntimeDeps, evaluateGatedAction, gateVerdictToCursorResponse, processApprovalPrompt, resolveGateConfig, } from '../shared/gate-runtime.js';
 import { findRepoRoot } from '../shared/repo-root.js';
@@ -104,6 +105,9 @@ function isSubagentEvent(payload, eventName) {
 function isFileMutationTool(toolName) {
     return toolName === 'Write' || toolName === 'StrReplace' || toolName === 'Delete';
 }
+function isCursorPreToolUseEvent(eventName) {
+    return eventName === 'preToolUse' || eventName === 'PreToolUse';
+}
 export async function handleBeforeSubmitPromptHook(payload) {
     try {
         const prompt = String(payload.prompt ?? '');
@@ -123,7 +127,13 @@ export async function handleBeforeSubmitPromptHook(payload) {
             ...(result.replay ? { replay: result.replay } : {}),
         };
     }
-    catch {
+    catch (error) {
+        if (isRepoConfigTrustError(error)) {
+            return {
+                continue: false,
+                user_message: error.message,
+            };
+        }
         return {
             continue: false,
             user_message: 'belay failed while processing approval state. Run belay doctor, then retry.',
@@ -155,7 +165,13 @@ export async function handleShellGateHook(payload) {
         });
         return gateVerdictToCursorResponse(verdict);
     }
-    catch {
+    catch (error) {
+        if (isRepoConfigTrustError(error)) {
+            return {
+                permission: 'deny',
+                user_message: error.message,
+            };
+        }
         return {
             permission: 'deny',
             user_message: 'belay failed while classifying this shell command. Run belay doctor, then retry.',
@@ -168,6 +184,9 @@ export async function runShellGateHook() {
 export async function handleToolGateHook(eventName, payload) {
     try {
         const toolName = String(payload.tool_name ?? '');
+        if (isCursorPreToolUseEvent(eventName) && toolName === 'Shell') {
+            return { permission: 'allow' };
+        }
         const resolution = resolveCursorToolActionCwdDetails(payload, process.cwd(), eventName, toolName);
         if (isUnsafeGlobalHookFallback(resolution)) {
             return {
@@ -187,9 +206,9 @@ export async function handleToolGateHook(eventName, payload) {
             });
             return gateVerdictToCursorResponse(verdict);
         }
-        if (toolName === 'Shell') {
+        if (isFileMutationTool(toolName)) {
             const verdict = await evaluateGatedAction(ctx, deps, {
-                kind: 'shell',
+                kind: 'tool',
                 cwd,
                 payload,
                 toolName,
@@ -197,28 +216,34 @@ export async function handleToolGateHook(eventName, payload) {
             });
             return gateVerdictToCursorResponse(verdict);
         }
-        if (isFileMutationTool(toolName)) {
+        if (payload.tool_name === 'Task') {
             const verdict = await evaluateGatedAction(ctx, deps, {
-                kind: 'tool',
+                kind: 'subagent',
                 cwd,
                 payload,
-                toolName,
                 sourceEvent: eventName,
             });
             return gateVerdictToCursorResponse(verdict);
         }
-        if (payload.tool_name === 'Task') {
+        if (isCursorPreToolUseEvent(eventName)) {
             const verdict = await evaluateGatedAction(ctx, deps, {
-                kind: 'subagent',
+                kind: 'tool',
                 cwd,
                 payload,
+                toolName,
                 sourceEvent: eventName,
             });
             return gateVerdictToCursorResponse(verdict);
         }
         return { permission: 'allow' };
     }
-    catch {
+    catch (error) {
+        if (isRepoConfigTrustError(error)) {
+            return {
+                permission: 'deny',
+                user_message: error.message,
+            };
+        }
         return {
             permission: 'deny',
             user_message: 'belay failed while classifying this tool action. Run belay doctor, then retry.',

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

@@ -5,7 +5,6 @@ import path from 'node:path';
 import { compactApprovals, createApprovalRecordWithEnvelope } from '../../core/approval.js';
 import { buildReplayHint, buildRetryInstructionForConfig, canAutoReplay, getExecutionLeaseMs, validateReplayEnvelope, } from '../../core/approval-replay.js';
 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, toolInvocationCorrelationId, } from '../../core/audit-serialize.js';
 import { boundedUtf8Tail } from '../../core/bounded-output.js';
@@ -37,6 +36,7 @@ import { notifyDeny } from '../../core/notify.js';
 import { canonicalPath } from '../../core/path-utils.js';
 import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
 import { fingerprintReplayPayload, redactToolInvocationId } from '../../core/replay-scrub.js';
+import { assertRepoConfigTrusted } from '../../core/repo-config-trust.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';
@@ -91,7 +91,15 @@ async function loadJsonFile(filePath, fallback) {
 export function createDefaultGateRuntimeDeps() {
     return {
         async readConfig(configPath) {
-            return loadJsonFile(configPath, {});
+            try {
+                return JSON.parse(await readFile(configPath, 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return {};
+                }
+                throw error;
+            }
         },
         async appendAudit(ctx, event) {
             const auditPath = path.join(ctx.repoRoot, ctx.config.audit.logPath);
@@ -149,6 +157,7 @@ export function createDefaultGateRuntimeDeps() {
 }
 export async function resolveGateConfig(ctx, deps) {
     const loaded = await deps.readConfig(ctx.configPath);
+    await assertRepoConfigTrusted(ctx.repoRoot, ctx.layout.name, loaded);
     let teamConfig = null;
     const teamPath = teamConfigPath();
     if (existsSync(teamPath)) {
@@ -675,7 +684,23 @@ export async function evaluateGatedAction(ctx, deps, params) {
         ...authorization,
         egressProxyActive,
     };
-    const predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
+    let predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
+    if (action.kind === 'tool' &&
+        predicted.reason === 'unclassified_tool' &&
+        (ctx.config.policy.codexUnmappedTool ?? 'deny') === 'deny') {
+        predicted = {
+            ...predicted,
+            verdict: 'deny_pending_approval',
+            reason: 'unmapped_tool',
+            assessment: {
+                reversibility: 'irreversible',
+                external: false,
+                blastRadius: 'unknown tool action',
+                confidence: 0.5,
+                signals: ['unmapped_tool'],
+            },
+        };
+    }
     if (action.kind === 'shell' &&
         action.command &&
         isContainedUnknownExecutionEligible(ctx.config, action, predicted)) {
@@ -937,19 +962,6 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         if (created) {
             await recordGateApprovalAsk(stateDir, result.reason, false);
         }
-        let approvalToken;
-        try {
-            approvalToken = await issueApprovalToken({
-                approvalId: approval.approvalId,
-                fingerprint: approval.fingerprint,
-                repoRoot: approval.repoRoot,
-                issuedAt: approval.createdAt,
-                expiresAt: approval.expiresAt,
-            }, configuredControlPlaneDir(ctx.config));
-        }
-        catch {
-            approvalToken = undefined;
-        }
         const denialReason = failure?.reason ?? result.reason;
         if (ctx.config.notifications.webhookUrl || ctx.config.notifications.commandHook) {
             await notifyDeny(ctx.config.notifications, {
@@ -958,7 +970,6 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
                 summary: result.normalizedCommand ?? result.summary ?? '',
                 repoRoot: ctx.repoRoot,
                 fingerprint: result.fingerprint,
-                approvalToken,
             });
         }
         const failureAuditFields = typeof failure?.auditFields === 'function'