chainlesschain 0.162.159 → 0.162.161

package/src/repl/bg-dashboard.js

@@ -1,9 +1,11 @@
 /**
  * Background-agent dashboard — the interactive agent view behind
  * `cc daemon view` (no id). Claude-Code `claude agents` parity: one live panel
- * over every background session with grouping (Needs input / Working /
+ * over every background session with grouping (Needs input / Working / Idle /
  * Completed / Failed / Stopped), peek + reply, attach hand-off, stop, rename,
- * pin, filter, and new-task dispatch.
+ * pin, filter, and new-task dispatch. Phase→group classification is the shared
+ * `background-agent-phase.js` contract, so `idle` (parked, nothing blocking)
+ * is kept distinct from a genuine `needs-input` (a human decision blocks it).
  *
  * Design:
  * - Pure model/render layer (`groupKey`, `buildDashboardModel`,
@@ -17,10 +19,12 @@
  */
 
 import chalk from "chalk";
+import { phaseGroupKey } from "../lib/background-agent-phase.js";
 
 export const GROUP_ORDER = [
   "needs-input",
   "working",
+  "idle",
   "completed",
   "failed",
   "stopped",
@@ -29,24 +33,21 @@ export const GROUP_ORDER = [
 export const GROUP_TITLES = {
   "needs-input": "Needs input",
   working: "Working",
+  idle: "Idle",
   completed: "Completed",
   failed: "Failed",
   stopped: "Stopped",
 };
 
 /**
- * Group a session: running+idle phase = waiting for a follow-up (the closest
- * analog of "needs input" — the worker finished a turn and a client can
- * reply); running+turn = working; lost workers count as failed.
+ * Group a session into a dashboard bucket. Delegates to the shared
+ * `background-agent-phase.js` contract so the worker/supervisor and this panel
+ * agree on phase semantics: running + pending approval / blocking phase →
+ * "needs-input"; running + idle (parked, nothing blocking) → "idle"; running +
+ * working/turn/starting → "working"; lost/unknown → "failed".
  */
 export function groupKey(session) {
-  const status = session?.status;
-  if (status === "running") {
-    return session.phase === "idle" ? "needs-input" : "working";
-  }
-  if (status === "completed") return "completed";
-  if (status === "stopped") return "stopped";
-  return "failed"; // failed | lost | unknown
+  return phaseGroupKey(session);
 }
 
 function formatAge(ms) {

package/src/runtime/agent-core.js

@@ -25,6 +25,7 @@ import sharedSettingsHooks from "../lib/settings-hooks.cjs";
 import sharedHookRunner from "../lib/hook-runner.cjs";
 import sharedHookEvents from "../lib/settings-hook-events.cjs";
 import { mergeProviderOptions } from "../lib/provider-options.js";
+import { applyCredentialProxy } from "../lib/credential-proxy.js";
 import { getPlanModeManager } from "../lib/plan-mode.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
 import { executeHooks, HookEvents } from "../lib/hook-manager.js";
@@ -673,8 +674,8 @@ Key behaviors:
 When the user's problem involves data processing, calculations, file operations, text parsing, API calls, web scraping, or any task that can be solved programmatically:
 - Proactively write and execute code using run_code tool
 - Choose the best language: Python for data/math/scraping, Node.js for JSON/API, Bash for system tasks
-- Missing Python packages are auto-installed via pip when import errors are detected
-- Scripts are persisted in .chainlesschain/agent-scripts/ for reference
+- Missing Python packages are NOT auto-installed by default; the tool result tells you (and the user) how to opt in (settings runCode.autoInstall)
+- Scripts run from a temp file by default; pass persist:true to keep one in .chainlesschain/agent-scripts/ for reference
 - Show the results and explain them clearly
 - If the first attempt fails, debug and retry with a different approach
 
@@ -1263,6 +1264,8 @@ export async function executeTool(name, args, context = {}) {
   // Sensitive-file write guard (Claude-Code 2.1.160 parity): shell startup
   // files / PowerShell profiles / git+husky hooks execute code on the user's
   // next shell or commit — even otherwise-permitted edit flows confirm first.
+  // Auto-exec configs (.vscode/tasks.json, .mcp.json, .idea run configs, …)
+  // ride the same gate via autoExecConfigReason.
   // An explicit settings `allow` rule is the only bypass (exact user
   // pre-authorization); headless without a confirmer fails closed.
   if (
@@ -1272,9 +1275,10 @@ export async function executeTool(name, args, context = {}) {
     settingsVerdict.decision !== "allow" &&
     args?.path
   ) {
-    const { sensitiveFileReason } =
+    const { sensitiveFileReason, autoExecConfigReason } =
       await import("../lib/sensitive-file-guard.js");
-    const sensReason = sensitiveFileReason(args.path);
+    const sensReason =
+      sensitiveFileReason(args.path) || autoExecConfigReason(args.path);
     if (sensReason) {
       const ok = await requestInteractivePermission(name, args, context, cwd, {
         tool: name,
@@ -2537,7 +2541,10 @@ async function executeToolInner(
             // Same agent-identity env as the foreground path: CLAUDECODE marks
             // "running under the agent"; the session id correlates work to the
             // run (CC_SESSION_ID + CLAUDE_CODE_SESSION_ID for Claude-Code parity).
-            env: {
+            // Credential proxy (opt-in, CC_CREDENTIAL_PROXY): keeps the agent's
+            // real long-lived secrets out of the spawned command's env — a
+            // no-op (same object) when disabled. See credential-proxy.js.
+            env: applyCredentialProxy({
               ...process.env,
               CLAUDECODE: "1",
               ...(sessionId
@@ -2546,7 +2553,7 @@ async function executeToolInner(
                     CLAUDE_CODE_SESSION_ID: String(sessionId),
                   }
                 : {}),
-            },
+            }).env,
             // POSIX: own process group so check_shell{kill}/teardown can signal
             // the whole tree (shell + its grandchild command). No-op on Windows
             // where the tree is killed via taskkill /T instead.
@@ -2712,7 +2719,10 @@ async function executeToolInner(
           // parity): CLAUDECODE=1 marks "running under the agent"; CC_SESSION_ID
           // + its CLAUDE_CODE_SESSION_ID mirror let scripts/hooks correlate work
           // to the agent session (the mirror is what CC-targeting tools expect).
-          env: {
+          // Credential proxy (opt-in, CC_CREDENTIAL_PROXY): keeps the agent's
+          // real long-lived secrets out of the shell's env — a no-op (same
+          // object) when disabled. See credential-proxy.js.
+          env: applyCredentialProxy({
             ...process.env,
             CLAUDECODE: "1",
             ...(sessionId
@@ -2721,7 +2731,7 @@ async function executeToolInner(
                   CLAUDE_CODE_SESSION_ID: String(sessionId),
                 }
               : {}),
-          },
+          }).env,
         };
         let output;
         if (shellInv.useDefaultShell) {
@@ -3908,7 +3918,10 @@ async function _executeRunCode(args, cwd) {
   const lang = args.language;
   const code = args.code;
   const timeoutSec = Math.min(Math.max(args.timeout || 60, 1), 300);
-  const persist = args.persist !== false; // default true
+  // gap-analysis 2026-07-11 P0 "依赖安装与凭据": agent-generated scripts
+  // default to the OS temp dir; only an explicit persist:true lands them in
+  // the project (.chainlesschain/agent-scripts/).
+  const persist = args.persist === true; // default false (temp dir)
 
   const extMap = { python: ".py", node: ".js", bash: ".sh" };
   const ext = extMap[lang];
@@ -3978,6 +3991,51 @@ async function _executeRunCode(args, cwd) {
             };
           }
 
+          // Auto-install is OPT-IN (settings runCode.autoInstall / env
+          // CC_RUN_CODE_AUTO_INSTALL=1) with an optional package allowlist;
+          // every attempt — including refused ones — is audited.
+          const {
+            resolveAutoInstallPolicy,
+            isPackageAllowed,
+            autoInstallDisabledHint,
+            recordInstallAudit,
+          } = await import("../lib/dependency-install-policy.js");
+          const installPolicy = resolveAutoInstallPolicy({ cwd });
+          if (!installPolicy.enabled) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "disabled",
+            });
+            return {
+              error: (stderr || message).substring(0, 5000),
+              stderr: stderr.substring(0, 5000),
+              exitCode: err.status,
+              language: lang,
+              ...classified,
+              hint: autoInstallDisabledHint(packageName),
+              scriptPath: persist ? scriptPath : undefined,
+            };
+          }
+          if (!isPackageAllowed(packageName, installPolicy.allowlist)) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "blocked",
+            });
+            return {
+              error: (stderr || message).substring(0, 5000),
+              stderr: stderr.substring(0, 5000),
+              exitCode: err.status,
+              language: lang,
+              ...classified,
+              hint: `Package "${packageName}" is not in runCode.installAllowlist — install it manually or add it to the allowlist.`,
+              scriptPath: persist ? scriptPath : undefined,
+            };
+          }
+
           // Attempt pip install
           try {
             execSync(`${interpreter} -m pip install ${packageName}`, {
@@ -3986,6 +4044,12 @@ async function _executeRunCode(args, cwd) {
               maxBuffer: 2 * 1024 * 1024,
               stdio: ["pipe", "pipe", "pipe"],
             });
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "installed",
+            });
 
             // Retry execution
             const retryStart = Date.now();
@@ -4006,6 +4070,13 @@ async function _executeRunCode(args, cwd) {
               scriptPath: persist ? scriptPath : undefined,
             };
           } catch (pipErr) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "failed",
+              detail: (pipErr.stderr || pipErr.message || "").substring(0, 200),
+            });
             return {
               error: (stderr || message).substring(0, 5000),
               stderr: stderr.substring(0, 5000),
@@ -4233,6 +4304,17 @@ async function _executeSpawnSubAgent(args, ctx) {
     tools: explicitTools,
     profile: profileName,
   } = args;
+  // Extended sub-agent contract (gap 2026-07-11 P1): per-spawn deny-list,
+  // iteration cap and worktree isolation — spawn args win over the agent
+  // file's frontmatter defaults.
+  let disallowedTools = Array.isArray(args.disallowedTools)
+    ? args.disallowedTools.filter(Boolean)
+    : null;
+  let subMaxTurns =
+    Number.isFinite(Number(args.maxTurns)) && Number(args.maxTurns) > 0
+      ? Math.floor(Number(args.maxTurns))
+      : null;
+  let subIsolation = args.isolation === "worktree" ? "worktree" : null;
 
   // Named subagent delegation (cc agents / .chainlesschain|.claude/agents/*.md):
   // load the agent's persona (its body = system prompt) + tool allow-list.
@@ -4250,6 +4332,13 @@ async function _executeSpawnSubAgent(args, ctx) {
       }
       role = role || md.name;
       if (!explicitTools && Array.isArray(md.tools)) explicitTools = md.tools;
+      if (!disallowedTools && Array.isArray(md.disallowedTools)) {
+        disallowedTools = md.disallowedTools;
+      }
+      if (!subMaxTurns && md.maxTurns) subMaxTurns = md.maxTurns;
+      if (!subIsolation && md.isolation === "worktree") {
+        subIsolation = "worktree";
+      }
       if (md.model) mdModel = md.model;
       if (md.systemPrompt) {
         mdProfile = { name: md.name, systemPrompt: md.systemPrompt };
@@ -4289,9 +4378,19 @@ async function _executeSpawnSubAgent(args, ctx) {
   // profile.systemPrompt seam) when no declarative profile was requested.
   if (!profile && mdProfile) profile = mdProfile;
 
-  const allowedTools = Array.isArray(explicitTools)
+  let allowedTools = Array.isArray(explicitTools)
     ? explicitTools
     : profile?.toolAllowlist || null;
+  // Deny-list: subtract from the resolved allow-list; with no allow-list
+  // ("all tools"), subtract from the full built-in contract set. spawn itself
+  // is always denied downstream by depth/breadth caps, so no special-casing.
+  if (Array.isArray(disallowedTools) && disallowedTools.length > 0) {
+    const deny = new Set(disallowedTools.map((t) => String(t).trim()));
+    const base = Array.isArray(allowedTools)
+      ? allowedTools
+      : listCodingAgentToolNames();
+    allowedTools = base.filter((t) => !deny.has(t));
+  }
 
   // Auto-condense parent context if caller didn't provide explicit context
   let resolvedContext = inheritedContext || null;
@@ -4399,6 +4498,10 @@ async function _executeSpawnSubAgent(args, ctx) {
     // single total-sub-agent pool (breadth cap spans the whole tree).
     subAgentBudget: ctx.subAgentBudget || null,
     onUsage,
+    // Extended contract (gap 2026-07-11): per-agent iteration cap + opt-in
+    // worktree isolation. undefined keeps the profile/flag defaults intact.
+    ...(subMaxTurns ? { maxIterations: subMaxTurns } : {}),
+    ...(subIsolation === "worktree" ? { useWorktree: true } : {}),
   });
   subCtxRef = subCtx;
 

package/src/runtime/coding-agent-contract-shared.cjs

@@ -521,7 +521,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "code",
     tier: "extension",
     description:
-      "Write and execute code in Python, Node.js, or Bash. Use this when the user needs data processing, calculations, file batch operations, API calls, or any task best solved with a script. Scripts are saved for reference. Missing Python packages are auto-installed.",
+      "Write and execute code in Python, Node.js, or Bash. Use this when the user needs data processing, calculations, file batch operations, API calls, or any task best solved with a script. Scripts run from a temp file unless persist:true. Missing Python packages are NOT auto-installed unless the user opted in (settings runCode.autoInstall).",
     inputSchema: {
       type: "object",
       properties: {
@@ -538,7 +538,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
         persist: {
           type: "boolean",
           description:
-            "If true (default), save script in .chainlesschain/agent-scripts/. If false, use temp file and clean up.",
+            "If true, save the script in .chainlesschain/agent-scripts/ for reference. Default false: run from a temp file outside the project.",
         },
       },
       required: ["language", "code"],
@@ -599,6 +599,23 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           description:
             "Run the sub-agent in the BACKGROUND: the call returns immediately with a running handle and you continue working; the sub-agent's result is delivered to you automatically in a later turn (the run waits for stragglers before finishing). Use for independent subtasks you don't need before your next step.",
         },
+        disallowedTools: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional tool DENY-list for the sub-agent: these are removed from whatever tool set it would otherwise get (explicit `tools`, agent-file allowlist, or all).",
+        },
+        maxTurns: {
+          type: "number",
+          description:
+            "Optional iteration cap for the sub-agent's own loop (positive integer; default 8 or the profile's cap).",
+        },
+        isolation: {
+          type: "string",
+          enum: ["worktree"],
+          description:
+            "Optional isolation mode: \"worktree\" runs the sub-agent in a fresh git worktree so its file edits land on an isolated branch (diff/merge summary comes back with the result).",
+        },
       },
       required: ["task"],
     },

package/src/runtime/headless-runner.js

@@ -54,6 +54,18 @@ import { composeSystemPrompt } from "./system-prompt.js";
 import { buildUserContent } from "../lib/image-input.js";
 import { mergeConsecutiveMessages } from "./message-roles.js";
 import { isHeadlessConfigCommand } from "../lib/headless-config-command.js";
+import {
+  STREAM_PROTOCOL_VERSION,
+  computePolicyDigest,
+  computeToolsHash,
+  buildLoadedSources,
+} from "../lib/headless-manifest.js";
+import {
+  HEADLESS_EXIT_CODES,
+  classifyLoopError,
+  exitCodeForEndReason,
+} from "../lib/exit-codes.cjs";
+import { isolationLevel } from "../lib/agent-sandbox.js";
 import { withQuietStdout } from "./quiet-stdout.js";
 import { CostBudget } from "../lib/cost-budget.js";
 import {
@@ -200,13 +212,18 @@ export function parseToolList(value) {
  * Persistence is intentionally OFF unless a resume/continue/persist intent is
  * present, so a plain one-shot `cc agent -p "..."` writes nothing to disk.
  *
- * @param {object} options { resume, continueSession, sessionId, persistSession }
+ * `--ephemeral` forces persistence OFF regardless of the above: a resume id
+ * still REPLAYS prior history into context, but nothing new is written — the
+ * deterministic-CI shape ("read context, leave no trace").
+ *
+ * @param {object} options { resume, continueSession, sessionId, persistSession, ephemeral }
  * @param {object} store   { getLastSessionId }  (injection seam)
  * @param {string} fallbackId  used when nothing is being resumed
  * @returns {{ sessionId:string, resumeId:string|null, persist:boolean, wantLatest:boolean }}
  */
 export function resolveHeadlessSession(options = {}, store = {}, fallbackId) {
-  const { resume, continueSession, sessionId, persistSession } = options;
+  const { resume, continueSession, sessionId, persistSession, ephemeral } =
+    options;
   const wantLatest = continueSession === true || resume === true;
   let resumeId = null;
   if (wantLatest) {
@@ -217,7 +234,10 @@ export function resolveHeadlessSession(options = {}, store = {}, fallbackId) {
   } else if (typeof resume === "string" && resume.trim()) {
     resumeId = resume.trim();
   }
-  const persist = persistSession === true || resumeId != null || wantLatest;
+  const persist =
+    ephemeral === true
+      ? false
+      : persistSession === true || resumeId != null || wantLatest;
   const id = resumeId || sessionId || fallbackId;
   return { sessionId: id, resumeId, persist, wantLatest };
 }
@@ -900,7 +920,12 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     } catch (err) {
       writeErr(`Error: ${err.message}\n`);
       emitHeadlessError(err.message);
-      return { exitCode: 1, result: err.message, isError: true };
+      // Bad --mcp-config / MCP wiring is a CONFIG error, not a run failure.
+      return {
+        exitCode: HEADLESS_EXIT_CODES.CONFIG_ERROR,
+        result: err.message,
+        isError: true,
+      };
     }
   }
 
@@ -943,7 +968,12 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       writeErr(`Error: ${err.message}\n`);
       if (mcp?.mcpClient) await mcp.mcpClient.disconnectAll().catch(() => {});
       emitHeadlessError(err.message);
-      return { exitCode: 1, result: err.message, isError: true };
+      // A bad --permission-prompt-tool reference is a CONFIG error.
+      return {
+        exitCode: HEADLESS_EXIT_CODES.CONFIG_ERROR,
+        result: err.message,
+        isError: true,
+      };
     }
     if (approvalGate && typeof approvalGate.setConfirmer === "function") {
       approvalGate.setConfirmer(
@@ -1175,11 +1205,32 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   emitStream({
     type: "system",
     subtype: "init",
+    // Deterministic-headless manifest (gap-analysis 2026-07-11): protocol
+    // version + persistence + live sources + policy/tool digests so CI can
+    // assert the run shape. Mirrors agent-sdk PROTOCOL_VERSION.
+    protocol_version: STREAM_PROTOCOL_VERSION,
     session_id: sessionId,
+    session_persistence: persist,
     model,
     provider,
     permission_mode: options.permissionMode || "default",
     tools: enabledToolNames,
+    tools_hash: computeToolsHash(enabledToolNames),
+    policy_digest: computePolicyDigest({
+      permissionMode: options.permissionMode,
+      allowedTools: options.allowedTools,
+      disallowedTools: options.disallowedTools,
+      permissionRules,
+    }),
+    loaded_sources: buildLoadedSources({
+      permissionRules,
+      settingsHooks,
+      mcp: Boolean(mcp),
+      enabledToolNames,
+    }),
+    // True isolation level for tool subprocesses: os-sandbox (bwrap) /
+    // container (docker) / policy-only (no sandbox — rules are pre-execution).
+    isolation_level: isolationLevel(options.sandbox),
     max_turns: budget.limit,
     resumed_from: resumeId,
     history_messages: history.length,
@@ -1471,7 +1522,9 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     } else {
       writeErr(`Error: ${message}\n`);
     }
-    return { exitCode: 1, result: message, isError: true };
+    // Provider/transport failures get their own exit code (5) so CI can tell
+    // "the model call failed" from "the run itself errored" (1).
+    return { exitCode: classifyLoopError(err), result: message, isError: true };
   } finally {
     // Drop the signal handlers first — a normal return must not leave a
     // process-wide SIGINT/SIGTERM listener behind (a later Ctrl-C would wrongly
@@ -1739,7 +1792,13 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   }
 
-  return { exitCode: isError ? 1 : 0, result: finalText, isError };
+  // Exit-code taxonomy: max-turns → 3, cost cap → 4 (both still non-zero, so
+  // "any failure" checks keep working; scripts can now tell exhaustion apart).
+  return {
+    exitCode: exitCodeForEndReason(endReason, isError),
+    result: finalText,
+    isError,
+  };
 }
 
 function buildResultEnvelope({