@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/context/real-path.mjs

@@ -0,0 +1,91 @@
+/**
+ * lib/engine/context/real-path.mjs — where a path really leads (CF-19, W5-B).
+ *
+ * Permission path rules and the engine-config protection judge a file by the
+ * place a tool call would really touch, not by the name the model gave it: a
+ * symlink inside the working directory that points at ~/.ssh, /etc or
+ * ~/.claude/settings.json is judged as that target (lib/engine/permissions.mjs).
+ *
+ * `resolveRealPath(target)`:
+ *   · an existing path → its realpath (every symlink on the way resolved);
+ *   · a dangling symlink → the path its link text names, resolved again (a
+ *     Write through it creates that file);
+ *   · a path that does not exist yet → the realpath of its nearest existing
+ *     ancestor joined with the rest (a new file under a symlinked directory);
+ *   · a symlink loop, or a chain longer than the hop budget → null (nothing
+ *     can be opened through it). Never throws.
+ *
+ * The file-system calls are injectable, so the walk is testable with fakes.
+ * Checking is not locking: a link swapped between the check and the tool's
+ * open is not caught (docs/engine/README.md, Permissions).
+ *
+ * @module lib/engine/context/real-path
+ */
+
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+/** How many path steps (links followed and ancestors walked) one resolution may take. */
+export const MAX_RESOLVE_STEPS = 160;
+
+/**
+ * @typedef {Object} RealPathFs
+ * @property {(p:string)=>string} [realpath]
+ * @property {(p:string)=>{isSymbolicLink:()=>boolean}} [lstat]
+ * @property {(p:string)=>string} [readlink]
+ */
+
+/**
+ * @param {string} target  absolute (a relative path is resolved against process.cwd())
+ * @param {RealPathFs} [fs]
+ * @returns {string|null}
+ */
+export function resolveRealPath(target, fs = {}) {
+  const realpath = fs.realpath ?? ((/** @type string */ p) => realpathSync.native(p));
+  const lstat = fs.lstat ?? lstatSync;
+  const readlink = fs.readlink ?? ((/** @type string */ p) => readlinkSync(p, "utf8"));
+  let steps = 0;
+  /** @param {string} p @returns {string|null} */
+  const walk = (p) => {
+    if (++steps > MAX_RESOLVE_STEPS) return null;
+    try {
+      return realpath(p);
+    } catch (e) {
+      if (/** @type {NodeJS.ErrnoException} */ (e)?.code === "ELOOP") return null;
+      /* ENOENT, ENOTDIR, EACCES: look at the path itself, then at its parent */
+    }
+    let isLink = false;
+    try {
+      isLink = lstat(p).isSymbolicLink();
+    } catch {
+      isLink = false;
+    }
+    if (isLink) {
+      let text;
+      try {
+        text = readlink(p);
+      } catch {
+        return null;
+      }
+      return walk(path.resolve(path.dirname(p), text));
+    }
+    const parent = path.dirname(p);
+    if (parent === p) return p;
+    const real = walk(parent);
+    return real === null ? null : path.join(real, path.basename(p));
+  };
+  try {
+    return walk(path.resolve(String(target)));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A resolver for the permission engine (`evaluatePermission({resolvePath})`).
+ * @param {RealPathFs} [fs]
+ * @returns {(p:string)=>string|null}
+ */
+export function createPathResolver(fs = {}) {
+  return (p) => resolveRealPath(p, fs);
+}

package/lib/engine/context/secret-values.mjs

@@ -0,0 +1,163 @@
+/**
+ * lib/engine/context/secret-values.mjs — does an environment VALUE look like a
+ * credential, whatever its variable is called (CF-118, W5-B)?
+ *
+ * The name scrub (tools/bash.mjs SECRET_ENV and EXTENDED_SECRET_ENV) misses a
+ * credential whose name says nothing: `DATABASE_URL=postgres://app:pw@db/x`,
+ * `REDIS_URL`, `AMQP_URL`, `SENTRY_DSN`, a token stored as `UPSTREAM`. This
+ * module judges the value. `credentialValueKind(value, {name})` returns the
+ * first rule that matches, or null:
+ *
+ *   url-userinfo    scheme://user:PASSWORD@host… anywhere in the value — a
+ *                   non-empty password is required (`https://user@host` and
+ *                   `http://host:8080/` are not credentials)
+ *   url-secret      a URL carrying a signing or token query parameter
+ *                   (`?token=`, `?access_token=`, `?key=`, `?sig=`,
+ *                   `X-Amz-Signature=`, … with a value of 16+ characters), or a
+ *                   Slack or Discord webhook URL
+ *   private-key     a PEM private key block (`-----BEGIN … PRIVATE KEY-----`)
+ *   token-prefix    a vendor token shape: `sk-…`, `sk_live_…`, `ghp_…`/`gho_…`/
+ *                   `ghu_…`/`ghs_…`/`ghr_…`, `github_pat_…`, `glpat-…`,
+ *                   `xox[abpr]-…`, `xapp-…`, `AKIA…`/`ASIA…` (16 more), `AIza…`,
+ *                   `npm_…`, `hf_…`, and Cohort's own `cst_…` / `nlk_…`
+ *   jwt             three base64url parts, the first `eyJ…`
+ *   high-entropy    a run of 32+ characters of the base64/base64url/token
+ *                   alphabet holding lower case, upper case AND digits, with a
+ *                   Shannon entropy of at least 4.0 bits per character; a
+ *                   leading `word_` (≤ 12 letters: `session_`, `msg_`) is not
+ *                   counted in the length, so prefixed ids stay short
+ *   hex             the whole value is 32+ hex digits
+ *
+ * The thresholds, and why they are conservative. Random base64 of 24+ bytes
+ * (32 characters) measures ~4.4–5.0 bits per character; the ordinary values
+ * found in a seat's environment measure less or fail the character-class test:
+ * paths (`/`, `~` or `.` first; searched segment by segment), PATH-like lists
+ * (`:` separates), `NODE_OPTIONS` (no upper case), UUIDs (excluded by shape),
+ * subresource-integrity strings (`sha512-…`, excluded by prefix), prefixed ids
+ * (`session_01…`, prefix not counted). Hex is judged apart: a 40-character git
+ * SHA and a 32-character hex API key look the same, so a hex value is withheld
+ * unless its NAME says it is a hash or an id (`GIT_COMMIT`, `GITHUB_SHA`,
+ * `*_DIGEST`, `*_CHECKSUM`, `*_REV`, `*_ID`, `npm_package_gitHead`, …;
+ * {@link HASH_OR_ID_NAME_RE}). The same name exemption applies to the
+ * high-entropy rule — never to the URL, key, vendor-prefix or JWT rules, which
+ * name a credential by their shape alone.
+ *
+ * Not caught (a narrowing, not a boundary): a short or low-entropy password
+ * under an ordinary name (`DB_PW=hunter2`), a secret split across two variables
+ * each below the length threshold, a hex or random secret under a hash- or
+ * id-shaped name, a value encoded with an alphabet outside the token one
+ * (percent-encoding with `%`), and anything a command reads from a file.
+ * Base64- or hex-wrapped secrets of 24+ bytes ARE caught (by the high-entropy
+ * and hex rules).
+ *
+ * Pure: no I/O, no clock, no randomness.
+ *
+ * @module lib/engine/context/secret-values
+ */
+
+/** A value this long, of the token alphabet, with all three character classes, is measured. */
+export const HIGH_ENTROPY_MIN_LENGTH = 32;
+/** Shannon entropy per character at or above which such a run is a credential. */
+export const HIGH_ENTROPY_MIN_BITS = 4.0;
+/** Such a run reads as random, not as words, when its letters hold at most this share of vowels … */
+export const MAX_RANDOM_VOWEL_SHARE = 0.3;
+/** … or its digits fall in at least this many separate runs. */
+export const MIN_RANDOM_DIGIT_RUNS = 3;
+/** A whole value of this many hex digits or more is a credential unless its name is hash- or id-shaped. */
+export const HEX_MIN_LENGTH = 32;
+
+/**
+ * Names whose hex or high-entropy value is an identifier, not a credential:
+ * a whole `_`-separated word (`GIT_COMMIT`, `BUILD_ID`, `IMAGE_DIGEST`) or a
+ * camel-case tail (`npm_package_gitHead`).
+ */
+export const HASH_OR_ID_NAME_RE = /(?:^|_)(?:SHA\d*|COMMIT|REV|REVISION|HASH|DIGEST|CHECKSUM|FINGERPRINT|INTEGRITY|ETAG|ID|IDS|UUID|GUID|NONCE|TRACE|SPAN|VERSION|BUILD|HEAD|REF)(?:_|$)|(?:[a-z](?:Sha|Hash|Head|Commit|Id|Digest))$/;
+
+const URL_USERINFO_RE = /\b[a-z][a-z0-9+.-]*:\/\/[^\s/?#@:]*:[^\s/?#@]+@[^\s/?#@]/i;
+const URL_SECRET_PARAM_RE = /[?&](?:access_token|refresh_token|id_token|token|auth|api_?key|key|secret|client_secret|password|passwd|sig|signature|x-amz-signature|x-amz-credential|x-amz-security-token|x-goog-signature|x-goog-credential)=([^&#\s]{16,})/i;
+const WEBHOOK_RE = /https:\/\/(?:hooks\.slack\.com\/(?:services|workflows|triggers)\/[A-Za-z0-9/_-]{20,}|(?:ptb\.|canary\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/[A-Za-z0-9_-]{20,})/i;
+const PRIVATE_KEY_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/;
+const JWT_RE = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/;
+/** Vendor token shapes. Each is bounded on the left so a longer word containing it does not match. */
+const TOKEN_PREFIX_RES = Object.freeze([
+  /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{20,}/, //                         OpenAI, Anthropic (sk-ant-…), DeepSeek, …
+  /(?<![A-Za-z0-9_])(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}/, //       Stripe
+  /(?<![A-Za-z0-9_])gh[pousr]_[A-Za-z0-9]{30,}/, //                     GitHub
+  /(?<![A-Za-z0-9_])github_pat_[A-Za-z0-9_]{22,}/,
+  /(?<![A-Za-z0-9_-])glpat-[A-Za-z0-9_-]{20,}/, //                      GitLab
+  /(?<![A-Za-z0-9_-])xox[abpr]-[A-Za-z0-9-]{10,}/, //                   Slack
+  /(?<![A-Za-z0-9_-])xapp-\d-[A-Za-z0-9-]{10,}/,
+  /(?<![A-Za-z0-9])(?:AKIA|ASIA)[0-9A-Z]{16}(?![0-9A-Za-z])/, //        AWS access key id
+  /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}/, //                         Google API key
+  /(?<![A-Za-z0-9_])npm_[A-Za-z0-9]{36}(?![A-Za-z0-9])/,
+  /(?<![A-Za-z0-9_])hf_[A-Za-z0-9]{30,}/, //                            Hugging Face
+  /(?<![A-Za-z0-9_])(?:cst|nlk)_[A-Za-z0-9_-]{16,}/, //                 Cohort gateway and org keys
+]);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_RE = /^[0-9a-f]+$/i;
+const TOKEN_ALPHABET_RE = /^[A-Za-z0-9+/=_.~-]+$/;
+const INTEGRITY_PREFIX_RE = /^(?:sha1|sha224|sha256|sha384|sha512|md5)[-:]/i;
+/** Separators between the candidate runs of a value (a `Bearer x`, `a=b;c=d`, a path's segments). */
+const RUN_SPLIT_RE = /[\s,;:=&"'<>()[\]{}|@\\/]+/;
+
+/**
+ * Shannon entropy of a string, in bits per character. Pure.
+ * @param {string} s
+ * @returns {number}
+ */
+export function shannonBitsPerChar(s) {
+  if (s.length === 0) return 0;
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const ch of s) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  let bits = 0;
+  for (const n of counts.values()) {
+    const p = n / s.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+
+/**
+ * One candidate run: long, of the token alphabet, all three classes, random enough.
+ * @param {string} run
+ */
+function looksRandom(run) {
+  if (!TOKEN_ALPHABET_RE.test(run) || UUID_RE.test(run) || INTEGRITY_PREFIX_RE.test(run)) return false;
+  const body = run.replace(/^[a-z]{1,12}_/, "");
+  if (body.length < HIGH_ENTROPY_MIN_LENGTH) return false;
+  if (!/[a-z]/.test(body) || !/[A-Z]/.test(body) || !/[0-9]/.test(body)) return false;
+  if (shannonBitsPerChar(body) < HIGH_ENTROPY_MIN_BITS) return false;
+  // Words, not noise: a camel-case identifier (`MyLongClassName2024Build`) has English's vowel share
+  // and its digits in one or two runs; random letters are ~19% vowels and random digits scatter.
+  const letters = body.replace(/[^A-Za-z]/g, "");
+  const vowelShare = (letters.match(/[aeiou]/gi)?.length ?? 0) / letters.length;
+  const digitRuns = body.match(/[0-9]+/g)?.length ?? 0;
+  return vowelShare <= MAX_RANDOM_VOWEL_SHARE || digitRuns >= MIN_RANDOM_DIGIT_RUNS;
+}
+
+/**
+ * @typedef {'url-userinfo'|'url-secret'|'private-key'|'token-prefix'|'jwt'|'high-entropy'|'hex'} CredentialValueKind
+ */
+
+/**
+ * Which credential shape a value has, if any. Pure.
+ * @param {unknown} value
+ * @param {{name?:string}} [o]  the variable's name: a hash- or id-shaped name exempts the hex and high-entropy rules
+ * @returns {CredentialValueKind|null}
+ */
+export function credentialValueKind(value, { name = "" } = {}) {
+  if (typeof value !== "string" || value.length < 8) return null;
+  if (URL_USERINFO_RE.test(value)) return "url-userinfo";
+  if (value.includes("://") && (URL_SECRET_PARAM_RE.test(value) || WEBHOOK_RE.test(value))) return "url-secret";
+  if (PRIVATE_KEY_RE.test(value)) return "private-key";
+  if (TOKEN_PREFIX_RES.some((re) => re.test(value))) return "token-prefix";
+  if (JWT_RE.test(value)) return "jwt";
+  if (HASH_OR_ID_NAME_RE.test(name)) return null;
+  const trimmed = value.trim();
+  if (trimmed.length >= HEX_MIN_LENGTH && HEX_RE.test(trimmed) && !UUID_RE.test(trimmed)) return "hex";
+  // The whole value (standard base64 may hold `/`), unless it reads as a path; then each run.
+  if (!/^[/~.]/.test(trimmed) && looksRandom(trimmed)) return "high-entropy";
+  if (trimmed.split(RUN_SPLIT_RE).some((run) => run.length >= HIGH_ENTROPY_MIN_LENGTH && looksRandom(run))) return "high-entropy";
+  return null;
+}

package/lib/engine/context/settings.mjs

@@ -0,0 +1,274 @@
+/**
+ * lib/engine/context/settings.mjs — the settings layers a run obeys.
+ *
+ * Files (Claude-compatible layout), from highest precedence to lowest:
+ *
+ *   managed   /Library/Application Support/ClaudeCode/managed-settings.json (macOS)
+ *             /etc/claude-code/managed-settings.json (Linux)
+ *   cli       --settings <file|json>, then the permission flags
+ *   local     <cwd>/.claude/settings.local.json
+ *   project   <cwd>/.claude/settings.json
+ *   user      ~/.claude/settings.json   ($CLAUDE_CONFIG_DIR replaces ~/.claude)
+ *
+ * Merging:
+ *   · permissions.allow / deny / ask and additionalDirectories concatenate
+ *     across layers (rule evaluation is by category, so order within a
+ *     category never changes a decision);
+ *   · hooks concatenate per event, each entry remembering its layer;
+ *   · permissions.defaultMode takes the highest-precedence layer that sets it;
+ *     a managed defaultMode also beats --permission-mode (the managed layer
+ *     is the organisation's, the flag is the caller's);
+ *   · disableBypassPermissionsMode: "disable" in any layer holds;
+ *   · disableAllHooks is honoured only from the user and managed layers (a
+ *     project cannot switch off a seat's hooks) and never removes managed
+ *     hooks; set elsewhere it is ignored with a warning;
+ *   · project MCP approval — enableAllProjectMcpServers and
+ *     enabledMcpjsonServers — is honoured only from the managed, cli and user
+ *     layers: a repository cannot approve its own .mcp.json.
+ *     disabledMcpjsonServers (a restriction) is honoured from every layer;
+ *   · `cohort.pluginDirs` (an engine extension, ignored by other tools)
+ *     concatenates; each entry is a plugin root, `dir/*` expands to its
+ *     subdirectories;
+ *   · `env` merges key by key, a higher layer's value winning. It is applied
+ *     to the environment of tool commands (Bash, subject to its credential
+ *     scrub), hook commands and stdio MCP servers (subject to theirs) — never
+ *     to the engine's own gateway configuration;
+ *   · `model` takes the highest-precedence layer that sets it; it is the
+ *     run's default tier when neither --model nor COHORT_LLM_MODEL is given;
+ *   · `apiKeyHelper` is ignored with a warning: the engine's gateway
+ *     credential is COHORT_LLM_TOKEN;
+ *   · the engine's own keys under `cohort` — `contextWindows` and `compaction`
+ *     (objects, merged key by key), `promptCacheKey` and `imageInput`
+ *     (booleans, highest layer wins) and `webTools` (only `false` counts, from
+ *     any layer) — are returned as `engine`.
+ *
+ * Relative paths in a layer resolve against that layer's root: the project
+ * directory for project/local, the home directory for user, the working
+ * directory for cli, and "/" for managed.
+ *
+ * `mergeSettings` is pure; `loadSettingsLayers` reads through injected fs.
+ *
+ * @module lib/engine/context/settings
+ */
+
+import path from "node:path";
+import { compileRules, mergeRuleSets } from "../permissions.mjs";
+
+/** @typedef {'managed'|'cli'|'local'|'project'|'user'} SettingsScope */
+/** @typedef {{scope:SettingsScope, path:string, baseDir:string, settings:any}} SettingsLayer */
+
+export const HOOK_EVENTS = Object.freeze(["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop", "SubagentStop", "PreCompact", "Notification"]);
+
+/** @param {string} platform */
+export function defaultManagedSettingsPath(platform) {
+  if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
+  if (platform === "linux") return "/etc/claude-code/managed-settings.json";
+  return null;
+}
+
+/**
+ * @param {{homedir:string|null, cwd:string, env?:Record<string,string|undefined>}} p
+ * @returns {string|null} the per-user config directory (~/.claude)
+ */
+export function userConfigDir({ homedir, env = {} }) {
+  if (env.CLAUDE_CONFIG_DIR) return env.CLAUDE_CONFIG_DIR;
+  return homedir ? path.join(homedir, ".claude") : null;
+}
+
+/**
+ * @param {object} p
+ * @param {string|null} p.homedir
+ * @param {string} p.cwd
+ * @param {string|null} [p.managedPath]
+ * @param {string|null} [p.cliSettings]  --settings value: a path, or inline JSON
+ * @param {Record<string,string|undefined>} [p.env]
+ * @param {(file:string) => string} p.readFile
+ * @param {(file:string) => boolean} p.exists
+ * @returns {{layers: SettingsLayer[], errors: string[]}}  layers in precedence order, HIGHEST first
+ */
+export function loadSettingsLayers({ homedir, cwd, managedPath = null, cliSettings = null, env = {}, readFile, exists }) {
+  /** @type {SettingsLayer[]} */
+  const layers = [];
+  const errors = [];
+  const read = (/** @type {SettingsScope} */ scope, /** @type string */ file, /** @type string */ baseDir) => {
+    if (!exists(file)) return;
+    try {
+      const settings = JSON.parse(readFile(file));
+      if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not a JSON object");
+      layers.push({ scope, path: file, baseDir, settings });
+    } catch (e) {
+      errors.push(`${scope} settings ${file}: ${e instanceof Error ? e.message : e}`);
+    }
+  };
+  if (managedPath) read("managed", managedPath, "/");
+  if (cliSettings !== null && cliSettings !== undefined) {
+    const v = String(cliSettings).trim();
+    if (v.startsWith("{")) {
+      try {
+        layers.push({ scope: "cli", path: "--settings (inline)", baseDir: cwd, settings: JSON.parse(v) });
+      } catch (e) {
+        errors.push(`--settings: not valid JSON (${e instanceof Error ? e.message : e})`);
+      }
+    } else {
+      const file = path.resolve(cwd, v);
+      if (!exists(file)) errors.push(`--settings ${file}: file not found`);
+      else read("cli", file, cwd);
+    }
+  }
+  read("local", path.join(cwd, ".claude", "settings.local.json"), cwd);
+  read("project", path.join(cwd, ".claude", "settings.json"), cwd);
+  const userDir = userConfigDir({ homedir, cwd, env });
+  if (userDir) read("user", path.join(userDir, "settings.json"), homedir ?? userDir);
+  return { layers, errors };
+}
+
+/**
+ * @typedef {Object} HookEntry
+ * @property {string} matcher
+ * @property {Array<{type:string, command?:string, timeout?:number}>} hooks
+ * @property {string} source
+ * @property {string} baseDir
+ * @property {SettingsScope} [scope]
+ */
+
+/** Layers whose word approves project MCP servers or switches off hooks. */
+const APPROVING_SCOPES = new Set(["managed", "cli", "user"]);
+const HOOK_SWITCH_SCOPES = new Set(["managed", "user"]);
+
+/**
+ * @param {SettingsLayer[]} layers  HIGHEST precedence first
+ * @param {{allowedTools?:string[], disallowedTools?:string[], permissionMode?:string|null, cwd:string}} flags
+ */
+export function mergeSettings(layers, flags) {
+  /** Problems that would silently drop a restriction: the run must not start. */
+  const errors = [];
+  /** Problems that lose nothing protective (an unknown hook event name). */
+  const warnings = [];
+  const ruleSets = [];
+  const additionalDirectories = [];
+  /** @type {Record<string, HookEntry[]>} */
+  const hooks = Object.fromEntries(HOOK_EVENTS.map((e) => [e, []]));
+  const pluginDirs = [];
+  let defaultMode = null;
+  /** @type {string|null} */
+  let managedDefaultMode = null;
+  let disableBypass = false;
+  let disableAllHooks = null;
+  /** @type {{enableAll:boolean|null, enabled:string[], disabled:string[]}} */
+  const mcpApproval = { enableAll: null, enabled: [], disabled: [] };
+  const names = (/** @type unknown */ v) => (Array.isArray(v) ? v.map(String) : []);
+  /** @type {Record<string,string>} */
+  const env = {};
+  /** @type {string|null} */
+  let model = null;
+  /** @type {{contextWindows:Record<string,unknown>, compaction:Record<string,unknown>, promptCacheKey?:boolean, imageInput?:boolean, webTools?:boolean}} */
+  const engine = { contextWindows: {}, compaction: {} };
+
+  // Lowest precedence first, so a scalar set later wins.
+  for (const layer of [...layers].reverse()) {
+    const s = layer.settings || {};
+    const label = `${layer.scope} ${layer.path}`;
+    const perms = s.permissions;
+    if (perms !== undefined) {
+      if (!perms || typeof perms !== "object") errors.push(`${label}: "permissions" must be an object`);
+      else {
+        const compiled = compileRules(perms, { source: label, baseDir: layer.baseDir });
+        ruleSets.push(compiled.rules);
+        errors.push(...compiled.errors);
+        if (typeof perms.defaultMode === "string") {
+          defaultMode = perms.defaultMode;
+          if (layer.scope === "managed") managedDefaultMode = perms.defaultMode;
+        }
+        if (perms.disableBypassPermissionsMode === "disable") disableBypass = true;
+        if (Array.isArray(perms.additionalDirectories)) {
+          for (const d of perms.additionalDirectories) additionalDirectories.push(path.resolve(layer.baseDir, String(d)));
+        }
+      }
+    }
+    if (typeof s.disableAllHooks === "boolean") {
+      if (HOOK_SWITCH_SCOPES.has(layer.scope)) disableAllHooks = s.disableAllHooks;
+      else warnings.push(`${label}: disableAllHooks is honoured only in user or managed settings (ignored)`);
+    }
+    mcpApproval.disabled.push(...names(s.disabledMcpjsonServers));
+    if (s.enableAllProjectMcpServers !== undefined || s.enabledMcpjsonServers !== undefined) {
+      if (APPROVING_SCOPES.has(layer.scope)) {
+        if (typeof s.enableAllProjectMcpServers === "boolean") mcpApproval.enableAll = s.enableAllProjectMcpServers;
+        mcpApproval.enabled.push(...names(s.enabledMcpjsonServers));
+      } else {
+        warnings.push(`${label}: project MCP servers cannot be approved from ${layer.scope} settings (ignored); approve them in ~/.claude/settings.json or pass --mcp-config`);
+      }
+    }
+    if (s.hooks !== undefined) {
+      if (!s.hooks || typeof s.hooks !== "object") errors.push(`${label}: "hooks" must be an object`);
+      else {
+        for (const [event, entries] of Object.entries(s.hooks)) {
+          if (!HOOK_EVENTS.includes(event)) {
+            warnings.push(`${label}: unknown hook event "${event}" (ignored)`);
+            continue;
+          }
+          if (!Array.isArray(entries)) {
+            errors.push(`${label}: hooks.${event} must be an array`);
+            continue;
+          }
+          for (const entry of entries) {
+            if (!entry || !Array.isArray(entry.hooks)) {
+              errors.push(`${label}: hooks.${event} entries need a "hooks" array`);
+              continue;
+            }
+            hooks[event].push({ matcher: typeof entry.matcher === "string" ? entry.matcher : "", hooks: entry.hooks, source: label, baseDir: layer.baseDir, scope: layer.scope });
+          }
+        }
+      }
+    }
+    const dirs = s.cohort?.pluginDirs;
+    if (Array.isArray(dirs)) for (const d of dirs) pluginDirs.push({ dir: path.resolve(layer.baseDir, String(d)), source: label });
+    // CF-21: env, model, apiKeyHelper; the engine's own `cohort` keys.
+    if (s.env !== undefined) {
+      if (!s.env || typeof s.env !== "object" || Array.isArray(s.env)) warnings.push(`${label}: "env" must be an object (ignored)`);
+      else {
+        for (const [k, v] of Object.entries(s.env)) {
+          if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") env[k] = String(v);
+          else warnings.push(`${label}: env.${k} must be a string (ignored)`);
+        }
+      }
+    }
+    if (typeof s.model === "string" && s.model.trim() !== "") model = s.model.trim();
+    if (s.apiKeyHelper !== undefined) warnings.push(`${label}: apiKeyHelper is ignored by the Cohort Engine; its gateway credential comes from COHORT_LLM_TOKEN`);
+    const c = s.cohort && typeof s.cohort === "object" ? s.cohort : {};
+    for (const key of /** @type {const} */ (["contextWindows", "compaction"])) {
+      if (c[key] && typeof c[key] === "object" && !Array.isArray(c[key])) Object.assign(engine[key], c[key]);
+    }
+    if (typeof c.promptCacheKey === "boolean") engine.promptCacheKey = c.promptCacheKey;
+    if (typeof c.imageInput === "boolean") engine.imageInput = c.imageInput;
+    // A restriction: `webTools: false` in any layer holds (a repository cannot switch back on what the seat switched off).
+    if (c.webTools === false) engine.webTools = false;
+  }
+
+  const cli = compileRules({ allow: flags.allowedTools ?? [], deny: flags.disallowedTools ?? [] }, { source: "command line", baseDir: flags.cwd });
+  errors.push(...cli.errors);
+  // Managed rules are part of `layers`; CLI rules add to them (rules only ever
+  // add restrictions or permissions, and deny/ask win by category).
+  ruleSets.push(cli.rules);
+
+  if (managedDefaultMode !== null && flags.permissionMode && flags.permissionMode !== managedDefaultMode) {
+    warnings.push(`managed settings set permissions.defaultMode "${managedDefaultMode}", which overrides the requested permission mode "${flags.permissionMode}"`);
+  }
+
+  return {
+    rules: mergeRuleSets(...ruleSets),
+    mode: managedDefaultMode ?? flags.permissionMode ?? defaultMode ?? "default",
+    defaultMode,
+    disableBypassPermissionsMode: disableBypass,
+    additionalDirectories,
+    // Switched off, only the managed layer's own hooks still run.
+    hooks: disableAllHooks === true ? Object.fromEntries(HOOK_EVENTS.map((e) => [e, hooks[e].filter((h) => h.scope === "managed")])) : hooks,
+    hooksDisabled: disableAllHooks === true,
+    mcpApproval,
+    pluginDirs,
+    env,
+    model,
+    engine,
+    errors,
+    warnings,
+  };
+}