fullcourtdefense-cli 1.29.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.js

@@ -46,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.
  *
@@ -147,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:[]};}}`,
@@ -177,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');

package/dist/commands/hook.js

@@ -48,6 +48,7 @@ const deterministicGuard_1 = require("./deterministicGuard");
 const localSafetySnapshot_1 = require("../localSafetySnapshot");
 const taintLedger_1 = require("./taintLedger");
 const notify_1 = require("../notify");
+const blockExplanation_1 = require("../blockExplanation");
 const distress_1 = require("../distress");
 const describeError_1 = require("../describeError");
 const policyGateHealth_1 = require("../policyGateHealth");
@@ -486,7 +487,9 @@ function respondDegraded(ctx, detail, toolName, kind = 'unreachable', opts = {})
             (0, distress_1.reportDistress)('hook', authRejected ? distress_1.DISTRESS.AUTH_BROKEN : failure === 'rejected' ? distress_1.DISTRESS.BACKEND_REJECTED : distress_1.DISTRESS.HOOK_FAIL_CLOSED, `Blocking ${ctx.event} actions: ${cause} ${health.consecutiveFailures} times in a row since ${health.firstFailureAt || 'now'} (${detail})`);
             (0, telemetry_1.spoolEvent)({ decision: 'block', toolName, reason: `fail-closed: ${detail}`, offlineEnforced: true });
             (0, telemetry_1.triggerFlush)(true);
-            ctx.respond(true, `Blocked by FullCourtDefense — ${cause} (${health.consecutiveFailures}x in a row) and this machine is set to fail-closed. ${detail} ${advice}`, `FullCourtDefense could not verify this ${ctx.event} against your org policies (${detail}) and the failure is persistent, so fail-closed mode is blocking. ${advice}`);
+            const failClosedWhy = `${cause} (${health.consecutiveFailures}x in a row) and this machine is set to fail-closed. ${detail} ${advice}`;
+            const explained = explainGuardStop('fail_closed', ctx.event, { toolName: toolName || 'unknown', toolArgs: {} }, failClosedWhy);
+            ctx.respond(true, explained.userMessage, `FullCourtDefense could not verify this ${ctx.event} against your org policies (${detail}) and the failure is persistent, so fail-closed mode is blocking. ${advice} ${explained.agentMessage}`);
         }
         // Grace window: transient failure on a fail-closed machine — allow this
         // action, but record distress so the episode is visible in the console.
@@ -531,6 +534,7 @@ function tryDeveloperConfirmation(ctx, call, verdict, payload, where) {
         remember: verdict.approval?.remember ?? 'none',
         reason: verdict.reason,
         where,
+        policies: ctx.localPolicies,
     });
     if (prepared.outcome === 'allow')
         ctx.respond(false, undefined, prepared.agentMsg);
@@ -593,10 +597,15 @@ function prepareDeveloperConfirmation(event, call, payload, source) {
     });
     (0, telemetry_1.triggerFlush)(false);
     const reason = source.reason || `${call.toolName} needs your confirmation`;
+    // Name the rule in the prompt itself: a developer deciding y/n must see WHICH
+    // rule is asking and where to change it — same builder as every block.
+    const explained = source.where === 'local-safety' && source.localFinding
+        ? explainLocalSafetyStop('ask', event, call, source.localFinding)
+        : explainPolicyStop('ask', event, call, source, source.policies);
     return {
         outcome: 'ask',
-        userMsg: `FullCourtDefense${policyLabel}: ${reason}. Allow this ${event}?`,
-        agentMsg: `FullCourtDefense paused this ${event} for the developer's confirmation${policyLabel}: ${reason}. Wait for the developer's answer in the IDE prompt — do not retry or work around it.`,
+        userMsg: `${explained.userMessage}\nAllow this ${event}?`,
+        agentMsg: `FullCourtDefense paused this ${event} for the developer's confirmation${policyLabel}: ${reason}. Wait for the developer's answer in the IDE prompt — do not retry or work around it. ${explained.agentMessage}`,
     };
 }
 /**
@@ -680,7 +689,8 @@ function tryLocalPolicyEnforcement(ctx, call, detail, opts = {}) {
             : '';
         spoolCallEvent(call, { decision: 'block', reason: `local policy (offline): ${reason}`, offlineEnforced: true });
         (0, telemetry_1.triggerFlush)(true);
-        ctx.respond(true, `Blocked by FullCourtDefense${local.policyName ? ` (${local.policyName})` : ''} — enforced locally while the policy service is unreachable.${approvalNote}`, `FullCourtDefense blocked this ${ctx.event} using the locally cached org policy${local.policyName ? ` "${local.policyName}"` : ''} (${detail}).${approvalNote} Do not retry until the connection is restored or the policy allows it.`);
+        const explained = explainPolicyStop('block', ctx.event, call, local, policies, `Enforced from the locally cached policy while the policy service is unreachable (${detail}).${approvalNote}`);
+        ctx.respond(true, explained.userMessage, `${explained.agentMessage} Do not retry until the connection is restored or the policy allows it.`);
     }
     // Monitor machines land here by design (zero synchronous network calls), not
     // because anything is down — never tell the developer the service is
@@ -800,10 +810,85 @@ function machineMetadata(client = 'cursor') {
  * see/manage it" in one glance — a bare reason string left developers unable
  * to tell a built-in rule from an org policy or to find the console entry.
  */
-function localBlockUserMessage(finding) {
-    const origin = finding.source === 'custom' ? 'org custom rule' : 'built-in Local Safety rule';
-    return `Blocked by FullCourtDefense local guard — ${finding.reason}`
-        + ` [${origin} "${finding.itemId}" — logged to your org's console (machine timeline); admins manage rules under Shield → Local Safety]`;
+function localBlockUserMessage(finding, event = 'shell', call, note) {
+    return explainLocalSafetyStop('block', event, call || { toolName: 'prompt', toolArgs: {} }, finding, note).userMessage;
+}
+/** Fleet machine id for deep links — best-effort, never throws. */
+function explanationMachineId() {
+    try {
+        return (0, machineIdentity_1.getMachineIdentity)().machineId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Every stop the hook emits is explained through ONE builder (blockExplanation.ts):
+ * what was stopped, which rule BY NAME and where it came from, why it matched,
+ * and the exact console page that removes the block. Fixed templates, no prose.
+ */
+function explainPolicyStop(outcome, event, call, verdict, policies, note) {
+    const policy = verdict.policyId ? policies?.find(p => p.id === verdict.policyId) : undefined;
+    let facts = {};
+    let operation;
+    try {
+        const inferred = (0, actionPolicyEngine_1.inferToolContext)(call.toolName, call.toolArgs);
+        facts = inferred.context;
+        operation = inferred.operation;
+    }
+    catch { /* explanation must never fail the hook */ }
+    return (0, blockExplanation_1.buildBlockExplanation)({
+        outcome,
+        event,
+        toolName: call.toolName,
+        toolArgs: call.toolArgs,
+        source: {
+            kind: 'policy',
+            policyName: verdict.policyName,
+            policyId: verdict.policyId,
+            matchedRule: verdict.matchedRule,
+            scope: policy?.scope,
+            facts,
+            operation,
+            reason: verdict.reason,
+        },
+        consoleUrl: (0, notify_1.consoleUrl)(),
+        machineId: explanationMachineId(),
+        developerName: developerId(),
+        note,
+    });
+}
+function explainLocalSafetyStop(outcome, event, call, finding, note) {
+    return (0, blockExplanation_1.buildBlockExplanation)({
+        outcome,
+        event,
+        toolName: call.toolName,
+        toolArgs: call.toolArgs,
+        source: {
+            kind: 'local_safety',
+            itemId: finding.itemId,
+            category: finding.category,
+            source: finding.source,
+            explanation: finding.explanation,
+            reason: finding.reason,
+        },
+        consoleUrl: (0, notify_1.consoleUrl)(),
+        machineId: explanationMachineId(),
+        developerName: developerId(),
+        note,
+    });
+}
+function explainGuardStop(kind, event, call, reason, ruleId) {
+    return (0, blockExplanation_1.buildBlockExplanation)({
+        outcome: 'block',
+        event,
+        toolName: call.toolName,
+        toolArgs: call.toolArgs,
+        source: { kind, ruleId, reason },
+        consoleUrl: (0, notify_1.consoleUrl)(),
+        machineId: explanationMachineId(),
+        developerName: developerId(),
+    });
 }
 function spoolLocalFinding(input) {
     (0, telemetry_1.spoolEvent)({
@@ -1195,6 +1280,7 @@ async function hookCommandInner(args, config, io) {
                 remember: 'session',
                 reason: finding.reason.replace(/[.\s]+$/, ''),
                 where: 'local-safety',
+                localFinding: finding,
             });
             if (prepared.outcome === 'ask') {
                 ask = true;
@@ -1323,7 +1409,8 @@ async function hookCommandInner(args, config, io) {
                 return;
             }
             spoolLocalFinding({ finding: localBlock, toolName: 'prompt', operation: 'prompt' });
-            respond(true, localBlockUserMessage(localBlock), `FullCourtDefense blocked this prompt locally (${localBlock.ruleId}). Do not retry.`);
+            const explained = explainLocalSafetyStop('block', 'prompt', { toolName: 'prompt', toolArgs: {} }, localBlock);
+            respond(true, explained.userMessage, `FullCourtDefense blocked this prompt locally (${localBlock.ruleId}). Do not retry. ${explained.agentMessage}`);
             return;
         }
         if (localOnly) {
@@ -1357,7 +1444,8 @@ async function runTaintApproveOnce(ctx, event, call, sessId, taintFinding) {
     const hardBlock = () => {
         spoolCallEvent(call, { decision: 'block', reason: taintFinding.reason, ruleId: taintFinding.ruleId, offlineEnforced: true });
         (0, telemetry_1.triggerFlush)(true);
-        respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason}`, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} Do not retry.`);
+        const explained = explainGuardStop('taint', event, call, taintFinding.reason, taintFinding.ruleId);
+        respond(true, explained.userMessage, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} Do not retry. ${explained.agentMessage}`);
         return false;
     };
     const approveOnceEnabled = process.env.FCD_TAINT_APPROVE_ONCE_DISABLED !== 'true'
@@ -1410,10 +1498,11 @@ async function runTaintApproveOnce(ctx, event, call, sessId, taintFinding) {
         offlineEnforced: true,
     });
     (0, telemetry_1.triggerFlush)(true);
-    respond(true, `Blocked by FullCourtDefense taint guard — ${taintFinding.reason} `
-        + (outcome === 'denied'
-            ? 'You denied the approve-once request.'
-            : 'The approve-once request expired with no decision. If you want this action, re-run it and approve from your own terminal (fullcourtdefense approve).'), `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} The developer was asked and did not approve. Do not retry.`);
+    const outcomeNote = outcome === 'denied'
+        ? 'You denied the approve-once request.'
+        : 'The approve-once request expired with no decision. If you want this action, re-run it and approve from your own terminal (fullcourtdefense approve).';
+    const explained = explainGuardStop('taint', event, call, `${taintFinding.reason} ${outcomeNote}`, taintFinding.ruleId);
+    respond(true, explained.userMessage, `FullCourtDefense blocked this ${event} locally (${taintFinding.ruleId}): ${taintFinding.reason} The developer was asked and did not approve. Do not retry. ${explained.agentMessage}`);
     return false;
 }
 async function enforceActionPolicy(ctx) {
@@ -1448,7 +1537,8 @@ async function enforceActionPolicy(ctx) {
             return;
         }
         spoolLocalFinding({ finding: localBlock, toolName: call.toolName, operation: event });
-        respond(true, localBlockUserMessage(localBlock), `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry.`);
+        const explained = explainLocalSafetyStop('block', event, call, localBlock);
+        respond(true, explained.userMessage, `FullCourtDefense blocked this ${event} locally (${localBlock.ruleId}). Do not retry. ${explained.agentMessage}`);
         return;
     }
     // Local Safety rule set to "Ask the developer" (no block rule matched).
@@ -1464,7 +1554,8 @@ async function enforceActionPolicy(ctx) {
         }
         else if (!(0, devConfirm_1.isHumanPresent)()) {
             spoolLocalFinding({ finding: localAsk, toolName: call.toolName, operation: event });
-            respond(true, `${localBlockUserMessage(localAsk)} This rule asks the developer to confirm, but no developer is present on this machine (CI / ephemeral), so it is blocked.`, `FullCourtDefense blocked this ${event} locally (${localAsk.ruleId}): the rule requires the developer's confirmation and no human is present here. Do not retry.`);
+            const explained = explainLocalSafetyStop('block', event, call, localAsk, 'This rule asks the developer to confirm, but no developer is present on this machine (CI / ephemeral), so it is blocked.');
+            respond(true, explained.userMessage, `FullCourtDefense blocked this ${event} locally (${localAsk.ruleId}): the rule requires the developer's confirmation and no human is present here. Do not retry. ${explained.agentMessage}`);
             return;
         }
         else {
@@ -1483,7 +1574,8 @@ async function enforceActionPolicy(ctx) {
         }
         spoolCallEvent(call, { decision: 'block', reason: selfApproval.reason, ruleId: 'local-taint-self-approval', offlineEnforced: true });
         (0, telemetry_1.triggerFlush)(true);
-        respond(true, `Blocked by FullCourtDefense self-protection — ${selfApproval.reason}`, `FullCourtDefense blocked this ${event} locally (local-taint-self-approval): ${selfApproval.reason} Do not retry.`);
+        const explained = explainGuardStop('self_protection', event, call, selfApproval.reason, 'local-taint-self-approval');
+        respond(true, explained.userMessage, `FullCourtDefense blocked this ${event} locally (local-taint-self-approval): ${selfApproval.reason} Do not retry. ${explained.agentMessage}`);
         return;
     }
     // --- Deterministic taint tracking (local, no backend) ---
@@ -1605,7 +1697,8 @@ async function enforceActionPolicy(ctx) {
             const reason = localVerdict.reason || `${call.toolName}: blocked by org Action Policy`;
             spoolCallEvent(call, { decision: 'block', reason: `local policy (block mode, local-first): ${reason}`, offlineEnforced: true });
             (0, telemetry_1.triggerFlush)(true);
-            respond(true, `Blocked by FullCourtDefense${localVerdict.policyName ? ` (${localVerdict.policyName})` : ''} — ${reason}`, `FullCourtDefense blocked this ${event} by org Action Policy${localVerdict.policyName ? ` "${localVerdict.policyName}"` : ''}: ${reason}. This is a policy decision, not an error — do not retry.`);
+            const explained = explainPolicyStop('block', event, call, localVerdict, ctx.localPolicies);
+            respond(true, explained.userMessage, explained.agentMessage);
             return;
         }
         if (localVerdict.verdict === 'log') {
@@ -1616,7 +1709,7 @@ async function enforceActionPolicy(ctx) {
             return;
         }
         // require_approval, developer scope + human present → IDE-native ask (no org queue).
-        if (tryDeveloperConfirmation({ event, respond, shadow }, call, localVerdict, payload, 'local-first'))
+        if (tryDeveloperConfirmation({ event, respond, shadow, localPolicies: ctx.localPolicies }, call, localVerdict, payload, 'local-first'))
             return;
         // require_approval (org scope) → synchronous gate below creates the approval action.
     }
@@ -1719,7 +1812,8 @@ async function enforceActionPolicy(ctx) {
                 message: `${call.toolName} needs human approval${policyName ? ` (${policyName})` : ''}.`,
                 url: queueUrl,
             });
-            respond(true, `Approval required by FullCourtDefense${policyName ? ` (${policyName})` : ''} — ${reason}. Approve at ${queueUrl}`, `This ${event} requires human approval per Action Policy. Stop and ask the developer to approve it in the FullCourtDefense console: ${queueUrl}`);
+            const explained = explainPolicyStop('approval', event, call, { policyName, policyId: result.actionPolicy?.policyId, matchedRule: result.actionPolicy?.matchedRule, reason }, ctx.localPolicies, `Approve at ${queueUrl}`);
+            respond(true, explained.userMessage, `This ${event} requires human approval per Action Policy. Stop and ask the developer to approve it in the FullCourtDefense console: ${queueUrl}. ${explained.agentMessage}`);
             return;
         }
         // Make the wait visible on the machine: the hook process has no UI and its
@@ -1752,7 +1846,8 @@ async function enforceActionPolicy(ctx) {
         respond(false, undefined, `[FullCourtDefense shadow] would block ${call.toolName}${policyName ? ` (${policyName})` : ''}: ${reason}`);
         return;
     }
-    respond(true, `Blocked by FullCourtDefense${policyName ? ` (${policyName})` : ''} — ${reason}`, `FullCourtDefense blocked this ${event} per Action Policy: ${reason}. Do not retry.`);
+    const explained = explainPolicyStop(result.decision === 'mask' ? 'mask' : 'block', event, call, { policyName, policyId: result.actionPolicy?.policyId, matchedRule: result.actionPolicy?.matchedRule, reason }, ctx.localPolicies);
+    respond(true, explained.userMessage, explained.agentMessage);
 }
 async function waitForApproval(input) {
     const headers = { 'Content-Type': 'application/json' };