chainlesschain 0.162.188 → 0.162.193

package/src/command-surface-policy.js

@@ -0,0 +1,197 @@
+/**
+ * Stable command-surface policy used by the manifest generator.
+ *
+ * Keep this module dependency-free: phase-0 help and manifest generation both
+ * consume it before the full Commander command graph is loaded.
+ */
+
+export const COMMAND_MANIFEST_SCHEMA = "chainlesschain.command-manifest.v3";
+export const COMMAND_SURFACE_SCHEMA = "chainlesschain.command-surface.v2";
+export const COMMAND_LIFECYCLE_SCHEMA = "chainlesschain.command-lifecycle.v1";
+export const DEFAULT_COMMAND = "agent";
+
+export const TOP_LEVEL_GROWTH_POLICY = Object.freeze({
+  baselineCommandCount: 175,
+  maximumNetGrowth: 0,
+});
+
+export const COMMAND_NAMESPACES = Object.freeze([
+  Object.freeze({
+    name: "lab",
+    summary: "Compatibility namespace for long-tail and experimental commands",
+    visibility: "extended",
+  }),
+]);
+
+const MINIMUM_COMPATIBILITY_RELEASE_CYCLES = 2;
+
+const COMMAND_MIGRATIONS = Object.freeze({
+  dao: Object.freeze({
+    namespace: "lab",
+    deprecatedSince: "0.162.189",
+    removalNotBefore: "0.164.0",
+  }),
+  evomap: Object.freeze({
+    namespace: "lab",
+    deprecatedSince: "0.162.189",
+    removalNotBefore: "0.164.0",
+  }),
+});
+
+export const CORE_COMMAND_GROUPS = Object.freeze([
+  Object.freeze({
+    id: "code",
+    label: "Code",
+    commands: Object.freeze(["agent", "session", "skill"]),
+  }),
+  Object.freeze({
+    id: "integrations",
+    label: "Integrations",
+    commands: Object.freeze(["mcp", "plugin"]),
+  }),
+  Object.freeze({
+    id: "configuration",
+    label: "Configuration",
+    commands: Object.freeze(["config", "auth", "doctor", "status", "update"]),
+  }),
+]);
+
+const CORE_GROUP_BY_COMMAND = new Map(
+  CORE_COMMAND_GROUPS.flatMap((group) =>
+    group.commands.map((command) => [command, group]),
+  ),
+);
+
+function parseReleaseVersion(value, label) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) throw new Error(`${label} must be an exact semver release`);
+  return match.slice(1).map(Number);
+}
+
+function releaseCycleDistance(from, to) {
+  const [fromMajor, fromMinor] = parseReleaseVersion(from, "deprecatedSince");
+  const [toMajor, toMinor] = parseReleaseVersion(to, "removalNotBefore");
+  if (fromMajor !== toMajor) {
+    throw new Error(
+      "command migration windows may not cross a major release boundary",
+    );
+  }
+  return toMinor - fromMinor;
+}
+
+function lifecycleForCommand(commandName) {
+  const migration = COMMAND_MIGRATIONS[commandName];
+  if (!migration) return Object.freeze({ state: "active" });
+
+  const releaseCycles = releaseCycleDistance(
+    migration.deprecatedSince,
+    migration.removalNotBefore,
+  );
+  if (releaseCycles < MINIMUM_COMPATIBILITY_RELEASE_CYCLES) {
+    throw new Error(
+      `${commandName} must remain compatible for at least ${MINIMUM_COMPATIBILITY_RELEASE_CYCLES} release cycles`,
+    );
+  }
+
+  return Object.freeze({
+    state: "deprecated",
+    deprecatedSince: migration.deprecatedSince,
+    removalNotBefore: migration.removalNotBefore,
+    minimumReleaseCycles: MINIMUM_COMPATIBILITY_RELEASE_CYCLES,
+    releaseCycle: "minor",
+  });
+}
+
+export function validateCommandSurface(entries) {
+  if (!Array.isArray(entries)) {
+    throw new TypeError("command surface entries must be an array");
+  }
+  const netGrowth =
+    entries.length - TOP_LEVEL_GROWTH_POLICY.baselineCommandCount;
+  if (netGrowth > TOP_LEVEL_GROWTH_POLICY.maximumNetGrowth) {
+    throw new Error(
+      `Top-level command net growth is ${netGrowth}; maximum is ${TOP_LEVEL_GROWTH_POLICY.maximumNetGrowth}`,
+    );
+  }
+
+  const names = new Set(entries.map((entry) => entry.name));
+  const topLevelTokens = new Set(
+    entries.flatMap((entry) => [
+      entry.name,
+      ...(Array.isArray(entry.aliases) ? entry.aliases : []),
+    ]),
+  );
+  for (const namespace of COMMAND_NAMESPACES) {
+    if (topLevelTokens.has(namespace.name)) {
+      throw new Error(
+        `Virtual command namespace '${namespace.name}' collides with a registered top-level command or alias`,
+      );
+    }
+  }
+  for (const commandName of Object.keys(COMMAND_MIGRATIONS)) {
+    if (!names.has(commandName)) {
+      throw new Error(`Migrated command is not registered: ${commandName}`);
+    }
+  }
+
+  const deprecatedCompatibilityCount = entries.filter(
+    (entry) => entry.lifecycle?.state === "deprecated",
+  ).length;
+  const activeRegisteredCommandCount =
+    entries.length - deprecatedCompatibilityCount;
+  return {
+    ...TOP_LEVEL_GROWTH_POLICY,
+    registeredCommandCount: entries.length,
+    activeRegisteredCommandCount,
+    virtualNamespaceCount: COMMAND_NAMESPACES.length,
+    deprecatedCompatibilityCount,
+    recommendedTopLevelCommandCount:
+      activeRegisteredCommandCount + COMMAND_NAMESPACES.length,
+    netGrowth,
+  };
+}
+
+export function describeCommandSurface(commandName) {
+  const group = CORE_GROUP_BY_COMMAND.get(commandName);
+  const migration = COMMAND_MIGRATIONS[commandName];
+  return {
+    stability: group ? "stable" : "compatibility",
+    category: group?.id || "compatibility",
+    visibility: group ? "core" : "extended",
+    replacement: migration ? `${migration.namespace} ${commandName}` : null,
+    lifecycle: lifecycleForCommand(commandName),
+  };
+}
+
+export function buildCommandSurfaceDescriptor(entries = []) {
+  const migrationCommands = Object.entries(COMMAND_MIGRATIONS).map(
+    ([command, migration]) => ({
+      command,
+      replacement: `${migration.namespace} ${command}`,
+    }),
+  );
+  return {
+    schema: COMMAND_SURFACE_SCHEMA,
+    defaultCommand: DEFAULT_COMMAND,
+    lifecyclePolicy: {
+      schema: COMMAND_LIFECYCLE_SCHEMA,
+      minimumCompatibilityReleaseCycles: MINIMUM_COMPATIBILITY_RELEASE_CYCLES,
+      releaseCycle: "minor",
+    },
+    topLevelGrowth: validateCommandSurface(entries),
+    namespaces: COMMAND_NAMESPACES.map((namespace) => ({
+      ...namespace,
+      commands: migrationCommands
+        .filter(({ replacement }) =>
+          replacement.startsWith(`${namespace.name} `),
+        )
+        .map(({ command }) => command)
+        .sort(),
+    })),
+    coreGroups: CORE_COMMAND_GROUPS.map((group) => ({
+      id: group.id,
+      label: group.label,
+      commands: [...group.commands],
+    })),
+  };
+}

package/src/commands/agent.js

@@ -17,9 +17,11 @@ import {
 import { resolveImages, resolveVisionLlm } from "../lib/image-input.js";
 import { loadConfig } from "../lib/config-manager.js";
 import {
-  normalizeAgentSandbox,
+  normalizeAgentSandboxMode,
   assertSandboxAvailable,
+  enforceSandboxFailClosed,
 } from "../lib/agent-sandbox.js";
+import { appendSecurityAuditEvent } from "../lib/security-audit.js";
 
 /**
  * Resolve + validate `--add-dir` values into absolute, existing, de-duped
@@ -82,6 +84,12 @@ export function resolveFallbackModels(flagValue, llm = {}) {
   return normalizeFallbackModels(configured);
 }
 
+export function containsApiKeyArgument(argv = process.argv) {
+  return argv.some(
+    (value) => value === "--api-key" || String(value).startsWith("--api-key="),
+  );
+}
+
 /**
  * Read all of stdin as a UTF-8 string. Resolves "" immediately when stdin is a
  * TTY (nothing piped) so we never block an interactive invocation.
@@ -154,6 +162,10 @@ export function registerAgentCommand(program) {
       "--fork-session",
       "When resuming, branch into a NEW session id and leave the original untouched (claude --fork-session parity)",
     )
+    .option(
+      "--fork-request-id <key>",
+      "Stable idempotency key for --fork-session retries (omit for a new fork each invocation)",
+    )
     .option(
       "--add-dir <dir>",
       "Extra working directory the agent may read/search/edit (repeatable)",
@@ -167,6 +179,19 @@ export function registerAgentCommand(program) {
       "--no-checkpoint",
       "Disable auto-checkpointing (it is on by default inside git repos)",
     )
+    .option(
+      "--managed-checkpoint",
+      "Checkpoint bounded mutating tools with Process Broker; unavailable writer lifetimes are reported as coverage none",
+    )
+    .option(
+      "--managed-checkpoint-state <dir>",
+      "Durable managed-checkpoint state directory (must be outside the workspace)",
+    )
+    .option(
+      "--managed-checkpoint-exclude <path>",
+      "Explicit workspace path excluded from managed checkpoints; repeatable and reported as partial coverage",
+      (val, prev) => (prev || []).concat([val]),
+    )
     .option(
       "--safe-mode",
       "Run bare: disable project memory, settings hooks, memory recall, IDE context, status line and update notice (permission rules STAY active)",
@@ -207,6 +232,10 @@ export function registerAgentCommand(program) {
       "--sandbox [image]",
       "Run shell commands in an ephemeral Docker sandbox (network disabled by default)",
     )
+    .option(
+      "--sandbox-mode <mode>",
+      "Sandbox posture: off | workspace-write | strict (explicit isolation modes fail closed)",
+    )
     .option("--sandbox-network", "Allow network access inside --sandbox")
     .option(
       "--otlp <file>",
@@ -453,7 +482,7 @@ export function registerAgentCommand(program) {
         options.apiKey = process.env.CC_API_KEY;
       } else if (
         options.apiKey &&
-        process.argv.includes("--api-key") &&
+        containsApiKeyArgument(process.argv) &&
         !process.env.VITEST &&
         !process.env.VITEST_WORKER_ID
       ) {
@@ -478,6 +507,7 @@ export function registerAgentCommand(program) {
       // 2.1.169 parity): flip every customization kill-switch BEFORE anything
       // loads. Permission rules stay active. --bare (CC_BARE) is safe mode
       // PLUS skills, plugins and MCP/IDE/PDH/JetBrains auto-connect off.
+      let safeIsolationRequested = options.permissionMode === "auto";
       {
         const {
           applySafeMode,
@@ -486,6 +516,7 @@ export function registerAgentCommand(program) {
           bareModeRequested,
         } = await import("../lib/safe-mode.js");
         if (bareModeRequested(options)) {
+          safeIsolationRequested = true;
           const applied = applyBareMode();
           // Ambient auto-connects off; an EXPLICIT --ide/--pdh/--jetbrains
           // (or --mcp-config, handled downstream) still wins — bare kills
@@ -498,6 +529,7 @@ export function registerAgentCommand(program) {
             `bare mode: hooks/skills/plugins/memory/MCP-auto-connect disabled (${applied.join(", ")}) — permission rules stay active.\n`,
           );
         } else if (safeModeRequested(options)) {
+          safeIsolationRequested = true;
           const applied = applySafeMode();
           process.stderr.write(
             `safe mode: customizations disabled (${applied.join(", ")}) — permission rules stay active.\n`,
@@ -721,7 +753,11 @@ export function registerAgentCommand(program) {
         const { applyForkSession } =
           await import("../runtime/headless-runner.js");
         const fork = applyForkSession(
-          { forkSession: true, sessionId: options.session },
+          {
+            forkSession: true,
+            sessionId: options.session,
+            forkRequestId: options.forkRequestId,
+          },
           store,
         );
         if (fork.missing) {
@@ -778,6 +814,7 @@ export function registerAgentCommand(program) {
       // interactive, which all read options.model) picks it up; env vars are
       // set on the process so the agent loop + child tools inherit them.
       let settingsSandbox = null;
+      let managedSettingsSandbox = null;
       try {
         const { loadSettingsConfig } =
           await import("../lib/settings-loader.cjs");
@@ -800,8 +837,52 @@ export function registerAgentCommand(program) {
         }
         if (!options.model && sc.model) options.model = sc.model;
         settingsSandbox = sc.sandbox || null;
-      } catch {
-        // settings overrides are best-effort 鈥?never block the run
+        managedSettingsSandbox = sc.managedSandbox || null;
+      } catch (error) {
+        if (error?.code === "CC_MANAGED_SETTINGS_INVALID") {
+          process.stderr.write(`Error: ${error.message}\n`);
+          await _finishWorktree();
+          process.exit(6);
+        }
+        // User/project settings overrides remain best-effort. Organization
+        // managed settings are handled above and may never fail open.
+      }
+
+      let resolvedAgentSandbox;
+      try {
+        resolvedAgentSandbox = normalizeAgentSandboxMode(
+          options.sandboxMode,
+          options.sandbox,
+          {
+            cwd: process.cwd(),
+            network: options.sandboxNetwork === true,
+            settings: settingsSandbox,
+            managedSettings: managedSettingsSandbox,
+          },
+        );
+        if (safeIsolationRequested && resolvedAgentSandbox) {
+          resolvedAgentSandbox = enforceSandboxFailClosed(
+            resolvedAgentSandbox,
+            options.permissionMode === "auto" ? "auto" : "safe",
+          );
+        }
+        assertSandboxAvailable(resolvedAgentSandbox);
+        if (options.sandboxMode === "off") {
+          appendSecurityAuditEvent("sandbox_mode_off", {
+            details: {
+              command: "agent",
+              permissionMode: options.permissionMode || "default",
+              isolation: "policy-only",
+            },
+          });
+          process.stderr.write(
+            "Warning: sandbox mode is explicitly off; shell commands use policy checks without OS isolation.\n",
+          );
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        await _finishWorktree();
+        process.exit(6);
       }
 
       // Extra workspace roots (--add-dir) 鈥?shared by headless + interactive.
@@ -994,10 +1075,14 @@ export function registerAgentCommand(program) {
             // paths (default ON in a git repo) so panel/stream sessions snapshot
             // before mutating tools and can be rewound via `cc checkpoint`.
             autoCheckpoint,
+            managedCheckpoint: options.managedCheckpoint === true,
+            managedCheckpointStateDir: options.managedCheckpointState || null,
+            managedCheckpointExclusions: options.managedCheckpointExclude || [],
             permissionMode: options.permissionMode,
             allowedTools: parseToolList(options.allowedTools),
             disallowedTools: parseToolList(options.disallowedTools),
             additionalDirectories,
+            sandbox: resolvedAgentSandbox,
             maxTurns: options.maxTurns
               ? parseInt(options.maxTurns, 10)
               : undefined,
@@ -1163,20 +1248,6 @@ export function registerAgentCommand(program) {
           }
           return;
         }
-        const agentSandbox = normalizeAgentSandbox(options.sandbox, {
-          cwd: process.cwd(),
-          network: options.sandboxNetwork === true,
-          settings: settingsSandbox,
-        });
-        // Strict sandbox mode: failIfUnavailable refuses to START when the
-        // configured engine can't run — no silent per-command degradation.
-        try {
-          assertSandboxAvailable(agentSandbox);
-        } catch (err) {
-          process.stderr.write(`Error: ${err.message}\n`);
-          await _finishWorktree();
-          process.exit(6); // config error (see lib/exit-codes.cjs)
-        }
         // Resume requested onto a session with no headless (JSONL) transcript?
         // Warn instead of silently starting empty 鈥?headless resume rebuilds
         // from the JSONL store only (DB-only sessions are not replayable here).
@@ -1230,8 +1301,11 @@ export function registerAgentCommand(program) {
           allowedTools: parseToolList(options.allowedTools),
           disallowedTools: parseToolList(options.disallowedTools),
           additionalDirectories,
-          sandbox: agentSandbox,
+          sandbox: resolvedAgentSandbox,
           autoCheckpoint,
+          managedCheckpoint: options.managedCheckpoint === true,
+          managedCheckpointStateDir: options.managedCheckpointState || null,
+          managedCheckpointExclusions: options.managedCheckpointExclude || [],
           // --worktree: stamp the isolation worktree (branch name) onto each
           // turn's explicit turn-binding record (advisory; null without it).
           worktreeId: _worktree ? _worktree.branch : null,
@@ -1401,18 +1475,6 @@ export function registerAgentCommand(program) {
 
       // Strict sandbox mode also guards the interactive session: refuse to
       // start when failIfUnavailable is set and the engine can't run.
-      const interactiveSandbox = normalizeAgentSandbox(options.sandbox, {
-        cwd: process.cwd(),
-        network: options.sandboxNetwork === true,
-        settings: settingsSandbox,
-      });
-      try {
-        assertSandboxAvailable(interactiveSandbox);
-      } catch (err) {
-        process.stderr.write(`Error: ${err.message}\n`);
-        process.exit(6); // config error (see lib/exit-codes.cjs)
-      }
-
       const runtime = createAgentRuntimeFactory().createAgentRuntime({
         model: options.model,
         thinking,
@@ -1434,8 +1496,11 @@ export function registerAgentCommand(program) {
         parkOnExit: options.parkOnExit, // false when --no-park-on-exit
         bundlePath: options.bundle || null,
         additionalDirectories,
-        sandbox: interactiveSandbox,
+        sandbox: resolvedAgentSandbox,
         autoCheckpoint,
+        managedCheckpoint: options.managedCheckpoint === true,
+        managedCheckpointStateDir: options.managedCheckpointState || null,
+        managedCheckpointExclusions: options.managedCheckpointExclude || [],
         // Keep interactive --worktree sessions in the same explicit
         // turn-binding coverage model as headless runs.
         worktreeId: _worktree ? _worktree.branch : null,