chainlesschain 0.166.81 → 0.166.83

package/src/lib/settings-loader.cjs

@@ -27,9 +27,83 @@
 const fsDefault = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
+const { randomUUID } = require("node:crypto");
 const { projectRootBase } = require("./project-root.cjs");
+const { observeSettingsSources } = require("./settings-source-observation.cjs");
+// Node >=22.12 supports synchronous require(ESM). Load these write-only
+// helpers on first use: permission readers should not trigger Node 22.12's
+// native require(ESM) warning just by discovering settings. Official writes
+// remain synchronous and keep the runtime's warning when applicable.
+let securityStoreHelpers;
+let fileLockHelper;
+function securityStore() {
+  return (securityStoreHelpers ??= require("./durable-security-store.js"));
+}
+function lockHelper() {
+  return (fileLockHelper ??= require("./with-file-lock.js").withFileLock);
+}
+
+const _deps = {
+  fs: fsDefault,
+  homedir: () => os.homedir(),
+  readSecurityStore: (...args) => securityStore().readSecurityStore(...args),
+  writeSecurityStore: (...args) => securityStore().writeSecurityStore(...args),
+  withFileLock: (...args) => lockHelper()(...args),
+};
+
+// A process-wide owner deliberately revokes unrelated projects too. Matching
+// only contributing paths misses absent files, parent discovery and aliases.
+// Only this module can advance it; raw edits and other processes are not events.
+const settingsOwnerId = randomUUID();
+let settingsRevision = Object.freeze({
+  ownerId: settingsOwnerId,
+  revision: 0,
+  state: "ready",
+});
+const settingsListeners = new Set();
+
+function getSettingsPermissionRevision() {
+  if (settingsRevision.state !== "ready") {
+    const error = new Error("settings permission authority is unavailable");
+    error.code = "CC_SETTINGS_PERMISSION_AUTHORITY_UNAVAILABLE";
+    throw error;
+  }
+  return settingsRevision;
+}
+
+function subscribeSettingsPermissionRevision(listener) {
+  if (typeof listener !== "function") {
+    throw new TypeError("settings revision listener must be a function");
+  }
+  settingsListeners.add(listener);
+  return () => settingsListeners.delete(listener);
+}
+
+function beginSettingsMutation() {
+  getSettingsPermissionRevision();
+  const next = settingsRevision.revision + 1;
+  settingsRevision = Object.freeze({
+    ownerId: settingsOwnerId,
+    revision: next,
+    state: Number.isSafeInteger(next) ? "mutating" : "invalid",
+  });
+  // Latch before calling observers. Reentrant writers/readers cannot acquire
+  // the lock or obtain authority while an official write is in progress.
+  for (const listener of [...settingsListeners]) {
+    try {
+      listener(settingsRevision);
+    } catch {
+      // An observer cannot prevent another running shell from being revoked.
+    }
+  }
+  if (settingsRevision.state === "invalid") {
+    getSettingsPermissionRevision();
+  }
+}
 
-const _deps = { fs: fsDefault, homedir: () => os.homedir() };
+function finishSettingsMutation(state) {
+  settingsRevision = Object.freeze({ ...settingsRevision, state });
+}
 
 const KINDS = Object.freeze(["allow", "ask", "deny"]);
 
@@ -88,6 +162,27 @@ function settingsPaths(cwd, explicitFile) {
   return list;
 }
 
+/**
+ * Strict, read-only inventory for persistent-authority integration. Includes
+ * every ordered candidate, even absent files and files with no permission
+ * contribution. This does not register an anchor or grant execution authority.
+ */
+function inspectSettingsSources(opts = {}) {
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const candidates = [
+    ...settingsPaths(cwd, opts.settingsFile),
+    managedSettingsPath(opts),
+  ];
+  return Object.freeze({
+    schema: "chainlesschain.settings-source-observation/v1",
+    cwd,
+    sources: observeSettingsSources(candidates, {
+      fs: _deps.fs,
+      maxBytes: opts.maxBytes,
+    }),
+  });
+}
+
 /** Organization-controlled settings file. This layer is always highest. */
 function managedSettingsPath(opts = {}) {
   if (opts.managedSettingsFile) return path.resolve(opts.managedSettingsFile);
@@ -260,30 +355,88 @@ function scopeFile(cwd, scope) {
  * @throws if the target file exists but is malformed JSON (refuse to clobber).
  */
 function addRule({ cwd = process.cwd(), kind, rule, scope = "project" } = {}) {
+  const entryCwd = process.cwd();
+  const absoluteCwd = path.resolve(entryCwd, cwd);
+  // Check before lock acquisition: notification callbacks may reenter here.
+  getSettingsPermissionRevision();
   if (!KINDS.includes(kind)) {
     throw new Error(`kind must be allow | ask | deny (got "${kind}")`);
   }
-  const file = scopeFile(cwd, scope);
-  let data = {};
-  if (_deps.fs.existsSync(file)) {
-    const text = _deps.fs.readFileSync(file, "utf-8");
-    try {
-      data = JSON.parse(text) || {};
-    } catch (err) {
-      throw new Error(
-        `refusing to overwrite malformed ${file} (${err.message})`,
-      );
-    }
+  if (typeof rule !== "string" || !rule.trim()) {
+    throw new TypeError("permission rule must be a non-empty string");
   }
-  if (!data.permissions || typeof data.permissions !== "object") {
-    data.permissions = {};
+  if (!["project", "local", "user"].includes(scope)) {
+    throw new TypeError("scope must be project | local | user");
   }
-  if (!Array.isArray(data.permissions[kind])) data.permissions[kind] = [];
-  if (data.permissions[kind].includes(rule)) return { file, added: false };
-  data.permissions[kind].push(rule);
+  const file = path.resolve(entryCwd, scopeFile(absoluteCwd, scope));
   _deps.fs.mkdirSync(path.dirname(file), { recursive: true });
-  _deps.fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf-8");
-  return { file, added: true };
+  let began = false;
+  let committed = false;
+  try {
+    const result = _deps.withFileLock(
+      file,
+      () => {
+        // Atomic replacement would otherwise replace the link itself after
+        // reading its target. Separate file links also have separate locks.
+        // Directory aliases continue to address the same file and lock.
+        if (
+          _deps.fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()
+        ) {
+          throw new TypeError(
+            `refusing to replace a settings file symbolic link: ${file}`,
+          );
+        }
+        const data = _deps.readSecurityStore(file, "settings");
+        if (
+          Object.hasOwn(data, "permissions") &&
+          (!data.permissions ||
+            typeof data.permissions !== "object" ||
+            Array.isArray(data.permissions))
+        ) {
+          throw new TypeError(
+            `refusing to overwrite malformed permissions: ${file}`,
+          );
+        }
+        data.permissions ??= {};
+        // Refuse to hide a damaged rule list, including a different decision.
+        for (const decision of KINDS) {
+          if (
+            Object.hasOwn(data.permissions, decision) &&
+            (!Array.isArray(data.permissions[decision]) ||
+              data.permissions[decision].some(
+                (entry) => typeof entry !== "string",
+              ))
+          ) {
+            throw new TypeError(
+              `refusing to overwrite malformed permission rules: ${file}`,
+            );
+          }
+        }
+        data.permissions[kind] ??= [];
+        if (data.permissions[kind].includes(rule))
+          return { file, added: false };
+        data.permissions[kind].push(rule);
+        beginSettingsMutation();
+        began = true;
+        _deps.writeSecurityStore(file, "settings", data);
+        committed = true;
+        return { file, added: true };
+      },
+      { failIfUnavailable: true },
+    );
+    if (began) finishSettingsMutation("ready");
+    return result;
+  } catch (error) {
+    if (!error.commitState) {
+      error.commitState = committed ? "committed" : "not-committed";
+    }
+    if (began) {
+      finishSettingsMutation(
+        error.commitState === "unknown" ? "invalid" : "ready",
+      );
+    }
+    throw error;
+  }
 }
 
 /**
@@ -508,6 +661,7 @@ function readStringArraySetting(key, opts = {}) {
 }
 
 module.exports = {
+  inspectSettingsSources,
   loadSettings,
   loadSettingsConfig,
   readSettingsFile,
@@ -523,6 +677,8 @@ module.exports = {
   mergeSandboxSettings,
   ruleSource,
   addRule,
+  getSettingsPermissionRevision,
+  subscribeSettingsPermissionRevision,
   scopeFile,
   KINDS,
   _deps,

package/src/lib/settings-source-observation.cjs

@@ -0,0 +1,270 @@
+"use strict";
+
+/**
+ * Read-only settings observations for a future persistent authority protocol.
+ * Only Node builtins: CJS readers must not materialize a require(ESM) bridge.
+ *
+ * These checks detect ordinary replacement and in-place edits. Path-based Node
+ * APIs do not prevent an adversarial parent swap-and-restore between checks.
+ * No observation is a generation, registration, or permission grant.
+ */
+const fsDefault = require("node:fs");
+const path = require("node:path");
+const { createHash } = require("node:crypto");
+const { TextDecoder } = require("node:util");
+
+const MAX_SETTINGS_SOURCE_BYTES = 1024 * 1024;
+const MAX_SETTINGS_SOURCES = 64;
+const FILE_FIELDS = [
+  "dev",
+  "ino",
+  "mode",
+  "nlink",
+  "size",
+  "mtimeNs",
+  "ctimeNs",
+];
+
+function failure(code, cause = null) {
+  const error = new Error(
+    "Settings source observation is unavailable",
+    cause ? { cause } : undefined,
+  );
+  error.name = "SettingsSourceObservationError";
+  error.code = code;
+  return error;
+}
+
+function sameFields(left, right, fields) {
+  return fields.every(
+    (field) =>
+      left[field] !== undefined &&
+      right[field] !== undefined &&
+      left[field] === right[field],
+  );
+}
+
+function pathIdentity(value) {
+  return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+function lstatOrMissing(fs, file) {
+  try {
+    return fs.lstatSync(file, { bigint: true });
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    if (cause?.code === "ENOTDIR")
+      throw failure("CC_SETTINGS_SOURCE_UNSAFE", cause);
+    throw cause;
+  }
+}
+
+function assertRegularFile(stat) {
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n) {
+    throw failure("CC_SETTINGS_SOURCE_UNSAFE");
+  }
+}
+
+function freezeJson(value) {
+  const pending = [value];
+  while (pending.length) {
+    const current = pending.pop();
+    if (!current || typeof current !== "object") continue;
+    for (const child of Object.values(current)) pending.push(child);
+    Object.freeze(current);
+  }
+  return value;
+}
+
+function inspect(file, fs, maxBytes) {
+  const logicalPath = path.resolve(file);
+  const entry = lstatOrMissing(fs, logicalPath);
+  if (entry) assertRegularFile(entry);
+
+  // Preserve absent candidates too, including a missing .claude directory.
+  let logicalParent = path.dirname(logicalPath);
+  const remaining = [path.basename(logicalPath)];
+  while (!lstatOrMissing(fs, logicalParent)) {
+    const next = path.dirname(logicalParent);
+    if (next === logicalParent) throw failure("CC_SETTINGS_SOURCE_UNAVAILABLE");
+    remaining.unshift(path.basename(logicalParent));
+    logicalParent = next;
+  }
+  const canonicalParent = fs.realpathSync(logicalParent);
+  const physicalPath = path.join(canonicalParent, ...remaining);
+  const flags =
+    (fs.constants?.O_RDONLY ?? fsDefault.constants.O_RDONLY) |
+    (fs.constants?.O_NOFOLLOW ?? fsDefault.constants.O_NOFOLLOW ?? 0) |
+    (fs.constants?.O_NONBLOCK ?? fsDefault.constants.O_NONBLOCK ?? 0);
+  const descriptors = [];
+  function open(filePath) {
+    const fd = fs.openSync(filePath, flags);
+    descriptors.push(fd);
+    return fd;
+  }
+  function verifyParent(original) {
+    if (
+      pathIdentity(fs.realpathSync(logicalParent)) !==
+      pathIdentity(canonicalParent)
+    ) {
+      throw failure("CC_SETTINGS_SOURCE_CHANGED");
+    }
+    const current = fs.fstatSync(open(canonicalParent), { bigint: true });
+    if (
+      !current.isDirectory() ||
+      !sameFields(original, current, ["dev", "ino", "mode"])
+    ) {
+      throw failure("CC_SETTINGS_SOURCE_CHANGED");
+    }
+  }
+
+  function readOpenedSource() {
+    // Comparing opened handles avoids Node 22.12 Windows path-stat's projected
+    // zero device; both identities come from the same API and real volume.
+    const parent = fs.fstatSync(open(canonicalParent), { bigint: true });
+    if (!parent.isDirectory()) throw failure("CC_SETTINGS_SOURCE_UNSAFE");
+    const common = {
+      logicalPath,
+      physicalPath,
+      nearestExistingParent: canonicalParent,
+      remainingPath: path.join(...remaining),
+      parentIdentity: Object.freeze({
+        dev: String(parent.dev),
+        ino: String(parent.ino),
+      }),
+    };
+    if (!entry) {
+      if (lstatOrMissing(fs, logicalPath))
+        throw failure("CC_SETTINGS_SOURCE_CHANGED");
+      verifyParent(parent);
+      if (lstatOrMissing(fs, path.join(logicalParent, remaining[0])))
+        throw failure("CC_SETTINGS_SOURCE_CHANGED");
+      if (lstatOrMissing(fs, physicalPath))
+        throw failure("CC_SETTINGS_SOURCE_CHANGED");
+      return Object.freeze({
+        ...common,
+        exists: false,
+        byteLength: 0,
+        digest: null,
+        settings: null,
+      });
+    }
+
+    const fd = open(physicalPath);
+    const before = fs.fstatSync(fd, { bigint: true });
+    assertRegularFile(before);
+    if (before.size > BigInt(maxBytes))
+      throw failure("CC_SETTINGS_SOURCE_TOO_LARGE");
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let length = 0;
+    for (;;) {
+      const count = fs.readSync(
+        fd,
+        buffer,
+        length,
+        buffer.length - length,
+        length,
+      );
+      if (!count) break;
+      length += count;
+      if (length > maxBytes) throw failure("CC_SETTINGS_SOURCE_TOO_LARGE");
+    }
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (
+      !sameFields(before, after, FILE_FIELDS) ||
+      BigInt(length) !== after.size
+    ) {
+      throw failure("CC_SETTINGS_SOURCE_CHANGED");
+    }
+    const finalEntry = lstatOrMissing(fs, logicalPath);
+    if (!finalEntry) throw failure("CC_SETTINGS_SOURCE_CHANGED");
+    assertRegularFile(finalEntry);
+    const reopened = fs.fstatSync(open(physicalPath), { bigint: true });
+    if (!sameFields(before, reopened, FILE_FIELDS))
+      throw failure("CC_SETTINGS_SOURCE_CHANGED");
+    verifyParent(parent);
+    const bytes = buffer.subarray(0, length);
+    let settings;
+    try {
+      const text = new TextDecoder("utf-8", {
+        fatal: true,
+        ignoreBOM: true,
+      }).decode(bytes);
+      settings = JSON.parse(text);
+      if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        throw new TypeError("Settings must be an object");
+    } catch (cause) {
+      throw failure("CC_SETTINGS_SOURCE_INVALID", cause);
+    }
+    return Object.freeze({
+      ...common,
+      exists: true,
+      byteLength: length,
+      digest: createHash("sha256").update(bytes).digest("hex"),
+      settings: freezeJson(settings),
+    });
+  }
+  let result;
+  let bodyError = null;
+  let bodyThrew = false;
+  let closeError = null;
+  try {
+    result = readOpenedSource();
+  } catch (cause) {
+    bodyThrew = true;
+    bodyError = cause;
+  } finally {
+    for (const fd of descriptors.reverse()) {
+      try {
+        fs.closeSync(fd);
+      } catch (cause) {
+        closeError ??= cause;
+      }
+    }
+  }
+  if (bodyThrew) throw bodyError;
+  if (closeError) throw closeError;
+  return result;
+}
+
+function observeSettingsSource(
+  file,
+  { fs = fsDefault, maxBytes = MAX_SETTINGS_SOURCE_BYTES } = {},
+) {
+  if (typeof file !== "string" || !file || file.includes("\0"))
+    throw new TypeError("A settings source path is required");
+  if (
+    !Number.isSafeInteger(maxBytes) ||
+    maxBytes < 1 ||
+    maxBytes > MAX_SETTINGS_SOURCE_BYTES
+  )
+    throw new TypeError("Settings source byte limit is invalid");
+  try {
+    return inspect(file, fs, maxBytes);
+  } catch (cause) {
+    if (cause?.name === "SettingsSourceObservationError") throw cause;
+    throw failure("CC_SETTINGS_SOURCE_UNAVAILABLE", cause);
+  }
+}
+
+function observeSettingsSources(files, options = {}) {
+  if (!Array.isArray(files) || files.length > MAX_SETTINGS_SOURCES)
+    throw new TypeError("Settings source list must be bounded");
+  // Resolve every input before the first filesystem operation; later chdir
+  // cannot change where a remaining relative candidate is inspected.
+  const resolved = files.map((file) => {
+    if (typeof file !== "string" || !file || file.includes("\0"))
+      throw new TypeError("A settings source path is required");
+    return path.resolve(file);
+  });
+  return Object.freeze(
+    resolved.map((file) => observeSettingsSource(file, options)),
+  );
+}
+
+module.exports = {
+  MAX_SETTINGS_SOURCE_BYTES,
+  MAX_SETTINGS_SOURCES,
+  observeSettingsSource,
+  observeSettingsSources,
+};

package/src/lib/sub-agent-context.js

@@ -9,6 +9,10 @@
  */
 
 import crypto from "crypto";
+import {
+  captureAgentExecutionPolicy,
+  resolveAgentToolSelection,
+} from "./agent-execution-policy.js";
 import { CLIContextEngineering } from "./cli-context-engineering.js";
 import {
   agentLoop,
@@ -206,7 +210,12 @@ export class SubAgentContext {
     this.taskProgressTracker = options.taskProgressTracker || null;
     this.tokenBudget = options.tokenBudget || null;
     this.inheritedContext = options.inheritedContext || null;
-    this.allowedTools = options.allowedTools ?? null; // null = all; [] = none
+    const executionPolicy = captureAgentExecutionPolicy(options);
+    const toolSelection = resolveAgentToolSelection(executionPolicy);
+    Object.defineProperty(this, "allowedTools", {
+      value: toolSelection.enabledToolNames, // null = all; [] = none
+      enumerable: true,
+    });
     this.depth = options.depth || 1; // nesting level (parent main loop = 0)
     // Shared run-wide TOTAL-sub-agent counter (one object across the whole tree)
     // so this sub-agent's own spawns draw from the same breadth pool.
@@ -218,7 +227,10 @@ export class SubAgentContext {
     // Optional session-level Extension Tier admission policy. Keep it as an
     // explicit inherited capability so child loops cannot silently bypass the
     // parent's admission decision.
-    this.toolAdmission = options.toolAdmission || null;
+    Object.defineProperty(this, "toolAdmission", {
+      value: executionPolicy.toolAdmission,
+      enumerable: true,
+    });
     // Skill capability INTERSECT: null = unrestricted; a list (possibly empty)
     // restricts run_skill/list_skills in this context's loop to those skills.
     this.skillAllowlist =
@@ -374,14 +386,11 @@ export class SubAgentContext {
       permissionRules: options.permissionRules || null,
       permissionRulesProvider: options.permissionRulesProvider || null,
       hostManagedToolPolicy: options.hostManagedToolPolicy || null,
+      hostManagedToolPolicyAuthority:
+        options.hostManagedToolPolicyAuthority || null,
       planManager: options.planManager || null,
-      sandbox: options.sandbox || null,
-      additionalDirectories: Array.isArray(options.additionalDirectories)
-        ? Object.freeze([...options.additionalDirectories])
-        : null,
-      shellPolicyOverrides: options.shellPolicyOverrides || null,
-      classifyAllShell: options.classifyAllShell === true,
-      unattendedActionPolicy: options.unattendedActionPolicy || null,
+      ...executionPolicy,
+      disabledTools: toolSelection.disabledTools,
     });
 
     // Build isolated system prompt
@@ -409,6 +418,8 @@ export class SubAgentContext {
    * @returns {Promise<{ summary: string, artifacts: Array, tokenCount: number, toolsUsed: string[], iterationCount: number }>}
    */
   async run(userPrompt, loopOptions = {}) {
+    const executionPolicy = captureAgentExecutionPolicy(loopOptions);
+    loopOptions = { ...loopOptions, ...executionPolicy };
     if (this.status !== "active") {
       throw new Error(
         `SubAgentContext ${this.id} is not active (status: ${this.status})`,
@@ -663,10 +674,14 @@ export class SubAgentContext {
     // Re-apply tighten-only capability fields after loopOptions. In particular,
     // [] must survive as deny-all and cannot be replaced by a worktree/direct
     // runner override.
-    if (Array.isArray(this.allowedTools)) {
-      options.enabledToolNames = [...this.allowedTools];
+    const selectionPolicy = captureAgentExecutionPolicy(options);
+    const toolSelection = resolveAgentToolSelection(
+      selectionPolicy,
+      this.allowedTools,
+    );
+    options.enabledToolNames = toolSelection.enabledToolNames;
+    if (Array.isArray(toolSelection.enabledToolNames))
       options.exactToolNames = true;
-    }
     options.subAgentContract = this.subAgentContract;
     options.sessionBudget = this.sessionBudget;
     options.hostResourceBudget = this.hostResourceBudget;
@@ -697,14 +712,17 @@ export class SubAgentContext {
     if (authority.hostManagedToolPolicy) {
       options.hostManagedToolPolicy = authority.hostManagedToolPolicy;
     }
+    if (authority.hostManagedToolPolicyAuthority) {
+      options.hostManagedToolPolicyAuthority =
+        authority.hostManagedToolPolicyAuthority;
+    }
     if (authority.planManager) options.planManager = authority.planManager;
     if (authority.sandbox) options.sandbox = authority.sandbox;
-    if (authority.additionalDirectories) {
-      options.additionalDirectories = [...authority.additionalDirectories];
-    }
-    if (authority.shellPolicyOverrides) {
-      options.shellPolicyOverrides = authority.shellPolicyOverrides;
-    }
+    options.additionalDirectories = authority.additionalDirectories || [];
+    options.shellPolicyOverrides = authority.shellPolicyOverrides;
+    options.disabledTools = Object.freeze([
+      ...new Set([...authority.disabledTools, ...toolSelection.disabledTools]),
+    ]);
     if (authority.classifyAllShell) options.classifyAllShell = true;
     if (authority.unattendedActionPolicy) {
       options.unattendedActionPolicy = authority.unattendedActionPolicy;