chainlesschain 0.162.159 → 0.162.160

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

@@ -0,0 +1,62 @@
+/**
+ * `llm.apiKeyHelper` (gap-analysis 2026-07-11 P0 "依赖安装与凭据"): fetch the
+ * LLM API key from an external command instead of storing it in plaintext
+ * config.json. Point it at your OS credential store, e.g.:
+ *
+ *   Windows :  "powershell -NoProfile -Command \"...CredentialManager...\""
+ *   macOS   :  "security find-generic-password -s cc-llm -w"
+ *   Linux   :  "secret-tool lookup service cc-llm"
+ *
+ * Resolution precedence stays: --api-key > CC_API_KEY > config llm.apiKey >
+ * llm.apiKeyHelper. The helper's stdout (trimmed) is the key; a failing or
+ * empty helper resolves null so the run fails with the provider's own
+ * missing-key error (never a silent fallback — see the no-silent-substitution
+ * rule). Cached per process (5 min) so multi-call runs don't re-spawn it.
+ */
+
+import { execSync } from "node:child_process";
+
+const TTL_MS = 5 * 60 * 1000;
+const _cache = new Map(); // helper command → { key, at }
+let _warnedFailure = false;
+
+/**
+ * @param {string} helperCmd  shell command printing the key on stdout
+ * @param {{exec?:Function, now?:()=>number, writeErr?:(s:string)=>void}} [opts]
+ * @returns {string|null}
+ */
+export function resolveApiKeyFromHelper(helperCmd, opts = {}) {
+  const cmd = typeof helperCmd === "string" ? helperCmd.trim() : "";
+  if (!cmd) return null;
+  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;
+  try {
+    const out = exec(cmd, {
+      encoding: "utf-8",
+      timeout: 10000,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const key = String(out || "").trim();
+    if (!key) return null;
+    _cache.set(cmd, { key, at: now() });
+    return key;
+  } catch (err) {
+    // Warn once per process, then stay quiet — the provider's missing-key
+    // error is the actionable surface.
+    if (!_warnedFailure) {
+      _warnedFailure = true;
+      const writeErr = opts.writeErr || ((s) => process.stderr.write(s));
+      writeErr(`[api-key-helper] llm.apiKeyHelper failed: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+
+/** Test seam: drop the per-process cache + warn-once latch. */
+export function clearApiKeyHelperCache() {
+  _cache.clear();
+  _warnedFailure = false;
+}

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

@@ -223,6 +223,38 @@ export function renameBackgroundAgent(id, title, options = {}) {
   return next;
 }
 
+/**
+ * Remove a background agent's RECORD (state file + log) — `cc daemon rm`
+ * (gap-analysis 2026-07-11 P0 "后台 Agent Supervisor" 补 rm 动词). Terminal
+ * sessions (completed/failed/stopped/lost) remove directly; a still-running
+ * one is refused unless `force`, which stops it first. The underlying JSONL
+ * conversation session is NOT touched — that's `cc session delete`.
+ */
+export function removeBackgroundAgent(id, options = {}) {
+  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+    now: options.now,
+    heartbeatStaleMs: options.heartbeatStaleMs,
+  });
+  if (!state) throw new Error(`Background agent not found: ${id}`);
+  if (state.status === "running") {
+    if (options.force !== true) {
+      throw new Error(
+        `${id} is still running — stop it first (cc daemon stop ${id}) or pass --force`,
+      );
+    }
+    try {
+      stopBackgroundAgent(id);
+    } catch {
+      /* best-effort — the record removal below is the point of rm --force */
+    }
+  }
+  rmSync(statePath(id), { force: true });
+  if (options.keepLog !== true) {
+    rmSync(logPath(id), { force: true });
+  }
+  return { id, removed: true, status: state.status };
+}
+
 /**
  * Pin/unpin a session for the dashboard (`cc daemon view`) — pinned sessions
  * sort first inside their group. Same read-modify-write + verify-retry dance

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

@@ -0,0 +1,130 @@
+/**
+ * Dependency-install policy for `run_code` (gap-analysis 2026-07-11,
+ * docs/CLAUDE_CODE_CLI_GAP_ANALYSIS.md P0 "依赖安装与凭据").
+ *
+ * Auto `pip install` on a Python import error used to be unconditional. It is
+ * now OPT-IN:
+ *   - env `CC_RUN_CODE_AUTO_INSTALL=1|0` wins outright (kill-switch friendly)
+ *   - settings.json `runCode.autoInstall: true` opts in per project/user
+ *   - default: DISABLED — the tool result explains how to enable it
+ *
+ * When enabled, an optional `runCode.installAllowlist` (array of package
+ * names, PEP 503-normalized) restricts WHICH packages may be installed, and
+ * every attempt — including blocked/disabled ones — is appended to an audit
+ * log at ~/.chainlesschain/audit/dependency-install.jsonl.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const _require = createRequire(import.meta.url);
+
+/** PEP 503 name normalization: lowercase, runs of -_. collapse to "-". */
+export function normalizePackageName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[-_.]+/g, "-");
+}
+
+/**
+ * Resolve the effective auto-install policy.
+ * @param {{cwd?:string, env?:object, settingsFile?:string|null}} opts
+ * @returns {{enabled:boolean, allowlist:string[]|null, source:string}}
+ */
+export function resolveAutoInstallPolicy({
+  cwd = process.cwd(),
+  env = process.env,
+  settingsFile = null,
+} = {}) {
+  const raw = env.CC_RUN_CODE_AUTO_INSTALL;
+  if (raw === "1" || raw === "0") {
+    return {
+      enabled: raw === "1",
+      allowlist: raw === "1" ? readAllowlist({ cwd, settingsFile }) : null,
+      source: "env",
+    };
+  }
+  let enabled = false;
+  try {
+    const { readBooleanSetting } = _require("./settings-loader.cjs");
+    enabled =
+      readBooleanSetting("runCode.autoInstall", { cwd, settingsFile }) === true;
+  } catch {
+    enabled = false; // fail-closed: no settings → stay disabled
+  }
+  return {
+    enabled,
+    allowlist: enabled ? readAllowlist({ cwd, settingsFile }) : null,
+    source: enabled ? "settings" : "default",
+  };
+}
+
+function readAllowlist({ cwd = process.cwd(), settingsFile }) {
+  try {
+    const { settingsPaths, readSettingsFile, loadManagedSettings } = _require(
+      "./settings-loader.cjs",
+    );
+    let value;
+    for (const file of settingsPaths(cwd, settingsFile)) {
+      const node = readSettingsFile(file)?.runCode?.installAllowlist;
+      if (Array.isArray(node)) value = node; // closest layer wins
+    }
+    const managed = loadManagedSettings({});
+    const mNode = managed?.settings?.runCode?.installAllowlist;
+    if (Array.isArray(mNode)) value = mNode; // managed policy wins outright
+    if (!Array.isArray(value)) return null;
+    const list = value.map(normalizePackageName).filter(Boolean);
+    return list.length ? list : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a package may be installed under the policy's allowlist.
+ * No allowlist configured → any (validity is checked separately).
+ */
+export function isPackageAllowed(name, allowlist) {
+  if (!allowlist) return true;
+  return allowlist.includes(normalizePackageName(name));
+}
+
+/** Human hint for the disabled-by-default path (returned in the tool result). */
+export function autoInstallDisabledHint(packageName) {
+  return (
+    `Missing Python package "${packageName}". Auto-install is disabled by ` +
+    `default; install it yourself (pip install ${packageName}), or opt in via ` +
+    `settings.json {"runCode":{"autoInstall":true}} or CC_RUN_CODE_AUTO_INSTALL=1.`
+  );
+}
+
+/**
+ * Append an install-attempt audit record (best-effort, never throws).
+ * @param {{package:string, interpreter?:string, cwd?:string,
+ *          outcome:"installed"|"failed"|"blocked"|"disabled", detail?:string}} entry
+ * @param {{baseDir?:string, now?:()=>number}} [opts]  injection seams
+ */
+export function recordInstallAudit(entry, opts = {}) {
+  try {
+    const baseDir =
+      opts.baseDir ||
+      process.env.CC_AUDIT_DIR ||
+      path.join(os.homedir(), ".chainlesschain", "audit");
+    fs.mkdirSync(baseDir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date(opts.now ? opts.now() : Date.now()).toISOString(),
+      kind: "dependency-install",
+      ...entry,
+    });
+    fs.appendFileSync(
+      path.join(baseDir, "dependency-install.jsonl"),
+      line + "\n",
+      "utf-8",
+    );
+  } catch {
+    /* audit is best-effort — never affect the run */
+  }
+}

package/src/lib/exit-codes.cjs

@@ -0,0 +1,77 @@
+/**
+ * Headless exit-code taxonomy (gap-analysis 2026-07-11, P0 "确定性 Headless"):
+ * scripted callers can tell apart WHY a run ended without parsing stderr.
+ *
+ * Backward compatibility: every failure is still non-zero, 0 stays success,
+ * 2 stays "settings hook blocked the prompt" (pre-existing), 130/143 stay the
+ * signal-interrupt codes. The new codes carve budget/turn exhaustion and
+ * config errors out of the generic 1.
+ */
+
+const HEADLESS_EXIT_CODES = Object.freeze({
+  OK: 0,
+  /** generic failure (tool/loop/unclassified error) */
+  ERROR: 1,
+  /** a settings hook blocked the prompt (pre-existing semantic) */
+  HOOK_BLOCKED: 2,
+  /** the turn budget (--max-turns / loop iteration cap) ran out first */
+  MAX_TURNS: 3,
+  /** the --max-budget-usd cost cap stopped the run */
+  MAX_BUDGET: 4,
+  /** the LLM call itself failed (provider/model/network error) */
+  MODEL_ERROR: 5,
+  /** bad run configuration (--mcp-config / --permission-prompt-tool / settings) */
+  CONFIG_ERROR: 6,
+  /** user interrupt (SIGINT) — 128+2, shell convention */
+  INTERRUPT_SIGINT: 130,
+  /** termination (SIGTERM) — 128+15, shell convention */
+  INTERRUPT_SIGTERM: 143,
+});
+
+/**
+ * Best-effort classifier for errors thrown out of the agent loop: provider /
+ * transport failures → MODEL_ERROR, everything else → generic ERROR. Checks
+ * structural markers (HTTP status, network error codes) before falling back —
+ * never message-text guessing beyond the explicit LLM markers.
+ */
+function classifyLoopError(err) {
+  if (!err) return HEADLESS_EXIT_CODES.ERROR;
+  const status = err.status ?? err.statusCode ?? err.response?.status;
+  if (Number.isFinite(Number(status))) return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  const code = err.code || err.cause?.code;
+  if (
+    typeof code === "string" &&
+    /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|UND_ERR)/.test(
+      code,
+    )
+  ) {
+    return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  }
+  if (typeof err.name === "string" && /LLM|Provider|Api/i.test(err.name)) {
+    return HEADLESS_EXIT_CODES.MODEL_ERROR;
+  }
+  return HEADLESS_EXIT_CODES.ERROR;
+}
+
+/**
+ * Map a finished run's endReason (+ error flag) to an exit code.
+ * @param {string} endReason  "complete" | "max_turns" | "budget-exhausted" |
+ *                            "cost-budget-exhausted" | "no-response" | ...
+ * @param {boolean} isError
+ */
+function exitCodeForEndReason(endReason, isError) {
+  if (!isError) return HEADLESS_EXIT_CODES.OK;
+  if (endReason === "max_turns" || endReason === "budget-exhausted") {
+    return HEADLESS_EXIT_CODES.MAX_TURNS;
+  }
+  if (endReason === "cost-budget-exhausted") {
+    return HEADLESS_EXIT_CODES.MAX_BUDGET;
+  }
+  return HEADLESS_EXIT_CODES.ERROR;
+}
+
+module.exports = {
+  HEADLESS_EXIT_CODES,
+  classifyLoopError,
+  exitCodeForEndReason,
+};

package/src/lib/headless-manifest.js

@@ -0,0 +1,175 @@
+/**
+ * Deterministic-headless manifest helpers (gap-analysis 2026-07-11,
+ * docs/CLAUDE_CODE_CLI_GAP_ANALYSIS.md P0 "确定性 Headless").
+ *
+ * The stream-json init event carries a protocol version, whether this run
+ * persists its session, which ambient customization sources are live, and
+ * short digests of the resolved permission policy + tool surface — so a CI
+ * caller can assert "same run shape" across invocations without diffing the
+ * whole event stream.
+ *
+ * STREAM_PROTOCOL_VERSION mirrors packages/agent-sdk/src/protocol.ts
+ * PROTOCOL_VERSION — a BREAKING stream-json change must bump both in the same
+ * commit (see agent-sdk docs/PROTOCOL.md). Additive optional fields stay on
+ * the current version.
+ */
+
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+
+export const STREAM_PROTOCOL_VERSION = 1;
+
+const _require = createRequire(import.meta.url);
+
+function shortHash(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+const sortedList = (v) =>
+  [...new Set((Array.isArray(v) ? v : []).filter(Boolean))].sort();
+
+// null = "no explicit list" (the default full tool set) — kept distinct from
+// an explicit empty list so the digest can tell the two apart.
+const sortedListOrNull = (v) => (Array.isArray(v) ? sortedList(v) : null);
+
+/**
+ * Digest of the resolved permission policy: permission mode + allow/deny tool
+ * lists + settings permission rules. Stable across key order / duplicates so
+ * two runs with the same effective policy produce the same digest.
+ *
+ * @param {object} p
+ * @param {string} [p.permissionMode]
+ * @param {string[]} [p.allowedTools]
+ * @param {string[]} [p.disallowedTools]
+ * @param {{allow?:string[],ask?:string[],deny?:string[]}|null} [p.permissionRules]
+ * @returns {string} 16-hex-char sha256 prefix
+ */
+export function computePolicyDigest({
+  permissionMode,
+  allowedTools,
+  disallowedTools,
+  permissionRules,
+} = {}) {
+  const rules = permissionRules
+    ? {
+        allow: sortedList(permissionRules.allow),
+        ask: sortedList(permissionRules.ask),
+        deny: sortedList(permissionRules.deny),
+      }
+    : null;
+  return shortHash({
+    v: 1,
+    permissionMode: permissionMode || "default",
+    allowedTools: sortedListOrNull(allowedTools),
+    disallowedTools: sortedList(disallowedTools),
+    rules,
+  });
+}
+
+/**
+ * Digest of the tool surface exposed to the model (name set, order-independent).
+ * @param {string[]} toolNames
+ * @returns {string} 16-hex-char sha256 prefix
+ */
+export function computeToolsHash(toolNames) {
+  return shortHash({ v: 1, tools: sortedListOrNull(toolNames) });
+}
+
+/**
+ * Which ambient customization sources are LIVE for this run. Reflects the
+ * kill-switch env vars (--safe-mode / --bare flip these) plus what the runner
+ * actually wired. Under `--bare` this collapses to at most
+ * ["settings-permissions"] (+ explicit MCP), which is the reproducibility
+ * signal CI wants.
+ *
+ * @param {object} p
+ * @param {object|null} [p.permissionRules]  resolved settings permission rules
+ * @param {object|null} [p.settingsHooks]    resolved settings hooks
+ * @param {boolean} [p.mcp]                  MCP surface enabled/connected
+ * @param {string[]} [p.enabledToolNames]
+ * @param {object} [p.env=process.env]
+ * @returns {string[]}
+ */
+export function buildLoadedSources({
+  permissionRules = null,
+  settingsHooks = null,
+  mcp = false,
+  enabledToolNames = null,
+  env = process.env,
+} = {}) {
+  const on = (k) => env[k] !== "0";
+  // null tool list = "default full set" → run_skill is available.
+  const skillToolAvailable =
+    !Array.isArray(enabledToolNames) || enabledToolNames.includes("run_skill");
+  const sources = [];
+  if (permissionRules) sources.push("settings-permissions");
+  if (settingsHooks) sources.push("settings-hooks");
+  if (on("CC_PROJECT_MEMORY")) sources.push("project-memory");
+  if (on("CC_MEMORY_INJECT")) sources.push("memory-recall");
+  if (on("CC_SKILLS") && skillToolAvailable) {
+    sources.push("skills");
+  }
+  if (on("CC_PLUGINS")) sources.push("plugins");
+  if (mcp) sources.push("mcp");
+  return sources;
+}
+
+/**
+ * Machine-readable capability manifest for `cc agent --capabilities`:
+ * everything a programmatic caller needs to know up front to drive this CLI
+ * (protocol version, tool names, permission modes, IO formats, exit codes,
+ * feature flags) without parsing --help text.
+ */
+export function buildAgentCapabilities() {
+  let version = null;
+  try {
+    version = _require("../../package.json").version || null;
+  } catch {
+    /* manifest stays usable without a version */
+  }
+  const contract = _require("../runtime/coding-agent-contract-shared.cjs");
+  const { HEADLESS_EXIT_CODES } = _require("./exit-codes.cjs");
+  return {
+    name: "chainlesschain-cli",
+    version,
+    protocol_version: STREAM_PROTOCOL_VERSION,
+    agent_tools: contract.listCodingAgentToolNames(),
+    permission_modes: [
+      "default",
+      "manual",
+      "auto",
+      "dontAsk",
+      "plan",
+      "acceptEdits",
+      "bypassPermissions",
+    ],
+    output_formats: ["text", "json", "stream-json"],
+    input_formats: ["text", "stream-json"],
+    exit_codes: HEADLESS_EXIT_CODES,
+    features: {
+      bare: true,
+      safe_mode: true,
+      ephemeral: true,
+      background: true,
+      worktree: true,
+      checkpoint: true,
+      json_schema_output: true,
+      partial_messages: true,
+      interactive_approvals: true,
+      permission_prompt_tool: true,
+      remote_control: true,
+      mcp: {
+        config_file: true,
+        registry: true,
+        tool_search: true,
+        oauth: true,
+        managed_allowlist: true,
+      },
+      sandbox_engines: ["docker", "bubblewrap"],
+    },
+  };
+}

package/src/lib/hook-runner.cjs

@@ -117,6 +117,69 @@ function tryParseDecision(stdout) {
  *            nonBlockingError?:boolean, error?:string }}
  */
 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 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
+    }
+  }
+  return result;
+}
+
+// Payload schema version (gap 2026-07-11 P2): every hook's stdin JSON carries
+// schema_version so hook scripts can branch on future payload changes.
+// Additive-only changes keep the version; a breaking reshape must bump it.
+const HOOK_PAYLOAD_SCHEMA_VERSION = 1;
+
+// command → { fails, openedAt } (per process; hooks are per-run anyway)
+const _breaker = new Map();
+
+function hookBreakerConfig(env = process.env) {
+  const threshold = Number(env.CC_HOOK_BREAKER_THRESHOLD);
+  const cooldown = Number(env.CC_HOOK_BREAKER_COOLDOWN_MS);
+  return {
+    threshold:
+      Number.isFinite(threshold) && threshold >= 0 ? Math.floor(threshold) : 3,
+    cooldownMs: Number.isFinite(cooldown) && cooldown > 0 ? cooldown : 60000,
+  };
+}
+
+/** Test seam: clear breaker state between cases. */
+function _resetHookBreaker() {
+  _breaker.clear();
+}
+
+function _runCommandHookInner(command, input = {}, opts = {}) {
   const { cwd, event } = opts;
   // spawnSync is SYNCHRONOUS — it blocks the whole agent until the hook returns
   // or its timeout fires. Node treats a 0/undefined timeout as UNLIMITED, so a
@@ -128,15 +191,15 @@ function runCommandHook(command, input = {}, opts = {}) {
     Number.isFinite(_rawTimeout) && _rawTimeout > 0
       ? Math.min(_rawTimeout, 600000)
       : 60000;
-  if (!command) {
-    return { decision: HOOK_DECISIONS.CONTINUE, reason: null, exitCode: 0 };
-  }
   const shellKind = normalizeShellKind(opts.shell);
   const usePowershell = shellKind === "powershell" || shellKind === "pwsh";
   let res;
   try {
     const common = {
-      input: JSON.stringify(input),
+      input: JSON.stringify({
+        ...input,
+        schema_version: input.schema_version ?? HOOK_PAYLOAD_SCHEMA_VERSION,
+      }),
       cwd: cwd || process.cwd(),
       encoding: "utf-8",
       timeout,
@@ -258,5 +321,8 @@ module.exports = {
   runHooks,
   tryParseDecision,
   HOOK_DECISIONS,
+  HOOK_PAYLOAD_SCHEMA_VERSION,
+  hookBreakerConfig,
+  _resetHookBreaker,
   _deps,
 };