fullcourtdefense-cli 1.28.0 → 1.30.0

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' };

package/dist/commands/mcpGateway.js

@@ -62,6 +62,7 @@ const runtimeConfig_1 = require("../runtimeConfig");
 const sessionLimits_1 = require("../sessionLimits");
 const telemetry_1 = require("../telemetry");
 const notify_1 = require("../notify");
+const blockExplanation_1 = require("../blockExplanation");
 const distress_1 = require("../distress");
 const policyGateHealth_1 = require("../policyGateHealth");
 const actionPolicyEngine_1 = require("../actionPolicyEngine");
@@ -869,6 +870,52 @@ class AgentGuardApi {
  * unexpected errors FAIL OPEN — the guard's own bug must never break the
  * developer's tool call.
  */
+/**
+ * Same explanation the IDE hook gives: what / which rule by name / why / how
+ * to remove it. The MCP client shows the error text to the developer, so the
+ * multi-line user message IS the block text.
+ */
+function explainGatewayStop(input) {
+    let machineId;
+    try {
+        machineId = (0, machineIdentity_1.getMachineIdentity)().machineId;
+    }
+    catch { /* ignore */ }
+    return (0, blockExplanation_1.buildBlockExplanation)({
+        outcome: input.outcome,
+        event: 'mcp',
+        toolName: input.toolName,
+        toolArgs: (input.toolArgs && typeof input.toolArgs === 'object' ? input.toolArgs : {}),
+        source: input.source,
+        consoleUrl: (0, notify_1.consoleUrl)(),
+        machineId,
+        developerName: (0, localSafetySnapshot_1.hookSnapshotIdentity)().developerName,
+        note: input.note,
+    });
+}
+function explainGatewayLocalSafety(outcome, toolName, toolArgs, finding, note) {
+    const explained = explainGatewayStop({
+        outcome, toolName, toolArgs, note,
+        source: { kind: 'local_safety', itemId: finding.itemId, category: finding.category, source: finding.source, explanation: finding.explanation, reason: finding.reason },
+    });
+    return `${explained.userMessage}\nThis is a security policy decision, not a transient error — do not retry.`;
+}
+function explainGatewayPolicy(outcome, toolName, toolArgs, 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)(toolName, (toolArgs || {}));
+        facts = inferred.context;
+        operation = inferred.operation;
+    }
+    catch { /* explanation never fails the gateway */ }
+    const explained = explainGatewayStop({
+        outcome, toolName, toolArgs, note,
+        source: { kind: 'policy', policyName: verdict.policyName, policyId: verdict.policyId, matchedRule: verdict.matchedRule, scope: policy?.scope, facts, operation, reason: verdict.reason },
+    });
+    return `${explained.userMessage}\nThis is a policy decision, not an error — do not retry.`;
+}
 function blockError(message) {
     const err = new Error(message);
     err.fcdDeliberateBlock = true;
@@ -1195,7 +1242,7 @@ class McpGatewayServer {
                             approvalScope: 'developer', confirmLatencyMs: answer.latencyMs,
                         });
                         (0, telemetry_1.triggerFlush)(true);
-                        throw blockError(`${ask.reason} (${origin} "${ask.itemId}", ${ask.ruleId}: ${ask.evidence}) — ${answer.answer === 'timeout' ? 'you did not answer the confirmation prompt in time' : 'you declined the confirmation prompt'}, so this tool call was not executed. Logged to your org's console. This is a security policy decision, not a transient error — do not retry.`);
+                        throw blockError(explainGatewayLocalSafety('block', toolName, toolArgs, ask, `${answer.answer === 'timeout' ? 'You did not answer the confirmation prompt in time' : 'You declined the confirmation prompt'}, so this tool call was not executed.`));
                     }
                 }
                 else {
@@ -1219,7 +1266,7 @@ class McpGatewayServer {
                 }
                 else {
                     this.spoolLocalFinding(localBlock, toolName, operation);
-                    throw blockError(`${localBlock.reason} (${origin} "${localBlock.itemId}", ${localBlock.ruleId}: ${localBlock.evidence}) — logged to your org's console; admins manage rules under Shield → Local Safety.${askNote} This is a security policy decision, not a transient error — do not retry.`);
+                    throw blockError(explainGatewayLocalSafety('block', toolName, toolArgs, localBlock, askNote.trim() || undefined));
                 }
             }
             // --- Machine-role session amount limits (pre-call: operation counts) ---
@@ -1316,7 +1363,7 @@ class McpGatewayServer {
                     (0, telemetry_1.spoolEvent)({ decision: 'block', toolName, operation: localOperation, reason: `local policy (block mode, local-first): ${reason}`, ruleId: local.policyName ? `action-policy:${local.policyName}` : undefined, offlineEnforced: true });
                     (0, telemetry_1.triggerFlush)(true);
                     (0, notify_1.notifyOs)({ title: 'FullCourtDefense — blocked by policy', message: `${toolName} blocked${local.policyName ? ` (${local.policyName})` : ''}.` });
-                    throw blockError(`FullCourtDefense blocked ${toolName} by org Action Policy${local.policyName ? ` "${local.policyName}"` : ''}: ${reason}. This is a policy decision, not an error — do not retry.`);
+                    throw blockError(explainGatewayPolicy('block', toolName, toolArgs, local, cachedPolicies));
                 }
                 if (local.verdict === 'log') {
                     // "Warn only": the call runs, the fleet records Warned (not a silent
@@ -1394,7 +1441,7 @@ class McpGatewayServer {
                                 : '';
                             (0, telemetry_1.spoolEvent)({ decision: 'block', toolName, operation: localOperation, reason: `local policy (offline): ${local.reason || local.verdict}`, offlineEnforced: true });
                             (0, telemetry_1.triggerFlush)(true);
-                            throw blockError(`FullCourtDefense blocked ${toolName} using the locally cached org policy${local.policyName ? ` "${local.policyName}"` : ''} while the policy service is unreachable (${detail}).${approvalNote}`);
+                            throw blockError(explainGatewayPolicy('block', toolName, toolArgs, local, cachedPolicies, `Enforced from the locally cached policy while the policy service is unreachable (${detail}).${approvalNote}`));
                         }
                         const localReason = blocking
                             ? `[monitor] local policy would ${local.verdict} (offline): ${local.reason || ''}`
@@ -1476,16 +1523,8 @@ class McpGatewayServer {
                     // and where to review it — so the developer (and the AI agent relaying the error)
                     // can tell exactly why the call was refused instead of guessing.
                     const policy = preflight.actionPolicy;
-                    const parts = [];
-                    parts.push(policy?.reason || preflight.intentEvaluation?.reasons?.[0] || `Tool call ${preflight.decision} by FullCourtDefense.`);
-                    if (policy?.policyName)
-                        parts.push(`Policy: "${policy.policyName}"`);
-                    if (policy?.matchedRule)
-                        parts.push(`Matched rule: ${policy.matchedRule}`);
-                    parts.push(`Tool: ${toolName}${operation && operation !== toolName ? ` (operation: ${operation})` : ''}`);
-                    parts.push(`Review or change this policy in the FullCourtDefense console → Agent Security → Policies.`);
-                    parts.push('This is a policy decision, not an error — do not retry.');
-                    throw blockError(parts.join(' | '));
+                    const outcome = preflight.decision === 'approval' ? 'approval' : preflight.decision === 'mask' ? 'mask' : 'block';
+                    throw blockError(explainGatewayPolicy(outcome, toolName, toolArgs, { policyName: policy?.policyName, policyId: policy?.policyId, matchedRule: policy?.matchedRule, reason: policy?.reason || preflight.intentEvaluation?.reasons?.[0] }, cachedPolicies, outcome === 'approval' ? `Approve at ${(0, notify_1.approvalsConsoleUrl)()}` : undefined));
                 }
             }
             downstreamAttempted = true;

package/dist/commands/posixShellGuard.d.ts

@@ -11,6 +11,18 @@ export declare function detectGitBash(): string | undefined;
  * Git Bash installed (bash only — no zsh there).
  */
 export declare function posixGuardSupported(): boolean;
+/** The shared Node checker: exits 97 on a confirmed block, 0 otherwise (fail-open). */
+export declare function buildGuardJs(nodePath: string, cliEntry: string): string;
+/**
+ * Shared POSIX-shell prompt for an ask hit (sourced by both the bash and zsh
+ * guards — plain POSIX/bash syntax, no ZLE). Args: <meta line> <typed line>.
+ * Returns 0 = run the command, 1 = do not. Reads ONE key from /dev/tty with a
+ * timeout; y = run once, s = run + export FCD_SHELL_ASK_OK for this shell,
+ * anything else / timeout / no tty = not executed. Every answer is reported
+ * through the checker's --record mode. Fail-strict: an ask that cannot be
+ * answered is a block, never a silent allow.
+ */
+export declare function buildAskShellFunction(shell: 'bash' | 'zsh'): string;
 export interface PosixShellGuardStatus {
     supported: boolean;
     installed: boolean;

package/dist/commands/posixShellGuard.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ASK_CODE = void 0;
 exports.detectGitBash = detectGitBash;
 exports.posixGuardSupported = posixGuardSupported;
+exports.buildGuardJs = buildGuardJs;
+exports.buildAskShellFunction = buildAskShellFunction;
 exports.getPosixShellGuardStatus = getPosixShellGuardStatus;
 exports.isPosixShellGuardInstalled = isPosixShellGuardInstalled;
 exports.installPosixShellGuardCommand = installPosixShellGuardCommand;
@@ -45,6 +47,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 macOS/Linux shell guard — real-time blocking of dangerous commands
  * TYPED by a human into bash or zsh (inside or outside the IDE).
@@ -160,6 +163,9 @@ function buildGuardJs(nodePath, cliEntry) {
         `const CLI_ENTRY=${JSON.stringify(cliEntry)};`,
         `const BLOCK_CODE=${BLOCK_CODE};`,
         `const ASK_CODE=${exports.ASK_CODE};`,
+        `const RULES_URL=${JSON.stringify((0, notify_1.shellRulesConsoleUrl)())};`,
+        `// Which rule (by id + origin) and where an admin changes it — printed on every block 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);}`,
         `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:[]};}}`,
         `// Execution view (aligned with the CLI's stripInertDataSegments): quoted spans containing whitespace are`,
         `// prose (inert) unless in a code position — interpreter -c/-Command flags, remote executors (ssh/wsl/docker`,
@@ -190,6 +196,7 @@ function buildGuardJs(nodePath, cliEntry) {
         `}`,
         `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(BLOCK_CODE);`,
         ``,
     ].join('\n');
@@ -213,6 +220,7 @@ function buildAskShellFunction(shell) {
         `  local __fcd_meta="$1" __fcd_line="$2" __fcd_tag __fcd_id __fcd_sev __fcd_reason __fcd_ans=""`,
         `  local __fcd_oldifs="$IFS"; IFS="$(printf '\\t')"; read -r __fcd_tag __fcd_id __fcd_sev __fcd_reason <<< "$__fcd_meta"; IFS="$__fcd_oldifs"`,
         `  printf '[FullCourtDefense] ASK [%s]: %s (rule %s)\\n' "$__fcd_sev" "$__fcd_reason" "$__fcd_id" >&2`,
+        `  printf 'Rule id %s — an admin can set it to Ask / Warn only / Off here: %s&rule=%s\\n' "$__fcd_id" ${shSingleQuote((0, notify_1.shellRulesConsoleUrl)())} "$__fcd_id" >&2`,
         `  # Only a shell with a REAL keyboard may be asked: stdin must be this shell's`,
         `  # terminal. A spawned / piped / embedded shell (stdin not a tty) never opens`,
         `  # /dev/tty — on MSYS that can be some OTHER window's console — it blocks now.`,

package/dist/commands/shellGuard.d.ts

@@ -51,6 +51,16 @@ export declare const SHELL_ASK_TIMEOUT_SECONDS = 30;
 export declare const SHELL_ASK_REMEMBER_HOURS = 12;
 /** Normalize a console action into what a typed-command guard can enforce. */
 export declare function toShellGuardAction(raw: unknown): ShellGuardAction;
+/**
+ * Leading command names that anchor a built-in rule — what a first-token hook
+ * (cmd.exe doskey) can key on. Derived from the shared tables so a new rule
+ * cannot be added without its command name reaching the cmd guard's index.
+ */
+/** Every built-in terminal rule id, ignoring console toggles (parity tests, docs). */
+export declare function builtinRuleIds(): string[];
+/** Every built-in terminal rule, all switched ON with default action (parity tests). */
+export declare function builtinRulesAllOn(): ShellGuardRule[];
+export declare function builtinRuleCommandNames(): string[];
 interface ShellGuardRulesFile {
     updatedAt: string;
     mode: 'block' | 'monitor';
@@ -81,6 +91,8 @@ export declare function evaluateShellCommand(line: string, rules?: ShellGuardRul
  * No-op unless the guard is installed. Never throws.
  */
 export declare function refreshShellGuardRules(): void;
+/** The profile guard script. Placeholders are substituted at install time. */
+export declare function buildGuardPs1(nodePath: string, cliEntry: string): string;
 /**
  * The user's Documents folder from the shell-folder registry entry — the one
  * place that knows about OneDrive/folder redirection. reg.exe is a plain