chainlesschain 0.166.82 → 0.166.83

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;