@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/capability/request.d.ts

@@ -0,0 +1,48 @@
+export declare const CAPABILITY_REQUEST_VERSION: 1;
+export type CapabilityAction = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'secret.read' | 'git.ref.write' | 'control_plane.write' | 'indeterminate';
+export type CapabilityEvidenceLevel = 'certain' | 'possible' | 'indeterminate';
+export type CapabilityHookKind = 'shell' | 'tool' | 'subagent';
+export interface CapabilityPrincipal {
+    adapter?: string;
+    repoRoot: string;
+    sessionHash?: string;
+}
+export type CapabilityResource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'network';
+    host: string;
+    port?: number;
+    protocol?: string;
+} | {
+    kind: 'executable';
+    command: string;
+} | {
+    kind: 'package-cache';
+    manager: 'npm' | 'pnpm';
+} | {
+    kind: 'git-ref';
+    ref: string;
+} | {
+    kind: 'unknown';
+};
+export interface CapabilityRequestContext {
+    cwd: string;
+    inputFingerprint: string;
+    hookKind: CapabilityHookKind;
+    analysisBasis: string[];
+    boundaryProfile?: string;
+}
+export interface CapabilityEvidence {
+    level: CapabilityEvidenceLevel;
+    signals: string[];
+}
+export interface CapabilityRequestV1 {
+    version: typeof CAPABILITY_REQUEST_VERSION;
+    principal: CapabilityPrincipal;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    context: CapabilityRequestContext;
+    evidence: CapabilityEvidence;
+}

package/dist/core/capability/request.js

@@ -0,0 +1 @@
+export const CAPABILITY_REQUEST_VERSION = 1;

package/dist/core/capability/resolver.d.ts

@@ -0,0 +1,4 @@
+export { evaluateSegmentShellPolicy, type SegmentShellPolicyInput, } from '../verdict/shell-policy.js';
+export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
+export { type CapabilityAuthorizationMetadata, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, type FileMutationCapabilityAnalysis, policyDecisionRequiresAsk, type ShellCapabilityAnalysis, type SubagentCapabilityAnalysis, } from './policy-engine.js';

package/dist/core/capability/resolver.js

@@ -0,0 +1,4 @@
+export { evaluateSegmentShellPolicy, } from '../verdict/shell-policy.js';
+export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
+export { policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, policyDecisionRequiresAsk, } from './policy-engine.js';

package/dist/core/classify-subagent.d.ts

@@ -1,2 +1,3 @@
+import type { BelayConfigV3 } from './config.js';
 import type { ClassifierOptions, ClassifyResult } from './types.js';
-export declare function classifySubagent(payload: Record<string, unknown>, repoRoot: string, options?: ClassifierOptions): ClassifyResult;
+export declare function classifySubagent(payload: Record<string, unknown>, repoRoot: string, options: ClassifierOptions | undefined, config: BelayConfigV3): ClassifyResult;

package/dist/core/classify-subagent.js

@@ -1,3 +1,6 @@
+import { BOUNDARY_PROFILE_L3_L4_ONLY } from './capability/boundary-profile.js';
+import { policyReasonToLegacyReason } from './capability/policy-bridge.js';
+import { evaluateSubagentPolicy, policyDecisionRequiresAsk } from './capability/policy-engine.js';
 import { canonicalStringify, subagentFingerprint } from './fingerprint.js';
 import { subagentFingerprintSource } from './replay-scrub.js';
 import { scrubValue } from './scrub.js';
@@ -25,7 +28,7 @@ function extractSubagentText(payload, options) {
 function fingerprintSource(payload, options) {
     return subagentFingerprintSource(payload, options.scrubOptions ?? {});
 }
-export function classifySubagent(payload, repoRoot, options = {}) {
+export function classifySubagent(payload, repoRoot, options = {}, config) {
     const kind = payload.tool_name === 'Task' ? 'Task' : String(payload.subagent_type ?? 'generalPurpose');
     const scrubbed = fingerprintSource(payload, options);
     const summary = extractSubagentText(payload, options);
@@ -35,6 +38,36 @@ export function classifySubagent(payload, repoRoot, options = {}) {
         const pattern = new RegExp(`\\b${term}\\b`, 'i');
         return pattern.test(lowered);
     });
+    const signals = hasExternalTerm ? ['subagent_external_intent_hint'] : ['subagent_default_review'];
+    const { request, decision } = evaluateSubagentPolicy({
+        subagentType: kind,
+        summary,
+        repoRoot,
+        cwd: repoRoot,
+        inputFingerprint: fingerprint,
+        signals,
+    }, config, {
+        grants: options.grants,
+        attestation: options.attestation,
+        egressProxyActive: options.egressProxyActive,
+    });
+    if (policyDecisionRequiresAsk(decision)) {
+        return {
+            verdict: 'deny_pending_approval',
+            reason: policyReasonToLegacyReason(decision),
+            summary,
+            fingerprint,
+            assessment: {
+                reversibility: 'recoverable_with_cost',
+                external: hasExternalTerm,
+                blastRadius: 'subagent task scope',
+                confidence: hasExternalTerm ? 0.7 : 0.67,
+                signals: [...signals, ...decision.signals],
+            },
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+        };
+    }
     return {
         verdict: 'allow_flagged',
         reason: 'subagent_review',
@@ -45,7 +78,10 @@ export function classifySubagent(payload, repoRoot, options = {}) {
             external: false,
             blastRadius: 'subagent task scope',
             confidence: hasExternalTerm ? 0.7 : 0.67,
-            signals: hasExternalTerm ? ['subagent_external_intent_hint'] : ['subagent_default_review'],
+            signals,
         },
+        capabilityRequests: [request],
+        authorizationDecision: decision,
+        boundaryProfile: options.boundaryProfile ?? BOUNDARY_PROFILE_L3_L4_ONLY,
     };
 }

package/dist/core/classify-tool.js

@@ -1,11 +1,14 @@
 import path from 'node:path';
+import { BOUNDARY_PROFILE_L3_L4_ONLY } from './capability/boundary-profile.js';
+import { policyReasonToLegacyReason } from './capability/policy-bridge.js';
+import { evaluateFileMutationPolicy, policyDecisionRequiresAsk, } from './capability/policy-engine.js';
 import { canonicalStringify, toolFingerprint } from './fingerprint.js';
 import { matchesSensitivePath } from './glob.js';
 import { pathWithinRoot, resolveWorkspaceRootMatch } from './path-utils.js';
 import { scrubValue } from './scrub.js';
 import { classifyShell, resolveClassifierTrustedCwd } from './verdict/adapter.js';
-import { mutationPrescanRequiresAsk, tier1RequiresAsk } from './verdict/judge.js';
-import { createJudgeFromConfig } from './verdict/judge-factory.js';
+import { isGitPath } from './verdict/containment.js';
+import { mutationPrescanRequiresAsk } from './verdict/prescan.js';
 const DEFAULT_SENSITIVE_PATHS = ['.env', '.env.*', '**/credentials/**'];
 const FILE_WRITE_TOOL_NAMES = new Set(['write']);
 const FILE_EDIT_TOOL_NAMES = new Set([
@@ -18,6 +21,19 @@ const FILE_EDIT_TOOL_NAMES = new Set([
 ]);
 const FILE_DELETE_TOOL_NAMES = new Set(['delete']);
 const APPLY_PATCH_TOOL_NAMES = new Set(['apply_patch', 'applypatch']);
+function policyAuth(options) {
+    if (!options.grants &&
+        options.attestation === undefined &&
+        options.egressProxyActive === undefined) {
+        return undefined;
+    }
+    return {
+        grants: options.grants,
+        attestation: options.attestation,
+        egressProxyActive: options.egressProxyActive,
+        sensitivePaths: options.sensitivePaths,
+    };
+}
 function scrubPayload(value, options) {
     return scrubValue(value, options.scrubOptions);
 }
@@ -76,11 +92,7 @@ function applyPatchTargets(patch) {
 function normalizedToolName(toolName) {
     return toolName.trim().toLowerCase();
 }
-function resolveFileTier1Judge(config, options, repoRoot) {
-    return options.tier1Judge ?? createJudgeFromConfig(config, { repoRoot });
-}
-async function classifyFileMutationWithTier1(params) {
-    const judge = resolveFileTier1Judge(params.config, params.options, params.repoRoot);
+function classifyFileMutationWithPolicy(params) {
     const trustedCwd = resolveClassifierTrustedCwd(params.cwd, params.options);
     const prescan = mutationPrescanRequiresAsk({
         targets: [params.filePath],
@@ -91,11 +103,29 @@ async function classifyFileMutationWithTier1(params) {
         sensitivePaths: params.options.sensitivePaths ?? params.config.classifier.sensitivePaths,
     });
     if (prescan) {
+        const fingerprint = toolFingerprint(params.toolName, { path: params.filePath }, params.repoRoot);
+        const { request, decision } = evaluateFileMutationPolicy({
+            hookKind: 'tool',
+            toolKind: params.toolKind,
+            filePath: params.filePath,
+            resolvedPath: params.resolvedPath,
+            repoRoot: params.repoRoot,
+            cwd: params.cwd,
+            inputFingerprint: fingerprint,
+            signals: [...params.signals, 'tier1_catastrophic', prescan.reason],
+            isDelete: params.isDelete,
+            locationLabel: params.locationLabel,
+            trustedWorkspaceRoots: params.options.trustedWorkspaceRoots,
+            sensitivePaths: params.options.sensitivePaths ?? params.config.classifier.sensitivePaths,
+        }, params.config, policyAuth(params.options));
+        const legacyReason = policyDecisionRequiresAsk(decision)
+            ? policyReasonToLegacyReason(decision)
+            : 'tier1_catastrophic';
         return {
             verdict: 'deny_pending_approval',
-            reason: 'tier1_catastrophic',
+            reason: legacyReason,
             summary: params.filePath,
-            fingerprint: toolFingerprint(params.toolName, { path: params.filePath }, params.repoRoot),
+            fingerprint,
             assessment: {
                 reversibility: 'irreversible',
                 external: params.locationLabel === 'outside_repo',
@@ -103,20 +133,32 @@ async function classifyFileMutationWithTier1(params) {
                     ? 'outside the repository'
                     : 'sensitive repository file',
                 confidence: 0.95,
-                signals: [...params.signals, 'tier1_catastrophic', prescan.reason],
+                signals: [...params.signals, 'tier1_catastrophic', prescan.reason, ...decision.signals],
             },
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+            boundaryProfile: params.options.boundaryProfile ?? BOUNDARY_PROFILE_L3_L4_ONLY,
         };
     }
-    const tier1Text = `file_mutation: ${params.toolKind} path=${params.resolvedPath} location=${params.locationLabel}`;
-    const tier1 = await judge.evaluate({
-        text: tier1Text,
-        context: { cwd: params.cwd, repoRoot: params.repoRoot },
-    });
     const fingerprint = toolFingerprint(params.toolName, { path: params.filePath }, params.repoRoot);
-    if (tier1RequiresAsk(tier1)) {
+    const { request, decision } = evaluateFileMutationPolicy({
+        hookKind: 'tool',
+        toolKind: params.toolKind,
+        filePath: params.filePath,
+        resolvedPath: params.resolvedPath,
+        repoRoot: params.repoRoot,
+        cwd: params.cwd,
+        inputFingerprint: fingerprint,
+        signals: params.signals,
+        isDelete: params.isDelete,
+        locationLabel: params.locationLabel,
+        trustedWorkspaceRoots: params.options.trustedWorkspaceRoots,
+        sensitivePaths: params.options.sensitivePaths ?? params.config.classifier.sensitivePaths,
+    }, params.config, policyAuth(params.options));
+    if (policyDecisionRequiresAsk(decision)) {
         return {
             verdict: 'deny_pending_approval',
-            reason: 'tier1_catastrophic',
+            reason: policyReasonToLegacyReason(decision),
             summary: params.filePath,
             fingerprint,
             assessment: {
@@ -125,9 +167,12 @@ async function classifyFileMutationWithTier1(params) {
                 blastRadius: params.locationLabel === 'outside_repo'
                     ? 'outside the repository'
                     : 'sensitive repository file',
-                confidence: 0.82,
-                signals: [...params.signals, 'tier1_catastrophic', tier1.reason],
+                confidence: 0.95,
+                signals: [...params.signals, ...decision.signals],
             },
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+            boundaryProfile: params.options.boundaryProfile ?? BOUNDARY_PROFILE_L3_L4_ONLY,
         };
     }
     const reason = params.isDelete ? 'file_delete' : 'file_mutation';
@@ -141,8 +186,11 @@ async function classifyFileMutationWithTier1(params) {
             external: params.locationLabel === 'outside_repo',
             blastRadius: params.locationLabel === 'outside_repo' ? 'outside the repository' : 'this repository',
             confidence: 0.72,
-            signals: [...params.signals, 'tier1_restorable', tier1.reason],
+            signals: [...params.signals, ...decision.signals],
         },
+        capabilityRequests: [request],
+        authorizationDecision: decision,
+        boundaryProfile: params.options.boundaryProfile ?? BOUNDARY_PROFILE_L3_L4_ONLY,
     };
 }
 export async function classifyToolUse(payload, repoRoot, cwd, config, options = {}) {
@@ -230,24 +278,24 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
         const hitsProtectedRoot = protectedRoots.some((root) => pathWithinRoot(root, resolvedPath));
         if (hitsProtectedRoot) {
             signals.push('control_plane_path');
-            return {
-                verdict: 'deny_pending_approval',
-                reason: 'control_plane_mutation',
-                summary: filePath,
-                fingerprint: toolFingerprint(toolName, { path: filePath }, repoRoot),
-                assessment: {
-                    reversibility: 'irreversible',
-                    external: false,
-                    blastRadius: 'agent-belay control plane',
-                    confidence: 0.97,
-                    signals,
-                },
-            };
+            return classifyFileMutationWithPolicy({
+                toolName,
+                toolKind,
+                filePath,
+                resolvedPath,
+                repoRoot,
+                cwd,
+                config,
+                options,
+                signals,
+                isDelete: FILE_DELETE_TOOL_NAMES.has(toolKind),
+                locationLabel: 'control_plane',
+            });
         }
         const workspaceMatch = resolveWorkspaceRootMatch(repoRoot, options.trustedWorkspaceRoots, resolvedPath);
         if (workspaceMatch === null) {
             signals.push('outside_repo_path');
-            return classifyFileMutationWithTier1({
+            return classifyFileMutationWithPolicy({
                 toolName,
                 toolKind,
                 filePath,
@@ -274,7 +322,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
             sensitivePaths,
         });
         if (workspacePrescan) {
-            return classifyFileMutationWithTier1({
+            return classifyFileMutationWithPolicy({
                 toolName,
                 toolKind,
                 filePath,
@@ -291,7 +339,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
         const relativePath = workspaceMatch.relativePath;
         if (matchesSensitivePath(relativePath, sensitivePaths)) {
             signals.push('sensitive_path');
-            return classifyFileMutationWithTier1({
+            return classifyFileMutationWithPolicy({
                 toolName,
                 toolKind,
                 filePath,
@@ -306,35 +354,51 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
             });
         }
         if (FILE_DELETE_TOOL_NAMES.has(toolKind)) {
-            signals.push('file_delete');
-            return {
-                verdict: 'allow_flagged',
-                reason: 'file_delete',
-                summary: filePath,
-                fingerprint: toolFingerprint(toolName, { path: filePath }, repoRoot),
-                assessment: {
-                    reversibility: 'recoverable_with_cost',
-                    external: false,
-                    blastRadius: 'this repository',
-                    confidence: 0.7,
+            if (isGitPath(resolvedPath, repoRoot)) {
+                signals.push('protected_artifact');
+                return classifyFileMutationWithPolicy({
+                    toolName,
+                    toolKind,
+                    filePath,
+                    resolvedPath,
+                    repoRoot,
+                    cwd,
+                    config,
+                    options,
                     signals,
-                },
-            };
+                    isDelete: true,
+                    locationLabel: 'sensitive_path',
+                });
+            }
+            signals.push('file_delete');
+            return classifyFileMutationWithPolicy({
+                toolName,
+                toolKind,
+                filePath,
+                resolvedPath,
+                repoRoot,
+                cwd,
+                config,
+                options,
+                signals,
+                isDelete: true,
+                locationLabel: 'repo_local',
+            });
         }
         signals.push('file_mutation');
-        return {
-            verdict: 'allow_flagged',
-            reason: 'file_mutation',
-            summary: filePath,
-            fingerprint: toolFingerprint(toolName, { path: filePath }, repoRoot),
-            assessment: {
-                reversibility: 'recoverable_with_cost',
-                external: false,
-                blastRadius: 'this repository',
-                confidence: 0.68,
-                signals,
-            },
-        };
+        return classifyFileMutationWithPolicy({
+            toolName,
+            toolKind,
+            filePath,
+            resolvedPath,
+            repoRoot,
+            cwd,
+            config,
+            options,
+            signals,
+            isDelete: false,
+            locationLabel: 'repo_local',
+        });
     }
     if (APPLY_PATCH_TOOL_NAMES.has(toolKind)) {
         const patch = extractPatch(payload);

package/dist/core/config.d.ts

@@ -1,6 +1,6 @@
-import type { ClassifierOptions, ControlPlaneIntegrity, ScrubOptions, UnknownLocalEffectPolicy, UnparseableShellPolicy } from './types.js';
+import type { BoundaryDriverId } from './capability/attestation.js';
+import type { BelayMode, ClassifierOptions, ControlPlaneIntegrity, ScrubOptions, UnknownLocalEffectPolicy, UnparseableShellPolicy } from './types.js';
 import { type BelayJudgeRuntimeConfig } from './verdict/judge-runtime-config.js';
-export type BelayMode = 'enforce' | 'audit';
 export type { UnknownLocalEffectPolicy };
 export interface BelayConfigV1 {
     version: 1;
@@ -46,6 +46,15 @@ export interface BelayModelAssistConfig {
     model?: string;
     timeoutMs?: number;
 }
+export interface BelayFileCheckpointConfig {
+    enabled: boolean;
+    allowNonGit: boolean;
+    maxFiles: number;
+    maxSourceBytes: number;
+    maxWorkspaceBytes: number;
+    prepareTimeoutMs: number;
+    copyConcurrency: number;
+}
 export interface BelayTransactionalConfig {
     enabled: boolean;
     minConfidence: number;
@@ -55,6 +64,14 @@ export interface BelayTransactionalConfig {
     gates: {
         shell: boolean;
     };
+    fileCheckpoint: BelayFileCheckpointConfig;
+    checkpoint?: {
+        enabled: boolean;
+        appliedRetentionHours: number;
+        restoredRetentionHours: number;
+        maxCheckpoints: number;
+        maxBytes: number;
+    };
 }
 export interface BelayPolicyConfig {
     unknownLocalEffect: UnknownLocalEffectPolicy;
@@ -94,7 +111,10 @@ export interface JudgeCloudConsent {
     endpoint: string;
     by: string;
 }
+export type BelayJudgeMode = 'shadow' | 'off';
 export interface BelayJudgeConfig {
+    /** Gate uses PolicyEngine; judge runs async shadow/compare only. */
+    mode?: BelayJudgeMode;
     provider: JudgeProvider;
     providerId?: JudgeProviderId | DeprecatedJudgeProviderId;
     model: string;
@@ -157,8 +177,14 @@ export interface BelayEgressConfig {
     /** When true with egress enabled, L3 external command lists become hints only. */
     demoteL3External: boolean;
 }
+export interface BelayCapabilityConfig {
+    grantsEnabled?: boolean;
+    boundaryDriver?: BoundaryDriverId;
+    attestationRelPath?: string;
+}
+export declare const DEFAULT_CAPABILITY_V5: BelayCapabilityConfig;
 export interface BelayConfigV4 {
-    version: 4;
+    version: 4 | 5;
     adapter?: 'cursor' | 'claude' | 'codex';
     /** Where hooks/runtime/skill artifacts are installed. Defaults to project. */
     installScope?: 'project' | 'global';
@@ -178,6 +204,7 @@ export interface BelayConfigV4 {
     sandbox: BelaySandboxConfig;
     audit: BelayConfigV2['audit'];
     judge: BelayJudgeConfig;
+    capability?: BelayCapabilityConfig;
 }
 /** @deprecated Use BelayConfigV4 */
 export type BelayConfigV3 = BelayConfigV4;
@@ -186,6 +213,9 @@ export type BelayConfig = BelayConfigV4;
 export declare const DEFAULT_FENCE_WARN_THRESHOLD = 0.5;
 export declare const DEFAULT_CONFIDENCE_THRESHOLDS: BelayConfidenceThresholds;
 export declare const DEFAULT_MODEL_ASSIST: BelayModelAssistConfig;
+export declare const DEFAULT_FILE_CHECKPOINT: BelayFileCheckpointConfig;
+export declare function normalizeFileCheckpointConfig(raw: Partial<BelayFileCheckpointConfig> | undefined): BelayFileCheckpointConfig;
+export declare const DEFAULT_RECOVERY_CHECKPOINT: NonNullable<BelayTransactionalConfig['checkpoint']>;
 export declare const DEFAULT_TRANSACTIONAL_V3: BelayTransactionalConfig;
 export declare const LEGACY_POLICY_V3: BelayPolicyConfig;
 /** Fresh install defaults: recoverable-first with opaque/unparseable fail-closed. */
@@ -239,6 +269,7 @@ type RawConfigInput = Partial<{
     sandbox: Partial<BelaySandboxConfig>;
     audit: Partial<BelayConfigV2['audit']>;
     installScope: 'project' | 'global';
+    capability: Partial<BelayCapabilityConfig>;
 }>;
 export declare function migrateConfig(loaded: unknown): BelayConfigV4;
 export declare function normalizeConfigV2(config: BelayConfigV2): BelayConfigV2;