chainlesschain 0.162.122 → 0.162.124

package/src/harness/mcp-client.js

@@ -18,6 +18,8 @@ import { EventEmitter } from "events";
 export const _deps = {
   spawn,
   fetch: (...args) => globalThis.fetch(...args),
+  // Backoff sleep seam (tests override with a no-op so retries don't wait).
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
 
 /**
@@ -95,6 +97,37 @@ export function isLikelyConnectionError(err) {
   );
 }
 
+/** Capability-discovery retry tuning (Claude-Code 2.1.191 "short backoff"). */
+const MCP_DISCOVERY_RETRIES = 2; // up to 3 attempts total
+const MCP_DISCOVERY_BACKOFF_MS = 250; // 250ms, 500ms
+
+/**
+ * Hard cap on the unterminated stdout tail buffered per stdio server. JSON-RPC
+ * frames are newline-delimited; a runaway or non-MCP process that streams
+ * without ever emitting a newline would otherwise grow `entry._buffer` without
+ * bound and exhaust memory. 16M chars is far above any legitimate single MCP
+ * message (even a tool result with embedded base64), so crossing it signals a
+ * misbehaving server. Override per server with `config.maxBufferChars` (0
+ * disables the cap).
+ */
+const MCP_MAX_BUFFER_CHARS = 16 * 1024 * 1024;
+
+/**
+ * Is this a TRANSIENT error worth a short retry during capability discovery?
+ * Narrower than isLikelyConnectionError: connection-level failures and 5xx
+ * server errors retry, but 4xx (auth 401/403, not-found 404 = permanent for the
+ * same request), already-waited timeouts, and a dead stdio process do not —
+ * retrying those just wastes attempts.
+ */
+export function isTransientMcpError(err) {
+  const msg = String((err && err.message) || err || "");
+  if (/HTTP 4\d\d\b/i.test(msg)) return false; // any 4xx is permanent here
+  if (/Request timeout/i.test(msg)) return false; // already spent the full budget
+  return /fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|EPIPE|socket hang up|network error|HTTP 5\d\d\b/i.test(
+    msg,
+  );
+}
+
 /**
  * MCP Client — manages connections to MCP servers.
  */
@@ -271,14 +304,28 @@ export class MCPClient extends EventEmitter {
           failPending(`MCP server "${name}" process error: ${err.message}`);
           this.emit("server-error", { name, error: err.message });
         });
+
+        // Writing to a stdio server that closed its stdin read end (or died
+        // mid-write) makes the stdin pipe emit an asynchronous 'error' (EPIPE).
+        // An 'error' event with no listener is an uncaught exception in Node and
+        // would CRASH the whole CLI — and the try/catch around stdin.write only
+        // catches synchronous throws, not this async event. Handle it: drain
+        // in-flight requests and surface it, mirroring the process 'error' path.
+        if (proc.stdin && typeof proc.stdin.on === "function") {
+          proc.stdin.on("error", (err) => {
+            entry.state = ServerState.ERROR;
+            failPending(`MCP server "${name}" stdin error: ${err.message}`);
+            this.emit("server-error", { name, error: err.message });
+          });
+        }
       } else {
         throw new Error(
           `transport "${transportKind}" is not supported by this client`,
         );
       }
 
-      // Initialize MCP protocol
-      const initResult = await this._sendRequest(name, "initialize", {
+      // Initialize MCP protocol (retried on transient network errors).
+      const initResult = await this._requestWithRetry(name, "initialize", {
         protocolVersion: "2024-11-05",
         capabilities: { tools: {}, resources: {}, prompts: {} },
         clientInfo: { name: "chainlesschain-cli", version: "0.37.9" },
@@ -302,7 +349,11 @@ export class MCPClient extends EventEmitter {
       const advertisesTools =
         entry.capabilities && entry.capabilities.tools !== undefined;
       try {
-        const toolsResult = await this._sendRequest(name, "tools/list", {});
+        const toolsResult = await this._requestWithRetry(
+          name,
+          "tools/list",
+          {},
+        );
         entry.tools = toolsResult?.tools || [];
       } catch (err) {
         if (advertisesTools) {
@@ -358,6 +409,7 @@ export class MCPClient extends EventEmitter {
         try {
           entry.process.stdout?.removeAllListeners();
           entry.process.stderr?.removeAllListeners();
+          entry.process.stdin?.removeAllListeners?.();
           entry.process.removeAllListeners();
           entry.process.kill();
         } catch {
@@ -590,6 +642,34 @@ export class MCPClient extends EventEmitter {
 
   // ─── Internal JSON-RPC transport ──────────────────────────────
 
+  /**
+   * Capability-discovery request with a short backoff retry on TRANSIENT
+   * network errors (Claude-Code 2.1.191: "capability discovery now retries
+   * transient network errors with short backoff"). Permanent errors (4xx,
+   * JSON-RPC errors, timeouts, dead stdio process) throw on the first failure.
+   */
+  async _requestWithRetry(
+    serverName,
+    method,
+    params,
+    attempts = MCP_DISCOVERY_RETRIES,
+  ) {
+    for (let i = 0; ; i++) {
+      try {
+        return await this._sendRequest(serverName, method, params);
+      } catch (err) {
+        if (i >= attempts || !isTransientMcpError(err)) throw err;
+        this.emit("server-retry", {
+          name: serverName,
+          method,
+          attempt: i + 1,
+          error: err?.message || String(err),
+        });
+        await _deps.sleep(MCP_DISCOVERY_BACKOFF_MS * (i + 1));
+      }
+    }
+  }
+
   _sendRequest(serverName, method, params) {
     const entry = this.servers.get(serverName);
     if (!entry) return Promise.reject(new Error("Server not available"));
@@ -719,9 +799,16 @@ export class MCPClient extends EventEmitter {
       if (!response.ok) {
         const text =
           typeof response.text === "function" ? await response.text() : "";
-        throw new Error(
-          `HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}`,
-        );
+        const detail = text ? `: ${text.slice(0, 200)}` : "";
+        // 404 usually means a wrong/stale server URL — name it and point at the
+        // MCP config (Claude-Code 2.1.191: "HTTP 404 errors now show the URL and
+        // point to your MCP config") instead of a bare "HTTP 404".
+        if (response.status === 404) {
+          throw new Error(
+            `HTTP 404${detail} — ${entry.httpUrl} returned Not Found; check this server's "url" in your MCP config`,
+          );
+        }
+        throw new Error(`HTTP ${response.status}${detail}`);
       }
 
       const contentType = response.headers?.get
@@ -807,6 +894,37 @@ export class MCPClient extends EventEmitter {
         // Skip malformed lines
       }
     }
+
+    // Guard against unbounded buffer growth: a runaway / non-MCP server that
+    // streams without ever sending a newline would grow the unterminated tail
+    // forever and exhaust memory. If the leftover partial line exceeds the cap,
+    // treat it as a fatal transport error (drop the buffer, drain in-flight
+    // requests, kill the process) rather than letting it grow without limit.
+    const cap = Number.isFinite(entry.config?.maxBufferChars)
+      ? entry.config.maxBufferChars
+      : MCP_MAX_BUFFER_CHARS;
+    if (cap > 0 && entry._buffer.length > cap) {
+      entry._buffer = "";
+      entry.state = ServerState.ERROR;
+      const errMsg = `MCP server "${serverName}" exceeded the ${cap}-char line buffer with no newline (runaway or non-MCP output)`;
+      for (const [, pending] of entry._pending) {
+        if (pending.timeout) clearTimeout(pending.timeout);
+        try {
+          pending.reject(new Error(errMsg));
+        } catch {
+          // already settled — ignore
+        }
+      }
+      entry._pending.clear();
+      if (entry.process) {
+        try {
+          entry.process.kill();
+        } catch {
+          // best-effort — surfacing the error is what matters
+        }
+      }
+      this.emit("server-error", { name: serverName, error: errMsg });
+    }
   }
 
   _handleMessage(serverName, msg) {

package/src/harness/worktree-isolator.js

@@ -13,7 +13,9 @@ import { resolve } from "node:path";
 import {
   isGitRepo,
   gitExec,
+  gitExecArgs,
   assertSafeGitRef,
+  assertSafeGitPath,
 } from "../lib/git-integration.js";
 
 const WORKTREE_DIR = ".worktrees";
@@ -167,6 +169,7 @@ export function diffWorktree(repoDir, branchName, options = {}) {
   if (options.baseBranch) assertSafeGitRef(options.baseBranch, "base branch");
   const base = options.baseBranch || "HEAD";
   const filePath = options.filePath || null;
+  if (filePath) assertSafeGitPath(filePath, "file path");
   const fileArg = filePath ? ` -- "${filePath}"` : "";
   const statOutput = gitExec(
     `diff ${base}...${branchName} --stat --numstat${fileArg}`,
@@ -223,14 +226,13 @@ export function mergeWorktree(repoDir, branchName, options = {}) {
       const msg =
         options.message ||
         `feat: merge agent work from ${branchName} (squashed)`;
-      gitExec(`commit -m "${msg.replace(/"/g, '\\"')}"`, repoDir);
+      // Free-text message → argv (no shell) so `$()`/backticks/quotes in it
+      // can't inject a command (the old `-m "…"` only escaped `"`).
+      gitExecArgs(["commit", "-m", msg], repoDir);
     } else {
       const msg =
         options.message || `Merge branch '${branchName}' (agent task)`;
-      gitExec(
-        `merge ${branchName} --no-edit -m "${msg.replace(/"/g, '\\"')}"`,
-        repoDir,
-      );
+      gitExecArgs(["merge", branchName, "--no-edit", "-m", msg], repoDir);
     }
 
     if (deleteBranch) {
@@ -393,6 +395,7 @@ export function applyWorktreeAutomationCandidate(
   const conflictType = options.conflictType || null;
   const baseBranch = _resolveBaseBranchForMerge(repoDir, options.baseBranch);
 
+  if (filePath) assertSafeGitPath(filePath, "file path");
   if (!filePath) {
     throw new Error("filePath is required");
   }
@@ -514,8 +517,10 @@ export function worktreeLog(repoDir, branchName, baseBranch = "HEAD") {
 
 function _fileStatus(repoDir, base, branch, filePath) {
   try {
-    const output = gitExec(
-      `diff ${base}...${branch} --name-status -- "${filePath}"`,
+    // filePath here comes from git's conflict output (a tracked file name);
+    // pass it via argv so an exotic / maliciously-named file can't inject.
+    const output = gitExecArgs(
+      ["diff", `${base}...${branch}`, "--name-status", "--", filePath],
       repoDir,
     );
     const status = output.trim().charAt(0);
@@ -603,7 +608,10 @@ function _buildConflictSummary(repoDir, filePath, branchName) {
 
 function _conflictStatusCode(repoDir, filePath) {
   try {
-    const output = gitExec(`status --porcelain -- "${filePath}"`, repoDir);
+    const output = gitExecArgs(
+      ["status", "--porcelain", "--", filePath],
+      repoDir,
+    );
     const firstLine = output.split("\n").find((line) => line.trim());
     return firstLine ? firstLine.slice(0, 2) : "UU";
   } catch (_e) {
@@ -779,7 +787,10 @@ function _buildDiffPreview(repoDir, filePath, branchName) {
   };
 
   try {
-    const diff = gitExec(`diff HEAD...${branchName} -- "${filePath}"`, repoDir);
+    const diff = gitExecArgs(
+      ["diff", `HEAD...${branchName}`, "--", filePath],
+      repoDir,
+    );
     preview.snippet =
       diff.length > 2000
         ? `${diff.slice(0, 2000)}\n... [diff truncated]`

package/src/lib/agent-core.js

@@ -3,8 +3,11 @@ export {
   AGENT_TOOLS,
   AGENT_TOOL_REGISTRY,
   MAX_SUB_AGENT_DEPTH,
+  MAX_SUB_AGENTS_PER_RUN,
   MAX_TOOL_RESULT_CHARS,
   capToolResultString,
+  safeStringifyToolResult,
+  tokenizeShellWords,
   reloadSkills,
   getAgentToolDefinitions,
   getAgentToolDescriptors,

package/src/lib/autonomous-agent.js

@@ -8,6 +8,7 @@
  */
 
 import { EventEmitter } from "events";
+import { firstBalancedJson } from "./json-schema-output.js";
 
 // Exported for test injection
 export const _deps = {
@@ -471,10 +472,10 @@ Reply with a JSON object: { "action": "retry|add_step|skip", "newParams": {...},
 
   _parseSteps(text) {
     try {
-      // Extract JSON array from response
-      const match = text.match(/\[[\s\S]*\]/);
-      if (match) {
-        return JSON.parse(match[0]);
+      // Extract the first balanced JSON array from the response
+      const jsonText = firstBalancedJson(text, "[");
+      if (jsonText) {
+        return JSON.parse(jsonText);
       }
     } catch (_err) {
       // Parse failure
@@ -484,8 +485,8 @@ Reply with a JSON object: { "action": "retry|add_step|skip", "newParams": {...},
 
   _parseJSON(text) {
     try {
-      const match = text.match(/\{[\s\S]*\}/);
-      if (match) return JSON.parse(match[0]);
+      const jsonText = firstBalancedJson(text, "{");
+      if (jsonText) return JSON.parse(jsonText);
     } catch (_err) {
       // Parse failure
     }

package/src/lib/chat-intent-service.js

@@ -18,6 +18,7 @@
  */
 
 import { chatWithStreaming, chatStream } from "./chat-core.js";
+import { firstBalancedJson } from "./json-schema-output.js";
 
 const DEFAULT_INTENT_TIMEOUT_MS = 15000;
 
@@ -76,8 +77,9 @@ function extractJson(content) {
   if (fenced) return fenced[1].trim();
   const generic = content.match(/```\s*([\s\S]*?)```/);
   if (generic) return generic[1].trim();
-  const bare = content.match(/\{[\s\S]*\}/);
-  return bare ? bare[0] : null;
+  // Balanced extraction stops at the first complete object instead of the old
+  // greedy /\{[\s\S]*\}/, which over-captured trailing prose with a stray }.
+  return firstBalancedJson(content, "{");
 }
 
 /**

package/src/lib/checkpoint-store.js

@@ -256,6 +256,29 @@ export function createCheckpoint(cwd = process.cwd(), opts = {}) {
       /* non-critical */
     }
 
+    // Bound the session's checkpoint history when asked. Auto-checkpointing
+    // (one ref per mutating tool) passes a cap so a long agentic run can't
+    // accumulate unbounded refs — which also keeps nextId's per-create
+    // for-each-ref scan bounded. Best-effort: pruning never fails the
+    // checkpoint, and the dropped commit objects stay reachable via newer
+    // checkpoints' parent chain (only addressability by id is lost for the
+    // oldest entries). Manual `cc checkpoint create` omits the cap → unbounded.
+    if (Number.isFinite(opts.maxPerSession) && opts.maxPerSession > 0) {
+      try {
+        const rows = listRefs(root, session); // oldest-first (creatordate)
+        const excess = rows.length - opts.maxPerSession;
+        for (let i = 0; i < excess; i++) {
+          try {
+            git(["update-ref", "-d", rows[i].ref], { cwd: root });
+          } catch {
+            /* best-effort — a failed prune never affects the new checkpoint */
+          }
+        }
+      } catch {
+        /* pruning is entirely best-effort */
+      }
+    }
+
     return { id, ref, commit, tree, parent, label, session, createdAt, files };
   } finally {
     rmQuiet(tmpIndex);

package/src/lib/credential-guard.js

@@ -0,0 +1,291 @@
+/**
+ * Credential READ guard — Claude-Code 2.1.189 parity ("`sandbox.credentials`
+ * setting blocks sandboxed commands from reading credential files and secret
+ * environment variables").
+ *
+ * cc has no OS sandbox (by design), but the same intent applies one layer up:
+ * the agent must not silently slurp the user's secrets into model context,
+ * where they could be echoed back, logged, summarized into a transcript, or
+ * exfiltrated by a later tool call. This guard flags two read paths —
+ *   1. the `read_file` tool pointed at a credential file (.env, ~/.aws/credentials,
+ *      private keys, …), and
+ *   2. `run_shell` commands that read a credential file (`cat .env`) or print a
+ *      secret-looking environment variable (`echo $ANTHROPIC_API_KEY`, `printenv`).
+ * — so `executeTool` can confirm first (interactive) or fail closed (headless),
+ * exactly like the sensitive-file WRITE guard ([[sensitive-file-guard.js]]).
+ *
+ * An explicit settings `allow` rule pre-authorizes; `CC_CREDENTIAL_GUARD=0`
+ * disables it. Deliberately, `--safe-mode` does NOT disable this guard: like
+ * permission deny rules, it is a SAFETY surface, not a customization — "debug
+ * my customizations bare" must never widen what secrets the agent may read.
+ *
+ * Precision over recall: matches are conservative so everyday reads
+ * (.env.example, public keys, package.json) never trip a confirm — a guard that
+ * cries wolf trains users to blind-approve.
+ */
+
+import { createRequire } from "node:module";
+
+const require_ = createRequire(import.meta.url);
+// Reuse the shell policy's compound-command splitter (separators + $()/backtick
+// extraction). It is regex-based on separators and leaves backslashes intact,
+// so Windows paths survive (unlike the escaping tokenizer, which strips `\`).
+const { splitCommandSegments } = require_(
+  "../runtime/coding-agent-shell-policy.cjs",
+);
+
+// ── credential FILE patterns ────────────────────────────────────────────────
+
+// Exact basenames that are, by convention, secret stores.
+const CREDENTIAL_BASENAMES = new Set([
+  ".npmrc",
+  ".netrc",
+  "_netrc",
+  ".pgpass",
+  ".git-credentials",
+  ".pypirc",
+  ".dockercfg",
+  "credentials", // ~/.aws/credentials, gcloud, …
+  ".credentials",
+  "id_rsa",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ed25519", // private SSH keys (the `.pub` siblings have a different basename)
+  "id_ecdsa_sk",
+  "id_ed25519_sk", // FIDO/security-key SSH keys
+  ".htpasswd", // web-server basic-auth hashes
+  "kubeconfig", // bare KUBECONFIG file (the ~/.kube/config form is matched below)
+  ".terraformrc", // Terraform registry/API tokens
+  "terraform.rc",
+]);
+
+// Extensions whose BYTES are the secret (private keys / cert bundles / keyrings).
+// Public material (.pub/.crt/.cert/.cer) is intentionally absent.
+const SECRET_EXT_RE = /\.(pem|key|pfx|p12|keystore|jks|ppk|asc|gpg|pgp)$/i;
+
+// `.env` and real env files — but NOT the committed template/example forms.
+const ENV_SAFE_SUFFIX_RE = /\.(example|sample|template|dist|defaults|tpl)$/i;
+
+// Directory-scoped credential files (the basename alone is too generic).
+const CREDENTIAL_PATH_RE = [
+  /[\\/]\.aws[\\/]credentials$/i,
+  /[\\/]\.kube[\\/]config$/i,
+  /[\\/]\.docker[\\/]config\.json$/i,
+  /[\\/]\.config[\\/]gh[\\/]hosts\.yml$/i, // GitHub CLI OAuth token
+  /[\\/]\.gnupg[\\/]/i, // GPG keyring directory
+  /service[-_]account[^\\/]*\.json$/i, // GCP service-account key JSON
+];
+
+// secret(s).{json,yml,yaml,env,txt}
+const SECRETS_FILE_RE = /(^|[\\/])secrets?\.(json|ya?ml|env|txt)$/i;
+
+function isEnvSecret(base) {
+  if (base.toLowerCase() === ".env") return true;
+  if (/^\.env\./i.test(base)) return !ENV_SAFE_SUFFIX_RE.test(base);
+  return false;
+}
+
+/**
+ * Is this path a credential / secret file the agent should not read unprompted?
+ * @param {string} targetPath  path as the tool received it (rel or abs)
+ * @returns {string|null} human reason when sensitive, null otherwise
+ */
+export function credentialFileReason(targetPath) {
+  const p = String(targetPath || "");
+  if (!p) return null;
+  const norm = p.replace(/\\/g, "/");
+  const base = norm.split("/").pop() || "";
+  if (!base) return null;
+  if (isEnvSecret(base)) return `environment/secret file (${base})`;
+  if (CREDENTIAL_BASENAMES.has(base.toLowerCase()))
+    return `credential file (${base})`;
+  if (SECRET_EXT_RE.test(base))
+    return `private key / certificate material (${base})`;
+  if (SECRETS_FILE_RE.test(norm)) return `secrets file (${base})`;
+  for (const re of CREDENTIAL_PATH_RE) {
+    if (re.test(norm)) return `credential file (${base})`;
+  }
+  return null;
+}
+
+// ── secret ENV-VAR + command detection ──────────────────────────────────────
+
+// Content-reader commands: when one of these is aimed at a credential file, the
+// file's bytes land in the agent's tool output.
+const READ_COMMANDS = new Set([
+  "cat",
+  "tac",
+  "type",
+  "gc",
+  "get-content",
+  "less",
+  "more",
+  "head",
+  "tail",
+  "bat",
+  "nl",
+  "xxd",
+  "od",
+  "strings",
+]);
+
+// Commands whose job is to print a value into output — the exfil surface for a
+// secret env var (a tool that merely CONSUMES `$API_KEY` does not echo it).
+const PRINT_COMMANDS = new Set([
+  "echo",
+  "echo.",
+  "print",
+  "printf",
+  "printenv",
+  "write-host",
+  "write-output",
+  "write-information",
+]);
+
+// A var name looks secret when one of these words appears as an underscore- or
+// boundary-delimited segment: ANTHROPIC_API_KEY, AWS_SECRET_ACCESS_KEY,
+// GITHUB_TOKEN, DB_PASSWORD, MY_PASSPHRASE, OPENAI_APIKEY. `MONKEY`/`KEYBOARD`/
+// `TOKENIZER` do NOT match (no boundary).
+const SECRET_VAR_RE =
+  /(?:^|_)(KEY|KEYS|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|CREDENTIALS|PRIVATE|APIKEY|ACCESSKEY)(?:_|$)/i;
+
+// Ways a secret var is referenced inside a shell segment.
+const SECRET_REF_PATTERNS = [
+  /\$env:([A-Za-z_][A-Za-z0-9_]*)/gi, // PowerShell  $env:NAME
+  /(?:^|[\s"'(=;|&])env:([A-Za-z_][A-Za-z0-9_]*)/gi, // PowerShell `env:` drive (Get-Content env:NAME)
+  /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, // ${NAME}
+  /\$([A-Za-z_][A-Za-z0-9_]*)/g, // $NAME
+  /%([A-Za-z_][A-Za-z0-9_]*)%/g, // %NAME% (cmd.exe)
+];
+
+function referencedSecretVars(segment) {
+  const out = [];
+  for (const re of SECRET_REF_PATTERNS) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(segment))) {
+      if (SECRET_VAR_RE.test(m[1])) out.push(m[1]);
+    }
+  }
+  return out;
+}
+
+function baseName(tok) {
+  const b =
+    String(tok || "")
+      .replace(/\\/g, "/")
+      .split("/")
+      .pop() || "";
+  return b.replace(/\.exe$/i, "");
+}
+
+function firstCommandToken(segment) {
+  const m = segment
+    .trim()
+    .replace(/^["']/, "")
+    .match(/^(\S+)/);
+  return m ? baseName(m[1]).toLowerCase() : "";
+}
+
+/**
+ * Does this (possibly compound) shell command read a credential file or print a
+ * secret environment variable?
+ * @param {string} command
+ * @returns {{reason:string, kind:string, target?:string, segment:string}|null}
+ */
+export function commandReadsCredentials(command) {
+  const cmd = String(command || "");
+  if (!cmd.trim()) return null;
+  let segments;
+  try {
+    segments = splitCommandSegments(cmd);
+  } catch {
+    segments = [cmd];
+  }
+  if (!segments.length) segments = [cmd];
+
+  for (const segment of segments) {
+    const seg = String(segment || "");
+    if (!seg.trim()) continue;
+    const first = firstCommandToken(seg);
+    // Backslash-preserving split (the policy's escaping tokenizer would mangle
+    // Windows paths); quotes flattened so grouping doesn't hide a token —
+    // credentialFileReason keys off the basename, which survives the split.
+    const rawTokens = seg.replace(/["']/g, " ").split(/\s+/).filter(Boolean);
+    const args = rawTokens.slice(1);
+    const nonFlagArgs = args.filter((t) => !t.startsWith("-"));
+
+    // (a) full-environment dump — printenv/env with no var, or PowerShell
+    //     `Get-ChildItem env:` family. Reveals EVERY secret at once.
+    if (
+      ((first === "printenv" || first === "env") && nonFlagArgs.length === 0) ||
+      (["get-childitem", "gci", "dir", "ls"].includes(first) &&
+        args.some((t) => /^env:?$/i.test(t)))
+    ) {
+      return {
+        reason: "dumps all environment variables (may expose secrets)",
+        kind: "env-dump",
+        segment: seg,
+      };
+    }
+
+    // (b) reading a credential file with a content-reader command.
+    if (READ_COMMANDS.has(first)) {
+      for (const tok of args) {
+        const r = credentialFileReason(tok);
+        if (r)
+          return {
+            reason: `reads ${r}`,
+            kind: "file",
+            target: tok,
+            segment: seg,
+          };
+      }
+    }
+
+    // (c) printing / reading a secret-looking env var (via $VAR / %VAR% / env:).
+    if (PRINT_COMMANDS.has(first) || READ_COMMANDS.has(first)) {
+      const vars = referencedSecretVars(seg);
+      if (vars.length)
+        return {
+          reason: `reads secret environment variable ${vars[0]}`,
+          kind: "env-var",
+          target: vars[0],
+          segment: seg,
+        };
+    }
+
+    // (d) `printenv ANTHROPIC_API_KEY` — bare var name (no $ sigil).
+    if (first === "printenv") {
+      const hit = nonFlagArgs.find((t) => SECRET_VAR_RE.test(t));
+      if (hit)
+        return {
+          reason: `reads secret environment variable ${hit}`,
+          kind: "env-var",
+          target: hit,
+          segment: seg,
+        };
+    }
+  }
+  return null;
+}
+
+/**
+ * Whether the credential guard is disabled via `CC_CREDENTIAL_GUARD`
+ * (0 / false / no / off). Default ON — only an explicit opt-out turns it off.
+ * @param {object} [env=process.env]
+ * @returns {boolean}
+ */
+export function credentialGuardDisabled(env = process.env) {
+  const raw = env && env.CC_CREDENTIAL_GUARD;
+  return raw != null && /^(0|false|no|off)$/i.test(String(raw).trim());
+}
+
+export const _internals = {
+  CREDENTIAL_BASENAMES,
+  READ_COMMANDS,
+  PRINT_COMMANDS,
+  SECRET_VAR_RE,
+  referencedSecretVars,
+  isEnvSecret,
+};

package/src/lib/ensure-utf8.js

@@ -45,8 +45,14 @@ export function ensureUtf8() {
 export function getUtf8SpawnOptions(opts = {}) {
   if (process.platform !== "win32") return { encoding: "utf-8", ...opts };
 
+  // NOTE: spread `...opts` BEFORE the `env` key so the merged UTF-8 env wins.
+  // If `...opts` came last, a caller passing `opts.env` would clobber the whole
+  // merge (losing process.env + PYTHONIOENCODING + CHCP) — silently defeating
+  // the entire point of this helper. opts.env is still merged in last *within*
+  // the env object so caller overrides for individual vars are honored.
   return {
     encoding: "utf-8",
+    ...opts,
     env: {
       ...process.env,
       PYTHONIOENCODING: "utf-8",
@@ -54,6 +60,5 @@ export function getUtf8SpawnOptions(opts = {}) {
       CHCP: "65001",
       ...opts.env,
     },
-    ...opts,
   };
 }