chainlesschain 0.162.166 → 0.162.168

package/src/lib/hook-runner.cjs

@@ -26,8 +26,9 @@ const {
   buildPowershellArgv,
   loadShellConfig,
 } = require("./shell-selector.cjs");
+const { mergeHookDecisions } = require("./hook-event-bus.cjs");
 
-const _deps = { spawnSync: cpDefault.spawnSync };
+const _deps = { spawnSync: cpDefault.spawnSync, spawn: cpDefault.spawn };
 
 const HOOK_DECISIONS = Object.freeze({
   BLOCK: "block",
@@ -116,43 +117,65 @@ function tryParseDecision(stdout) {
  *            stdout?:string, stderr?:string, additionalContext?:string,
  *            nonBlockingError?:boolean, error?:string }}
  */
+// Circuit breaker (gap 2026-07-11 P2 "Hooks 硬化"): N consecutive non-blocking
+// failures (spawn error / timeout / non-zero non-2 exit) of the SAME command
+// trip an open state — further runs are skipped for a cooldown, then one
+// half-open trial runs; success (or a real block/ask decision) closes it.
+// CC_HOOK_BREAKER_THRESHOLD=0 disables. Extracted so the sync + async runners
+// share ONE breaker implementation.
+function _breakerShortCircuit(command, breaker) {
+  if (breaker.threshold <= 0) return null;
+  const st = _breaker.get(command);
+  if (st && st.fails >= breaker.threshold) {
+    const now = Date.now();
+    if (now - st.openedAt < breaker.cooldownMs) {
+      return {
+        decision: HOOK_DECISIONS.CONTINUE,
+        reason: `hook circuit breaker open (${st.fails} consecutive failures) — skipped for cooldown`,
+        exitCode: null,
+        skipped: true,
+        breakerOpen: true,
+      };
+    }
+    // half-open: let this one trial through; the outcome records below.
+  }
+  return null;
+}
+
+function _breakerRecord(command, breaker, result) {
+  if (breaker.threshold <= 0) return;
+  if (result.nonBlockingError) {
+    const st = _breaker.get(command) || { fails: 0, openedAt: 0 };
+    st.fails += 1;
+    if (st.fails >= breaker.threshold) st.openedAt = Date.now();
+    _breaker.set(command, st);
+  } else {
+    _breaker.delete(command); // success / block / ask closes the breaker
+  }
+}
+
 function runCommandHook(command, input = {}, opts = {}) {
   if (!command) {
     return { decision: HOOK_DECISIONS.CONTINUE, reason: null, exitCode: 0 };
   }
-  // Circuit breaker (gap 2026-07-11 P2 "Hooks 硬化"): N consecutive
-  // non-blocking failures (spawn error / timeout / non-zero non-2 exit) of
-  // the SAME command trip an open state — further runs are skipped for a
-  // cooldown, then one half-open trial runs; success (or a real block/ask
-  // decision) closes it. CC_HOOK_BREAKER_THRESHOLD=0 disables.
   const breaker = hookBreakerConfig();
-  if (breaker.threshold > 0) {
-    const st = _breaker.get(command);
-    if (st && st.fails >= breaker.threshold) {
-      const now = Date.now();
-      if (now - st.openedAt < breaker.cooldownMs) {
-        return {
-          decision: HOOK_DECISIONS.CONTINUE,
-          reason: `hook circuit breaker open (${st.fails} consecutive failures) — skipped for cooldown`,
-          exitCode: null,
-          skipped: true,
-          breakerOpen: true,
-        };
-      }
-      // half-open: let this one trial through; the outcome below decides.
-    }
-  }
+  const shortCircuit = _breakerShortCircuit(command, breaker);
+  if (shortCircuit) return shortCircuit;
   const result = _runCommandHookInner(command, input, opts);
-  if (breaker.threshold > 0) {
-    if (result.nonBlockingError) {
-      const st = _breaker.get(command) || { fails: 0, openedAt: 0 };
-      st.fails += 1;
-      if (st.fails >= breaker.threshold) st.openedAt = Date.now();
-      _breaker.set(command, st);
-    } else {
-      _breaker.delete(command); // success / block / ask closes the breaker
-    }
+  _breakerRecord(command, breaker, result);
+  return result;
+}
+
+/** Async counterpart of runCommandHook (same breaker + protocol). */
+async function runCommandHookAsync(command, input = {}, opts = {}) {
+  if (!command) {
+    return { decision: HOOK_DECISIONS.CONTINUE, reason: null, exitCode: 0 };
   }
+  const breaker = hookBreakerConfig();
+  const shortCircuit = _breakerShortCircuit(command, breaker);
+  if (shortCircuit) return shortCircuit;
+  const result = await _runCommandHookInnerAsync(command, input, opts);
+  _breakerRecord(command, breaker, result);
   return result;
 }
 
@@ -230,7 +253,19 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
       nonBlockingError: true,
     };
   }
-  // spawnSync surfaces timeout/ENOENT on res.error (status null) — non-blocking.
+  return interpretHookOutcome(res);
+}
+
+/**
+ * Interpret a finished hook process — a spawnSync result OR the collected output
+ * of an async spawn — into a normalized decision. The exit-code / JSON-stdout
+ * protocol lives in ONE place so the sync and async runners can never drift.
+ *
+ * @param {{error?:Error|null, status:number|null, stdout?:string, stderr?:string}} res
+ */
+function interpretHookOutcome(res) {
+  // A surfaced spawn error (timeout / ENOENT, status null) is non-blocking — a
+  // broken hook must never wedge the agent; only an explicit block blocks.
   if (res.error) {
     return {
       decision: HOOK_DECISIONS.CONTINUE,
@@ -287,19 +322,157 @@ function _runCommandHookInner(command, input = {}, opts = {}) {
 }
 
 /**
- * Run a list of command hooks in order; first BLOCK (or ASK) short-circuits.
- * @returns {{ decision, reason, hook?, results }}
+ * Async single-hook runner — mirrors _runCommandHookInner but uses async spawn
+ * so a batch can run CONCURRENTLY (see runHooksParallel). stdin gets the JSON
+ * payload; stdout/stderr are collected (bounded); a hard timeout SIGKILLs a hung
+ * hook and reports it as a non-blocking error. Interpretation is shared via
+ * interpretHookOutcome so the exit-code protocol matches the sync path exactly.
+ */
+async function _runCommandHookInnerAsync(command, input = {}, opts = {}) {
+  const { cwd, event } = opts;
+  const _rawTimeout = Number(opts.timeout);
+  const timeout =
+    Number.isFinite(_rawTimeout) && _rawTimeout > 0
+      ? Math.min(_rawTimeout, 600000)
+      : 60000;
+  const shellKind = normalizeShellKind(opts.shell);
+  const usePowershell = shellKind === "powershell" || shellKind === "pwsh";
+  const wd = cwd || process.cwd();
+  const inputJson = JSON.stringify({
+    ...input,
+    schema_version: input.schema_version ?? HOOK_PAYLOAD_SCHEMA_VERSION,
+  });
+  const spawnEnv = {
+    ...process.env,
+    CLAUDE_HOOK_EVENT: event || input.hook_event_name || "",
+  };
+
+  let child;
+  try {
+    if (usePowershell) {
+      const { executionPolicy } = loadShellConfig({ cwd: wd });
+      const inv = buildPowershellArgv(command, shellKind, { executionPolicy });
+      child = _deps.spawn(inv.file, inv.argv, { cwd: wd, env: spawnEnv });
+    } else {
+      child = _deps.spawn(command, { cwd: wd, env: spawnEnv, shell: true });
+    }
+  } catch (err) {
+    return {
+      decision: HOOK_DECISIONS.CONTINUE,
+      reason: `hook spawn failed: ${err.message}`,
+      exitCode: null,
+      error: err.message,
+      nonBlockingError: true,
+    };
+  }
+
+  return await new Promise((resolve) => {
+    const MAXB = 8 * 1024 * 1024;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (res) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(interpretHookOutcome(res));
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already exited */
+      }
+      done({
+        error: new Error(`hook timed out after ${timeout}ms`),
+        status: null,
+        stdout,
+        stderr,
+      });
+    }, timeout);
+    if (typeof timer.unref === "function") timer.unref();
+
+    child.on("error", (err) =>
+      done({ error: err, status: null, stdout, stderr }),
+    );
+    if (child.stdout) {
+      child.stdout.on("data", (d) => {
+        if (stdout.length < MAXB) stdout += d.toString("utf8");
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (d) => {
+        if (stderr.length < MAXB) stderr += d.toString("utf8");
+      });
+    }
+    child.on("close", (code) =>
+      done({ error: null, status: code, stdout, stderr }),
+    );
+    // Feed the payload to the hook's stdin. A fast-exiting hook may close its
+    // end first (EPIPE) — that is harmless, the exit code still governs.
+    try {
+      if (child.stdin) {
+        child.stdin.on("error", () => {});
+        child.stdin.write(inputJson);
+        child.stdin.end();
+      }
+    } catch {
+      /* stdin already closed */
+    }
+  });
+}
+
+/**
+ * Run a list of command hooks and reduce to one decision.
+ *
+ * Default (`opts.mergeStrict` falsy): in-order, the first BLOCK **or** ASK
+ * short-circuits — byte-identical to the historical behavior.
+ *
+ * `opts.mergeStrict: true`: run EVERY matching hook (no short-circuit) then take
+ * the STRICTEST decision (block > ask > allow > continue) via mergeHookDecisions.
+ * This closes the safety gap where an earlier hook's `ask` masks a LATER hook's
+ * `block` (the short-circuit path returns `ask` and never runs the blocker).
+ * Claude-Code parity: all matching hooks contribute to the merged decision.
+ * spawnSync is synchronous so execution is sequential — but the MERGE is
+ * order-independent, so the outcome matches a parallel run.
+ *
+ * @returns {{ decision, reason, hook?, results, contributing? }}
  */
 function runHooks(commandHooks, input = {}, opts = {}) {
   const results = [];
-  for (const h of commandHooks || []) {
-    const r = runCommandHook(h.command, input, {
+  const hooks = commandHooks || [];
+  const runOne = (h) =>
+    runCommandHook(h.command, input, {
       ...opts,
       timeout: h.timeout != null ? h.timeout * 1000 : opts.timeout,
       // per-hook shell selection (P1 #8): `{ "type":"command", "command":…,
       // "shell":"powershell" }` in the settings hook entry
       shell: h.shell != null ? h.shell : opts.shell,
     });
+
+  if (opts.mergeStrict) {
+    const decisions = [];
+    for (const h of hooks) {
+      const r = runOne(h);
+      results.push({ command: h.command, ...r });
+      decisions.push({
+        decision: r.decision,
+        reason: r.reason,
+        hook: h.command,
+      });
+    }
+    const merged = mergeHookDecisions(decisions);
+    return {
+      decision: merged.decision,
+      reason: merged.reason,
+      hook: merged.hook,
+      results,
+      contributing: merged.contributing,
+    };
+  }
+
+  for (const h of hooks) {
+    const r = runOne(h);
     results.push({ command: h.command, ...r });
     if (
       r.decision === HOOK_DECISIONS.BLOCK ||
@@ -316,9 +489,48 @@ function runHooks(commandHooks, input = {}, opts = {}) {
   return { decision: HOOK_DECISIONS.CONTINUE, reason: null, results };
 }
 
+/**
+ * Run every matching hook CONCURRENTLY (async spawn) and reduce to the strictest
+ * decision (block > ask > allow > continue) via mergeHookDecisions — the true-
+ * parallel form of runHooks({mergeStrict}). Wall-clock is the slowest single hook
+ * rather than their sum; the merge is order-independent so the outcome matches
+ * the sequential strict merge exactly. Same per-hook timeout/shell resolution as
+ * runHooks. Returns the same shape ({decision, reason, hook, results,
+ * contributing}) so the decision consumers are unchanged.
+ */
+async function runHooksParallel(commandHooks, input = {}, opts = {}) {
+  const hooks = commandHooks || [];
+  const settled = await Promise.all(
+    hooks.map((h) =>
+      runCommandHookAsync(h.command, input, {
+        ...opts,
+        timeout: h.timeout != null ? h.timeout * 1000 : opts.timeout,
+        shell: h.shell != null ? h.shell : opts.shell,
+      }).then((r) => ({ h, r })),
+    ),
+  );
+  const results = settled.map(({ h, r }) => ({ command: h.command, ...r }));
+  const decisions = settled.map(({ h, r }) => ({
+    decision: r.decision,
+    reason: r.reason,
+    hook: h.command,
+  }));
+  const merged = mergeHookDecisions(decisions);
+  return {
+    decision: merged.decision,
+    reason: merged.reason,
+    hook: merged.hook,
+    results,
+    contributing: merged.contributing,
+  };
+}
+
 module.exports = {
   runCommandHook,
+  runCommandHookAsync,
   runHooks,
+  runHooksParallel,
+  interpretHookOutcome,
   tryParseDecision,
   HOOK_DECISIONS,
   HOOK_PAYLOAD_SCHEMA_VERSION,

package/src/lib/install-command-policy.js

@@ -0,0 +1,343 @@
+/**
+ * install-command-policy — a UNIFIED classifier + audit for package-install
+ * shell commands across managers (npm / pnpm / yarn / bun / pip / pipx / poetry /
+ * conda / brew / winget / choco / apt / dnf / yum / apk / snap / gem / cargo /
+ * go / composer / dotnet).
+ *
+ * The gap (docs/…INCREMENTAL_GAP_ANALYSIS P0 "跨平台沙箱"): "npm、pip、winget、brew
+ * 等安装入口需要统一权限类型与审计事件". Today a `run_shell` install command is just
+ * another shell command — there is no single place that recognizes "this fetches
+ * and runs third-party code" regardless of which tool does it, and no unified
+ * audit trail. This module supplies both, as PURE detection (no I/O) plus a
+ * best-effort injected-IO audit sink, so it can be reused by the shell approval
+ * path today and other entry points (run_code, hooks) later.
+ *
+ * Design: a per-manager table maps a binary to its install subcommand(s), a
+ * global-scope signal, and package extraction. `classifyInstallCommand` splits a
+ * compound command into segments (reusing the shell-policy splitter) so
+ * `npm i foo && pip install bar` reports BOTH installs. Nothing here changes a
+ * permission decision — callers decide whether to raise a risk floor; the
+ * classification is advisory + auditable.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import shellPolicy from "../runtime/coding-agent-shell-policy.cjs";
+
+const { splitCommandSegments, tokenizeShellCommand } = shellPolicy;
+
+// Leading tokens that wrap the real command and must be stripped before the
+// binary is read: privilege elevation, env-var assignments, and `env`/`command`.
+const WRAPPER_TOKENS = new Set([
+  "sudo",
+  "doas",
+  "env",
+  "command",
+  "exec",
+  "nice",
+]);
+
+/**
+ * Per-manager install detection. `sub` = subcommand keywords that mean "install".
+ * `system` = the install always affects the whole machine/user (no project
+ * scope), so it is treated as global regardless of flags. `globalFlags`/
+ * `globalWords` mark a per-tool global install. `packageWord` (dotnet) requires a
+ * keyword before the package name.
+ */
+const MANAGERS = [
+  {
+    name: "npm",
+    bin: /^npm$/,
+    sub: ["install", "i", "add", "ci"],
+    globalFlags: ["-g", "--global"],
+  },
+  {
+    name: "pnpm",
+    bin: /^pnpm$/,
+    sub: ["install", "i", "add"],
+    globalFlags: ["-g", "--global"],
+  },
+  {
+    name: "yarn",
+    bin: /^yarn$/,
+    sub: ["add", "install"],
+    globalWords: ["global"],
+  },
+  {
+    name: "bun",
+    bin: /^bun$/,
+    sub: ["install", "i", "add"],
+    globalFlags: ["-g", "--global"],
+  },
+  { name: "pip", bin: /^pip[0-9.]*$/, sub: ["install"], globalFlags: [] },
+  { name: "pipx", bin: /^pipx$/, sub: ["install"], system: true },
+  { name: "poetry", bin: /^poetry$/, sub: ["add"], globalFlags: [] },
+  { name: "conda", bin: /^conda$/, sub: ["install"], globalFlags: [] },
+  { name: "brew", bin: /^brew$/, sub: ["install"], system: true },
+  { name: "winget", bin: /^winget$/, sub: ["install"], system: true },
+  { name: "choco", bin: /^choco(latey)?$/, sub: ["install"], system: true },
+  { name: "apt", bin: /^apt(-get)?$/, sub: ["install"], system: true },
+  { name: "dnf", bin: /^(dnf|yum)$/, sub: ["install"], system: true },
+  { name: "apk", bin: /^apk$/, sub: ["add"], system: true },
+  { name: "snap", bin: /^snap$/, sub: ["install"], system: true },
+  { name: "gem", bin: /^gem$/, sub: ["install"], system: true },
+  { name: "cargo", bin: /^cargo$/, sub: ["install"], system: true },
+  { name: "go", bin: /^go$/, sub: ["install", "get"], system: true },
+  {
+    name: "composer",
+    bin: /^composer$/,
+    sub: ["require", "install"],
+    globalWords: ["global"],
+  },
+  {
+    name: "dotnet",
+    bin: /^dotnet$/,
+    sub: ["add"],
+    packageWord: "package",
+    system: false,
+  },
+];
+
+/** Basename of a binary path, minus a Windows .exe/.cmd/.bat/.ps1 suffix. */
+function normalizeBin(token) {
+  const base = String(token || "")
+    .replace(/\\/g, "/")
+    .split("/")
+    .pop();
+  return base.replace(/\.(exe|cmd|bat|ps1)$/i, "").toLowerCase();
+}
+
+/** Strip leading wrapper tokens (sudo/env/VAR=val) → the real argv, or null. */
+function unwrapArgv(tokens) {
+  let i = 0;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (WRAPPER_TOKENS.has(t) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  return tokens.slice(i);
+}
+
+/**
+ * Classify ONE already-split command segment. Returns an install descriptor or
+ * null. Pure.
+ * @returns {{manager:string, subcommand:string, packages:string[], global:boolean}|null}
+ */
+export function classifyInstallSegment(segment) {
+  let argv = unwrapArgv(tokenizeShellCommand(segment));
+  if (argv.length === 0) return null;
+  // Module invocation: `python -m pip install …` (and `py -m pip …`) is the
+  // canonical way run_code's auto-install — and plenty of humans — invoke pip;
+  // treat the module as the binary so it classifies like a direct `pip`.
+  if (
+    /^(python[0-9.]*|py)$/.test(normalizeBin(argv[0])) &&
+    argv[1] === "-m" &&
+    argv.length > 2
+  ) {
+    argv = argv.slice(2);
+  }
+  const bin = normalizeBin(argv[0]);
+  const mgr = MANAGERS.find((m) => m.bin.test(bin));
+  if (!mgr) return null;
+
+  const rest = argv.slice(1);
+  // Find the install subcommand token (first non-flag token that matches). For
+  // dotnet, the trigger is `add … package`, so also require the package word.
+  let subIdx = -1;
+  let subcommand = null;
+  for (let i = 0; i < rest.length; i++) {
+    const tok = rest[i];
+    if (mgr.sub.includes(tok)) {
+      subIdx = i;
+      subcommand = tok;
+      break;
+    }
+  }
+  if (subIdx === -1) return null;
+  if (mgr.packageWord && !rest.slice(subIdx + 1).includes(mgr.packageWord)) {
+    return null; // e.g. `dotnet add reference` is not a package install
+  }
+
+  // Everything after the subcommand (and, for dotnet, after `package`) that is
+  // not a flag = the requested packages (best-effort; enough for audit).
+  let argsAfter = rest.slice(subIdx + 1);
+  if (mgr.packageWord) {
+    const pw = argsAfter.indexOf(mgr.packageWord);
+    argsAfter = pw >= 0 ? argsAfter.slice(pw + 1) : argsAfter;
+  }
+  const packages = argsAfter.filter((t) => !t.startsWith("-"));
+
+  const global =
+    mgr.system === true ||
+    (mgr.globalFlags || []).some((f) => rest.includes(f)) ||
+    (mgr.globalWords || []).some((w) => rest.includes(w));
+
+  return { manager: mgr.name, subcommand, packages, global };
+}
+
+/**
+ * Classify a full (possibly compound) shell command. Splits on `&&`/`||`/`;`/`|`
+ * so `npm i a && pip install b` reports BOTH. Returns `{ isInstall, installs }`.
+ * Pure.
+ */
+export function classifyInstallCommand(command) {
+  const segments = splitCommandSegments(String(command || ""));
+  const installs = [];
+  for (const seg of segments) {
+    const hit = classifyInstallSegment(seg);
+    if (hit) installs.push(hit);
+  }
+  return { isInstall: installs.length > 0, installs };
+}
+
+/** True if any classified install is global/system-scoped (higher blast radius). */
+export function hasGlobalInstall(classification) {
+  return !!(
+    classification &&
+    Array.isArray(classification.installs) &&
+    classification.installs.some((i) => i.global)
+  );
+}
+
+// ── remote-script execution ("curl … | sh") ────────────────────────────────
+// The most dangerous "fetch and run third-party code" vector isn't a package
+// manager at all — it's piping a download straight into a shell, or running a
+// shell over a command/process substitution that downloads. It runs UNPINNED,
+// UNVERIFIED, attacker-mutable code with the agent's privileges. These patterns
+// must be recognized on the RAW command (the pipe/substitution structure is lost
+// once split into segments), so they use anchored regexes rather than the
+// per-segment classifier.
+const REMOTE_FETCHERS = "curl|wget|fetch|iwr|invoke-webrequest|http|httpie";
+const SHELL_INTERPRETERS =
+  "sh|bash|zsh|ksh|dash|fish|python[0-9.]*|ruby|perl|node|deno|pwsh|powershell|eval|source";
+
+// `curl URL | sh`, `wget -O- URL | sudo bash`, `curl URL | tee f | sh`. After
+// the pipe, skip inline wrappers (`sudo `/`env `, space-separated) AND piped
+// pass-throughs (`tee f |`, `cat |`) before the interpreter.
+const PIPE_TO_SHELL_RE = new RegExp(
+  `\\b(${REMOTE_FETCHERS})\\b[^|]*\\|\\s*(?:(?:sudo|env|command|nice)\\s+|(?:tee|cat)\\b[^|]*\\|\\s*)*(${SHELL_INTERPRETERS})\\b`,
+  "i",
+);
+// `bash -c "$(curl URL)"`, `sh <(curl URL)`, `eval "$(wget -O- URL)"`
+const SUBST_TO_SHELL_RE = new RegExp(
+  `\\b(${SHELL_INTERPRETERS})\\b[^\\n]*[$<]\\(\\s*(?:sudo\\s+)?(${REMOTE_FETCHERS})\\b`,
+  "i",
+);
+
+function firstUrl(s) {
+  const m = String(s).match(/\bhttps?:\/\/[^\s'"|)>]+/i);
+  return m ? m[0] : null;
+}
+
+/**
+ * Detect remote-script execution in a raw shell command: a network fetcher piped
+ * into (or command/process-substituted into) a shell interpreter. Returns
+ * `{ isRemoteExec, matches:[{pattern, fetcher, interpreter, url}] }`. Pure.
+ */
+export function classifyRemoteExecCommand(command) {
+  const s = String(command || "");
+  const matches = [];
+  const pipe = PIPE_TO_SHELL_RE.exec(s);
+  if (pipe) {
+    matches.push({
+      pattern: "pipe-to-shell",
+      fetcher: pipe[1].toLowerCase(),
+      interpreter: pipe[2].toLowerCase(),
+      url: firstUrl(s),
+    });
+  }
+  const subst = SUBST_TO_SHELL_RE.exec(s);
+  if (subst) {
+    matches.push({
+      pattern: "cmdsubst-to-shell",
+      interpreter: subst[1].toLowerCase(),
+      fetcher: subst[2].toLowerCase(),
+      url: firstUrl(s),
+    });
+  }
+  return { isRemoteExec: matches.length > 0, matches };
+}
+
+/**
+ * Combined "untrusted code acquisition" classification: package installs AND
+ * remote-script execution. `flagged` is true if EITHER fires — the single signal
+ * a caller gates/audits on. Pure.
+ */
+export function classifyCodeAcquisition(command) {
+  const install = classifyInstallCommand(command);
+  const remote = classifyRemoteExecCommand(command);
+  return {
+    flagged: install.isInstall || remote.isRemoteExec,
+    isInstall: install.isInstall,
+    installs: install.installs,
+    isRemoteExec: remote.isRemoteExec,
+    remoteExec: remote.matches,
+  };
+}
+
+/**
+ * Resolve the install-command policy from env/settings (opt-in, so the default
+ * shell path is byte-unchanged). `audit` enables the audit trail; `riskFloor`
+ * ("low"|"medium"|"high") is the MINIMUM risk an install command is treated as
+ * (never lowers an already-higher risk).
+ */
+export function resolveInstallPolicy({
+  env = process.env,
+  settings = null,
+} = {}) {
+  const s = (settings && settings.installPolicy) || {};
+  const envAudit = env.CC_INSTALL_AUDIT;
+  const audit =
+    envAudit === "1" ? true : envAudit === "0" ? false : s.audit === true;
+  const riskFloor =
+    env.CC_INSTALL_RISK_FLOOR ||
+    (typeof s.riskFloor === "string" ? s.riskFloor : null) ||
+    null;
+  return {
+    audit,
+    riskFloor: riskFloor ? String(riskFloor).toLowerCase() : null,
+    enabled: audit || !!riskFloor,
+  };
+}
+
+const RISK_RANK = { low: 0, medium: 1, high: 2 };
+
+/**
+ * Apply a risk floor: return whichever of `currentRisk` / `floor` is HIGHER
+ * (never downgrades). Unknown values pass `currentRisk` through unchanged.
+ */
+export function applyRiskFloor(currentRisk, floor) {
+  if (!floor || !(floor in RISK_RANK)) return currentRisk;
+  const cur = RISK_RANK[currentRisk];
+  if (cur == null) return currentRisk;
+  return RISK_RANK[floor] > cur ? floor : currentRisk;
+}
+
+/** Best-effort append of one install-command audit record. Never throws. */
+export function recordInstallCommandAudit(entry, opts = {}) {
+  try {
+    const baseDir =
+      opts.baseDir ||
+      (opts.env || process.env).CC_AUDIT_DIR ||
+      path.join(os.homedir(), ".chainlesschain", "audit");
+    const _fs = opts.fs || fs;
+    _fs.mkdirSync(baseDir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date(opts.now ? opts.now() : Date.now()).toISOString(),
+      kind: "install-command",
+      ...entry,
+    });
+    _fs.appendFileSync(
+      path.join(baseDir, "install-commands.jsonl"),
+      line + "\n",
+      "utf-8",
+    );
+    return true;
+  } catch {
+    return false; // audit is best-effort — never affect the run
+  }
+}

package/src/lib/jsonl-session-store.js

@@ -21,6 +21,7 @@ export {
   readEvents,
   rebuildMessages,
   listJsonlSessions,
+  listSessionIds,
   renameSession,
   pruneJsonlSessions,
   forkSession,