@guilz-dev/belay 0.2.0 → 0.4.0

package/dist/core/audit-replay-context.js

@@ -0,0 +1,88 @@
+import { createHash } from 'node:crypto';
+export function hashReplayPayload(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export function buildAuditActionSnapshot(kind, result, replayAction) {
+    if (!replayAction?.cwd) {
+        return undefined;
+    }
+    const replayKind = replayAction.kind;
+    const resolvedKind = replayKind === 'shell' || replayKind === 'tool' || replayKind === 'subagent' ? replayKind : kind;
+    const normalizedAction = result.normalizedCommand ?? replayAction.command ?? result.summary ?? '';
+    if (!normalizedAction.trim()) {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        kind: resolvedKind,
+        cwd: replayAction.cwd,
+        normalizedAction,
+        ...(replayAction.toolName ? { toolName: replayAction.toolName } : {}),
+        ...(replayAction.payload ? { payloadHash: hashReplayPayload(replayAction.payload) } : {}),
+    };
+}
+export function parseAuditActionSnapshot(record) {
+    const raw = record.actionSnapshot;
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const snapshot = raw;
+    if (snapshot.schemaVersion !== 1) {
+        return null;
+    }
+    if (typeof snapshot.cwd !== 'string' || !snapshot.cwd.trim()) {
+        return null;
+    }
+    const kind = snapshot.kind;
+    if (kind !== 'shell' && kind !== 'tool' && kind !== 'subagent') {
+        return null;
+    }
+    if (typeof snapshot.normalizedAction !== 'string' || !snapshot.normalizedAction.trim()) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        kind,
+        cwd: snapshot.cwd,
+        normalizedAction: snapshot.normalizedAction,
+        ...(typeof snapshot.toolName === 'string' ? { toolName: snapshot.toolName } : {}),
+        ...(typeof snapshot.payloadHash === 'string' ? { payloadHash: snapshot.payloadHash } : {}),
+    };
+}
+export function buildAuditReplayContext(kind, result, replayAction) {
+    if (!replayAction?.cwd) {
+        return undefined;
+    }
+    const replayKind = replayAction.kind;
+    const resolvedKind = replayKind === 'shell' || replayKind === 'tool' || replayKind === 'subagent' ? replayKind : kind;
+    return {
+        cwd: replayAction.cwd,
+        kind: resolvedKind,
+        command: replayAction.command ?? result.normalizedCommand ?? result.summary,
+        ...(replayAction.toolName ? { toolName: replayAction.toolName } : {}),
+        ...(replayAction.payload ? { payload: replayAction.payload } : {}),
+    };
+}
+export function parseAuditReplayContext(record) {
+    const raw = record.replayContext;
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const ctx = raw;
+    if (typeof ctx.cwd !== 'string' || !ctx.cwd.trim()) {
+        return null;
+    }
+    const kind = ctx.kind;
+    if (kind !== 'shell' && kind !== 'tool' && kind !== 'subagent') {
+        return null;
+    }
+    return {
+        cwd: ctx.cwd,
+        kind,
+        ...(typeof ctx.command === 'string' ? { command: ctx.command } : {}),
+        ...(typeof ctx.toolName === 'string' ? { toolName: ctx.toolName } : {}),
+        ...(ctx.payload && typeof ctx.payload === 'object' && !Array.isArray(ctx.payload)
+            ? { payload: ctx.payload }
+            : {}),
+    };
+}

package/dist/core/audit-types.d.ts

@@ -1,5 +1,7 @@
+import type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
 import type { Assessment } from './types.js';
-export declare const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export type { AuditActionSnapshot, AuditReplayContext } from './audit-replay-context.js';
+export declare const AUDIT_METRICS_SCHEMA_VERSION = 3;
 export declare const GATE_EVENTS: Set<string>;
 export interface AuditRecord {
     timestamp?: string;
@@ -11,6 +13,7 @@ export interface AuditRecord {
     summary?: string;
     approvalId?: string;
     wouldBlock?: boolean;
+    judgeFallbackReason?: string;
     permission?: string;
     mode?: string;
     assessment?: Assessment;
@@ -21,6 +24,8 @@ export interface AuditRecord {
     transactionalCategories?: string[];
     transactionalChangeCount?: number;
     transactionalSkipReason?: string;
+    replayContext?: AuditReplayContext;
+    actionSnapshot?: AuditActionSnapshot;
     [key: string]: unknown;
 }
 export interface AuditFilter {
@@ -63,3 +68,21 @@ export interface NoisyRuleCandidate {
     approvedCount: number;
     approvalRate: number;
 }
+export interface ReasonApprovalRatio {
+    reason: string;
+    wouldBlockCount: number;
+    approvedAfterDenyCount: number;
+    approvalRate: number;
+}
+export interface RepeatedFingerprintAsk {
+    fingerprint: string;
+    summary: string;
+    reason: string;
+    askCount: number;
+}
+export interface AvailabilityAskCounts {
+    total: number;
+    missingTrustedCwd: number;
+    judgeTimeout: number;
+    judgeFallback: number;
+}

package/dist/core/audit-types.js

@@ -1,2 +1,2 @@
-export const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export const AUDIT_METRICS_SCHEMA_VERSION = 3;
 export const GATE_EVENTS = new Set(['beforeShellExecution', 'preToolUse', 'subagentGate']);

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

@@ -1,5 +1,6 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
-export { collectOutsideRepoPaths } from './paths.js';
-export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce } from './reasons.js';
-export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, } from './types.js';
+export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
+export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';
+export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile, } from './types.js';

package/dist/core/capability/index.js

@@ -1,4 +1,5 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
-export { collectOutsideRepoPaths } from './paths.js';
-export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce } from './reasons.js';
+export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
+export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';

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

@@ -1 +1,2 @@
-export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string): string[];
+export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];
+export declare function collectOutsideRepoPathsFromToolPayload(payload: Record<string, unknown>, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];

package/dist/core/capability/paths.js

@@ -1,20 +1,88 @@
-import { relativeWithinRepo, resolveMutationTarget } from '../path-utils.js';
+import path from 'node:path';
+import { resolveMutationTarget, resolveWorkspaceRootMatch } from '../path-utils.js';
 import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
-export function collectOutsideRepoPaths(command, cwd, repoRoot) {
+function applyPatchTargets(patch) {
+    const targets = [];
+    for (const line of patch.split('\n')) {
+        const match = line.match(/^\*\*\* (?:Add|Delete|Update) File: (.+)$/);
+        if (match?.[1]) {
+            targets.push(match[1]);
+            continue;
+        }
+        const moveMatch = line.match(/^\*\*\* Move to: (.+)$/);
+        if (moveMatch?.[1]) {
+            targets.push(moveMatch[1]);
+        }
+    }
+    return targets;
+}
+function extractToolFilePath(payload) {
+    const toolInput = payload.tool_input;
+    if (!toolInput || typeof toolInput !== 'object') {
+        return null;
+    }
+    const input = toolInput;
+    for (const key of ['path', 'file_path', 'target_file', 'filePath']) {
+        if (typeof input[key] === 'string') {
+            return input[key];
+        }
+    }
+    return null;
+}
+function extractToolPatch(payload) {
+    const toolInput = payload.tool_input;
+    if (!toolInput || typeof toolInput !== 'object') {
+        return null;
+    }
+    const input = toolInput;
+    for (const key of ['patch', 'input', 'text']) {
+        if (typeof input[key] === 'string' && input[key].trim()) {
+            return input[key];
+        }
+    }
+    return null;
+}
+function addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots = []) {
+    const resolved = resolveMutationTarget(token, cwd);
+    if (resolved && resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
+        paths.add(resolved);
+    }
+}
+export function collectOutsideRepoPaths(command, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const tokens = tokenizeShell(command);
     const redirects = extractRedirectTargets(tokens);
     const paths = new Set();
     for (const token of tokens.slice(1)) {
-        const resolved = resolveMutationTarget(token, cwd);
-        if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
-            paths.add(resolved);
-        }
+        addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots);
     }
     for (const redirect of redirects) {
-        const resolved = resolveMutationTarget(redirect, cwd);
-        if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
+        addOutsideRepoPath(paths, redirect, cwd, repoRoot, trustedWorkspaceRoots);
+    }
+    return [...paths];
+}
+export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot, trustedWorkspaceRoots = []) {
+    const toolKind = String(payload.tool_name ?? '')
+        .trim()
+        .toLowerCase();
+    const paths = new Set();
+    const filePath = extractToolFilePath(payload);
+    if (filePath) {
+        const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+        if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
             paths.add(resolved);
         }
+        return [...paths];
+    }
+    if (toolKind === 'apply_patch' || toolKind === 'applypatch') {
+        const patch = extractToolPatch(payload);
+        if (patch) {
+            for (const target of applyPatchTargets(patch)) {
+                const resolved = path.isAbsolute(target) ? target : path.resolve(cwd, target);
+                if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
+                    paths.add(resolved);
+                }
+            }
+        }
     }
     return [...paths];
 }

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

@@ -1,2 +1,5 @@
 export declare const FS_SCOPE_REASONS: Set<string>;
+export declare const JUDGE_CLOUD_CONSENT_REASON: "judge_cloud_consent";
+export declare const CAPABILITY_APPROVAL_REASONS: Set<string>;
 export declare function shouldSkipBrokerApprovedOnce(brokerActive: boolean, reason: string): boolean;
+export declare function shouldSkipBrokerApprovedRecord(brokerActive: boolean, approvalReason: string | undefined): boolean;

package/dist/core/capability/reasons.js

@@ -1,4 +1,12 @@
 export const FS_SCOPE_REASONS = new Set(['outside_repo_mutation', 'outside_repo_redirect']);
+export const JUDGE_CLOUD_CONSENT_REASON = 'judge_cloud_consent';
+export const CAPABILITY_APPROVAL_REASONS = new Set([
+    ...FS_SCOPE_REASONS,
+    JUDGE_CLOUD_CONSENT_REASON,
+]);
 export function shouldSkipBrokerApprovedOnce(brokerActive, reason) {
     return brokerActive && FS_SCOPE_REASONS.has(reason);
 }
+export function shouldSkipBrokerApprovedRecord(brokerActive, approvalReason) {
+    return brokerActive && approvalReason !== undefined && FS_SCOPE_REASONS.has(approvalReason);
+}

package/dist/core/capability/trusted-workspace-roots.d.ts

@@ -0,0 +1,25 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile } from './types.js';
+export declare function trustedWorkspaceRootsPath(config: BelayConfigV3, repoLocalStateDir: string): string;
+export declare function loadTrustedWorkspaceRoots(filePath: string): Promise<TrustedWorkspaceRootsFile>;
+export declare function loadTrustedWorkspaceRootsSync(filePath: string): TrustedWorkspaceRootsFile;
+export declare function saveTrustedWorkspaceRoots(filePath: string, state: TrustedWorkspaceRootsFile): Promise<void>;
+export declare function normalizeTrustedWorkspaceRootPath(targetPath: string): string;
+export interface TrustedWorkspaceRootValidationParams {
+    candidatePath: string;
+    repoRoot: string;
+    controlPlaneDir?: string | null;
+    protectedRoots?: string[];
+    requireExistingDirectory?: boolean;
+    requireNonGit?: boolean;
+}
+export interface TrustedWorkspaceRootValidationResult {
+    ok: boolean;
+    normalizedPath: string;
+    reason?: 'not_directory' | 'broad_root' | 'high_stakes' | 'inside_repo' | 'inside_git_repo' | 'control_plane_overlap' | 'protected_root_overlap';
+}
+export declare function isBroadTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function isHighStakesTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function validateTrustedWorkspaceRootCandidate(params: TrustedWorkspaceRootValidationParams): TrustedWorkspaceRootValidationResult;
+export declare function isPathWithinTrustedWorkspaceRoots(absolutePath: string, roots: TrustedWorkspaceRootsFile): boolean;
+export declare function addTrustedWorkspaceRoot(roots: TrustedWorkspaceRootsFile, entry: TrustedWorkspaceRootEntry): TrustedWorkspaceRootsFile;

package/dist/core/capability/trusted-workspace-roots.js

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+import { canonicalPath, containingGitRoot, pathWithinRoot, resolveWorkspaceRootMatch, } from '../path-utils.js';
+export function trustedWorkspaceRootsPath(config, repoLocalStateDir) {
+    return path.join(belayStateDir(config, repoLocalStateDir), 'trusted-workspace-roots.json');
+}
+export async function loadTrustedWorkspaceRoots(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(await readFile(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export function loadTrustedWorkspaceRootsSync(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export async function saveTrustedWorkspaceRoots(filePath, state) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function normalizeTrustedWorkspaceRootPath(targetPath) {
+    return canonicalPath(targetPath);
+}
+function sanitizeTrustedWorkspaceRootEntries(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return [];
+        }
+        const record = entry;
+        if (typeof record.path !== 'string' || !record.path.trim()) {
+            return [];
+        }
+        const approvedAt = typeof record.approvedAt === 'string' ? record.approvedAt : new Date(0).toISOString();
+        const approvalId = typeof record.approvalId === 'string' ? record.approvalId : 'unknown';
+        const source = record.source === 'approval' ? 'approval' : undefined;
+        return [
+            {
+                path: path.resolve(record.path),
+                approvedAt,
+                approvalId,
+                ...(source ? { source } : {}),
+            },
+        ];
+    });
+}
+const SYSTEM_HIGH_STAKES_PREFIXES = [
+    '/etc',
+    '/private/etc',
+    '/bin',
+    '/sbin',
+    '/usr',
+    '/opt',
+    '/System',
+    '/Library',
+];
+const HOME_HIGH_STAKES_SEGMENTS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker', '.config'];
+function isDirectoryPath(targetPath) {
+    try {
+        return statSync(targetPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isBroadTrustedWorkspaceRoot(targetPath) {
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    const root = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (root === normalizeTrustedWorkspaceRootPath(path.parse(root).root)) {
+        return true;
+    }
+    if (home && normalizeTrustedWorkspaceRootPath(home) === root) {
+        return true;
+    }
+    return false;
+}
+export function isHighStakesTrustedWorkspaceRoot(targetPath) {
+    const normalized = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (SYSTEM_HIGH_STAKES_PREFIXES.some((prefix) => normalized === normalizeTrustedWorkspaceRootPath(prefix) ||
+        pathWithinRoot(normalizeTrustedWorkspaceRootPath(prefix), normalized))) {
+        return true;
+    }
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (!home) {
+        return false;
+    }
+    const homeRoot = normalizeTrustedWorkspaceRootPath(home);
+    if (!pathWithinRoot(homeRoot, normalized)) {
+        return false;
+    }
+    return HOME_HIGH_STAKES_SEGMENTS.some((segment) => pathWithinRoot(path.join(homeRoot, segment), normalized));
+}
+export function validateTrustedWorkspaceRootCandidate(params) {
+    const normalizedPath = normalizeTrustedWorkspaceRootPath(params.candidatePath);
+    if (params.requireExistingDirectory !== false && !isDirectoryPath(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'not_directory' };
+    }
+    if (isBroadTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'broad_root' };
+    }
+    if (isHighStakesTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'high_stakes' };
+    }
+    if (resolveWorkspaceRootMatch(params.repoRoot, [], normalizedPath) !== null) {
+        return { ok: false, normalizedPath, reason: 'inside_repo' };
+    }
+    if (params.requireNonGit !== false && containingGitRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'inside_git_repo' };
+    }
+    const normalizedControlPlane = params.controlPlaneDir?.trim()
+        ? normalizeTrustedWorkspaceRootPath(params.controlPlaneDir)
+        : null;
+    if (normalizedControlPlane &&
+        (pathWithinRoot(normalizedControlPlane, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedControlPlane))) {
+        return { ok: false, normalizedPath, reason: 'control_plane_overlap' };
+    }
+    if ((params.protectedRoots ?? []).some((root) => {
+        const normalizedRoot = normalizeTrustedWorkspaceRootPath(root);
+        return (pathWithinRoot(normalizedRoot, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedRoot));
+    })) {
+        return { ok: false, normalizedPath, reason: 'protected_root_overlap' };
+    }
+    return { ok: true, normalizedPath };
+}
+export function isPathWithinTrustedWorkspaceRoots(absolutePath, roots) {
+    const resolved = normalizeTrustedWorkspaceRootPath(absolutePath);
+    return roots.roots.some((entry) => {
+        const root = path.resolve(entry.path);
+        return resolved === root || pathWithinRoot(root, resolved);
+    });
+}
+export function addTrustedWorkspaceRoot(roots, entry) {
+    const normalized = normalizeTrustedWorkspaceRootPath(entry.path);
+    const filtered = roots.roots.filter((existing) => normalizeTrustedWorkspaceRootPath(existing.path) !== normalized);
+    return {
+        version: 1,
+        roots: [...filtered, { ...entry, path: normalized }],
+    };
+}

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

@@ -1,4 +1,4 @@
-export type CapabilityApprovalScope = 'once' | 'path';
+export type CapabilityApprovalScope = 'once' | 'path' | 'workspace-root';
 export interface FsScopeAllowlistEntry {
     path: string;
     approvedAt: string;
@@ -8,3 +8,13 @@ export interface FsScopeAllowlistFile {
     version: 1;
     paths: FsScopeAllowlistEntry[];
 }
+export interface TrustedWorkspaceRootEntry {
+    path: string;
+    approvedAt: string;
+    approvalId: string;
+    source?: 'approval';
+}
+export interface TrustedWorkspaceRootsFile {
+    version: 1;
+    roots: TrustedWorkspaceRootEntry[];
+}

package/dist/core/capability-approval.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityApprovalScope } from './capability/types.js';
-import type { BelayConfigV3 } from './config.js';
+import { type BelayConfigV3 } from './config.js';
 import type { ApprovalStateFile } from './types.js';
 export interface CapabilityApprovalStore {
     loadPending: () => Promise<{
@@ -13,6 +13,7 @@ export interface CapabilityApprovalStore {
     writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     allowlistPath: string;
+    trustedRootsPath: string;
 }
 export declare function recordCapabilityApproval(params: {
     approvalId: string;

package/dist/core/capability-approval.js

@@ -1,11 +1,13 @@
 import { recordApproval } from './approval-service.js';
 import { addPathToAllowlist, loadFsScopeAllowlist, normalizeAllowlistPath, saveFsScopeAllowlist, } from './capability/allowlist.js';
 import { FS_SCOPE_REASONS } from './capability/reasons.js';
+import { addTrustedWorkspaceRoot, loadTrustedWorkspaceRoots, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, validateTrustedWorkspaceRootCandidate, } from './capability/trusted-workspace-roots.js';
+import { resolveControlPlaneDir } from './config.js';
 export async function recordCapabilityApproval(params) {
     const pending = await params.store.loadPending();
     const match = pending.state.approvals.find((approval) => approval.approvalId === params.approvalId);
     if (params.scope === 'path') {
-        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+        if (!match || match.kind !== 'shell' || !FS_SCOPE_REASONS.has(match.reason)) {
             return {
                 ok: false,
                 message: 'Path scope approvals apply only to pending outside-repo shell actions (outside_repo_mutation / outside_repo_redirect).',
@@ -18,6 +20,85 @@ export async function recordCapabilityApproval(params) {
             };
         }
     }
+    if (params.scope === 'workspace-root') {
+        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+            return {
+                ok: false,
+                message: 'workspace-root scope approvals apply only to pending outside-repo actions (outside_repo_mutation / outside_repo_redirect).',
+            };
+        }
+        if (!params.scopePath?.trim()) {
+            return {
+                ok: false,
+                message: 'approve --scope workspace-root requires --path <absolute-directory-path>.',
+            };
+        }
+        if (!match.scopeHint || match.scopeHint.scope !== 'workspace-root') {
+            return {
+                ok: false,
+                message: 'workspace-root approval requires a pending scope hint. Re-run the original blocked action to mint a scoped approval.',
+            };
+        }
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const normalizedHint = normalizeTrustedWorkspaceRootPath(match.scopeHint.path);
+        if (normalizedPath !== normalizedHint) {
+            return {
+                ok: false,
+                message: `workspace-root approval path must exactly match the suggested path: ${normalizedHint}`,
+            };
+        }
+        const validation = validateTrustedWorkspaceRootCandidate({
+            candidatePath: normalizedPath,
+            repoRoot: match.repoRoot,
+            controlPlaneDir: params.config.controlPlane.enabled
+                ? resolveControlPlaneDir(params.config)
+                : undefined,
+            requireExistingDirectory: true,
+            requireNonGit: true,
+        });
+        if (!validation.ok) {
+            if (validation.reason === 'not_directory') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval requires an existing directory path.',
+                };
+            }
+            if (validation.reason === 'broad_root') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: broad roots (/, drive root, HOME) are not allowed.',
+                };
+            }
+            if (validation.reason === 'high_stakes') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: high-stakes directories cannot be trusted roots.',
+                };
+            }
+            if (validation.reason === 'inside_repo') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: the path is already inside the repository root.',
+                };
+            }
+            if (validation.reason === 'inside_git_repo') {
+                return {
+                    ok: false,
+                    message: `workspace-root approval rejected: ${normalizedPath} is under a git repository.`,
+                };
+            }
+            if (validation.reason === 'control_plane_overlap') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: control plane paths cannot be trusted roots.',
+                };
+            }
+            return {
+                ok: false,
+                message: 'workspace-root approval rejected by trusted-root policy.',
+            };
+        }
+    }
     const result = await recordApproval({
         approvalId: params.approvalId,
         config: params.config,
@@ -25,9 +106,26 @@ export async function recordCapabilityApproval(params) {
         requireSignedToken: params.requireSignedToken ?? false,
         store: params.store,
     });
-    if (!result.ok || params.scope !== 'path' || !params.scopePath?.trim()) {
+    if (!result.ok ||
+        (params.scope !== 'path' && params.scope !== 'workspace-root') ||
+        !params.scopePath?.trim()) {
         return { ok: result.ok, message: result.message };
     }
+    if (params.scope === 'workspace-root') {
+        const trustedRoots = await loadTrustedWorkspaceRoots(params.store.trustedRootsPath);
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const updated = addTrustedWorkspaceRoot(trustedRoots, {
+            path: normalizedPath,
+            approvedAt: new Date().toISOString(),
+            approvalId: params.approvalId,
+            source: 'approval',
+        });
+        await saveTrustedWorkspaceRoots(params.store.trustedRootsPath, updated);
+        return {
+            ok: true,
+            message: `${result.message} Trusted workspace root ${normalizedPath} added.`,
+        };
+    }
     const allowlist = await loadFsScopeAllowlist(params.store.allowlistPath);
     const normalizedPath = normalizeAllowlistPath(params.scopePath.trim());
     const updated = addPathToAllowlist(allowlist, {

package/dist/core/classify-subagent.js

@@ -1,4 +1,5 @@
 import { canonicalStringify, subagentFingerprint } from './fingerprint.js';
+import { subagentFingerprintSource } from './replay-scrub.js';
 import { scrubValue } from './scrub.js';
 const EXTERNAL_TERMS = ['deploy', 'production', 'publish', 'release', 'ship', 'notify', 'email'];
 function extractSubagentText(payload, options) {
@@ -22,26 +23,7 @@ function extractSubagentText(payload, options) {
     return canonicalStringify(scrubValue(payload, options.scrubOptions));
 }
 function fingerprintSource(payload, options) {
-    const toolInput = payload.tool_input;
-    if (toolInput && typeof toolInput === 'object') {
-        const input = toolInput;
-        return scrubValue({
-            description: input.description ?? '',
-            prompt: input.prompt ?? '',
-        }, options.scrubOptions);
-    }
-    const task = payload.task;
-    if (typeof task === 'string') {
-        return scrubValue({ task }, options.scrubOptions);
-    }
-    if (task && typeof task === 'object') {
-        const taskObj = task;
-        return scrubValue({
-            description: taskObj.description ?? '',
-            prompt: taskObj.prompt ?? '',
-        }, options.scrubOptions);
-    }
-    return scrubValue(payload, options.scrubOptions);
+    return subagentFingerprintSource(payload, options.scrubOptions ?? {});
 }
 export function classifySubagent(payload, repoRoot, options = {}) {
     const kind = payload.tool_name === 'Task' ? 'Task' : String(payload.subagent_type ?? 'generalPurpose');