chainlesschain 0.162.175 → 0.162.177

package/src/lib/agent-tool-admission.js

@@ -30,6 +30,110 @@ export const TOOL_TIER = Object.freeze({
   EXTENSION: "extension",
 });
 
+const ADMISSION_BOOLEAN_FIELDS = Object.freeze([
+  "enforce",
+  "capabilityGranted",
+  "policyAllowed",
+  "permissionGranted",
+  "budgetOk",
+  "uiSupported",
+]);
+const ADMISSION_TEXT_FIELDS = Object.freeze([
+  "source",
+  "version",
+  "scope",
+  "tier",
+]);
+const ADMISSION_TEXT_PATTERN = /^[A-Za-z0-9@][A-Za-z0-9_.:/@+-]{0,127}$/;
+const RESERVED_TOOL_NAMES = new Set(["__proto__", "prototype", "constructor"]);
+
+/**
+ * Parse the IDE-to-CLI CC_TOOL_ADMISSION envelope. Only decision/provenance
+ * fields are accepted; arguments, prompts and credentials have no place in
+ * this contract. Invalid input throws so a host that opted into enforcement
+ * cannot silently fall back to an ungoverned session.
+ */
+export function parseToolAdmissionConfig(input) {
+  if (input == null || input === "") return null;
+  let raw;
+  try {
+    raw = typeof input === "string" ? input : JSON.stringify(input);
+  } catch {
+    throw new Error("tool admission config is not valid JSON");
+  }
+  if (typeof raw !== "string") {
+    throw new Error("tool admission config must be an object");
+  }
+  if (Buffer.byteLength(raw, "utf8") > 32768) {
+    throw new Error("tool admission config exceeds 32 KiB");
+  }
+  let value;
+  try {
+    value = typeof input === "string" ? JSON.parse(input) : input;
+  } catch {
+    throw new Error("tool admission config is not valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("tool admission config must be an object");
+  }
+  if (value.enforce !== true) {
+    throw new Error("tool admission config must set enforce=true");
+  }
+
+  const sanitize = (entry, label) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${label} must be an object`);
+    }
+    const out = {};
+    for (const field of ADMISSION_BOOLEAN_FIELDS) {
+      if (entry[field] !== undefined) {
+        if (typeof entry[field] !== "boolean") {
+          throw new Error(`${label}.${field} must be boolean`);
+        }
+        out[field] = entry[field];
+      }
+    }
+    for (const field of ADMISSION_TEXT_FIELDS) {
+      if (entry[field] !== undefined) {
+        if (
+          typeof entry[field] !== "string" ||
+          !ADMISSION_TEXT_PATTERN.test(entry[field])
+        ) {
+          throw new Error(`${label}.${field} must be a safe identifier`);
+        }
+        out[field] = entry[field];
+      }
+    }
+    return out;
+  };
+
+  const config = sanitize(value, "toolAdmission");
+  config.enforce = true;
+  if (value.tools !== undefined) {
+    if (
+      !value.tools ||
+      typeof value.tools !== "object" ||
+      Array.isArray(value.tools)
+    ) {
+      throw new Error("toolAdmission.tools must be an object");
+    }
+    const entries = Object.entries(value.tools);
+    if (entries.length > 256)
+      throw new Error("toolAdmission.tools exceeds 256 entries");
+    config.tools = {};
+    for (const [name, entry] of entries) {
+      if (
+        !/^[A-Za-z0-9_.:-]{1,160}$/.test(name) ||
+        RESERVED_TOOL_NAMES.has(name)
+      ) {
+        throw new Error(`invalid tool admission name: ${name}`);
+      }
+      config.tools[name] = sanitize(entry, `toolAdmission.tools.${name}`);
+    }
+  }
+  return config;
+}
+
 /** Normalize a tier label; anything unrecognized → EXTENSION (fail-closed). */
 export function normalizeToolTier(value) {
   const s = String(value || "")

package/src/lib/agent-worktree.js

@@ -11,24 +11,28 @@
  *    a merge hint. Removal failures fail-open to "kept".
  */
 
-import { execFileSync, execSync } from "child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { createWorktree, removeWorktree } from "./worktree-isolator.js";
 import { findProjectRoot } from "./project-instructions.js";
+import executionBroker from "./process-execution-broker/index.js";
 
 export const _deps = {
-  execFileSync,
-  execSync,
+  execFileSync: executionBroker.execFileSync.bind(executionBroker),
   createWorktree,
   removeWorktree,
 };
 
-function git(cmd, cwd, deps) {
-  return (deps.execSync || execSync)(`git ${cmd}`, {
+function git(args, cwd, deps, options = {}) {
+  const run = deps.execFileSync || _deps.execFileSync;
+  return run("git", args, {
     cwd,
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
+    stdio: options.stdio || ["ignore", "pipe", "ignore"],
+    origin: options.origin || "agent-worktree:query",
+    policy: "allow",
+    scope: "agent-worktree",
+    shell: false,
   });
 }
 
@@ -90,17 +94,17 @@ export function validateAgentWorktree(info, { deps = _deps } = {}) {
     }
 
     const repoTop = canonicalPath(
-      git("rev-parse --show-toplevel", info.repoRoot, deps).trim(),
+      git(["rev-parse", "--show-toplevel"], info.repoRoot, deps).trim(),
     );
     const worktreeTop = canonicalPath(
-      git("rev-parse --show-toplevel", worktreePath, deps).trim(),
+      git(["rev-parse", "--show-toplevel"], worktreePath, deps).trim(),
     );
     if (repoTop !== repo || worktreeTop !== worktree) {
       return { valid: false, reason: "worktree path identity mismatch" };
     }
 
     const registered = parseRegisteredWorktrees(
-      git("worktree list --porcelain", info.repoRoot, deps),
+      git(["worktree", "list", "--porcelain"], info.repoRoot, deps),
     ).find((entry) => {
       try {
         return canonicalPath(entry.path) === worktree;
@@ -138,16 +142,13 @@ function removeVerifiedAgentWorktree(info, deps) {
     return null;
   }
 
-  const run = deps.execFileSync || execFileSync;
-  run("git", ["worktree", "remove", info.path], {
-    cwd: info.repoRoot,
-    encoding: "utf8",
+  git(["worktree", "remove", info.path], info.repoRoot, deps, {
+    origin: "agent-worktree:cleanup",
     stdio: ["ignore", "pipe", "pipe"],
   });
   try {
-    run("git", ["branch", "-D", "--", info.branch], {
-      cwd: info.repoRoot,
-      encoding: "utf8",
+    git(["branch", "-D", "--", info.branch], info.repoRoot, deps, {
+      origin: "agent-worktree:cleanup",
       stdio: ["ignore", "pipe", "pipe"],
     });
     return null;
@@ -174,7 +175,7 @@ export function setupAgentWorktree({
   const suffix = Math.random().toString(36).slice(2, 6);
   const branch = `cc-agent-${stamp}-${suffix}`;
   const info = (deps.createWorktree || createWorktree)(repoRoot, branch);
-  const baseSha = git("rev-parse HEAD", info.path, deps).trim();
+  const baseSha = git(["rev-parse", "HEAD"], info.path, deps).trim();
   return { ...info, repoRoot, baseSha };
 }
 
@@ -205,8 +206,8 @@ export function finishAgentWorktree(info, { deps = _deps } = {}) {
   let headSha = null;
   let readable = false;
   try {
-    dirty = git("status --porcelain", info.path, deps).trim().length > 0;
-    headSha = git("rev-parse HEAD", info.path, deps).trim();
+    dirty = git(["status", "--porcelain"], info.path, deps).trim().length > 0;
+    headSha = git(["rev-parse", "HEAD"], info.path, deps).trim();
     readable = true;
   } catch {
     /* unreadable → keep, never destroy work we cannot verify */

package/src/lib/api-key-helper.js

@@ -14,7 +14,7 @@
  * rule). Cached per process (5 min) so multi-call runs don't re-spawn it.
  */
 
-import { execSync } from "node:child_process";
+import { executionBroker } from "./process-execution-broker/index.js";
 
 const TTL_MS = 5 * 60 * 1000;
 const _cache = new Map(); // helper command → { key, at }
@@ -31,7 +31,15 @@ export function resolveApiKeyFromHelper(helperCmd, opts = {}) {
   const now = opts.now || Date.now;
   const hit = _cache.get(cmd);
   if (hit && now() - hit.at < TTL_MS) return hit.key;
-  const exec = opts.exec || execSync;
+  const exec =
+    opts.exec ||
+    ((command, options) =>
+      executionBroker.execSync(command, {
+        ...options,
+        origin: "credential:api-key-helper",
+        policy: "allow",
+        scope: "credential",
+      }));
   try {
     const out = exec(cmd, {
       encoding: "utf-8",

package/src/lib/async-hook-supervisor.cjs

@@ -28,11 +28,10 @@
  *   - tree-reaping of every child on stopAll() / process 'exit', so a session
  *     never leaves an orphan hook process.
  *
- * `_deps.spawn` / `_deps.now` are injected so the whole supervisor is unit-
+ * Process runners and `_deps.now` are injected so the whole supervisor is unit-
  * testable with fake child processes (no real shell).
  */
 
-const cpDefault = require("node:child_process");
 const { tryParseDecision } = require("./hook-runner.cjs");
 
 const DEFAULT_TIMEOUT_MS = 60000;
@@ -52,8 +51,10 @@ class AsyncHookSupervisor {
         ? Number(opts.maxConcurrent)
         : DEFAULT_MAX_CONCURRENT;
     this._deps = {
-      spawn: opts.spawn || cpDefault.spawn,
-      spawnSync: opts.spawnSync || cpDefault.spawnSync,
+      run: opts.run || opts.spawn || null,
+      runSync: opts.runSync || opts.spawnSync || null,
+      killProcess: opts.killProcess || process.kill.bind(process),
+      platform: opts.platform || process.platform,
       now: opts.now || (() => Date.now()),
     };
     this._running = new Map(); // key -> { child, timer }
@@ -125,8 +126,12 @@ class AsyncHookSupervisor {
       return;
     }
     try {
-      if (process.platform === "win32") {
-        const r = this._deps.spawnSync(
+      if (this._deps.platform === "win32") {
+        // Snapshot before taskkill: a policy-restricted taskkill may terminate
+        // the shell and then fail on its descendants, orphaning them so a
+        // parent-PID query performed afterward can no longer find the tree.
+        const descendants = this._windowsDescendantPids(pid);
+        const r = this._deps.runSync(
           "taskkill",
           ["/PID", String(pid), "/T", "/F"],
           { windowsHide: true },
@@ -135,20 +140,27 @@ class AsyncHookSupervisor {
         // tree snapshot and termination. Repeat once so that race cannot
         // leave a short-lived hook grandchild orphaned.
         if (!r?.error && r?.status === 0) {
-          this._deps.spawnSync(
-            "taskkill",
-            ["/PID", String(pid), "/T", "/F"],
-            { windowsHide: true },
-          );
+          this._deps.runSync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+            windowsHide: true,
+          });
         }
-        // If taskkill couldn't launch, fall back to a direct kill.
+        // Restricted runners can launch taskkill but still receive a non-zero
+        // access/policy result. Enumerate the tree while it is still alive,
+        // then terminate descendants leaf-first before killing the shell.
         if (r && (r.error || (r.status != null && r.status !== 0))) {
+          for (const descendant of descendants.reverse()) {
+            try {
+              this._deps.killProcess(descendant, "SIGKILL");
+            } catch {
+              /* already gone */
+            }
+          }
           child.kill(signal);
         }
       } else {
         // Negative pid → the whole process group (requires the detached spawn).
         try {
-          process.kill(-pid, signal);
+          this._deps.killProcess(-pid, signal);
         } catch {
           child.kill(signal);
         }
@@ -162,6 +174,102 @@ class AsyncHookSupervisor {
     }
   }
 
+  /**
+   * Snapshot a Windows process tree for the taskkill-denied fallback. Query the
+   * process table once instead of issuing a quoted WMIC `where` expression for
+   * every level: Node/cmd quoting can silently turn that expression into an
+   * invalid WMIC alias query. PowerShell/CIM covers systems where WMIC has been
+   * removed. Traversal is bounded + cycle-safe so corrupt data cannot stall
+   * session teardown.
+   */
+  _windowsDescendantPids(rootPid) {
+    if (this._deps.platform !== "win32") return [];
+    const root = Number(rootPid);
+    if (!Number.isInteger(root) || root <= 0) return [];
+    let output = "";
+    let shouldTryCim = false;
+    try {
+      const result = this._deps.runSync(
+        "wmic",
+        [
+          "path",
+          "Win32_Process",
+          "get",
+          "ParentProcessId,ProcessId",
+          "/format:csv",
+        ],
+        {
+          encoding: "utf8",
+          windowsHide: true,
+          timeout: 3000,
+        },
+      );
+      if (!result?.error && result?.status === 0) {
+        output = String(result.stdout || "");
+      } else if (result?.error?.code === "ENOENT") {
+        shouldTryCim = true;
+      }
+    } catch {
+      shouldTryCim = true;
+    }
+    if (!output && shouldTryCim) {
+      try {
+        const result = this._deps.runSync(
+          "powershell.exe",
+          [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Get-CimInstance Win32_Process | ForEach-Object { '{0},{1}' -f $_.ParentProcessId,$_.ProcessId }",
+          ],
+          {
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: 3000,
+          },
+        );
+        if (!result?.error && result?.status === 0) {
+          output = String(result.stdout || "");
+        }
+      } catch {
+        return [];
+      }
+    }
+
+    const childrenByParent = new Map();
+    for (const line of output.split(/\r?\n/)) {
+      const fields = line.trim().split(",");
+      if (fields.length < 2) continue;
+      const parentPid = Number(fields.at(-2));
+      const childPid = Number(fields.at(-1));
+      if (
+        !Number.isInteger(parentPid) ||
+        parentPid < 0 ||
+        !Number.isInteger(childPid) ||
+        childPid <= 0
+      ) {
+        continue;
+      }
+      const children = childrenByParent.get(parentPid) || [];
+      children.push(childPid);
+      childrenByParent.set(parentPid, children);
+    }
+
+    const seen = new Set([root]);
+    const pending = [root];
+    const descendants = [];
+    while (pending.length > 0 && seen.size <= 256) {
+      const parentPid = pending.shift();
+      for (const childPid of childrenByParent.get(parentPid) || []) {
+        if (seen.has(childPid)) continue;
+        seen.add(childPid);
+        descendants.push(childPid);
+        pending.push(childPid);
+      }
+    }
+    return descendants;
+  }
+
   /** Install the process-exit reaper exactly once, only when a child exists. */
   _installExitHook() {
     if (this._exitHookInstalled) return;
@@ -251,17 +359,29 @@ class AsyncHookSupervisor {
 
     let child;
     try {
-      child = this._deps.spawn(hook.command, {
+      const spawnOptions = {
         cwd: opts.cwd || process.cwd(),
         shell: true,
         // POSIX: own process group so a timeout / stopAll can signal the whole
         // tree (shell + the real hook command), not just the shell wrapper.
         // No-op on Windows, where the tree is reaped via `taskkill /T` instead.
-        detached: process.platform !== "win32",
+        detached: this._deps.platform !== "win32",
         env: {
           ...process.env,
           CLAUDE_HOOK_EVENT: hook.event || payload.hook_event_name || "",
         },
+      };
+      if (typeof this._deps.run !== "function") {
+        throw new Error("async hook process runner unavailable");
+      }
+      child = this._deps.run(hook.command, {
+        ...spawnOptions,
+        origin: hook.origin || "async-hook:command",
+        policy: "allow",
+        scope: "async-hook",
+        pluginId: hook.pluginId || null,
+        pluginVersion: hook.pluginVersion || null,
+        pluginSource: hook.pluginSource || null,
       });
     } catch (err) {
       this._record(hook, {

package/src/lib/async-hook-supervisor.js

@@ -0,0 +1,47 @@
+import supervisor from "./async-hook-supervisor.cjs";
+import executionBroker from "./process-execution-broker/index.js";
+
+const brokerRunner = executionBroker.spawn.bind(executionBroker);
+const brokerSyncRunner = executionBroker.spawnSync.bind(executionBroker);
+
+export const _processDeps = {
+  run: brokerRunner,
+  runSync: brokerSyncRunner,
+};
+
+function runAsyncHook(command, options = {}) {
+  return _processDeps.run(command, [], {
+    ...options,
+    origin: options.origin || "async-hook:command",
+    policy: "allow",
+    scope: "async-hook",
+  });
+}
+
+function runAsyncHookSupervisorCommand(command, args, options = {}) {
+  return _processDeps.runSync(command, args, {
+    ...options,
+    origin: options.origin || "async-hook:supervisor",
+    policy: "allow",
+    scope: "async-hook",
+  });
+}
+
+export class AsyncHookSupervisor extends supervisor.AsyncHookSupervisor {
+  constructor(options = {}) {
+    super({
+      ...options,
+      run: options.run || options.spawn || runAsyncHook,
+      runSync:
+        options.runSync || options.spawnSync || runAsyncHookSupervisorCommand,
+    });
+  }
+}
+
+export const { DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONCURRENT } = supervisor;
+
+export default {
+  AsyncHookSupervisor,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_MAX_CONCURRENT,
+};

package/src/lib/background-agent-supervisor.js

@@ -1,4 +1,3 @@
-import { spawn, spawnSync } from "node:child_process";
 import {
   closeSync,
   existsSync,
@@ -21,6 +20,7 @@ import {
   finishAgentWorktree,
   validateAgentWorktree,
 } from "./agent-worktree.js";
+import executionBroker from "./process-execution-broker/index.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
@@ -42,6 +42,16 @@ export const PID_IDENTITY_TOLERANCE_MS = 60000;
 const START_TIME_CACHE_TTL_MS = 10000;
 const _startTimeCache = new Map();
 
+function runSupervisorCommand(file, args, options, origin) {
+  return _deps.spawnSync(file, args, {
+    ...options,
+    origin,
+    policy: "allow",
+    scope: "background-agent",
+    shell: false,
+  });
+}
+
 /** CIM_DATETIME (`20260711120000.500000+480`) → epoch ms, null when unparseable. */
 export function parseCimDateToMs(raw) {
   const m =
@@ -77,7 +87,7 @@ function defaultReadProcessStartTimeMs(pid) {
     // wmic first (fast, ~100-300ms); PowerShell CIM as fallback (wmic is
     // removed from recent Windows 11 builds).
     try {
-      const r = spawnSync(
+      const r = runSupervisorCommand(
         "wmic",
         [
           "process",
@@ -88,6 +98,7 @@ function defaultReadProcessStartTimeMs(pid) {
           "/value",
         ],
         { windowsHide: true, encoding: "utf8", timeout: 5000 },
+        "background-agent:process-start-time",
       );
       if (!r.error && r.status === 0) {
         const m = /CreationDate=([^\r\n]+)/.exec(r.stdout || "");
@@ -101,10 +112,11 @@ function defaultReadProcessStartTimeMs(pid) {
       const script =
         `$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${target}' -ErrorAction SilentlyContinue; ` +
         "if ($p -and $p.CreationDate) { [DateTimeOffset]::new($p.CreationDate).ToUnixTimeMilliseconds() }";
-      const r = spawnSync(
+      const r = runSupervisorCommand(
         "powershell",
         ["-NoProfile", "-NonInteractive", "-Command", script],
         { windowsHide: true, encoding: "utf8", timeout: 10000 },
+        "background-agent:process-start-time",
       );
       if (!r.error && r.status === 0) {
         const n = Number(String(r.stdout || "").trim());
@@ -118,10 +130,15 @@ function defaultReadProcessStartTimeMs(pid) {
   // POSIX: `ps -o lstart=` gives an absolute start timestamp on Linux + macOS
   // (procps and BSD ps both support it; busybox ps does not → null → open).
   try {
-    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(target)], {
-      encoding: "utf8",
-      timeout: 5000,
-    });
+    const r = runSupervisorCommand(
+      "ps",
+      ["-o", "lstart=", "-p", String(target)],
+      {
+        encoding: "utf8",
+        timeout: 5000,
+      },
+      "background-agent:process-start-time",
+    );
     if (!r.error && r.status === 0) {
       const t = Date.parse(String(r.stdout || "").trim());
       if (Number.isFinite(t) && t > 0) return t;
@@ -147,13 +164,14 @@ function defaultKillProcessTree(pid, signal = "SIGKILL") {
   if (target === process.pid) return false;
   try {
     if (process.platform === "win32") {
-      const r = _deps.spawnSync(
+      const r = runSupervisorCommand(
         "taskkill",
         ["/PID", String(target), "/T", "/F"],
         {
           windowsHide: true,
           encoding: "utf8",
         },
+        "background-agent:process-tree-kill",
       );
       return !r.error && r.status === 0;
     }
@@ -170,8 +188,8 @@ function defaultKillProcessTree(pid, signal = "SIGKILL") {
 }
 
 export const _deps = {
-  spawn,
-  spawnSync,
+  spawn: executionBroker.spawn.bind(executionBroker),
+  spawnSync: executionBroker.spawnSync.bind(executionBroker),
   // Single POSIX signal seam: every kill this module issues goes through here
   // so tests can stub it — a bare `process.kill` is NOT interceptable and a
   // fixture recording a live pid would eat a REAL signal (the shard-2/4
@@ -741,7 +759,7 @@ export function resumeBackgroundAgent(id, prompt, options = {}) {
 }
 
 /**
- * Fail fast on an unusable cwd. Without this, spawn() surfaces a bad cwd as
+ * Fail fast on an unusable cwd. Without this, process launch surfaces a bad cwd as
  * an ASYNC 'error' event on the detached child — which nothing listened to
  * (uncaught exception with no context) — and the pre-written state/job files
  * stayed behind as a phantom "running" session. Deleted, file-replaced, and
@@ -826,6 +844,10 @@ export function launchBackgroundAgent({
       detached: true,
       stdio: "ignore",
       windowsHide: true,
+      origin: "background-agent:worker",
+      policy: "allow",
+      scope: "background-agent",
+      shell: false,
     });
   } catch (error) {
     rmSync(jobFile, { force: true });
@@ -922,13 +944,14 @@ export function stopBackgroundAgent(id) {
     return { ...lost, stopped: false };
   }
   if (process.platform === "win32") {
-    const killed = _deps.spawnSync(
+    const killed = runSupervisorCommand(
       "taskkill",
       ["/PID", String(state.pid), "/T", "/F"],
       {
         windowsHide: true,
         encoding: "utf8",
       },
+      "background-agent:stop-tree",
     );
     if (killed.error || (killed.status !== 0 && isProcessAlive(state.pid))) {
       throw new Error(

package/src/lib/background-task-manager.js

@@ -1 +1,5 @@
-export { TaskStatus, BackgroundTaskManager } from "../harness/background-task-manager.js";
+export {
+  _deps,
+  TaskStatus,
+  BackgroundTaskManager,
+} from "../harness/background-task-manager.js";