@vellumai/assistant 0.3.0

package/src/permissions/defaults.ts

@@ -0,0 +1,254 @@
+import { join } from 'node:path';
+import { getRootDir } from '../util/platform.js';
+import { getBundledSkillsDir } from '../config/skills.js';
+import { getConfig } from '../config/loader.js';
+
+export interface DefaultRuleTemplate {
+  id: string;
+  tool: string;
+  pattern: string;
+  scope: string;
+  decision: 'allow' | 'deny' | 'ask';
+  priority: number;
+  allowHighRisk?: boolean;
+}
+
+const HOST_FILE_TOOLS = ['host_file_read', 'host_file_write', 'host_file_edit'] as const;
+const COMPUTER_USE_TOOLS = [
+  'computer_use_click',
+  'computer_use_double_click',
+  'computer_use_right_click',
+  'computer_use_type_text',
+  'computer_use_key',
+  'computer_use_scroll',
+  'computer_use_drag',
+  'computer_use_wait',
+  'computer_use_open_app',
+  'computer_use_run_applescript',
+  'computer_use_request_control',
+  // computer_use_done and computer_use_respond are terminal signal tools
+  // (RiskLevel.Low) — they don't perform any computer action, so they
+  // should NOT get an 'ask' rule.
+] as const;
+
+/**
+ * Returns default trust rules shipped with the assistant.
+ * Computed at runtime so paths reflect the configured root directory.
+ */
+export function getDefaultRuleTemplates(): DefaultRuleTemplate[] {
+  const hostFileRules = HOST_FILE_TOOLS.map((tool) => ({
+    id: `default:ask-${tool}-global`,
+    tool,
+    pattern: `${tool}:/**`,
+    scope: 'everywhere',
+    decision: 'ask' as const,
+    priority: 50,
+  }));
+
+  // host_bash command candidates are raw commands ("ls", "npm test"), so the
+  // global default ask rule uses "**" (globstar) instead of a "tool:*" prefix
+  // because commands often contain "/" (e.g. "cat /etc/hosts").
+  const hostShellRule: DefaultRuleTemplate = {
+    id: 'default:ask-host_bash-global',
+    tool: 'host_bash',
+    pattern: '**',
+    scope: 'everywhere',
+    decision: 'ask',
+    priority: 50,
+  };
+
+  // Sandboxed bash commands run in an isolated container — auto-allow all of
+  // them (including high-risk) so the user is never prompted for sandbox work.
+  // Only emit this rule when the sandbox is actually enabled; otherwise bash
+  // commands execute on the host and must go through normal permission checks.
+  const sandboxEnabled = getConfig().sandbox.enabled;
+  const sandboxShellRule: DefaultRuleTemplate | null = sandboxEnabled
+    ? {
+        id: 'default:allow-bash-global',
+        tool: 'bash',
+        pattern: '**',
+        scope: 'everywhere',
+        decision: 'allow',
+        priority: 50,
+        allowHighRisk: true,
+      }
+    : null;
+
+  // Standalone "**" globstar — minimatch only treats ** as globstar when it is
+  // its own path segment, so a "tool:**" prefix would collapse to single-star
+  // behavior and fail to match candidates containing "/".  The tool is already
+  // filtered by `findHighestPriorityRule` (rule.tool !== tool), so a prefix is
+  // unnecessary.
+  const computerUseRules = COMPUTER_USE_TOOLS.map((tool) => ({
+    id: `default:ask-${tool}-global`,
+    tool,
+    pattern: '**',
+    scope: 'everywhere',
+    decision: 'ask' as const,
+    priority: 1000,
+  }));
+
+  // Managed skill authoring tools — scaffold and delete modify ~/.vellum/workspace/skills/
+  // and should require explicit user approval.
+  const MANAGED_SKILL_TOOLS = ['scaffold_managed_skill', 'delete_managed_skill'] as const;
+  const managedSkillRules = MANAGED_SKILL_TOOLS.map((tool) => ({
+    id: `default:ask-${tool}-global`,
+    tool,
+    pattern: `${tool}:*`,
+    scope: 'everywhere',
+    decision: 'ask' as const,
+    priority: 1000,
+  }));
+
+  // Workspace prompt files — the agent should always be able to read, edit,
+  // and write these without prompting.  Also allow `rm BOOTSTRAP.md` so the
+  // agent can delete it at the end of the onboarding ritual.
+  const workspaceDir = join(getRootDir(), 'workspace').replaceAll('\\', '/');
+  const WORKSPACE_PROMPT_FILES = ['IDENTITY.md', 'USER.md', 'SOUL.md', 'BOOTSTRAP.md'] as const;
+  const WORKSPACE_FILE_TOOLS = ['file_read', 'file_write', 'file_edit'] as const;
+  const workspacePromptRules = WORKSPACE_FILE_TOOLS.flatMap((tool) =>
+    WORKSPACE_PROMPT_FILES.map((file) => ({
+      id: `default:allow-${tool}-${file.toLowerCase().replace('.md', '')}`,
+      tool,
+      pattern: `${tool}:${workspaceDir}/${file}`,
+      scope: 'everywhere',
+      decision: 'allow' as const,
+      priority: 100,
+    })),
+  );
+
+  const bootstrapDeleteRule: DefaultRuleTemplate = {
+    id: 'default:allow-bash-rm-bootstrap',
+    tool: 'bash',
+    pattern: 'rm BOOTSTRAP.md',
+    scope: workspaceDir,
+    decision: 'allow',
+    priority: 100,
+  };
+
+  // Skill source directories — writing or editing skill source files should
+  // require explicit user approval so a compromised agent loop cannot silently
+  // modify skill code to escalate privileges.
+  const managedSkillsDir = join(getRootDir(), 'workspace', 'skills').replaceAll('\\', '/');
+  const bundledSkillsDir = getBundledSkillsDir().replaceAll('\\', '/');
+  const SKILL_MUTATION_TOOLS = ['file_write', 'file_edit'] as const;
+  const skillDirs: { dir: string; label: string }[] = [
+    { dir: managedSkillsDir, label: 'managed' },
+    { dir: bundledSkillsDir, label: 'bundled' },
+  ];
+
+  // Append any user-configured extra skill directories so they get the
+  // same default ask rules as managed and bundled dirs.
+  const extraDirs = getConfig().skills.load.extraDirs;
+  for (let i = 0; i < extraDirs.length; i++) {
+    skillDirs.push({ dir: extraDirs[i].replaceAll('\\', '/'), label: `extra-${i}` });
+  }
+
+  const skillSourceMutationRules = skillDirs.flatMap(({ dir, label }) =>
+    SKILL_MUTATION_TOOLS.map((tool) => ({
+      id: `default:ask-${tool}-${label}-skills`,
+      tool,
+      pattern: `${tool}:${dir}/**`,
+      scope: 'everywhere',
+      decision: 'ask' as const,
+      priority: 50,
+    })),
+  );
+
+  const skillLoadRule: DefaultRuleTemplate = {
+    id: 'default:allow-skill_load-global',
+    tool: 'skill_load',
+    pattern: 'skill_load:*',
+    scope: 'everywhere',
+    decision: 'allow',
+    priority: 100,
+  };
+
+  // Browser tools were previously core-registered with RiskLevel.Low (auto-allowed).
+  // After migration to skill-provided tools, default allow rules preserve the
+  // same frictionless UX so they don't trigger permission prompts.
+  // browser_navigate candidates contain URLs with "/" (e.g.
+  // "browser_navigate:https://example.com/path"), so it needs standalone
+  // "**" globstar (same as host_bash / computer_use_*).  The tool field
+  // already filters by tool name, so a prefix is unnecessary.
+  const browserNavigateRule: DefaultRuleTemplate = {
+    id: 'default:allow-browser_navigate-global',
+    tool: 'browser_navigate',
+    pattern: '**',
+    scope: 'everywhere',
+    decision: 'allow',
+    priority: 100,
+  };
+
+  const BROWSER_TOOLS_NO_SLASH = [
+    'browser_snapshot',
+    'browser_screenshot',
+    'browser_close',
+    'browser_click',
+    'browser_type',
+    'browser_press_key',
+    'browser_wait_for',
+    'browser_extract',
+    'browser_fill_credential',
+  ] as const;
+
+  const browserToolRules: DefaultRuleTemplate[] = BROWSER_TOOLS_NO_SLASH.map((tool) => ({
+    id: `default:allow-${tool}-global`,
+    tool,
+    pattern: `${tool}:*`,
+    scope: 'everywhere',
+    decision: 'allow' as const,
+    priority: 100,
+  }));
+
+  // ui_update and ui_dismiss are purely passive operations (modify/remove existing
+  // surfaces). ui_show is excluded because it can create forms that collect user
+  // input — it goes through normal permission checking instead.
+  const UI_SURFACE_TOOLS = ['ui_update', 'ui_dismiss'] as const;
+  const uiSurfaceRules: DefaultRuleTemplate[] = UI_SURFACE_TOOLS.map((tool) => ({
+    id: `default:allow-${tool}-global`,
+    tool,
+    pattern: `${tool}:*`,
+    scope: 'everywhere',
+    decision: 'allow' as const,
+    priority: 100,
+  }));
+
+  // view_image is a read-only sandbox tool — always allow without prompting.
+  // Candidates contain "/" (absolute paths), so use "/**" globstar.
+  const viewImageRule: DefaultRuleTemplate = {
+    id: 'default:allow-view_image-global',
+    tool: 'view_image',
+    pattern: 'view_image:/**',
+    scope: 'everywhere',
+    decision: 'allow',
+    priority: 100,
+  };
+
+  // memory_search is a read-only tool — always allow without prompting.
+  const memorySearchRule: DefaultRuleTemplate = {
+    id: 'default:allow-memory_search-global',
+    tool: 'memory_search',
+    pattern: 'memory_search:*',
+    scope: 'everywhere',
+    decision: 'allow',
+    priority: 100,
+  };
+
+  return [
+    ...hostFileRules,
+    hostShellRule,
+    ...(sandboxShellRule ? [sandboxShellRule] : []),
+    ...computerUseRules,
+    ...managedSkillRules,
+    ...workspacePromptRules,
+    bootstrapDeleteRule,
+    ...skillSourceMutationRules,
+    skillLoadRule,
+    browserNavigateRule,
+    ...browserToolRules,
+    ...uiSurfaceRules,
+    viewImageRule,
+    memorySearchRule,
+  ];
+}

package/src/permissions/prompter.ts

@@ -0,0 +1,98 @@
+import { v4 as uuid } from 'uuid';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+import type { UserDecision, AllowlistOption, ScopeOption } from './types.js';
+import type { ExecutionTarget } from '../tools/types.js';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import { AssistantError, ErrorCode } from '../util/errors.js';
+import { redactSensitiveFields } from '../security/redaction.js';
+
+const log = getLogger('permission-prompter');
+
+interface PendingPrompt {
+  resolve: (value: { decision: UserDecision; selectedPattern?: string; selectedScope?: string }) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class PermissionPrompter {
+  private pending = new Map<string, PendingPrompt>();
+  private sendToClient: (msg: ServerMessage) => void;
+
+  constructor(sendToClient: (msg: ServerMessage) => void) {
+    this.sendToClient = sendToClient;
+  }
+
+  updateSender(sendToClient: (msg: ServerMessage) => void): void {
+    this.sendToClient = sendToClient;
+  }
+
+  async prompt(
+    toolName: string,
+    input: Record<string, unknown>,
+    riskLevel: string,
+    allowlistOptions: AllowlistOption[],
+    scopeOptions: ScopeOption[],
+    diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean },
+    sandboxed?: boolean,
+    sessionId?: string,
+    executionTarget?: ExecutionTarget,
+    persistentDecisionsAllowed?: boolean,
+  ): Promise<{ decision: UserDecision; selectedPattern?: string; selectedScope?: string }> {
+    const requestId = uuid();
+
+    return new Promise((resolve, reject) => {
+      const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
+      const timer = setTimeout(() => {
+        this.pending.delete(requestId);
+        log.warn({ requestId, toolName }, 'Permission prompt timed out, defaulting to deny');
+        resolve({ decision: 'deny' });
+      }, timeoutMs);
+
+      this.pending.set(requestId, { resolve, reject, timer });
+
+      this.sendToClient({
+        type: 'confirmation_request',
+        requestId,
+        toolName,
+        input: redactSensitiveFields(input),
+        riskLevel,
+        allowlistOptions: allowlistOptions.map((o) => ({ label: o.label, description: o.description, pattern: o.pattern })),
+        scopeOptions: scopeOptions.map((o) => ({ label: o.label, scope: o.scope })),
+        diff,
+        sandboxed,
+        sessionId,
+        executionTarget,
+        persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
+      });
+    });
+  }
+
+  hasPendingRequest(requestId: string): boolean {
+    return this.pending.has(requestId);
+  }
+
+  resolveConfirmation(
+    requestId: string,
+    decision: UserDecision,
+    selectedPattern?: string,
+    selectedScope?: string,
+  ): void {
+    const pending = this.pending.get(requestId);
+    if (!pending) {
+      log.warn({ requestId }, 'No pending prompt for confirmation response');
+      return;
+    }
+    clearTimeout(pending.timer);
+    this.pending.delete(requestId);
+    pending.resolve({ decision, selectedPattern, selectedScope });
+  }
+
+  dispose(): void {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new AssistantError('Prompter disposed', ErrorCode.INTERNAL_ERROR));
+    }
+    this.pending.clear();
+  }
+}

package/src/permissions/secret-prompter.ts

@@ -0,0 +1,114 @@
+import { v4 as uuid } from 'uuid';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import { AssistantError, ErrorCode } from '../util/errors.js';
+
+type SecretRequestMessage = Extract<ServerMessage, { type: 'secret_request' }>;
+
+const log = getLogger('secret-prompter');
+
+export type SecretDelivery = 'store' | 'transient_send';
+
+export interface SecretPromptResult {
+  value: string | null;
+  delivery: SecretDelivery;
+}
+
+interface PendingSecretPrompt {
+  resolve: (result: SecretPromptResult) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class SecretPrompter {
+  private pending = new Map<string, PendingSecretPrompt>();
+  private sendToClient: (msg: ServerMessage) => void;
+
+  constructor(sendToClient: (msg: ServerMessage) => void) {
+    this.sendToClient = sendToClient;
+  }
+
+  updateSender(sendToClient: (msg: ServerMessage) => void): void {
+    this.sendToClient = sendToClient;
+  }
+
+  /**
+   * Send a secret_request to the client and wait for the response.
+   *
+   * SECURITY: Logs only metadata (requestId, service, field) — never the
+   * returned secret value. The timeout path also returns a null value
+   * without logging anything sensitive.
+   */
+  async prompt(
+    service: string,
+    field: string,
+    label: string,
+    description?: string,
+    placeholder?: string,
+    sessionId?: string,
+    purpose?: string,
+    allowedTools?: string[],
+    allowedDomains?: string[],
+  ): Promise<SecretPromptResult> {
+    const requestId = uuid();
+
+    return new Promise((resolve, reject) => {
+      const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
+      const timer = setTimeout(() => {
+        this.pending.delete(requestId);
+        log.warn({ requestId, service, field }, 'Secret prompt timed out');
+        resolve({ value: null, delivery: 'store' });
+      }, timeoutMs);
+
+      this.pending.set(requestId, { resolve, reject, timer });
+
+      const config = getConfig();
+      const msg: SecretRequestMessage = {
+        type: 'secret_request',
+        requestId,
+        service,
+        field,
+        label,
+        description,
+        placeholder,
+        sessionId,
+        purpose,
+        allowedTools,
+        allowedDomains,
+        allowOneTimeSend: config.secretDetection.allowOneTimeSend,
+      };
+      this.sendToClient(msg);
+    });
+  }
+
+  hasPendingRequest(requestId: string): boolean {
+    return this.pending.has(requestId);
+  }
+
+  /**
+   * Resolve a pending secret prompt with the user-supplied value.
+   *
+   * SECURITY: This method intentionally never logs `value`. All log
+   * statements must use metadata-only fields (requestId, service, field).
+   * Any future change that adds logging here must be audited for leaks.
+   */
+  resolveSecret(requestId: string, value?: string, delivery?: SecretDelivery): void {
+    const pending = this.pending.get(requestId);
+    if (!pending) {
+      log.warn({ requestId }, 'No pending prompt for secret response');
+      return;
+    }
+    clearTimeout(pending.timer);
+    this.pending.delete(requestId);
+    pending.resolve({ value: value ?? null, delivery: delivery ?? 'store' });
+  }
+
+  dispose(): void {
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new AssistantError('Prompter disposed', ErrorCode.INTERNAL_ERROR));
+    }
+    this.pending.clear();
+  }
+}

package/src/permissions/shell-identity.ts

@@ -0,0 +1,227 @@
+import { parse, type ParsedCommand, type CommandSegment, type DangerousPattern } from '../tools/terminal/parser.js';
+import type { AllowlistOption } from './types.js';
+
+export type { ParsedCommand };
+
+export interface ShellActionKey {
+  /** e.g. "action:gh", "action:gh pr", "action:gh pr view" */
+  key: string;
+  /** How many tokens deep this key goes */
+  depth: number;
+}
+
+export interface ShellIdentityAnalysis {
+  /** The parsed segments from the shell parser */
+  segments: CommandSegment[];
+  /** The operator sequence between segments (e.g. ['&&', '|']) */
+  operators: string[];
+  /** Whether the command contains opaque constructs (eval, heredocs, etc.) */
+  hasOpaqueConstructs: boolean;
+  /** Dangerous patterns detected by the parser */
+  dangerousPatterns: DangerousPattern[];
+}
+
+export interface ActionKeyResult {
+  /** The derived action keys from narrowest to broadest */
+  keys: ShellActionKey[];
+  /** Whether this command has a "simple action" shape (setup prefix + single action) */
+  isSimpleAction: boolean;
+  /** The primary action segment (the non-setup-prefix action command) */
+  primarySegment?: CommandSegment;
+}
+
+/** Programs that are considered setup prefixes (not the main action) */
+const SETUP_PREFIX_PROGRAMS = new Set(['cd', 'pushd', 'export', 'unset', 'set']);
+
+const MAX_ACTION_KEY_DEPTH = 3;
+
+/**
+ * Analyze a shell command using the tree-sitter parser to extract
+ * identity information for permission decisions.
+ */
+export async function analyzeShellCommand(command: string, preParsed?: ParsedCommand): Promise<ShellIdentityAnalysis> {
+  const parsed = preParsed ?? await parse(command);
+
+  const operators: string[] = [];
+  for (const seg of parsed.segments) {
+    if (seg.operator) {
+      operators.push(seg.operator);
+    }
+  }
+
+  return {
+    segments: parsed.segments,
+    operators,
+    hasOpaqueConstructs: parsed.hasOpaqueConstructs,
+    dangerousPatterns: parsed.dangerousPatterns,
+  };
+}
+
+/**
+ * Derive canonical action keys from a shell command analysis.
+ *
+ * Action keys identify the "family" of a command for allowlist purposes.
+ * For example, `cd repo && gh pr view 5525 --json title` derives:
+ *   - action:gh pr view
+ *   - action:gh pr
+ *   - action:gh
+ *
+ * Only "simple action" commands (optional setup prefix + one action) get
+ * action keys. Pipelines and complex chains are marked non-simple.
+ */
+export function deriveShellActionKeys(analysis: ShellIdentityAnalysis): ActionKeyResult {
+  const { segments } = analysis;
+
+  if (segments.length === 0) {
+    return { keys: [], isSimpleAction: false };
+  }
+
+  // For multi-segment commands, only allow simple-action classification if
+  // ALL inter-segment operators are explicitly &&. Any other operator (|, ||,
+  // ;, &, empty/missing) means the separator is unknown or unsafe.
+  // This safely handles cases where the parser doesn't capture certain
+  // separators (;, newline, &) and leaves them as empty operators.
+  if (segments.length > 1) {
+    for (const seg of segments) {
+      const op = seg.operator;
+      // Non-empty operator that isn't && → definitely complex
+      if (op && op !== '&&') {
+        return { keys: [], isSimpleAction: false };
+      }
+    }
+    // Also check: if there are multiple segments but no operators at all
+    // between them (e.g. newline-separated), that's suspicious.
+    // The first segment always has operator '' (no preceding operator).
+    // If any non-first segment also has operator '', the separator was
+    // not captured — treat as complex for safety.
+    for (let i = 1; i < segments.length; i++) {
+      if (!segments[i].operator) {
+        return { keys: [], isSimpleAction: false };
+      }
+    }
+  }
+
+  // Separate setup-prefix segments from action segments
+  const actionSegments: CommandSegment[] = [];
+  let foundNonPrefix = false;
+
+  for (const seg of segments) {
+    if (!foundNonPrefix && SETUP_PREFIX_PROGRAMS.has(seg.program)) {
+      continue;
+    }
+    foundNonPrefix = true;
+    actionSegments.push(seg);
+  }
+
+  // Simple action: exactly one non-prefix action segment
+  if (actionSegments.length !== 1) {
+    return { keys: [], isSimpleAction: false };
+  }
+
+  const primarySegment = actionSegments[0];
+  const tokens: string[] = [primarySegment.program];
+
+  // Add non-flag, non-path stable subcommand tokens (up to MAX_ACTION_KEY_DEPTH)
+  for (const arg of primarySegment.args) {
+    if (tokens.length >= MAX_ACTION_KEY_DEPTH) break;
+    if (arg.startsWith('-')) continue;
+    if (arg.includes('/') || arg.startsWith('.')) continue;
+    if (/^\d+$/.test(arg)) continue;
+    if (arg.includes('$') || arg.includes('"') || arg.includes("'")) continue;
+    tokens.push(arg);
+  }
+
+  // Build action keys from narrowest to broadest
+  const keys: ShellActionKey[] = [];
+  for (let depth = tokens.length; depth >= 1; depth--) {
+    keys.push({
+      key: `action:${tokens.slice(0, depth).join(' ')}`,
+      depth,
+    });
+  }
+
+  return { keys, isSimpleAction: true, primarySegment };
+}
+
+/**
+ * Build an ordered list of command candidates for trust-rule matching.
+ *
+ * Candidate ordering:
+ *   1. Raw command (backward compatibility — existing rules match as before)
+ *   2. Canonical primary command (if simple action) — the full primary segment text
+ *   3. Action keys from narrowest to broadest (if simple action)
+ *
+ * Complex commands (pipelines, multi-action chains) only return the raw candidate.
+ */
+export async function buildShellCommandCandidates(command: string, preParsed?: ParsedCommand): Promise<string[]> {
+  const trimmed = command.trim();
+  if (!trimmed) return [trimmed];
+
+  const analysis = await analyzeShellCommand(trimmed, preParsed);
+  const actionResult = deriveShellActionKeys(analysis);
+
+  const candidates: string[] = [trimmed];
+
+  if (actionResult.isSimpleAction && actionResult.primarySegment) {
+    // Add canonical primary command text (the actual segment, not the full command with setup prefixes)
+    const canonical = actionResult.primarySegment.command;
+    if (canonical !== trimmed) {
+      candidates.push(canonical);
+    }
+
+    // Add action keys
+    for (const actionKey of actionResult.keys) {
+      candidates.push(actionKey.key);
+    }
+  }
+
+  // Deduplicate while preserving order
+  return [...new Set(candidates)];
+}
+
+/**
+ * Build allowlist options for shell commands using parser-derived identity.
+ *
+ * For simple actions (optional setup prefix + one action), options are:
+ *   1. Exact canonical primary command
+ *   2. Deepest action key (e.g. "action:gh pr view")
+ *   3. Broader action keys (e.g. "action:gh pr", "action:gh")
+ *
+ * For complex commands (pipelines, multi-action chains), only the exact
+ * command is offered (no broad options).
+ */
+export async function buildShellAllowlistOptions(command: string): Promise<AllowlistOption[]> {
+  const trimmed = command.trim();
+  if (!trimmed) return [];
+
+  const analysis = await analyzeShellCommand(trimmed);
+  const actionResult = deriveShellActionKeys(analysis);
+
+  if (!actionResult.isSimpleAction || !actionResult.primarySegment) {
+    // Complex command — exact only
+    return [{ label: trimmed, description: 'This exact compound command', pattern: trimmed }];
+  }
+
+  const options: AllowlistOption[] = [];
+
+  // Full original command text — "this exact command" means exactly what the user approved
+  options.push({ label: trimmed, description: 'This exact command', pattern: trimmed });
+
+  // Action keys from narrowest to broadest
+  for (const actionKey of actionResult.keys) {
+    const keyTokens = actionKey.key.replace(/^action:/, '');
+    options.push({
+      label: `${keyTokens} *`,
+      description: `Any "${keyTokens}" command`,
+      pattern: actionKey.key,
+    });
+  }
+
+  // Deduplicate by pattern
+  const seen = new Set<string>();
+  return options.filter((o) => {
+    if (seen.has(o.pattern)) return false;
+    seen.add(o.pattern);
+    return true;
+  });
+}