@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/verdict/verdict.js

@@ -1,12 +1,17 @@
-import { resolveMutationTarget } from '../path-utils.js';
-import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
+import path from 'node:path';
+import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
+import { policyDecisionRequiresAsk } from '../capability/policy-engine.js';
+import { canonicalPath, resolveMutationTarget } from '../path-utils.js';
+import { extractRedirectTargets, isFdDuplication, isRedirectOperator, tokenizeShell, } from '../shell-tokenizer.js';
 import { analyzePathTargets, cwdRelative, isDestructiveHighStakesMutation, resolveTrustedPath, touchesProtectedRoot, } from './containment.js';
 import { classifyEgressTool } from './egress-classify.js';
 import { verdictFingerprint } from './fingerprint.js';
-import { mutationPrescanRequiresAsk, prescanInterpreterCode, tier1RequiresAsk } from './judge.js';
-import { isRoutineLauncher, resolveLauncherRecipe } from './launcher-resolve.js';
+import { isReadOnlyLauncherInvocation, isRoutineLauncher, resolveLauncherRecipe, } from './launcher-resolve.js';
 import { allowFromCustomOverride, askFromCustomExternal, customAllowMatch, customExternalMatch, } from './overrides.js';
 import { extractRecursiveScript, isBareInterpreter, isVariableIndirectHead, parseSegment, peelTransparentWrappers, redactCommand, segmentOpacity, splitTopLevelSegments, substitutionInners, } from './parser.js';
+import { mutationPrescanRequiresAsk, prescanInterpreterCode, tier1RequiresAsk } from './prescan.js';
+import { evaluateSegmentShellPolicy, shellPolicyMetadata, } from './shell-policy.js';
+import { analyzeShellCommandSemantics, isPureReadOnlySemantics, LOCAL_MUTATION_KEYS, } from './shell-semantics.js';
 const DEFAULT_MAX_DEPTH = 8;
 const TIER0_EXTERNAL_KEYS = new Set([
     'git push',
@@ -20,7 +25,6 @@ const TIER0_EXTERNAL_KEYS = new Set([
     'supabase',
     'scp',
     'ssh',
-    'rsync',
 ]);
 const TIER0_EXTERNAL_HEADS = new Set([
     'dropdb',
@@ -30,66 +34,6 @@ const TIER0_EXTERNAL_HEADS = new Set([
     'mongosh',
     'redis-cli',
 ]);
-const READ_ONLY_KEYS = new Set([
-    'cat',
-    'cd',
-    'echo',
-    'git diff',
-    'git log',
-    'git rev-parse',
-    'git show',
-    'git status',
-    'head',
-    'ls',
-    'pwd',
-    'rg',
-    'sort',
-    'tail',
-    'wc',
-    'which',
-    'find',
-]);
-const PURE_READ_ONLY_KEYS = new Set([
-    'echo',
-    'git diff',
-    'git log',
-    'git rev-parse',
-    'git show',
-    'git status',
-    'pwd',
-    'which',
-]);
-const LOCAL_MUTATION_KEYS = new Set([
-    'chmod',
-    'cp',
-    'git add',
-    'git clean',
-    'git commit',
-    'git mv',
-    'git reset',
-    'mkdir',
-    'mv',
-    'rm',
-    'sed',
-    'tee',
-    'touch',
-    'truncate',
-]);
-/** Routine local build/test runners resolved from launcher recipes. */
-const LOCAL_ROUTINE_HEADS = new Set([
-    'tsc',
-    'vitest',
-    'vite',
-    'webpack',
-    'esbuild',
-    'rollup',
-    'jest',
-    'mocha',
-    'cargo',
-    'go',
-    'make',
-    'cmake',
-]);
 const BELAY_SELF_COMMANDS = new Set(['approve', 'revoke']);
 const FIND_DANGEROUS_FLAGS = new Set(['-delete', '-exec', '-execdir', '-ok', '-okdir']);
 function isFindDangerous(tokens) {
@@ -126,7 +70,7 @@ async function evaluateSubstitutions(command, context, depth) {
         }
         worst = worst ? combineInternal(worst, innerVerdict) : innerVerdict;
     }
-    if (!worst) {
+    if (!worst || worst.permission === 'allow') {
         return null;
     }
     return {
@@ -177,26 +121,46 @@ function combineInternal(left, right) {
             : right.reason,
         signals: [...new Set([...left.signals, ...right.signals])],
         judgeTrace: right.judgeTrace ?? left.judgeTrace,
+        capabilityRequests: [...(left.capabilityRequests ?? []), ...(right.capabilityRequests ?? [])],
+        authorizationDecision: worsePermission(left.permission, right.permission) === 'ask'
+            ? right.permission === 'ask'
+                ? (right.authorizationDecision ?? left.authorizationDecision)
+                : left.authorizationDecision
+            : (right.authorizationDecision ?? left.authorizationDecision),
     };
 }
 function askVerdict(params) {
     return { ...params, permission: 'ask' };
 }
-function allowVerdict(params) {
-    return { ...params, permission: 'allow' };
+function resolveShellPathTargets(pathArgs, context) {
+    if (!context.cwd) {
+        return [];
+    }
+    return pathArgs.map((target) => {
+        const resolved = (context.trustedCwd ? resolveTrustedPath(target, context.cwd, context.trustedCwd) : null) ??
+            resolveMutationTarget(target, context.cwd);
+        if (!resolved) {
+            const joined = path.isAbsolute(target) ? target : path.join(context.cwd, target);
+            return canonicalPath(joined);
+        }
+        return canonicalPath(resolved);
+    });
 }
-function withJudgeTrace(verdict, judgeTrace) {
-    if (!judgeTrace) {
-        return verdict;
+function withShellPolicyMetadata(input, existing = {}) {
+    if (existing.capabilityRequests?.length) {
+        return existing;
     }
-    return { ...verdict, judgeTrace };
+    return shellPolicyMetadata(input);
+}
+function allowVerdict(params) {
+    return { ...params, permission: 'allow' };
 }
 function extractPathArgs(tokens) {
     const redirects = extractRedirectTargets(tokens);
     const args = [...redirects];
     for (let index = 1; index < tokens.length; index += 1) {
         const token = tokens[index];
-        if (!token || token.startsWith('-') || token === '>' || token === '>>' || token === '<') {
+        if (!token || token.startsWith('-') || isRedirectOperator(token) || isFdDuplication(token)) {
             continue;
         }
         if (redirects.includes(token)) {
@@ -209,8 +173,15 @@ function extractPathArgs(tokens) {
 function isVariableOrOpaquePathToken(token) {
     return token.includes('$') || token.includes('`');
 }
-function isPureReadOnlySegment(segment) {
-    return PURE_READ_ONLY_KEYS.has(segment.key) || PURE_READ_ONLY_KEYS.has(segment.head);
+function pathContextFromSemantics(context, semantics) {
+    const cwd = semantics.gitWorkTree ?? semantics.effectiveCwd;
+    if (!cwd || cwd === context.cwd) {
+        return context;
+    }
+    return { ...context, cwd };
+}
+function isPureReadOnlySegment(segment, semantics) {
+    return isPureReadOnlySemantics(segment, semantics);
 }
 function updateChainState(command, state) {
     const segment = parseSegment(command);
@@ -233,10 +204,13 @@ function updateChainState(command, state) {
         trustedCwd: true,
     };
 }
-function tier0ExternalMatch(key, head, tokens) {
+function tier0ExternalMatch(key, head, tokens, signals = []) {
     if (TIER0_EXTERNAL_KEYS.has(key)) {
         return true;
     }
+    if (signals.includes('git.push')) {
+        return true;
+    }
     if (TIER0_EXTERNAL_HEADS.has(head)) {
         return true;
     }
@@ -248,9 +222,6 @@ function tier0ExternalMatch(key, head, tokens) {
             tokens.some((t) => t === '--push' || t.startsWith('--output=type=registry')))) {
         return true;
     }
-    if (head === 'git' && tokens[1] === 'push') {
-        return true;
-    }
     if (head === 'terraform' && tokens[1] === 'apply') {
         return true;
     }
@@ -304,6 +275,7 @@ function tier0HighStakesRm(tokens, context) {
         cwd: context.cwd,
         repoRoot: context.repoRoot,
         trustedCwd: context.trustedCwd,
+        trustedWorkspaceRoots: context.trustedWorkspaceRoots,
         sensitivePaths: context.sensitivePaths,
         protectedArtifactRoots: context.protectedArtifactRoots,
     });
@@ -336,7 +308,7 @@ function tier0HighStakesRm(tokens, context) {
             const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
                 resolveMutationTarget(target, context.cwd);
             if (resolved &&
-                isDestructiveHighStakesMutation(head, resolved, context.repoRoot, context.sensitivePaths, context.protectedArtifactRoots)) {
+                isDestructiveHighStakesMutation(head, resolved, context.repoRoot, context.sensitivePaths, context.protectedArtifactRoots, context.trustedWorkspaceRoots)) {
                 destructiveHighStakes = true;
                 break;
             }
@@ -354,6 +326,39 @@ function tier0HighStakesRm(tokens, context) {
     }
     return null;
 }
+function verdictFromOpacityPolicy(params) {
+    const { request, decision } = evaluateSegmentShellPolicy({
+        command: params.command,
+        segmentHead: params.segmentHead,
+        effect: params.effect,
+        location: params.location,
+        opacity: params.opacity,
+        pathArgs: params.pathArgs,
+        signals: params.signals,
+        context: params.context,
+    });
+    const base = {
+        location: params.location,
+        opacity: params.opacity,
+        effect: params.effect,
+        confidence: 'deterministic',
+        signals: [...params.signals, ...decision.signals],
+        capabilityRequests: [request],
+        authorizationDecision: decision,
+    };
+    if (policyDecisionRequiresAsk(decision)) {
+        return {
+            permission: 'ask',
+            reason: policyDecisionToLegacyReason(decision),
+            ...base,
+        };
+    }
+    return {
+        permission: 'allow',
+        reason: policyDecisionToLegacyReason(decision),
+        ...base,
+    };
+}
 async function evaluateSegment(command, context, depth) {
     const maxDepth = context.maxRecursionDepth ?? DEFAULT_MAX_DEPTH;
     if (depth > maxDepth) {
@@ -368,23 +373,15 @@ async function evaluateSegment(command, context, depth) {
     }
     const opacity = segmentOpacity(command);
     if (opacity === 'unparseable') {
-        if (context.unparseableShell === 'deny') {
-            return askVerdict({
-                location: 'unknown',
-                opacity: 'unparseable',
-                effect: 'unknown',
-                confidence: 'deterministic',
-                reason: 'unparseable_shell',
-                signals: ['unparseable_shell'],
-            });
-        }
-        return allowVerdict({
-            location: 'unknown',
+        return verdictFromOpacityPolicy({
+            command,
+            segmentHead: parseSegment(command).head,
             opacity: 'unparseable',
             effect: 'unknown',
-            confidence: 'deterministic',
-            reason: 'unparseable_shell',
+            location: 'unknown',
+            pathArgs: [],
             signals: ['unparseable_shell'],
+            context,
         });
     }
     const substitutionResult = await evaluateSubstitutions(command, context, depth);
@@ -394,13 +391,15 @@ async function evaluateSegment(command, context, depth) {
     const tokens = tokenizeShell(command);
     const { tokens: peeled, xargsStdinOpaque } = peelTransparentWrappers(tokens);
     if (xargsStdinOpaque || isBareInterpreter(tokens)) {
-        return askVerdict({
-            location: 'unknown',
+        return verdictFromOpacityPolicy({
+            command,
+            segmentHead: parseSegment(command).head,
             opacity: 'opaque',
             effect: 'unknown',
-            confidence: 'deterministic',
-            reason: 'opaque_execution',
+            location: 'unknown',
+            pathArgs: [],
             signals: ['opaque_execution'],
+            context,
         });
     }
     const segment = parseSegment(command);
@@ -429,13 +428,28 @@ async function evaluateSegment(command, context, depth) {
     if (recursiveScript) {
         const prescan = prescanInterpreterCode(recursiveScript);
         if (prescan && tier1RequiresAsk(prescan)) {
+            const { request, decision } = evaluateSegmentShellPolicy({
+                command: recursiveScript,
+                segmentHead: segment.head,
+                effect: 'unknown',
+                location: 'unknown',
+                opacity: 'recursive',
+                pathArgs: [],
+                signals: ['interpreter_secret_prescan', prescan.reason],
+                context,
+            });
+            const legacyReason = policyDecisionRequiresAsk(decision)
+                ? policyDecisionToLegacyReason(decision)
+                : 'interpreter_secret_prescan';
             return askVerdict({
                 location: 'unknown',
                 opacity: 'recursive',
                 effect: 'unknown',
                 confidence: 'deterministic',
-                reason: 'interpreter_secret_prescan',
-                signals: ['interpreter_secret_prescan'],
+                reason: legacyReason,
+                signals: ['interpreter_secret_prescan', prescan.reason, ...decision.signals],
+                capabilityRequests: [request],
+                authorizationDecision: decision,
             });
         }
         const innerVerdict = await evaluateSegment(recursiveScript, context, depth + 1);
@@ -480,8 +494,10 @@ async function evaluateSegment(command, context, depth) {
         }
         let innerVerdict = null;
         for (const recipe of resolution.recipes) {
-            const evaluated = await evaluateSegment(recipe, context, depth + 1);
-            innerVerdict = innerVerdict ? combineInternal(innerVerdict, evaluated) : evaluated;
+            for (const sub of splitTopLevelSegments(recipe)) {
+                const evaluated = await evaluateSegment(sub, context, depth + 1);
+                innerVerdict = innerVerdict ? combineInternal(innerVerdict, evaluated) : evaluated;
+            }
         }
         if (!innerVerdict) {
             return askVerdict({
@@ -499,38 +515,78 @@ async function evaluateSegment(command, context, depth) {
             signals: [...innerVerdict.signals, resolution.reason],
         };
     }
-    const egressClass = classifyEgressTool(segment.head, peeled);
+    const semantics = analyzeShellCommandSemantics(peeled, segment, context.cwd);
+    const pathContext = pathContextFromSemantics(context, semantics);
+    if (semantics.requiresAsk) {
+        const { request, decision } = evaluateSegmentShellPolicy({
+            command,
+            segmentHead: segment.head,
+            effect: 'local_mutation',
+            location: 'repo_local',
+            opacity: 'transparent',
+            pathArgs: semantics.pathTargets,
+            signals: semantics.requiresAsk.signals,
+            context: pathContext,
+        });
+        return askVerdict({
+            location: 'repo_local',
+            opacity: 'transparent',
+            effect: 'local_mutation',
+            confidence: 'deterministic',
+            reason: semantics.requiresAsk.reason,
+            signals: semantics.requiresAsk.signals,
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+        });
+    }
+    const egressClass = semantics.egressClass ?? classifyEgressTool(segment.head, peeled);
     if (egressClass === 'destructive') {
+        const { request, decision } = evaluateSegmentShellPolicy({
+            command,
+            segmentHead: segment.head,
+            effect: 'remote_mutation',
+            location: 'external',
+            opacity: 'transparent',
+            egressClass: 'destructive',
+            pathArgs: [],
+            signals: ['tier0_external', segment.head],
+            context,
+        });
         return askVerdict({
             location: 'external',
             opacity: 'transparent',
             effect: 'remote_mutation',
             confidence: 'deterministic',
             reason: 'tier0_external',
-            signals: ['tier0_external', segment.head],
+            signals: ['tier0_external', segment.head, ...decision.signals],
+            capabilityRequests: [request],
+            authorizationDecision: decision,
         });
     }
-    if (egressClass === 'read') {
-        return allowVerdict({
+    if (tier0ExternalMatch(semantics.normalizedKey ?? segment.key, segment.head, peeled, semantics.signals)) {
+        const tier0Key = semantics.normalizedKey ?? segment.key;
+        const { request, decision } = evaluateSegmentShellPolicy({
+            command,
+            segmentHead: segment.head,
+            effect: 'remote_mutation',
             location: 'external',
             opacity: 'transparent',
-            effect: 'read_only',
-            confidence: 'deterministic',
-            reason: 'egress_read',
-            signals: ['egress_read', segment.head],
+            pathArgs: [],
+            signals: ['tier0_external', tier0Key, ...semantics.signals],
+            context: pathContext,
         });
-    }
-    if (tier0ExternalMatch(segment.key, segment.head, peeled)) {
         return askVerdict({
             location: 'external',
             opacity: 'transparent',
             effect: 'remote_mutation',
             confidence: 'deterministic',
             reason: 'tier0_external',
-            signals: ['tier0_external', segment.key],
+            signals: ['tier0_external', tier0Key, ...decision.signals],
+            capabilityRequests: [request],
+            authorizationDecision: decision,
         });
     }
-    const rmVerdict = tier0HighStakesRm(peeled, context);
+    const rmVerdict = tier0HighStakesRm(peeled, pathContext);
     if (rmVerdict) {
         return rmVerdict;
     }
@@ -544,28 +600,29 @@ async function evaluateSegment(command, context, depth) {
             signals: ['belay_control_plane_command', segment.head],
         });
     }
-    let effect = 'unknown';
-    if (READ_ONLY_KEYS.has(segment.key) || READ_ONLY_KEYS.has(segment.head)) {
+    let effect = semantics.effect;
+    if (isReadOnlyLauncherInvocation(peeled)) {
         effect = 'read_only';
     }
-    else if (LOCAL_MUTATION_KEYS.has(segment.key) || LOCAL_MUTATION_KEYS.has(segment.head)) {
-        effect = 'local_mutation';
-    }
-    else if (LOCAL_ROUTINE_HEADS.has(segment.head)) {
-        effect = 'local_mutation';
-    }
-    const pathArgs = extractPathArgs(peeled);
-    if (extractRedirectTargets(peeled).length > 0 && effect === 'read_only') {
-        effect = 'local_mutation';
-    }
+    const pathArgs = semantics.pathTargets;
+    const policyPathArgs = [...new Set([...pathArgs, ...(semantics.scopeTargets ?? [])])];
     const pathAnalysis = analyzePathTargets({
-        targets: pathArgs,
-        cwd: context.cwd,
-        repoRoot: context.repoRoot,
-        trustedCwd: context.trustedCwd,
-        sensitivePaths: context.sensitivePaths,
-        protectedArtifactRoots: context.protectedArtifactRoots,
+        targets: policyPathArgs,
+        cwd: pathContext.cwd,
+        repoRoot: pathContext.repoRoot,
+        trustedCwd: pathContext.trustedCwd,
+        trustedWorkspaceRoots: pathContext.trustedWorkspaceRoots,
+        sensitivePaths: pathContext.sensitivePaths,
+        protectedArtifactRoots: pathContext.protectedArtifactRoots,
     });
+    // Path-less read/mutation in a trusted cwd: assume repo-local (e.g. git status, tsc --noEmit).
+    const effectiveLocation = policyPathArgs.length === 0 &&
+        pathContext.trustedCwd &&
+        pathContext.cwd &&
+        (effect === 'read_only' || effect === 'local_mutation') &&
+        pathAnalysis.location === 'unknown'
+        ? 'repo_local'
+        : pathAnalysis.location;
     if (!context.trustedCwd || !context.cwd) {
         if (opacity === 'opaque' || effect === 'unknown' || effect === 'local_mutation') {
             return askVerdict({
@@ -577,7 +634,7 @@ async function evaluateSegment(command, context, depth) {
                 signals: ['missing_trusted_cwd'],
             });
         }
-        if (effect === 'read_only' && !isPureReadOnlySegment(segment)) {
+        if (effect === 'read_only' && !isPureReadOnlySegment(segment, semantics)) {
             return askVerdict({
                 location: 'unknown',
                 opacity,
@@ -592,9 +649,9 @@ async function evaluateSegment(command, context, depth) {
         context.protectedArtifactRoots &&
         context.protectedArtifactRoots.length > 0) {
         for (const target of pathArgs) {
-            const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
-                resolveMutationTarget(target, context.cwd);
-            if (resolved && touchesProtectedRoot(resolved, context.protectedArtifactRoots)) {
+            const resolved = resolveTrustedPath(target, pathContext.cwd, pathContext.trustedCwd) ??
+                resolveMutationTarget(target, pathContext.cwd);
+            if (resolved && touchesProtectedRoot(resolved, pathContext.protectedArtifactRoots ?? [])) {
                 return askVerdict({
                     location: pathAnalysis.location,
                     opacity: 'transparent',
@@ -609,10 +666,10 @@ async function evaluateSegment(command, context, depth) {
     if (effect === 'local_mutation' || effect === 'unknown') {
         let destructiveHighStakes = false;
         for (const target of pathArgs) {
-            const resolved = resolveTrustedPath(target, context.cwd, context.trustedCwd) ??
-                resolveMutationTarget(target, context.cwd);
+            const resolved = resolveTrustedPath(target, pathContext.cwd, pathContext.trustedCwd) ??
+                resolveMutationTarget(target, pathContext.cwd);
             if (resolved &&
-                isDestructiveHighStakesMutation(segment.head, resolved, context.repoRoot, context.sensitivePaths, context.protectedArtifactRoots)) {
+                isDestructiveHighStakesMutation(segment.head, resolved, pathContext.repoRoot, pathContext.sensitivePaths, pathContext.protectedArtifactRoots, pathContext.trustedWorkspaceRoots)) {
                 destructiveHighStakes = true;
                 break;
             }
@@ -661,17 +718,43 @@ async function evaluateSegment(command, context, depth) {
             signals: ['unknown_location_mutation'],
         });
     }
+    const resolvedPathTargets = resolveShellPathTargets(policyPathArgs, pathContext);
+    const semanticSignals = semantics.signals;
+    const buildPolicyInput = (overrides) => ({
+        command: recursiveScript ?? command,
+        segmentHead: segment.head,
+        opacity,
+        egressClass: egressClass ?? undefined,
+        pathArgs: policyPathArgs,
+        resolvedPathTargets,
+        signals: [...semanticSignals, ...pathAnalysis.signals],
+        context: pathContext,
+        ...overrides,
+    });
     const outsideMutation = pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed';
     const mutationPrescan = (effect === 'local_mutation' || effect === 'unknown') && pathArgs.length > 0
         ? mutationPrescanRequiresAsk({
             targets: pathArgs,
-            cwd: context.cwd,
-            repoRoot: context.repoRoot,
-            trustedCwd: context.trustedCwd,
-            sensitivePaths: context.sensitivePaths,
+            cwd: pathContext.cwd,
+            repoRoot: pathContext.repoRoot,
+            trustedCwd: pathContext.trustedCwd,
+            trustedWorkspaceRoots: pathContext.trustedWorkspaceRoots,
+            sensitivePaths: pathContext.sensitivePaths,
         })
         : null;
     if (mutationPrescan) {
+        const { request, decision } = evaluateSegmentShellPolicy(buildPolicyInput({
+            effect: 'local_mutation',
+            location: pathAnalysis.location === 'unknown'
+                ? 'unknown'
+                : pathAnalysis.location === 'repo_outside' || pathAnalysis.location === 'mixed'
+                    ? pathAnalysis.location
+                    : 'repo_local',
+            signals: ['tier1_catastrophic', mutationPrescan.reason, ...pathAnalysis.signals],
+        }));
+        const legacyReason = policyDecisionRequiresAsk(decision)
+            ? policyDecisionToLegacyReason(decision, { outsideMutation, effect: 'local_mutation' })
+            : 'tier1_catastrophic';
         return askVerdict({
             location: pathAnalysis.location === 'unknown'
                 ? 'unknown'
@@ -681,24 +764,28 @@ async function evaluateSegment(command, context, depth) {
             opacity,
             effect: 'local_mutation',
             confidence: 'deterministic',
-            reason: 'tier1_catastrophic',
-            signals: ['tier1_catastrophic', mutationPrescan.reason],
+            reason: legacyReason,
+            signals: ['tier1_catastrophic', mutationPrescan.reason, ...decision.signals],
+            capabilityRequests: [request],
+            authorizationDecision: decision,
         });
     }
-    const needsTier1 = effect === 'unknown' ||
+    const needsPolicy = effect === 'unknown' ||
         TIER0_EXTERNAL_HEADS.has(segment.head) ||
         egressClass === 'ambiguous' ||
+        egressClass === 'read' ||
         (outsideMutation && effect !== 'read_only');
-    let tier1Trace;
-    if (needsTier1) {
-        const tier1Text = recursiveScript ?? command;
-        const tier1 = await context.judge.evaluate({
-            text: tier1Text,
-            context: { cwd: context.cwd, repoRoot: context.repoRoot },
-            innerCode: recursiveScript ?? undefined,
-        });
-        tier1Trace = context.judge.lastTrace;
-        if (tier1RequiresAsk(tier1)) {
+    let policyMetadata = {};
+    if (needsPolicy) {
+        const { request, decision } = evaluateSegmentShellPolicy(buildPolicyInput({
+            effect,
+            location: pathAnalysis.location,
+        }));
+        policyMetadata = {
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+        };
+        if (policyDecisionRequiresAsk(decision)) {
             return askVerdict({
                 location: pathAnalysis.location === 'unknown'
                     ? 'unknown'
@@ -706,72 +793,104 @@ async function evaluateSegment(command, context, depth) {
                         ? pathAnalysis.location
                         : 'repo_local',
                 opacity,
-                effect: !tier1.local_recoverable ? 'remote_mutation' : effect,
-                confidence: 'llm',
-                reason: 'tier1_catastrophic',
-                signals: ['tier1_catastrophic', tier1.reason],
-                judgeTrace: tier1Trace,
+                effect: decision.reason === 'external_effect' || decision.reason === 'network_connect'
+                    ? 'remote_mutation'
+                    : effect,
+                confidence: 'deterministic',
+                reason: policyDecisionToLegacyReason(decision, { outsideMutation, effect }),
+                signals: ['policy_required', ...decision.signals],
+                ...policyMetadata,
             });
         }
     }
     if (outsideMutation && effect !== 'read_only') {
-        return withJudgeTrace(allowVerdict({
+        const policyAllowsOutside = policyMetadata.authorizationDecision?.outcome === 'allow' &&
+            (policyMetadata.authorizationDecision.matchedRule === 'grant.exact' ||
+                policyMetadata.authorizationDecision.matchedRule === 'boundary.verified' ||
+                policyMetadata.authorizationDecision.matchedRule === 'builtin.trusted_workspace');
+        if (!policyAllowsOutside) {
+            const legacyReason = policyMetadata.authorizationDecision &&
+                policyDecisionRequiresAsk(policyMetadata.authorizationDecision)
+                ? policyDecisionToLegacyReason(policyMetadata.authorizationDecision, {
+                    outsideMutation,
+                    effect,
+                })
+                : 'outside_repo_mutation';
+            return askVerdict({
+                location: pathAnalysis.location,
+                opacity,
+                effect: 'local_mutation',
+                confidence: 'deterministic',
+                reason: legacyReason,
+                signals: ['outside_repo_mutation', ...pathAnalysis.signals],
+                ...policyMetadata,
+            });
+        }
+        return allowVerdict({
             location: pathAnalysis.location,
             opacity,
             effect: 'local_mutation',
-            confidence: tier1Trace ? 'llm' : 'deterministic',
+            confidence: 'deterministic',
             reason: 'repo_outside_local_mutation',
             signals: ['repo_outside_local_mutation', ...pathAnalysis.signals],
-        }), tier1Trace);
+            ...policyMetadata,
+        });
     }
-    if (pathAnalysis.location === 'repo_local' &&
+    if (effectiveLocation === 'repo_local' &&
         (effect === 'read_only' || effect === 'local_mutation') &&
         opacity !== 'opaque') {
-        return withJudgeTrace(allowVerdict({
+        return allowVerdict({
             location: 'repo_local',
             opacity,
             effect,
             confidence: 'assumed_repo_local',
             reason: effect === 'read_only' ? 'read_only' : 'repo_local_mutation',
             signals: effect === 'read_only' ? ['read_only'] : ['repo_local_mutation'],
-        }), tier1Trace);
+            ...withShellPolicyMetadata(buildPolicyInput({ effect, location: 'repo_local' }), policyMetadata),
+        });
     }
     if (effect === 'read_only') {
-        const readOnlyLocation = context.trustedCwd && context.cwd
-            ? pathAnalysis.location === 'unknown'
+        const readOnlyLocation = pathContext.trustedCwd && pathContext.cwd
+            ? effectiveLocation === 'unknown'
                 ? 'repo_local'
-                : pathAnalysis.location
+                : effectiveLocation
             : 'unknown';
-        return withJudgeTrace(allowVerdict({
+        return allowVerdict({
             location: readOnlyLocation,
             opacity,
             effect: 'read_only',
             confidence: context.trustedCwd && context.cwd ? 'assumed_repo_local' : 'deterministic',
             reason: 'read_only',
             signals: ['read_only'],
-        }), tier1Trace);
+            ...withShellPolicyMetadata(buildPolicyInput({ effect: 'read_only', location: readOnlyLocation }), policyMetadata),
+        });
     }
     if (allowOverride) {
-        return withJudgeTrace(allowFromCustomOverride(opacity), tier1Trace);
+        return allowFromCustomOverride(opacity);
     }
     if (context.unknownLocalEffect === 'allow_flagged') {
-        return withJudgeTrace(allowVerdict({
-            location: pathAnalysis.location === 'unknown' ? 'repo_local' : pathAnalysis.location,
+        return allowVerdict({
+            location: effectiveLocation === 'unknown' ? 'repo_local' : effectiveLocation,
             opacity,
             effect: 'unknown',
             confidence: 'assumed_repo_local',
             reason: 'unknown_local_effect',
             signals: ['unknown_local_effect'],
-        }), tier1Trace);
+            ...withShellPolicyMetadata(buildPolicyInput({
+                effect: 'unknown',
+                location: effectiveLocation === 'unknown' ? 'repo_local' : effectiveLocation,
+            }), policyMetadata),
+        });
     }
-    return withJudgeTrace(askVerdict({
-        location: pathAnalysis.location,
+    return askVerdict({
+        location: effectiveLocation,
         opacity,
         effect,
         confidence: 'deterministic',
         reason: 'unknown_local_effect',
         signals: ['unknown_local_effect'],
-    }), tier1Trace);
+        ...withShellPolicyMetadata(buildPolicyInput({ effect, location: pathAnalysis.location }), policyMetadata),
+    });
 }
 function toVerdictResult(internal, command, context, fingerprintCwd = context.cwd) {
     const commandRedacted = redactCommand(command);
@@ -787,6 +906,8 @@ function toVerdictResult(internal, command, context, fingerprintCwd = context.cw
         fingerprint: verdictFingerprint(relative, commandRedacted),
         signals: internal.signals,
         judgeTrace: internal.judgeTrace,
+        capabilityRequests: internal.capabilityRequests,
+        authorizationDecision: internal.authorizationDecision,
     };
 }
 export async function verdict(command, context) {