@semalt-ai/code 1.8.5 → 1.20.0

package/lib/permission-rules.js

@@ -0,0 +1,401 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Per-pattern permission rules (Task 4.1) — the pure rule engine.
+// ---------------------------------------------------------------------------
+//
+// Extends the coarse per-tier permission model (--allow-fs/exec/net, --readonly,
+// per-session "always") with rich rules that match on a TOOL plus its ARGUMENTS
+// (glob OR regex) and resolve to one of `allow` / `deny` / `ask`. Rules are
+// layered across user scope (~/.semalt-ai/config.json) and project scope
+// (.semalt/config.json — attacker-controllable in a cloned repo).
+//
+// EVERYTHING in this module is a pure function: no I/O beyond fs.realpathSync for
+// path canonicalization (constraint 3), which is unavoidable to resolve symlinks.
+// The manager (lib/permissions.js) and the agent gate (lib/agent.js) consume the
+// decisions; composition with the unbypassable Phase 0 controls (deny-list,
+// secret-file guard, --readonly, isPathSafe) happens THERE and downstream in the
+// executors — an `allow` rule can never re-enable something those forbid.
+//
+// The six security constraints (see Task 4.1 brief), and where each lives:
+//   1. Project can only NARROW — collectMatches drops every project `allow` rule
+//      structurally before resolution, so a project rule can only ever contribute
+//      `deny`/`ask`. Enforced here, not by convention.
+//   2. Precedence is total + deterministic — deny > ask > allow; more-specific
+//      beats less-specific; equal specificity resolves by deny>ask>allow (so it
+//      is order-independent). Across layers: most-restrictive wins.
+//   3. Canonicalize before matching — normalizeCall resolves `..`, symlinks, and
+//      absolute/relative forms; matching is on the canonical form.
+//   4. Regex safety — normalizeRule rejects pathological patterns (ReDoS guard)
+//      and bounds subject length; a regex that errors/over-runs fails closed.
+//   5. Fail closed — a malformed rule is dropped at load; a matcher error never
+//      GRANTS (an erroring `allow` is treated as no-match) and still RESTRICTS
+//      (an erroring `deny`/`ask` is treated as a match).
+//   6. Compose, don't bypass — the resolver only ever returns allow/deny/ask/null
+//      for the RULE layer; the manager keeps the deny-list/secret/readonly checks.
+
+const fs = require('fs');
+const path = require('path');
+
+// Per canonical action (call[0]): its public tag (for matching by either name)
+// and the argument shape used to derive matchable subjects.
+//   category 'shell' → args[0] is the command string
+//   category 'file'  → `paths` indices are filesystem paths (canonicalized)
+//   category 'net'   → `urls` indices are URLs; `paths` indices are dest files
+//   category 'other' → no matchable argument subject (only tool-only rules match)
+const ACTION_META = {
+  shell:           { tag: 'exec',            category: 'shell' },
+  read:            { tag: 'read_file',       category: 'file', paths: [0] },
+  write:           { tag: 'write_file',      category: 'file', paths: [0] },
+  append:          { tag: 'append_file',     category: 'file', paths: [0] },
+  list_dir:        { tag: 'list_dir',        category: 'file', paths: [0] },
+  delete_file:     { tag: 'delete_file',     category: 'file', paths: [0] },
+  make_dir:        { tag: 'make_dir',        category: 'file', paths: [0] },
+  remove_dir:      { tag: 'remove_dir',      category: 'file', paths: [0] },
+  move_file:       { tag: 'move_file',       category: 'file', paths: [0, 1] },
+  copy_file:       { tag: 'copy_file',       category: 'file', paths: [0, 1] },
+  edit_file:       { tag: 'edit_file',       category: 'file', paths: [0] },
+  search_in_file:  { tag: 'search_in_file',  category: 'file', paths: [0] },
+  replace_in_file: { tag: 'replace_in_file', category: 'file', paths: [0] },
+  search_files:    { tag: 'search_files',    category: 'file', paths: [1] },
+  file_stat:       { tag: 'file_stat',       category: 'file', paths: [0] },
+  upload:          { tag: 'upload',          category: 'file', paths: [0] },
+  grep:            { tag: 'grep',            category: 'file' },
+  glob:            { tag: 'glob',            category: 'file' },
+  download:        { tag: 'download',        category: 'net', urls: [0], paths: [1] },
+  http_get:        { tag: 'http_get',        category: 'net', urls: [0] },
+  ask_user:        { tag: 'ask_user',        category: 'other' },
+  store_memory:    { tag: 'store_memory',    category: 'other' },
+  recall_memory:   { tag: 'recall_memory',   category: 'other' },
+  list_memories:   { tag: 'list_memories',   category: 'other' },
+  get_env:         { tag: 'get_env',         category: 'other' },
+  set_env:         { tag: 'set_env',         category: 'other' },
+  system_info:     { tag: 'system_info',     category: 'other' },
+};
+
+const VALID_ACTIONS = new Set(['allow', 'deny', 'ask']);
+// Restrictiveness rank — used to pick the most-restrictive decision across layers.
+const RANK = { deny: 3, ask: 2, allow: 1 };
+
+// ── ReDoS guard (constraint 4) ─────────────────────────────────────────────
+// Mirror of the cheap heuristic in lib/tools.js: reject pathologically long
+// patterns and the common catastrophic-backtracking anti-patterns. A pattern
+// that trips this is dropped at load time (fail closed). Subject length is
+// additionally bounded at match time.
+const MAX_PATTERN_LEN = 1000;
+const MAX_SUBJECT_LEN = 8192;
+
+function isPatternUnsafe(source) {
+  if (typeof source !== 'string') return true;
+  if (source.length > MAX_PATTERN_LEN) return true;
+  if (/(\(.*[+*].*\).*[+*])|(\[.*\].*[+*].*[+*])/.test(source)) return true;
+  return false;
+}
+
+// ── matcher compilation ────────────────────────────────────────────────────
+
+// A glob → anchored RegExp. `crossSep` controls whether `*`/`?` cross a path
+// separator: false for path-style globs (segment-aware), true for command/URL
+// globs (greedy). `**` always crosses separators; a trailing `/**` (or leading
+// `**/`) collapses the separator so `src/**` matches `src/a/b` and `**/*.env`
+// matches both `x.env` and `a/b/x.env`.
+function globToRegExp(glob, { crossSep = false } = {}) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i++;
+        if (glob[i + 1] === '/') { i++; re += '(?:.*/)?'; }
+        else re += '.*';
+      } else {
+        re += crossSep ? '.*' : '[^/]*';
+      }
+    } else if (c === '?') {
+      re += crossSep ? '.' : '[^/]';
+    } else if ('\\^$+.()|{}[]'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+// Count of "literal" (non-wildcard / non-metacharacter) characters — the
+// specificity weight of a pattern. More literal chars ⇒ more specific.
+function literalCount(source, kind) {
+  if (typeof source !== 'string') return 0;
+  const meta = kind === 'regex' ? new Set('.*+?()[]{}|^$\\') : new Set('*?');
+  let n = 0;
+  for (const ch of source) if (!meta.has(ch)) n++;
+  return n;
+}
+
+// Compile a rule's argument matcher from its source string. Returns null when no
+// matcher is given (a tool-only rule), or throws on an unsafe/invalid pattern so
+// normalizeRule can drop the rule (fail closed). `crossSep` comes from which key
+// the user used (`path:` ⇒ false; `pattern:`/`url:`/`match:` ⇒ true).
+function compileMatcher(source, crossSep) {
+  if (source == null) return { kind: 'any', specificity: 0, test: () => true };
+  const s = String(source);
+  if (s === '*' || s === '**') return { kind: 'any', specificity: 0, test: () => true };
+
+  const rx = s.match(/^\/(.*)\/([gimsuy]*)$/);
+  if (rx) {
+    const body = rx[1];
+    if (isPatternUnsafe(body)) throw new Error(`unsafe regex pattern: ${s}`);
+    // Strip the stateful `g` flag (it makes .test() position-dependent).
+    const flags = (rx[2] || '').replace(/g/g, '');
+    const re = new RegExp(body, flags);
+    return {
+      kind: 'regex',
+      specificity: literalCount(body, 'regex'),
+      test: (str) => re.test(str.length > MAX_SUBJECT_LEN ? str.slice(0, MAX_SUBJECT_LEN) : str),
+    };
+  }
+
+  if (isPatternUnsafe(s)) throw new Error(`unsafe glob pattern: ${s}`);
+  const re = globToRegExp(s, { crossSep });
+  return {
+    kind: 'glob',
+    specificity: literalCount(s, 'glob'),
+    test: (str) => re.test(str.length > MAX_SUBJECT_LEN ? str.slice(0, MAX_SUBJECT_LEN) : str),
+  };
+}
+
+const TOOL_WEIGHT = 1000; // a literal tool dominates an argument-pattern's weight
+
+// Normalize one raw rule object into an internal rule, or null if malformed
+// (logged via `log`). `scope` is 'user' | 'project'. The matcher source is taken
+// from exactly one of `pattern` | `path` | `url` | `match`; supplying more than
+// one is ambiguous and the rule is dropped (fail closed).
+function normalizeRule(raw, scope, log) {
+  const warn = (msg) => { if (typeof log === 'function') log(`permission rule dropped (${scope}): ${msg}`); };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) { warn('not an object'); return null; }
+
+  const action = typeof raw.action === 'string' ? raw.action.trim().toLowerCase() : '';
+  if (!VALID_ACTIONS.has(action)) { warn(`bad action ${JSON.stringify(raw.action)}`); return null; }
+
+  const tool = typeof raw.tool === 'string' ? raw.tool.trim() : '';
+  if (!tool) { warn('missing tool'); return null; }
+
+  const keys = ['pattern', 'path', 'url', 'match'].filter((k) => raw[k] != null && raw[k] !== '');
+  if (keys.length > 1) { warn(`multiple matcher keys (${keys.join(', ')})`); return null; }
+  const key = keys[0] || null;
+  const source = key ? String(raw[key]) : null;
+  const crossSep = key !== 'path'; // path globs are segment-aware; everything else is greedy
+
+  let toolMatcher, matcher;
+  try {
+    toolMatcher = globToRegExp(tool, { crossSep: true });
+    matcher = compileMatcher(source, crossSep);
+  } catch (err) {
+    warn(err.message);
+    return null;
+  }
+
+  const toolSpecificity = (tool === '*' || tool === '**') ? 0 : TOOL_WEIGHT;
+  return {
+    scope,
+    tool,
+    toolMatcher,
+    matcher,
+    matcherKey: key,
+    source,
+    action,
+    specificity: toolSpecificity + matcher.specificity,
+  };
+}
+
+// Normalize an array of raw rules for one layer; malformed entries are dropped.
+function normalizeRuleLayer(rawRules, scope, log) {
+  if (!Array.isArray(rawRules)) return [];
+  const out = [];
+  for (const raw of rawRules) {
+    const r = normalizeRule(raw, scope, log);
+    if (r) out.push(r);
+  }
+  return out;
+}
+
+// Build the layered rule set from the two RAW config objects (already parsed
+// JSON, NOT the shallow-merged view — the layers MUST stay separate so the
+// project layer can be structurally prevented from widening). Reads
+// `<cfg>.permissions.rules`.
+function loadRuleLayers(userCfg, projectCfg, log) {
+  const pick = (cfg) => (cfg && cfg.permissions && Array.isArray(cfg.permissions.rules)) ? cfg.permissions.rules : [];
+  return {
+    user: normalizeRuleLayer(pick(userCfg), 'user', log),
+    project: normalizeRuleLayer(pick(projectCfg), 'project', log),
+  };
+}
+
+// ── call canonicalization (constraint 3) ───────────────────────────────────
+
+// Resolve a path to its canonical absolute form (symlinks + `..` collapsed) and
+// a cwd-relative form, both in posix separators so globs match identically on
+// every platform. For a not-yet-existent path (writes), the existing ancestor is
+// realpath'd and the basename re-appended.
+function canonicalizePath(p, cwd) {
+  const base = cwd || process.cwd();
+  let abs = path.resolve(base, p);
+  try {
+    abs = fs.realpathSync(abs);
+  } catch {
+    try {
+      const dir = fs.realpathSync(path.dirname(abs));
+      abs = path.join(dir, path.basename(abs));
+    } catch { /* keep the path.resolve form */ }
+  }
+  const absPosix = abs.split(path.sep).join('/');
+  const rel = path.relative(base, abs).split(path.sep).join('/');
+  return { abs: absPosix, rel };
+}
+
+function normalizeCommand(cmd) {
+  return String(cmd == null ? '' : cmd).replace(/\s+/g, ' ').trim();
+}
+
+// Turn a [action, ...args] call tuple into the canonical, matchable shape.
+function normalizeCall(call, opts = {}) {
+  const arr = Array.isArray(call) ? call : [];
+  const action = arr[0];
+  const args = arr.slice(1);
+  const meta = ACTION_META[action] || { tag: action, category: 'other' };
+  const cwd = opts.cwd || process.cwd();
+
+  const out = { action, tag: meta.tag, category: meta.category, command: null, url: null, paths: [] };
+
+  if (meta.category === 'shell') {
+    out.command = normalizeCommand(args[0]);
+  }
+  if (meta.urls) {
+    for (const i of meta.urls) {
+      if (args[i] != null && args[i] !== '') { out.url = String(args[i]); break; }
+    }
+  }
+  if (meta.paths) {
+    for (const i of meta.paths) {
+      const v = args[i];
+      if (v == null || v === '') continue;
+      const { abs, rel } = canonicalizePath(String(v), cwd);
+      out.paths.push(abs);
+      if (rel && rel !== abs) out.paths.push(rel);
+    }
+  }
+  return out;
+}
+
+// ── matching + resolution ──────────────────────────────────────────────────
+
+function toolMatches(rule, call) {
+  try {
+    return rule.toolMatcher.test(String(call.action)) || rule.toolMatcher.test(String(call.tag));
+  } catch {
+    return false;
+  }
+}
+
+// Does a rule match a normalized call? Returns true | false | 'error'. 'error'
+// (a matcher threw at runtime, e.g. a pathological regex that slipped the load
+// guard) is propagated so the caller can fail closed.
+function ruleMatchesCall(rule, call) {
+  if (!toolMatches(rule, call)) return false;
+  if (rule.matcher.kind === 'any') return true;
+
+  let subjects;
+  if (call.category === 'shell') subjects = [call.command];
+  else if (call.category === 'net') subjects = [call.url, ...call.paths];
+  else if (call.category === 'file') subjects = call.paths;
+  else subjects = []; // 'other' — only tool-only rules match
+
+  for (const s of subjects) {
+    if (s == null) continue;
+    try {
+      if (rule.matcher.test(String(s))) return true;
+    } catch {
+      return 'error';
+    }
+  }
+  return false;
+}
+
+// Collect the rules in one layer that match the call. Fail-closed handling of a
+// matcher error: it NEVER grants (an erroring `allow` is treated as no-match)
+// and still RESTRICTS (an erroring `deny`/`ask` is treated as a match).
+function collectMatches(rules, call) {
+  const matches = [];
+  for (const rule of rules || []) {
+    let m;
+    try { m = ruleMatchesCall(rule, call); } catch { m = 'error'; }
+    if (m === true) matches.push(rule);
+    else if (m === 'error' && rule.action !== 'allow') matches.push(rule);
+  }
+  return matches;
+}
+
+// Resolve one layer's matches to a single { decision, rule } or null. Precedence:
+// most specific wins; among equal specificity, deny > ask > allow (so the result
+// is independent of rule order — no ambiguity).
+function layerDecision(matches) {
+  if (!matches || !matches.length) return null;
+  let maxSpec = -1;
+  for (const r of matches) if (r.specificity > maxSpec) maxSpec = r.specificity;
+  const top = matches.filter((r) => r.specificity === maxSpec);
+  const deny = top.find((r) => r.action === 'deny');
+  if (deny) return { decision: 'deny', rule: deny };
+  const ask = top.find((r) => r.action === 'ask');
+  if (ask) return { decision: 'ask', rule: ask };
+  return { decision: 'allow', rule: top[0] };
+}
+
+function ruleReason(rule) {
+  if (!rule) return null;
+  const src = rule.source ? ` ${rule.matcherKey || 'pattern'}=${rule.source}` : '';
+  return `${rule.scope} ${rule.action} ${rule.tool}${src}`;
+}
+
+// THE resolver. Takes a NORMALIZED call (already canonicalized — constraint 3),
+// the layered rules, and a context bag (reserved for tier/readonly composition,
+// which the manager performs). Returns the deterministic rule-layer decision:
+//   { decision: 'allow'|'deny'|'ask'|null, rule, reason, scope }
+// `null` means no rule matched — the caller falls back to the tier/descriptor
+// default. Project rules can only NARROW: every project `allow` is dropped before
+// resolution, so the project layer can contribute only `deny`/`ask`. Across
+// layers the MOST RESTRICTIVE decision wins.
+function resolvePermission(call, layers, context = {}) { // eslint-disable-line no-unused-vars
+  const userMatches = collectMatches(layers && layers.user, call);
+  // Structural project-cannot-widen: drop project `allow` rules entirely.
+  const projectMatches = collectMatches(layers && layers.project, call).filter((r) => r.action !== 'allow');
+
+  const u = layerDecision(userMatches);
+  const p = layerDecision(projectMatches);
+
+  let winner;
+  if (u && p) winner = RANK[p.decision] > RANK[u.decision] ? p : u;
+  else winner = u || p;
+
+  if (!winner) return { decision: null, rule: null, reason: null, scope: null };
+  return { decision: winner.decision, rule: winner.rule, reason: ruleReason(winner.rule), scope: winner.rule.scope };
+}
+
+module.exports = {
+  ACTION_META,
+  resolvePermission,
+  normalizeCall,
+  canonicalizePath,
+  normalizeCommand,
+  normalizeRule,
+  normalizeRuleLayer,
+  loadRuleLayers,
+  globToRegExp,
+  compileMatcher,
+  ruleMatchesCall,
+  collectMatches,
+  layerDecision,
+  ruleReason,
+  // test seams
+  literalCount,
+  isPatternUnsafe,
+};

package/lib/permissions.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const writer = require('./ui/writer');
-const messages = require('./ui/messages');
+const dbg = require('./debug');
+const { resolvePermission, normalizeCall } = require('./permission-rules');
 
 const TIER_FS = ['read_file', 'write_file', 'append_file', 'delete_file', 'list_dir', 'make_dir', 'move_file', 'copy_file', 'file_stat', 'search_files', 'store_memory', 'recall_memory'];
 const TIER_EXEC = ['exec'];
@@ -9,11 +10,23 @@ const TIER_NET = ['http_get', 'download'];
 const TIER_SYS = ['system_info', 'get_env', 'set_env'];
 
 const TIER_MAP = { fs: TIER_FS, exec: TIER_EXEC, net: TIER_NET, sys: TIER_SYS };
-const READONLY_BLOCKED = new Set(['write_file', 'append_file', 'delete_file', 'move_file', 'copy_file']);
+// Every FILE-mutating tool. --readonly governs file tools only; shell side
+// effects are NOT constrained here (a read-only session must still run `ls` /
+// `git status`) — shell writes are confined by the OS sandbox + deny-list,
+// the right layer for that (Pre-Task 5.0c).
+const READONLY_BLOCKED = new Set([
+  'write_file', 'append_file', 'delete_file', 'move_file', 'copy_file', 'download',
+  'edit_file', 'replace_in_file', 'make_dir', 'remove_dir', 'upload',
+  // Native git tools (Task 5.1). The mutating git tools (the create/delete paths
+  // of branch/worktree are gated inside their executors) honor --readonly too — a
+  // read-only session must not stage/commit/switch/create. Read-only git tools
+  // (git_status/git_diff/git_log, and the LIST ops) are NOT here, so they still run.
+  'git_add', 'git_commit', 'git_branch', 'git_checkout', 'git_worktree',
+]);
 
 let _permissionQueueTail = Promise.resolve();
 
-function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {}) {
+function createPermissionManager(ui, { allowedTiers = [], readonly = false, skipPermissions = false, rules = null, cwd = null, approver = null, quiet = false } = {}) {
   const { BOLD, FG_CYAN, FG_DARK, FG_GRAY, FG_GREEN, FG_RED, FG_YELLOW, RST, interactiveSelect } = ui;
 
   const autoApprovedTags = new Set();
@@ -27,6 +40,29 @@ function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {
     sessionApprovedTags: new Set(),
   };
 
+  // Per-pattern rule layers (Task 4.1). { user: [...], project: [...] } of
+  // already-normalized rules, kept SEPARATE so the project layer can be
+  // structurally prevented from widening (see lib/permission-rules.js).
+  const ruleLayers = (rules && typeof rules === 'object')
+    ? { user: rules.user || [], project: rules.project || [] }
+    : { user: [], project: [] };
+  const hasRules = ruleLayers.user.length > 0 || ruleLayers.project.length > 0;
+
+  // Resolve the per-pattern rule decision for a [action, ...args] call tuple.
+  // Returns { decision: 'allow'|'deny'|'ask'|null, rule, reason }. `null` when no
+  // rule matches → the caller falls back to the tier/descriptor default. Pure
+  // wrapper around resolvePermission; any failure fails closed to a null decision
+  // (the normal gate then still asks for mutating tools).
+  function resolveRule(call) {
+    if (!hasRules) return { decision: null, rule: null, reason: null };
+    try {
+      const normalized = normalizeCall(call, { cwd: cwd || process.cwd() });
+      return resolvePermission(normalized, ruleLayers, { readonly, tiers: allowedTiers });
+    } catch {
+      return { decision: null, rule: null, reason: null };
+    }
+  }
+
   let uiCallbacks = null;
 
   function setUICallbacks(callbacks) {
@@ -45,10 +81,10 @@ function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {
   // The picker renders into the writer's modal region — a live band above
   // the status bar that redraws in place on every keystroke. Arrow-key
   // navigation rebuilds the lines array and calls onShowModal again; nothing
-  // lands in scrollback until the user confirms. On resolve/cancel the
-  // modal is cleared and a single summary line is emitted to scrollback
-  // (for multi-line descriptions — e.g. a file-write diff — the full body
-  // is retained so the user can still see what was approved).
+  // lands in scrollback until the user confirms. On resolve/cancel the modal
+  // is simply cleared — NO summary line is emitted (Output Refactor Phase 2,
+  // D1): the execution result line is the single post-approval confirmation,
+  // so an echo here would just duplicate it.
   function requestPermission(description, onShowModal, onCloseModal, onCaptureNavigation) {
     // Serialize dialogs: each permission waits for the previous one to be answered
     const myTurn = _permissionQueueTail;
@@ -88,12 +124,13 @@ function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {
 
       function finish(result) {
         const chosen = result === 'cancel' ? 'no' : options[selectedIdx].toLowerCase();
-        const glyph = (chosen === 'no') ? '✗' : '✓';
-        // The full `description` is preserved in the summary so multi-line
-        // bodies (e.g. file-write diffs) remain visible in scrollback after
-        // the modal closes. chatHistory's system-message renderer styles the
-        // first line by the leading glyph and indents continuations.
-        onCloseModal(`${glyph} ${description}`);
+        // Output Refactor Phase 2 (D1): close the modal WITHOUT emitting a
+        // post-close summary line. The execution result line (the descriptor's
+        // `result` phase via renderOperation) is the single confirmation of the
+        // operation, so a `✓ shell: ls` / `✓ file: Edit line N` echo here just
+        // duplicated it. Manual-approve now produces the same post-execution
+        // output as auto-approve: only the result line.
+        onCloseModal();
         releaseQueue();
         resolve(chosen);
       }
@@ -116,28 +153,87 @@ function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {
     }));
   }
 
+  // Per-auto-approved-command breadcrumb. By DEFAULT this writes nothing to
+  // scrollback/UI: the per-command result line (command + outcome + duration,
+  // emitted for every tool) and the one-time "Auto-approve enabled for `tag`"
+  // grant line already cover it — a per-command `✓ Auto-approved: <cmd>` line
+  // just duplicates the command and reads as auto-approve chatter on every call.
+  // The diagnostic detail (incl. the `[rule: …]` / `[--dangerously-skip-...]`
+  // context the call sites embed in `description`) is preserved under
+  // --debug, routed through dbg.log — which is silent in 'off' mode (the
+  // default), scrollback in --debug, and the file in --debug-file. The audit
+  // log records every tool call independently, so nothing is lost regardless.
   function _emitAutoApproved(description) {
-    if (uiCallbacks) {
-      uiCallbacks.onAddMessage({ role: 'system', content: `✓ Auto-approved: ${description}` });
-    } else {
-      messages.sysSuccess(`Auto-approved: ${description}`);
-    }
+    dbg.log(`[permission] auto-approved: ${description}`);
   }
 
-  async function askPermission(actionType, description, tag) {
-    if (state.autoApproveAll) {
-      _emitAutoApproved(description);
+  async function askPermission(actionType, description, tag, ruleVerdict = null) {
+    // --dangerously-skip-permissions is the ONLY way to fully auto-approve any
+    // tool call. It does not bypass the destructive-command deny-list (enforced
+    // unbypassably in tools.js) — it only skips the interactive/refusal gate.
+    // A per-pattern `deny` rule is handled in the agent gate BEFORE this point
+    // (it blocks even under skip-permissions); here we see only allow/ask/null.
+    if (skipPermissions) {
+      _emitAutoApproved(`[--dangerously-skip-permissions] ${description}`);
       return true;
     }
 
-    if (tag && (autoApprovedTags.has(tag) || state.sessionApprovedTags.has(tag))) {
-      _emitAutoApproved(description);
-      return true;
+    // Per-pattern rules (Task 4.1). An `ask` rule FORCES the interactive prompt:
+    // it bypasses the auto-approve shortcuts below (tier flags, /approve, and the
+    // per-session "always") so a user policy of "ask for this" always holds. An
+    // `allow` rule auto-approves even what a tier wouldn't — but still composes
+    // with the deny-list / secret-guard / --readonly enforced downstream.
+    const ruleDecision = ruleVerdict && ruleVerdict.decision;
+    const forceAsk = ruleDecision === 'ask';
+
+    if (!forceAsk) {
+      if (ruleDecision === 'allow') {
+        _emitAutoApproved(`[rule${ruleVerdict.reason ? `: ${ruleVerdict.reason}` : ''}] ${description}`);
+        return true;
+      }
+
+      if (state.autoApproveAll) {
+        _emitAutoApproved(description);
+        return true;
+      }
+
+      if (tag && (autoApprovedTags.has(tag) || state.sessionApprovedTags.has(tag))) {
+        _emitAutoApproved(description);
+        return true;
+      }
+    }
+
+    // Programmatic approver (Task 5.2, SDK). When the process is embedded (no
+    // TTY) a host may supply an async approver — the programmatic equivalent of
+    // the interactive prompt. It is consulted ONLY when we would otherwise have
+    // to refuse for lack of a way to ask (no tier/rule/skip auto-approved above),
+    // so it never widens what a tier already granted, and an approver that throws
+    // or returns falsy means "no" (fail closed). With NO approver the safe
+    // default holds — refuse — exactly as headless does.
+    if (typeof approver === 'function') {
+      try {
+        const ok = await approver({ actionType, description, tag, rule: ruleVerdict || null });
+        return !!ok;
+      } catch {
+        return false;
+      }
     }
 
     if (!process.stdout.isTTY || !process.stdin.isTTY) {
-      writer.scrollback(`  [non-TTY] Auto-approving: ${description}`);
-      return true;
+      // Non-TTY / headless mode. WITHOUT --dangerously-skip-permissions we no
+      // longer silently auto-approve — that was the security hole. A tier flag
+      // (--allow-fs/exec/net/all) pre-approves its tag above; anything reaching
+      // here would otherwise require interactive confirmation we cannot show,
+      // so we refuse it instead of approving it. `quiet` (set by the embedding
+      // SDK) suppresses the scrollback line — the denial is already surfaced to
+      // the host in the structured run result.
+      if (!quiet) {
+        writer.scrollback(
+          `  [non-TTY] Refused (interactive confirmation required, and ` +
+          `--dangerously-skip-permissions not set): ${description}`
+        );
+      }
+      return false;
     }
 
     if (uiCallbacks) {
@@ -209,6 +305,7 @@ function createPermissionManager(ui, { allowedTiers = [], readonly = false } = {
     captureSelect,
     clear,
     readonlyBlock,
+    resolveRule,
     setUICallbacks,
     state,
     toggleAll,