fullcourtdefense-cli 1.35.10 → 1.36.2

package/dist/askHeader.js

@@ -0,0 +1,573 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentClientLabel = agentClientLabel;
+exports.environmentTag = environmentTag;
+exports.projectsInCommand = projectsInCommand;
+exports.buildAskHeader = buildAskHeader;
+/**
+ * The header at the top of every "Ask the developer" dialog: WHO is asking, WHY
+ * it popped up in one sentence, and the facts behind it (Command, Action,
+ * Affects, Where, Token / Secret sent to, Always allow).
+ *
+ * Deterministic wording of facts the hook already has — the grant scope's cloud
+ * entries (`cloudGrant.ts`), the destination the engine derived, the rule that
+ * asked — plus literal project ids read off the command (`--project x`,
+ * `…googleapis.com/…/projects/<id>/…`). Nothing here decides anything; a field
+ * that cannot be read says "unknown". Pure: no I/O, no engine, no Node built-ins — the
+ * browser extension bundles `approvalPrompt.ts` (and so this module) for the browser.
+ */
+const commandNarrative_1 = require("./commandNarrative");
+const MAX_COMMAND = 90;
+/** The console's client names (`frontend/src/lib/activityClient.ts`): the dialog and the console name the same agent. */
+const CLIENT_LABELS = {
+    cursor: 'Cursor', codex: 'Codex', 'claude-code': 'Claude Code', 'claude-desktop': 'Claude Desktop', vscode: 'VS Code',
+    copilot: 'Copilot CLI', 'gemini-cli': 'Gemini CLI', windsurf: 'Windsurf', kiro: 'Kiro',
+};
+/** `canonicalAgentClient` aliases plus the console's. */
+const CLIENT_ALIASES = { gemini: 'gemini-cli', 'vs-code': 'vscode', 'copilot-cli': 'copilot' };
+/** The client id as the console labels it; undefined for a missing or placeholder id. */
+function agentClientLabel(raw) {
+    const id = (raw || '').trim().toLowerCase().replace(/[\s_]+/g, '-');
+    const client = CLIENT_ALIASES[id] || id;
+    if (!client || /^(?:unknown|other|custom|none)$/.test(client))
+        return undefined;
+    return CLIENT_LABELS[client] || (/^[a-z0-9][a-z0-9.-]{0,30}$/.test(client) ? client : undefined);
+}
+/** Credential rules whose secret is a token (the row says "Token sent to"). */
+const TOKEN_RULES = new Set(['gcloud_access_token_cmd', 'gh_auth_token_cmd', 'az_access_token_cmd']);
+const REMOVAL_PROGRAM = /^(?:sudo\s+)?(rm|remove-item|ri|del|erase|rmdir|rd)(?:\.exe)?\s/i;
+/**
+ * What a local removal touches, from its literal targets and the engine's own
+ * scope decision (`operation`: a workspace-scoped removal is `write`, anything
+ * wider `DELETE` — `isWorkspaceScopedRemoval`). Undefined when no target is readable.
+ */
+function localRemovalAffects(command, operation) {
+    const removals = segments(command).filter(s => REMOVAL_PROGRAM.test(s));
+    if (!removals.length)
+        return undefined;
+    const scoped = String(operation || '').toLowerCase() === 'write';
+    const parts = [];
+    let unreadable = false;
+    for (const segment of removals) {
+        for (const raw of segment.trim().split(/\s+/).slice(1)) {
+            if (/^(?:sudo|rm|remove-item|ri|del|erase|rmdir|rd)$/i.test(raw) || /^-/.test(raw) || /^\/[a-z]$/i.test(raw))
+                continue;
+            const t = raw.replace(/^["']|["']$/g, '').replace(/\\/g, '/');
+            if (/^(?:~|\$home|\$\{home\}|%userprofile%|\$env:userprofile)(?:\/+\*?)?$/i.test(t))
+                parts.push('your home folder');
+            else if (/^\/+\*?$/.test(t))
+                parts.push('the whole drive (/)');
+            else if (/^[a-z]:(?:\/+\*?)?$/i.test(t))
+                parts.push(`the whole drive (${t.slice(0, 2).toUpperCase()})`);
+            else if (/^(?:\*|\.\/+\*)$/.test(t))
+                parts.push(scoped ? 'everything in the folder the script changed into' : 'everything in the current folder');
+            else if (/[$%`(]/.test(t))
+                unreadable = true;
+            else if (!/^(?:\/|[a-z]:\/|~)/i.test(t) && !/(?:^|\/)\.\.(?:\/|$)/.test(t))
+                parts.push(scoped ? `your workspace folder ${t}` : `folder ${t}`);
+            else
+                parts.push(t);
+        }
+    }
+    const named = unique(parts).slice(0, 3);
+    if (!named.length)
+        return undefined;
+    return `${named.join(', ')}${unreadable ? ' and a path it cannot read' : ''} — can't be undone`;
+}
+const GCLOUD_VALUED = /^--(?:project|region|zone|format|configuration|account|filter|limit|image|platform|source|port|memory|cpu|service-account|location|database|instance)$/;
+const GCLOUD_SERVICE = {
+    run: 'Cloud Run', sql: 'Cloud SQL', functions: 'Cloud Function', compute: 'Compute Engine', firestore: 'Firestore',
+    secrets: 'secret', pubsub: 'Pub/Sub', container: 'GKE', storage: 'Cloud Storage', projects: 'project', artifacts: 'Artifact Registry',
+};
+function words(segment) {
+    return (segment.match(/"[^"]*"|'[^']*'|\S+/g) || []).map(w => w.replace(/^["']|["']$/g, ''));
+}
+function flag(ws, names) {
+    for (let i = 0; i < ws.length; i++) {
+        for (const name of names) {
+            if (ws[i] === name && ws[i + 1] && !ws[i + 1].startsWith('-'))
+                return ws[i + 1];
+            if (ws[i].startsWith(`${name}=`))
+                return ws[i].slice(name.length + 1);
+        }
+    }
+    return undefined;
+}
+/** A literal name, or undefined when it is computed. */
+function literalName(value) {
+    return value && !/[$`(){}%]/.test(value) ? value : undefined;
+}
+/** The resource a cloud line names: "Cloud Run service api", "bucket acme-prod-site", "deployment api in namespace payments". */
+function cloudAffects(segment, tool) {
+    const ws = words(segment);
+    const at = ws.findIndex(w => w.toLowerCase().replace(/^.*[\\/]/, '').replace(/\.(?:exe|cmd)$/, '') === tool);
+    if (at < 0)
+        return undefined;
+    const argv = ws.slice(at + 1);
+    const bucket = argv.map(w => /^(?:gs|s3):\/\/([^/\s]+)/i.exec(w)?.[1]).find(Boolean);
+    if (bucket && literalName(bucket))
+        return `bucket ${bucket}`;
+    const ns = literalName(flag(argv, ['-n', '--namespace']));
+    const inNs = ns ? ` in namespace ${ns}` : '';
+    const operands = (valued) => {
+        const out = [];
+        for (let i = 0; i < argv.length; i++) {
+            if (argv[i].startsWith('-')) {
+                if (!argv[i].includes('=') && valued.test(argv[i]))
+                    i++;
+                continue;
+            }
+            out.push(argv[i]);
+        }
+        return out;
+    };
+    if (tool === 'gcloud') {
+        const path = operands(GCLOUD_VALUED).filter(w => !/^(?:alpha|beta|preview)$/.test(w));
+        const service = GCLOUD_SERVICE[path[0] || ''];
+        const verbAt = path.findIndex(w => /^(?:delete|deploy|create|update|describe|list|set-iam-policy|add-iam-policy-binding|remove-iam-policy-binding|replace|patch|start|stop|restart|resize|rm)$/.test(w));
+        const name = verbAt >= 0 ? literalName(path[verbAt + 1]) : undefined;
+        if (!service || !name)
+            return undefined;
+        const kind = verbAt > 1 ? path[verbAt - 1].replace(/ies$/, 'y').replace(/s$/, '') : path[0] === 'run' ? 'service' : '';
+        return `${service}${kind && service !== kind ? ` ${kind}` : ''} ${name}`;
+    }
+    if (tool === 'kubectl' || tool === 'oc') {
+        const path = operands(/^(?:--context|-n|--namespace|--kubeconfig|--cluster|--user|-s|--server|--as|-f|--filename|-l|--selector|-o|--output)$/);
+        const file = literalName(flag(argv, ['-f', '--filename']));
+        if (file)
+            return `the manifests in ${file}${inNs}`;
+        const kind = literalName(path[1]);
+        const name = literalName(path[2]);
+        return kind && name ? `${kind} ${name}${inNs}` : kind ? `${kind}${inNs}` : undefined;
+    }
+    if (tool === 'helm') {
+        const path = operands(/^(?:--kube-context|-n|--namespace|--kubeconfig|-f|--values|--set|--version|--repo)$/);
+        const release = literalName(path[1]);
+        return release ? `release ${release}${inNs}` : undefined;
+    }
+    if (tool === 'az') {
+        const group = literalName(flag(argv, ['--resource-group', '-g']));
+        const name = literalName(flag(argv, ['--name', '-n']));
+        const path = operands(/^(?:--subscription|-o|--output|--query|--name|-n|--resource-group|-g)$/);
+        if (path[0] === 'group' && name)
+            return `resource group ${name}`;
+        return name ? `${path.slice(0, -1).join(' ') || 'resource'} ${name}${group ? ` in resource group ${group}` : ''}` : group ? `resource group ${group}` : undefined;
+    }
+    if (tool === 'terraform' || tool === 'tofu') {
+        const dir = literalName(argv.find(w => w.startsWith('-chdir='))?.slice(7));
+        return dir ? `the ${tool} resources in ${dir}` : undefined;
+    }
+    return undefined;
+}
+/** `cloudGrant.ts` PROJECT_ID_RE; not imported, that module reads files and the caller's env. */
+const PROJECT_ID_RE = /^(?:[a-z][a-z0-9.-]*:)?[a-z0-9][a-z0-9-]{3,62}$/;
+/** Credential-command rules (deterministicGuard `CREDENTIAL_COMMAND_RULES`) in plain words. */
+const CREDENTIAL_ACTIONS = {
+    gcloud_access_token_cmd: 'Reads a cloud access token',
+    gcloud_secret_access_cmd: 'Reads a secret value',
+    gh_auth_token_cmd: 'Reads the GitHub token',
+    git_credential_fill: 'Reads stored git credentials',
+    macos_keychain_dump: 'Reads a keychain password',
+    kubectl_config_raw: 'Reads raw Kubernetes credentials',
+    aws_export_credentials: 'Reads AWS secret keys',
+    aws_secret_fetch_cmd: 'Reads a secret value',
+    az_access_token_cmd: 'Reads an Azure access token',
+    vault_read_cmd: 'Reads a Vault secret',
+};
+/** The program a credential rule is about, to find its segment when no token printer matched. */
+const CREDENTIAL_PROGRAM = {
+    gcloud_access_token_cmd: 'gcloud', gcloud_secret_access_cmd: 'gcloud', gh_auth_token_cmd: 'gh', git_credential_fill: 'git',
+    macos_keychain_dump: 'security', kubectl_config_raw: 'kubectl', aws_export_credentials: 'aws', aws_secret_fetch_cmd: 'aws',
+    az_access_token_cmd: 'az', vault_read_cmd: 'vault',
+};
+/** Token printers found anywhere in a segment (`$t = (gcloud auth … print-access-token)`), for rules without an id. */
+const TOKEN_PRINTER_ACTIONS = [
+    { re: /\bgcloud(?:\.cmd|\.exe)?\s+(?:[\w-]+\s+)*?auth\s+(?:application-default\s+)?print-access-token\b/i, action: 'Reads a cloud access token' },
+    { re: /\bgcloud(?:\.cmd|\.exe)?\s+(?:[\w-]+\s+)*?auth\s+print-identity-token\b/i, action: 'Reads a cloud identity token' },
+    { re: /\bgh(?:\.exe)?\s+auth\s+token\b/i, action: 'Reads the GitHub token' },
+];
+const HOW_RANK = ['delete', 'permissions', 'protected', 'change', 'read'];
+/** Name tokens of a project id → environment. Deterministic, and only a hint: the dialog says "(by name)". */
+function environmentTag(projectId) {
+    const words = projectId.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    if (words.some(w => /^(?:prod|production|prd)$/.test(w)))
+        return 'production';
+    if (words.some(w => /^(?:staging|stage|stg)$/.test(w)))
+        return 'staging';
+    if (words.some(w => /^(?:dev|development|test|sandbox)$/.test(w)))
+        return 'dev';
+    return undefined;
+}
+function strongestTag(ids) {
+    const tags = ids.map(environmentTag);
+    return ['production', 'staging', 'dev'].find(tag => tags.includes(tag));
+}
+/**
+ * Statements, quote- and bracket-aware. A script block's braces separate statements
+ * (`try { $v = gcloud … }` yields `$v = gcloud …`); `@{ … }` / `${ … }` are data and stay whole.
+ */
+function segments(command) {
+    const out = [];
+    let current = '';
+    let quote = '';
+    let depth = 0;
+    const blocks = [];
+    const cut = () => { out.push(current); current = ''; };
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = '';
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '{') {
+            const block = depth === 0 && !/[@$]/.test(command[i - 1] || '');
+            blocks.push(block);
+            if (block) {
+                cut();
+                continue;
+            }
+            depth++;
+        }
+        else if (ch === '}') {
+            if (blocks.pop()) {
+                cut();
+                continue;
+            }
+            depth = Math.max(0, depth - 1);
+        }
+        else if (ch === '(' || ch === '[')
+            depth++;
+        else if (ch === ')' || ch === ']')
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && (ch === '\n' || ch === ';' || ((ch === '&' || ch === '|') && command[i + 1] === ch))) {
+            if (ch !== '\n' && ch !== ';')
+                i++;
+            cut();
+            continue;
+        }
+        current += ch;
+    }
+    cut();
+    return out.map(s => s.trim()).filter(Boolean);
+}
+/** One line; a long one keeps its head and its tail (a destination or target often comes last), cut between words. */
+function oneLine(text, max = MAX_COMMAND) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length <= max)
+        return flat;
+    let head = flat.slice(0, Math.ceil((max - 3) * 0.6));
+    let tail = flat.slice(-(max - head.length - 3));
+    const headSpace = head.lastIndexOf(' ');
+    if (headSpace > head.length * 0.6)
+        head = head.slice(0, headSpace);
+    const tailSpace = tail.indexOf(' ');
+    if (tailSpace >= 0 && tailSpace < tail.length * 0.4 && flat[flat.length - tail.length - 1] !== ' ')
+        tail = tail.slice(tailSpace + 1);
+    return `${head.trimEnd()} … ${tail.trimStart()}`;
+}
+/** Literal project ids named on the command: `--project x` / `--project=x` and Google API `projects/<id>` paths. */
+function projectsInCommand(command) {
+    const ids = [];
+    let computed = false;
+    const add = (raw) => {
+        const value = raw.replace(/^["']|["']$/g, '');
+        if (/[$`(){}%<>]/.test(value) || !PROJECT_ID_RE.test(value.toLowerCase())) {
+            computed = true;
+            return;
+        }
+        if (!ids.includes(value.toLowerCase()))
+            ids.push(value.toLowerCase());
+    };
+    for (const m of command.matchAll(/(?:^|\s)--project(?:=|\s+)("[^"]*"|'[^']*'|[^\s;|&]+)/g))
+        add(m[1]);
+    for (const m of command.matchAll(/https?:\/\/[a-z0-9.-]*googleapis\.com\/[^\s"'`]*?\bprojects\/([^/\s"'`?#]+)/gi))
+        add(m[1]);
+    return { ids, computed };
+}
+function cloudEntries(entries) {
+    return (entries || []).map(entry => entry.split('|')).filter(p => p.length >= 3 && p[0])
+        .map(([tool, how, ...rest]) => ({ tool, how, where: rest.join('|') }));
+}
+/** Nothing about where this use acts is known. */
+function whereUnknown(entry) {
+    return entry.how === '?' || !entry.where || entry.where === '?';
+}
+/** The environment names the tag reads: gcloud project, aws profile, kube context (as `cloudEntryEnvironmentNames`). */
+function environmentNames(entry) {
+    return entry.where.split(',').map(part => [part.slice(0, part.indexOf('=')), part.slice(part.indexOf('=') + 1)])
+        .filter(([key, value]) => /^(?:project|profile|context)$/.test(key) && value && value !== '?').map(([, value]) => value);
+}
+/** Where one use acts, in the header's words (as `cloudGrant.ts` whereWords): `acme-prod` / `profile dev, region eu-west-1` / `unknown`. */
+function entryWhere(entry) {
+    if (whereUnknown(entry))
+        return 'unknown';
+    if (entry.tool === 'gcloud' && entry.where.startsWith('project='))
+        return entry.where.slice(8);
+    const parts = entry.where.split(',');
+    const words = parts.filter(part => part !== 'profile-from=default').map(part => {
+        const key = part.slice(0, part.indexOf('='));
+        const value = part.slice(part.indexOf('=') + 1);
+        if (value === '?')
+            return `unknown ${key}`;
+        if (value === '-')
+            return `no ${key === 'group' ? 'resource group' : key}`;
+        if (key === 'namespace' && value === '*')
+            return 'all namespaces';
+        return `${key} ${key === 'bucket' ? value.split('+').join(' + ') : value}`;
+    }).join(', ');
+    return parts.includes('profile-from=default') ? `${words} (profile from the default config)` : words;
+}
+/** The target in the sentence: `project acme-prod` / `aws profile dev, region eu-west-1`. */
+function entryTarget(entry) {
+    if (whereUnknown(entry))
+        return undefined;
+    return entry.tool === 'gcloud' && entry.where.startsWith('project=') ? `project ${entry.where.slice(8)}` : `${entry.tool} ${entryWhere(entry)}`;
+}
+/** How a `git push` on the line is protected: forced (`--force`, `-f`, `--force-with-lease`, `+refspec`), tags / all refs, or a plain push to a protected branch. */
+function gitPushKind(command) {
+    const pushes = segments(command).filter(s => /\bgit(?:\.exe)?\b(?:\s+-C\s+\S+|\s+-c\s+\S+|\s+--?[\w-]+(?:=\S+)?)*\s+push\b/i.test(s));
+    if (pushes.some(s => /\spush\b.*(?:\s(?:--force(?:-with-lease|-if-includes)?(?:=\S*)?|-[a-z]*f[a-z]*)(?=\s|$)|\s\+[^\s+]+)/i.test(s)))
+        return 'force';
+    if (pushes.some(s => /\spush\b.*\s--(?:tags|follow-tags|all|mirror)\b/i.test(s)))
+        return 'tags';
+    return 'branch';
+}
+function strongestHow(entries) {
+    const hows = entries.map(entry => entry.how);
+    return HOW_RANK.find(how => hows.includes(how)) || hows.find(how => how.startsWith('cmd:'))
+        || hows.find(how => how && how !== '?') || (hows.includes('?') ? '?' : undefined);
+}
+function howAction(how, tools) {
+    if (how === 'delete')
+        return 'Delete';
+    if (how === 'permissions')
+        return 'Permissions change';
+    if (how === 'change')
+        return 'Change';
+    if (how === 'read')
+        return 'Read';
+    if (how === 'protected')
+        return 'Force push or push to a protected branch';
+    if (how === '?')
+        return `Runs ${tools}`;
+    if (how === 'exec')
+        return 'Runs a remote command';
+    if (how.startsWith('cmd:'))
+        return `Runs ${tools} ${how.slice(4)}`;
+    return `Runs ${tools} (${how})`;
+}
+/** The statement the decisive fact came from: the delete, the token read, the rule's program. */
+function matchedSegment(command, pick) {
+    return segments(command).find(pick);
+}
+function toolSegment(tools, how) {
+    const program = `\\b(?:${tools.map(t => t.replace(/[^\w-]/g, '')).join('|')})(?:\\.exe|\\.cmd)?\\b`;
+    if (how === 'delete')
+        return new RegExp(`${program}.*\\b(?:delete|rm|purge|destroy|uninstall|terminate-[\\w-]+|delete-[\\w-]+)\\b`, 'i');
+    if (how === 'permissions')
+        return new RegExp(`${program}.*(?:iam|policy|role|rbac|auth\\s+can-i)`, 'i');
+    return new RegExp(program, 'i');
+}
+function ruleItem(subject, detail, policy) {
+    const fromId = subject?.ruleId?.startsWith('local-safety:') ? subject.ruleId.slice('local-safety:'.length) : undefined;
+    const fromDetail = detail ? /\bid ([a-z][a-z0-9_]*)/.exec(detail)?.[1] : undefined;
+    const items = (fromId || fromDetail || policy || '').split('+').map(s => s.trim());
+    return items.find(item => CREDENTIAL_ACTIONS[item]) || items[0] || undefined;
+}
+function operationAction(operation) {
+    const op = String(operation || '').toLowerCase();
+    if (/^(?:delete|destroy|drop|remove)$/.test(op))
+        return 'Delete';
+    if (/^(?:write|update|create|send|execute_write|modify|restart)$/.test(op))
+        return 'Change';
+    if (/^(?:read|list|get|search)$/.test(op))
+        return 'Read';
+    return undefined;
+}
+function nounOf(kind, event) {
+    if (kind === 'shell command' || kind === 'terminal command' || event === 'shell')
+        return 'command';
+    if (kind)
+        return kind;
+    if (event === 'mcp')
+        return 'MCP tool call';
+    return 'action';
+}
+/** `grantNotOfferedReason` ("Always allow is not offered for gcloud deletes.") → the row's own words. */
+function alwaysNotOfferedRow(reason) {
+    if (/^Always allow is not offered for .+ deletes\.$/.test(reason))
+        return 'Not offered for deletes — each delete is confirmed.';
+    if (/^Always allow is not offered for .+ permission changes\.$/.test(reason))
+        return 'Not offered for permission changes — each one is confirmed.';
+    const needs = /^Always allow needs the (.+) on the command: (add .+)\.$/.exec(reason);
+    if (needs)
+        return `Not offered: the ${needs[1]} ${/ and /.test(needs[1]) ? 'are' : 'is'} unknown — ${needs[2]}.`;
+    return reason.replace(/^Always allow is not offered:?\s*/i, 'Not offered: ').replace(/^Not offered: for /, 'Not offered for ')
+        .replace(/^Always allow needs /, 'Not offered: needs ');
+}
+/** The `add --project` / `git push <remote> <branch>` hint the scope's refusal already names. */
+function addHint(reason, tools) {
+    const named = reason && /^Always allow needs /.test(reason) ? /: ([^:]+)\.$/.exec(reason)?.[1] : undefined;
+    return named || (tools.length === 1 && tools[0] === 'gcloud' ? 'add --project' : undefined);
+}
+function alwaysRow(input) {
+    if (input.alwaysOffered)
+        return input.alwaysCovers || 'This kind of action, on this machine.';
+    if (input.alwaysNotOffered)
+        return alwaysNotOfferedRow(input.alwaysNotOffered);
+    const off = input.subject?.alwaysOff;
+    if (off === 'org')
+        return 'Not offered: your organization turned Always allow off.';
+    if (off === 'rule')
+        return 'Not offered: this rule asks every time.';
+    return 'Not offered for this rule.';
+}
+function projectPhrase(ids, tag) {
+    const named = ids.length === 1 ? `project ${ids[0]}` : `projects ${ids.join(', ')}`;
+    return tag === 'production' ? `${named} (production)` : named;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function buildAskHeader(input) {
+    const subject = input.subject || {};
+    const command = (input.command || '').trim();
+    const shell = subject.event ? subject.event === 'shell' : /command$/.test(input.kind || '') || (!input.tool && Boolean(command));
+    const noun = nounOf(input.kind, subject.event);
+    const item = ruleItem(subject, input.ruleDetail, input.policy);
+    const credentialAction = item ? CREDENTIAL_ACTIONS[item] : undefined;
+    const cloud = cloudEntries(subject.cloud);
+    const how = cloud.length ? strongestHow(cloud) : undefined;
+    const decisiveEntries = how ? cloud.filter(entry => entry.how === how) : [];
+    const decisiveTools = unique(decisiveEntries.map(entry => entry.tool));
+    const printer = shell ? TOKEN_PRINTER_ACTIONS.find(p => p.re.test(command)) : undefined;
+    // A token read is about the token, even when the line also reaches a target not read yet (`curl` POST).
+    const credential = Boolean(credentialAction || (printer && (!how || how === '?')));
+    // Where: a credential line names the project its literal Google API URL / --project acts on;
+    // otherwise what the cloud entries name (each unknown part stays "unknown"), else a literal
+    // project on the command, else the host the action reaches.
+    const literal = shell && (credential || !cloud.length) ? projectsInCommand(command) : { ids: [], computed: false };
+    const useCloud = cloud.length > 0 && !(credential && literal.ids.length);
+    const cloudWheres = unique(cloud.map(entryWhere));
+    const names = useCloud ? unique(cloud.flatMap(environmentNames)) : literal.ids;
+    const host = subject.destinationDomain || (subject.credentialHosts || [])[0]
+        || (shell ? /https?:\/\/([a-z0-9.-]+\.[a-z]{2,})(?=[/:\s"'`]|$)/i.exec(command)?.[1]?.toLowerCase() : undefined);
+    const tag = names.length ? strongestTag(names) : undefined;
+    const hint = addHint(input.alwaysNotOffered, unique(cloud.map(entry => entry.tool)));
+    let where;
+    if (useCloud) {
+        const known = cloudWheres.filter(w => w !== 'unknown').slice(0, 3);
+        const unknown = cloudWheres.length > known.length ? `unknown${hint ? ` — ${hint}` : ''}` : '';
+        where = [known.join(known.some(w => w.includes(', ')) ? '; ' : ', '), unknown].filter(Boolean).join(' + ');
+    }
+    else if (literal.ids.length)
+        where = literal.ids.slice(0, 3).join(', ');
+    else if (literal.computed)
+        where = 'unknown — add --project';
+    else
+        where = host || (subject.event === 'mcp' || input.tool ? 'unknown' : 'this machine');
+    const whereText = tag ? `${where} · ${tag} (by name)` : where;
+    const removal = shell && !credential && !how ? localRemovalAffects(command, subject.operation) : undefined;
+    let source;
+    let action;
+    let why;
+    if (credential) {
+        source = 'credential';
+        action = credentialAction || printer.action;
+        why = `This ${noun} ${action.charAt(0).toLowerCase()}${action.slice(1)}.`;
+    }
+    else if (how) {
+        source = 'cloud';
+        const tools = decisiveTools.join(', ');
+        action = howAction(how, tools);
+        const targets = unique(decisiveEntries.map(entryTarget).filter((t) => Boolean(t))).slice(0, 3);
+        const anyUnknown = decisiveEntries.some(whereUnknown);
+        const named = targets.length ? `${targets.join('; ')}${anyUnknown ? ' and one it does not name' : ''}${tag === 'production' ? ' (production)' : ''}`
+            : decisiveTools.length === 1 && decisiveTools[0] === 'gcloud' ? 'a project it does not name' : 'an environment it does not name';
+        // A protected git push: FORCE only when the command forces (the entry cannot tell a force push from a push to main).
+        const push = how === 'protected' ? gitPushKind(command) : undefined;
+        if (push)
+            action = push === 'force' ? 'Force push' : push === 'tags' ? 'Push tags or every branch' : 'Push to a protected branch';
+        const branch = decisiveEntries.map(e => /(?:^|,)branch=([^,]+)/.exec(e.where)?.[1]).find(b => b && b !== '?');
+        const remote = decisiveEntries.map(e => /(?:^|,)remote=([^,]+)/.exec(e.where)?.[1]).find(r => r && r !== '?');
+        const verbs = {
+            '?': `runs ${tools}; where it acts could not be read`,
+            delete: `DELETES in ${named}`,
+            permissions: `CHANGES PERMISSIONS in ${named}`,
+            protected: push === 'force' ? `FORCE-PUSHES to ${named}`
+                : push === 'tags' ? `pushes tags or every branch to ${named}`
+                    : `pushes to ${branch || 'a protected branch'}${remote ? ` in git remote ${remote}` : ''}`,
+            change: `changes ${named}`,
+            read: `reads ${named}`,
+            exec: `runs a command on ${named}`,
+        };
+        const verb = verbs[how] || (how.startsWith('cmd:') ? `runs \`${tools} ${how.slice(4)}\` in ${named}` : `runs ${tools} (${how}) in ${named}`);
+        why = `This ${noun} ${verb}.`;
+    }
+    else if (removal) {
+        // A local removal: no environment (Where stays "this machine"); what it removes is the fact.
+        source = 'operation';
+        action = 'Delete';
+        why = `This ${noun} DELETES ${removal.replace(/ — can't be undone$/, '')}.`;
+    }
+    else if (operationAction(subject.operation)) {
+        source = 'operation';
+        action = operationAction(subject.operation);
+        const target = literal.ids.length ? ` ${projectPhrase(literal.ids, tag)}` : host ? ` ${host}` : '';
+        why = action === 'Delete' ? `This ${noun} DELETES${target ? ` in${target}` : ''}.`
+            : action === 'Change' ? `This ${noun} changes or sends data${target ? ` to${target}` : ''}.`
+                : `This ${noun} reads${target || ' data'}.`;
+    }
+    else {
+        source = 'rule';
+        action = /credential/i.test(input.ruleDetail || '') ? 'Credential command'
+            : input.kind ? `${input.kind.charAt(0).toUpperCase()}${input.kind.slice(1)}`
+                : input.tool ? 'Tool call' : 'Action';
+        why = input.policy ? `Rule "${oneLine(input.policy, 80)}" asks before this ${noun} runs.` : `A policy asks before this ${noun} runs.`;
+    }
+    const decisive = !shell ? undefined
+        : source === 'credential' ? matchedSegment(command, s => TOKEN_PRINTER_ACTIONS.some(p => p.re.test(s)) || (item ? new RegExp(`\\b${(CREDENTIAL_PROGRAM[item] || '\\S')}`, 'i').test(s) : false))
+            : source === 'cloud' ? (matchedSegment(command, s => toolSegment(decisiveTools, how).test(s) && !/\bgcloud\s+(?:auth|config)\b/i.test(s))
+                || matchedSegment(command, s => toolSegment(decisiveTools, 'any').test(s)))
+                : undefined;
+    const shown = decisive || (shell ? segments(command)[0] : input.tool || command) || 'unknown';
+    const affects = removal || (source === 'cloud' && decisive ? cloudAffects(decisive, decisiveTools[0]) : undefined);
+    // Where the secret goes: the credential binding's hosts (what Always allow binds), else the
+    // hosts the step list follows the token to through literal variables (`tokenDestinations`).
+    let secretSentTo;
+    let always = alwaysRow(input);
+    if (credential) {
+        const bound = subject.credentialHosts || [];
+        const followed = bound.length ? [] : (0, commandNarrative_1.tokenDestinations)(command);
+        const label = (item && TOKEN_RULES.has(item)) || (!credentialAction && printer) ? 'Token sent to' : 'Secret sent to';
+        secretSentTo = { label, value: [...bound, ...followed].slice(0, 3).join(', ') || 'unknown' };
+        // A destination IS readable, but another step on the line is not: say that, not "could not be read".
+        if ((bound.length || followed.length) && /where the credential goes could not be read/.test(input.alwaysNotOffered || '')) {
+            always = `Not offered: another step on this line could send the ${label === 'Token sent to' ? 'token' : 'secret'} somewhere the check cannot read.`;
+        }
+    }
+    const agent = agentClientLabel(subject.agentClient || input.ide);
+    const act = shell ? 'run this command' : input.tool || subject.event === 'mcp' ? 'call this tool' : /file/.test(input.kind || subject.event || '') ? 'change this file' : 'take this action';
+    return {
+        who: agent ? `Your AI agent (${agent}) wants to ${act}.` : `An unknown agent wants to ${act}.`,
+        why,
+        commandLabel: shell ? 'Command' : input.tool ? 'Tool' : 'Target',
+        command: oneLine(shown),
+        action,
+        ...(affects ? { affects } : {}),
+        ...(removal && /your home folder|the whole drive/.test(removal) ? { danger: true } : {}),
+        where,
+        ...(tag ? { tag } : {}),
+        whereText,
+        ...(secretSentTo ? { secretSentTo } : {}),
+        always,
+        source,
+    };
+}

package/dist/blockExplanation.d.ts

@@ -85,6 +85,15 @@ export interface BlockExplanation {
     /** Single paragraph for the agent: stop, do not retry, relay the message. */
     agentMessage: string;
 }
+/**
+ * The reason recorded for an action that RAN (monitor / shadow, or a Warn-only rule).
+ * Guard findings are phrased as enforced ("Blocked recursive force delete …"); a
+ * record of something that was not stopped must never say "Blocked".
+ *   would_block -> "Would block: recursive force delete …"   (monitor / shadow)
+ *   would_ask   -> "Would ask: …"                             (monitor / shadow, Ask rule)
+ *   warned      -> "Recorded: …"                              (rule set to Warn only)
+ */
+export declare function recordedReason(reason: string, kind: 'would_block' | 'would_ask' | 'warned'): 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;

package/dist/blockExplanation.js

@@ -16,6 +16,7 @@
  * tested byte-for-byte by `scripts/test-block-explanation.js`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordedReason = recordedReason;
 exports.summarizeAction = summarizeAction;
 exports.buildBlockExplanation = buildBlockExplanation;
 exports.oneLineExplanation = oneLineExplanation;
@@ -35,6 +36,19 @@ function shorten(text, max = MAX_WHAT) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
 }
+/**
+ * The reason recorded for an action that RAN (monitor / shadow, or a Warn-only rule).
+ * Guard findings are phrased as enforced ("Blocked recursive force delete …"); a
+ * record of something that was not stopped must never say "Blocked".
+ *   would_block -> "Would block: recursive force delete …"   (monitor / shadow)
+ *   would_ask   -> "Would ask: …"                             (monitor / shadow, Ask rule)
+ *   warned      -> "Recorded: …"                              (rule set to Warn only)
+ */
+function recordedReason(reason, kind) {
+    const fact = reason.trim().replace(/^(?:Blocked|Matched)\s+/, '');
+    const lead = kind === 'would_block' ? 'Would block' : kind === 'would_ask' ? 'Would ask' : 'Recorded';
+    return `${lead}: ${fact}`;
+}
 /** 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);

package/dist/callerEnv.d.ts

@@ -11,7 +11,7 @@
  *
  * Node built-ins only: this leaf is on the slim hook's warm-path module graph.
  */
-export declare const CALLER_ENV_KEYS: readonly ["FCD_HUMAN_PRESENT", "FCD_EPHEMERAL", "FULLCOURTDEFENSE_EPHEMERAL", "CI", "GITHUB_ACTIONS", "GITLAB_CI", "TF_BUILD", "JENKINS_URL", "BUILDKITE", "CIRCLECI", "DISPLAY", "WAYLAND_DISPLAY", "FCD_ASK_CHANNEL", "FCD_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "FCD_RUN_ID", "GITHUB_RUN_ID", "CI_PIPELINE_ID", "FCD_WORKLOAD_INSTANCE_ID", "CLAUDECODE", "CLAUDE_PROJECT_DIR", "VSCODE_PID", "TERM_PROGRAM", "WORKSPACE_PATH", "FCD_HOOK_IDE_TIMEOUT_MS", "FCD_TAINT_APPROVE_ONCE_DISABLED", "FCD_TAINT_APPROVAL_TIMEOUT_MS"];
+export declare const CALLER_ENV_KEYS: readonly ["FCD_HUMAN_PRESENT", "FCD_EPHEMERAL", "FULLCOURTDEFENSE_EPHEMERAL", "CI", "GITHUB_ACTIONS", "GITLAB_CI", "TF_BUILD", "JENKINS_URL", "BUILDKITE", "CIRCLECI", "DISPLAY", "WAYLAND_DISPLAY", "FCD_ASK_CHANNEL", "FCD_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "FCD_RUN_ID", "GITHUB_RUN_ID", "CI_PIPELINE_ID", "FCD_WORKLOAD_INSTANCE_ID", "CLAUDECODE", "CLAUDE_PROJECT_DIR", "VSCODE_PID", "TERM_PROGRAM", "WORKSPACE_PATH", "FCD_HOOK_IDE_TIMEOUT_MS", "FCD_TAINT_APPROVE_ONCE_DISABLED", "FCD_TAINT_APPROVAL_TIMEOUT_MS", "CLOUDSDK_CORE_PROJECT", "CLOUDSDK_ACTIVE_CONFIG_NAME", "CLOUDSDK_CONFIG", "APPDATA", "AWS_PROFILE", "AWS_DEFAULT_PROFILE", "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_ACCESS_KEY_ID", "KUBECONFIG", "HELM_KUBECONTEXT", "HELM_NAMESPACE", "HELM_KUBEAPISERVER", "HELM_KUBETOKEN", "HELM_KUBEASUSER", "DOCKER_HOST", "DOCKER_CONTEXT", "AZURE_CONFIG_DIR", "AZURE_DEFAULTS_GROUP", "TF_WORKSPACE", "TF_DATA_DIR", "PGHOST", "PGDATABASE", "PGSERVICE", "MYSQL_HOST"];
 export type CallerEnvSnapshot = Partial<Record<(typeof CALLER_ENV_KEYS)[number], string>>;
 /** The keys above that are set in `env` — what the thin client sends. */
 export declare function snapshotCallerEnv(env?: NodeJS.ProcessEnv): CallerEnvSnapshot;

package/dist/callerEnv.js

@@ -34,6 +34,20 @@ exports.CALLER_ENV_KEYS = [
     'CLAUDECODE', 'CLAUDE_PROJECT_DIR', 'VSCODE_PID', 'TERM_PROGRAM', 'WORKSPACE_PATH',
     // Human-wait budget and approve-once switches.
     'FCD_HOOK_IDE_TIMEOUT_MS', 'FCD_TAINT_APPROVE_ONCE_DISABLED', 'FCD_TAINT_APPROVAL_TIMEOUT_MS',
+    // Which GCP project a gcloud line targets when it names none (cloudGrant.activeGcloudProject).
+    'CLOUDSDK_CORE_PROJECT', 'CLOUDSDK_ACTIVE_CONFIG_NAME', 'CLOUDSDK_CONFIG', 'APPDATA',
+    // Which aws profile / region and which kube context an aws / kubectl / helm line targets
+    // (cloudGrantTools). AWS_ACCESS_KEY_ID only says static keys override every profile.
+    'AWS_PROFILE', 'AWS_DEFAULT_PROFILE', 'AWS_REGION', 'AWS_DEFAULT_REGION', 'AWS_CONFIG_FILE', 'AWS_SHARED_CREDENTIALS_FILE', 'AWS_ACCESS_KEY_ID',
+    'KUBECONFIG', 'HELM_KUBECONTEXT', 'HELM_NAMESPACE', 'HELM_KUBEAPISERVER', 'HELM_KUBETOKEN', 'HELM_KUBEASUSER',
+    // A docker line talks to a remote daemon (grantTargets).
+    'DOCKER_HOST', 'DOCKER_CONTEXT',
+    // Which az subscription / resource group an az line falls back to (cloudGrantTools).
+    'AZURE_CONFIG_DIR', 'AZURE_DEFAULTS_GROUP',
+    // Which terraform workspace a terraform / tofu line runs in (cloudGrantTools).
+    'TF_WORKSPACE', 'TF_DATA_DIR',
+    // Which database host / name a psql / mysql line falls back to (cloudGrantTools).
+    'PGHOST', 'PGDATABASE', 'PGSERVICE', 'MYSQL_HOST',
 ];
 /** The keys above that are set in `env` — what the thin client sends. */
 function snapshotCallerEnv(env = process.env) {