fullcourtdefense-cli 1.28.0 → 1.30.0

package/dist/blockExplanation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The ONE developer-facing explanation for a FullCourtDefense stop.
+ *
+ * Every enforcement surface (IDE hooks, MCP gateway, terminal guards) MUST go
+ * through here when it blocks, masks, or pauses an action. A developer who is
+ * stopped has to learn, in one glance and without opening anything:
+ *
+ *   1. WHAT was stopped            — the exact command / path / tool call
+ *   2. WHICH RULE, BY NAME         — the policy or Local Safety rule, and where it came from
+ *   3. WHY it matched              — the deterministic fact that fired (operation, secret kind, host…)
+ *   4. HOW TO REMOVE THE BLOCK     — the exact console page, and what to click
+ *
+ * Fixed templates only: nothing here is generated text, and raw argument
+ * values never leak beyond the short "what" line. Pure — no I/O, so it is unit
+ * tested byte-for-byte by `scripts/test-block-explanation.js`.
+ */
+export type ExplanationOutcome = 'block' | 'ask' | 'approval' | 'mask';
+export interface PolicyExplanationSource {
+    kind: 'policy';
+    policyName?: string;
+    policyId?: string;
+    /** Engine `matchedRule`, e.g. `DELETE → block (toolArgs.containsSecret equals true)`. */
+    matchedRule?: string;
+    /** Policy scope: `organization` (company default) or a machine/developer-scoped exception. */
+    scope?: string;
+    /** Engine facts that explain the match. Only well-known keys are rendered. */
+    facts?: Record<string, string | undefined>;
+    operation?: string;
+    /**
+     * Verdict reason from the engine or the policy service. Rendered only when it
+     * says more than the rule line already does (the engine's own
+     * `Action policy "<name>": … blocked` boilerplate is dropped; a server-side
+     * or admin-written reason such as "Destructive business operation blocked" is kept).
+     */
+    reason?: string;
+}
+export interface LocalSafetyExplanationSource {
+    kind: 'local_safety';
+    itemId: string;
+    /** Console label when known (e.g. "GitHub CLI token print"); falls back to the id. */
+    label?: string;
+    category?: string;
+    source: 'builtin' | 'custom';
+    explanation?: string;
+    /** Machine-stated reason from the guard (`reason` on the finding). */
+    reason: string;
+}
+export interface GuardExplanationSource {
+    kind: 'taint' | 'self_protection' | 'fail_closed' | 'suspended' | 'offline';
+    ruleId?: string;
+    reason: string;
+}
+export type ExplanationSource = PolicyExplanationSource | LocalSafetyExplanationSource | GuardExplanationSource;
+export interface BlockExplanationInput {
+    outcome: ExplanationOutcome;
+    /** Hook event / surface: shell, file, mcp, prompt, terminal, gateway. */
+    event: string;
+    toolName: string;
+    toolArgs?: Record<string, unknown>;
+    source: ExplanationSource;
+    /** Console base URL (no trailing slash). */
+    consoleUrl: string;
+    /** Fleet machine id — used to deep-link the machine page. */
+    machineId?: string;
+    /** Developer display name, when the block is machine-scoped. */
+    developerName?: string;
+    /** Extra sentence appended to the "why" (e.g. no human present on CI). */
+    note?: string;
+}
+export interface BlockExplanation {
+    /** One line, first thing the developer reads. */
+    headline: string;
+    /** The stopped action, shortened, never more than ~160 chars. */
+    what: string;
+    /** Rule name + origin, exactly as it appears in the console. */
+    rule: string;
+    /** Deterministic reason the rule matched. */
+    why: string;
+    /** Numbered, concrete steps to lift the block. */
+    unblock: string[];
+    /** Deep link to the console entry that controls this rule. */
+    consoleLink: string;
+    /** Full multi-line text shown to the developer (IDE toast / terminal stderr). */
+    userMessage: string;
+    /** Single paragraph for the agent: stop, do not retry, relay the message. */
+    agentMessage: string;
+}
+/** The stopped action in the developer's own terms — command, path, or tool call. */
+export declare function summarizeAction(event: string, toolName: string, args?: Record<string, unknown>): string;
+export declare function buildBlockExplanation(input: BlockExplanationInput): BlockExplanation;
+/**
+ * Compact single-line form for surfaces with no room for a block (terminal
+ * `[FullCourtDefense]` line, Claude `permissionDecisionReason`).
+ */
+export declare function oneLineExplanation(explanation: BlockExplanation): string;

package/dist/blockExplanation.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * The ONE developer-facing explanation for a FullCourtDefense stop.
+ *
+ * Every enforcement surface (IDE hooks, MCP gateway, terminal guards) MUST go
+ * through here when it blocks, masks, or pauses an action. A developer who is
+ * stopped has to learn, in one glance and without opening anything:
+ *
+ *   1. WHAT was stopped            — the exact command / path / tool call
+ *   2. WHICH RULE, BY NAME         — the policy or Local Safety rule, and where it came from
+ *   3. WHY it matched              — the deterministic fact that fired (operation, secret kind, host…)
+ *   4. HOW TO REMOVE THE BLOCK     — the exact console page, and what to click
+ *
+ * Fixed templates only: nothing here is generated text, and raw argument
+ * values never leak beyond the short "what" line. Pure — no I/O, so it is unit
+ * tested byte-for-byte by `scripts/test-block-explanation.js`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeAction = summarizeAction;
+exports.buildBlockExplanation = buildBlockExplanation;
+exports.oneLineExplanation = oneLineExplanation;
+const MAX_WHAT = 160;
+function str(v) {
+    return typeof v === 'string' && v.trim() ? v : undefined;
+}
+function shorten(text, max = MAX_WHAT) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+/** The stopped action in the developer's own terms — command, path, or tool call. */
+function summarizeAction(event, toolName, args = {}) {
+    const command = str(args.command) || str(args.cmd) || str(args.commandLine) || str(args.script);
+    if (command)
+        return `${shorten(command)}  (${event === 'terminal' ? 'terminal command' : 'shell command'})`;
+    const path = str(args.path) || str(args.file_path) || str(args.filePath) || str(args.target_file) || str(args.notebook_path);
+    if (path) {
+        const verb = /read|open|view|cat|list|search|grep/i.test(toolName) ? 'read' : 'edit';
+        return `${shorten(path)}  (file ${verb})`;
+    }
+    const url = str(args.url) || str(args.uri) || str(args.endpoint);
+    if (url)
+        return `${toolName} → ${shorten(url, 120)}  (network call)`;
+    if (event === 'prompt')
+        return 'the prompt you submitted';
+    const server = str(args.mcp_server_name) || str(args.server_name) || str(args.serverName);
+    return `${server ? `${server} / ` : ''}${toolName}  (${event === 'mcp' ? 'MCP tool call' : `${event} action`})`;
+}
+/** Headline per outcome — `${noun}` is the action kind ("shell command", "MCP tool call"…). */
+function headlineFor(outcome, noun) {
+    switch (outcome) {
+        case 'ask': return `FullCourtDefense paused this ${noun} — your confirmation is needed.`;
+        case 'approval': return `FullCourtDefense paused this ${noun} — Approval required from your security team.`;
+        case 'mask': return `FullCourtDefense masked secrets in this ${noun}.`;
+        default: return `FullCourtDefense blocked this ${noun}.`;
+    }
+}
+/** The step list title — a pause is lifted by an answer, a block by a rule change. */
+function stepsTitle(outcome) {
+    return outcome === 'block' ? 'To remove this block:' : outcome === 'mask' ? 'To change this rule:' : 'To remove this block (or to stop being asked):';
+}
+function eventNoun(event) {
+    switch (event) {
+        case 'shell': return 'shell command';
+        case 'terminal': return 'terminal command';
+        case 'file': return 'file operation';
+        case 'read': return 'file read';
+        case 'mcp': return 'MCP tool call';
+        case 'prompt': return 'prompt';
+        case 'gateway': return 'tool call';
+        default: return 'action';
+    }
+}
+/** Company default vs local exception — the same words the console uses. */
+function scopeWords(scope, developerName) {
+    if (!scope || scope === 'organization' || scope === 'org')
+        return '🌐 company default — applies to every machine';
+    if (scope === 'machine' || scope === 'developer' || scope === 'local')
+        return `📍 local rule — only ${developerName || 'this machine'}`;
+    return `${scope} policy`;
+}
+const FACT_WORDS = [
+    ['operation', v => v && !/^(shell|execute|unknown)$/i.test(v) ? `the action was classified as ${v.toUpperCase()}` : undefined],
+    ['toolArgs.containsSecret', (v, f) => v === 'true'
+            ? `a secret-shaped value was found in the arguments${f['toolArgs.secretKind'] && f['toolArgs.secretKind'] !== 'none' ? ` (${f['toolArgs.secretKind'].replace(/_/g, ' ')})` : ''}`
+            : undefined],
+    ['toolArgs.containsPii', v => v === 'true' ? 'personal data (PII) was found in the arguments' : undefined],
+    ['destination.type', (v, f) => v === 'external' ? `the destination ${f['destination.domain'] ? `"${f['destination.domain']}" ` : ''}is outside your organisation` : undefined],
+    ['destination.domain', (v, f) => f['destination.type'] === 'external' ? undefined : `destination host: ${v}`],
+    ['url.risk', v => v && v !== 'none' && v !== 'low' ? `the URL was rated ${v} risk` : undefined],
+    ['path.sensitive', v => v === 'true' ? 'the path is a sensitive location' : undefined],
+];
+/** Which facts the rule's constraints actually referenced — only those are shown. */
+function relevantFacts(matchedRule, facts, operation) {
+    const out = [];
+    const constraintText = (matchedRule || '').toLowerCase();
+    for (const [key, words] of FACT_WORDS) {
+        const value = key === 'operation' ? (facts.operation || operation) : facts[key];
+        if (!value)
+            continue;
+        // Operation is always the reason a per-operation rule fired; other facts
+        // are shown only when the constraint text mentions them.
+        if (key !== 'operation' && !constraintText.includes(key.toLowerCase()))
+            continue;
+        const line = words(value, facts);
+        if (line)
+            out.push(line);
+    }
+    return out;
+}
+/** A verdict reason worth showing: not empty, not the engine's own restatement of the rule line. */
+function informativeReason(reason, policyName) {
+    const text = (reason || '').replace(/\s+/g, ' ').trim();
+    if (!text)
+        return undefined;
+    if (/^Action policy "/i.test(text))
+        return undefined; // engine boilerplate: `Action policy "<name>": DELETE blocked`
+    if (text.toLowerCase() === policyName.toLowerCase())
+        return undefined;
+    return shorten(text.replace(/[.\s]+$/, ''), 200);
+}
+function policiesLink(consoleUrl, policyId) {
+    return `${consoleUrl}/agent-security/users?view=policies&rules=mcp${policyId ? `&policy=${encodeURIComponent(policyId)}` : ''}`;
+}
+function shellRulesLink(consoleUrl, itemId) {
+    return `${consoleUrl}/agent-security/users?view=policies&rules=shell${itemId ? `&rule=${encodeURIComponent(itemId)}` : ''}`;
+}
+function machineLink(consoleUrl, machineId) {
+    return machineId ? `${consoleUrl}/agent-security/machines/${encodeURIComponent(machineId)}` : undefined;
+}
+function buildBlockExplanation(input) {
+    const noun = eventNoun(input.event);
+    const what = summarizeAction(input.event, input.toolName, input.toolArgs || {});
+    const consoleUrl = input.consoleUrl.replace(/\/$/, '');
+    const machine = machineLink(consoleUrl, input.machineId);
+    let rule;
+    let why;
+    let unblock;
+    let consoleLink;
+    const src = input.source;
+    if (src.kind === 'policy') {
+        const name = src.policyName || 'an Action Policy';
+        consoleLink = policiesLink(consoleUrl, src.policyId);
+        rule = `Action Policy "${name}" (${scopeWords(src.scope, input.developerName)})${src.matchedRule ? ` — rule: ${src.matchedRule}` : ''}`;
+        const facts = relevantFacts(src.matchedRule, src.facts || {}, src.operation);
+        const extraReason = informativeReason(src.reason, name);
+        if (extraReason)
+            facts.push(extraReason);
+        why = facts.length ? facts.join('; ') : `the ${noun} matched this rule`;
+        unblock = [
+            `Open the rule in the console: ${consoleLink}`,
+            src.scope === 'organization' || !src.scope
+                ? `An admin can switch "${name}" to Ask the developer / Warn only, add an exception for ${input.developerName || 'this machine'} (Override), or Disable it.`
+                : `An admin can change or remove the local rule "${name}" for ${input.developerName || 'this machine'}.`,
+            ...(machine ? [`See this decision, with the rule name, on your machine timeline: ${machine}`] : []),
+            'Wrong block? Tell your admin the rule name above — every decision is recorded, nothing was sent anywhere.',
+        ];
+    }
+    else if (src.kind === 'local_safety') {
+        const label = src.label || src.itemId;
+        consoleLink = shellRulesLink(consoleUrl, src.itemId);
+        // Same words as the console: a built-in catalog rule vs a rule an admin wrote.
+        const detail = [label !== src.itemId ? `id ${src.itemId}` : '', src.category || ''].filter(Boolean).join(', ');
+        rule = src.source === 'custom'
+            ? `org custom rule "${label}" in Local Safety${detail ? ` (${detail})` : ''}`
+            : `built-in Local Safety rule "${label}"${detail ? ` (${detail})` : ''}`;
+        why = src.explanation ? `${src.reason} — ${src.explanation}` : src.reason;
+        unblock = [
+            `Open the rule in the console: ${consoleLink}`,
+            `An admin can set "${label}" to Ask the developer, Warn only, or Off — for everyone or only for ${input.developerName || 'this machine'}.`,
+            ...(machine ? [`See this decision, with the rule name, on your machine timeline: ${machine}`] : []),
+            'Wrong block? Tell your admin the rule name above — every decision is recorded, nothing was sent anywhere.',
+        ];
+    }
+    else {
+        consoleLink = machine || `${consoleUrl}/agent-security/users?view=machines`;
+        switch (src.kind) {
+            case 'taint':
+                rule = `FullCourtDefense taint guard${src.ruleId ? ` (${src.ruleId})` : ''}`;
+                why = src.reason;
+                unblock = [
+                    'The agent tried to act on content it received from an untrusted source (tool output, web page, file).',
+                    'If you want this action, run it yourself from your own terminal — the guard only stops the agent, never you.',
+                    `Machine timeline: ${consoleLink}`,
+                ];
+                break;
+            case 'self_protection':
+                rule = `FullCourtDefense self-protection${src.ruleId ? ` (${src.ruleId})` : ''}`;
+                why = src.reason;
+                unblock = [
+                    'Agents may not approve their own actions or edit FullCourtDefense configuration.',
+                    'Do it yourself from your own terminal (fullcourtdefense approve / fullcourtdefense doctor).',
+                    `Machine timeline: ${consoleLink}`,
+                ];
+                break;
+            case 'fail_closed':
+                rule = 'Fail-closed mode (machine setting)';
+                why = src.reason;
+                unblock = [
+                    'Restore the connection to the policy service, or run: fullcourtdefense doctor',
+                    `An admin can switch this machine to fail-open under Machines: ${consoleLink}`,
+                ];
+                break;
+            case 'suspended':
+                rule = 'Machine suspended by your security team';
+                why = src.reason;
+                unblock = [`Ask your admin to resume this machine: ${consoleLink}`];
+                break;
+            default:
+                rule = 'Cached org policy (policy service unreachable)';
+                why = src.reason;
+                unblock = [
+                    'Restore the connection to the policy service, or run: fullcourtdefense doctor',
+                    `Machine page: ${consoleLink}`,
+                ];
+        }
+    }
+    if (input.note)
+        why = `${why} ${input.note}`.trim();
+    const headline = headlineFor(input.outcome, noun);
+    const userMessage = [
+        headline,
+        `What:    ${what}`,
+        `Rule:    ${rule}`,
+        `Why:     ${why}`,
+        stepsTitle(input.outcome),
+        ...unblock.map((step, i) => `  ${i + 1}. ${step}`),
+    ].join('\n');
+    const agentVerb = input.outcome === 'block' || input.outcome === 'mask'
+        ? 'This is a policy decision, not an error — do not retry, rephrase, or work around it.'
+        : 'Wait for the developer\'s answer — do not retry or work around it.';
+    const agentMessage = `${headline} Rule: ${rule}. Why: ${why}. ${agentVerb} Tell the developer exactly this: the block came from ${rule}; to remove it: ${unblock[0]}`;
+    return { headline, what, rule, why, unblock, consoleLink, userMessage, agentMessage };
+}
+/**
+ * Compact single-line form for surfaces with no room for a block (terminal
+ * `[FullCourtDefense]` line, Claude `permissionDecisionReason`).
+ */
+function oneLineExplanation(explanation) {
+    return `${explanation.headline} ${explanation.rule}. Why: ${explanation.why}. Remove it: ${explanation.consoleLink}`;
+}

package/dist/commands/cmdGuard.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Anchors of the SHARED command rules (deterministicGuard ↔ shellGuard) that
+ * are cheap enough to wrap in cmd: `gh`, `vault`, `security`, … — derived, not
+ * hand-listed, so a new shared rule reaches cmd's index automatically unless
+ * its command is on the high-frequency diet above. cmd stays PARTIAL by
+ * construction (first token only, no `git`/`kubectl`/`aws` wrappers); the
+ * console labels it that way.
+ */
+export declare const INTERCEPTED_COMMANDS: string[];
 export declare function buildGuardJs(nodePath: string, cliEntry: string): string;
 export interface CmdGuardStatus {
     supported: boolean;

package/dist/commands/cmdGuard.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTERCEPTED_COMMANDS = void 0;
 exports.buildGuardJs = buildGuardJs;
 exports.isCmdGuardInstalled = isCmdGuardInstalled;
 exports.getCmdGuardStatus = getCmdGuardStatus;
@@ -45,6 +46,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const shellGuard_1 = require("./shellGuard");
+const notify_1 = require("../notify");
 /**
  * Interactive cmd.exe guard — blocks dangerous commands TYPED in Command Prompt.
  *
@@ -75,7 +77,7 @@ const AUTORUN_MARKER = 'fullcourtdefense-cmd-autorun.bat';
  * so pipes/`&&` chains where the dangerous command is not first are NOT caught by
  * cmd (they ARE under PowerShell/zsh/bash and `shell-guard-check`).
  */
-const INTERCEPTED_COMMANDS = [
+const FIXED_INTERCEPTED_COMMANDS = [
     // Destructive filesystem / disk / permission tampering
     'del', 'erase', 'rd', 'rmdir', 'format', 'cipher', 'diskpart', 'fsutil',
     'takeown', 'icacls', 'attrib', 'compact',
@@ -97,8 +99,25 @@ const INTERCEPTED_COMMANDS = [
  * Coverage is NOT lost where it matters: agent-driven commands go through the
  * IDE hooks (full ruleset, any position in the line), and humans typing in
  * PowerShell are covered in-process by the PSReadLine guard. Interactive
- * cmd.exe keeps only the rare, high-signal destructive/tamper commands above.
+ * cmd.exe keeps only the rare, high-signal destructive/tamper commands above
+ * plus the low-frequency anchors of the shared command rules (below).
  */
+const CMD_HIGH_FREQUENCY_COMMANDS = new Set([
+    'docker', 'git', 'kubectl', 'aws', 'gcloud', 'az', 'terraform', 'pulumi', 'wsl',
+    'curl', 'wget', 'taskkill', 'robocopy', 'xcopy', 'psql', 'mysql', 'mongo', 'mongosh', 'sqlcmd',
+]);
+/**
+ * Anchors of the SHARED command rules (deterministicGuard ↔ shellGuard) that
+ * are cheap enough to wrap in cmd: `gh`, `vault`, `security`, … — derived, not
+ * hand-listed, so a new shared rule reaches cmd's index automatically unless
+ * its command is on the high-frequency diet above. cmd stays PARTIAL by
+ * construction (first token only, no `git`/`kubectl`/`aws` wrappers); the
+ * console labels it that way.
+ */
+exports.INTERCEPTED_COMMANDS = Array.from(new Set([
+    ...FIXED_INTERCEPTED_COMMANDS,
+    ...(0, shellGuard_1.builtinRuleCommandNames)().filter(name => !CMD_HIGH_FREQUENCY_COMMANDS.has(name)),
+]));
 function regString(key, value) {
     try {
         const out = (0, child_process_1.execFileSync)('reg', ['query', key, '/v', value], {
@@ -129,6 +148,9 @@ function buildGuardJs(nodePath, cliEntry) {
         `const NODE_PATH=${JSON.stringify(nodePath)};`,
         `const CLI_ENTRY=${JSON.stringify(cliEntry)};`,
         `const ASK_TIMEOUT_S=${shellGuard_1.SHELL_ASK_TIMEOUT_SECONDS};const ASK_REMEMBER_MS=${shellGuard_1.SHELL_ASK_REMEMBER_HOURS}*3600*1000;`,
+        `const RULES_URL=${JSON.stringify((0, notify_1.shellRulesConsoleUrl)())};`,
+        `// Which rule (by id + origin) and where an admin changes it — printed on every block/ask so the developer is never left guessing.`,
+        `function unblockHint(rule){return 'Rule: "'+rule.reason+'" ('+(rule.source==='custom'?'org custom rule':'built-in Local Safety rule')+', id '+rule.id+'). To remove this block an admin can set it to Ask / Warn only / Off here: '+RULES_URL+'&rule='+encodeURIComponent(rule.id);}`,
         `// "s = remember for this cmd window": keyed by the parent cmd.exe pid (doskey runs us directly under it); dies with the window, capped in time.`,
         `const ASK_MEMORY_PATH=${JSON.stringify(path.join(os.homedir(), '.fullcourtdefense'))}+'/cmd-ask-'+process.ppid+'.json';`,
         `function loadRules(){try{const raw=JSON.parse(fs.readFileSync(RULES_PATH,'utf8'));const rules=(raw.rules||[]).map(r=>{try{return{id:r.id,category:r.category,severity:r.severity,reason:r.reason,source:r.source,action:r.action==='warn'?'warn':r.action==='ask'?'ask':'block',re:new RegExp(r.pattern,'i')};}catch{return null;}}).filter(Boolean);return{mode:raw.mode==='block'?'block':'monitor',rules};}catch{return{mode:'monitor',rules:[]};}}`,
@@ -159,12 +181,14 @@ function buildGuardJs(nodePath, cliEntry) {
         `if(hit.action==='ask'){`,
         `  if(askRemembered(hit.id)){console.error('[FullCourtDefense] allowed — you confirmed rule '+hit.id+' earlier in this cmd window.');spoolEvent(hit,line,'allow','remembered');delegate(args);}`,
         `  console.error('[FullCourtDefense] ASK ['+(hit.severity||'')+']: '+hit.reason+' (rule '+hit.id+')');`,
+        `  console.error(unblockHint(hit));`,
         `  const a=askDeveloper(hit);`,
         `  if(a==='y'||a==='s'){if(a==='s')rememberAsk(hit.id);console.error('[FullCourtDefense] yes'+(a==='s'?' — remembered for this cmd window.':'')+' Reported to your security dashboard as allowed by you.');spoolEvent(hit,line,'allow','confirmed');delegate(args);}`,
         `  const outcome=a==='t'?'timeout':'declined';console.error('[FullCourtDefense] '+(outcome==='timeout'?'no answer':'no')+' — this command was not executed ('+outcome+'). Reported to your security dashboard.');spoolEvent(hit,line,'block',outcome);process.exit(1);`,
         `}`,
         `console.error('[FullCourtDefense] BLOCKED ['+(hit.severity||'')+']: '+hit.reason+' (rule '+hit.id+')');`,
         `console.error('This command was not executed. Reported to your security dashboard.');`,
+        `console.error(unblockHint(hit));`,
         `spoolEvent(hit,line,'block');process.exit(1);`,
         ``,
     ].join('\n');
@@ -180,7 +204,7 @@ function buildGuardJs(nodePath, cliEntry) {
 function buildMacroFile(nodePath) {
     const guardJs = batQuote(GUARD_JS_PATH);
     const node = batQuote(nodePath);
-    return `${INTERCEPTED_COMMANDS.map(cmd => `${cmd}=${node} ${guardJs} ${cmd} $*`).join('\r\n')}\r\n`;
+    return `${exports.INTERCEPTED_COMMANDS.map(cmd => `${cmd}=${node} ${guardJs} ${cmd} $*`).join('\r\n')}\r\n`;
 }
 function buildAutorunBat(nodePath) {
     const guardJs = batQuote(GUARD_JS_PATH);

package/dist/commands/deterministicGuard.d.ts

@@ -69,6 +69,41 @@ export interface LocalSafetyScanOptions {
      */
     trustedScriptPaths?: string[];
 }
+/**
+ * Built-ins that ship OFF until an org switches them on in the console. Shared
+ * with the terminal guards so a machine with no snapshot yet (fresh install,
+ * wiped cache) enforces the SAME default set in the IDE and in a shell.
+ */
+export declare const DEFAULT_DISABLED_BUILT_INS: ReadonlySet<string>;
+/**
+ * One command rule shared by EVERY surface that can see a typed command: the
+ * IDE/agent hooks (this module), the PowerShell / bash / zsh profile guards and
+ * the cmd.exe doskey guard (shellGuard.ts loads this table into the terminal
+ * rule file verbatim). `pattern` is a regex SOURCE that must compile — and
+ * mean the same thing — under both JS and .NET with IgnoreCase: `\b`, `\s`,
+ * `(?:…)`, lookaheads and `[^\n;|&]` only. No lookbehind, no named groups,
+ * no `\d`-class differences. `commands` are the leading binaries a rule can
+ * fire on — the only thing a first-token hook (doskey) can key on.
+ */
+export interface SharedCommandRule {
+    itemId: string;
+    /** Catalog category id (local-safety-catalog.ts). */
+    categoryId: 'credential_commands';
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    pattern: string;
+    reason: string;
+    /** Leading command names this rule anchors on (for name-keyed hooks such as cmd.exe doskey). */
+    commands: string[];
+}
+/**
+ * Commands that PRINT stored credentials to stdout — the file-path rules are
+ * useless against them because the secret never comes from a watched file
+ * ("gh auth token" emits the same token that lives in hosts.yml). Obvious,
+ * rarely-legitimate-for-agents forms are on by default; cloud token printers
+ * that legitimate deploy tooling uses constantly are strict (off by default,
+ * see DEFAULT_DISABLED_BUILT_INS). Ids match local-safety-catalog.ts.
+ */
+export declare const CREDENTIAL_COMMAND_RULES: readonly SharedCommandRule[];
 export declare function stripInertDataSegments(text: string): string;
 export declare function scanDeterministicToolCall(toolName: string, toolArgs: Record<string, unknown>, options?: LocalSafetyScanOptions): DeterministicFinding | undefined;
 export declare function scanDeterministicTextResponse(text: string, options?: LocalSafetyScanOptions): DeterministicFinding | undefined;

package/dist/commands/deterministicGuard.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREDENTIAL_COMMAND_RULES = exports.DEFAULT_DISABLED_BUILT_INS = void 0;
 exports.toLocalSafetyRuleAction = toLocalSafetyRuleAction;
 exports.stripInertDataSegments = stripInertDataSegments;
 exports.scanDeterministicToolCall = scanDeterministicToolCall;
@@ -189,7 +190,12 @@ const SQL_KEYS = new Set([
     'toolArgs.query',
     'toolArgs.sql',
 ]);
-const DEFAULT_DISABLED_BUILT_INS = new Set([
+/**
+ * Built-ins that ship OFF until an org switches them on in the console. Shared
+ * with the terminal guards so a machine with no snapshot yet (fresh install,
+ * wiped cache) enforces the SAME default set in the IDE and in a shell.
+ */
+exports.DEFAULT_DISABLED_BUILT_INS = new Set([
     'git_clean_force',
     'generic_kubectl_delete',
     'truncate_table',
@@ -413,7 +419,7 @@ function collectStrings(value, keyPath = 'args', out = [], depth = 0) {
     return out;
 }
 function disabled(options) {
-    return new Set(options?.disabledBuiltInItemIds || Array.from(DEFAULT_DISABLED_BUILT_INS));
+    return new Set(options?.disabledBuiltInItemIds || Array.from(exports.DEFAULT_DISABLED_BUILT_INS));
 }
 function isEnabled(itemId, options) {
     return !disabled(options).has(itemId);
@@ -587,39 +593,47 @@ function containsSensitiveCredentialPath(value) {
  * useless against them because the secret never comes from a watched file
  * ("gh auth token" emits the same token that lives in hosts.yml). Obvious,
  * rarely-legitimate-for-agents forms are on by default; cloud token printers
- * that legitimate deploy tooling uses constantly are strict (off by default).
+ * that legitimate deploy tooling uses constantly are strict (off by default,
+ * see DEFAULT_DISABLED_BUILT_INS). Ids match local-safety-catalog.ts.
  */
+exports.CREDENTIAL_COMMAND_RULES = [
+    { itemId: 'gh_auth_token_cmd', categoryId: 'credential_commands', severity: 'critical', commands: ['gh'],
+        reason: 'GitHub CLI token print (gh auth token)',
+        pattern: String.raw `\bgh\s+auth\s+token\b|\bgh\s+auth\s+status\b(?=[^\n;|&]*(?:--show-token|\s-t\b))` },
+    { itemId: 'git_credential_fill', categoryId: 'credential_commands', severity: 'critical', commands: ['git'],
+        reason: 'git credential helper dump',
+        pattern: String.raw `\bgit\s+credential(?:-manager|-store|-cache)?\s+(?:fill|get)\b` },
+    { itemId: 'macos_keychain_dump', categoryId: 'credential_commands', severity: 'critical', commands: ['security'],
+        reason: 'macOS keychain password dump',
+        pattern: String.raw `\bsecurity\s+(?:find-generic-password|find-internet-password)\b[^\n;|&]*\s-w\b|\bsecurity\s+dump-keychain\b` },
+    { itemId: 'kubectl_config_raw', categoryId: 'credential_commands', severity: 'high', commands: ['kubectl'],
+        reason: 'raw kubeconfig dump (kubectl config view --raw)',
+        pattern: String.raw `\bkubectl\s+config\s+view\b[^\n;|&]*--raw\b` },
+    { itemId: 'aws_export_credentials', categoryId: 'credential_commands', severity: 'critical', commands: ['aws'],
+        reason: 'AWS secret access key export',
+        pattern: String.raw `\baws\s+configure\s+export-credentials\b|\baws\s+configure\s+get\b[^\n;|&]*secret` },
+    { itemId: 'gcloud_access_token_cmd', categoryId: 'credential_commands', severity: 'high', commands: ['gcloud'],
+        reason: 'gcloud access-token print',
+        pattern: String.raw `\bgcloud\s+auth\b[^\n;|&]*\bprint-access-token\b` },
+    { itemId: 'gcloud_secret_access_cmd', categoryId: 'credential_commands', severity: 'high', commands: ['gcloud'],
+        reason: 'GCP Secret Manager read',
+        pattern: String.raw `\bgcloud\s+secrets\s+versions\s+access\b` },
+    { itemId: 'az_access_token_cmd', categoryId: 'credential_commands', severity: 'high', commands: ['az'],
+        reason: 'Azure access-token print',
+        pattern: String.raw `\baz\s+account\s+get-access-token\b` },
+    { itemId: 'aws_secret_fetch_cmd', categoryId: 'credential_commands', severity: 'high', commands: ['aws'],
+        reason: 'AWS secret fetch',
+        pattern: String.raw `\baws\s+secretsmanager\s+get-secret-value\b|\baws\s+ssm\s+get-parameter\b[^\n;|&]*--with-decryption\b` },
+    { itemId: 'vault_read_cmd', categoryId: 'credential_commands', severity: 'high', commands: ['vault'],
+        reason: 'Vault secret read',
+        pattern: String.raw `\bvault\s+(?:kv\s+get|read)\b` },
+];
+const CREDENTIAL_COMMAND_REGEXES = exports.CREDENTIAL_COMMAND_RULES.map(rule => ({ rule, re: new RegExp(rule.pattern, 'i') }));
 function credentialCommandReason(value) {
-    return matchCommand(value, (_text, lower) => {
-        if (/\bgh\s+auth\s+token\b/.test(lower) || (/\bgh\s+auth\s+status\b/.test(lower) && /(?:--show-token|\s-t\b)/.test(lower))) {
-            return { itemId: 'gh_auth_token_cmd', reason: 'GitHub CLI token print (gh auth token)' };
-        }
-        if (/\bgit\s+credential(?:-manager|-store|-cache)?\s+(?:fill|get)\b/.test(lower)) {
-            return { itemId: 'git_credential_fill', reason: 'git credential helper dump' };
-        }
-        if (/\bsecurity\s+(?:find-generic-password|find-internet-password)\b[^\n;|&]*\s-w\b/.test(lower) || /\bsecurity\s+dump-keychain\b/.test(lower)) {
-            return { itemId: 'macos_keychain_dump', reason: 'macOS keychain password dump' };
-        }
-        if (/\bkubectl\s+config\s+view\b[^\n;|&]*--raw\b/.test(lower)) {
-            return { itemId: 'kubectl_config_raw', reason: 'raw kubeconfig dump (kubectl config view --raw)' };
-        }
-        if (/\baws\s+configure\s+export-credentials\b/.test(lower) || /\baws\s+configure\s+get\b[^\n;|&]*secret/.test(lower)) {
-            return { itemId: 'aws_export_credentials', reason: 'AWS secret access key export' };
-        }
-        if (/\bgcloud\s+auth\b[^\n;|&]*\bprint-access-token\b/.test(lower)) {
-            return { itemId: 'gcloud_access_token_cmd', reason: 'gcloud access-token print' };
-        }
-        if (/\bgcloud\s+secrets\s+versions\s+access\b/.test(lower)) {
-            return { itemId: 'gcloud_secret_access_cmd', reason: 'GCP Secret Manager read' };
-        }
-        if (/\baz\s+account\s+get-access-token\b/.test(lower)) {
-            return { itemId: 'az_access_token_cmd', reason: 'Azure access-token print' };
-        }
-        if (/\baws\s+secretsmanager\s+get-secret-value\b/.test(lower) || /\baws\s+ssm\s+get-parameter\b[^\n;|&]*--with-decryption\b/.test(lower)) {
-            return { itemId: 'aws_secret_fetch_cmd', reason: 'AWS secret fetch' };
-        }
-        if (/\bvault\s+(?:kv\s+get|read)\b/.test(lower)) {
-            return { itemId: 'vault_read_cmd', reason: 'Vault secret read' };
+    return matchCommand(value, text => {
+        for (const { rule, re } of CREDENTIAL_COMMAND_REGEXES) {
+            if (re.test(text))
+                return { itemId: rule.itemId, reason: rule.reason };
         }
         return undefined;
     });
@@ -1190,7 +1204,7 @@ function scanReferencedScript(command, cwd, options) {
         while (finding
             && (finding.category === 'sensitive_file' || finding.category === 'metadata_ssrf')
             && !scriptActsOnFinding(content, finding.category)) {
-            const baseDisabled = scanOptions?.disabledBuiltInItemIds || Array.from(DEFAULT_DISABLED_BUILT_INS);
+            const baseDisabled = scanOptions?.disabledBuiltInItemIds || Array.from(exports.DEFAULT_DISABLED_BUILT_INS);
             scanOptions = { ...(scanOptions || {}), disabledBuiltInItemIds: [...baseDisabled, finding.itemId] };
             finding = scanTextValue('script_file', content, scanOptions);
         }
@@ -1212,7 +1226,7 @@ function withRuleSuppressed(options, finding) {
             customBlocks: (options?.customBlocks || []).filter(block => block.id !== finding.itemId),
         };
     }
-    const baseDisabled = options?.disabledBuiltInItemIds || Array.from(DEFAULT_DISABLED_BUILT_INS);
+    const baseDisabled = options?.disabledBuiltInItemIds || Array.from(exports.DEFAULT_DISABLED_BUILT_INS);
     return { ...(options || {}), disabledBuiltInItemIds: [...baseDisabled, finding.itemId] };
 }
 function findingAction(finding) {