@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/permissions.mjs

@@ -0,0 +1,845 @@
+/**
+ * lib/engine/permissions.mjs — may this tool call run? (pure)
+ *
+ * Modes:
+ *   default            rules decide; anything not allowed needs approval
+ *   acceptEdits        also allows Write/Edit/NotebookEdit inside the working
+ *                      directory (and permissions.additionalDirectories)
+ *   plan               denies every tool that can change anything
+ *   dontAsk            anything not explicitly allowed is denied
+ *   bypassPermissions  allows everything except deny and ask rules
+ *
+ * Rules come from `permissions.allow / deny / ask` in the settings layers and
+ * from --allowedTools / --disallowedTools. Syntax (Claude-compatible):
+ *
+ *   Bash                      every Bash call
+ *   Bash(npm run test:*)      a command starting with "npm run test"
+ *   Bash(git log *)           `*` wildcard anywhere; otherwise an exact command
+ *   Read(./src/**)            path globs, gitignore style: `//abs`, `~/home`,
+ *   Edit(/docs/*.md)          `/from-settings-root`, `./` or bare = from cwd;
+ *                             a pattern with no slash matches at any depth.
+ *                             Read rules also govern Glob and Grep; Edit rules
+ *                             govern Write, Edit and NotebookEdit.
+ *   WebFetch(domain:example.com)
+ *   mcp__cohort               every tool of that server (= mcp__cohort__*)
+ *   mcp__cohort__org_rpc      one MCP tool
+ *
+ * Evaluation, first match wins in this order:
+ *   1. a deny rule                     → deny  (holds in every mode)
+ *   2. plan mode and a tool not planSafe → deny (every MCP tool counts as
+ *                                               mutating, whatever its hint;
+ *                                               TOOL_POSTURE names the agent
+ *                                               and session tools, CF-47)
+ *   3. an ask rule                     → ask   (holds in every mode)
+ *   4. an allow rule                   → allow (for a write to engine config,
+ *                                               only a rule naming a path)
+ *   5. a write to engine config        → ask   (see below; every mode; for
+ *                                               Bash, bashEngineConfigWrite)
+ *   6. bypassPermissions               → allow
+ *   7. acceptEdits and an edit in scope→ allow
+ *   8. a read-only built-in, or a TOOL_POSTURE autoAllow tool → allow
+ *   9. dontAsk                         → deny
+ *  10. otherwise                       → ask
+ *
+ * Engine config (`isEngineConfigPath`): anything under a `.claude` directory
+ * (settings, settings.local, skills, agents, commands, hooks, memory), any
+ * `.mcp.json` or `.claude.json`, the instruction files CLAUDE.md,
+ * CLAUDE.local.md, COHORT.md and AGENTS.md, and anything under a caller-named
+ * config directory ($CLAUDE_CONFIG_DIR). A write there could plant a hook, an
+ * MCP server, an allow rule or `defaultMode: bypassPermissions` for the next
+ * run, so no mode auto-allows it and neither does a whole-tool `Write`/`Edit`
+ * allow rule; only a path-specific allow rule does.
+ *
+ * The engine has no approval prompt: the caller turns `ask` into a denial with
+ * a message that says how to allow the call (`headlessAskDenial`), unless a
+ * PreToolUse hook decided it first.
+ *
+ * Compound shell commands are split on `&&`, `||`, `;`, `|`, `&` and newlines
+ * outside quotes. An allow rule must match EVERY part; a deny or ask rule
+ * matches when ANY part does. A command with command substitution (`$(…)`,
+ * backticks, `<(…)`) never matches a Bash allow rule that has a specifier.
+ *
+ * Deny and ask rules fail closed. Each part is also tested with common
+ * wrappers stripped (`sudo`, `env A=1`, `nohup`, `time`, `command`, `exec`,
+ * `nice`, `timeout 5`, `xargs`), quotes removed from the command word, and a
+ * path on it reduced to its basename (`/bin/rm` is `rm`). A command whose
+ * real text the rules cannot see — substitution, `eval`, `sh|bash|zsh -c`,
+ * `find -exec`, a command word that is a variable — matches EVERY Bash deny
+ * and ask rule that has a specifier.
+ *
+ * Symlinks (CF-19, W5-B). With a `resolvePath` (context/real-path.mjs; the
+ * guard and the CLI always pass one), a path is judged by where it really
+ * leads: a deny or ask path rule matches the name OR the real path, an allow
+ * rule must cover the real path (the rule's literal prefix resolved too, so
+ * `/tmp/**` still covers /private/tmp), the engine-config protection holds for
+ * a link to config, and acceptEdits allows only an edit whose real path is in
+ * scope. A new file is judged by its nearest existing ancestor's real path, a
+ * dangling link by the path it names; a loop keeps its name. A link swapped
+ * between this check and the tool's open is not caught.
+ *
+ * A Bash (or Monitor) command that names engine config in a redirection, tee,
+ * cp, mv, sed -i … (`bashEngineConfigWrite`) is an `ask` in every mode, like an
+ * Edit of config: a whole-tool `Bash` allow does not cover it, only specific
+ * rules naming the file. A conservative narrowing, not a boundary.
+ *
+ * No filesystem, clock or environment access: every input is a parameter.
+ *
+ * @module lib/engine/permissions
+ */
+
+import path from "node:path";
+
+export const PERMISSION_MODES = Object.freeze(["default", "acceptEdits", "plan", "dontAsk", "bypassPermissions"]);
+export const EDIT_TOOLS = Object.freeze(new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]));
+export const READ_TOOLS = Object.freeze(new Set(["Read", "Glob", "Grep", "LS", "NotebookRead"]));
+
+/**
+ * CF-47 (W4-B): the permission posture of the agent, session and front-door
+ * tools, keyed by tool name. Rationale: docs/engine/posture.md.
+ *
+ *   planSafe   the tool runs in plan mode
+ *   autoAllow  the tool needs no allow rule in default and dontAsk modes
+ *
+ * A built-in named here is judged by this table whatever its own `readOnly`
+ * flag says; the flag stays the loop's parallel-batching hint. Tools not named
+ * here use their `readOnly` flag for both. MCP tools are never either.
+ *
+ *   session-state  reads or manages only this run's own state      planSafe, autoAllow
+ *   spawns-clamped starts a child held to this run's mode and rules autoAllow
+ *   spawns-work    starts work the run's guard does not hold        neither
+ *   outbound       reaches a session with its own permissions      neither
+ */
+export const TOOL_POSTURE = Object.freeze({
+  TodoWrite: posture("session-state"),
+  TaskOutput: posture("session-state"),
+  TaskStop: posture("session-state"),
+  BashOutput: posture("session-state"),
+  KillShell: posture("session-state"),
+  ScheduleWakeup: posture("session-state"),
+  ListAgents: posture("session-state"),
+  WorkflowStatus: posture("session-state"),
+  Task: posture("spawns-clamped"),
+  Agent: posture("spawns-clamped"),
+  Workflow: posture("spawns-work"),
+  Monitor: posture("spawns-work"),
+  SendMessage: posture("outbound"),
+});
+
+/** @param {'session-state'|'spawns-clamped'|'spawns-work'|'outbound'} kind */
+function posture(kind) {
+  return Object.freeze({ kind, planSafe: kind === "session-state", autoAllow: kind === "session-state" || kind === "spawns-clamped" });
+}
+
+/**
+ * The posture a call is judged by. Pure.
+ * @param {{toolName:string, readOnly:boolean, isMcp?:boolean}} p
+ * @returns {{kind:string, planSafe:boolean, autoAllow:boolean}}
+ */
+export function toolPosture({ toolName, readOnly, isMcp = false }) {
+  if (isMcp) return { kind: "mcp", planSafe: false, autoAllow: false };
+  const named = Object.hasOwn(TOOL_POSTURE, toolName) ? TOOL_POSTURE[/** @type {keyof typeof TOOL_POSTURE} */ (toolName)] : null;
+  if (named) return named;
+  return readOnly ? { kind: "read-only", planSafe: true, autoAllow: true } : { kind: "mutating", planSafe: false, autoAllow: false };
+}
+
+/**
+ * @typedef {{raw:string, tool:string, specifier:string|null, source:string, baseDir:string}} PermissionRule
+ * @typedef {{allow:PermissionRule[], deny:PermissionRule[], ask:PermissionRule[]}} RuleSet
+ * @typedef {{behavior:'allow'|'deny'|'ask', reason:string, rule?:string}} PermissionDecision
+ */
+
+/** @param {unknown} mode */
+export function isPermissionMode(mode) {
+  return typeof mode === "string" && PERMISSION_MODES.includes(mode);
+}
+
+/**
+ * Split a --allowedTools / --disallowedTools value into rule strings: commas
+ * or whitespace separate rules, except inside parentheses.
+ * @param {string} value
+ */
+export function splitRuleList(value) {
+  const out = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of String(value)) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth = Math.max(0, depth - 1);
+    if (depth === 0 && (ch === "," || /\s/.test(ch))) {
+      if (cur.trim()) out.push(cur.trim());
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/**
+ * @param {string} text
+ * @param {{source?:string, baseDir?:string}} [o]
+ * @returns {{ok:true, rule:PermissionRule} | {ok:false, error:string}}
+ */
+export function parseRule(text, o = {}) {
+  const raw = String(text ?? "").trim();
+  const m = /^([A-Za-z0-9_*-]+)(?:\(([\s\S]*)\))?$/.exec(raw);
+  if (!m) return { ok: false, error: `permission rule "${raw}" is not ToolName or ToolName(specifier)` };
+  const specifier = m[2] === undefined ? null : m[2].trim();
+  return { ok: true, rule: { raw, tool: m[1], specifier: specifier === "" ? null : specifier, source: o.source ?? "", baseDir: o.baseDir ?? "" } };
+}
+
+/**
+ * @param {{allow?:unknown, deny?:unknown, ask?:unknown}} lists
+ * @param {{source:string, baseDir:string}} o
+ * @returns {{rules:RuleSet, errors:string[]}}
+ */
+export function compileRules(lists, o) {
+  /** @type {RuleSet} */
+  const rules = { allow: [], deny: [], ask: [] };
+  const errors = [];
+  for (const kind of /** @type {const} */ (["allow", "deny", "ask"])) {
+    const list = lists?.[kind];
+    if (list === undefined || list === null) continue;
+    if (!Array.isArray(list)) {
+      errors.push(`${o.source}: permissions.${kind} must be an array`);
+      continue;
+    }
+    for (const item of list) {
+      const r = parseRule(String(item), o);
+      if (r.ok) rules[kind].push(r.rule);
+      else errors.push(`${o.source}: ${r.error}`);
+    }
+  }
+  return { rules, errors };
+}
+
+/** @param {...RuleSet} sets @returns {RuleSet} */
+export function mergeRuleSets(...sets) {
+  return {
+    allow: sets.flatMap((s) => s.allow),
+    deny: sets.flatMap((s) => s.deny),
+    ask: sets.flatMap((s) => s.ask),
+  };
+}
+
+/** @param {string} glob  `*` = any run of characters */
+function wildcardRegex(glob) {
+  return new RegExp(`^${glob.split("*").map(escapeRe).join("[\\s\\S]*")}$`);
+}
+
+/** @param {string} s */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Does the rule's tool part cover this tool name?
+ * @param {string} ruleTool
+ * @param {string} toolName
+ */
+export function ruleToolMatches(ruleTool, toolName) {
+  if (ruleTool.startsWith("mcp__")) {
+    const rest = ruleTool.slice("mcp__".length);
+    if (!rest.includes("__")) return toolName.startsWith(`mcp__${rest}__`); // server-level rule
+    return ruleTool.includes("*") ? wildcardRegex(ruleTool).test(toolName) : ruleTool === toolName;
+  }
+  if ((ruleTool === "Task" || ruleTool === "Agent") && (toolName === "Task" || toolName === "Agent")) return true; // one tool, two names
+  if (ruleTool === "Read") return READ_TOOLS.has(toolName);
+  if (ruleTool === "Edit") return EDIT_TOOLS.has(toolName);
+  return ruleTool.includes("*") ? wildcardRegex(ruleTool).test(toolName) : ruleTool === toolName;
+}
+
+/**
+ * Split a shell command into simple commands, outside quotes. Pure and
+ * conservative: it does not understand every shell construct, and callers
+ * treat what it cannot see through (`hasSubstitution`) as unmatched for allow.
+ * @param {string} command
+ * @returns {{parts:string[], hasSubstitution:boolean}}
+ */
+export function splitShellCommand(command) {
+  const s = String(command);
+  const parts = [];
+  let cur = "";
+  let quote = /** @type {string|null} */ (null);
+  let hasSubstitution = false;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const next = s[i + 1];
+    if (quote) {
+      if (ch === "\\" && quote === '"' && next !== undefined) {
+        cur += ch + next;
+        i++;
+        continue;
+      }
+      if (quote === '"' && (ch === "`" || (ch === "$" && next === "("))) hasSubstitution = true;
+      if (ch === quote) quote = null;
+      cur += ch;
+      continue;
+    }
+    if (ch === "\\" && next !== undefined) {
+      cur += ch + next;
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      cur += ch;
+      continue;
+    }
+    if (ch === "`" || (ch === "$" && next === "(") || ((ch === "<" || ch === ">") && next === "(")) hasSubstitution = true;
+    const two = ch + (next ?? "");
+    if (two === "&&" || two === "||") {
+      parts.push(cur);
+      cur = "";
+      i++;
+      continue;
+    }
+    if (ch === ";" || ch === "|" || ch === "&" || ch === "\n") {
+      parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  parts.push(cur);
+  return {
+    parts: parts.map((p) => p.trim().replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)\s+)+/, "").trim()).filter((p) => p !== ""),
+    hasSubstitution,
+  };
+}
+
+const WRAPPERS = new Set(["sudo", "env", "nohup", "time", "command", "builtin", "exec", "nice", "timeout", "xargs", "stdbuf", "doas"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "csh", "tcsh"]);
+
+/** @param {string} word  quotes and backslashes removed, a path reduced to its basename */
+function normaliseCommandWord(word) {
+  const unquoted = word.replace(/["'\\]/g, "");
+  return unquoted.includes("/") ? unquoted.slice(unquoted.lastIndexOf("/") + 1) : unquoted;
+}
+
+/**
+ * The texts a deny or ask rule is tested against for one simple command: the
+ * part as written, then with its command word normalised and each leading
+ * wrapper (and the wrapper's own options and assignments) stripped.
+ * @param {string} part
+ * @returns {{texts:string[], opaque:boolean}}
+ */
+export function denyCandidates(part) {
+  const texts = [part];
+  let words = part.split(/\s+/).filter(Boolean);
+  let opaque = false;
+  for (let guard = 0; guard < 10 && words.length > 0; guard++) {
+    const cmd = normaliseCommandWord(words[0]);
+    if (words[0].startsWith("$")) opaque = true;
+    if (cmd === "eval") opaque = true;
+    if (SHELLS.has(cmd) && words.slice(1).some((w) => /^-[A-Za-z]*c[A-Za-z]*$/.test(w))) opaque = true;
+    if (cmd === "find" && words.some((w) => /^-(exec|execdir|ok|okdir)$/.test(w))) opaque = true;
+    texts.push([cmd, ...words.slice(1)].join(" "));
+    if (!WRAPPERS.has(cmd)) break;
+    // Drop the wrapper, then its options, assignments and a numeric argument (nice -n 5, timeout 10s).
+    let i = 1;
+    while (i < words.length && (/^-/.test(words[i]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || /^\d+[smhd]?$/.test(words[i]))) i++;
+    words = words.slice(i);
+  }
+  return { texts, opaque };
+}
+
+/** @param {string} spec @param {string} command */
+function bashSpecMatches(spec, command) {
+  if (spec === "*") return true;
+  if (spec.endsWith(":*")) {
+    const prefix = spec.slice(0, -2);
+    return command === prefix || command.startsWith(`${prefix} `) || (prefix.endsWith(" ") && command.startsWith(prefix));
+  }
+  if (spec.includes("*")) return wildcardRegex(spec).test(command);
+  return command === spec;
+}
+
+/**
+ * Compile a gitignore-style path pattern to an absolute-path regex.
+ * @param {string} pattern
+ * @param {{cwd:string, homedir:string|null, baseDir:string}} where
+ */
+export function pathPatternRegex(pattern, where) {
+  const { root, p } = patternParts(pattern, where);
+  return compilePathRegex(root, p);
+}
+
+/**
+ * CF-19: the same pattern with its literal prefix (root plus the segments before
+ * the first glob character) resolved through symlinks, so a resolved target is
+ * compared with a resolved rule — `Edit(/tmp/**)` still covers a file whose real
+ * path is /private/tmp/…, and `./**` still covers cwd when cwd is a symlink. Pure
+ * (the resolver is a parameter).
+ * @param {string} pattern
+ * @param {{cwd:string, homedir:string|null, baseDir:string}} where
+ * @param {(p:string)=>string|null} resolvePath
+ */
+export function resolvedPathPatternRegex(pattern, where, resolvePath) {
+  const { root, p } = patternParts(pattern, where);
+  const segs = p === "" ? [] : p.split("/");
+  let i = 0;
+  while (i < segs.length && !/[*?[\]{}]/.test(segs[i])) i++;
+  const literalRoot = path.join(root, ...segs.slice(0, i));
+  const realRoot = resolvePath(literalRoot) ?? literalRoot;
+  const rest = segs.slice(i).join("/");
+  if (rest === "") return new RegExp(`^${escapeRe(realRoot)}(?:/.*)?$`);
+  return compilePathRegex(realRoot, rest);
+}
+
+/**
+ * The absolute root a pattern is anchored at and the glob body under it.
+ * @param {string} pattern
+ * @param {{cwd:string, homedir:string|null, baseDir:string}} where
+ */
+function patternParts(pattern, { cwd, homedir, baseDir }) {
+  let p = pattern;
+  let root;
+  if (p.startsWith("//")) {
+    root = "/";
+    p = p.slice(2);
+  } else if (p.startsWith("~/")) {
+    root = homedir ?? "/nonexistent-home";
+    p = p.slice(2);
+  } else if (p.startsWith("/")) {
+    root = baseDir || cwd;
+    p = p.slice(1);
+  } else {
+    root = cwd;
+    if (p.startsWith("./")) p = p.slice(2);
+    else if (!p.includes("/")) p = `**/${p}`; // gitignore: no slash matches at any depth
+  }
+  // `dir/` and `dir/**` both name a directory; the suffix below covers its
+  // contents, and the directory itself matches too (a Grep rooted there).
+  if (p.endsWith("/**")) p = p.slice(0, -3);
+  else if (p.endsWith("/")) p = p.slice(0, -1);
+  return { root, p };
+}
+
+/** @param {string} root @param {string} p */
+function compilePathRegex(root, p) {
+  let re = "";
+  for (let i = 0; i < p.length; i++) {
+    const ch = p[i];
+    if (ch === "*" && p[i + 1] === "*") {
+      if (p[i + 2] === "/") {
+        re += "(?:.*/)?";
+        i += 2;
+      } else {
+        re += ".*";
+        i += 1;
+      }
+    } else if (ch === "*") re += "[^/]*";
+    else if (ch === "?") re += "[^/]";
+    else re += escapeRe(ch);
+  }
+  const rootPrefix = root.endsWith("/") ? root : `${root}/`;
+  // A pattern naming a directory also covers everything under it.
+  return new RegExp(`^${escapeRe(rootPrefix)}${re}(?:/.*)?$`);
+}
+
+/**
+ * The path a file tool acts on. For Glob it is the directory the pattern's
+ * literal prefix reaches — `{pattern:"/etc/**"}` reads /etc, whatever `path` is.
+ * @param {string} toolName @param {any} input @param {string} cwd
+ */
+export function targetPath(toolName, input, cwd) {
+  const raw = input?.file_path ?? input?.notebook_path ?? input?.path;
+  const base = typeof raw === "string" && raw !== "" ? path.resolve(cwd, raw) : READ_TOOLS.has(toolName) ? path.resolve(cwd) : null;
+  if (toolName === "Glob" && base && typeof input?.pattern === "string") {
+    const literal = [];
+    for (const seg of input.pattern.split("/")) {
+      if (/[*?[\]{}]/.test(seg)) break;
+      literal.push(seg);
+    }
+    const prefix = literal.join("/");
+    if (prefix !== "") return path.resolve(base, prefix);
+    if (input.pattern.startsWith("/")) return "/"; // "/**": the literal prefix is the root itself
+  }
+  return base;
+}
+
+export const INSTRUCTION_FILE_NAMES = Object.freeze(new Set(["CLAUDE.md", "CLAUDE.local.md", "COHORT.md", "AGENTS.md"]));
+
+/**
+ * Is this absolute path part of the engine's own configuration or instructions?
+ * @param {string} target  absolute
+ * @param {string[]} [configDirs]  extra config roots ($CLAUDE_CONFIG_DIR)
+ */
+export function isEngineConfigPath(target, configDirs = []) {
+  const segments = target.split("/").filter(Boolean);
+  const base = segments[segments.length - 1] ?? "";
+  if (segments.slice(0, -1).includes(".claude") || base === ".claude") return true;
+  if (base === ".mcp.json" || base === ".claude.json" || INSTRUCTION_FILE_NAMES.has(base)) return true;
+  return isWithin(target, configDirs);
+}
+
+/**
+ * @param {PermissionRule} rule
+ * @param {{toolName:string, input:any}} call
+ * @param {{cwd:string, homedir:string|null, resolvePath?:((p:string)=>string|null)|null}} where
+ * @param {'allow'|'deny'|'ask'} kind
+ */
+export function ruleMatches(rule, call, where, kind) {
+  if (!ruleToolMatches(rule.tool, call.toolName)) return false;
+  if (rule.specifier === null || rule.specifier === "*") return true;
+  if (call.toolName.startsWith("mcp__")) return false; // MCP rules take no specifier
+
+  if (call.toolName === "Bash") {
+    const command = typeof call.input?.command === "string" ? call.input.command.trim() : "";
+    const { parts, hasSubstitution } = splitShellCommand(command);
+    if (kind === "allow") {
+      if (hasSubstitution || parts.length === 0) return false;
+      return parts.every((p) => bashSpecMatches(rule.specifier, p));
+    }
+    // deny / ask: fail closed on what the rule cannot see through.
+    if (hasSubstitution) return true;
+    if (bashSpecMatches(rule.specifier, command)) return true;
+    const spec = /** @type string */ (rule.specifier);
+    return parts.some((p) => {
+      const { texts, opaque } = denyCandidates(p);
+      return opaque || texts.some((t) => bashSpecMatches(spec, t));
+    });
+  }
+
+  if (READ_TOOLS.has(call.toolName) || EDIT_TOOLS.has(call.toolName)) {
+    const target = targetPath(call.toolName, call.input, where.cwd);
+    if (!target) return false;
+    const at = { cwd: where.cwd, homedir: where.homedir, baseDir: rule.baseDir };
+    const lexical = pathPatternRegex(rule.specifier, at);
+    if (!where.resolvePath) return lexical.test(target);
+    // CF-19: judged by where the path leads. Deny and ask match either the name or the real path
+    // (fail closed); an allow must cover the real path. An unresolvable path (a loop) keeps its name.
+    const real = where.resolvePath(target);
+    if (real === null) return lexical.test(target);
+    const realMatches = lexical.test(real) || resolvedPathPatternRegex(rule.specifier, at, where.resolvePath).test(real);
+    return kind === "allow" ? realMatches : realMatches || lexical.test(target);
+  }
+
+  if (call.toolName === "WebFetch" && rule.specifier.startsWith("domain:")) {
+    const domain = rule.specifier.slice("domain:".length).toLowerCase();
+    try {
+      const host = new URL(String(call.input?.url)).hostname.toLowerCase();
+      return host === domain || host.endsWith(`.${domain}`);
+    } catch {
+      return false;
+    }
+  }
+
+  if (call.toolName === "Skill") return call.input?.skill === rule.specifier;
+  if (call.toolName === "SlashCommand") return slashCommandMatches(rule.specifier, call.input?.command); // SlashCommand(/review), SlashCommand(/kit:*)
+  if (call.toolName === "Task" || call.toolName === "Agent") return subagentTypeMatches(rule.specifier, call.input?.subagent_type, kind); // Task(code-reader)
+  return false;
+}
+
+/**
+ * Does `SlashCommand(<specifier>)` cover an invoked command name (W4-E2)? The
+ * leading `/` is optional on both sides. `/name` is that name exactly;
+ * `/kit:*` is `kit` and every `kit:<name>` (a plugin's commands and skills).
+ * Pure.
+ * @param {string} specifier @param {unknown} command
+ */
+export function slashCommandMatches(specifier, command) {
+  if (typeof command !== "string") return false;
+  const name = command.trim().replace(/^\//, "");
+  const spec = specifier.trim().replace(/^\//, "");
+  if (spec.endsWith(":*")) {
+    const prefix = spec.slice(0, -2);
+    return name === prefix || name.startsWith(`${prefix}:`);
+  }
+  return name === spec;
+}
+
+/**
+ * Does `Task(<specifier>)` cover the subagent type the model asked for? The
+ * Task tool trims the name and accepts a plugin agent's unqualified name, so a
+ * rule must see the same name the tool will run:
+ *   allow        the trimmed name equals the specifier, exactly;
+ *   deny / ask   also when one side is unqualified and equals the other side's
+ *                unqualified part (`Task(kit:helper)` refuses "helper", and
+ *                `Task(helper)` refuses "kit:helper") — fail closed.
+ * The Task tool re-checks the resolved definition name as well (agents/runtime.mjs).
+ * @param {string} specifier @param {unknown} requested @param {'allow'|'deny'|'ask'} kind
+ */
+export function subagentTypeMatches(specifier, requested, kind) {
+  if (typeof requested !== "string") return false;
+  const want = requested.trim();
+  const spec = specifier.trim();
+  if (want === spec) return true;
+  if (kind === "allow") return false;
+  const bare = (/** @type string */ n) => n.slice(n.lastIndexOf(":") + 1);
+  return (!want.includes(":") && want === bare(spec)) || (!spec.includes(":") && spec === bare(want));
+}
+
+/**
+ * The allow rule covering a Bash call: a rule with no specifier covers any
+ * command; otherwise EVERY part of the command must be covered by some
+ * specific rule (different parts may be covered by different rules), and a
+ * command with substitution is never covered. Returns the last rule used.
+ * A command that writes engine config (`configWrite`, CF-19) is covered only by
+ * specific rules, at least one of which names the file as the command does.
+ * @param {PermissionRule[]} allowRules @param {any} input
+ * @param {{target:string, word:string}|null} [configWrite]
+ * @returns {PermissionRule|undefined}
+ */
+function bashAllowRule(allowRules, input, configWrite = null) {
+  const bashRules = allowRules.filter((r) => ruleToolMatches(r.tool, "Bash"));
+  const whole = bashRules.find((r) => r.specifier === null || r.specifier === "*");
+  if (whole && !configWrite) return whole;
+  const specific = bashRules.filter((r) => r.specifier !== null && r.specifier !== "*");
+  const command = typeof input?.command === "string" ? input.command.trim() : "";
+  const { parts, hasSubstitution } = splitShellCommand(command);
+  if (hasSubstitution || parts.length === 0) return undefined;
+  let last;
+  let namesTarget = false;
+  for (const part of parts) {
+    last = specific.find((r) => bashSpecMatches(/** @type string */ (r.specifier), part));
+    if (!last) return undefined;
+    if (configWrite && /** @type string */ (last.specifier).includes(configWrite.word)) namesTarget = true;
+  }
+  return configWrite && !namesTarget ? undefined : last;
+}
+
+/* ───────────────── CF-19: a shell command that writes engine config ───────────────── */
+
+/** Commands whose every operand may be a destination. */
+const COPY_WRITERS = new Set(["tee", "cp", "mv", "install", "ln", "rsync", "truncate", "touch"]);
+/** A redirection and its target: `>f`, `>> f`, `2>f`, `&>f`, `>|f` (the target keeps its quotes). */
+const REDIRECT_RE = /(?:^|[^<>&$\d])\d*(?:&?>>?|>\|)\s*((?:"[^"]*"|'[^']*'|[^\s;&|()<>"'])+)/g;
+
+/** Split a simple command into words, removing quotes and backslashes. Pure. @param {string} text */
+function shellWords(text) {
+  const out = [];
+  let cur = "";
+  let quoted = false;
+  /** @type {string|null} */
+  let q = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (q) {
+      if (ch === q) q = null;
+      else if (ch === "\\" && q === '"' && i + 1 < text.length) cur += text[++i];
+      else cur += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      q = ch;
+      quoted = true;
+    } else if (ch === "\\" && i + 1 < text.length) {
+      cur += text[++i];
+    } else if (/\s/.test(ch)) {
+      if (cur !== "" || quoted) out.push(cur);
+      cur = "";
+      quoted = false;
+    } else cur += ch;
+  }
+  if (cur !== "" || quoted) out.push(cur);
+  return out;
+}
+
+/**
+ * Does a Bash command name engine configuration as a place it writes? A
+ * conservative pre-check, because a shell command cannot be path-checked: it
+ * looks at redirection targets, the operands of `tee`, `cp`, `mv`, `install`,
+ * `ln`, `rsync`, `truncate`, `touch`, the files of `sed -i` / `perl -i`,
+ * `dd of=`, `curl -o` and `wget -O`, through wrappers (`sudo`, `env A=1`, …),
+ * `cd`/`pushd` (the directory later parts resolve against), `sh|bash|zsh -c`
+ * and `eval` scripts (to depth 3). `~` and `$HOME` expand to `homedir`; with a
+ * resolver, a name is also judged by the path it really leads to. It narrows,
+ * it is not a boundary: an interpreter (`python -c`, `node -e`), `git`,
+ * `patch`, a substituted or variable path, or a copy made under another name
+ * and renamed by a program is not seen. A `cp` FROM config is flagged too.
+ * Pure (the resolver is a parameter).
+ * @param {unknown} command
+ * @param {{cwd:string, homedir?:string|null, configDirs?:string[], resolvePath?:((p:string)=>string|null)|null}} where
+ * @param {number} [depth]
+ * @returns {{target:string, word:string}|null}  the first config path it names, as resolved and as written
+ */
+export function bashEngineConfigWrite(command, { cwd, homedir = null, configDirs = [], resolvePath = null }, depth = 0) {
+  const text = typeof command === "string" ? command : "";
+  if (text.trim() === "" || depth > 3) return null;
+  const realConfigDirs = resolvePath ? configDirs.map((d) => resolvePath(path.resolve(d)) ?? path.resolve(d)) : [];
+  const expandHome = (/** @type string */ w) => {
+    if (!homedir) return w;
+    if (w === "~" || w.startsWith("~/")) return homedir + w.slice(1);
+    return w.replace(/^\$\{?HOME\}?(?=\/|$)/, homedir);
+  };
+  /** @param {string} word @param {string} dir */
+  const configTarget = (word, dir) => {
+    const w = word.replace(/["']/g, "");
+    if (w === "" || w.startsWith("&") || w.startsWith("-")) return null;
+    const abs = path.resolve(dir, expandHome(w));
+    if (isEngineConfigPath(abs, configDirs)) return { target: abs, word: w };
+    const real = resolvePath ? resolvePath(abs) : null;
+    return real !== null && isEngineConfigPath(real, realConfigDirs) ? { target: real, word: w } : null;
+  };
+  let dir = cwd;
+  for (const part of splitShellCommand(text).parts) {
+    for (const m of part.matchAll(REDIRECT_RE)) {
+      const hit = configTarget(m[1], dir);
+      if (hit) return hit;
+    }
+    const words = shellWords(part);
+    let i = 0;
+    for (let guard = 0; guard < 10 && i < words.length; guard++) {
+      while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
+      if (i >= words.length || !WRAPPERS.has(normaliseCommandWord(words[i]))) break;
+      i++;
+      while (i < words.length && (/^-/.test(words[i]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || /^\d+[smhd]?$/.test(words[i]))) i++;
+    }
+    if (i >= words.length) continue;
+    const cmd = normaliseCommandWord(words[i]);
+    const args = words.slice(i + 1).filter((a) => !/^\d*(?:&?>>?|>\||<)/.test(a));
+    /** @type {string[]} */
+    let candidates = [];
+    if (cmd === "cd" || cmd === "pushd") {
+      const d = args.find((a) => !a.startsWith("-"));
+      if (d) dir = path.resolve(dir, expandHome(d));
+      continue;
+    }
+    if (SHELLS.has(cmd) || cmd === "eval") {
+      const at = cmd === "eval" ? 0 : args.findIndex((a) => /^-[A-Za-z]*c[A-Za-z]*$/.test(a)) + 1;
+      const script = cmd === "eval" ? args.join(" ") : at > 0 ? args[at] : undefined;
+      const inner = script === undefined ? null : bashEngineConfigWrite(script, { cwd: dir, homedir, configDirs, resolvePath }, depth + 1);
+      if (inner) return inner;
+      continue;
+    }
+    if (COPY_WRITERS.has(cmd)) candidates = args.map((a) => (a.startsWith("--target-directory=") ? a.slice("--target-directory=".length) : a));
+    else if ((cmd === "sed" && args.some((a) => /^-[A-Za-z]*i/.test(a) || a.startsWith("--in-place"))) || (cmd === "perl" && args.some((a) => /^-[A-Za-z]*i/.test(a)))) candidates = args;
+    else if (cmd === "dd") candidates = args.filter((a) => a.startsWith("of=")).map((a) => a.slice(3));
+    else if (cmd === "curl" || cmd === "wget") {
+      const letter = cmd === "curl" ? "o" : "O";
+      const long = cmd === "curl" ? "--output" : "--output-document";
+      args.forEach((a, k) => {
+        if ((a === long || new RegExp(`^-[A-Za-z]*${letter}$`).test(a)) && args[k + 1] !== undefined) candidates.push(args[k + 1]); // -o f, -so f
+        else if (a.startsWith(`${long}=`)) candidates.push(a.slice(long.length + 1));
+        else if (a.startsWith(`-${letter}`) && a.length > 2 && !a.startsWith("--")) candidates.push(a.slice(2)); // -of
+      });
+    }
+    for (const c of candidates) {
+      const hit = configTarget(c, dir);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+/**
+ * Memoise a resolver for one decision, and make it never throw.
+ * @param {(p:string)=>string|null} fn
+ * @returns {(p:string)=>string|null}
+ */
+function memoResolver(fn) {
+  /** @type {Map<string, string|null>} */
+  const cache = new Map();
+  return (p) => {
+    if (!cache.has(p)) {
+      let r = null;
+      try {
+        r = fn(p);
+      } catch {
+        r = null;
+      }
+      cache.set(p, typeof r === "string" ? r : null);
+    }
+    return cache.get(p) ?? null;
+  };
+}
+
+/** @param {string} file @param {string[]} dirs */
+function isWithin(file, dirs) {
+  return dirs.some((d) => {
+    const rel = path.relative(path.resolve(d), file);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+  });
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.toolName
+ * @param {any} p.input
+ * @param {boolean} p.readOnly        the tool cannot change anything
+ * @param {boolean} [p.isMcp]         MCP tools are never auto-allowed as read-only
+ * @param {string} p.mode
+ * @param {RuleSet} p.rules
+ * @param {string} p.cwd
+ * @param {string|null} [p.homedir]
+ * @param {string[]} [p.additionalDirectories]
+ * @param {string[]} [p.configDirs]  extra engine config roots ($CLAUDE_CONFIG_DIR)
+ * @param {((p:string)=>string|null)|null} [p.resolvePath]  CF-19: where a path really leads
+ *   (context/real-path.mjs); null judges paths by name only
+ * @returns {PermissionDecision}
+ */
+export function evaluatePermission({ toolName, input, readOnly, isMcp = false, mode, rules, cwd, homedir = null, additionalDirectories = [], configDirs = [], resolvePath = null }) {
+  const m = isPermissionMode(mode) ? mode : "default";
+  const call = { toolName, input };
+  const real = resolvePath ? memoResolver(resolvePath) : null;
+  const where = { cwd, homedir, resolvePath: real };
+  const find = (/** @type {'allow'|'deny'|'ask'} */ kind) => rules[kind].find((r) => ruleMatches(r, call, where, kind));
+
+  const pos = toolPosture({ toolName, readOnly, isMcp });
+  const deny = find("deny");
+  if (deny) return { behavior: "deny", reason: `denied by the rule ${deny.raw}${deny.source ? ` (${deny.source})` : ""}`, rule: deny.raw };
+  // An MCP server's readOnlyHint is its own claim: plan mode does not rely on it.
+  if (m === "plan" && !pos.planSafe) {
+    const reason = isMcp ? "plan mode does not run MCP tools" : pos.kind === "mutating" ? "plan mode allows only tools that change nothing" : `plan mode does not run ${toolName}: it ${POSTURE_REASON[pos.kind]}`;
+    return { behavior: "deny", reason };
+  }
+  const ask = find("ask");
+  if (ask) return { behavior: "ask", reason: `the rule ${ask.raw}${ask.source ? ` (${ask.source})` : ""} requires approval`, rule: ask.raw };
+  const editTarget = EDIT_TOOLS.has(toolName) ? targetPath(toolName, input, cwd) : null;
+  // CF-19: an edit is judged by the file it really reaches (a symlink's target) as well as by its name.
+  const realEdit = editTarget && real ? real(editTarget) : editTarget;
+  const realOf = (/** @type string */ d) => (real ? (real(path.resolve(d)) ?? path.resolve(d)) : d);
+  const protectedWrite = Boolean(editTarget && (isEngineConfigPath(editTarget, configDirs) || (realEdit !== null && realEdit !== editTarget && isEngineConfigPath(realEdit, configDirs.map(realOf)))));
+  const configWrite = toolName === "Bash" ? bashEngineConfigWrite(input?.command, { cwd, homedir, configDirs, resolvePath: real }) : null;
+  const allow = toolName === "Bash" ? bashAllowRule(rules.allow, input, configWrite) : protectedWrite ? rules.allow.find((r) => r.specifier !== null && r.specifier !== "*" && ruleMatches(r, call, where, "allow")) : find("allow");
+  if (allow) return { behavior: "allow", reason: `allowed by the rule ${allow.raw}`, rule: allow.raw };
+  if (protectedWrite) {
+    const via = realEdit && realEdit !== editTarget ? ` (a link to ${realEdit})` : "";
+    return { behavior: "ask", reason: `${editTarget}${via} is engine configuration or instructions, which no mode edits without approval` };
+  }
+  if (configWrite) {
+    return {
+      behavior: "ask",
+      reason: `the command writes to ${configWrite.target}, which is engine configuration or instructions; a shell command cannot be path-checked, so one that names such a file in a redirection, tee, cp, mv, sed -i or the like needs approval in every mode`,
+    };
+  }
+  if (m === "bypassPermissions") return { behavior: "allow", reason: "bypassPermissions mode" };
+  const editInScope = editTarget && (real ? realEdit !== null && isWithin(realEdit, [cwd, ...additionalDirectories].map(realOf)) : isWithin(editTarget, [cwd, ...additionalDirectories]));
+  if (m === "acceptEdits" && editInScope) {
+    return { behavior: "allow", reason: "acceptEdits mode: an edit inside the working directory" };
+  }
+  if (pos.autoAllow) return { behavior: "allow", reason: pos.kind === "read-only" ? "a read-only tool" : `${toolName} needs no rule: it ${POSTURE_REASON[pos.kind]}` };
+  if (m === "dontAsk") return { behavior: "deny", reason: "dontAsk mode denies anything not allowed by a rule" };
+  return { behavior: "ask", reason: "no rule allows this tool" };
+}
+
+/** Why a posture class is judged as it is (reason text for decisions). */
+export const POSTURE_REASON = Object.freeze({
+  "session-state": "reads or manages only this run's own state",
+  "spawns-clamped": "starts a subagent held to this run's permission mode and rules",
+  "spawns-work": "starts work this run's permission checks do not cover",
+  outbound: "reaches another session, which acts with its own permissions",
+});
+
+/**
+ * Is the tool denied outright, whatever its input? Such tools are not offered
+ * to the model at all (a rule with no specifier, or a server-level MCP rule).
+ * @param {string} toolName @param {RuleSet} rules
+ */
+export function isToolFullyDenied(toolName, rules) {
+  return rules.deny.some((r) => (r.specifier === null || r.specifier === "*") && ruleToolMatches(r.tool, toolName));
+}
+
+/**
+ * The tool_result text for an `ask` the engine cannot put to anyone.
+ * @param {string} toolName @param {PermissionDecision} decision
+ */
+export function headlessAskDenial(toolName, decision) {
+  return (
+    `Permission to use ${toolName} was not granted: ${decision.reason}, and this run cannot ask for approval. ` +
+    `It can be allowed with --allowedTools "${toolName}" or a permissions.allow rule in settings. Do not retry the same call; continue without it or explain what is blocked.`
+  );
+}