@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/utils/bypass-token.js

@@ -0,0 +1,133 @@
+/**
+ * Bypass token file helpers (Phase 2c safety-net #2).
+ *
+ * The token lives at `~/.claude-forge/bypass.token` (mode 0600). When present
+ * and not expired, PreToolUseHandler treats it like an inline `forge:bypass=`
+ * marker — the next deny becomes a `bypass` row + allow=true.
+ *
+ * Format (JSON):
+ *   {
+ *     "token":      "<uuid>",
+ *     "expires_at": "ISO timestamp",
+ *     "reason":     "<free-form text>",
+ *     "issued_at":  "ISO timestamp"
+ *   }
+ *
+ * Read-side robustness:
+ *   • Parsing failure / missing fields / expired token → returns `null`.
+ *   • File-mode looser than 0600 → returns `null` AND logs a warning (the
+ *     daemon refuses to honor a world-readable token to avoid local privilege
+ *     escalation).
+ *
+ * Write-side robustness:
+ *   • Always writes mode 0600 explicitly.
+ *   • Atomic via `writeFileSync` + chmod fallback.
+ */
+import { chmodSync, existsSync, readFileSync, statSync, unlinkSync, writeFileSync, mkdirSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { FORGE_PATHS } from '../constants.js';
+import { logger } from './logger.js';
+/**
+ * Read & validate the bypass token. Returns `null` for any of:
+ *   • file missing
+ *   • file mode != 0600 (world / group readable)
+ *   • JSON parse error
+ *   • missing required fields
+ *   • expired
+ *
+ * Caller paths (PreToolUseHandler) should treat a `null` return as "no bypass".
+ */
+export function readBypassFile(path = FORGE_PATHS.bypassToken()) {
+    try {
+        if (!existsSync(path))
+            return null;
+        // Security: refuse to honor a token that is readable by other users.
+        // 0600 = rw-------. We accept any subset of owner bits but reject if
+        // group/other bits are set.
+        try {
+            const st = statSync(path);
+            // mode bits: low 9 = rwx for u/g/o. group bits = 0o070, other bits = 0o007.
+            const groupOrOther = st.mode & 0o077;
+            if (groupOrOther !== 0) {
+                logger.warn(`[bypass-token] refusing token at ${path}: mode ${(st.mode & 0o777).toString(8)} is not 0600`);
+                return null;
+            }
+        }
+        catch (statErr) {
+            logger.debug(`[bypass-token] stat failed: ${statErr}`);
+        }
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.token !== 'string' ||
+            typeof parsed.expires_at !== 'string' ||
+            typeof parsed.reason !== 'string' ||
+            typeof parsed.issued_at !== 'string') {
+            return null;
+        }
+        const expMs = Date.parse(parsed.expires_at);
+        if (!Number.isFinite(expMs) || expMs <= Date.now()) {
+            return null;
+        }
+        return parsed;
+    }
+    catch (err) {
+        logger.debug(`[bypass-token] read failed: ${err}`);
+        return null;
+    }
+}
+/**
+ * Write the token JSON with mode 0600. The parent directory is created if it
+ * does not already exist. Returns the path written so callers can echo it.
+ */
+export function writeBypassFile(opts) {
+    const path = opts.path ?? FORGE_PATHS.bypassToken();
+    const nowMs = opts.nowMs ?? Date.now();
+    const payload = {
+        token: opts.token ?? randomUUID(),
+        issued_at: new Date(nowMs).toISOString(),
+        expires_at: new Date(nowMs + opts.ttlMs).toISOString(),
+        reason: opts.reason,
+    };
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    // Write then chmod — writeFileSync's `mode` option respects umask on some
+    // platforms, so an explicit chmod is the only way to guarantee 0600.
+    writeFileSync(path, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf-8' });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch (err) {
+        logger.warn(`[bypass-token] chmod 0600 failed (token still written): ${err}`);
+    }
+    return { path, payload };
+}
+/** Remove the token file if present. Idempotent. */
+export function revokeBypassFile(path = FORGE_PATHS.bypassToken()) {
+    try {
+        if (!existsSync(path))
+            return false;
+        unlinkSync(path);
+        return true;
+    }
+    catch (err) {
+        logger.warn(`[bypass-token] revoke failed: ${err}`);
+        return false;
+    }
+}
+/**
+ * Parse `--ttl <duration>` argument from CLI. Accepts:
+ *   • plain number → seconds
+ *   • `<n>s` / `<n>m` / `<n>h` suffix
+ * Returns milliseconds. Throws on invalid input.
+ */
+export function parseTtl(input) {
+    const trimmed = input.trim();
+    const m = /^(\d+)\s*([smh]?)$/i.exec(trimmed);
+    if (!m)
+        throw new Error(`Invalid --ttl "${input}" (expected: <n>[s|m|h], e.g. 5m, 30s, 1h)`);
+    const n = Number(m[1]);
+    const unit = (m[2] || 's').toLowerCase();
+    const mult = unit === 'h' ? 3600_000 : unit === 'm' ? 60_000 : 1000;
+    return n * mult;
+}
+//# sourceMappingURL=bypass-token.js.map

package/dist/core/utils/bypass-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bypass-token.js","sourceRoot":"","sources":["../../../src/core/utils/bypass-token.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/cc-builtin-agents.d.ts

@@ -0,0 +1,3 @@
+/** True if the given subagent_type is a Claude Code built-in (no .md file). */
+export declare function isBuiltinAgent(name: string): boolean;
+//# sourceMappingURL=cc-builtin-agents.d.ts.map

package/dist/core/utils/cc-builtin-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-builtin-agents.d.ts","sourceRoot":"","sources":["../../../src/core/utils/cc-builtin-agents.ts"],"names":[],"mappings":"AAyBA,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD"}

package/dist/core/utils/cc-builtin-agents.js

@@ -0,0 +1,29 @@
+/**
+ * Claude Code built-in (virtual) subagent types.
+ *
+ * These names are advertised by the Claude Code TUI / Task tool but have no
+ * backing markdown file in `.claude/agents/`. The Web "Agent 委托" tab still
+ * receives delegation events for them (they show up in routing_events), so we
+ * must classify them as `builtin` rather than rejecting the detail request.
+ *
+ * Issue #4 (2026-05-29): clicking `Plan` / `Explore` / `general-purpose` in
+ * the delegation table previously returned HTTP 400 because the agent-name
+ * regex was lowercase-kebab only. We now accept builtin names and return a
+ * friendly 200 response with `source: 'builtin'`.
+ *
+ * Maintenance: when Claude Code ships new builtins, append to this set.
+ * Names are matched case-sensitively (matches what Task tool sends).
+ */
+const CC_BUILTIN_AGENTS = new Set([
+    'general-purpose',
+    'Plan',
+    'Explore',
+    'Task',
+    'claude-code-guide',
+    'statusline-setup',
+]);
+/** True if the given subagent_type is a Claude Code built-in (no .md file). */
+export function isBuiltinAgent(name) {
+    return CC_BUILTIN_AGENTS.has(name);
+}
+//# sourceMappingURL=cc-builtin-agents.js.map

package/dist/core/utils/cc-builtin-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-builtin-agents.js","sourceRoot":"","sources":["../../../src/core/utils/cc-builtin-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IACrD,iBAAiB;IACjB,MAAM;IACN,SAAS;IACT,MAAM;IACN,mBAAmB;IACnB,kBAAkB;CACnB,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/utils/claude-cli-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * spec 1851 R-B: probe for the `claude` CLI binary on PATH.
+ *
+ * The distill pipeline spawns this binary via `child_process.spawn` to drive
+ * the skill-distiller agent in headless mode (`claude -p --agent
+ * skill-distiller --bare ...`). Because the spawned `claude` reuses the
+ * user's Claude Code OAuth/keychain session, the daemon no longer needs an
+ * `ANTHROPIC_API_KEY` for distillation — billing flows through the user's
+ * Claude Code subscription.
+ *
+ * Resolution order:
+ *   1. `which claude` (POSIX PATH lookup — covers brew / npm-global installs
+ *      visible in the calling shell).
+ *   2. Common static install paths (homebrew, /usr/local, ~/.local) as
+ *      fallback when the daemon was launched by launchd with a stripped PATH.
+ *
+ * Result is cached for 5 minutes so the `/api/skills/distill/status` probe
+ * (called on every status poll from the Web UI) doesn't fork a child process
+ * each time.
+ */
+export declare function findClaudeBin(opts?: {
+    force?: boolean;
+}): string | null;
+/** Test-only: clear the cache. @internal */
+export declare function _resetClaudeCliCache(): void;
+//# sourceMappingURL=claude-cli-resolver.d.ts.map

package/dist/core/utils/claude-cli-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/utils/claude-cli-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,wBAAgB,aAAa,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,GAAG,IAAI,CAyB3E;AAwDD,4CAA4C;AAC5C,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}

package/dist/core/utils/claude-cli-resolver.js

@@ -0,0 +1,115 @@
+/**
+ * spec 1851 R-B: probe for the `claude` CLI binary on PATH.
+ *
+ * The distill pipeline spawns this binary via `child_process.spawn` to drive
+ * the skill-distiller agent in headless mode (`claude -p --agent
+ * skill-distiller --bare ...`). Because the spawned `claude` reuses the
+ * user's Claude Code OAuth/keychain session, the daemon no longer needs an
+ * `ANTHROPIC_API_KEY` for distillation — billing flows through the user's
+ * Claude Code subscription.
+ *
+ * Resolution order:
+ *   1. `which claude` (POSIX PATH lookup — covers brew / npm-global installs
+ *      visible in the calling shell).
+ *   2. Common static install paths (homebrew, /usr/local, ~/.local) as
+ *      fallback when the daemon was launched by launchd with a stripped PATH.
+ *
+ * Result is cached for 5 minutes so the `/api/skills/distill/status` probe
+ * (called on every status poll from the Web UI) doesn't fork a child process
+ * each time.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from './logger.js';
+let cachedPath; // undefined = not yet probed
+let cachedAt = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+export function findClaudeBin(opts = {}) {
+    const now = Date.now();
+    if (!opts.force && cachedPath !== undefined && now - cachedAt < CACHE_TTL_MS) {
+        return cachedPath;
+    }
+    cachedPath = probe();
+    cachedAt = now;
+    if (cachedPath) {
+        logger.info(`[claude-cli-resolver] resolved claude binary → ${cachedPath}`);
+    }
+    else {
+        // Under launchd the daemon inherits a stripped PATH (com.claude-forge.daemon
+        // plist sets PATH=/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin). Any
+        // npm-global / nvm install lives OUTSIDE that PATH, so `which claude` fails
+        // and only the static fallback list below can save us. Same launchd-PATH
+        // class of bug as binary-paths.ts (commit cd48a735). When even the fallbacks
+        // miss, the classifier / distiller / knowledge-build spawns all fail — so we
+        // warn LOUDLY here instead of returning null into a debug-swallowed caller.
+        logger.warn('[claude-cli-resolver] claude binary NOT FOUND — `which claude` failed AND no static ' +
+            `fallback matched (PATH="${process.env.PATH ?? ''}"). Daemon LLM spawns (task-boundary ` +
+            'classifier, distiller, knowledge build) will all fail until claude is on PATH or one of ' +
+            'the known install paths.');
+    }
+    return cachedPath;
+}
+/**
+ * Static install paths probed when `which claude` fails under a launchd-stripped
+ * PATH. Ordered most→least common on macOS/Linux. nvm / npm-global installs are
+ * the gap decision 083112fc widened beyond the original homebrew-only trio.
+ */
+function staticCandidates() {
+    const home = process.env.HOME ?? '';
+    const candidates = [
+        '/opt/homebrew/bin/claude', // Apple-silicon homebrew (most common)
+        '/usr/local/bin/claude', // Intel homebrew / manual installs
+        `${home}/.local/bin/claude`, // pipx-style / user-local
+        `${home}/.bun/bin/claude`, // bun global
+    ];
+    // nvm: ~/.nvm/versions/node/<ver>/bin/claude — version dir is dynamic, so we
+    // enumerate installed node versions rather than guess. Newest-first ordering
+    // is best-effort (lexical) since the exact active version is unknown here.
+    const nvmRoot = path.join(home, '.nvm', 'versions', 'node');
+    try {
+        const versions = fs.readdirSync(nvmRoot).sort().reverse();
+        for (const v of versions) {
+            candidates.push(path.join(nvmRoot, v, 'bin', 'claude'));
+        }
+    }
+    catch {
+        // no nvm dir — skip
+    }
+    // npm global prefix (covers `npm i -g @anthropic-ai/claude-code` outside nvm).
+    if (home) {
+        candidates.push(path.join(home, '.npm-global', 'bin', 'claude'));
+        candidates.push('/usr/local/lib/node_modules/.bin/claude');
+    }
+    return candidates;
+}
+function probe() {
+    // Try `which claude` first (POSIX); fallback to checking common paths.
+    try {
+        const out = execSync('which claude', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (out && fs.existsSync(out))
+            return out;
+    }
+    catch {
+        // not on PATH
+    }
+    for (const candidate of staticCandidates()) {
+        try {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            // ignore — try next
+        }
+    }
+    return null;
+}
+/** Test-only: clear the cache. @internal */
+export function _resetClaudeCliCache() {
+    cachedPath = undefined;
+    cachedAt = 0;
+}
+//# sourceMappingURL=claude-cli-resolver.js.map

package/dist/core/utils/claude-cli-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli-resolver.js","sourceRoot":"","sources":["../../../src/core/utils/claude-cli-resolver.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/claude-cli-spawn.d.ts

@@ -0,0 +1,106 @@
+/**
+ * claude-cli-spawn.ts — Public helper for spawning the `claude` CLI,
+ * parsing the stream-json output across CLI versions, and returning the
+ * raw assistant text.
+ *
+ * Origin: extracted from `src/skills/distill/distiller.ts`
+ * (spec 1851 R-B commit `03fbda1d`) so multiple call-sites (claudemd,
+ * knowledge build, patch web, …) can share the same plumbing instead of
+ * each re-implementing spawn + JSON merge + timeout + cancel.
+ *
+ * Spec: docs/design/2026-05-29/0902-ai-config-removal-master-spec.md §2.6
+ * Decision: f5a5b030 (Option B — claude CLI shell-out everywhere)
+ *
+ * OAuth / `--bare` history (2026-05-29):
+ *  - The CLI's `--bare` flag skips Keychain reads and forces auth via
+ *    `ANTHROPIC_API_KEY` only. Subscription users (no API key) hit an
+ *    immediate "Not logged in" failure under `--bare`. The distiller hit
+ *    this first (fixed in commit `6b02f87b`); this shared helper hit the
+ *    same bug for `cf claudemd`, `cf knowledge build`, `cf patch` etc.
+ *  - Fix mirrors the distiller: default `bareMode` is now `false`, and
+ *    daemon-recursion (spawned child's hooks firing back into the daemon)
+ *    is broken by setting `CLAUDE_FORGE_INTERNAL_SPAWN=1` on the child
+ *    env. Every entry-point hook short-circuits when EITHER
+ *    `CLAUDE_FORGE_INTERNAL_SPAWN` or `CLAUDE_FORGE_DISTILL_SPAWN`
+ *    (legacy) is non-empty. See src/hooks/*.sh.
+ *
+ * Design notes:
+ *  - We do NOT couple to envelope parsing. Each caller defines its own
+ *    `---X---...---END---` envelope (SKILL / SKIP / CLAUDEMD / PATCH …) and
+ *    parses the returned string itself.
+ *  - The CLI's stream-json schema differs between Claude Code versions; the
+ *    merge accepts the union of common shapes (assistant_message /
+ *    content_block_delta / message_delta / text_delta / result).
+ *  - `findClaudeBin` is reused from `src/core/utils/claude-cli-resolver.ts`
+ *    (do not duplicate — both call sites must hit the same 5-min PATH cache).
+ */
+export interface ClaudeCliProgressEvent {
+    /** Event type as reported by the CLI (e.g. `content_block_delta`). */
+    type: string;
+    /** Running total of assistant text characters accumulated so far. */
+    charCount?: number;
+    /** Raw JSON event for callers that want to inspect everything. */
+    raw?: unknown;
+}
+export interface ClaudeCliSpawnOpts {
+    /** Sub-agent name passed to `--agent <name>`. */
+    agent: string;
+    /** Text sent to the spawned `claude` process via stdin. */
+    prompt: string;
+    /**
+     * Pass `--bare` (skip hooks/LSP/auto-memory/MCP).  Default: `false`.
+     *
+     * IMPORTANT: `--bare` also forces auth via `ANTHROPIC_API_KEY` only and
+     * skips Keychain reads, so subscription users (no API key) get
+     * "Not logged in" instantly. Daemon-recursion is instead broken via the
+     * `CLAUDE_FORGE_INTERNAL_SPAWN=1` env we always set on the child — every
+     * entry-point hook short-circuits when this env is non-empty. Only set
+     * `bareMode: true` when you explicitly want a hermetic headless run AND
+     * have `ANTHROPIC_API_KEY` exported (CI / batch tooling).
+     */
+    bareMode?: boolean;
+    /**
+     * Allowed tool list forwarded as `--allowedTools "Tool1 Tool2"`.  Default
+     * empty (CLI uses agent's own `tools:` frontmatter).
+     */
+    allowedTools?: string[];
+    /** Aborts the subprocess on `signal.abort()` (sends SIGTERM). */
+    cancelSignal?: AbortSignal;
+    /** Hard timeout in ms.  Default: 600 000 (10 min, same as distiller). */
+    timeoutMs?: number;
+    /** Streaming progress hook invoked for every parsed stream-json line. */
+    onProgress?: (event: ClaudeCliProgressEvent) => void;
+    /** Optional override for the `claude` binary path (else PATH probe). */
+    claudeBin?: string;
+}
+export declare class ClaudeCliMissingError extends Error {
+    constructor();
+}
+export declare class ClaudeCliExitError extends Error {
+    readonly exitCode: number;
+    readonly stderrSnippet: string;
+    constructor(exitCode: number, stderr: string);
+}
+export declare class ClaudeCliTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare class ClaudeCliCancelledError extends Error {
+    constructor();
+}
+/**
+ * Spawn `claude -p --agent <name> [--bare] --output-format stream-json
+ *   --verbose --include-partial-messages --input-format text
+ *   [--allowedTools "..."]`
+ * with the given prompt on stdin, then collect the assistant's text from
+ * the stream-json output.
+ *
+ * `--bare` is opt-in (`bareMode: true`); the default keeps OAuth Keychain
+ * reads working for subscription users. Recursion is broken via the
+ * `CLAUDE_FORGE_INTERNAL_SPAWN=1` env we set on the child.
+ *
+ * Returns the raw assistant text (the caller is responsible for envelope
+ * parsing, e.g. `parseSkillBlock` / `parseClaudeMdBlock`).
+ */
+export declare function spawnClaudeCli(opts: ClaudeCliSpawnOpts): Promise<string>;
+//# sourceMappingURL=claude-cli-spawn.d.ts.map

package/dist/core/utils/claude-cli-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli-spawn.d.ts","sourceRoot":"","sources":["../../../src/core/utils/claude-cli-spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAOH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,iEAAiE;IACjE,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACrD,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;;CAO/C;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ7C;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,SAAS,EAAE,MAAM;CAK9B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgI9E"}

package/dist/core/utils/claude-cli-spawn.js

@@ -0,0 +1,219 @@
+/**
+ * claude-cli-spawn.ts — Public helper for spawning the `claude` CLI,
+ * parsing the stream-json output across CLI versions, and returning the
+ * raw assistant text.
+ *
+ * Origin: extracted from `src/skills/distill/distiller.ts`
+ * (spec 1851 R-B commit `03fbda1d`) so multiple call-sites (claudemd,
+ * knowledge build, patch web, …) can share the same plumbing instead of
+ * each re-implementing spawn + JSON merge + timeout + cancel.
+ *
+ * Spec: docs/design/2026-05-29/0902-ai-config-removal-master-spec.md §2.6
+ * Decision: f5a5b030 (Option B — claude CLI shell-out everywhere)
+ *
+ * OAuth / `--bare` history (2026-05-29):
+ *  - The CLI's `--bare` flag skips Keychain reads and forces auth via
+ *    `ANTHROPIC_API_KEY` only. Subscription users (no API key) hit an
+ *    immediate "Not logged in" failure under `--bare`. The distiller hit
+ *    this first (fixed in commit `6b02f87b`); this shared helper hit the
+ *    same bug for `cf claudemd`, `cf knowledge build`, `cf patch` etc.
+ *  - Fix mirrors the distiller: default `bareMode` is now `false`, and
+ *    daemon-recursion (spawned child's hooks firing back into the daemon)
+ *    is broken by setting `CLAUDE_FORGE_INTERNAL_SPAWN=1` on the child
+ *    env. Every entry-point hook short-circuits when EITHER
+ *    `CLAUDE_FORGE_INTERNAL_SPAWN` or `CLAUDE_FORGE_DISTILL_SPAWN`
+ *    (legacy) is non-empty. See src/hooks/*.sh.
+ *
+ * Design notes:
+ *  - We do NOT couple to envelope parsing. Each caller defines its own
+ *    `---X---...---END---` envelope (SKILL / SKIP / CLAUDEMD / PATCH …) and
+ *    parses the returned string itself.
+ *  - The CLI's stream-json schema differs between Claude Code versions; the
+ *    merge accepts the union of common shapes (assistant_message /
+ *    content_block_delta / message_delta / text_delta / result).
+ *  - `findClaudeBin` is reused from `src/core/utils/claude-cli-resolver.ts`
+ *    (do not duplicate — both call sites must hit the same 5-min PATH cache).
+ */
+import { spawn } from 'node:child_process';
+import { findClaudeBin } from './claude-cli-resolver.js';
+export class ClaudeCliMissingError extends Error {
+    constructor() {
+        super('[claude-cli-spawn] claude CLI not found on PATH. Install via `brew install claude` or `npm i -g @anthropic-ai/claude-code`.');
+        this.name = 'ClaudeCliMissingError';
+    }
+}
+export class ClaudeCliExitError extends Error {
+    exitCode;
+    stderrSnippet;
+    constructor(exitCode, stderr) {
+        super(`[claude-cli-spawn] claude CLI exited ${exitCode}: ${stderr.slice(0, 500)}`);
+        this.name = 'ClaudeCliExitError';
+        this.exitCode = exitCode;
+        this.stderrSnippet = stderr.slice(0, 500);
+    }
+}
+export class ClaudeCliTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`[claude-cli-spawn] claude CLI timeout after ${timeoutMs}ms`);
+        this.name = 'ClaudeCliTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class ClaudeCliCancelledError extends Error {
+    constructor() {
+        super('[claude-cli-spawn] cancelled by user');
+        this.name = 'ClaudeCliCancelledError';
+    }
+}
+// ── Implementation ────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 600_000;
+/**
+ * Spawn `claude -p --agent <name> [--bare] --output-format stream-json
+ *   --verbose --include-partial-messages --input-format text
+ *   [--allowedTools "..."]`
+ * with the given prompt on stdin, then collect the assistant's text from
+ * the stream-json output.
+ *
+ * `--bare` is opt-in (`bareMode: true`); the default keeps OAuth Keychain
+ * reads working for subscription users. Recursion is broken via the
+ * `CLAUDE_FORGE_INTERNAL_SPAWN=1` env we set on the child.
+ *
+ * Returns the raw assistant text (the caller is responsible for envelope
+ * parsing, e.g. `parseSkillBlock` / `parseClaudeMdBlock`).
+ */
+export async function spawnClaudeCli(opts) {
+    const claudeBin = opts.claudeBin ?? findClaudeBin();
+    if (!claudeBin)
+        throw new ClaudeCliMissingError();
+    const args = [
+        '-p',
+        '--agent', opts.agent,
+    ];
+    if (opts.bareMode === true)
+        args.push('--bare');
+    args.push('--output-format', 'stream-json', 
+    // claude CLI rejects `--print --output-format=stream-json` without --verbose:
+    // "When using --print, --output-format=stream-json requires --verbose".
+    // Same regression as spec 1443 (commit b2e87f45) for distiller.ts; the
+    // 2026-05-29 shared-helper extraction missed this flag.
+    '--verbose', '--include-partial-messages', '--input-format', 'text');
+    if (opts.allowedTools && opts.allowedTools.length > 0) {
+        args.push('--allowedTools', opts.allowedTools.join(' '));
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(claudeBin, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                // Recursion guard: every entry-point hook in src/hooks/*.sh
+                // short-circuits when this env is non-empty, preventing the spawned
+                // claude subprocess from firing its hooks back into the daemon.
+                CLAUDE_FORGE_INTERNAL_SPAWN: '1',
+            },
+        });
+        let assistantText = '';
+        let stderr = '';
+        let buffer = '';
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const cancelHandler = () => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            settle(() => reject(new ClaudeCliCancelledError()));
+        };
+        opts.cancelSignal?.addEventListener('abort', cancelHandler);
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const timeoutId = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            settle(() => reject(new ClaudeCliTimeoutError(timeoutMs)));
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            buffer += chunk.toString('utf-8');
+            let nl;
+            while ((nl = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, nl).trim();
+                buffer = buffer.slice(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    const ev = JSON.parse(line);
+                    const before = assistantText.length;
+                    // CLI stream-json event shapes vary across versions; accept the
+                    // union of common forms and extract any text we can find.
+                    if (ev.type === 'assistant' || ev.type === 'assistant_message') {
+                        const content = ev.content;
+                        if (Array.isArray(content)) {
+                            for (const c of content) {
+                                if (c && typeof c === 'object' && typeof c.text === 'string') {
+                                    assistantText += c.text;
+                                }
+                            }
+                        }
+                        else if (typeof ev.text === 'string') {
+                            assistantText += ev.text;
+                        }
+                    }
+                    else if (ev.type === 'content_block_delta') {
+                        const delta = ev.delta;
+                        if (delta && typeof delta.text === 'string')
+                            assistantText += delta.text;
+                    }
+                    else if (ev.type === 'message_delta' || ev.type === 'text_delta') {
+                        const delta = ev.delta;
+                        if (typeof delta === 'string')
+                            assistantText += delta;
+                    }
+                    else if (ev.type === 'result') {
+                        const result = ev.result;
+                        if (typeof result === 'string' && !assistantText)
+                            assistantText = result;
+                    }
+                    // Always notify caller, even when no text was extracted from this
+                    // line (callers use the event types for spinner / SSE bridging).
+                    void before;
+                    opts.onProgress?.({
+                        type: ev.type ?? 'unknown',
+                        charCount: assistantText.length,
+                        raw: ev,
+                    });
+                }
+                catch {
+                    // Ignore non-JSON lines — stream-json normally never emits them,
+                    // but defensive against partial buffering bugs in older CLI builds.
+                }
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('close', (code) => {
+            clearTimeout(timeoutId);
+            opts.cancelSignal?.removeEventListener('abort', cancelHandler);
+            if (code === 0) {
+                settle(() => resolve(assistantText));
+            }
+            else {
+                settle(() => reject(new ClaudeCliExitError(code ?? -1, stderr)));
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeoutId);
+            opts.cancelSignal?.removeEventListener('abort', cancelHandler);
+            settle(() => reject(new Error(`[claude-cli-spawn] claude CLI spawn error: ${err.message}`)));
+        });
+        child.stdin.write(opts.prompt);
+        child.stdin.end();
+    });
+}
+//# sourceMappingURL=claude-cli-spawn.js.map