fullcourtdefense-cli 1.7.22 → 1.7.23

package/dist/commands/deterministicGuard.d.ts

@@ -1,11 +1,30 @@
 export type DeterministicDirection = 'request' | 'response';
+export type DeterministicCategory = 'sensitive_file' | 'metadata_ssrf' | 'destructive_command' | 'destructive_sql' | 'infra_destroy' | 'reverse_shell' | 'secret_exfiltration';
 export interface DeterministicFinding {
     blocked: true;
     ruleId: string;
-    category: 'sensitive_file' | 'metadata_ssrf' | 'destructive_command' | 'destructive_sql' | 'infra_destroy' | 'reverse_shell' | 'secret_exfiltration';
+    category: DeterministicCategory;
+    categoryId: string;
+    itemId: string;
+    source: 'builtin' | 'custom';
     reason: string;
     evidence: string;
+    explanation?: string;
+    policyHash?: string;
 }
-export declare function scanDeterministicToolCall(toolName: string, toolArgs: Record<string, unknown>): DeterministicFinding | undefined;
-export declare function scanDeterministicTextResponse(text: string): DeterministicFinding | undefined;
-export declare function scanDeterministicPrompt(text: string): DeterministicFinding | undefined;
+export interface LocalSafetyCustomBlock {
+    id: string;
+    categoryId: string;
+    pattern: string;
+    explanation?: string;
+}
+export interface LocalSafetyScanOptions {
+    disabledBuiltInItemIds?: string[];
+    customBlocks?: LocalSafetyCustomBlock[];
+    policyHash?: string;
+    cwd?: string;
+    inspectScripts?: boolean;
+}
+export declare function scanDeterministicToolCall(toolName: string, toolArgs: Record<string, unknown>, options?: LocalSafetyScanOptions): DeterministicFinding | undefined;
+export declare function scanDeterministicTextResponse(text: string, options?: LocalSafetyScanOptions): DeterministicFinding | undefined;
+export declare function scanDeterministicPrompt(text: string, options?: LocalSafetyScanOptions): DeterministicFinding | undefined;

package/dist/commands/deterministicGuard.js

@@ -1,27 +1,62 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanDeterministicToolCall = scanDeterministicToolCall;
 exports.scanDeterministicTextResponse = scanDeterministicTextResponse;
 exports.scanDeterministicPrompt = scanDeterministicPrompt;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const SECRET_PATTERNS = [
-    { label: 'private key material', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/i },
-    { label: 'AWS access key', re: /\bAKIA[0-9A-Z]{16}\b/ },
-    { label: 'GitHub token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/ },
-    { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ },
-    { label: 'Anthropic API key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
-    { label: 'OpenAI project key', re: /\bsk-proj-[A-Za-z0-9_-]{20,}\b/ },
-    { label: 'OpenAI API key', re: /\bsk-[A-Za-z0-9_-]{32,}\b/ },
-    { label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/ },
-    { label: 'Stripe live key', re: /\b[rs]k_live_[0-9a-zA-Z]{24,}\b/ },
-    { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
-    { label: 'HuggingFace token', re: /\bhf_[A-Za-z0-9]{30,}\b/ },
-    { label: 'database URL with password', re: /\b(?:postgres(?:ql)?|mongodb(?:\+srv)?|mysql):\/\/[^/\s'":]+:[^@\s'"]+@/i },
+    { itemId: 'private_key_material', label: 'private key material', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/i },
+    { itemId: 'aws_access_key', label: 'AWS access key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { itemId: 'github_token', label: 'GitHub token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/ },
+    { itemId: 'github_token', label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ },
+    { itemId: 'anthropic_key', label: 'Anthropic API key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+    { itemId: 'openai_key', label: 'OpenAI project key', re: /\bsk-proj-[A-Za-z0-9_-]{20,}\b/ },
+    { itemId: 'openai_key', label: 'OpenAI API key', re: /\bsk-[A-Za-z0-9_-]{32,}\b/ },
+    { itemId: 'slack_token', label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/ },
+    { itemId: 'stripe_live_key', label: 'Stripe live key', re: /\b[rs]k_live_[0-9a-zA-Z]{24,}\b/ },
+    { itemId: 'google_api_key', label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { itemId: 'huggingface_token', label: 'HuggingFace token', re: /\bhf_[A-Za-z0-9]{30,}\b/ },
+    { itemId: 'database_url_password', label: 'database URL with password', re: /\b(?:postgres(?:ql)?|mongodb(?:\+srv)?|mysql):\/\/[^/\s'":]+:[^@\s'"]+@/i },
 ];
 const METADATA_ENDPOINTS = [
-    '169.254.169.254',
-    'metadata.google.internal',
-    'metadata.azure.com',
-    '100.100.100.200',
+    { itemId: 'aws_gcp_metadata_ip', value: '169.254.169.254', label: 'cloud metadata endpoint' },
+    { itemId: 'gcp_metadata_host', value: 'metadata.google.internal', label: 'GCP metadata endpoint' },
+    { itemId: 'azure_metadata_host', value: 'metadata.azure.com', label: 'Azure metadata endpoint' },
+    { itemId: 'alibaba_metadata_ip', value: '100.100.100.200', label: 'Alibaba cloud metadata endpoint' },
 ];
 const OUTBOUND_TOOL_HINT = /(?:http|fetch|request|curl|wget|webhook|upload|send|email|mail|slack|discord|teams|post|put|publish|notify)/i;
 const COMMAND_TOOL_HINT = /(?:shell|bash|command|cmd|powershell|terminal|exec|subprocess|run|script)/i;
@@ -46,6 +81,11 @@ const SQL_KEYS = new Set([
     'toolArgs.query',
     'toolArgs.sql',
 ]);
+const DEFAULT_DISABLED_BUILT_INS = new Set([
+    'git_clean_force',
+    'generic_kubectl_delete',
+    'truncate_table',
+]);
 function evidence(value) {
     const compact = value.replace(/\s+/g, ' ').trim();
     return compact.length > 180 ? `${compact.slice(0, 180)}...` : compact;
@@ -96,41 +136,84 @@ function collectStrings(value, keyPath = 'args', out = [], depth = 0) {
     }
     return out;
 }
+function disabled(options) {
+    return new Set(options?.disabledBuiltInItemIds || Array.from(DEFAULT_DISABLED_BUILT_INS));
+}
+function isEnabled(itemId, options) {
+    return !disabled(options).has(itemId);
+}
+function builtIn(itemId, categoryId, category, ruleId, reason, findingEvidence, explanation, options) {
+    if (!isEnabled(itemId, options))
+        return undefined;
+    return {
+        blocked: true,
+        ruleId,
+        category,
+        categoryId,
+        itemId,
+        source: 'builtin',
+        reason,
+        evidence: evidence(findingEvidence),
+        explanation,
+        policyHash: options?.policyHash,
+    };
+}
+function customBlock(value, options) {
+    const lower = value.toLowerCase();
+    for (const block of options?.customBlocks || []) {
+        const pattern = block.pattern.trim();
+        if (!pattern || !lower.includes(pattern.toLowerCase()))
+            continue;
+        return {
+            blocked: true,
+            ruleId: 'local-custom-block',
+            category: 'destructive_command',
+            categoryId: block.categoryId || 'custom',
+            itemId: block.id,
+            source: 'custom',
+            reason: block.explanation || `Blocked custom local safety pattern: ${pattern}.`,
+            evidence: evidence(value),
+            explanation: block.explanation,
+            policyHash: options?.policyHash,
+        };
+    }
+    return undefined;
+}
 function findSecret(value) {
     for (const pattern of SECRET_PATTERNS) {
         const match = value.match(pattern.re);
         if (match?.[0])
-            return { label: pattern.label, value: match[0] };
+            return { itemId: pattern.itemId, label: pattern.label, value: match[0] };
     }
     return undefined;
 }
 function containsMetadataEndpoint(value) {
     const normalized = decodeLoosely(value).toLowerCase();
-    return METADATA_ENDPOINTS.some(endpoint => normalized.includes(endpoint));
+    return METADATA_ENDPOINTS.find(endpoint => normalized.includes(endpoint.value));
 }
 function containsSensitiveCredentialPath(value) {
     const text = normalizeForPath(value);
     const traversal = /(?:^|\/)\.\.(?:\/|$)/.test(text) || /%2e/i.test(value);
     const checks = [
-        { label: 'SSH private key', re: /(?:^|\/)\.ssh\/id_(?:rsa|ed25519|ecdsa|dsa)(?:$|[/?#\s'"])/ },
-        { label: 'SSH config', re: /(?:^|\/)\.ssh\/config(?:$|[/?#\s'"])/ },
-        { label: 'AWS credentials', re: /(?:^|\/)\.aws\/(?:credentials|config)(?:$|[/?#\s'"])/ },
-        { label: 'Kubernetes config', re: /(?:^|\/)\.kube\/config(?:$|[/?#\s'"])/ },
-        { label: 'Docker auth config', re: /(?:^|\/)\.docker\/config\.json(?:$|[/?#\s'"])/ },
-        { label: 'npm credentials', re: /(?:^|\/)\.npmrc(?:$|[/?#\s'"])/ },
-        { label: 'PyPI credentials', re: /(?:^|\/)\.pypirc(?:$|[/?#\s'"])/ },
-        { label: 'netrc credentials', re: /(?:^|\/)\.netrc(?:$|[/?#\s'"])/ },
-        { label: 'GCP ADC credentials', re: /application_default_credentials\.json(?:$|[/?#\s'"])/ },
-        { label: 'Linux shadow file', re: /(?:^|\/)etc\/(?:shadow|sudoers)(?:$|[/?#\s'"])/ },
-        { label: 'PowerShell history', re: /powershell\/psreadline\/consolehost_history\.txt(?:$|[/?#\s'"])/ },
-        { label: 'browser credential store', re: /(?:login data|cookies|key4\.db|logins\.json)(?:$|[/?#\s'"])/ },
+        { itemId: 'ssh_private_key', label: 'SSH private key', re: /(?:^|\/)\.ssh\/id_(?:rsa|ed25519|ecdsa|dsa)(?:$|[/?#\s'"])/ },
+        { itemId: 'ssh_config', label: 'SSH config', re: /(?:^|\/)\.ssh\/config(?:$|[/?#\s'"])/ },
+        { itemId: 'aws_credentials', label: 'AWS credentials', re: /(?:^|\/)\.aws\/(?:credentials|config)(?:$|[/?#\s'"])/ },
+        { itemId: 'kube_config', label: 'Kubernetes config', re: /(?:^|\/)\.kube\/config(?:$|[/?#\s'"])/ },
+        { itemId: 'docker_auth', label: 'Docker auth config', re: /(?:^|\/)\.docker\/config\.json(?:$|[/?#\s'"])/ },
+        { itemId: 'npmrc', label: 'npm credentials', re: /(?:^|\/)\.npmrc(?:$|[/?#\s'"])/ },
+        { itemId: 'pypirc', label: 'PyPI credentials', re: /(?:^|\/)\.pypirc(?:$|[/?#\s'"])/ },
+        { itemId: 'netrc', label: 'netrc credentials', re: /(?:^|\/)\.netrc(?:$|[/?#\s'"])/ },
+        { itemId: 'gcp_adc', label: 'GCP ADC credentials', re: /application_default_credentials\.json(?:$|[/?#\s'"])/ },
+        { itemId: 'linux_shadow', label: 'Linux shadow file', re: /(?:^|\/)etc\/(?:shadow|sudoers)(?:$|[/?#\s'"])/ },
+        { itemId: 'powershell_history', label: 'PowerShell history', re: /powershell\/psreadline\/consolehost_history\.txt(?:$|[/?#\s'"])/ },
+        { itemId: 'browser_credentials', label: 'browser credential store', re: /(?:login data|cookies|key4\.db|logins\.json)(?:$|[/?#\s'"])/ },
     ];
     for (const check of checks) {
         if (check.re.test(text))
-            return check.label;
+            return { itemId: check.itemId, label: check.label };
     }
     if (traversal && /(?:^|\/)\.env(?:\.[a-z0-9_-]+)?(?:$|[/?#\s'"])/.test(text)) {
-        return 'environment file via path traversal';
+        return { itemId: 'env_traversal', label: 'environment file via path traversal' };
     }
     return undefined;
 }
@@ -138,69 +221,75 @@ function destructiveCommandReason(value) {
     const text = normalizeForCommand(value);
     const lower = text.toLowerCase();
     if (/\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+(?:["']?\/["']?|\*)(?:\s|$|[;&|])/.test(lower))
-        return 'recursive force delete of filesystem root';
+        return { itemId: 'rm_rf_root', reason: 'recursive force delete of filesystem root' };
     if (/\bsudo\s+rm\s+-[a-z]*r[a-z]*f[a-z]*\s+(?:["']?\/["']?|\*)(?:\s|$|[;&|])/.test(lower))
-        return 'recursive force delete of filesystem root';
+        return { itemId: 'rm_rf_root', reason: 'recursive force delete of filesystem root' };
     if (/\b(?:del|erase)\s+\/[a-z]*s[a-z]*\s+\/[a-z]*q[a-z]*\s+[a-z]:\\(?:\s|$)/i.test(text))
-        return 'recursive Windows drive delete';
+        return { itemId: 'windows_drive_delete', reason: 'recursive Windows drive delete' };
     if (lower.includes('remove-item') && lower.includes('-recurse') && lower.includes('-force') && /[a-z]:\\?(?:\s|$)/i.test(text))
-        return 'recursive Windows drive delete';
+        return { itemId: 'windows_drive_delete', reason: 'recursive Windows drive delete' };
     if (/: *\(\) *\{ *: *\| *: *& *\} *; *:/.test(text))
-        return 'fork bomb';
+        return { itemId: 'fork_bomb', reason: 'fork bomb' };
     if (/\bmkfs(?:\.[a-z0-9]+)?\s+\/dev\//i.test(text))
-        return 'filesystem format command';
+        return { itemId: 'mkfs_device', reason: 'filesystem format command' };
     if (/\bdd\b(?=.*\bof=\/dev\/(?:sd|xvd|hd|nvme|disk))/i.test(text))
-        return 'raw disk overwrite command';
+        return { itemId: 'dd_disk_overwrite', reason: 'raw disk overwrite command' };
     if (/\bchmod\s+-r\s+777\s+\/(?:\s|$)/i.test(text))
-        return 'recursive permission change on root';
+        return { itemId: 'chmod_root_777', reason: 'recursive permission change on root' };
+    if (/\bgit\s+(?:reset\s+--hard|clean\s+-f(?:d|x|dx)?\b)/i.test(text))
+        return { itemId: 'git_clean_force', reason: 'destructive git clean/reset' };
     return undefined;
 }
 function reverseShellReason(value) {
     const text = normalizeForCommand(value);
     if (/\bbash\s+-i\b.*\/dev\/tcp\//i.test(text))
-        return 'bash reverse shell';
+        return { itemId: 'bash_dev_tcp', reason: 'bash reverse shell' };
     if (/\b(?:nc|ncat|netcat)\b.*\s-e\s+(?:\/bin\/)?(?:sh|bash)\b/i.test(text))
-        return 'netcat reverse shell';
+        return { itemId: 'netcat_exec', reason: 'netcat reverse shell' };
     if (/\bsocat\b.*\bexec:(?:\/bin\/)?(?:sh|bash)\b/i.test(text))
-        return 'socat reverse shell';
+        return { itemId: 'socat_exec', reason: 'socat reverse shell' };
     if (/\b(?:curl|wget)\b[^|;&]{0,300}\|\s*(?:sudo\s+)?(?:sh|bash)\b/i.test(text))
-        return 'remote script piped to shell';
+        return { itemId: 'curl_pipe_shell', reason: 'remote script piped to shell' };
     if (/\bpython(?:3)?\s+-c\b(?=.*socket)(?=.*subprocess)/i.test(text))
-        return 'python reverse shell';
+        return { itemId: 'python_socket_subprocess', reason: 'python reverse shell' };
     return undefined;
 }
 function destructiveSqlReason(value) {
     const text = normalizeForCommand(value);
     if (/\bdrop\s+database\b/i.test(text))
-        return 'DROP DATABASE';
+        return { itemId: 'drop_database', reason: 'DROP DATABASE' };
     if (/\bdrop\s+schema\b/i.test(text))
-        return 'DROP SCHEMA';
+        return { itemId: 'drop_schema', reason: 'DROP SCHEMA' };
+    if (/\btruncate\s+table\b/i.test(text))
+        return { itemId: 'truncate_table', reason: 'TRUNCATE TABLE' };
     return undefined;
 }
 function infraDestroyReason(value) {
     const text = normalizeForCommand(value);
     if (/\bterraform\s+destroy\b(?=.*--auto-approve)/i.test(text))
-        return 'terraform destroy with auto-approve';
+        return { itemId: 'terraform_destroy_auto', reason: 'terraform destroy with auto-approve' };
     if (/\bpulumi\s+destroy\b(?=.*(?:--yes|-y))/i.test(text))
-        return 'pulumi destroy with auto-approve';
-    if (/\bkubectl\s+delete\s+(?:namespace|clusterrole|secret)\b/i.test(text))
-        return 'destructive kubectl delete';
+        return { itemId: 'pulumi_destroy_yes', reason: 'pulumi destroy with auto-approve' };
+    if (/\bkubectl\s+delete\s+namespace\b/i.test(text))
+        return { itemId: 'kubectl_delete_namespace', reason: 'destructive kubectl namespace delete' };
+    if (/\bkubectl\s+delete\s+(?:clusterrole|secret)\b/i.test(text))
+        return { itemId: 'generic_kubectl_delete', reason: 'destructive kubectl delete' };
     if (/\bkubectl\s+delete\s+all\b(?=.*--all)/i.test(text))
-        return 'broad kubectl delete all';
+        return { itemId: 'kubectl_delete_all_all', reason: 'broad kubectl delete all' };
     if (/\bgcloud\s+projects\s+delete\b/i.test(text))
-        return 'GCP project deletion';
+        return { itemId: 'gcloud_project_delete', reason: 'GCP project deletion' };
     if (/\bgcloud\s+sql\s+instances\s+delete\b/i.test(text))
-        return 'GCP SQL instance deletion';
+        return { itemId: 'gcloud_sql_delete', reason: 'GCP SQL instance deletion' };
     if (/\baws\s+s3\s+rm\s+s3:\/\/\S+\s+--recursive\b/i.test(text))
-        return 'recursive S3 deletion';
+        return { itemId: 'aws_s3_recursive_rm', reason: 'recursive S3 deletion' };
     if (/\baws\s+cloudformation\s+delete-stack\b/i.test(text))
-        return 'CloudFormation stack deletion';
+        return { itemId: 'aws_cloudformation_delete_stack', reason: 'CloudFormation stack deletion' };
     if (/\baws\s+iam\s+attach-user-policy\b(?=.*AdministratorAccess)/i.test(text))
-        return 'IAM administrator privilege grant';
+        return { itemId: 'aws_iam_admin_policy', reason: 'IAM administrator privilege grant' };
     if (/\baws\s+iam\s+create-access-key\b/i.test(text))
-        return 'IAM access key creation';
+        return { itemId: 'aws_iam_access_key', reason: 'IAM access key creation' };
     if (/\baz\s+group\s+delete\b(?=.*(?:--yes|-y))/i.test(text))
-        return 'Azure resource group deletion';
+        return { itemId: 'az_group_delete_yes', reason: 'Azure resource group deletion' };
     return undefined;
 }
 function isOutboundContext(toolName, candidates) {
@@ -216,107 +305,77 @@ function isSqlContext(toolName, candidate) {
     const lastKey = candidate.keyPath.split('.').pop() || '';
     return SQL_TOOL_HINT.test(toolName) || SQL_KEYS.has(lastKey) || SQL_KEYS.has(candidate.keyPath);
 }
-function scanDeterministicToolCall(toolName, toolArgs) {
+function scanTextValue(toolName, value, options) {
+    const custom = customBlock(value, options);
+    if (custom)
+        return custom;
+    const sensitivePath = containsSensitiveCredentialPath(value);
+    if (sensitivePath) {
+        return builtIn(sensitivePath.itemId, 'sensitive_files', 'sensitive_file', 'local-sensitive-credential-path', `Blocked local agent access to ${sensitivePath.label}.`, value, sensitivePath.label, options);
+    }
+    const metadata = containsMetadataEndpoint(value);
+    if (metadata) {
+        return builtIn(metadata.itemId, 'metadata_ssrf', 'metadata_ssrf', 'local-cloud-metadata-ssrf', `Blocked request to ${metadata.label}.`, value, metadata.value, options);
+    }
+    const reverseShell = reverseShellReason(value);
+    if (reverseShell) {
+        return builtIn(reverseShell.itemId, 'reverse_shells', 'reverse_shell', 'local-reverse-shell', `Blocked ${reverseShell.reason}.`, value, reverseShell.reason, options);
+    }
+    const destructive = destructiveCommandReason(value);
+    if (destructive) {
+        return builtIn(destructive.itemId, 'destructive_filesystem', 'destructive_command', 'local-destructive-command', `Blocked ${destructive.reason}.`, value, destructive.reason, options);
+    }
+    const infraDestroy = infraDestroyReason(value);
+    if (infraDestroy) {
+        return builtIn(infraDestroy.itemId, 'infra_destroy', 'infra_destroy', 'local-infra-destroy', `Blocked ${infraDestroy.reason}.`, value, infraDestroy.reason, options);
+    }
+    const destructiveSql = destructiveSqlReason(value);
+    if (destructiveSql) {
+        return builtIn(destructiveSql.itemId, 'destructive_sql', 'destructive_sql', 'local-destructive-sql', `Blocked destructive SQL command: ${destructiveSql.reason}.`, value, destructiveSql.reason, options);
+    }
+    return undefined;
+}
+function scanDeterministicToolCall(toolName, toolArgs, options) {
     const candidates = collectStrings(toolArgs);
     const outbound = isOutboundContext(toolName, candidates);
     for (const candidate of candidates) {
-        const sensitivePath = containsSensitiveCredentialPath(candidate.value);
-        if (sensitivePath) {
-            return {
-                blocked: true,
-                ruleId: 'local-sensitive-credential-path',
-                category: 'sensitive_file',
-                reason: `Blocked local agent access to ${sensitivePath}.`,
-                evidence: evidence(candidate.value),
-            };
-        }
+        const custom = customBlock(candidate.value, options);
+        if (custom)
+            return custom;
     }
     for (const candidate of candidates) {
-        if (containsMetadataEndpoint(candidate.value)) {
-            return {
-                blocked: true,
-                ruleId: 'local-cloud-metadata-ssrf',
-                category: 'metadata_ssrf',
-                reason: 'Blocked request to cloud metadata endpoint.',
-                evidence: evidence(candidate.value),
-            };
-        }
-    }
-    for (const candidate of candidates) {
-        if (!isCommandContext(toolName, candidate))
-            continue;
-        const reverseShell = reverseShellReason(candidate.value);
-        if (reverseShell) {
-            return {
-                blocked: true,
-                ruleId: 'local-reverse-shell',
-                category: 'reverse_shell',
-                reason: `Blocked ${reverseShell}.`,
-                evidence: evidence(candidate.value),
-            };
-        }
-        const destructive = destructiveCommandReason(candidate.value);
-        if (destructive) {
-            return {
-                blocked: true,
-                ruleId: 'local-destructive-command',
-                category: 'destructive_command',
-                reason: `Blocked ${destructive}.`,
-                evidence: evidence(candidate.value),
-            };
-        }
-        const infraDestroy = infraDestroyReason(candidate.value);
-        if (infraDestroy) {
-            return {
-                blocked: true,
-                ruleId: 'local-infra-destroy',
-                category: 'infra_destroy',
-                reason: `Blocked ${infraDestroy}.`,
-                evidence: evidence(candidate.value),
-            };
-        }
+        const finding = scanTextValue(toolName, candidate.value, options);
+        if (finding && (isCommandContext(toolName, candidate) || finding.category === 'sensitive_file' || finding.category === 'metadata_ssrf'))
+            return finding;
     }
     for (const candidate of candidates) {
         if (!isSqlContext(toolName, candidate))
             continue;
         const destructiveSql = destructiveSqlReason(candidate.value);
         if (destructiveSql) {
-            return {
-                blocked: true,
-                ruleId: 'local-destructive-sql',
-                category: 'destructive_sql',
-                reason: `Blocked destructive SQL command: ${destructiveSql}.`,
-                evidence: evidence(candidate.value),
-            };
+            return builtIn(destructiveSql.itemId, 'destructive_sql', 'destructive_sql', 'local-destructive-sql', `Blocked destructive SQL command: ${destructiveSql.reason}.`, candidate.value, destructiveSql.reason, options);
         }
     }
     if (outbound) {
         for (const candidate of candidates) {
             const secret = findSecret(candidate.value);
             if (secret) {
-                return {
-                    blocked: true,
-                    ruleId: 'local-secret-exfiltration',
-                    category: 'secret_exfiltration',
-                    reason: `Blocked outbound data containing ${secret.label}.`,
-                    evidence: evidence(secret.value),
-                };
+                return builtIn(secret.itemId, 'secret_exfiltration', 'secret_exfiltration', 'local-secret-exfiltration', `Blocked outbound data containing ${secret.label}.`, secret.value, secret.label, options);
             }
         }
     }
+    if (options?.inspectScripts && toolArgs.command && typeof toolArgs.command === 'string') {
+        const scriptFinding = scanReferencedScript(toolArgs.command, typeof toolArgs.cwd === 'string' ? toolArgs.cwd : options.cwd, options);
+        if (scriptFinding)
+            return scriptFinding;
+    }
     return undefined;
 }
-function scanDeterministicTextResponse(text) {
+function scanDeterministicTextResponse(text, options) {
     const secret = findSecret(text);
     if (!secret)
         return undefined;
-    return {
-        blocked: true,
-        ruleId: 'local-secret-in-tool-response',
-        category: 'secret_exfiltration',
-        reason: `Blocked tool response containing ${secret.label}.`,
-        evidence: evidence(secret.value),
-    };
+    return builtIn(secret.itemId, 'secret_exfiltration', 'secret_exfiltration', 'local-secret-in-tool-response', `Blocked tool response containing ${secret.label}.`, secret.value, secret.label, options);
 }
 function looksLikeQuestion(value) {
     return /^(?:what|why|how|explain|describe|is|are|can you explain)\b/i.test(value.trim());
@@ -327,79 +386,121 @@ function bareOrActionIntent(value, action) {
         return false;
     return action.test(trimmed) || /^[^\n]{1,240}$/.test(trimmed);
 }
-function scanDeterministicPrompt(text) {
+function scanDeterministicPrompt(text, options) {
     const trimmed = text.trim();
     if (!trimmed || looksLikeQuestion(trimmed))
         return undefined;
+    const custom = customBlock(trimmed, options);
+    if (custom)
+        return custom;
     const secret = findSecret(trimmed);
     if (secret && OUTBOUND_TOOL_HINT.test(trimmed)) {
-        return {
-            blocked: true,
-            ruleId: 'local-prompt-secret-exfiltration',
-            category: 'secret_exfiltration',
-            reason: `Blocked prompt asking to send ${secret.label}.`,
-            evidence: evidence(secret.value),
-        };
+        return builtIn(secret.itemId, 'secret_exfiltration', 'secret_exfiltration', 'local-prompt-secret-exfiltration', `Blocked prompt asking to send ${secret.label}.`, secret.value, secret.label, options);
     }
     const sensitivePath = containsSensitiveCredentialPath(trimmed);
     if (sensitivePath && bareOrActionIntent(trimmed, /\b(?:read|open|cat|show|print|copy|upload|send|exfiltrate)\b/i)) {
-        return {
-            blocked: true,
-            ruleId: 'local-prompt-sensitive-credential-path',
-            category: 'sensitive_file',
-            reason: `Blocked prompt targeting ${sensitivePath}.`,
-            evidence: evidence(trimmed),
-        };
+        return builtIn(sensitivePath.itemId, 'sensitive_files', 'sensitive_file', 'local-prompt-sensitive-credential-path', `Blocked prompt targeting ${sensitivePath.label}.`, trimmed, sensitivePath.label, options);
     }
     if (bareOrActionIntent(trimmed, /\b(?:run|execute|launch|start)\b/i)) {
         const reverseShell = reverseShellReason(trimmed);
         if (reverseShell) {
-            return {
-                blocked: true,
-                ruleId: 'local-prompt-reverse-shell',
-                category: 'reverse_shell',
-                reason: `Blocked prompt containing ${reverseShell}.`,
-                evidence: evidence(trimmed),
-            };
+            return builtIn(reverseShell.itemId, 'reverse_shells', 'reverse_shell', 'local-prompt-reverse-shell', `Blocked prompt containing ${reverseShell.reason}.`, trimmed, reverseShell.reason, options);
         }
         const destructive = destructiveCommandReason(trimmed);
         if (destructive) {
-            return {
-                blocked: true,
-                ruleId: 'local-prompt-destructive-command',
-                category: 'destructive_command',
-                reason: `Blocked prompt containing ${destructive}.`,
-                evidence: evidence(trimmed),
-            };
+            return builtIn(destructive.itemId, 'destructive_filesystem', 'destructive_command', 'local-prompt-destructive-command', `Blocked prompt containing ${destructive.reason}.`, trimmed, destructive.reason, options);
         }
         const infraDestroy = infraDestroyReason(trimmed);
         if (infraDestroy) {
-            return {
-                blocked: true,
-                ruleId: 'local-prompt-infra-destroy',
-                category: 'infra_destroy',
-                reason: `Blocked prompt containing ${infraDestroy}.`,
-                evidence: evidence(trimmed),
-            };
+            return builtIn(infraDestroy.itemId, 'infra_destroy', 'infra_destroy', 'local-prompt-infra-destroy', `Blocked prompt containing ${infraDestroy.reason}.`, trimmed, infraDestroy.reason, options);
         }
     }
     const destructiveSql = destructiveSqlReason(trimmed);
     if (destructiveSql && bareOrActionIntent(trimmed, /\b(?:run|execute|query|apply)\b/i)) {
-        return {
-            blocked: true,
-            ruleId: 'local-prompt-destructive-sql',
-            category: 'destructive_sql',
-            reason: `Blocked prompt containing destructive SQL command: ${destructiveSql}.`,
-            evidence: evidence(trimmed),
-        };
+        return builtIn(destructiveSql.itemId, 'destructive_sql', 'destructive_sql', 'local-prompt-destructive-sql', `Blocked prompt containing destructive SQL command: ${destructiveSql.reason}.`, trimmed, destructiveSql.reason, options);
+    }
+    const metadata = containsMetadataEndpoint(trimmed);
+    if (metadata && /\b(?:fetch|request|curl|open|connect|call)\b/i.test(trimmed)) {
+        return builtIn(metadata.itemId, 'metadata_ssrf', 'metadata_ssrf', 'local-prompt-cloud-metadata-ssrf', `Blocked prompt targeting ${metadata.label}.`, trimmed, metadata.value, options);
+    }
+    return undefined;
+}
+function splitCommand(command) {
+    return command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map(part => part.replace(/^["']|["']$/g, '')) || [];
+}
+function safeResolveScriptPath(candidate, cwd) {
+    if (!candidate || /^https?:\/\//i.test(candidate))
+        return undefined;
+    const base = cwd || process.cwd();
+    const resolved = path.resolve(base, candidate);
+    const root = path.resolve(base);
+    if (!resolved.toLowerCase().startsWith(root.toLowerCase()))
+        return undefined;
+    const ext = path.extname(resolved).toLowerCase();
+    if (!['.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd', '.py', '.js', '.mjs', '.cjs'].includes(ext))
+        return undefined;
+    return resolved;
+}
+function referencedScripts(command, cwd) {
+    const tokens = splitCommand(command);
+    const scripts = [];
+    const runners = new Set(['bash', 'sh', 'zsh', 'python', 'python3', 'node', 'pwsh']);
+    for (let i = 0; i < tokens.length; i++) {
+        const token = path.basename(tokens[i]).toLowerCase();
+        if (runners.has(token)) {
+            const next = tokens.slice(i + 1).find(part => part && !part.startsWith('-'));
+            const resolved = next ? safeResolveScriptPath(next, cwd) : undefined;
+            if (resolved)
+                scripts.push(resolved);
+        }
+        if ((token === 'powershell' || token === 'powershell.exe') && tokens[i + 1]?.toLowerCase() === '-file') {
+            const resolved = safeResolveScriptPath(tokens[i + 2], cwd);
+            if (resolved)
+                scripts.push(resolved);
+        }
+        const direct = safeResolveScriptPath(tokens[i], cwd);
+        if (direct)
+            scripts.push(direct);
+    }
+    if (tokens[0]?.toLowerCase() === 'npm' && tokens[1]?.toLowerCase() === 'run' && tokens[2]) {
+        const pkg = path.resolve(cwd || process.cwd(), 'package.json');
+        try {
+            const stat = fs.statSync(pkg);
+            if (stat.size <= 200_000) {
+                const parsed = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+                const script = parsed?.scripts?.[tokens[2]];
+                if (typeof script === 'string')
+                    scripts.push(`npm:${tokens[2]}:${script}`);
+            }
+        }
+        catch { /* ignore */ }
     }
-    if (containsMetadataEndpoint(trimmed) && /\b(?:fetch|request|curl|open|connect|call)\b/i.test(trimmed)) {
+    return Array.from(new Set(scripts));
+}
+function scanReferencedScript(command, cwd, options) {
+    for (const script of referencedScripts(command, cwd)) {
+        let content = '';
+        if (script.startsWith('npm:')) {
+            content = script;
+        }
+        else {
+            try {
+                const stat = fs.statSync(script);
+                if (!stat.isFile() || stat.size > 250_000)
+                    continue;
+                content = fs.readFileSync(script, 'utf8');
+            }
+            catch {
+                continue;
+            }
+        }
+        const finding = scanTextValue('script_file', content, options);
+        if (!finding)
+            continue;
         return {
-            blocked: true,
-            ruleId: 'local-prompt-cloud-metadata-ssrf',
-            category: 'metadata_ssrf',
-            reason: 'Blocked prompt targeting cloud metadata endpoint.',
-            evidence: evidence(trimmed),
+            ...finding,
+            evidence: evidence(`${script}: ${finding.evidence}`),
+            reason: `${finding.reason} Found inside referenced script ${script.startsWith('npm:') ? script.split(':').slice(0, 2).join(':') : path.basename(script)}.`,
         };
     }
     return undefined;

package/dist/commands/hook.js

@@ -41,6 +41,7 @@ const config_1 = require("../config");
 const runtimeConfig_1 = require("../runtimeConfig");
 const telemetry_1 = require("../telemetry");
 const deterministicGuard_1 = require("./deterministicGuard");
+const localSafetySnapshot_1 = require("../localSafetySnapshot");
 const taintLedger_1 = require("./taintLedger");
 const DEBUG_LOG = path.join(os.homedir(), '.fullcourtdefense-hook.log');
 /** Append a diagnostic line so we can see exactly what Cursor invoked + the verdict. */
@@ -324,6 +325,24 @@ function machineMetadata() {
         agentClient: 'cursor',
     };
 }
+function spoolLocalFinding(input) {
+    (0, telemetry_1.spoolEvent)({
+        decision: 'block',
+        toolName: input.toolName,
+        operation: input.operation,
+        reason: input.finding.reason,
+        ruleId: input.finding.ruleId,
+        category: input.finding.category,
+        categoryId: input.finding.categoryId,
+        itemId: input.finding.itemId,
+        source: input.finding.source,
+        evidence: input.finding.evidence,
+        explanation: input.finding.explanation,
+        policyHash: input.finding.policyHash,
+        offlineEnforced: true,
+    });
+    (0, telemetry_1.triggerFlush)(true);
+}
 async function hookCommand(args, config) {
     // Mode is server-authoritative (pulled from the cached runtime bundle), with
     // local flags as explicit overrides. Resolved after creds below.
@@ -343,14 +362,16 @@ async function hookCommand(args, config) {
     const shieldId = creds.shieldId;
     const shieldKey = creds.shieldKey;
     const apiUrl = creds.apiUrl;
+    let effectivePolicyHash;
     // Server-authoritative enforcement mode: the console flips shield.mode and the
     // machine applies it on the next poll. Cached locally (stale-while-error), so
     // this is instant when fresh and bounded (~1.5s) only when stale.
     if (!forceMonitor && !forceEnforce && shieldId) {
         try {
-            const bundle = await (0, runtimeConfig_1.getRuntimeBundle)({ apiUrl, shieldId, shieldKey });
+            const bundle = await (0, runtimeConfig_1.getRuntimeBundle)({ apiUrl, shieldId, shieldKey, developerName: developerId(), machineName: os.hostname() });
             if (bundle.source !== 'default') {
                 shadow = bundle.mode !== 'block'; // 'monitor'/'shadow' => report-only
+                effectivePolicyHash = bundle.policyHash || bundle.version;
                 dbg({ phase: 'mode_resolved', mode: bundle.mode, source: bundle.source, shadow });
             }
         }
@@ -416,6 +437,7 @@ async function hookCommand(args, config) {
         await enforceActionPolicy({
             event, payload, apiUrl: apiUrl, shieldId: shieldId, shieldKey,
             shadow, failClosed, timeoutMs, approvalMode, approvalTimeoutMs, approvalPollMs, respond,
+            effectivePolicyHash,
         });
         return;
     }
@@ -428,13 +450,23 @@ async function hookCommand(args, config) {
         // Record the developer's prompt so taint-tracking can later tell whether a
         // sensitive action (network/git) was actually requested by the human.
         (0, taintLedger_1.recordUserPrompt)(sessionId(payload), text);
-        const localBlock = (0, deterministicGuard_1.scanDeterministicPrompt)(text);
+        const snapshot = await (0, localSafetySnapshot_1.loadLocalSafetySnapshot)({
+            apiUrl: apiUrl,
+            shieldId: shieldId,
+            shieldKey,
+            developerName: developerId(),
+            machineName: os.hostname(),
+            expectedPolicyHash: effectivePolicyHash,
+        });
+        const localBlock = (0, deterministicGuard_1.scanDeterministicPrompt)(text, (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
         if (localBlock) {
             dbg({ phase: 'local_deterministic_prompt_block', event, ruleId: localBlock.ruleId, category: localBlock.category });
             if (shadow) {
+                spoolLocalFinding({ finding: localBlock, toolName: 'prompt', operation: 'prompt' });
                 respond(false, undefined, `[FullCourtDefense shadow] would block prompt: ${localBlock.reason}`);
                 return;
             }
+            spoolLocalFinding({ finding: localBlock, toolName: 'prompt', operation: 'prompt' });
             respond(true, `Blocked by FullCourtDefense local guard — ${localBlock.reason}`, `FullCourtDefense blocked this prompt locally (${localBlock.ruleId}). Do not retry.`);
             return;
         }
@@ -448,21 +480,32 @@ async function hookCommand(args, config) {
     respond(false);
 }
 async function enforceActionPolicy(ctx) {
-    const { event, payload, apiUrl, shieldId, shieldKey, shadow, timeoutMs, respond } = ctx;
+    const { event, payload, apiUrl, shieldId, shieldKey, shadow, timeoutMs, respond, effectivePolicyHash } = ctx;
     const call = buildToolCall(event, payload);
     if (!call) {
         respond(false);
         return;
     }
-    const localBlock = (0, deterministicGuard_1.scanDeterministicToolCall)(call.toolName, call.toolArgs);
+    const snapshot = await (0, localSafetySnapshot_1.loadLocalSafetySnapshot)({
+        apiUrl,
+        shieldId,
+        shieldKey,
+        developerName: developerId(),
+        machineName: os.hostname(),
+        expectedPolicyHash: effectivePolicyHash,
+    });
+    const localBlock = (0, deterministicGuard_1.scanDeterministicToolCall)(call.toolName, call.toolArgs, (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot, {
+        cwd: typeof call.toolArgs.cwd === 'string' ? call.toolArgs.cwd : process.cwd(),
+        inspectScripts: event === 'shell',
+    }));
     if (localBlock) {
         dbg({ phase: 'local_deterministic_block', event, tool: call.toolName, ruleId: localBlock.ruleId, category: localBlock.category });
         if (shadow) {
+            spoolLocalFinding({ finding: localBlock, toolName: call.toolName, operation: event });
             respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}: ${localBlock.reason}`);
             return;
         }
-        (0, telemetry_1.spoolEvent)({ decision: 'block', toolName: call.toolName, reason: localBlock.reason, ruleId: localBlock.ruleId, offlineEnforced: true });
-        (0, telemetry_1.triggerFlush)(true);
+        spoolLocalFinding({ finding: localBlock, toolName: call.toolName, operation: event });
         respond(true, `Blocked by FullCourtDefense local guard — ${localBlock.reason}`, `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry.`);
         return;
     }

package/dist/commands/mcpGateway.js

@@ -54,6 +54,7 @@ const discoverPaths_1 = require("./discoverPaths");
 const discover_1 = require("./discover");
 const deterministicGuard_1 = require("./deterministicGuard");
 const restartNotice_1 = require("./restartNotice");
+const localSafetySnapshot_1 = require("../localSafetySnapshot");
 const DEFAULT_API_URL = 'https://api.fullcourtdefense.ai';
 const MANAGED_SERVER_NAME = 'agentguard-gateway';
 const INSTALL_GATEWAY_ARGS = { includeShieldKey: false };
@@ -591,7 +592,14 @@ class McpGatewayServer {
         let approvalActionId;
         let operation = typeof params.operation === 'string' && params.operation.trim() ? params.operation.trim() : undefined;
         try {
-            const localBlock = (0, deterministicGuard_1.scanDeterministicToolCall)(toolName, toolArgs);
+            const snapshot = await (0, localSafetySnapshot_1.loadLocalSafetySnapshot)({
+                apiUrl: this.gatewayConfig.apiUrl,
+                shieldId: this.gatewayConfig.shieldId,
+                shieldKey: this.gatewayConfig.shieldKey,
+                developerName: this.gatewayConfig.developerName,
+                machineName: os.hostname(),
+            });
+            const localBlock = (0, deterministicGuard_1.scanDeterministicToolCall)(toolName, toolArgs, (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
             if (localBlock)
                 throw new Error(`${localBlock.reason} (${localBlock.ruleId}: ${localBlock.evidence})`);
             const preflight = await this.api.checkToolCall({ toolName, operation, toolArgs });
@@ -610,7 +618,7 @@ class McpGatewayServer {
                 }
             }
             const rawResult = await this.downstream.callTool(toolName, toolArgs);
-            const localResponseBlock = (0, deterministicGuard_1.scanDeterministicTextResponse)(contentToText(rawResult));
+            const localResponseBlock = (0, deterministicGuard_1.scanDeterministicTextResponse)(contentToText(rawResult), (0, localSafetySnapshot_1.snapshotToScanOptions)(snapshot));
             if (localResponseBlock)
                 throw new Error(`${localResponseBlock.reason} (${localResponseBlock.ruleId}: ${localResponseBlock.evidence})`);
             const finalResult = this.gatewayConfig.scanResponse

package/dist/localSafetySnapshot.d.ts

@@ -0,0 +1,18 @@
+import { LocalSafetyCustomBlock, LocalSafetyScanOptions } from './commands/deterministicGuard';
+export interface LocalSafetySnapshot {
+    policyHash: string;
+    disabledBuiltInItemIds: string[];
+    customBlocks: LocalSafetyCustomBlock[];
+    updatedAt?: string;
+}
+export interface LocalSafetySnapshotInput {
+    apiUrl: string;
+    shieldId: string;
+    shieldKey?: string;
+    developerName: string;
+    machineName: string;
+    expectedPolicyHash?: string;
+    timeoutMs?: number;
+}
+export declare function loadLocalSafetySnapshot(input: LocalSafetySnapshotInput): Promise<LocalSafetySnapshot | undefined>;
+export declare function snapshotToScanOptions(snapshot: LocalSafetySnapshot | undefined, extra?: Pick<LocalSafetyScanOptions, 'cwd' | 'inspectScripts'>): LocalSafetyScanOptions;

package/dist/localSafetySnapshot.js

@@ -0,0 +1,130 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadLocalSafetySnapshot = loadLocalSafetySnapshot;
+exports.snapshotToScanOptions = snapshotToScanOptions;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const CACHE_TTL_MS = 60_000;
+const CACHE_DIR = path.join(os.homedir(), '.fullcourtdefense');
+function cachePath(input) {
+    const key = crypto.createHash('sha1')
+        .update([input.apiUrl, input.shieldId, input.developerName, input.machineName].join('|'))
+        .digest('hex');
+    return path.join(CACHE_DIR, `local-safety-${key}.json`);
+}
+function readCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!parsed?.snapshot || typeof parsed.loadedAt !== 'number')
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(file, snapshot) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ loadedAt: Date.now(), snapshot }, null, 2), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch { /* best-effort */ }
+}
+function toSnapshot(data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    return {
+        policyHash: typeof data.policyHash === 'string' ? data.policyHash : '',
+        disabledBuiltInItemIds: Array.isArray(data.disabledBuiltInItemIds)
+            ? data.disabledBuiltInItemIds.filter((item) => typeof item === 'string')
+            : [],
+        customBlocks: Array.isArray(data.customBlocks)
+            ? data.customBlocks
+                .filter((item) => item && typeof item.pattern === 'string')
+                .map((item) => ({
+                id: String(item.id || item.pattern),
+                categoryId: String(item.categoryId || 'custom'),
+                pattern: String(item.pattern),
+                explanation: typeof item.explanation === 'string' ? item.explanation : undefined,
+            }))
+            : [],
+        updatedAt: typeof data.updatedAt === 'string' ? data.updatedAt : undefined,
+    };
+}
+async function loadLocalSafetySnapshot(input) {
+    const file = cachePath(input);
+    const cached = readCache(file);
+    const hashMatches = !input.expectedPolicyHash || cached?.snapshot.policyHash === input.expectedPolicyHash;
+    if (cached && hashMatches && Date.now() - cached.loadedAt < CACHE_TTL_MS)
+        return cached.snapshot;
+    const headers = { 'Content-Type': 'application/json' };
+    if (input.shieldKey)
+        headers['x-shield-key'] = input.shieldKey;
+    try {
+        const resp = await fetch(`${input.apiUrl}/api/agent-security/runtime/local-safety-snapshot`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                shieldId: input.shieldId,
+                developerName: input.developerName,
+                machineName: input.machineName,
+            }),
+            signal: AbortSignal.timeout(input.timeoutMs ?? 1200),
+        });
+        if (resp.ok) {
+            const body = await resp.json().catch(() => ({}));
+            if (body.success) {
+                const snapshot = toSnapshot(body.data);
+                if (snapshot) {
+                    writeCache(file, snapshot);
+                    return snapshot;
+                }
+            }
+        }
+    }
+    catch { /* offline-safe fallback below */ }
+    return cached?.snapshot;
+}
+function snapshotToScanOptions(snapshot, extra = {}) {
+    return {
+        disabledBuiltInItemIds: snapshot?.disabledBuiltInItemIds,
+        customBlocks: snapshot?.customBlocks,
+        policyHash: snapshot?.policyHash,
+        ...extra,
+    };
+}

package/dist/runtimeConfig.d.ts

@@ -17,6 +17,7 @@ export type ShieldMode = 'block' | 'monitor' | 'shadow';
 export interface RuntimeBundle {
     mode: ShieldMode;
     version: string;
+    policyHash?: string;
     policyCount?: number;
     pollIntervalMs?: number;
 }
@@ -24,6 +25,8 @@ export interface FetchBundleInput {
     apiUrl: string;
     shieldId: string;
     shieldKey?: string;
+    developerName?: string;
+    machineName?: string;
     /** Override cache TTL (ms). */
     ttlMs?: number;
     /** Force a network refresh regardless of cache freshness. */

package/dist/runtimeConfig.js

@@ -70,7 +70,7 @@ async function getRuntimeBundle(input) {
     const cached = cache[input.shieldId];
     const fresh = cached && Date.now() - cached.fetchedAt < ttl;
     if (cached && fresh && !input.force) {
-        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+        return { mode: cached.mode, version: cached.version, policyHash: cached.policyHash, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
     }
     try {
         const headers = { 'Content-Type': 'application/json' };
@@ -78,12 +78,17 @@ async function getRuntimeBundle(input) {
             headers['x-shield-key'] = input.shieldKey;
         if (cached?.version)
             headers['If-None-Match'] = cached.version;
-        const resp = await fetch(`${input.apiUrl}/api/cli/bundle?shieldId=${encodeURIComponent(input.shieldId)}`, { method: 'GET', headers, signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) });
+        const params = new URLSearchParams({ shieldId: input.shieldId });
+        if (input.developerName)
+            params.set('developerName', input.developerName);
+        if (input.machineName)
+            params.set('machineName', input.machineName);
+        const resp = await fetch(`${input.apiUrl}/api/cli/bundle?${params.toString()}`, { method: 'GET', headers, signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS) });
         // 304 Not Modified — cache is still valid; refresh its timestamp.
         if (resp.status === 304 && cached) {
             cache[input.shieldId] = { ...cached, fetchedAt: Date.now() };
             writeCacheFile(cache);
-            return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+            return { mode: cached.mode, version: cached.version, policyHash: cached.policyHash, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
         }
         if (resp.ok) {
             const body = await resp.json().catch(() => ({}));
@@ -91,6 +96,7 @@ async function getRuntimeBundle(input) {
                 const entry = {
                     mode: body.data.mode,
                     version: body.data.version,
+                    policyHash: body.data.policyHash,
                     policyCount: body.data.policyCount,
                     pollIntervalMs: body.data.pollIntervalMs,
                     fetchedAt: Date.now(),
@@ -103,7 +109,7 @@ async function getRuntimeBundle(input) {
     }
     catch { /* fall through to cache / default */ }
     if (cached) {
-        return { mode: cached.mode, version: cached.version, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
+        return { mode: cached.mode, version: cached.version, policyHash: cached.policyHash, policyCount: cached.policyCount, pollIntervalMs: cached.pollIntervalMs, source: 'cache' };
     }
     return { mode: 'block', version: '', source: 'default' };
 }

package/dist/telemetry.d.ts

@@ -6,6 +6,13 @@ export interface SpoolEvent {
     operation?: string;
     reason?: string;
     ruleId?: string;
+    category?: string;
+    categoryId?: string;
+    itemId?: string;
+    source?: 'builtin' | 'custom' | 'taint' | 'backend';
+    evidence?: string;
+    explanation?: string;
+    policyHash?: string;
     /** True when this decision was enforced locally while the backend was unreachable. */
     offlineEnforced?: boolean;
     occurredAt: string;

package/dist/telemetry.js

@@ -66,6 +66,13 @@ function spoolEvent(event) {
             operation: event.operation,
             reason: event.reason,
             ruleId: event.ruleId,
+            category: event.category,
+            categoryId: event.categoryId,
+            itemId: event.itemId,
+            source: event.source,
+            evidence: event.evidence,
+            explanation: event.explanation,
+            policyHash: event.policyHash,
             offlineEnforced: event.offlineEnforced,
         };
         fs.appendFileSync(SPOOL_PATH, JSON.stringify(full) + '\n', { encoding: 'utf-8', mode: 0o600 });

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.7.22"
+  "version": "1.7.23"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.7.22",
+  "version": "1.7.23",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {