fullcourtdefense-cli 1.35.10 → 1.36.2

package/dist/actionPolicyEngine.d.ts

@@ -235,6 +235,29 @@ export declare function canonicalAgentClient(value: string): string;
  */
 export type SecretKind = 'github_token' | 'aws_access_key' | 'google_api_key' | 'openai_key' | 'slack_token' | 'jwt' | 'private_key' | 'assignment' | 'high_entropy' | 'none';
 export declare function detectSecretKind(raw: string): SecretKind;
+/**
+ * gcloud read verbs. Token printers (`print-access-token`, `print-identity-token`)
+ * are credential dumps and are deliberately absent; `cat` streams object bytes
+ * and keeps its own stricter proof (isGcloudStorageCatRead). `versions` is a
+ * GROUP (`app versions`, `secrets versions`), never a verb: as a verb it made
+ * `gcloud app versions delete` a read. `access` is `secrets versions access`.
+ */
+export declare const GCLOUD_READ_VERB_RE: RegExp;
+/** gcloud verbs that change a cloud resource. Deletes are handled apart (DELETE). */
+export declare const GCLOUD_WRITE_VERB_RE: RegExp;
+/** gcloud verbs that remove a resource or its data (`kms keys versions destroy`, `secrets versions destroy`). */
+export declare const GCLOUD_DELETE_VERB_RE: RegExp;
+/**
+ * `gcloud [--global-flag …] [alpha|beta] <group…> <verb> …` on the masked,
+ * lowercased command words: the first token after the program that is not a
+ * flag and not a lowercase group word that names a further group. gcloud
+ * groups and verbs are both lowercase words, so the walk returns the FIRST
+ * word that is a known read/write/delete verb; a value, a redirect or an
+ * unknown word before any verb ends the walk with `null` (segment stays
+ * unknown). Nothing here reads the resource operand — `gs://…`, a service
+ * name, a secret name are what the verb acts ON, not where data goes.
+ */
+export declare function gcloudVerbWord(value: string): string | null;
 export type ShellAstMode = 'off' | 'shadow' | 'primary';
 /** Structural subset of shellAst.ts ShellFacts that the engine reads. */
 export interface ShellAstFactsLike {
@@ -268,6 +291,7 @@ export interface ShellAstOperationComparison {
     agree: boolean;
 }
 export declare function setShellAstProvider(provider: ((command: string) => ShellAstFactsLike | undefined) | undefined): void;
+export declare function setRemoteControlProvider(provider: ((command: string) => string | undefined) | undefined): void;
 export declare function setShellAstMode(mode: ShellAstMode): void;
 export declare function getShellAstMode(): ShellAstMode;
 /** Shadow telemetry: the comparison recorded by the most recent top-level shell classification (consumed once). */

package/dist/actionPolicyEngine.js

@@ -24,6 +24,9 @@ __export(actionPolicyEngine_exports, {
   ACTION_POLICY_GRANT_MAX_USES: () => ACTION_POLICY_GRANT_MAX_USES,
   CONTENT_FACT_FIELDS: () => CONTENT_FACT_FIELDS,
   DEFAULT_ACTION_POLICY_APPROVAL: () => DEFAULT_ACTION_POLICY_APPROVAL,
+  GCLOUD_DELETE_VERB_RE: () => GCLOUD_DELETE_VERB_RE,
+  GCLOUD_READ_VERB_RE: () => GCLOUD_READ_VERB_RE,
+  GCLOUD_WRITE_VERB_RE: () => GCLOUD_WRITE_VERB_RE,
   MACHINE_KINDS: () => MACHINE_KINDS,
   WORKSTATION_ASK_APPROVAL: () => WORKSTATION_ASK_APPROVAL,
   approvalExceptionError: () => approvalExceptionError,
@@ -32,6 +35,7 @@ __export(actionPolicyEngine_exports, {
   detectSecretKind: () => detectSecretKind,
   effectiveApprovalScope: () => effectiveApprovalScope,
   evaluateActionPolicies: () => evaluateActionPolicies,
+  gcloudVerbWord: () => gcloudVerbWord,
   getShellAstMode: () => getShellAstMode,
   inferBundledToolContext: () => inferBundledToolContext,
   inferToolContext: () => inferToolContext,
@@ -42,6 +46,7 @@ __export(actionPolicyEngine_exports, {
   resolveApprovalOptions: () => resolveApprovalOptions,
   roleExceptionError: () => roleExceptionError,
   ruleNeedsContentFact: () => ruleNeedsContentFact,
+  setRemoteControlProvider: () => setRemoteControlProvider,
   setShellAstMode: () => setShellAstMode,
   setShellAstProvider: () => setShellAstProvider,
   takeShellAstOperationComparison: () => takeShellAstOperationComparison,
@@ -6777,6 +6782,7 @@ var OPERATION_MATCH_SKIP_FIELDS = /* @__PURE__ */ new Set([
   "tool.status",
   "operation.status",
   "agent.baseline",
+  "toolArgs.remoteControl",
   // Identity / metadata — NOT action signals. Excluded so the tool/agent name can never
   // pollute operation matching.
   "toolName",
@@ -6820,6 +6826,7 @@ var OPERATION_MATCH_SKIP_FIELDS = /* @__PURE__ */ new Set([
   // its operation/capability; the words a person typed into a title are not a verb.
   "title",
   "subject",
+  "topic",
   "description",
   "message",
   "msg",
@@ -6901,25 +6908,30 @@ function buildOperationMatchText(_toolName, context) {
     const identifierField = /^(?:id|ids|uuid|uuids|guid|guids)$/.test(fieldWords[fieldWords.length - 1]);
     if (OPERATION_MATCH_SKIP_FIELDS.has(key) || identifierField || key.startsWith("args.") || key.startsWith("request.")) continue;
     if (typeof value !== "string" || value.length === 0 || value.length > 2e3) continue;
-    const text = COMMAND_LINE_FIELDS.has(key) ? shellVerbWords(value) : value;
+    const text = COMMAND_LINE_FIELDS.has(key) ? shellVerbWords(value) : SQL_STATEMENT_FIELDS.has(key) && !SQL_EXECUTES_STRING_RE.test(value) ? maskQuotedSpans(value) : value;
     parts.push(`${key} ${text}`);
   }
   return parts.join(" ");
 }
 var COMMAND_LINE_FIELDS = /* @__PURE__ */ new Set(["command", "cmd", "commandLine", "script", "args"]);
+var SQL_STATEMENT_FIELDS = /* @__PURE__ */ new Set(["query", "sql", "statement"]);
+var SQL_EXECUTES_STRING_RE = /\b(?:exec(?:ute)?|sp_executesql|prepare)\b/i;
 var CODE_EXEC_TOOL_NAME_RE = /\b(node ?repl|repl|shell|exec|execute|terminal|command|cmd|run ?code|bash|zsh|sh|powershell|pwsh)\b/i;
 function shellVerbWords(command) {
   let lead = "";
   let first = true;
   let scriptArgs = false;
   let previousBare = "";
-  return shellCommandWords(command).split(/\s+/).filter(Boolean).map((token) => {
-    if (token === ";") {
+  let previousToken = "";
+  return shellCommandWords(command).replace(/\|/g, " | ").split(/\s+/).filter(Boolean).map((token) => {
+    const afterToken = previousToken;
+    previousToken = token;
+    if (token === ";" || token === "|") {
       lead = "";
       first = true;
       scriptArgs = false;
       previousBare = "";
-      return token;
+      return token === "|" ? "" : token;
     }
     if (scriptArgs) return "";
     const flag = /^(-{1,2})([A-Za-z][A-Za-z0-9_-]*)(?:=.*)?$/.exec(token);
@@ -6931,6 +6943,14 @@ function shellVerbWords(command) {
       return "";
     }
     if (!flag && !lead) lead = word.toLowerCase();
+    else if (!flag && PACKAGE_EXECUTORS.has(lead) && previousBare === lead) lead = word.toLowerCase();
+    if (!flag && !leading && SEARCH_PROGRAMS.has(lead)) return "";
+    if (!flag && !leading && TEST_RUNNERS.has(lead)) return "";
+    if (!flag && PACKAGE_RUNNERS.has(lead) && (previousBare === "run" || previousBare === "run-script")) {
+      scriptArgs = true;
+      return "";
+    }
+    if (!flag && VCS_PROGRAMS.has(lead) && /^(?:-[a-z]*m|--message)$/.test(afterToken)) return "";
     if (flag) {
       if (VCS_PROGRAMS.has(lead)) return "";
       const segs = word.split(/[-_]+/).filter(Boolean);
@@ -6950,6 +6970,10 @@ function shellVerbWords(command) {
   }).filter(Boolean).join(" ");
 }
 var VCS_PROGRAMS = /* @__PURE__ */ new Set(["git", "gh", "hg", "svn", "glab"]);
+var SEARCH_PROGRAMS = /* @__PURE__ */ new Set(["grep", "egrep", "fgrep", "zgrep", "rg", "ag", "ack", "findstr", "select-string", "sls"]);
+var TEST_RUNNERS = /* @__PURE__ */ new Set(["pytest", "jest", "vitest", "mocha"]);
+var PACKAGE_RUNNERS = /* @__PURE__ */ new Set(["npm", "pnpm", "yarn", "bun"]);
+var PACKAGE_EXECUTORS = /* @__PURE__ */ new Set(["npx", "bunx", "pnpx"]);
 var GH_CONFIG_RESOURCES = /* @__PURE__ */ new Set(["secret", "variable", "cache", "alias", "label", "ssh-key", "gpg-key"]);
 var SCRIPT_RUNNER_LEADS = /* @__PURE__ */ new Set([
   "bash",
@@ -7056,7 +7080,7 @@ function isHighEntropySecretToken(token, allowWordSlug = false) {
   return shannonEntropy(token) >= 4;
 }
 var SECRET_NAME = String.raw`(?:api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|bearer[_-]?token|client[_-]?secret|secret[_-]?key|secret|password|passwd|pwd|credentials?|private[_-]?key|token)`;
-var SECRET_ASSIGNMENT_RE = new RegExp(String.raw`(?:^|[^\w])[\w.-]*?${SECRET_NAME}[\\"']*\s*(?:=>|[:=])\s*[\\"']*([^\s\\"',;&|)}\]<>]{8,})`, "gi");
+var SECRET_ASSIGNMENT_RE = new RegExp(String.raw`${SECRET_NAME}[\\"']*\s*(?:=>|[:=])\s*[\\"']*([^\s\\"',;&|)}\]<>]{8,})`, "gi");
 var SECRET_FLAG_RE = /(?:^|[\s"'`;(\[{,])--?(?:password|passwd|pwd|token|api-?key|secret|client-secret|access-token)(?:=|\s+)[\\"']*([^\s\\"',;&|)}\]<>-][^\s\\"',;&|)}\]<>]{7,})/gi;
 var SECRET_FLAG_QUOTED_RE = /(?:^|[\s"'`;(\[{,])--?(?:password|passwd|pwd|token|api-?key|secret|client-secret|access-token)(?:=|\s+)\\?(["'])([^\s"'\\-][^\s"'\\]{7,})\\?\1/gi;
 function isWordPhraseWithCounters(value) {
@@ -7142,7 +7166,7 @@ var AUTH_HEADER_RE = /\b(?:bearer|basic|token|apikey|x-api-key)\s+([A-Za-z0-9._~
 function hasSecretLikeValue(value) {
   return detectSecretKind(value) !== "none";
 }
-var PII_EMAIL_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+var PII_EMAIL_RE = /(?<![A-Z0-9._%+-])[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
 var PII_EMAIL_IGNORE_RE = /(?:@(?:example\.(?:com|org|net)|test\.[a-z]+|localhost(?:\.[a-z]+)?|[\w.-]*\.(?:invalid|test|local|localdomain|example)|users\.noreply\.github\.com|noreply\.[\w.-]+|[\w.-]*\.gserviceaccount\.com|[\w.-]*\.svc\.id\.goog)$|^(?:no-?reply|noreply|do-?not-?reply|test\d*|example|user\d*|admin|root|foo|bar|baz|someone|somebody|you|me|name|first\.last|john\.doe|jane\.doe|email)@)/i;
 var PII_PHONE_RE = /(?:^|[^\w.@/:-])(\+?\(?\d{1,4}\)?[\s-]\(?\d{2,4}\)?[\s-]\d{2,4}(?:[\s-]\d{2,4}){0,2})(?![\w.@/:-])/g;
 function hasPiiLikeValue(raw) {
@@ -8088,7 +8112,7 @@ function classifyShellWords(masked, raw, lead, cwdScoped = false) {
       if (redirect && !/^\/dev\/null$|^nul$|^\$null$/i.test(redirect[1])) return "write";
       return "read";
     }
-    if (gcloudVerb === "delete") return "DELETE";
+    if (GCLOUD_DELETE_VERB_RE.test(gcloudVerb)) return "DELETE";
     if (GCLOUD_WRITE_VERB_RE.test(gcloudVerb)) return pipesIntoInterpreter ? "SHELL" : "write";
   }
   if (/^(?:kubectl\s+(?:get|describe|logs|top|config\s+(?:current-context|get-contexts|view(?!\s+--raw)))|docker\s+(?:ps|images|logs|inspect|version|info)|terraform\s+(?:plan|validate|fmt|show|state\s+list|output)|aws\s+(?:s3\s+ls|sts\s+get-caller-identity)|az\s+account\s+show|npm\s+(?:ls|list|view|outdated|--version)|node\s+--version|python3?\s+--version)\b/.test(value)) return "read";
@@ -8124,15 +8148,16 @@ function classifyShellWords(masked, raw, lead, cwdScoped = false) {
   if (SHELL_BLOCK_STRUCTURE_RE.test(value)) return "read";
   return "SHELL";
 }
-var GCLOUD_READ_VERB_RE = /^(?:describe|list|ls|get-iam-policy|get-value|get-ancestors|read|check|versions)$/;
-var GCLOUD_WRITE_VERB_RE = /^(?:create|update|patch|replace|enable|disable|deploy|apply|import|export|start|stop|restart|resume|suspend|scale|promote|migrate|rollback|add-[a-z-]+|remove-[a-z-]+|set-[a-z-]+|unset|clear|activate|revoke|copy)$/;
+var GCLOUD_READ_VERB_RE = /^(?:describe|list|ls|get-iam-policy|get-value|get-ancestors|read|check|access)$/;
+var GCLOUD_WRITE_VERB_RE = /^(?:create|update|patch|replace|enable|disable|deploy|apply|import|export|start|stop|restart|resume|suspend|scale|promote|migrate|rollback|add|add-[a-z-]+|remove-[a-z-]+|set-[a-z-]+|unset|clear|activate|revoke|copy)$/;
+var GCLOUD_DELETE_VERB_RE = /^(?:delete|destroy)$/;
 function gcloudVerbWord(value) {
   const tokens = value.split("|")[0].trim().split(/\s+/);
   if (!/^gcloud(?:\.cmd|\.exe)?$/.test(tokens.shift() || "")) return null;
   let depth = 0;
   for (const token of tokens) {
     if (token.startsWith("-")) continue;
-    if (GCLOUD_READ_VERB_RE.test(token) || GCLOUD_WRITE_VERB_RE.test(token) || token === "delete") return token;
+    if (GCLOUD_READ_VERB_RE.test(token) || GCLOUD_WRITE_VERB_RE.test(token) || GCLOUD_DELETE_VERB_RE.test(token)) return token;
     if (!/^[a-z][a-z0-9-]*$/.test(token) || ++depth > 6) return null;
   }
   return null;
@@ -8160,6 +8185,10 @@ var lastShellAstOperationComparison;
 function setShellAstProvider(provider) {
   shellAstProvider = provider;
 }
+var remoteControlProvider;
+function setRemoteControlProvider(provider) {
+  remoteControlProvider = provider;
+}
 function setShellAstMode(mode) {
   shellAstMode = mode;
 }
@@ -8309,7 +8338,7 @@ function shellCommandTextOf(toolName, args) {
   return text || void 0;
 }
 function isPowerShellReadFormatter(segment) {
-  if (/^(?:Select-Object\s+[\w., *-]+|Format-Table(?:\s+[\w., *-]+)?|Format-List(?:\s+[\w., *-]+)?|Out-Null|ConvertFrom-Json)$/i.test(segment)) return true;
+  if (/^(?:Select-Object\s+[\w., *-]+|Format-Table(?:\s+[\w., *-]+)?|Format-List(?:\s+[\w., *-]+)?|Out-Null|Out-String(?:\s+-Stream)?|ConvertFrom-Json)$/i.test(segment)) return true;
   const tokens = segment.trim().split(/\s+/);
   if (tokens.shift()?.toLowerCase() !== "convertto-json") return false;
   const seen = /* @__PURE__ */ new Set();
@@ -8378,10 +8407,11 @@ function provenCompoundDownload(command, detectedUrl) {
   return segments.every((segment) => {
     const statusRead = /^\(((?:Invoke-WebRequest|iwr)\s+[^\r\n]+)\)\.(?:StatusCode|StatusDescription|RawContentLength)$/i.exec(segment);
     if (statusRead) segment = statusRead[1];
+    segment = segment.replace(/\s+(?:[12&]?>\s*(?:\/dev\/null|\$null|nul)|2>&1)(?=\s|$)/gi, "");
     const withoutWriteOut = segment.replace(/(\s(?:-w|--write-out)\s+)(?:"[^"\r\n$`@]*"|'[^'\r\n$`@]*')/g, '$1"fcd-write-out"');
     if (/[$`{}()<>;&]/.test(withoutWriteOut)) return false;
     const pipeline = splitShellSegments(segment, true);
-    if (pipeline.slice(1).some((part) => !isPowerShellReadFormatter(part))) return false;
+    if (pipeline.slice(1).some((part) => !isPowerShellReadFormatter(part) && !(classifyShellSegment(part) === "read" && !/[a-z][a-z0-9+.-]*:\/\//i.test(part)))) return false;
     const raw = pipeline[0];
     if (isGcloudStorageCatRead(raw)) return true;
     const pieces = raw.match(/"[^"\r\n]*"|'[^'\r\n]*'|[^\s"']+/g) || [];
@@ -8425,6 +8455,13 @@ function provenCompoundDownload(command, detectedUrl) {
         continue;
       }
       if (/^-[sfSLI]+$|^--(?:silent|fail|location|head)$|^-UseBasicParsing$/.test(token)) continue;
+      if (!isCurl && /^wget/i.test(program)) {
+        if (/^-q$|^--quiet$|^-q?O-$|^--output-document=-$/.test(token)) continue;
+        if (/^-q?O$|^--output-document$/.test(token) && tokens[i2 + 1] === "-") {
+          i2++;
+          continue;
+        }
+      }
       if (/^-TimeoutSec$/i.test(token) && /^\d+$/.test(tokens[i2 + 1] || "")) {
         i2++;
         continue;
@@ -8719,9 +8756,22 @@ function inferToolContext(toolName, args) {
     context["destination.type"] = context["request.destination.type"];
     context["destination.domain"] = context["request.destination.domain"];
   }
+  applyRemoteControlFact(toolName, args, context);
   applyWebReadFacts(toolName, args, context);
   return { operation, context };
 }
+function applyRemoteControlFact(toolName, args, context) {
+  delete context["toolArgs.remoteControl"];
+  const shellText = remoteControlProvider ? shellCommandTextOf(toolName, args) : void 0;
+  if (!shellText || !remoteControlProvider) return;
+  let bridge;
+  try {
+    bridge = remoteControlProvider(shellText);
+  } catch {
+    bridge = void 0;
+  }
+  if (bridge) context["toolArgs.remoteControl"] = bridge;
+}
 var WEB_READ_TOOL_NAMES = /* @__PURE__ */ new Set(["webfetch", "fetchwebpage", "webextract"]);
 function applyWebReadFacts(toolName, args, context) {
   if (!WEB_READ_TOOL_NAMES.has(toolName.toLowerCase().replace(/[_\-.\s]/g, ""))) return;
@@ -8746,6 +8796,7 @@ function applyWebReadFacts(toolName, args, context) {
   if (isLoopbackHost(parsed.hostname)) context["destination.loopback"] = "true";
   else delete context["destination.loopback"];
 }
+var SEARCH_PATTERN_FIELDS = ["query", "q", "pattern", "search", "searchQuery", "search_query", "term", "keyword", "keywords", "regex"];
 function inferBundledToolContext(toolName, args) {
   const context = {};
   let operation = toolName;
@@ -8767,16 +8818,19 @@ function inferBundledToolContext(toolName, args) {
     if (!reservedInputFact(key)) context[key] = String(val);
   }
   const nameWords = toolNameLower.replace(/[_\-.]/g, " ");
-  const isSearchTool = /\b(search|grep|find|lookup|locate)\b/.test(nameWords) && !/\b(delete|remove|drop|write|update|insert|replace|create)\b/.test(nameWords);
-  if (isSearchTool) {
-    operation = "read";
-    if (typeof context.query === "string") {
-      context["search.pattern"] = context.query;
-      delete context.query;
+  const notMutating = !/\b(delete|remove|drop|write|update|insert|replace|create)\b/.test(nameWords);
+  const isSearchTool = /\b(search|grep|find|lookup|locate)\b/.test(nameWords) && notMutating;
+  const isFilterTool = isSearchTool || /\blist\b/.test(nameWords) && notMutating;
+  if (isSearchTool) operation = "read";
+  if (isFilterTool) {
+    const patternKeys = SEARCH_PATTERN_FIELDS.filter((key) => typeof context[key] === "string");
+    if (patternKeys.length) {
+      context["search.pattern"] = patternKeys.map((key) => context[key]).join(" ");
+      for (const key of patternKeys) delete context[key];
     }
   }
   const isCodeExecTool = operation === toolName && CODE_EXEC_TOOL_NAME_RE.test(nameWords);
-  const sqlArg = args.query || args.sql || args.statement || (isCodeExecTool ? "" : args.command || args.code || args.script || args.input) || "";
+  const sqlArg = (isFilterTool ? "" : args.query) || args.sql || args.statement || (isCodeExecTool ? "" : args.command || args.code || args.script || args.input) || "";
   if (!isSearchTool && typeof sqlArg === "string" && sqlArg.length > 0) {
     const sqlMatch = sqlArg.match(/(?<!-)\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|GRANT|REVOKE|SHOW|DESCRIBE|EXPLAIN)\b(?!-)/i);
     if (sqlMatch) {
@@ -8855,6 +8909,7 @@ function inferBundledToolContext(toolName, args) {
       context["destination.type"] = isInternalHost(context["destination.domain"]) ? "internal" : "external";
     }
   }
+  applyRemoteControlFact(toolName, args, context);
   applyWebReadFacts(toolName, args, context);
   return { operation, context };
 }
@@ -8957,6 +9012,9 @@ function inventoryToolMatchesActionPolicy(toolName, toolActions, policies) {
   ACTION_POLICY_GRANT_MAX_USES,
   CONTENT_FACT_FIELDS,
   DEFAULT_ACTION_POLICY_APPROVAL,
+  GCLOUD_DELETE_VERB_RE,
+  GCLOUD_READ_VERB_RE,
+  GCLOUD_WRITE_VERB_RE,
   MACHINE_KINDS,
   WORKSTATION_ASK_APPROVAL,
   approvalExceptionError,
@@ -8965,6 +9023,7 @@ function inventoryToolMatchesActionPolicy(toolName, toolActions, policies) {
   detectSecretKind,
   effectiveApprovalScope,
   evaluateActionPolicies,
+  gcloudVerbWord,
   getShellAstMode,
   inferBundledToolContext,
   inferToolContext,
@@ -8975,6 +9034,7 @@ function inventoryToolMatchesActionPolicy(toolName, toolActions, policies) {
   resolveApprovalOptions,
   roleExceptionError,
   ruleNeedsContentFact,
+  setRemoteControlProvider,
   setShellAstMode,
   setShellAstProvider,
   takeShellAstOperationComparison,

package/dist/approvalPrompt.d.ts

@@ -1,3 +1,5 @@
+import { type AskHeader, type AskSubject } from './askHeader';
+export type { AskHeader, AskSubject } from './askHeader';
 export interface ApprovalMessageOptions {
     /** The dialog offers "Always allow"; the footer must say what that covers. */
     allowAlways?: boolean;
@@ -5,9 +7,20 @@ export interface ApprovalMessageOptions {
     alwaysScopeLabel?: string;
     /** How long it holds: "30 days" (default) or "7 days or 20 uses". */
     alwaysLimitsLabel?: string;
+    /** What / How / Where the grant covers (compact rows). Absent: the scope label is the What. */
+    alwaysCovers?: AlwaysCovers;
+    /** Two-button ask: one short line saying why "Always allow" is not offered. */
+    alwaysNotOffered?: string;
+    /** Facts from the ask envelope (grant scope, rule id) for the "Why you're asked" header. */
+    subject?: AskSubject;
     /** Visual variant. Ask is the interactive dialog; approval/block share the card, not extra buttons. */
     tone?: DialogTone;
 }
+export interface AlwaysCovers {
+    what: string;
+    how?: string;
+    where?: string;
+}
 /** Which policy outcome this window is showing. Icons and copy follow this; buttons do not. */
 export type DialogTone = 'ask' | 'approval' | 'block';
 export interface NativeDialogView {
@@ -15,6 +28,8 @@ export interface NativeDialogView {
     badge: string;
     headline: string;
     subtitle: string;
+    /** Ask dialogs: why it popped up and the facts behind it, above everything else. */
+    header?: AskHeader;
     kind?: string;
     /** The action: the whole script when the explanation carried it, else the short "What" line. */
     action?: string;

package/dist/approvalPrompt.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.nativeDialogView = nativeDialogView;
 exports.nativeApprovalTitle = nativeApprovalTitle;
 exports.nativeApprovalMessage = nativeApprovalMessage;
+const askHeader_1 = require("./askHeader");
 /** Compact OS prompt. The complete decision remains in the IDE response and audit. */
 function line(value, limit) {
     const text = value.replace(/\s+/g, ' ').trim();
@@ -12,6 +13,23 @@ function line(value, limit) {
     const head = Math.ceil((limit - 3) * 0.6);
     return `${text.slice(0, head)} … ${text.slice(-(limit - head - 3))}`;
 }
+/** `What: gcloud · How: change · Where: project acme-staging · 30 days, this machine`. */
+function alwaysCoversParts(options) {
+    const covers = options.alwaysCovers || (options.alwaysScopeLabel ? { what: options.alwaysScopeLabel } : undefined);
+    if (!options.allowAlways || !covers)
+        return undefined;
+    return [
+        `What: ${line(covers.what, 90)}`,
+        covers.how ? `How: ${line(covers.how, 60)}` : '',
+        covers.where ? `Where: ${line(covers.where, 180)}` : '',
+        `${options.alwaysLimitsLabel || '30 days'}, this machine`,
+    ].filter(Boolean).join(' · ');
+}
+/** `Always allow covers — What: gcloud · How: change · Where: project acme-staging · 30 days, this machine`. */
+function alwaysCoversLine(options) {
+    const parts = alwaysCoversParts(options);
+    return parts ? `Always allow covers — ${parts}` : undefined;
+}
 /** The full script is shown in a scrolling box; this only guards against a runaway payload. */
 const MAX_DIALOG_SCRIPT = 6000;
 const CEILING_NOTE_RE = /\s*This policy is set to Block[.;]\s*(?:Because it is not marked "Hard block", your workstation requires your approval before continuing\.|on a developer workstation it asks you instead\.)?\s*(?:An admin can (?:review the matching rule and its scope in the console|mark it "Hard block" in the console to stop this without asking)\.)?/;
@@ -19,13 +37,72 @@ const CEILING_NOTE_SHORT = 'set to Block; on your workstation it asks you first.
 /** Parse the `Rule:` line the block explanation writes into the name the console lists and its scope. */
 function ruleParts(rule) {
     const policy = /^Action Policy "(.+?)" \((.+?)\)(?: — rule: (.+))?$/.exec(rule);
-    if (policy)
-        return { policy: policy[1], scope: [policy[2].replace(/^[^\w]+/, ''), policy[3]].filter(Boolean).join(' · ') };
+    if (policy) {
+        const scopeWords = policy[2].replace(/^[^\w]+/, '');
+        return { policy: policy[1], scopeWords, ...(policy[3] ? { matched: policy[3] } : {}), scope: [scopeWords, policy[3]].filter(Boolean).join(' · ') };
+    }
     const local = /^(built-in Local Safety rule|org custom rule) "(.+?)"(?: in Local Safety)?(?: \((.+)\))?$/.exec(rule);
     if (local)
-        return { policy: local[2], localSafety: true, scope: [local[1] === 'org custom rule' ? 'Local Safety — org custom rule' : 'Local Safety — built-in rule', local[3]].filter(Boolean).join(' · ') };
+        return { policy: local[2], localSafety: true, customRule: local[1] === 'org custom rule', ...(local[3] ? { ruleDetail: local[3] } : {}), scope: [local[1] === 'org custom rule' ? 'Local Safety — org custom rule' : 'Local Safety — built-in rule', local[3]].filter(Boolean).join(' · ') };
     return { policy: rule };
 }
+/** `toolArgs.command matches gcloud *` → "gcloud commands"; unknown shapes → undefined (the IDE message keeps the raw rule). */
+function constraintWords(constraint) {
+    const m = /^(?:toolArgs\.)?([\w.]+) (equals|matches|contains|startsWith|in|notEquals|not_contains) (.+)$/.exec(constraint.trim());
+    if (!m)
+        return undefined;
+    const [, field, op, raw] = m;
+    const value = raw.trim();
+    if (field === 'command' || field === 'cmd') {
+        const lead = value.replace(/\s*\*+\s*$/, '').trim();
+        if ((op === 'matches' || op === 'startsWith') && /^[\w.-]+(?: [\w.-]+)?$/.test(lead))
+            return `${lead} commands`;
+        if (op === 'contains')
+            return `commands that contain "${value}"`;
+        return undefined;
+    }
+    if (field === 'destination.type' && op === 'equals')
+        return `actions that reach ${value === 'external' ? 'an external' : `a ${value}`} destination`;
+    if ((field === 'destination.domain' || field === 'destination.host') && op === 'equals')
+        return `actions that reach ${value}`;
+    if (field === 'agentClient' && op === 'equals')
+        return `actions by ${value}`;
+    return undefined;
+}
+const VERDICT_WORDS = { require_approval: 'asks for approval', block: 'blocks', allow: 'allows', log: 'records', warn: 'warns' };
+const OPERATION_WORDS = { SHELL: 'shell commands', EXECUTE: 'commands', DELETE: 'deletes', write: 'writes', read: 'reads', delete: 'deletes' };
+/**
+ * The rule that asked, in customer words — never engine syntax:
+ * `Company policy "Cloud changes need OK" asks for approval on gcloud commands, for every machine.`
+ * The raw matcher (`SHELL → require_approval (toolArgs.command matches gcloud *)`) stays in
+ * the IDE message's `Rule:` line.
+ */
+function ruleSentence(f, tone) {
+    if (!f.policy || f.fallback)
+        return undefined;
+    const name = `"${line(f.policy, 80)}"`;
+    if (f.localSafety) {
+        const category = (f.ruleDetail || '').split(',').map(s => s.trim()).find(s => s && !/^id /.test(s));
+        const kind = `${f.customRule ? "Your organization's" : 'Built-in'} Local Safety rule ${name}${category ? ` (${category.replace(/_/g, ' ')})` : ''}`;
+        return `${kind} ${tone === 'block' ? 'blocks this' : tone === 'approval' ? 'needs approval for this' : 'asks before this runs'}.`;
+    }
+    const owner = /^company default/i.test(f.scopeWords || '') ? 'Company policy' : /^local rule/i.test(f.scopeWords || '') ? 'Local rule' : 'Policy';
+    const whom = /applies to (.+)$/i.exec(f.scopeWords || '')?.[1] || /only (.+)$/i.exec(f.scopeWords || '')?.[1];
+    const m = /^(\S+) → (\w+)(?: \((.*)\))?$/.exec(f.matched || '');
+    const verb = m ? VERDICT_WORDS[m[2]] || 'asks' : 'asks';
+    const on = m && m[3] ? m[3].split(/,\s*(?=[\w.]+ (?:equals|matches|contains|startsWith|in|notEquals|not_contains) )/).map(constraintWords) : [];
+    const what = on.length && on.every(Boolean) ? on.join(' and ')
+        : m && !m[3] ? unique(m[1].split('/').map(op => OPERATION_WORDS[op]).filter(Boolean)).join(' and ') || undefined
+            : undefined;
+    return `${owner} ${name} ${verb}${what ? ` on ${what}` : ''}${whom ? `, for ${whom}` : ''}.`;
+}
+/** The header sentence already states the fact the rule fired on (cloud, credential, a local removal). */
+function saysTheFact(header) {
+    return header.source === 'cloud' || header.source === 'credential' || (header.source === 'operation' && Boolean(header.affects));
+}
+function unique(values) {
+    return [...new Set(values)];
+}
 function promptFacts(reason) {
     const rows = reason.split(/\r?\n/).map(row => row.trim()).filter(Boolean);
     const field = (name) => rows.find(row => row.startsWith(`${name}:`))?.slice(name.length + 1).trim();
@@ -61,8 +138,10 @@ function promptFacts(reason) {
         facts.kind = kind?.[2];
         facts.action = kind ? kind[1] : what;
     }
-    if (tool)
+    if (tool) {
         facts.tool = [tool, evidence].filter(Boolean).join(' · ');
+        facts.toolName = tool;
+    }
     if (why) {
         const stripped = why.replace(CEILING_NOTE_RE, ' ').replace(/\s+/g, ' ').trim();
         if (stripped !== why.trim())
@@ -74,6 +153,24 @@ function promptFacts(reason) {
 function sentences(text) {
     return text.split(/(?<=\.)\s+/).map(part => part.trim()).filter(Boolean);
 }
+/** The full action text: the script when the explanation carried it, else the "What" line. */
+function actionText(f) {
+    return f.script ? f.script.replace(/ ⏎ /g, '\n') : f.action;
+}
+function askHeaderFor(f, options) {
+    return (0, askHeader_1.buildAskHeader)({
+        command: actionText(f),
+        kind: f.kind,
+        tool: f.toolName,
+        policy: f.policy,
+        ruleDetail: f.ruleDetail,
+        ide: f.ide,
+        subject: options.subject,
+        alwaysOffered: Boolean(options.allowAlways),
+        alwaysCovers: alwaysCoversParts(options),
+        alwaysNotOffered: options.alwaysNotOffered,
+    });
+}
 /**
  * Layout model for the branded OS dialog. Same facts as the compact prompt;
  * skips mockup-only chrome (other-outcome chips, Request approval, project tags).
@@ -81,8 +178,19 @@ function sentences(text) {
 function nativeDialogView(reason, options = {}) {
     const f = promptFacts(reason);
     const tone = options.tone || 'ask';
+    // Free-form text carries no facts to put in the header.
+    const header = tone === 'ask' && !f.fallback ? askHeaderFor(f, options) : undefined;
+    const because = f.because ? sentences(line(f.because, 400)) : [];
+    // The header already says the fact a cloud / credential rule fired on; the rule line only names the rule.
+    if (header && saysTheFact(header))
+        because.shift();
+    // The rule by name, its source and who it applies to — in customer words; the engine
+    // matcher stays in the IDE message. Then the fact it fired on.
+    if (because.length && /^[a-z]/.test(because[0]))
+        because[0] = `Because ${because[0]}`;
     const why = [
-        ...(f.because ? sentences(line(f.because, 400)) : []),
+        ruleSentence(f, tone) || '',
+        ...because,
         f.note ? line(f.note, 180) : '',
         f.fallback ? line(f.fallback, 400) : '',
     ].filter(Boolean);
@@ -90,13 +198,14 @@ function nativeDialogView(reason, options = {}) {
         ? ['This action is stopped.', 'An admin can change the rule in the console.']
         : tone === 'approval'
             ? ['An admin or manager can approve it in the console.', 'Closing this window does not approve it.']
+            // With a header, what Always allow covers (or why it is not offered) is its last row.
             : [
-                'Allow once lets only this action continue.',
-                'Deny or close keeps it blocked.',
-                options.allowAlways && options.alwaysScopeLabel
-                    ? `Always allow: ${line(options.alwaysScopeLabel, 180)} for ${options.alwaysLimitsLabel || '30 days'} on this machine, while the rule stays as it is written today.`
-                    : '',
+                'Allow once lets only this action run; Deny or close keeps it stopped.',
+                header ? '' : alwaysCoversLine(options) || (!options.allowAlways && options.alwaysNotOffered ? line(options.alwaysNotOffered, 120) : ''),
             ].filter(Boolean);
+    // One statement shown whole in the header's Command row: the step list and script box would repeat it.
+    const full = actionText(f)?.replace(/\s+/g, ' ').trim();
+    const shownWhole = Boolean(header && full && header.command === full);
     const footer = f.policy && !f.fallback
         ? `Full details: the IDE message and this machine’s Activity. Console → Action Policies → ${f.localSafety ? 'Source: Local Safety → ' : ''}"${line(f.policy, 80)}".`
         : 'Full details are in the IDE message and this machine’s Activity in FullCourtDefense.';
@@ -109,10 +218,11 @@ function nativeDialogView(reason, options = {}) {
             : tone === 'approval'
                 ? 'A security policy paused this action for an admin or manager.'
                 : 'A security policy paused this action. Review the details and choose what to do next.',
+        ...(header ? { header } : {}),
         kind: f.kind,
         // The whole script when we have it (the box scrolls); the short line otherwise.
-        action: f.script ? f.script.replace(/ ⏎ /g, '\n') : f.action ? line(f.action, 280) : undefined,
-        steps: (f.steps || []).slice(0, 14).map(step => line(step, 220)),
+        action: shownWhole ? undefined : f.script ? actionText(f) : f.action ? line(f.action, 280) : undefined,
+        steps: shownWhole ? [] : (f.steps || []).slice(0, 14).map(step => line(step, 220)),
         policy: f.policy ? line(f.policy, 160) : undefined,
         scope: f.scope ? line(f.scope, 220) : undefined,
         agent: f.agent ? line(f.agent, 80) : undefined,
@@ -129,17 +239,41 @@ function nativeApprovalTitle(reason) {
     const parts = ['FullCourtDefense', f.kind ? `Approval needed: ${f.kind}` : 'Approval needed', f.policy ? line(f.policy, 60) : ''].filter(Boolean);
     return parts.join(' · ');
 }
+/** The header as text rows: the sentence, then Command / Action / Where / Always allow. */
+function headerLines(header) {
+    return [
+        header.who,
+        `Why you're asked: ${header.why}`,
+        `${`${header.commandLabel}:`.padEnd(9)}${header.command}`,
+        // One line in the compact text (the card draws Affects as its own row).
+        `Action:  ${header.action}${header.affects ? ` — affects ${header.affects}` : ''}`,
+        `Where:   ${header.whereText}`,
+        ...(header.secretSentTo ? [`${header.secretSentTo.label}: ${header.secretSentTo.value}`] : []),
+        `Always allow: ${header.always}`,
+    ];
+}
 function nativeApprovalMessage(reason, options = {}) {
     const f = promptFacts(reason);
+    const header = !f.fallback && (options.tone || 'ask') === 'ask' ? askHeaderFor(f, options) : undefined;
+    // As in the card: the fact a cloud / credential rule fired on is the header's sentence, not repeated.
+    const because = header && saysTheFact(header) && f.because
+        ? sentences(f.because).slice(1).join(' ')
+        : f.because;
+    const full = actionText(f)?.replace(/\s+/g, ' ').trim();
+    const steps = header && full && header.command === full ? [] : f.steps || [];
     const details = f.fallback ? [line(f.fallback, 650)] : [
+        ...(header ? headerLines(header) : []),
         f.policy ? `Policy:  ${line(f.policy, 160)}` : '',
-        f.scope ? `         ${line(f.scope, 200)}` : '',
-        f.action ? `Action:  ${f.kind ? `${f.kind} — ` : ''}${line(f.action, 230)}` : '',
-        ...(f.steps || []).slice(0, 6).map((step, index) => `${index === 0 ? 'Does:    ' : '         '}${index + 1}. ${line(step, 160)}`),
+        // Where the rule comes from, in customer words (the raw matcher is on the IDE message's Rule: line).
+        f.policy ? `         ${line(ruleSentence(f, options.tone || 'ask') || f.scope || '', 220)}` : '',
+        // The header's Command row is the action; without a header the action line stays.
+        f.action && !header ? `Action:  ${f.kind ? `${f.kind} — ` : ''}${line(f.action, 230)}` : '',
+        ...steps.slice(0, 6).map((step, index) => `${index === 0 ? 'Does:    ' : '         '}${index + 1}. ${line(step, 160)}`),
         f.agent ? `Agent: ${line(f.agent, 80)}` : '',
-        f.ide ? `IDE: ${line(f.ide, 40)}` : '',
+        // The header's first line already names the client.
+        f.ide && !header ? `IDE: ${line(f.ide, 40)}` : '',
         f.tool ? `Tool: ${line(f.tool, 230)}` : '',
-        f.because ? `Because: ${line(f.because, 300)}` : '',
+        because ? `Because: ${line(because, 300)}` : '',
         f.note ? `Note:    ${f.note}` : '',
     ].filter(Boolean);
     const where = f.policy && !f.fallback
@@ -148,15 +282,18 @@ function nativeApprovalMessage(reason, options = {}) {
     if (!options.allowAlways) {
         return [
             'Allow this action once?',
-            '', ...details, '',
+            // The header's "Why you're asked" answers the question directly below it.
+            ...(header ? [] : ['']), ...details, '',
+            ...(options.alwaysNotOffered && !header ? [line(options.alwaysNotOffered, 120)] : []),
             'Allow once permits only this action. Deny or closing keeps it stopped.',
             where,
         ].join('\n');
     }
+    const covers = header ? undefined : alwaysCoversLine(options);
     return [
         'Allow this action?',
-        '', ...details, '',
-        ...(options.alwaysScopeLabel ? [`Always allow: ${line(options.alwaysScopeLabel, 200)} for ${options.alwaysLimitsLabel || '30 days'} on this machine, while the rule stays as it is written today.`, ''] : []),
+        ...(header ? [] : ['']), ...details, '',
+        ...(covers ? [covers, ''] : []),
         'Allow once permits only this action. Deny or closing keeps it stopped.',
         where,
     ].join('\n');

package/dist/askDialog.d.ts

@@ -54,6 +54,8 @@ export interface AskEnvelope {
     grantLimits?: GrantLimits | null;
     /** Text for the dialog (the same explanation the IDE card shows). */
     reason: string;
+    /** The client the runtime event records as `agentClient` (cursor, claude-code, …): the dialog names the same agent as the console. */
+    agentClient?: string;
 }
 export type AskResolution = 'allow' | 'allow_always' | 'deny' | 'timeout' | 'ide';
 export interface HookVerdict {