forgedock 1.1.11 → 1.3.0

package/bin/runner.mjs

@@ -16,6 +16,7 @@
  *   listCommands(commandsDir)               → string[]      (available command names)
  *   loadCommandSpec(commandsDir, name)      → {path,name,content}
  *   buildSystemPrompt(spec, opts)           → string
+ *   buildCliSystemPrompt(spec)              → string        (cli-backend system prompt)
  *   buildUserMessage(name, args)            → string
  *   TOOL_DEFINITIONS                        → object[]      (Anthropic tool schemas)
  *   truncateToolResult(content)             → string        (cap + truncation marker)
@@ -42,11 +43,15 @@ import {
   writeFileSync,
   readdirSync,
   mkdirSync,
+  mkdtempSync,
+  rmSync,
   realpathSync,
 } from "fs";
 import { join, dirname, basename, relative, isAbsolute } from "path";
+import os from "os";
 import { execSync, spawnSync } from "child_process";
 import { parseForgeYaml, resolveModelAlias } from "./forge-utils.mjs";
+import { DEFAULT_SPAWN_MAX_BUFFER_BYTES } from "./cli-spawn-shared.mjs";
 
 const DEFAULT_MODEL = "claude-sonnet-5";
 const DEFAULT_MAX_ITERATIONS = 50;
@@ -55,6 +60,94 @@ const DEFAULT_MAX_TOKENS = 16384;
 // generous enough for CI steps (git clones, test suites) while bounding
 // the worst-case hang to 5 minutes. Override via FORGEDOCK_BASH_TIMEOUT (ms).
 const DEFAULT_BASH_TIMEOUT_MS = 5 * 60 * 1000;
+// Default wall-clock limit for a single `claude --print` CLI-backend
+// invocation (issue #2003). This bounds an entire command run (the CLI's own
+// internal tool-use loop), not one bash step, so it is deliberately larger
+// than DEFAULT_BASH_TIMEOUT_MS. Override via FORGEDOCK_CLI_TIMEOUT_MS (ms).
+const DEFAULT_CLI_TIMEOUT_MS = 15 * 60 * 1000;
+// Short bound for the `claude --version` presence probe used by backend
+// auto-detection — this must never make --dry-run (or a live run) hang, so
+// it is far shorter than DEFAULT_CLI_TIMEOUT_MS. Mirrors the timeout already
+// used by the `claude --version` doctor check in bin/forgedock.mjs.
+const CLI_PROBE_TIMEOUT_MS = 5000;
+/**
+ * Wraps a Set in a Proxy that blocks add()/delete()/clear(), so the
+ * returned collection is genuinely read-only — not just Object.frozen.
+ *
+ * Note: `Object.freeze(new Set(...))` does NOT prevent mutation. Set's
+ * mutator methods (add/delete/clear) operate on an internal [[SetData]]
+ * slot, not on the object's own enumerable properties, so Object.freeze()
+ * — which only locks down property descriptors — has no effect on them;
+ * `.add()` on a frozen Set still silently succeeds. A Proxy trapping the
+ * mutator method names is the only reliable way to make a Set read-only.
+ *
+ * Two known, intentionally-accepted deviations from a plain Set (neither
+ * is exercised by any current caller — grep confirms only `.has()` and
+ * spread/iteration are used):
+ *   - `structuredClone()` throws on a Proxy (no native [[SetData]] slot to
+ *     brand-check), where it would succeed on a plain Set.
+ *   - Without the `constructor` passthrough below, `.constructor` would
+ *     resolve to a bound wrapper rather than `Set` itself. Special-cased
+ *     here so `VALID_BACKENDS.constructor === Set` still holds.
+ */
+function readOnlySet(values) {
+  const target = new Set(values);
+  return new Proxy(target, {
+    get(t, prop, receiver) {
+      if (prop === "add" || prop === "delete" || prop === "clear") {
+        return () => {
+          throw new TypeError(
+            "VALID_BACKENDS is read-only and must not be mutated.",
+          );
+        };
+      }
+      // Return the real Set constructor, not a bound wrapper — keeps
+      // `VALID_BACKENDS.constructor === Set` true, matching a plain Set.
+      if (prop === "constructor") return Set;
+      const value = Reflect.get(t, prop, t);
+      return typeof value === "function" ? value.bind(t) : value;
+    },
+  });
+}
+
+/**
+ * Valid values for the `backend` option / --backend flag / FORGEDOCK_BACKEND
+ * env. Exported (issue #2013) so bin/forgedock.mjs's CLI-layer `--backend`
+ * flag validation can reuse this exact Set instead of maintaining its own
+ * independently-hardcoded copy — keeps both layers' "Must be one of: ..."
+ * error messages structurally unable to drift apart.
+ *
+ * Read-only (issue #2075): every importer (bin/engine.mjs, bin/forgedock.mjs)
+ * holds a reference to this exact instance, not a copy. Without the
+ * read-only wrapper above, any consumer calling .add()/.delete()/.clear()
+ * on it would silently change the accepted backend values — and the "Must
+ * be one of: ..." error-message wording — for every other consumer
+ * simultaneously. Treat it as immutable; mutation attempts throw.
+ */
+export const VALID_BACKENDS = readOnlySet(["cli", "api", "auto"]);
+// Per-process memoization for isClaudeCliAvailable(), keyed by `cwd` (issue
+// #2011). `runCommand()` calls resolveBackend() — and therefore, for the
+// default "auto" backend, isClaudeCliAvailable() — unconditionally on every
+// invocation, including every `--dry-run`. Without caching, a process that
+// calls runCommand() repeatedly (e.g. bin/batch-runner.mjs driving many
+// commands, or an orchestration loop) re-spawns `claude --version` on every
+// single call.
+//
+// Bounded on two axes (issues #2057, #2058 — review findings on PR #2056):
+//   1. TTL (`CLI_AVAILABILITY_CACHE_TTL_MS`): an entry older than the TTL is
+//      treated as absent and re-probed, so a `claude` install/uninstall that
+//      happens mid-run of a long-lived process (e.g. an orchestration loop)
+//      is picked up within one TTL window instead of staying stale for the
+//      rest of the process's lifetime.
+//   2. Max size (`CLI_AVAILABILITY_CACHE_MAX_SIZE`): entries beyond the cap
+//      evict the oldest (insertion-order, via `Map`'s iteration order and a
+//      delete+re-set on refresh) so a process that probes an unbounded
+//      number of distinct `cwd` values cannot grow this cache without limit.
+// Each entry stores `{ available, cachedAt }` instead of a bare boolean so
+// `isClaudeCliAvailable()` can evaluate the TTL.
+const CLI_AVAILABILITY_CACHE_TTL_MS = 60_000;
+const CLI_AVAILABILITY_CACHE_MAX_SIZE = 100;
+const cliAvailabilityCache = new Map();
 // Cap tool-result payloads so a large file read or verbose command does not
 // blow the context window in a single turn.
 const MAX_TOOL_RESULT_CHARS = 100_000;
@@ -106,6 +199,398 @@ export function resolveConfiguredDefaultModel(cwd) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Backend selection (issue #2003) — CLI vs API execution backend
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe whether the Claude Code CLI (`claude`) is present and responds on
+ * this machine, so `forgedock run` can drive it directly instead of
+ * requiring a separate, billable ANTHROPIC_API_KEY.
+ *
+ * Deliberately uses `execSync("claude --version", ...)` — a single command
+ * *string* executed through a shell — rather than
+ * `execFileSync("claude", [...])`. On Windows, `claude` is installed as a
+ * `claude.cmd` shim; `execFileSync` does not resolve `.cmd` shims and throws
+ * ENOENT even though the CLI is genuinely installed and on PATH (this exact
+ * regression previously made an unrelated skill-based enrichment backend
+ * silently dead on Windows — see issue #382). `execSync` always runs its
+ * command through a shell, which resolves PATHEXT-registered `.cmd`/`.bat`
+ * shims correctly on Windows and behaves identically on POSIX. This mirrors
+ * the pre-existing `claude --version` doctor check in bin/forgedock.mjs.
+ *
+ * Bounded by CLI_PROBE_TIMEOUT_MS so a hung or misbehaving `claude` binary
+ * can never make backend resolution (and therefore --dry-run, or the start
+ * of a live run) hang indefinitely. Any failure — not installed, not on
+ * PATH, times out, non-zero exit — is treated as "not available" and never
+ * throws; the caller (resolveBackend) falls back to the API backend.
+ *
+ * Memoized per `cwd` for up to `CLI_AVAILABILITY_CACHE_TTL_MS` (see
+ * `cliAvailabilityCache` above, issues #2011, #2057, #2058) — the first call
+ * for a given `cwd` pays the probe cost; every subsequent call for that same
+ * `cwd` within the TTL window returns the cached result instantly, with no
+ * new child process spawned. Once the TTL elapses the entry is treated as
+ * absent and re-probed, and the cache never grows past
+ * `CLI_AVAILABILITY_CACHE_MAX_SIZE` distinct `cwd` entries (oldest evicted
+ * first).
+ *
+ * @param {string} [cwd] - Working directory for the probe (default cwd).
+ * @param {object} [opts]
+ * @param {typeof execSync} [opts.execImpl] - Test seam only — production
+ *   callers must never override this; built-in ESM modules like
+ *   `node:child_process` export non-configurable bindings that `node:test`'s
+ *   `mock.method` cannot redefine, so tests inject a stub here directly
+ *   instead. Mirrors the existing `bin` test-seam parameter on
+ *   `runCliBackend()`.
+ * @returns {boolean}
+ */
+export function isClaudeCliAvailable(cwd = process.cwd(), { execImpl = execSync } = {}) {
+  const cached = cliAvailabilityCache.get(cwd);
+  if (cached && Date.now() - cached.cachedAt < CLI_AVAILABILITY_CACHE_TTL_MS) {
+    return cached.available;
+  }
+  let available;
+  try {
+    execImpl("claude --version", {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+      timeout: CLI_PROBE_TIMEOUT_MS,
+    });
+    available = true;
+  } catch {
+    available = false;
+  }
+  // Re-inserting an existing key moves it to the end of Map's iteration
+  // order (delete+set), so eviction below always drops the true oldest
+  // entry — whether "oldest" means "never refreshed" or "not refreshed in
+  // the longest time."
+  cliAvailabilityCache.delete(cwd);
+  cliAvailabilityCache.set(cwd, { available, cachedAt: Date.now() });
+  if (cliAvailabilityCache.size > CLI_AVAILABILITY_CACHE_MAX_SIZE) {
+    const oldestKey = cliAvailabilityCache.keys().next().value;
+    cliAvailabilityCache.delete(oldestKey);
+  }
+  return available;
+}
+
+/**
+ * Shared backend-resolution primitive (issue #2026) used by both
+ * `resolveBackend()` (below, `forgedock run`'s engine ladder — issue #2003)
+ * and `resolveEnrichBackend()` (bin/init-enrich.mjs's init-enrichment
+ * ladder — issue #2004). Both ladders share the exact same two steps — an
+ * explicit override wins outright, otherwise probe the local Claude Code
+ * CLI and prefer it when present — but diverge on (a) which override
+ * values are valid and whether an invalid one throws or is silently
+ * ignored, and (b) what to return when the CLI probe fails (`resolveBackend`
+ * always falls back to `"api"`; `resolveEnrichBackend` falls back to `"api"`
+ * only if `ANTHROPIC_API_KEY` is set, else `"none"`). Rather than force
+ * those into one shape, this shared helper implements exactly the common
+ * two steps and defers to a `cliFallback` callback for the diverging tail,
+ * and defers override *validation* (throw vs. fall-through) entirely to
+ * the caller — this function only performs a membership check, it never
+ * throws. This removes the duplicated CLI-probe-and-branch logic while
+ * preserving each caller's distinct, already-shipped behavior byte-for-byte.
+ *
+ * @param {object} opts
+ * @param {string} [opts.override] - Pre-validated override value. Returned
+ *   as-is when it is a member of `validOverrides`; otherwise ignored (the
+ *   caller is responsible for deciding whether an unrecognized value should
+ *   throw or fall through — this helper never throws).
+ * @param {Set<string>} opts.validOverrides - The set of override values this
+ *   caller accepts outright.
+ * @param {string} [opts.cwd] - Working directory for the CLI probe.
+ * @param {Function} [opts.isCliAvailableFn] - Injectable CLI-presence probe.
+ *   Defaults to `isClaudeCliAvailable` (which is itself memoized per `cwd` —
+ *   issue #2011). Callers MUST pass this through rather than reimplementing
+ *   probing, to preserve that cache.
+ * @param {Function} opts.cliFallback - Called (no args) when no valid
+ *   override was given AND the CLI probe failed. Must return the caller's
+ *   fallback backend value (e.g. `"api"`, or `"api"|"none"` depending on an
+ *   API key check).
+ * @returns {string} The resolved backend value.
+ */
+export function resolveBackendLadder({
+  override,
+  validOverrides,
+  cwd = process.cwd(),
+  isCliAvailableFn = isClaudeCliAvailable,
+  cliFallback,
+}) {
+  if (override !== undefined && validOverrides.has(override)) return override;
+  if (isCliAvailableFn(cwd)) return "cli";
+  return cliFallback();
+}
+
+/**
+ * Resolve which execution backend `runCommand()` should use.
+ *
+ * Ladder (issue #2003):
+ *   1. An explicit `"cli"` or `"api"` request always wins outright — no
+ *      probing, no fallback. This is what `--backend cli|api` and
+ *      `FORGEDOCK_BACKEND=cli|api` produce.
+ *   2. `"auto"` (the default) probes `isClaudeCliAvailable()`: prefers the
+ *      CLI backend when a working `claude` install is detected (reuses
+ *      whatever credentials the CLI already has — Pro/Max OAuth or a
+ *      CLI-managed key — with no ANTHROPIC_API_KEY required), otherwise
+ *      falls back to the API backend unchanged (existing behavior for every
+ *      caller that never opts in to this feature).
+ *
+ * Delegates its shared "override-or-probe-CLI" shape to
+ * `resolveBackendLadder()` (issue #2026) — this function retains its own
+ * `VALID_BACKENDS` throw-on-invalid check (NOT shared; see that helper's
+ * doc comment) and its own no-API-key-check fallback (always `"api"`,
+ * unconditionally — the API key itself is validated lazily downstream, only
+ * if/when the api backend is actually selected).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.requested] - "cli" | "api" | "auto" (default "auto").
+ * @param {string} [opts.cwd]       - Working directory for the CLI probe.
+ * @returns {"cli"|"api"}
+ */
+export function resolveBackend({ requested = "auto", cwd = process.cwd() } = {}) {
+  if (!VALID_BACKENDS.has(requested)) {
+    throw new Error(
+      `Invalid backend "${requested}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`,
+    );
+  }
+  return resolveBackendLadder({
+    override: requested === "auto" ? undefined : requested,
+    validOverrides: new Set(["cli", "api"]),
+    cwd,
+    cliFallback: () => "api",
+  });
+}
+
+/**
+ * Run a command via the local Claude Code CLI instead of the Anthropic SDK
+ * (issue #2003's "cli" backend). Shells out to headless print mode
+ * (`claude --print "<message>" --dangerously-skip-permissions`), reusing
+ * whatever the CLI is already authenticated with — no ANTHROPIC_API_KEY is
+ * read or required anywhere on this path.
+ *
+ * SECURITY — argv array, NEVER `shell: true`: `userMessage` is built from
+ * `buildUserMessage(commandName, args)`, and `args` originates from
+ * user-supplied CLI arguments to `forgedock run <command> <args...>` — it is
+ * untrusted input from this function's point of view. `spawnSync("claude",
+ * [...argv], { shell: false (default) })` passes each argument as a discrete,
+ * unparsed argv element: the target process receives `userMessage` as one
+ * literal string, with no shell ever tokenizing or expanding it, so shell
+ * metacharacters (`$(...)`, backticks, `;`, `&&`, `|`, `!`) inside it cannot
+ * trigger command injection. An earlier version of this function built a
+ * shell command *string* (`claude --print "<quoted message>" ...`) run via
+ * `spawnSync(command, { shell: true })` with hand-rolled quoting
+ * (backslash/double-quote escaping only) — that does NOT neutralize
+ * `$(...)`/backtick/`!` expansion inside POSIX double quotes and was an
+ * exploitable injection (verified: a crafted `userMessage` could execute
+ * arbitrary shell commands with this process's privileges). Do not
+ * reintroduce `shell: true` or string-command interpolation here.
+ *
+ * Windows `.cmd` shim resolution works WITHOUT `shell: true`: Node's
+ * spawn/spawnSync resolve a bare `"claude"` command via PATH+PATHEXT and
+ * safely re-invoke through cmd.exe internally when the resolved target is a
+ * `.cmd`/`.bat` file, using a properly escaped mechanism, and argv elements
+ * are never parsed as shell syntax (verified empirically on Windows: a
+ * malicious-looking argv element is delivered to the child process
+ * byte-for-byte, not executed). This is the correct fix for the
+ * `execFileSync("claude", [...])` ENOENT-on-Windows regression from issue
+ * #382 — that regression was about USING execFileSync with an unresolved
+ * bare command name in an older/incompatible way, not about needing
+ * `shell: true`; spawnSync's own PATH/PATHEXT resolution (unlike
+ * execFileSync's, in the failure mode #382 hit) handles the `.cmd` shim
+ * transparently here.
+ *
+ * `--dangerously-skip-permissions` mirrors the established headless-CI
+ * invocation pattern already documented in docs/CI.md and
+ * templates/workflows/forgedock-review.yml: without it, the CLI would block
+ * on an interactive permission prompt that a headless caller can never
+ * answer, hanging until FORGEDOCK_CLI_TIMEOUT_MS/DEFAULT_CLI_TIMEOUT_MS
+ * kills it.
+ *
+ * SYSTEM PROMPT / COMMAND SPEC DELIVERY (issue #2019): `systemPrompt` (built
+ * by `buildCliSystemPrompt(spec)` — see below) is written to a private
+ * temp file and forwarded via `--append-system-prompt-file <path>`, NOT
+ * passed inline as a `--system-prompt`/`--append-system-prompt` argv string.
+ * Two reasons this matters:
+ *   1. Size: a command spec like `commands/work-on.md` is 100+ KB, and the
+ *      full `commands/*.md` corpus is over 1MB. Windows' CreateProcess has a
+ *      ~32K character command-line limit; spawnSync here uses `shell: false`
+ *      so it hits that OS-level argv limit directly. A file path is always
+ *      short regardless of spec size.
+ *   2. Semantics: `--append-system-prompt-file` *appends* to the CLI's own
+ *      default system prompt (tool descriptions, environment info, etc.),
+ *      matching how a real `/work-on` slash-command invocation inside Claude
+ *      Code behaves — the ForgeDock spec augments the CLI's native
+ *      capabilities rather than replacing them. `--system-prompt-file` would
+ *      instead *replace* the CLI's default prompt entirely, which would
+ *      strip the CLI of its own operating instructions.
+ * The temp file lives in a per-call `mkdtempSync` directory and is always
+ * removed in a `finally` block, covering the timeout/spawn-error/non-zero-exit
+ * paths as well as the success path.
+ *
+ * Model selection is intentionally NOT forwarded to the CLI in this first
+ * increment — the CLI backend uses whatever model the `claude` CLI itself is
+ * configured for. `opts.model`/FORGEDOCK_MODEL only affects the API backend.
+ * Likewise, structured token usage is not available the same way the
+ * Anthropic SDK exposes it; `usage` is reported as `null` (an already
+ * fully-supported value throughout renderSummaryCard/renderDryRun).
+ *
+ * @param {object} opts
+ * @param {{path: string, name: string, content: string}} opts.spec
+ * @param {string} opts.userMessage
+ * @param {string} [opts.systemPrompt] - CLI-appropriate system prompt (see
+ *   `buildCliSystemPrompt`), forwarded via `--append-system-prompt-file`.
+ *   Omitted/empty is tolerated (no flag is added) so existing callers that
+ *   have not been updated yet do not break, but production callers should
+ *   always supply it — see issue #2019.
+ * @param {string[]} [opts.args]
+ * @param {string} opts.cwd
+ * @param {{log: Function, error?: Function}} [opts.logger]
+ * @param {string} [opts.bin] - Executable to invoke (default "claude"). Test
+ *   seam only — production callers must never override this; it exists so
+ *   tests can point at a controlled fake binary instead of either invoking
+ *   the real `claude` CLI (slow, non-deterministic, real side effects) or
+ *   fighting platform-specific PATH-resolution semantics to shim "claude"
+ *   itself (Windows resolves a bare executable name via the *calling*
+ *   process's search path at the OS level, which is not reliably
+ *   overridable per-call from within the same process).
+ * @param {Function} [opts.spawnFn] - Injectable replacement for
+ *   `child_process.spawnSync` (default `spawnSync`). Test seam only —
+ *   production callers must never override this. Mirrors the identical
+ *   `spawnFn` seam on `bin/init-enrich-cli.mjs`'s `enrich()` (issue #2033):
+ *   both functions spawn the local `claude` CLI in headless print mode, so
+ *   sharing the same seam shape lets tests exercise both with equivalent
+ *   fixtures and makes future divergence between the two easier to catch.
+ *   This is additive to the existing `bin` override seam above — tests may
+ *   still use a real fake-binary-on-disk + real `spawnSync` (the original
+ *   seam), or fully mock the call via `spawnFn` (no fake binary needed).
+ * @returns {{status: string, command: string, iterations: number, stopReason: string, usage: null, model: string, backend: "cli"}}
+ */
+export function runCliBackend({
+  spec,
+  userMessage,
+  systemPrompt = "",
+  args = [],
+  cwd,
+  logger = console,
+  bin = "claude",
+  spawnFn = spawnSync,
+}) {
+  const rawTimeout = parseInt(process.env.FORGEDOCK_CLI_TIMEOUT_MS, 10);
+  const timeoutMs =
+    Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : DEFAULT_CLI_TIMEOUT_MS;
+
+  // Write the system prompt (command spec + framing) to a private temp file
+  // rather than passing it inline as an argv string — see the SYSTEM PROMPT
+  // block comment above for why. The directory is created fresh per call and
+  // always removed in `finally`, regardless of how spawnSync exits below.
+  //
+  // `tmpDir` is declared here (outside `try`) so `finally` below can see it,
+  // but the `mkdtempSync`/`writeFileSync` calls themselves now run *inside*
+  // the `try` block (issue #2061 — review finding on PR #2060) rather than
+  // before it: if either call throws (disk full, EACCES on a locked-down
+  // temp dir, etc.), that throw must still be covered by the same `finally`
+  // cleanup path, not bypass it. `tmpDir` is assigned immediately after
+  // `mkdtempSync` succeeds — before `writeFileSync` runs — so a failure in
+  // `writeFileSync` still leaves `tmpDir` set and the already-created
+  // directory gets cleaned up.
+  let tmpDir = null;
+  let cliArgs = ["--print", userMessage, "--dangerously-skip-permissions"];
+
+  try {
+    if (systemPrompt) {
+      const createdDir = mkdtempSync(join(os.tmpdir(), "forgedock-cli-system-prompt-"));
+      tmpDir = createdDir;
+      const systemPromptPath = join(createdDir, "system-prompt.txt");
+      writeFileSync(systemPromptPath, systemPrompt, "utf-8");
+      cliArgs = [
+        "--print",
+        userMessage,
+        "--append-system-prompt-file",
+        systemPromptPath,
+        "--dangerously-skip-permissions",
+      ];
+    }
+
+    // Scrub the Anthropic API key from the child environment. This backend
+    // runs with `--dangerously-skip-permissions` (no confirmation gate on any
+    // tool call, including bash), and the runner is designed to feed
+    // untrusted third-party content (issue/PR bodies via gh) into the model
+    // loop — so a prompt-injection payload could otherwise issue a bash
+    // command that exfiltrates the key straight out of its own environment.
+    // Mirrors the existing scrub in the `run_bash` tool handler below.
+    // GH_TOKEN/GITHUB_TOKEN and all other env vars are intentionally left
+    // intact — only the Anthropic key is removed.
+    const childEnv = { ...process.env };
+    delete childEnv.ANTHROPIC_API_KEY;
+
+    // No `shell` option (defaults to false): argv is passed as discrete,
+    // unparsed elements — see the SECURITY note above. This also correctly
+    // resolves the Windows `.cmd` shim without needing shell:true.
+    const result = spawnFn(bin, cliArgs, {
+      cwd,
+      encoding: "utf-8",
+      maxBuffer: DEFAULT_SPAWN_MAX_BUFFER_BYTES,
+      timeout: timeoutMs,
+      env: childEnv,
+    });
+
+    const stdout = result.stdout ? String(result.stdout) : "";
+    const stderr = result.stderr ? String(result.stderr) : "";
+
+    // Same timeout-detection shape as run_bash below: ETIMEDOUT is the
+    // authoritative Node-initiated kill signal; the elapsed-time fallback is
+    // intentionally omitted here since spawnSync's own `timeout` + ETIMEDOUT is
+    // reliable for this single, non-looped invocation.
+    const timedOut = result.status === null && result.error?.code === "ETIMEDOUT";
+    if (timedOut) {
+      const timeoutSecs = Math.round(timeoutMs / 1000);
+      throw new Error(
+        `claude CLI invocation timed out after ${timeoutSecs}s and was killed. ` +
+          `Set FORGEDOCK_CLI_TIMEOUT_MS (ms) to adjust, or use --backend api.`,
+      );
+    }
+    if (result.error) {
+      throw new Error(`Failed to invoke claude CLI: ${result.error.message}`);
+    }
+
+    const output = (stdout + stderr).trim();
+    if (output) logger.log(output);
+
+    if (result.status !== 0) {
+      const err = new Error(
+        `claude CLI exited with status ${result.status ?? "?"}. See output above for details.`,
+      );
+      err.code = "CLI_BACKEND_FAILED";
+      throw err;
+    }
+
+    logger.log(
+      renderSummaryCard({
+        command: spec.name,
+        args,
+        iterations: 1,
+        stopReason: "cli_exit_0",
+        usage: null,
+      }),
+    );
+
+    return {
+      status: "complete",
+      command: spec.name,
+      iterations: 1,
+      stopReason: "cli_exit_0",
+      usage: null,
+      model: "cli",
+      backend: "cli",
+    };
+  } finally {
+    if (tmpDir) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command spec resolution
 // ---------------------------------------------------------------------------
@@ -231,6 +716,36 @@ export function buildSystemPrompt(spec, opts = {}) {
     .join("\n");
 }
 
+/**
+ * Assemble the system prompt to forward to the CLI backend (issue #2019).
+ *
+ * This is deliberately NOT `buildSystemPrompt()` reused verbatim:
+ * `buildSystemPrompt()` was written for the API backend's custom, minimal
+ * 3-tool loop (`read_file`/`write_file`/`run_bash`) and explicitly tells the
+ * model "You have three tools to do real work" — that claim is false for the
+ * CLI backend, which runs inside the full `claude` CLI with its own native
+ * tool set (Read/Write/Edit/Bash/etc.) and its own default system prompt.
+ * Passing the API-flavored prompt to the CLI via `--append-system-prompt-file`
+ * would misinform the model about which tools it actually has.
+ *
+ * Forwarded via `--append-system-prompt-file` (see `runCliBackend`), which
+ * *appends* to the CLI's own default system prompt rather than replacing it
+ * — the CLI keeps its normal tool descriptions/environment info, with the
+ * ForgeDock command specification layered on top, mirroring how invoking
+ * `/${spec.name}` as a real Claude Code slash command would behave.
+ *
+ * @param {{name: string, content: string}} spec
+ * @returns {string}
+ */
+export function buildCliSystemPrompt(spec) {
+  return [
+    `You are executing the ForgeDock "/${spec.name}" command. Follow the command specification below exactly, using your normal available tools to do the work (file edits, git, gh, running scripts/build/test commands, etc.). Post FORGE annotations to GitHub via the gh CLI exactly as the spec instructs. Do not ask the user questions — this is a headless run. When the command is fully complete, stop and emit a concise final summary of what was accomplished.`,
+    ``,
+    `=== COMMAND SPECIFICATION (commands/${spec.name}.md) ===`,
+    spec.content,
+  ].join("\n");
+}
+
 /**
  * Build the initial user message equivalent to the Claude Code slash invocation.
  *
@@ -603,7 +1118,7 @@ export function getToolHandlers(cwd) {
       const maxBuffer =
         Number.isFinite(rawMaxBuffer) && rawMaxBuffer > 0
           ? rawMaxBuffer
-          : 50 * 1024 * 1024;
+          : DEFAULT_SPAWN_MAX_BUFFER_BYTES;
       const result = spawnSync(command, {
         cwd,
         encoding: "utf-8",
@@ -698,25 +1213,53 @@ export function getToolHandlers(cwd) {
 
 /**
  * Render the dry-run preview: what would be sent to the API, no network.
- * @param {{spec: object, systemPrompt: string, userMessage: string, model: string, maxIterations: number}} ctx
+ *
+ * `systemPrompt` in `ctx` must already be the backend-appropriate prompt —
+ * callers resolve `backend === "cli" ? cliSystemPrompt : systemPrompt` before
+ * calling this (see `runCommand`). This function branches the `tools:` line
+ * (and the on-disk-vs-inline framing of the system-prompt line) on `backend`
+ * so the preview accurately reflects what each backend actually sends: the
+ * `api` backend sends `TOOL_DEFINITIONS` (its custom read_file/write_file/
+ * run_bash loop) inline as `system`; the `cli` backend uses the `claude`
+ * CLI's own native tool set and receives the prompt via
+ * `--append-system-prompt-file`, not inline (issue #2019).
+ *
+ * @param {{spec: object, systemPrompt: string, userMessage: string, model: string, maxIterations: number, backend?: "cli"|"api"}} ctx
  * @returns {string}
  */
 export function renderDryRun(ctx) {
-  const { spec, systemPrompt, userMessage, model, maxIterations } = ctx;
+  const { spec, systemPrompt, userMessage, model, maxIterations, backend } = ctx;
+  const backendLine =
+    backend === "cli"
+      ? `│ backend:        cli (claude CLI detected — no ANTHROPIC_API_KEY needed)`
+      : backend === "api"
+        ? `│ backend:        api (ANTHROPIC_API_KEY required)`
+        : null;
+  const toolsLine =
+    backend === "cli"
+      ? `│ tools:          claude CLI's native tools (Read/Write/Edit/Bash/etc. — not TOOL_DEFINITIONS below)`
+      : `│ tools:          ${TOOL_DEFINITIONS.map((t) => t.name).join(", ")}`;
+  const systemPromptLine =
+    backend === "cli"
+      ? `│ system prompt:  ${systemPrompt.length} chars (appended to CLI's default via --append-system-prompt-file)`
+      : `│ system prompt:  ${systemPrompt.length} chars`;
   return [
     `┌─ ForgeDock run (dry-run) ───────────────────────────────`,
     `│ command:        /${spec.name}`,
     `│ spec:           ${spec.path}`,
+    backendLine,
     `│ model:          ${model}`,
     `│ max iterations: ${maxIterations}`,
-    `│ tools:          ${TOOL_DEFINITIONS.map((t) => t.name).join(", ")}`,
-    `│ system prompt:  ${systemPrompt.length} chars`,
+    toolsLine,
+    systemPromptLine,
     `│ user message:   ${userMessage}`,
     `└─────────────────────────────────────────────────────────`,
     ``,
     `(dry-run) No API call made. Set ANTHROPIC_API_KEY and install`,
     `@anthropic-ai/sdk, then drop --dry-run to execute the pipeline.`,
-  ].join("\n");
+  ]
+    .filter((line) => line !== null && line !== undefined)
+    .join("\n");
 }
 
 /**
@@ -771,6 +1314,15 @@ export function renderSummaryCard(ctx) {
  *   `cwd`) > hardcoded DEFAULT_MODEL.
  * @param {number} [opts.maxIterations]      - Tool-loop bound.
  * @param {boolean} [opts.dryRun]            - Preview without an API call.
+ * @param {string} [opts.backend]            - "cli" | "api" | "auto" (default
+ *   "auto"). Resolution order when omitted: $FORGEDOCK_BACKEND env > "auto".
+ *   "auto" prefers the local Claude Code CLI when detected (no
+ *   ANTHROPIC_API_KEY needed), else falls back to the API backend. This
+ *   precedence is intentional/shipped (issue #2003's accepted acceptance
+ *   criteria) and is NOT changed by issue #2020 — that issue only adds a
+ *   discoverability notice (below) for the case where the ladder silently
+ *   preferred `cli` while an `ANTHROPIC_API_KEY` was also available, so
+ *   users know the `--backend api`/`FORGEDOCK_BACKEND=api` override exists.
  * @param {{log: Function, error?: Function}} [opts.logger] - Output sink.
  * @returns {Promise<{status: string, command: string, [k: string]: any}>}
  */
@@ -786,21 +1338,104 @@ export async function runCommand(opts = {}) {
       DEFAULT_MODEL,
     maxIterations = DEFAULT_MAX_ITERATIONS,
     dryRun = false,
+    backend = process.env.FORGEDOCK_BACKEND || "auto",
     logger = console,
   } = opts;
 
   const spec = loadCommandSpec(commandsDir, commandName);
   const systemPrompt = buildSystemPrompt(spec, { repoRoot: cwd });
+  // CLI-backend-specific prompt (issue #2019) — see buildCliSystemPrompt's
+  // doc comment for why this must NOT be the same string as `systemPrompt`
+  // above (that one is written for the API backend's custom 3-tool loop).
+  const cliSystemPrompt = buildCliSystemPrompt(spec);
   const userMessage = buildUserMessage(commandName, args);
 
+  // Resolve the backend before dry-run so the preview reports what would
+  // actually run. isClaudeCliAvailable() is bounded by CLI_PROBE_TIMEOUT_MS
+  // and never throws on detection failure, so this cannot make --dry-run (or
+  // the start of a live run) hang or fail even when `claude` is absent or
+  // misbehaving. An explicitly invalid `backend` value DOES throw here —
+  // surfacing a bad --backend/FORGEDOCK_BACKEND value immediately, before any
+  // work is attempted, rather than silently ignoring it.
+  const resolvedBackend = resolveBackend({ requested: backend, cwd });
+
   if (dryRun) {
-    logger.log(renderDryRun({ spec, systemPrompt, userMessage, model, maxIterations }));
-    return { status: "dry-run", command: spec.name, args, specPath: spec.path, model };
+    logger.log(
+      renderDryRun({
+        spec,
+        systemPrompt: resolvedBackend === "cli" ? cliSystemPrompt : systemPrompt,
+        userMessage,
+        model,
+        maxIterations,
+        backend: resolvedBackend,
+      }),
+    );
+    return {
+      status: "dry-run",
+      command: spec.name,
+      args,
+      specPath: spec.path,
+      model,
+      backend: resolvedBackend,
+    };
+  }
+
+  if (resolvedBackend === "cli") {
+    // Discoverability notice (issue #2020): the "auto" ladder's CLI-first
+    // precedence is intentional, shipped behavior (issue #2003's accepted
+    // acceptance criteria: "prefers CLI when present, falls back to SDK")
+    // and is NOT changed here — reverting it would contradict that accepted
+    // design, exactly as sibling issue #2023 found for the analogous
+    // init-enrich ladder. The actual gap #2020 identified is that this
+    // choice is invisible on a live run: --dry-run reports the resolved
+    // backend via renderDryRun() above, but a live run previously printed
+    // nothing, so a user who has both `claude` on PATH and
+    // ANTHROPIC_API_KEY set has no signal that the ladder picked "cli" over
+    // their key, nor that `--backend api`/`FORGEDOCK_BACKEND=api` exists to
+    // pin the previous (API-only) behavior. Gate strictly on:
+    //   - `backend` being the raw, pre-resolution "auto"/default value (an
+    //     explicit `--backend cli`/`FORGEDOCK_BACKEND=cli` request needs no
+    //     "did you mean to override" hint — the user already chose).
+    //   - `apiKey` being truthy (silent for the common CLI-only case with no
+    //     key at all — nothing to "switch away from").
+    if (backend === "auto" && apiKey) {
+      logger.log(
+        "Using the claude CLI backend (found on PATH). ANTHROPIC_API_KEY is also set — " +
+          "pass --backend api or set FORGEDOCK_BACKEND=api to use the API backend instead.",
+      );
+    }
+
+    // model/maxIterations only apply to the api backend — the cli backend
+    // uses whatever model the `claude` CLI itself is configured for, and has
+    // no equivalent iteration-cap concept for a single `claude --print`
+    // invocation. Warn (rather than silently drop) when the caller explicitly
+    // supplied either, so the behavior is discoverable outside of --dry-run.
+    // hasOwnProperty on the raw opts (not the destructured, default-applied
+    // values above) is required here: model/maxIterations always resolve to
+    // a computed default, so checking their truthiness would fire this
+    // warning on every single cli-backend run.
+    const ignoredOptions = [];
+    if (Object.prototype.hasOwnProperty.call(opts, "model")) ignoredOptions.push("model");
+    if (Object.prototype.hasOwnProperty.call(opts, "maxIterations"))
+      ignoredOptions.push("maxIterations");
+    if (ignoredOptions.length > 0) {
+      logger.log(
+        `Warning: --${ignoredOptions.join(" and --")} ${
+          ignoredOptions.length > 1 ? "are" : "is"
+        } ignored on the cli backend (backend: cli uses whatever model the ` +
+          `claude CLI itself is configured for). Use --backend api to honor ${
+            ignoredOptions.length > 1 ? "these options" : "this option"
+          }.`,
+      );
+    }
+    return runCliBackend({ spec, userMessage, systemPrompt: cliSystemPrompt, args, cwd, logger });
   }
 
   if (!apiKey) {
     const err = new Error(
-      "ANTHROPIC_API_KEY is not set. Export your Anthropic API key to run the live pipeline, or pass --dry-run to preview.",
+      "ANTHROPIC_API_KEY is not set. Export your Anthropic API key to run the live pipeline, " +
+        "pass --dry-run to preview, or use --backend cli (requires the `claude` CLI on PATH, " +
+        "already authenticated) to run without an API key.",
     );
     err.code = "NO_API_KEY";
     throw err;
@@ -894,6 +1529,7 @@ export async function runCommand(opts = {}) {
         stopReason: response.stop_reason,
         usage,
         model,
+        backend: "api",
       };
     }
 
@@ -929,5 +1565,12 @@ export async function runCommand(opts = {}) {
       usage,
     }),
   );
-  return { status: "max-iterations", command: spec.name, iterations, usage, model };
+  return {
+    status: "max-iterations",
+    command: spec.name,
+    iterations,
+    usage,
+    model,
+    backend: "api",
+  };
 }