chainlesschain 0.162.159 → 0.162.161

package/src/lib/project-instructions.js

@@ -44,6 +44,83 @@ export const PROJECT_FILE_NAMES = ["cc.md", "CLAUDE.md", "AGENTS.md"];
 /** Local (gitignored) companion names, first match wins. */
 export const LOCAL_FILE_NAMES = ["cc.local.md", "CLAUDE.local.md"];
 
+/**
+ * `instructionExcludes` — a large-monorepo reduction lever (P1). Subtrees whose
+ * instruction / rule / @import files should NEVER load (legacy, vendored,
+ * generated). Opt-in: empty by default so behavior is byte-identical unless the
+ * caller (config `instructionExcludes`) sets it. Patterns are matched against a
+ * path RELATIVE to the project root, with forward slashes:
+ *   - a bare name (`node_modules`, `dist`) matches that segment ANYWHERE;
+ *   - a slashed prefix (`packages/legacy`) matches that dir and everything under;
+ *   - a glob (`**​/generated/**`, `vendor/*`) matches via `*`/`**`/`?`.
+ */
+export function normalizeInstructionExcludes(list) {
+  if (!Array.isArray(list)) return [];
+  return [
+    ...new Set(
+      list
+        .map((s) =>
+          String(s || "")
+            .trim()
+            .replace(/\\/g, "/")
+            .replace(/\/+$/, ""),
+        )
+        .filter(Boolean),
+    ),
+  ];
+}
+
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++; // `**/` also swallows the slash
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+/**
+ * True when a repo-relative path falls under an excluded subtree. A file is
+ * excluded when it, or any of its ancestor directories, matches a pattern.
+ */
+export function pathIsExcluded(relPath, excludes) {
+  if (!excludes || excludes.length === 0) return false;
+  const rel = String(relPath || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\/?/, "")
+    .replace(/\/+$/, "");
+  if (!rel) return false;
+  const segs = rel.split("/");
+  for (const pat of excludes) {
+    if (/[*?[\]]/.test(pat)) {
+      const re = globToRegExp(pat);
+      if (re.test(rel)) return true;
+      let acc = "";
+      for (const s of segs) {
+        acc = acc ? `${acc}/${s}` : s;
+        if (re.test(acc)) return true;
+      }
+    } else {
+      if (rel === pat || rel.startsWith(`${pat}/`)) return true;
+      // a bare (slash-free) name matches that path segment anywhere
+      if (!pat.includes("/") && segs.includes(pat)) return true;
+    }
+  }
+  return false;
+}
+
 // Same boundary rule as file-ref-expander: `@` at start / after whitespace or
 // an opening bracket-quote, so emails and decorative @ never match.
 const IMPORT_TOKEN_RE = /(^|[\s("'`[{])@([^\s"'`)\]}]+)/g;
@@ -100,13 +177,21 @@ export function findInstructionFiles(opts = {}) {
   const { fs, path, os } = resolveDeps(opts);
   const cwd = path.resolve(opts.cwd || process.cwd());
   const home = opts.home || os.homedir() || "";
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
 
   const seen = new Set();
   const out = [];
+  const root = findProjectRoot(cwd, opts) || cwd;
+  // A discovered file under an excluded subtree (relative to the project root)
+  // never loads. The user-scope file lives outside the repo, so it is exempt.
+  const excluded = (abs) =>
+    excludes.length > 0 &&
+    pathIsExcluded(path.relative(root, path.resolve(abs)), excludes);
   const push = (p, scope) => {
     if (!p) return;
     const abs = path.resolve(p);
     if (seen.has(abs) || !isFile(fs, abs)) return;
+    if (scope !== "user" && excluded(abs)) return;
     seen.add(abs);
     out.push({ path: abs, scope });
   };
@@ -121,7 +206,6 @@ export function findInstructionFiles(opts = {}) {
     );
   }
 
-  const root = findProjectRoot(cwd, opts) || cwd;
   const chain = [];
   let dir = cwd;
   for (;;) {
@@ -274,6 +358,10 @@ export function loadProjectInstructions(opts = {}) {
     : DEFAULT_MAX_TOTAL_BYTES;
 
   const roots = findInstructionFiles(opts);
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
+  const projectRoot =
+    findProjectRoot(path.resolve(opts.cwd || process.cwd()), opts) ||
+    path.resolve(opts.cwd || process.cwd());
   const visited = new Set(roots.map((r) => r.path));
   const out = [];
   const warnings = [];
@@ -322,6 +410,15 @@ export function loadProjectInstructions(opts = {}) {
       const resolved = path.resolve(baseDir, target);
       if (visited.has(resolved) || !isFile(fs, resolved)) continue; // silent:
       // non-files are decorative @tokens (npm scopes, emails), not imports.
+      // An @import that resolves under an excluded subtree does not load — the
+      // reduction lever must not be bypassed by an import pointing into it.
+      if (
+        excludes.length > 0 &&
+        pathIsExcluded(path.relative(projectRoot, resolved), excludes)
+      ) {
+        visited.add(resolved);
+        continue;
+      }
       // Refuse to import a credential / secret file. `cc agent` auto-loads
       // project memory, so a cloned/untrusted repo's cc.md must NOT be able to
       // pull `@~/.ssh/id_rsa` / `@../.env` into the LLM-bound system prompt

package/src/lib/project-mcp-trust.js

@@ -0,0 +1,87 @@
+/**
+ * Project `.mcp.json` fingerprint trust (gap-analysis 2026-07-11 P1 "MCP 生命
+ * 周期" — 配置指纹变化后重新信任).
+ *
+ * `--project-mcp` opts a run into a checked-in `.mcp.json`, which can spawn
+ * arbitrary commands. That consent is for the file AS THE USER SAW IT — a
+ * later commit (or a compromised dependency's postinstall) editing the file
+ * must not ride the standing opt-in. So the first successful load records a
+ * sha256 fingerprint per absolute file path; a later load whose content no
+ * longer matches is REFUSED (fail-closed) until the user re-trusts via
+ * `CC_PROJECT_MCP_TRUST=1` (one-shot) or `cc mcp trust-project`.
+ *
+ * Store: ~/.chainlesschain/trusted-project-mcp.json  { [absPath]: {fingerprint, trustedAt} }
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getHomeDir } from "./paths.js";
+
+export const _deps = { fs };
+
+function storePath(opts = {}) {
+  return (
+    opts.storePath ||
+    process.env.CC_PROJECT_MCP_TRUST_STORE ||
+    path.join(getHomeDir(), "trusted-project-mcp.json")
+  );
+}
+
+export function projectMcpFingerprint(content) {
+  return createHash("sha256").update(String(content), "utf-8").digest("hex");
+}
+
+function readStore(opts) {
+  try {
+    const raw = _deps.fs.readFileSync(storePath(opts), "utf-8");
+    const data = JSON.parse(raw);
+    return data && typeof data === "object" ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check a project .mcp.json against the trust store.
+ * @returns {{status:"first-use"|"trusted"|"changed", fingerprint:string}}
+ */
+export function checkProjectMcpTrust(file, content, opts = {}) {
+  const fingerprint = projectMcpFingerprint(content);
+  const record = readStore(opts)[path.resolve(file)];
+  if (!record || !record.fingerprint) {
+    return { status: "first-use", fingerprint };
+  }
+  return {
+    status: record.fingerprint === fingerprint ? "trusted" : "changed",
+    fingerprint,
+  };
+}
+
+/** Record (or re-record) the trusted fingerprint for a file. */
+export function recordProjectMcpTrust(file, content, opts = {}) {
+  const target = storePath(opts);
+  const store = readStore(opts);
+  store[path.resolve(file)] = {
+    fingerprint: projectMcpFingerprint(content),
+    trustedAt: new Date(
+      typeof opts.now === "number" ? opts.now : Date.now(),
+    ).toISOString(),
+  };
+  try {
+    _deps.fs.mkdirSync(path.dirname(target), { recursive: true });
+    _deps.fs.writeFileSync(target, JSON.stringify(store, null, 2), {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+    return true;
+  } catch {
+    return false; // best-effort — a failed record just re-prompts next run
+  }
+}
+
+/** Truthy CC_PROJECT_MCP_TRUST → the user explicitly re-trusts this run. */
+export function projectMcpRetrustRequested(env = process.env) {
+  const raw = String(env.CC_PROJECT_MCP_TRUST || "").toLowerCase();
+  return raw === "1" || raw === "true";
+}

package/src/lib/remote-path-mapping.js

@@ -0,0 +1,229 @@
+/**
+ * Remote URI ↔ filesystem path mapping for the IDE bridge.
+ *
+ * A local IDE (VS Code / JetBrains) can report a file in a representation that
+ * does not exist on the host `cc` runs on, so inlining it into the prompt makes
+ * the agent's read_file/edit_file target a path the CLI host can't see:
+ *   - a URI:  file:///c:/code/my%20proj/文件.ts
+ *             vscode-remote://wsl+Ubuntu/home/u/x
+ *             vscode-remote://ssh-remote+host/home/u/x
+ *             vscode-remote://dev-container+<hex>/workspaces/x
+ *   - a WSL UNC path from a Windows host: \\wsl.localhost\Ubuntu\home\u\x
+ *     (older Windows builds: \\wsl$\Ubuntu\home\u\x)
+ *   - a Windows drive path while cc runs INSIDE WSL: C:\code\x  ==  /mnt/c/code/x
+ *
+ * normalizeIdePathForCli() folds these foreign forms into the CLI's native fs
+ * path; anything already native (or unrecognized) passes through byte-for-byte.
+ * cliPathToIdeUri() is the reverse, for surfaces that must hand a URI back to
+ * the editor.
+ *
+ * Pure: string transforms only (no fs / process). Percent-decoding preserves
+ * spaces and non-ASCII (中文) exactly, so round-trips are lossless.
+ */
+
+/** decodeURIComponent that never throws on a malformed % sequence. */
+function decodeSafe(s) {
+  if (typeof s !== "string") return s;
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s; // leave a malformed sequence as-is rather than lose the value
+  }
+}
+
+/** Has a `scheme://` prefix (a URI, not a bare path). */
+export function looksLikeUri(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9.+-]*:\/\//i.test(value);
+}
+
+/** `C:\…` or `C:/…` — a Windows drive-absolute path. */
+export function looksLikeWindowsPath(value) {
+  return typeof value === "string" && /^[a-zA-Z]:[\\/]/.test(value);
+}
+
+/** `\\host\…` or `//host/…` — a UNC path. */
+function looksLikeUnc(value) {
+  return typeof value === "string" && /^(\\\\|\/\/)[^\\/]/.test(value);
+}
+
+const WSL_UNC_RE =
+  /^(?:\\\\|\/\/)(?:wsl\.localhost|wsl\$)[\\/]([^\\/]+)[\\/]?(.*)$/i;
+
+/**
+ * `\\wsl.localhost\Ubuntu\home\u\x` (or `\\wsl$\…`, forward-slash variants) →
+ * `{ distro:"Ubuntu", posix:"/home/u/x" }`, or null when not a WSL UNC path.
+ */
+export function wslUncToPosix(value) {
+  if (typeof value !== "string") return null;
+  const m = value.match(WSL_UNC_RE);
+  if (!m) return null;
+  const distro = m[1];
+  const rest = (m[2] || "").replace(/\\/g, "/");
+  return { distro, posix: "/" + rest.replace(/^\/+/, "") };
+}
+
+/** `/home/u/x` + distro → `\\wsl.localhost\Ubuntu\home\u\x` (host overridable). */
+export function posixToWslUnc(posix, distro, { host = "wsl.localhost" } = {}) {
+  if (typeof posix !== "string" || !distro) return null;
+  const win = posix.replace(/^\/+/, "").replace(/\//g, "\\");
+  return `\\\\${host}\\${distro}\\${win}`;
+}
+
+/** `C:\code\x` → `/mnt/c/code/x`, or null when not a drive path. */
+export function winDriveToWslMount(value) {
+  if (!looksLikeWindowsPath(value)) return null;
+  const drive = value[0].toLowerCase();
+  const rest = value.slice(2).replace(/\\/g, "/").replace(/^\/+/, "");
+  return `/mnt/${drive}${rest ? "/" + rest : ""}`;
+}
+
+const WSL_MOUNT_RE = /^\/mnt\/([a-zA-Z])(?:\/(.*))?$/;
+
+/** `/mnt/c/code/x` → `C:\code\x`, or null when not a /mnt/<drive> path. */
+export function wslMountToWinDrive(value) {
+  if (typeof value !== "string") return null;
+  const m = value.match(WSL_MOUNT_RE);
+  if (!m) return null;
+  const drive = m[1].toUpperCase();
+  const rest = (m[2] || "").replace(/\//g, "\\");
+  return `${drive}:\\${rest}`;
+}
+
+/**
+ * Parse an IDE URI into its parts. Returns null for a non-URI or an unknown
+ * scheme (so the caller leaves it untouched).
+ *   { scheme, remoteKind, remoteParam, fsPath }
+ * `fsPath` is the decoded on-host path: a Windows drive path for a `file://`
+ * drive URI, else POSIX. `remoteKind`/`remoteParam` are set for vscode-remote.
+ */
+export function parseRemoteUri(uri) {
+  if (!looksLikeUri(uri)) return null;
+  const m = uri.match(/^([a-z][a-z0-9.+-]*):\/\/([^/]*)((?:\/[^?#]*)?)/i);
+  if (!m) return null;
+  const scheme = m[1].toLowerCase();
+  const authority = m[2] || "";
+  const rawPath = m[3] || "";
+
+  if (scheme === "file") {
+    if (authority) {
+      // file://server/share/… → UNC \\server\share\…
+      const unc = "\\\\" + authority + rawPath.replace(/\//g, "\\");
+      return {
+        scheme,
+        remoteKind: null,
+        remoteParam: null,
+        fsPath: decodeSafe(unc),
+      };
+    }
+    const decoded = decodeSafe(rawPath);
+    // /c:/code/x → c:\code\x  (Windows drive URI); else a POSIX path.
+    if (/^\/[a-zA-Z]:/.test(decoded)) {
+      return {
+        scheme,
+        remoteKind: null,
+        remoteParam: null,
+        fsPath: decoded.slice(1).replace(/\//g, "\\"),
+      };
+    }
+    return {
+      scheme,
+      remoteKind: null,
+      remoteParam: null,
+      fsPath: decoded || "/",
+    };
+  }
+
+  if (scheme === "vscode-remote" || scheme === "vscode-vfs") {
+    // authority = "<kind>+<param>", where `+` may be percent-encoded (%2B).
+    const auth = decodeSafe(authority);
+    const plus = auth.indexOf("+");
+    const remoteKind = plus >= 0 ? auth.slice(0, plus) : auth;
+    const remoteParam = plus >= 0 ? auth.slice(plus + 1) : null;
+    return {
+      scheme,
+      remoteKind: remoteKind || null,
+      remoteParam: remoteParam || null,
+      fsPath: decodeSafe(rawPath) || "/",
+    };
+  }
+
+  return null; // unknown scheme — don't guess
+}
+
+/**
+ * Detect the running CLI's WSL context from env (best-effort). Returns
+ * `{ isWsl, distro }`. Injected in tests; ide-context passes process.env.
+ */
+export function detectWsl(env = {}) {
+  const distro = env.WSL_DISTRO_NAME || null;
+  const isWsl = Boolean(distro || env.WSL_INTEROP);
+  return { isWsl, distro };
+}
+
+/**
+ * Fold an IDE-reported file value into the path `cc` can actually open on THIS
+ * host. Only recognized foreign forms are rewritten; a native or unrecognized
+ * value is returned unchanged (byte-for-byte).
+ *
+ * @param {string} value  URI or path as the IDE reported it
+ * @param {object} [opts]
+ * @param {string} [opts.platform=process.platform]  the CLI host platform
+ * @param {{isWsl?:boolean, distro?:string}} [opts.wsl]  WSL context (see detectWsl)
+ * @returns {string}
+ */
+export function normalizeIdePathForCli(value, opts = {}) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  const platform = opts.platform || process.platform;
+  const wsl = opts.wsl || {};
+  const onWindows = platform === "win32";
+
+  // 1) Resolve a URI down to its on-host fsPath first.
+  let base = value;
+  let remoteKind = null;
+  let remoteParam = null;
+  if (looksLikeUri(value)) {
+    const parsed = parseRemoteUri(value);
+    if (!parsed) return value; // unknown scheme → leave untouched
+    base = parsed.fsPath;
+    remoteKind = parsed.remoteKind;
+    remoteParam = parsed.remoteParam;
+  }
+
+  if (onWindows) {
+    // Native form is a Windows path. A POSIX path from a wsl-remote URI is
+    // reachable from Windows as a \\wsl.localhost\<distro>\… UNC.
+    if (remoteKind === "wsl" && remoteParam && base.startsWith("/")) {
+      return posixToWslUnc(base, remoteParam) || base;
+    }
+    return base;
+  }
+
+  // Native form is POSIX (Linux remote-host or inside WSL).
+  const wslUnc = wslUncToPosix(base);
+  if (wslUnc) return wslUnc.posix;
+  if (looksLikeWindowsPath(base) && wsl.isWsl) {
+    return winDriveToWslMount(base) || base;
+  }
+  return base;
+}
+
+/**
+ * Reverse: a CLI-native fs path → a URI the editor can open. `remoteAuthority`
+ * (e.g. "wsl+Ubuntu", "ssh-remote+host") produces a vscode-remote URI; without
+ * it, a `file://` URI. Percent-encodes spaces / non-ASCII per component.
+ */
+export function cliPathToIdeUri(fsPath, { remoteAuthority } = {}) {
+  if (typeof fsPath !== "string" || fsPath.length === 0) return fsPath;
+  const isWinDrive = looksLikeWindowsPath(fsPath);
+  const posixish = fsPath.replace(/\\/g, "/");
+  const encoded = posixish
+    .split("/")
+    .map((seg) => (/^[a-zA-Z]:$/.test(seg) ? seg : encodeURIComponent(seg)))
+    .join("/");
+  if (remoteAuthority) {
+    const path = encoded.startsWith("/") ? encoded : "/" + encoded;
+    return `vscode-remote://${remoteAuthority}${path}`;
+  }
+  const path = isWinDrive ? "/" + encoded : encoded;
+  return `file://${path.startsWith("/") ? "" : "/"}${path}`;
+}

package/src/lib/schedule-planner.js

@@ -0,0 +1,136 @@
+/**
+ * Pure scheduling planner for the agent Scheduler / Monitor (P1 §"统一持久
+ * Scheduler、Monitor 和 Channel").
+ *
+ * The persisted store ([[agent-schedule-store.js]]) already guarantees the
+ * catch-up invariant — a cron down for N periods fires ONCE, not N times,
+ * because `advanceCron` jumps to `nextCronTime(now)` rather than stepping
+ * through every miss. This module adds the pieces a unified daemon event
+ * runtime still needs, all as PURE, clock-injected functions (no timers, no
+ * RNG, deterministic across restarts):
+ *
+ *   - **deterministic jitter** — spread tasks that share a cron minute (e.g.
+ *     every `0 * * * *`) by a STABLE per-task offset, so a shared tick is not a
+ *     thundering herd. The offset is a hash of the task id, so it never moves
+ *     across a restart (an RNG offset would, defeating the point).
+ *   - **adaptive next-wakeup** — the earliest future fire time, so a daemon
+ *     sleeps until then instead of polling.
+ *   - **expiry** — a task past `expiresAt` retires without a final fire.
+ *
+ * A daemon uses `partitionSchedule` (retire expired, fire due) then
+ * `msUntilNextWakeup` (sleep precisely). `jitterMs = 0` (the default) makes the
+ * due set byte-identical to the store's existing `due()`.
+ */
+
+// FNV-1a → a stable 32-bit hash. Deterministic and dependency-free, so the same
+// task always draws the same jitter offset (across processes and restarts).
+function hash32(str) {
+  let h = 0x811c9dc5;
+  const s = String(str ?? "");
+  for (let i = 0; i < s.length; i += 1) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * A stable jitter offset in `[0, jitterMs)` derived from the task id. Same id +
+ * same jitterMs → same offset, every time. `jitterMs <= 0` → no jitter (0).
+ */
+export function jitterOffsetMs(id, jitterMs) {
+  const j = Math.floor(Number(jitterMs) || 0);
+  if (j <= 0) return 0;
+  return hash32(id) % j;
+}
+
+/** The entry's base fire time: `dueAt` for a wakeup, `nextAt` otherwise. */
+export function baseFireAt(entry) {
+  if (!entry) return null;
+  const raw = entry.kind === "wakeup" ? entry.dueAt : entry.nextAt;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Base fire time with the entry's deterministic jitter applied. */
+export function effectiveFireAt(entry, jitterMs = 0) {
+  const base = baseFireAt(entry);
+  if (base == null) return null;
+  return base + jitterOffsetMs(entry?.id, jitterMs);
+}
+
+/** Is an entry still pending/active (not in a terminal state)? */
+export function isSchedulable(entry) {
+  if (!entry) return false;
+  if (entry.kind === "wakeup") return entry.status === "pending";
+  return entry.status === "active";
+}
+
+/**
+ * Expiry: a task with an `expiresAt` at or before `now` is retired regardless
+ * of its schedule. A missing / non-positive `expiresAt` never expires.
+ */
+export function isEntryExpired(entry, now) {
+  const exp = Number(entry?.expiresAt);
+  return Number.isFinite(exp) && exp > 0 && exp <= Number(now);
+}
+
+/**
+ * Partition schedulable entries at `now` into what a daemon should do:
+ *   - `expired` — retire (status → expired). Checked BEFORE due so an expired
+ *     task never gets a final fire.
+ *   - `due` — fire now (jittered fire time has arrived).
+ *   - `waiting` — still pending.
+ * Terminal entries are skipped entirely.
+ */
+export function partitionSchedule(entries, { now, jitterMs = 0 } = {}) {
+  const t = Number(now);
+  const expired = [];
+  const due = [];
+  const waiting = [];
+  for (const entry of entries || []) {
+    if (!isSchedulable(entry)) continue;
+    if (isEntryExpired(entry, t)) {
+      expired.push(entry);
+      continue;
+    }
+    const fireAt = effectiveFireAt(entry, jitterMs);
+    if (fireAt != null && fireAt <= t) due.push(entry);
+    else waiting.push(entry);
+  }
+  return { expired, due, waiting };
+}
+
+/**
+ * The earliest future jittered fire time among schedulable, non-expired
+ * entries — what a daemon sleeps until (adaptive wakeup). An already-due entry
+ * contributes `now` (fire immediately). Returns null when nothing is scheduled.
+ */
+export function nextWakeupAt(entries, { now, jitterMs = 0 } = {}) {
+  const t = Number(now);
+  let min = null;
+  for (const entry of entries || []) {
+    if (!isSchedulable(entry) || isEntryExpired(entry, t)) continue;
+    const fireAt = effectiveFireAt(entry, jitterMs);
+    if (fireAt == null) continue;
+    const at = fireAt <= t ? t : fireAt;
+    if (min == null || at < min) min = at;
+  }
+  return min;
+}
+
+/**
+ * Milliseconds until the next wakeup, clamped to `[0, maxMs]` (a cap keeps a
+ * far-future task from parking the daemon forever — it re-checks by `maxMs`).
+ * null when nothing is scheduled.
+ */
+export function msUntilNextWakeup(
+  entries,
+  { now, jitterMs = 0, maxMs = null } = {},
+) {
+  const at = nextWakeupAt(entries, { now, jitterMs });
+  if (at == null) return null;
+  let ms = Math.max(0, at - Number(now));
+  if (maxMs != null && Number.isFinite(maxMs)) ms = Math.min(ms, Number(maxMs));
+  return ms;
+}

package/src/lib/sensitive-file-guard.js

@@ -66,3 +66,54 @@ export function sensitiveFileReason(targetPath) {
   }
   return null;
 }
+
+/**
+ * Auto-exec CONFIG write guard — the CLI-side twin of the IDE extension's
+ * `classifyAutoExecTarget` (vscode-extension/src/auto-exec-guard.js, kept as
+ * an independent pure function: no cross-package import). These files are not
+ * shells or hooks, but writing them still plants code that RUNS without an
+ * explicit user action: VS Code tasks auto-run on folder open, launch configs
+ * fire on debug, `.mcp.json` spawns arbitrary server processes the agent then
+ * auto-loads, JetBrains run configurations execute on the next Run, and
+ * devcontainer postCreate/postStart commands run on container open. Same
+ * conservative name-based posture as `sensitiveFileReason`; an unknown path is
+ * simply not risky (null), never a false positive.
+ *
+ * @param {string} targetPath  path as the tool received it (rel or abs)
+ * @returns {string|null} human reason when auto-exec-risky, null otherwise
+ */
+export function autoExecConfigReason(targetPath) {
+  const p = String(targetPath || "");
+  if (!p) return null;
+  const norm = p.replace(/\\/g, "/").toLowerCase();
+  const base = norm.split("/").pop() || "";
+  if (!base) return null;
+  if (base === ".mcp.json" || base === "mcp.json") {
+    return `auto-exec config: MCP server config (${base}) — can spawn arbitrary server processes the agent auto-loads`;
+  }
+  if (/(^|\/)\.vscode\/tasks\.json$/.test(norm)) {
+    return "auto-exec config: VS Code tasks (.vscode/tasks.json) — tasks can auto-run on folder open";
+  }
+  if (/(^|\/)\.vscode\/launch\.json$/.test(norm)) {
+    return "auto-exec config: VS Code launch/debug config (.vscode/launch.json) — runs commands on the next debug session";
+  }
+  if (/(^|\/)\.vscode\/settings\.json$/.test(norm)) {
+    return "auto-exec config: VS Code workspace settings (.vscode/settings.json) — can rebind shells/tools the user then runs";
+  }
+  if (/(^|\/)\.idea\/runconfigurations\//.test(norm)) {
+    return `auto-exec config: JetBrains run configuration (${base}) — executes on the user's next Run action`;
+  }
+  if (/(^|\/)\.idea\/workspace\.xml$/.test(norm)) {
+    return "auto-exec config: JetBrains workspace.xml — can embed run/startup tasks";
+  }
+  if (
+    base === "devcontainer.json" ||
+    /(^|\/)\.devcontainer\/devcontainer\.json$/.test(norm)
+  ) {
+    return "auto-exec config: devcontainer.json — postCreate/postStart commands run on container open";
+  }
+  if (base.endsWith(".code-workspace")) {
+    return `auto-exec config: VS Code workspace file (${base}) — can carry auto-run tasks and settings`;
+  }
+  return null;
+}

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

@@ -253,12 +253,16 @@ export class SubAgentContext {
     const artifacts = [];
     let lastContent = "";
 
-    // Build filtered tool list
-    const tools = this._getFilteredTools();
-
     // Merge LLM options — pass shared iteration budget if available
     const options = {
       ...this._llmOptions,
+      // Tool allowlist (fixed 2026-07-11): the filtered list used to be
+      // computed via _getFilteredTools() but never handed to agentLoop, so a
+      // sub-agent's `tools`/frontmatter allowlist was silently ignored at the
+      // LLM surface. agentLoop consumes NAMES via enabledToolNames.
+      ...(Array.isArray(this.allowedTools) && this.allowedTools.length > 0
+        ? { enabledToolNames: this.allowedTools }
+        : {}),
       contextEngine: this.contextEngine,
       cwd: this.cwd,
       // Nesting level: lets a nested spawn_sub_agent see — and cap — its depth.