@chorus-aidlc/chorus 0.17.3 → 0.18.1

package/cli/agent-cli-config.mjs

@@ -0,0 +1,323 @@
+// Per-profile literal argv/env. No IO, interpolation, defaults shared across agents,
+// or attempt to sandbox an operator who controls their executable/config files.
+const canonicalType = (type) => type === "claude" ? "claude-code" : type;
+
+// Known controls owned by the headless adapters (also protected in persistent
+// foreground config). Short options match attached values and clusters as well.
+const PROTECTED = {
+  "claude-code": {
+    long: "print output-format input-format verbose session-id resume continue fork-session no-session-persistence mcp-config strict-mcp-config permission-mode permission-prompts permission-prompt-tool dangerously-skip-permissions allow-dangerously-skip-permissions allowedTools allowed-tools disallowedTools disallowed-tools tools add-dir cwd system-prompt system-prompt-file append-system-prompt append-system-prompt-file settings setting-sources agent agents worktree teleport from-pr remote-control remote-control-session-name-prefix background bg cloud environment bare json-schema include-partial-messages replay-user-messages restricted safe-mode system-prompt-snapshot tmux include-hook-events forward-subagent-text prompt-suggestions",
+    short: "prcwv",
+  },
+  codex: {
+    long: "json experimental-json output-schema output-last-message color sandbox ask-for-approval full-auto approve-for-me not-so-yolo yolo dangerously-bypass-approvals-and-sandbox dangerously-bypass-hook-trust cd add-dir skip-git-repo-check ephemeral last all session resume fork profile remote remote-auth-token-env thread-source ignore-user-config ignore-rules",
+    short: "soaCp",
+  },
+  kiro: {
+    long: "no-interactive resume resume-id resume-picker agent trust-all-tools trust-tools list-sessions delete-session session-source format agent-engine v3 mode cwd tui legacy-ui classic list-models verbose",
+    short: "raldfv",
+  },
+  pi: {
+    long: "print mode continue resume session session-id session-dir no-session fork name cwd system-prompt append-system-prompt export list-models",
+    short: "pcrn",
+  },
+  dsh: {
+    long: "profile patch dump-config dump-default-config resume session session-id cwd rpc mode prompt",
+    short: "",
+  },
+  opencode: {
+    long: "continue session fork prompt agent port hostname mdns mdns-domain cors",
+    short: "cs",
+  },
+  openclaw: {
+    long: "session session-key session-id message agent local json gateway port profile dev to",
+    short: "mt",
+  },
+};
+
+// Arity is separate from protection and singleton precedence. This is NOT a
+// generic third-party parser: unknown flags pass through, but we never guess
+// whether their next token is a value. Sources/limitations: docs/DAEMON.md.
+// Each entry is zero, one required value, optional value, or variadic values.
+const ARITIES = {
+  "claude-code": {
+    zero: "print continue verbose fork-session no-session-persistence strict-mcp-config dangerously-skip-permissions allow-dangerously-skip-permissions bg background bare brief chrome no-chrome disable-slash-commands ide ax-screen-reader exclude-dynamic-system-prompt-sections include-hook-events include-partial-messages forward-subagent-text replay-user-messages restricted safe-mode",
+    one: "model effort autocompact debug-file fallback-model max-budget-usd plugin-dir plugin-url name agent agents append-system-prompt append-system-prompt-file system-prompt system-prompt-file input-format output-format json-schema permission-mode permission-prompts permission-prompt-tool session-id settings setting-sources environment remote-control-session-name-prefix system-prompt-snapshot",
+    optional: "debug resume worktree cloud from-pr remote-control teleport prompt-suggestions tmux",
+    many: "add-dir allowedTools allowed-tools disallowedTools disallowed-tools tools mcp-config betas file",
+    aliases: { "-p": "--print", "-c": "--continue", "-d": "--debug", "-n": "--name", "-r": "--resume", "-w": "--worktree" },
+  },
+  codex: {
+    zero: "strict-config oss search no-alt-screen json experimental-json full-auto approve-for-me not-so-yolo yolo dangerously-bypass-approvals-and-sandbox dangerously-bypass-hook-trust skip-git-repo-check ephemeral last all ignore-user-config ignore-rules",
+    one: "model config enable disable image local-provider profile sandbox ask-for-approval cd add-dir remote remote-auth-token-env thread-source output-schema output-last-message color",
+    aliases: { "-m": "--model", "-c": "--config", "-i": "--image", "-p": "--profile", "-s": "--sandbox", "-a": "--ask-for-approval", "-C": "--cd", "-o": "--output-last-message" },
+  },
+  kiro: {
+    zero: "resume resume-picker trust-all-tools no-interactive list-sessions list-models require-mcp-startup verbose tui legacy-ui classic v3",
+    one: "model effort resume-id agent trust-tools format delete-session session-source wrap agent-engine mode",
+    aliases: { "-r": "--resume", "-a": "--trust-all-tools", "-l": "--list-sessions", "-f": "--format", "-d": "--delete-session", "-w": "--wrap", "-v": "--verbose" },
+  },
+  pi: {
+    zero: "continue resume no-session no-tools no-builtin-tools no-extensions no-skills no-prompt-templates no-themes no-context-files verbose approve no-approve offline",
+    one: "provider model api-key system-prompt append-system-prompt mode session session-id fork session-dir name models tools exclude-tools thinking extension skill prompt-template theme use-theme export tui-mode",
+    optional: "print list-models",
+    aliases: { "-p": "--print", "-c": "--continue", "-r": "--resume", "-n": "--name", "-nt": "--no-tools", "-nbt": "--no-builtin-tools", "-t": "--tools", "-xt": "--exclude-tools", "-e": "--extension", "-ne": "--no-extensions", "-ns": "--no-skills", "-np": "--no-prompt-templates", "-nc": "--no-context-files", "-a": "--approve", "-na": "--no-approve" },
+  },
+  dsh: { zero: "dump-config dump-default-config", one: "profile patch" },
+  opencode: {
+    zero: "print-logs pure continue fork mdns",
+    one: "log-level model session prompt agent port hostname mdns-domain",
+    many: "cors",
+    aliases: { "-m": "--model", "-c": "--continue", "-s": "--session" },
+  },
+  openclaw: {
+    zero: "local json deliver dry-run best-effort-deliver dev no-color",
+    one: "model thinking message to session-id agent channel reply-to reply-channel reply-account timeout verbose profile log-level",
+    aliases: { "-m": "--message", "-t": "--to" },
+  },
+};
+const OPTION_ARITIES = Object.fromEntries(Object.entries(ARITIES).map(([type, spec]) => {
+  const flags = { "--help": "zero", "--version": "zero" };
+  for (const arity of ["zero", "one", "optional", "many"])
+    for (const name of (spec[arity] ?? "").split(" ").filter(Boolean)) flags[`--${name}`] = arity;
+  return [type, { flags, aliases: { "-h": "--help", "-V": "--version", "-v": "--version", ...spec.aliases } }];
+}));
+
+function optionAt(type, args, i) {
+  const spec = OPTION_ARITIES[type];
+  const token = args[i];
+  let flag = token.split("=", 1)[0];
+  let attached = token.includes("=");
+  // Pi has exact multi-character aliases (-nt, -xt, ...), not short clusters.
+  if (type !== "pi" && /^-[^-].+/.test(token) && !spec?.aliases[flag]) {
+    const short = token.slice(0, 2);
+    if (spec?.flags[spec.aliases[short]] === "one" || spec?.flags[spec.aliases[short]] === "optional") {
+      flag = short;
+      attached = true;
+    }
+  }
+  flag = spec?.aliases[flag] ?? flag;
+  const arity = spec?.flags[flag];
+  if (!arity) return null;
+  let size = 1;
+  const next = args[i + 1];
+  // Clap/yargs keep -- as a boundary; Pi and Commander consume it literally
+  // as a required value. Persistent configuration rejects sentinels either way.
+  const literalSentinel = ["pi", "claude-code", "dsh", "openclaw"].includes(type);
+  const piNonOptionValue = type === "pi" && ["--use-theme", "--tui-mode"].includes(flag);
+  const hasNext = next !== undefined && (next !== "--" || literalSentinel) &&
+    !(piNonOptionValue && next.startsWith("-"));
+  if (!attached && hasNext) {
+    if (arity === "one" || arity === "many") size++;
+    else if (arity === "optional" && !next.startsWith("-")) size++;
+  }
+  if (arity === "many") {
+    while (i + size < args.length && !args[i + size].startsWith("-")) size++;
+  }
+  return { flag, arity, size, missing: !attached && ["one", "many"].includes(arity) && size === 1 };
+}
+
+function invalid(label, field, reason) {
+  // Never include the token, env name, or value: even malformed keys can be secrets.
+  throw new Error(`Agent ${label}: ${field} ${reason}.`);
+}
+
+export function rejectSharedCliConfig(file) {
+  if (Array.isArray(file?.agents) && file.agents.length &&
+      (Object.hasOwn(file, "args") || Object.hasOwn(file, "env"))) {
+    throw new Error("daemon.json: top-level args/env cannot be shared with agents[]; move them into each agent entry.");
+  }
+}
+
+// Codex -c is repeatable by TOML key, not a singleton flag. Parse only a simple
+// dotted/quoted key; reject ambiguous keys in persistent config rather than risk
+// allowing quoted protected controls to bypass the guard.
+function codexConfigAt(args, i) {
+  const tok = args[i];
+  let value;
+  let size = 1;
+  if (tok === "-c" || tok === "--config") { value = args[i + 1]; size = value === "--" || value === undefined ? 1 : 2; }
+  else if (tok.startsWith("--config=")) value = tok.slice(9);
+  else if (tok.startsWith("-c") && !tok.startsWith("--")) value = tok.slice(2).replace(/^=/, "");
+  else return null;
+  const raw = typeof value === "string" ? value.split("=", 1)[0].trim() : "";
+  const key = raw.replace(/["']/g, "").replace(/\s*\.\s*/g, ".");
+  return { key, size, valid: typeof value === "string" && value.includes("=") && /^[A-Za-z_][A-Za-z0-9_.]*$/.test(key) };
+}
+
+export function validateAgentCliConfig(config = {}, type, label = "agent") {
+  const args = config.args === undefined ? [] : config.args;
+  const env = config.env === undefined ? {} : config.env;
+  if (!Array.isArray(args)) invalid(label, "args", "must be an array of strings");
+  for (let i = 0; i < args.length; i++) {
+    if (typeof args[i] !== "string" || args[i].includes("\0"))
+      invalid(label, `args[${i}]`, "must be a string without NUL");
+  }
+  if (!env || typeof env !== "object" || Array.isArray(env) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(env)))
+    invalid(label, "env", "must be a string-to-string object");
+  for (const [i, [key, value]] of Object.entries(env).entries()) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) invalid(label, `env entry[${i}]`, "has an invalid variable name");
+    if (/^CHORUS_/i.test(key)) invalid(label, `env entry[${i}]`, "cannot override managed CHORUS_* variables");
+    if (/^(CLAUDECODE|CLAUDE_CODE_ENTRYPOINT)$/i.test(key))
+      invalid(label, `env entry[${i}]`, "cannot override managed nested-Claude context variables");
+    if (typeof value !== "string" || value.includes("\0")) invalid(label, `env entry[${i}]`, "must have a string value without NUL");
+  }
+  const backend = canonicalType(type);
+  const controls = PROTECTED[backend];
+  const longs = new Set([...(controls?.long.split(" ") ?? []), "help", "version"]);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--" || args[i] === "-") invalid(label, `args[${i}]`, "cannot contain an argument terminator or stdin prompt marker");
+  }
+  for (let i = 0; i < args.length; i++) {
+    const tok = args[i];
+    const option = optionAt(backend, args, i);
+    if (controls && !tok.startsWith("-"))
+      invalid(label, `args[${i}]`, "cannot supply a positional prompt or ambiguous value; unknown options require inline --option=value syntax (if supported by the CLI)");
+    if ((longs.has((option?.flag ?? tok.split("=", 1)[0]).replace(/^--/, ""))) ||
+        (!option && /^-[^-]/.test(tok) && `${controls?.short ?? ""}hVv`.includes(tok[1])))
+      invalid(label, `args[${i}]`, "conflicts with managed backend controls; use the dedicated Chorus settings or explicit foreground passthrough");
+    if (backend === "codex") {
+      const c = codexConfigAt(args, i);
+      if (c) {
+        if (!c.valid || /^(mcp_servers|sandbox[^.]*|approval_policy|approvals_reviewer|cwd|permissions|developer_instructions|model_instructions_file|experimental_instructions_file|base_instructions)(\.|$)/.test(c.key))
+          invalid(label, `args[${i}]`, "has an invalid or managed Codex config key");
+      }
+    }
+    if (option?.missing) invalid(label, `args[${i}]`, "requires a value before managed launch arguments");
+    i += (option?.size ?? 1) - 1;
+  }
+  return { args: [...args], env: { ...env } };
+}
+
+// Windows child environments are case-insensitive, unlike an ordinary JS object
+// (including injected test envs). Match Node's sorted-key selection if an inherited
+// object contains duplicates; overlayAgentEnv removes collisions for overrides.
+export function getAgentEnv(env, name, platform = process.platform) {
+  if (platform !== "win32") return env[name];
+  const key = Object.keys(env).sort().find((key) => key.toUpperCase() === name.toUpperCase());
+  return key === undefined ? undefined : env[key];
+}
+
+export function overlayAgentEnv(base, overrides = {}, platform = process.platform) {
+  const result = { ...base };
+  if (platform === "win32") {
+    for (const key of Object.keys(result)) {
+      if (/^CHORUS_/i.test(key) && key !== key.toUpperCase()) {
+        result[key.toUpperCase()] = result[key];
+        delete result[key];
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (platform === "win32") {
+      for (const old of Object.keys(result)) if (old.toLowerCase() === key.toLowerCase()) delete result[old];
+    }
+    // Canonical PATH spelling also makes the existing binary resolvers consistent.
+    const name = platform === "win32" && key.toUpperCase() === "PATH" ? "PATH" : key;
+    Object.defineProperty(result, name, { value, enumerable: true, writable: true, configurable: true });
+  }
+  return result;
+}
+
+// Deliberately small registry. See docs/DAEMON.md for verified CLI sources/forms.
+const SINGLETONS = {
+  "claude-code": { "--model": "model", "--effort": "effort" },
+  codex: { "--model": "model", "-m": "model" },
+  kiro: { "--model": "model", "--effort": "effort" },
+  pi: { "--model": "model", "--thinking": "thinking", "--provider": "provider" },
+  opencode: { "--model": "model", "-m": "model" },
+  openclaw: { "--model": "model", "--thinking": "thinking" },
+};
+function singletonAt(type, args, i) {
+  if (type === "codex") {
+    const c = codexConfigAt(args, i);
+    if (c?.valid && ["model", "model_reasoning_effort"].includes(c.key)) return { key: c.key, size: c.size };
+  }
+  for (const [flag, key] of Object.entries(SINGLETONS[type] ?? {})) {
+    if (args[i] === flag) return { key, size: args[i + 1] === undefined || args[i + 1] === "--" ? 1 : 2 };
+    if (args[i].startsWith(`${flag}=`) || flag.length === 2 && args[i].startsWith(flag)) return { key, size: 1 };
+  }
+  return null;
+}
+// Only these command paths have a supported insertion scope. Walk known option
+// arities, never token-search: a value named "exec"/"resume" is not a command.
+const SUBCOMMANDS = {
+  codex: { exec: { resume: {} }, resume: {} },
+  kiro: { chat: {} },
+  openclaw: { agent: {} },
+};
+function foregroundScope(type, explicit) {
+  let commands = SUBCOMMANDS[type];
+  let start = 0;
+  if (!commands) return start;
+  for (let i = 0; i < explicit.length;) {
+    const token = explicit[i];
+    if (Object.hasOwn(commands, token)) {
+      start = ++i;
+      commands = commands[token];
+      if (!Object.keys(commands).length) break;
+      continue;
+    }
+    const option = optionAt(type, explicit, i);
+    if (option) {
+      if (option.missing) break;
+      i += option.size;
+    } else if (token.startsWith("--") && token.includes("=")) {
+      i++; // self-contained unknown option; no arity guess
+    } else break; // positional prompt/unknown command/ambiguous option
+  }
+  return start;
+}
+
+export function planAgentArgs(type, configured, explicit = []) {
+  type = canonicalType(type);
+  // Chorus analysis ALWAYS ends at the first bare --, even for backends that
+  // might consume it as an option value. Forward the original tokens unchanged.
+  const terminator = explicit.indexOf("--");
+  const scan = explicit.slice(0, terminator < 0 ? explicit.length : terminator);
+  const start = foregroundScope(type, scan);
+  const supplied = new Set();
+  for (let i = 0; i < scan.length; i++) {
+    const boundary = optionAt(type, scan, i);
+    // Unknown separated options may consume ANY following token. Do not infer
+    // overrides beyond this point; still forward the entire explicit argv.
+    if (!boundary && scan[i].startsWith("-") &&
+        !(scan[i].startsWith("--") && scan[i].includes("="))) break;
+    const option = singletonAt(type, scan, i);
+    // Local root/parent options do not override options of the selected child
+    // command. Codex --config/-c is global and applies across command scopes.
+    const globalConfig = type === "codex" && boundary?.flag === "--config";
+    if (option && (i >= start || globalConfig)) supplied.add(option.key);
+    i += (boundary?.size ?? 1) - 1;
+  }
+  const kept = [];
+  for (let i = 0; i < configured.length; i++) {
+    const boundary = optionAt(type, configured, i);
+    const option = singletonAt(type, configured, i);
+    const size = boundary?.size ?? 1;
+    if (!option || !supplied.has(option.key)) kept.push(...configured.slice(i, i + size));
+    i += size - 1;
+  }
+  return {
+    args: [...explicit.slice(0, start), ...kept, ...explicit.slice(start)],
+    configuredArgs: kept,
+  };
+}
+
+export function mergeAgentArgs(type, configured, explicit = []) {
+  return planAgentArgs(type, configured, explicit).args;
+}
+
+// cmd.exe parses even with shell:false. Until a fully tested cmd encoder exists,
+// only simple configured tokens are supported with .cmd/.bat shims. Native exe
+// and POSIX paths retain ALL literal tokens. Explicit foreground argv is unchanged.
+export function assertConfiguredShimArgs(binPath, args, platform = process.platform, label = "agent") {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(binPath)) return;
+  if (/["%!^&|<>()\r\n]/.test(binPath))
+    invalid(label, "executable path", "cannot be passed literally through a Windows command shim; use a native executable");
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i] || /[\s"'%!^&|<>()]/.test(args[i]))
+      invalid(label, `args[${i}]`, "cannot be passed literally through a Windows command shim; use a native executable");
+  }
+}

package/cli/agent-launcher.mjs

@@ -15,9 +15,11 @@
 // name/UUID and the resolved binary, nothing else.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
 import { statSync } from "node:fs";
 import { win32 as pathWin32, posix as pathPosix } from "node:path";
 import { resolveLaunchAgent } from "./credentials.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, planAgentArgs, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 
 /**
  * Launch agent-type → executable base name. Launch is a SUPERSET of daemon wake:
@@ -173,7 +175,7 @@ export function resolveBinaryPath(binName, deps = {}) {
   const isWin = platform === "win32";
   const p = isWin ? pathWin32 : pathPosix;
   const names = isWin ? [`${binName}.cmd`, `${binName}.exe`, binName] : [binName];
-  const pathVar = env.PATH || env.Path || "";
+  const pathVar = getAgentEnv(env, "PATH", platform) || env.Path || "";
   const dirs = pathVar.split(p.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -197,7 +199,7 @@ export function resolveSpawnCommand(binPath, args, platform = process.platform,
   const isWin = platform === "win32";
   const lower = binPath.toLowerCase();
   if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    const comspec = getAgentEnv(env, "COMSPEC", platform) || "cmd.exe";
     return { command: comspec, argv: ["/d", "/s", "/c", binPath, ...args] };
   }
   return { command: binPath, argv: args };
@@ -212,13 +214,20 @@ export function resolveSpawnCommand(binPath, args, platform = process.platform,
  * @param {NodeJS.ProcessEnv} [baseEnv]
  * @returns {NodeJS.ProcessEnv}
  */
-export function buildChildEnv(agent, baseEnv = process.env) {
-  const childEnv = { ...baseEnv };
+export function buildChildEnv(agent, baseEnv = process.env, platform = process.platform) {
+  const childEnv = overlayAgentEnv(baseEnv, agent.env, platform);
   if (agent.url) childEnv.CHORUS_URL = agent.url;
   if (agent.apiKey) childEnv.CHORUS_API_KEY = agent.apiKey;
   const profile = agent.agentUuid || agent.agentName;
   if (profile) childEnv.CHORUS_AGENT_PROFILE = profile;
-  delete childEnv.CHORUS_DAEMON_HEADLESS;
+  for (const key of Object.keys(childEnv)) {
+    if (key.toUpperCase() === "CHORUS_DAEMON_HEADLESS") delete childEnv[key];
+  }
+  if (agent.agentType === "claude-code" || agent.agentType === "claude") {
+    for (const key of Object.keys(childEnv)) {
+      if (["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"].includes(key.toUpperCase())) delete childEnv[key];
+    }
+  }
   return childEnv;
 }
 
@@ -233,8 +242,11 @@ USAGE
 
 Launches the agent's binary in the FOREGROUND with this agent's Chorus connection
 injected into the child (CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE).
-Everything after \`--\` is passed to the agent verbatim — the agent's full flag
-surface is available and is never inspected by chorus.
+Everything after \`--\` is passed to the agent verbatim. Recognized explicit model/
+reasoning options suppress configured equivalents in the selected command scope.
+Configured args precede explicit options after known commands (Codex exec, exec
+resume, resume; Kiro chat; OpenClaw agent), otherwise they go first. Unknown
+command grammars are not inferred. Analysis stops at the first bare \`--\`.
 
 FLAGS
   --name <name|uuid>   Which configured agent to launch (default: the only one).
@@ -295,8 +307,18 @@ export async function runAgentLaunch(argv = [], opts = {}) {
     return 1;
   }
 
-  // 3. Locate the binary on PATH.
-  const binPath = resolveBinaryPath(typeRes.binary, { env, platform, isFile: opts.isFile });
+  // Validate before binary discovery or spawn, against the effective --type.
+  let config;
+  try {
+    config = validateAgentCliConfig(agent, typeRes.type, agent.label);
+  } catch (e) {
+    err.write(`error: ${e.message}\n`);
+    return 1;
+  }
+  const childEnv = buildChildEnv({ ...agent, agentType: typeRes.type, env: config.env }, env, platform);
+
+  // 3. Locate the binary using this profile's effective PATH.
+  const binPath = resolveBinaryPath(typeRes.binary, { env: childEnv, platform, isFile: opts.isFile });
   if (!binPath) {
     err.write(
       `error: could not find the \`${typeRes.binary}\` executable on PATH ` +
@@ -305,9 +327,15 @@ export async function runAgentLaunch(argv = [], opts = {}) {
     return 1;
   }
 
-  // 4. Build the child env and the spawn command.
-  const childEnv = buildChildEnv(agent, env);
-  const { command, argv: spawnArgv } = resolveSpawnCommand(binPath, parsed.passthrough, platform, env);
+  // 4. Filter only configured recognized duplicates; explicit argv stays untouched.
+  const { args, configuredArgs } = planAgentArgs(typeRes.type, config.args, parsed.passthrough);
+  try {
+    assertConfiguredShimArgs(binPath, configuredArgs, platform, agent.label);
+  } catch (e) {
+    err.write(`error: ${e.message}\n`);
+    return 1;
+  }
+  const { command, argv: spawnArgv } = resolveSpawnCommand(binPath, args, platform, childEnv);
 
   // Diagnostic — agent name/uuid + binary ONLY. Never the key or url userinfo.
   out.write(`Launching ${agent.label} (${agent.agentUuid ?? "no uuid"}) → ${typeRes.binary}\n`);
@@ -321,13 +349,13 @@ export async function runAgentLaunch(argv = [], opts = {}) {
         env: childEnv,
         shell: false,
       });
-    } catch (e) {
-      err.write(`error: failed to launch ${typeRes.binary}: ${e.message}\n`);
+    } catch (error) {
+      err.write(`error: failed to launch ${typeRes.binary}: ${safeSpawnError(error)}\n`);
       resolve(1);
       return;
     }
-    child.on("error", (e) => {
-      err.write(`error: ${typeRes.binary} failed to start: ${e.message}\n`);
+    child.on("error", (error) => {
+      err.write(`error: ${typeRes.binary} failed to start: ${safeSpawnError(error)}\n`);
       resolve(1);
     });
     child.on("close", (code, signal) => {

package/cli/child-exit.mjs

@@ -0,0 +1,77 @@
+// cli/child-exit.mjs
+// One shared settlement path for every spawner's child process, so the five
+// backends (pi / claude / codex / kiro / dsh) cannot drift on "when is the wake
+// over?".
+//
+// WHY THIS EXISTS — `close` is not the same event as "the agent finished".
+// Node emits `exit` when the child process itself is reaped, but `close` only
+// once every stdio stream the child was given has been closed. A child that
+// leaves a DETACHED DESCENDANT behind (a backgrounded server, a `nohup`'d
+// helper) hands that descendant the SAME inherited pipes, so the pipes stay
+// open after the child is long gone and `close` may never fire. A spawner that
+// waits only for `close` therefore keeps reporting a finished wake as still
+// `running` — the phantom `running` turn. Settling on `exit` fixes that.
+//
+// !!! THE GRACE IS NOT A WAKE TIMEOUT AND NOT A WATCHDOG !!!
+// `stdioGraceMs` only starts counting AFTER the child process has ALREADY
+// EXITED, and it bounds one thing only: how long we wait for that dead
+// process's pipes to drain so a final stdout chunk is still parsed. It places
+// no limit whatsoever on how long an agent may run — a wake that runs for
+// hours is never interrupted, cancelled or "timed out" by this module. No
+// wake-duration limit is introduced anywhere here; do not repurpose this timer
+// into one.
+
+/** Grace for an already-exited process's pipes to drain. NOT a wake timeout. */
+export const DEFAULT_STDIO_GRACE_MS = 2000;
+
+/**
+ * Resolve once with the child's exit code as soon as the process is KNOWN to be gone.
+ *
+ *  • `close` first  → resolve immediately (today's behaviour, zero regression).
+ *  • `exit` first   → wait up to `stdioGraceMs` for `close` (so a last stdout chunk
+ *                     is still parsed), then resolve with the exit code anyway.
+ *
+ * Settles exactly once and NEVER rejects. The grace timer is `unref`'d so it can
+ * never hold the daemon's event loop open.
+ *
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {{ stdioGraceMs?: number, logger?: { warn?: (msg: string) => void }, label?: string }} [options]
+ * @returns {Promise<number | null>} the exit code (`null` when the child was signalled)
+ */
+export function awaitChildSettled(child, options = {}) {
+  const { stdioGraceMs = DEFAULT_STDIO_GRACE_MS, logger, label = "child" } = options;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+
+    const settle = (code) => {
+      if (settled) return;
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      resolve(code ?? null);
+    };
+
+    child.on?.("close", (code) => settle(code));
+
+    child.on?.("exit", (code) => {
+      if (settled || timer) return;
+      // The process is gone; give its (possibly descendant-held) pipes a bounded
+      // moment to drain, then settle regardless. See the header: not a timeout.
+      timer = setTimeout(() => {
+        timer = null;
+        if (settled) return;
+        logger?.warn?.(
+          `[Chorus] ${label} exited (code ${code ?? null}) but stdio stayed open for ` +
+            `${stdioGraceMs}ms; settling on exit`
+        );
+        settle(code);
+      }, stdioGraceMs);
+      // Never keep the daemon's event loop alive for a dead process's pipes.
+      timer?.unref?.();
+    });
+  });
+}

package/cli/claude-spawner.mjs

@@ -23,9 +23,12 @@
 // carried per-turn by the wake-prompt preamble in prompts.mjs, not at the system level.
 
 import { spawn } from "node:child_process";
+import { safeSpawnError } from "./launch-diagnostics.mjs";
+import { validateAgentCliConfig, overlayAgentEnv, getAgentEnv, assertConfiguredShimArgs } from "./agent-cli-config.mjs";
 import { existsSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { win32 as pathWin32, posix as pathPosix, join as pathJoin } from "node:path";
+import { awaitChildSettled } from "./child-exit.mjs";
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
@@ -102,7 +105,7 @@ export function escapeCwd(cwd, platform = process.platform) {
 export function transcriptPath(sessionId, cwd, deps = {}) {
   const env = deps.env ?? process.env;
   const platform = deps.platform ?? process.platform;
-  const configDir = env.CLAUDE_CONFIG_DIR || pathJoin(deps.home ?? homedir(), ".claude");
+  const configDir = getAgentEnv(env, "CLAUDE_CONFIG_DIR", platform) || pathJoin(deps.home ?? getAgentEnv(env, "HOME", platform) ?? getAgentEnv(env, "USERPROFILE", platform) ?? homedir(), ".claude");
   return pathJoin(configDir, "projects", escapeCwd(cwd, platform), `${sessionId}.jsonl`);
 }
 
@@ -146,8 +149,9 @@ export function resolveClaudePath(deps = {}) {
     });
 
   // An explicit override always wins (set by the daemon if the user configured it).
-  if (env.CHORUS_CLAUDE_PATH && isFile(env.CHORUS_CLAUDE_PATH)) {
-    return env.CHORUS_CLAUDE_PATH;
+  const override = getAgentEnv(env, "CHORUS_CLAUDE_PATH", platform);
+  if (override && isFile(override)) {
+    return override;
   }
 
   // Use platform-correct path semantics so the resolver is testable for
@@ -155,7 +159,7 @@ export function resolveClaudePath(deps = {}) {
   const isWin = platform === "win32";
   const p = isWin ? pathWin32 : pathPosix;
   const names = isWin ? ["claude.cmd", "claude.exe", "claude"] : ["claude"];
-  const pathVar = env.PATH || env.Path || "";
+  const pathVar = getAgentEnv(env, "PATH", platform) || env.Path || "";
   const dirs = pathVar.split(p.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -228,7 +232,7 @@ export function resolveSpawnCommand(claudePath, args, platform = process.platfor
   const isWin = platform === "win32";
   const lower = claudePath.toLowerCase();
   if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
-    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    const comspec = getAgentEnv(env, "COMSPEC", platform) || "cmd.exe";
     // /d skip AutoRun, /s treat everything after /c literally, /c run then exit.
     return { command: comspec, argv: ["/d", "/s", "/c", claudePath, ...args] };
   }
@@ -289,6 +293,8 @@ export class ClaudeSpawner {
     // can group-kill the tree; Windows does not. Injectable so a POSIX test host
     // can exercise the Windows branch and vice versa.
     this.platform = opts.platform ?? process.platform;
+    this.cliConfig = validateAgentCliConfig(opts.cliConfig, "claude-code", opts.label);
+    this.env = overlayAgentEnv(opts.env ?? process.env, this.cliConfig.env, this.platform);
   }
 
   /**
@@ -330,18 +336,19 @@ export class ClaudeSpawner {
       return { sessionId: typeof id === "string" ? id : "", backendSessionId: null, exitCode: null, isNew: Boolean(isNew) };
     }
 
-    const claudePath = this.claudePath ?? resolveClaudePath();
+    const claudePath = this.claudePath ?? resolveClaudePath({ env: this.env, platform: this.platform });
     if (!claudePath) {
       // No crash — surface visibly and resolve with a failure result.
       this.logger.error("[Chorus] cannot locate the `claude` executable on PATH; skipping wake");
       return { sessionId: id, backendSessionId: null, exitCode: null, isNew };
     }
 
-    const args = buildArgs({ sessionId: id, isNew, mcpConfigPath, permissionMode: this.permissionMode });
+    assertConfiguredShimArgs(claudePath, this.cliConfig.args, this.platform);
+    const args = [...buildArgs({ sessionId: id, isNew, mcpConfigPath, permissionMode: this.permissionMode }), ...this.cliConfig.args];
     // On Windows, a .cmd/.bat shim must be run via cmd.exe /c (CreateProcess
     // can't exec a script directly). resolveSpawnCommand keeps shell:false and
     // passes argv as an array — no shell injection surface either way.
-    const { command, argv } = resolveSpawnCommand(claudePath, args);
+    const { command, argv } = resolveSpawnCommand(claudePath, args, this.platform, this.env);
 
     // POSIX: spawn `detached: true` so the child becomes a PROCESS GROUP LEADER
     // (its pgid === its pid). The interrupt path then signals the whole group via
@@ -353,7 +360,10 @@ export class ClaudeSpawner {
     // stream and observe the exit. On Windows `detached` is NOT used: taskkill /T
     // walks the tree by pid, and detached there only spawns a new console window.
     const detached = (this.platform ?? process.platform) !== "win32";
-    const childEnv = { ...process.env, CHORUS_DAEMON_HEADLESS: "1" };
+    const childEnv = { ...this.env, CHORUS_DAEMON_HEADLESS: "1" };
+    for (const key of Object.keys(childEnv)) {
+      if (["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"].includes(key.toUpperCase())) delete childEnv[key];
+    }
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
@@ -379,8 +389,8 @@ export class ClaudeSpawner {
           detached,
           windowsHide: true,
         });
-      } catch (err) {
-        this.logger.error(`[Chorus] failed to spawn claude: ${err}`);
+      } catch (error) {
+        this.logger.error(`[Chorus] failed to spawn claude: ${safeSpawnError(error)}`);
         resolve({ sessionId: id, backendSessionId: null, exitCode: null, isNew });
         return;
       }
@@ -429,16 +439,18 @@ export class ClaudeSpawner {
         if (text) this.logger.warn(`[Chorus] claude stderr: ${text}`);
       });
 
-      child.on("error", (err) => {
+      child.on("error", (error) => {
         // e.g. ENOENT if the resolved path vanished — log, don't throw.
-        this.logger.error(`[Chorus] claude process error: ${err}`);
+        this.logger.error(`[Chorus] claude process error: ${safeSpawnError(error)}`);
         // backendSessionId is the `--resume` anchor (`id`), NOT observedSessionId:
         // a fork-on-resume claude can emit a new stream session_id, but the daemon
         // resumes and files the transcript under `id`, so `id` is the resumable value.
         resolve({ sessionId: observedSessionId, backendSessionId: id, exitCode: null, isNew });
       });
 
-      child.on("close", (code) => {
+      // Settle on process exit, not only on stdio close: a detached descendant can
+      // inherit the pipes and keep `close` from ever firing (see cli/child-exit.mjs).
+      awaitChildSettled(child, { logger: this.logger, label: "claude" }).then((code) => {
         if (code !== 0) {
           this.logger.warn(`[Chorus] claude exited with code ${code}`);
         }