@verevoir/review 0.3.0 → 0.3.2

package/node_modules/@verevoir/llm/dist/claude-cli/index.js

@@ -0,0 +1,1142 @@
+/**
+ * @verevoir/llm/claude-cli — the Claude Code CLI (`claude -p`) as a
+ * Reviewer-shaped provider, for callers that must run on a subscription
+ * credential rather than a billed API key.
+ *
+ * WHY THIS EXISTS, RATHER THAN A SECOND CREDENTIAL ON THE ANTHROPIC
+ * ADAPTER. The Anthropic Messages API accepts a subscription OAuth token
+ * only for requests that present themselves AS Claude Code (see
+ * anthropic/index.ts's `oauthSystemIdentity()`); this adapter instead
+ * shells out to the real thing — `claude -p` — and lets it authenticate
+ * itself, rather than this library forging that identity.
+ *
+ * PROVIDER ID IS `'claude-cli'`, DELIBERATELY DISTINCT FROM `'anthropic'`,
+ * so `TokenUsage.provider` unambiguously names which substrate served a
+ * call. NEVER REGISTERED into the shared model catalog / connection
+ * registry (no `registerModelCatalog`, no `registerProviderConnection`) —
+ * `resolveModel` / `resolveModelByTerm` must never be able to silently
+ * substitute this adapter for the real API one; a caller wanting this
+ * substrate imports and calls it directly, chosen deliberately, never
+ * resolved by policy.
+ *
+ * ══════════════════════════════════════════════════════════════════════
+ * SECURITY CORRECTION (0.26.3) — READ THIS BEFORE TOUCHING THE FLAG LIST.
+ * ══════════════════════════════════════════════════════════════════════
+ * Every published version from 0.25.0 through 0.26.2 passed `--tools ""`
+ * and this file's own header claimed that "disabl[ed] tool use
+ * substrate-wide". That was never true. Confirmed directly against the
+ * CLI (the operator ran it and relayed the answer, the same discipline
+ * every other confirmed fact in this file rests on): `--tools` takes a
+ * SPACE-SEPARATED ALLOWLIST of tool names; an empty string is read as
+ * NOT SET, not as an empty allowlist, so the flag silently did nothing
+ * and every call fell through to the CLI's own default built-in tool
+ * set the entire time this adapter has been published. This is the
+ * exact property the "no-bypass" architecture depends on — the reason a
+ * model must go through the caller's own tool belt rather than reading
+ * files directly — and the published package never had it.
+ *
+ * THE FIX: `--disallowedTools "*"`. Confirmed (not relayed) to remove a
+ * tool from context ENTIRELY when named bare (as opposed to a scoped
+ * rule like `Bash(rm *)`, which leaves the tool advertised and denies
+ * only matching calls) — "absent", the same failure shape this codebase
+ * uses everywhere else, not "refused". `EndConversation` is documented
+ * as deliberately exempt from deny rules while any other tool remains;
+ * expect to see it survive and do not read that as the fix failing.
+ *
+ * `--allowedTools` WAS CONSIDERED AND REJECTED — it is CONFIRMED
+ * ADDITIVE on top of the CLI's own default safe-list ("these run
+ * without prompting"), not a restriction, and removes nothing. Using it
+ * expecting an allowlist would have been a second, identically-shaped
+ * silent fail-open. Grepped: not used anywhere in this codebase.
+ *
+ * GETTING A FLAG RIGHT ONCE IS NOT THE FIX — this is also why `chat()`
+ * now speaks `stream-json` on BOTH stdin and stdout (see TOOL-SAFETY
+ * VERIFICATION below) rather than trusting `--disallowedTools "*"` by
+ * construction the way `--tools ""` was trusted. The CLI's own
+ * `{"type":"system","subtype":"init",...}` event carries a `tools`
+ * array — the only authoritative, checkable answer to what a run
+ * actually has. A flag is an intention; the init event is the
+ * observable. `chat()` asserts against it on every call, and refuses
+ * rather than proceeding on a mismatch — the exact mechanism that would
+ * have caught the `--tools ""` defect on day one instead of it shipping
+ * silently for three minor versions.
+ *
+ * DELIBERATELY NOT TOUCHED HERE: whether `--safe-mode` actually
+ * suppresses MCP-server loading is a SEPARATE, still-unconfirmed
+ * question (see the ISOLATION paragraph below) — conflating that fix
+ * with this one is exactly how the `--tools ""` defect nearly escaped a
+ * second time layered under a different, harder-to-isolate change. This
+ * adapter never passes `--mcp-config` at all (see ISOLATION), so the
+ * question does not even arise for `chat()`'s own single-shot path.
+ *
+ * TOOL-SAFETY VERIFICATION — THE MECHANISM. `chat()` builds its stdin as
+ * ONE `{"type":"user","message":{"role":"user","content":"..."}}` line
+ * (the flattened turn text, unchanged) under `--input-format stream-json
+ * --output-format stream-json --verbose` (the last is CONFIRMED
+ * required by a real invocation: `-p --output-format stream-json`
+ * without it fails immediately with "Error: When using --print,
+ * --output-format=stream-json requires --verbose", exit 1, before
+ * producing any stream-json line at all). On a successful exit, the
+ * stdout stream is split into JSON-per-line events; the
+ * `{"type":"system","subtype":"init"}` event's `tools` array MUST be
+ * empty, matching `--disallowedTools "*"`'s promise of zero built-in
+ * tools reachable. A NON-EMPTY array, or NO init event found in the
+ * stream at all (parsing failed, the shape changed, anything this
+ * adapter cannot make sense of), THROWS rather than returning a reply
+ * that may have used capabilities this call never declared — refusing
+ * to proceed on an unverifiable safety property, not merely an
+ * incorrect one.
+ *
+ * PAYLOAD CONTRACT for the terminal `{"type":"result",...}` event,
+ * confirmed against real invocations (history in CHANGELOG.md, not
+ * repeated here). Field-for-field IDENTICAL to the previous
+ * `--output-format json` envelope this file used to parse directly —
+ * only the FRAMING changed (one line among several in a stream, not the
+ * sole stdout payload). The reply text is a FLAT STRING under `result`
+ * — not `content`, not `text`, not nested. `stop_reason` is a real
+ * top-level field and maps directly to `ChatReply.stopReason`. `usage`
+ * carries `input_tokens` / `output_tokens` / `cache_read_input_tokens` /
+ * `cache_creation_input_tokens`. There is NO version field anywhere in
+ * the payload — `resolveCliVersion()`'s memoized `claude --version`
+ * spawn (below) is the ONLY source of `substrateVersion`. `is_error:
+ * true` CAN APPEAR ALONGSIDE A ZERO EXIT CODE, and — confirmed by a real
+ * invocation — CAN APPEAR ALONGSIDE `subtype: "success"`: `subtype`
+ * describes how the request/response cycle ended, not whether the
+ * content is a failure, so `chat()` reads only `is_error`, never
+ * `subtype`, as the failure signal. A SINGLE CALL CAN INVOKE MORE THAN
+ * ONE MODEL — `modelUsage` may name several; `determinePrimaryModel()`
+ * (below) reports only the entry matching the top-level `usage` block as
+ * `TokenUsage.model`, but every entry is named in a `console.warn` when
+ * more than one is present, so a second model having run is never
+ * silently dropped.
+ *
+ * `total_cost_usd` / per-model `modelUsage[].costUSD` ARE PRESENT IN THE
+ * PAYLOAD AND DELIBERATELY NOT SURFACED ONTO `TokenUsage` — not recorded
+ * elsewhere in this repository, so kept here rather than cut. The
+ * payload gives no signal for whether that figure is billed or notional,
+ * so asserting either would be an unbacked claim; what this adapter DOES
+ * know for certain is that no billed credential was available to spend,
+ * because {@link allowedEnv} never lets one reach the child. A settled
+ * dual-cost design (billed vs. notional) is deliberate, separate,
+ * out-of-scope work (`decisions/023`, aigency-governance).
+ *
+ * `chat()` ONLY in this first cut — no `chatWithTools` /
+ * `chatWithToolLoop`. `/google` shipped the same way at its own v0.4.0
+ * release (chat() only), then added chatWithTools/chatWithToolLoop in
+ * 0.13.0 — cited here as HISTORICAL precedent for a first cut, not as
+ * `/google`'s current state, which already has both. `--disallowedTools
+ * "*"` (always passed) makes a tool loop moot for THIS adapter's single-
+ * shot purpose anyway, so a turn carrying a `tool_use` / `tool_result`
+ * block is refused rather than silently flattened.
+ *
+ * `abortSignal` IS HONOURED AT ENTRY AND MID-CALL, not just an entry
+ * check: aborting while the spawned child is still running kills it
+ * (`child.kill()`) and rejects immediately with the signal's own reason,
+ * rather than letting the subprocess finish in the background. The
+ * memoized `claude --version` lookup is deliberately NOT wired to any
+ * one call's signal, since every caller shares it.
+ *
+ * `abortSignal` IS NO LONGER THE ONLY BOUND ON HOW LONG A CALL CAN RUN.
+ * `runClaudeCli` also carries its own IDLE timeout, independent of
+ * whether a caller ever supplies `abortSignal` at all — a child that
+ * goes silent on stdout/stderr for too long is killed and this call
+ * refuses, reset on every chunk so genuine work (however long it takes)
+ * is never mistaken for a hang. See `claudeCliIdleTimeoutMs`'s own doc
+ * comment, just above `runClaudeCli` below, for the default, the
+ * override precedence, and the named `.code`/`.timeoutMs` failure shape.
+ *
+ * `onProgress` IS ACCEPTED, NEVER INVOKED. `--disallowedTools "*"`
+ * disables every built-in tool a `report_progress` mechanism would
+ * need, and the terminal `result` event still delivers the full reply
+ * only once, not incrementally — there is no partial signal to narrate
+ * from either way. A caller supplying `onProgress` will never see it
+ * called; nothing here throws for supplying it.
+ *
+ * MODEL PINNING. `chat()` accepts `options.model` — an exact model id,
+ * passed straight through as `--model <id>` — so a caller that must
+ * compare this substrate against the direct API path (or across two
+ * calls, e.g. a governance review of the same commit through both
+ * transports) can force both to answer with the identical model rather
+ * than each one's own default/class resolution silently diverging. See
+ * `ChatOptions.model`'s own doc comment in the core for the full
+ * rationale. `--model` is documented in Claude Code's own `--help` as
+ * accepting either a class alias ("sonnet", "opus") or a full model id
+ * ("claude-sonnet-4-20250514") — that documentation is what this flag
+ * rests on; unlike the flags confirmed above against a real captured
+ * payload, this one has NOT independently been re-verified against a
+ * live invocation by this repository, and is stated here as relayed,
+ * not confirmed, in the same spirit as the Bedrock/Vertex strips this
+ * file used to carry. Omitting `options.model` leaves behaviour exactly
+ * as before — the local install's own default, unpinned.
+ *
+ * `options.maxTokens` IS ACCEPTED, NEVER USED — disclosed rather than
+ * silently ignored. There is no confirmed `claude -p` flag for an
+ * output-token ceiling (unlike `--model`, nothing in the CLI's own
+ * `--help` documents one), so this adapter has nothing to pass it to; a
+ * caller relying on `maxTokens` to avoid a truncated reply on this
+ * substrate has no lever here and should know that, not discover it by
+ * the field quietly doing nothing.
+ *
+ * ISOLATION FROM PROJECT/LOCAL CONFIGURATION, on top of `--safe-mode`'s
+ * own documented disabling of CLAUDE.md/skills/plugins/hooks/MCP
+ * servers/custom commands. Two more, deliberate: `--strict-mcp-config`
+ * is passed on every invocation, so even if `--safe-mode`'s MCP
+ * suppression turns out narrower in practice than its `--help` states,
+ * no MCP server from any configuration source reaches this call — only
+ * servers passed via an explicit `--mcp-config` flag would, and this
+ * adapter never passes that flag, so the effective set is always empty.
+ * And the spawn's `cwd` (see `runClaudeCli`) is set explicitly to the
+ * platform temp directory rather than inherited from whatever directory
+ * the calling process happens to be running in — a project's
+ * `CLAUDE.md` / `.mcp.json` live relative to cwd, and a governance
+ * review process's cwd is typically the very repository it is
+ * reviewing, which is precisely the content this call must not see.
+ * Both are defense-in-depth alongside `--safe-mode`, not a claim that
+ * `--safe-mode` alone was proven insufficient — this repository has not
+ * independently re-confirmed `--safe-mode`'s own documented MCP/
+ * CLAUDE.md suppression by direct observation, so it is not relied on
+ * alone, and whether it actually holds remains a SEPARATE, open
+ * question this change does not touch (see the SECURITY CORRECTION
+ * paragraph above).
+ *
+ * ═════════════════════════════════════════════════════════════
+ * SESSION-HOLDING TRANSPORT (wave 3) — chatWithToolLoop, chatWithTools,
+ * createSession/closeSession, and chat()'s optional `session`.
+ * ═════════════════════════════════════════════════════════════
+ * Everything above this paragraph describes the single-shot `chat()`
+ * path — spawn once, one exchange, exit. `session.ts` (spawn-once,
+ * held-across-turns) and `mcp-bridge.ts` (the embedded, authenticated
+ * MCP tool bridge a tool-bearing session spawns as its own subprocess)
+ * are what this section wires into a public surface. See those two
+ * files' own headers for the full mechanism and its confirmed-vs-relayed
+ * verification history; this paragraph covers only what wiring them here
+ * adds.
+ *
+ * THE HANDLE IS THE CALLER'S TO HOLD. This package has no concept of a
+ * conversation, so a session's lifetime cannot be keyed on one without
+ * this package making policy it has no basis to reason about (when to
+ * evict, what if the key never returns). `createSession()`/
+ * `closeSession()` hand the caller an opaque `ClaudeCliSessionHandle`;
+ * the caller decides how long to keep it. Presenting a handle whose
+ * process has died, been evicted, or was never used behaves identically
+ * — start fresh, the same shape as a 401 (see session.ts's DEAD-HANDLE
+ * SAFETY paragraph). This is safe specifically because the session is an
+ * ACCELERATOR over a stateless truth: the caller's own `turns` remain
+ * the ground truth, exactly as with every other adapter's stateless
+ * `chat()`/`chatWithToolLoop()` — losing a session costs a token-
+ * spending cold rebuild, never lost work.
+ *
+ * `chatWithTools()` REFUSES on this transport, unconditionally — this is
+ * deliberate, not a gap. There is no point in this transport's design
+ * where a `tool_use` exists without already having been executed: a
+ * tool-bearing turn runs entirely inside one `claude` invocation via the
+ * embedded MCP bridge, which calls the caller's own executor itself.
+ * There is no "hand back the tool_use, let the caller run it and call
+ * again" step for this function to perform. Use `chatWithToolLoop()`,
+ * with the executor supplied up front.
+ *
+ * `chatWithToolLoop()`'s "loop" IS NOT A LOOP OF SEPARATE MODEL CALLS,
+ * UNLIKE EVERY OTHER ADAPTER'S. Anthropic/Google/the OpenAI-compatible
+ * factory loop by making several separate requests, feeding each tool
+ * result back as the next request's input. Here, the looping — the
+ * model deciding to call a tool, seeing the result, deciding whether to
+ * call another — happens INSIDE one `claude -p` turn, driven by `claude`
+ * itself through the MCP bridge; this function makes exactly one call to
+ * `runSessionTurn` per invocation. `maxIterations` (default 5, matching
+ * every other adapter's own default) maps onto that turn's tool-call
+ * BUDGET (`session.ts`/`mcp-bridge.ts`'s `maxToolCalls`) rather than a
+ * count of calls this function makes — once spent, the bridge refuses
+ * further calls with a "budget exhausted, answer now" result rather than
+ * this function issuing a second request. `iterations` on the returned
+ * result is `SessionTurnResult.assistantEventCount` — an OBSERVED COUNT
+ * of `assistant` stream events, this transport's only available proxy
+ * for "how many model iterations happened" inside that one turn, not a
+ * count of separate calls this function made (it always makes exactly
+ * one). `onIteration`, correspondingly, fires at most once per call —
+ * there is no per-round-trip moment to fire it from partway through a
+ * turn this adapter cannot see inside of.
+ *
+ * `options.session` OMITTED: a throwaway session is opened and closed
+ * for this one call, so `chatWithToolLoop()`'s result is self-contained,
+ * exactly like every other adapter's. `options.session` SUPPLIED: the
+ * turn runs on that held session, and prompt-cache warmth + tool
+ * availability persist to the NEXT call on the same handle — but per
+ * session.ts's THE SYSTEM PROMPT, MODEL, AND TOOL SET ARE FIXED AT SPAWN
+ * paragraph, `options.turns` on a call supplying `session` must carry
+ * only the ONE new message, never the full history again — the session
+ * already holds it. `chat()`'s session branch (`chatOnSession`, below)
+ * carries the identical restriction, for the identical reason.
+ *
+ * PERMISSION DENIALS are surfaced as DATA on
+ * `ClaudeCliChatWithToolLoopResult.permissionDenials`, never thrown —
+ * see `PermissionDenial`'s own doc comment in session.ts for what an
+ * empty array does and does not mean, and why it must always be read
+ * alongside `toolUses`, never alone.
+ *
+ * RECONSTRUCTION DISCLOSURE. The session-holding transport was first
+ * built as one omnibus pull request (#55, 2,394 lines) and rejected by
+ * review for its size, with no split attempted. Splitting it required
+ * re-cutting from `main` after the pieces that DID land independently
+ * (`mcp-bridge.ts` at 0.26.6, `env.ts` at 0.26.7, `session.ts` in two
+ * waves at 0.26.8/0.26.9) diverged too far from #55's own branch history
+ * for a mechanical rebase. THIS WIRING — the additions in this section
+ * — was RECONSTRUCTED from the withdrawn #55 branch via targeted greps
+ * of its surviving copy, not transplanted byte-for-byte, and is
+ * evidenced behaviourally rather than assumed faithful:
+ * `chat.session.test.ts`'s own new tests exercise every path added here
+ * directly against the real, already-reviewed `session.ts`/
+ * `mcp-bridge.ts` contracts (mocked at the module boundary, the same way
+ * `chat.test.ts` mocks `node:child_process`), and a reader should weigh
+ * this section's correctness on that evidence, not on the reconstruction
+ * being exact.
+ */
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fireUsageHook } from '../audit-hook.js';
+import { ALLOWED_ENV_VARS, allowedEnv, CLAUDE_CLI_CREDENTIAL_ENV_VAR, PROVIDER } from './env.js';
+import { closeSession, createSession, resetClaudeCliSessionsForTests, runSessionTurn, SESSION_IDLE_TIMEOUT_MS, SESSION_MAX_HELD, SESSION_TURN_TIMEOUT_MS, } from './session.js';
+// PROVIDER and the env allowlist (ALLOWED_ENV_VARS / allowedEnv /
+// CLAUDE_CLI_CREDENTIAL_ENV_VAR) moved to env.ts — see that file's own
+// header for why (session.ts needs to build the identical child
+// environment without importing back into this file). Re-exported here
+// under the exact same names, so nothing importing
+// @verevoir/llm/claude-cli can tell they ever moved.
+export { ALLOWED_ENV_VARS, allowedEnv, CLAUDE_CLI_CREDENTIAL_ENV_VAR, PROVIDER };
+// The session-holding transport (session.ts + mcp-bridge.ts, wave 3 of
+// the split replacing the withdrawn #55) — see this file's SESSION-
+// HOLDING TRANSPORT header section below for the design, and each
+// re-exported name's own doc comment in session.ts for its contract.
+export { closeSession, createSession, resetClaudeCliSessionsForTests, SESSION_IDLE_TIMEOUT_MS, SESSION_MAX_HELD, SESSION_TURN_TIMEOUT_MS, };
+/** Flags applied to every invocation. See the file header's SECURITY
+ * CORRECTION and TOOL-SAFETY VERIFICATION paragraphs for why this is
+ * `--disallowedTools "*"` plus the stream-json input/output pair, not
+ * `--tools ""` plus `--output-format json` as before 0.26.3 — and why
+ * `--bare` / `--json-schema` / `--allowedTools` are not used instead.
+ * `--model` is appended only when `model` is supplied — see the file
+ * header's MODEL PINNING paragraph; omitting it leaves the CLI's own
+ * default model selection untouched. */
+function buildArgs(systemPrompt, model) {
+    const args = [
+        '-p',
+        '--system-prompt',
+        systemPrompt,
+        '--input-format',
+        'stream-json',
+        '--output-format',
+        'stream-json',
+        // CONFIRMED required by a real invocation, not relayed: `-p
+        // --output-format stream-json` without this fails immediately with
+        // "Error: When using --print, --output-format=stream-json requires
+        // --verbose" (exit 1) before producing any stream-json line at all.
+        '--verbose',
+        // CONFIRMED to remove every built-in tool from context entirely when
+        // named bare, unlike --tools "" — see the file header's SECURITY
+        // CORRECTION paragraph. This adapter never passes --mcp-config, so
+        // there is no MCP tool for --disallowedTools's own documented
+        // MCP-filtering quirk to matter for on this path.
+        '--disallowedTools',
+        '*',
+        '--strict-mcp-config',
+        '--no-session-persistence',
+        '--safe-mode',
+    ];
+    if (model) {
+        args.push('--model', model);
+    }
+    return args;
+}
+/**
+ * Flatten a turn's content to plain text for the CLI's stdin. Per
+ * {@link TurnContent}'s own contract ("adapters that don't support a given
+ * block kind should surface a typed error rather than silently dropping
+ * content"): a `tool_use` / `tool_result` block is meaningless here — this
+ * adapter has no tool loop (`--disallowedTools "*"` disables every
+ * built-in tool) — so a turn carrying one is refused rather than
+ * silently flattened away.
+ */
+function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    const parts = [];
+    for (const block of content) {
+        if (block.type === 'text') {
+            parts.push(block.text);
+            continue;
+        }
+        throw new Error(`claudeCli: turn content block of type "${block.type}" is not supported — this adapter ` +
+            'has no tool loop (--disallowedTools "*" disables every built-in tool), so a ' +
+            'tool_use/tool_result block would be silently dropped rather than acted on. Use plain ' +
+            'text turns.');
+    }
+    return parts.join('\n');
+}
+/**
+ * Multiple turns are joined as a labelled transcript — not equivalent to a
+ * real multi-turn CLI session (there is none; see the file header, this
+ * adapter is `chat()`-only, single-shot). Documented rather than silently
+ * mishandled. The one real caller this adapter is built for (a governance
+ * review lens) always supplies exactly one turn.
+ */
+function joinTurns(turns) {
+    if (turns.length === 1) {
+        return contentToText(turns[0].content);
+    }
+    return turns.map((t) => `## ${t.role}\n${contentToText(t.content)}`).join('\n\n');
+}
+/** Wraps the flattened turn text as ONE `stream-json` input line — the
+ * shape a real invocation confirmed works for a single-shot exchange
+ * (see the file header's TOOL-SAFETY VERIFICATION paragraph). Still
+ * exactly one message, still exactly one reply; only the wire framing
+ * changed from a raw text blob to this envelope. */
+function buildStreamInputLine(content) {
+    return JSON.stringify({ type: 'user', message: { role: 'user', content } }) + '\n';
+}
+/** Parses `claude`'s `stream-json` stdout into one JSON object per
+ * non-empty line. A line that is not valid JSON is silently skipped
+ * here, not treated as fatal on its own — if the events this adapter
+ * actually needs (the init event, the result event) are never found
+ * among what DID parse, the caller-side checks below refuse explicitly
+ * rather than guessing from a partial or malformed stream. */
+function parseStreamEvents(stdout) {
+    const events = [];
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null && typeof parsed === 'object') {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // Not a JSON line — ignored; see this function's own doc comment.
+        }
+    }
+    return events;
+}
+function findResultEvent(events) {
+    const found = events.find((e) => e.type === 'result');
+    return found ? found : null;
+}
+function findInitEvent(events) {
+    const found = events.find((e) => e.type === 'system' && e.subtype === 'init');
+    return found ? found : null;
+}
+/**
+ * THE VERIFICATION ITSELF — see the file header's TOOL-SAFETY
+ * VERIFICATION paragraph for the full reasoning. Checks the CLI's own
+ * `init` event's `tools` array — never trusts `--disallowedTools "*"`
+ * by construction the way `--tools ""` used to be trusted. Throws,
+ * naming exactly what was found, on either failure mode: a non-empty
+ * array (the flag did not do what it was supposed to), or no init event
+ * at all (the property cannot be verified, so this refuses rather than
+ * silently proceeding as if it had been).
+ */
+function assertNoBuiltinToolsReachable(events) {
+    const init = findInitEvent(events);
+    if (!init) {
+        throw new Error('claudeCli.chat(): could not verify the promised zero-built-in-tools property — no ' +
+            '{"type":"system","subtype":"init"} event was found in the stream-json output to check ' +
+            'its own "tools" array against. Refusing rather than silently proceeding as if ' +
+            '--disallowedTools "*" had been honoured unseen.');
+    }
+    const tools = Array.isArray(init.tools) ? init.tools : [];
+    if (tools.length > 0) {
+        throw new Error('claudeCli.chat(): expected zero built-in tools reachable (per --disallowedTools "*"), ' +
+            `but the CLI's own init event reported ${tools.length}: ${tools.join(', ')}. Refusing to ` +
+            'return a reply that may have used tools this call never declared — this is the exact ' +
+            'class of defect --tools "" silently had in every 0.25.0-0.26.2 release (see the file ' +
+            "header's SECURITY CORRECTION paragraph).");
+    }
+}
+/**
+ * Decide which single model to report as {@link TokenUsage.model} when
+ * `modelUsage` may name more than one — see the file header's PAYLOAD
+ * CONTRACT paragraph. Matches the entry whose token
+ * counts equal the top-level `usage` block (the model that actually
+ * produced the reply text); falls back to the first entry if no exact
+ * match is found, since at least one real model id is still better than
+ * `'unknown'` in that case.
+ */
+function determinePrimaryModel(usage, modelUsage) {
+    const entries = Object.entries(modelUsage ?? {});
+    if (entries.length === 0) {
+        return { model: 'unknown', sawMultipleModels: false, breakdown: '' };
+    }
+    const breakdown = entries
+        .map(([key, u]) => `${u.canonicalModel ?? key}: ${u.inputTokens ?? 0} in / ${u.outputTokens ?? 0} out, $${(u.costUSD ?? 0).toFixed(6)}`)
+        .join('; ');
+    const match = usage
+        ? entries.find(([, u]) => u.inputTokens === usage.input_tokens && u.outputTokens === usage.output_tokens)
+        : undefined;
+    const [key, u] = match ?? entries[0];
+    return { model: u.canonicalModel ?? key, sawMultipleModels: entries.length > 1, breakdown };
+}
+// ── Substrate version, memoized for the process's lifetime ──────────────
+// See the file header — there is NO version field anywhere in the real
+// payload, so this spawn is now the ONLY source of substrateVersion.
+let cachedCliVersionPromise = null;
+/** `claude --version`'s stdout is expected to read like `2.1.243 (Claude
+ * Code)` — recorded verbatim, trimmed, rather than parsed into parts. Parsing
+ * out just the number would assume a stable format this adapter has not
+ * independently confirmed; the whole string is unambiguous and just as
+ * usable for attribution. */
+function parseVersionOutput(stdout) {
+    const trimmed = stdout.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Resolve the installed `claude` CLI's version by spawning `claude
+ * --version` once and caching the result for every subsequent call in this
+ * process. A failure (spawn error, non-zero exit, empty output) caches as
+ * `undefined` rather than retrying — the version cannot change mid-run, so
+ * a failed lookup is as stable a fact as a successful one, and retrying it
+ * on every `chat()` call would reintroduce the extra spawn this exists to
+ * avoid.
+ */
+function resolveCliVersion() {
+    if (!cachedCliVersionPromise) {
+        cachedCliVersionPromise = (async () => {
+            try {
+                const { stdout, exitCode } = await runClaudeCli(['--version'], '');
+                if (exitCode !== 0)
+                    return undefined;
+                return parseVersionOutput(stdout);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    }
+    return cachedCliVersionPromise;
+}
+/**
+ * Test-only: clears the process-wide version cache so tests can observe
+ * `resolveCliVersion()`'s spawn-and-cache behaviour in isolation rather
+ * than inheriting a value memoized by an earlier test in the same run.
+ * Never called from production code — the whole point of the cache is
+ * that a real process only needs the version resolved once.
+ */
+export function resetClaudeCliVersionCacheForTests() {
+    cachedCliVersionPromise = null;
+}
+import { withGenAISpan } from '../otel.js';
+/** Builds the span outcome for {@link chat} / {@link chatWithToolLoop}'s
+ * wrappers from an already-computed {@link TokenUsage} — every field this
+ * adapter's `shapeUsage()` populates maps straight across, including the
+ * now-distinct `sessionId` (correlation only — a held session reuses one
+ * across every turn) and `providerRequestId` (the real per-turn-unique
+ * id: held-session `uuid`, or one-shot `session_id`, which genuinely IS
+ * unique per call there — see `shapeUsage()`'s own doc comment for why
+ * these stopped being the same field, a #73 review fix). `responseId`
+ * has no claude-cli equivalent and is left unset. */
+function genAIOutcomeFromUsage(usage) {
+    return {
+        responseModel: usage.model,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadInputTokens: usage.cacheReadInputTokens,
+        cacheCreationInputTokens: usage.cacheCreationInputTokens,
+        cacheCreationEphemeral5mInputTokens: usage.cacheCreationEphemeral5mInputTokens,
+        cacheCreationEphemeral1hInputTokens: usage.cacheCreationEphemeral1hInputTokens,
+        sessionId: usage.sessionId,
+        providerRequestId: usage.providerRequestId,
+        costUsdReported: usage.costUsdReported,
+    };
+}
+function shapeUsage(usage, model, substrateVersion, totalCostUsd, 
+// The real per-turn-unique id, already resolved by the caller: the
+// held-session envelope's own `uuid` (session.ts), or — for the
+// one-shot path — `session_id`, which genuinely IS unique there (a
+// fresh `claude` process, and therefore a fresh session, per call).
+// `undefined` when neither is available. NEVER the held-session
+// `session_id` passed below as `sessionId` — that id is shared across
+// every turn on the same session, so it cannot serve as a per-call id
+// (#73 review fix: it used to, incorrectly).
+providerRequestId, 
+// The CLI's session id, kept only for correlation (see
+// `TokenUsage.sessionId`'s own doc comment) — never used as
+// `providerRequestId` above.
+sessionId) {
+    // Constant, never computed — see the file header's PAYLOAD CONTRACT
+    // paragraph for why this is safe to assert rather than derive.
+    const route = 'subscription-oauth';
+    return {
+        provider: PROVIDER,
+        model,
+        direction: 'reasoning',
+        route,
+        substrateVersion,
+        inputTokens: usage?.input_tokens ?? 0,
+        outputTokens: usage?.output_tokens ?? 0,
+        cacheCreationInputTokens: usage?.cache_creation_input_tokens ?? 0,
+        cacheReadInputTokens: usage?.cache_read_input_tokens ?? 0,
+        // Real fields on the terminal result event (see the file header's
+        // PAYLOAD CONTRACT paragraph) this adapter never surfaced before now.
+        // Left undefined — never 0 or an assumed shape — when the payload
+        // doesn't carry them, matching every other optional TokenUsage field.
+        cacheCreationEphemeral5mInputTokens: usage?.cache_creation?.ephemeral_5m_input_tokens,
+        cacheCreationEphemeral1hInputTokens: usage?.cache_creation?.ephemeral_1h_input_tokens,
+        // Provider-reported only — never computed from a price table (see
+        // decisions/023, aigency-governance, cited in this file's header, for
+        // why a billed/notional split is deliberate, separate, out-of-scope
+        // work).
+        costUsdReported: totalCostUsd,
+        sessionId,
+        providerRequestId,
+    };
+}
+/**
+ * How the process ended, described for a human reading a failure message.
+ * Checks `signal` FIRST, unconditionally — Node never sets both
+ * `exitCode` and `signal` on the same close, so there is no case where
+ * checking `signal` first hides a real exit code. Before this existed, a
+ * signal-terminated run and a bare `exitCode: null` carrying no signal
+ * were reported identically, both as "exited with code null" — the
+ * distinguishing fact was available in the `close` event's own second
+ * argument and was being discarded on the way out.
+ */
+function describeExit(command, invocation) {
+    if (invocation.signal !== null) {
+        return `${command} was killed by signal ${invocation.signal}`;
+    }
+    return `${command} exited with code ${String(invocation.exitCode)}`;
+}
+/**
+ * Recovers the REAL failure reason on a non-zero exit from the terminal
+ * `{"type":"result",...}` stream-json event on stdout, rather than
+ * reporting only the bare exit code (and possibly stderr).
+ *
+ * THE ESCAPED DEFECT THIS EXISTS TO FIX. `claude -p`'s commonest real
+ * failure — not logged in — exits 1 with EMPTY stderr; the actual reason
+ * ("Not logged in · Please run /login") lives only in stdout's own
+ * result event, in `result`, typically alongside `is_error: true`.
+ *
+ * RECOVERY ORDER: stdout is parsed as stream-json events; the result
+ * event's `result` field wins when present and non-empty. Otherwise this
+ * falls back to stdout's raw text (stdout that isn't valid JSON at all,
+ * or carries no result event with a usable `result`). `stderr` is
+ * appended ONLY when it says something the recovered text doesn't
+ * already say, so a `stderr` that merely repeats the same message is
+ * never duplicated into it.
+ *
+ * DELIBERATELY NOT USED ON THE SPAWN-FAILURE PATH (`could not run the
+ * claude CLI — …`, thrown from `chat()`'s own catch block above when the
+ * `claude` process never starts at all, e.g. ENOENT). That message's
+ * prefix is matched verbatim by `aigency-harness` #99 to split
+ * `unreachable` from `refused` — this function only ever runs once the
+ * process HAS exited with a code, a case that message is never attached
+ * to, so the two do not collide. That prefix is untouched by this change.
+ */
+function describeNonZeroExitReason(spawned) {
+    const events = parseStreamEvents(spawned.stdout);
+    const resultEvent = findResultEvent(events);
+    const fromResult = resultEvent && typeof resultEvent.result === 'string' ? resultEvent.result.trim() : '';
+    const rawStdout = spawned.stdout.trim();
+    const reason = fromResult !== '' ? fromResult : rawStdout;
+    const stderrTrimmed = spawned.stderr.trim();
+    if (reason === '') {
+        // Nothing recoverable from stdout at all — stderr is all there is,
+        // the same shape this adapter reported before this fix existed.
+        return stderrTrimmed ? `: ${stderrTrimmed}` : '';
+    }
+    const stderrAddsNewInfo = stderrTrimmed !== '' && !reason.includes(stderrTrimmed);
+    return `: ${reason}${stderrAddsNewInfo ? ` (stderr: ${stderrTrimmed})` : ''}`;
+}
+/** What an aborted `AbortSignal` should be reported as: its own `reason`
+ * when that's an `Error`, a string-wrapped `reason` otherwise, or a
+ * generic `AbortError` when no reason was given. Shared by
+ * `throwIfAborted` (the entry check) and `runClaudeCli` (the mid-call
+ * kill-and-reject), so an abort reports identically regardless of when
+ * it happened. */
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    if (signal.reason !== undefined)
+        return new Error(String(signal.reason));
+    return new DOMException('Aborted', 'AbortError');
+}
+/** Throw the AbortSignal's reason (or a generic AbortError) when the
+ * signal is aborted. No-op when no signal is provided or the signal has
+ * not been aborted. Matches every sibling adapter's own `throwIfAborted`
+ * (`anthropic/index.ts`, `google/index.ts`, `openai/index.ts`,
+ * `openai-compat.ts`, `deepseek/index.ts`) so an abort reports
+ * identically no matter which substrate served the call. */
+function throwIfAborted(signal) {
+    if (!signal?.aborted)
+        return;
+    throw abortReason(signal);
+}
+/** Runs the CLI once, writing `input` to its stdin and collecting stdout /
+ * stderr / exit code. Separated from `chat()` so tests can mock exactly
+ * this seam without reimplementing stream plumbing per test. Also used by
+ * `resolveCliVersion()` for the (memoized, at most once per process)
+ * `--version` invocation — which never passes `signal` (see the file
+ * header's `abortSignal` paragraph for why a shared, memoized lookup
+ * must not be cancellable by any one caller's abort).
+ *
+ * When `signal` aborts — whether before this function is even called, or
+ * while the spawned child is still running — the child is killed
+ * (`child.kill()`, when one has been spawned) and the returned promise
+ * rejects immediately with the signal's own reason (see `abortReason`),
+ * rather than either waiting for the process to exit on its own or
+ * reporting the abort as an ordinary spawn failure. */
+/** How long `runClaudeCli` tolerates a gap with NO stdout/stderr output at
+ * all before killing the child and refusing — reset on every chunk inside
+ * the function below (see `resetIdleTimer`). IDLE, not wall-clock: a call
+ * that is actively producing output, however long in total, is never
+ * killed by this — only a silent gap is, the same rule session.ts's
+ * `SESSION_IDLE_TIMEOUT_MS` applies to a held session's between-turn gap.
+ *
+ * WHY TOOL EXECUTION INSIDE THE CLI IS SAFE UNDER THIS, EVEN WHEN IT RUNS
+ * LONG — the v4 lesson this corrects. A tool call is not silence: the
+ * CLI's own stream-json output (the assistant/tool_use lines around it)
+ * keeps arriving on stdout while it runs, and every one of those chunks
+ * resets this timer exactly like any other output would. A WALL-CLOCK
+ * bound would have to carve out an explicit exemption for tool time —
+ * easy to get wrong, which is exactly what v4 got wrong — or risk killing
+ * a call for doing real, visible work. An IDLE bound never needs that
+ * exemption: it only ever measures silence, and a running tool call is
+ * never silent on this stream.
+ *
+ * PRECEDENCE, highest first: the per-call override passed in by
+ * `chat()`/`chatImpl` (from `ChatOptions.idleTimeoutMs`), then the
+ * `CLAUDE_CLI_IDLE_TIMEOUT_MS` env var, then this default. At every step,
+ * a value that is not a finite number greater than zero is treated as
+ * absent and falls through to the next one — never as "disable the
+ * guard", so a caller's or operator's mistake degrades to the safe
+ * default instead of removing it.
+ *
+ * The rejection this produces on expiry carries a stable `.code`
+ * ({@link CLAUDE_CLI_IDLE_TIMEOUT_CODE}) and `.timeoutMs` field a caller
+ * can match on structurally, rather than by message text. Kept a
+ * DISTINCT code from the generic `LLM_TIMEOUT` contract some routes in
+ * this package are growing (not yet present on this branch) — that
+ * contract governs a whole call's wall-clock bound with real request
+ * teardown; this is a different mechanism (idle, not wall-clock; this
+ * adapter's own stdout/stderr gap, not a generic wrapper), and collapsing
+ * the two under one code ahead of that contract landing here would claim
+ * a compatibility this file cannot yet prove. The message itself is
+ * deliberately generic ("claude CLI produced no output for Nms") — this
+ * is `@verevoir/llm`, not a reviewer; a caller such as `@verevoir/review`
+ * maps this to its own could-not-run outcome in ITS OWN layer, not
+ * this one's. */
+const DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+/** The stable `.code` field on the `Error` this file's idle timeout
+ * rejects with — see {@link DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS}'s own
+ * doc comment for why this is kept distinct from the generic
+ * `LLM_TIMEOUT` contract rather than reusing it. */
+export const CLAUDE_CLI_IDLE_TIMEOUT_CODE = 'CLAUDE_CLI_IDLE_TIMEOUT';
+/**
+ * Resolves the idle-timeout budget for one call. Precedence, highest
+ * first: `perCallOverrideMs` (the caller's own `ChatOptions.idleTimeoutMs`),
+ * then the `CLAUDE_CLI_IDLE_TIMEOUT_MS` env var, then
+ * {@link DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS}. A value that is not a
+ * finite number greater than zero — at either level — is treated as
+ * absent and falls through to the next one, never disabling the guard.
+ */
+function claudeCliIdleTimeoutMs(perCallOverrideMs) {
+    if (typeof perCallOverrideMs === 'number' &&
+        Number.isFinite(perCallOverrideMs) &&
+        perCallOverrideMs > 0) {
+        return perCallOverrideMs;
+    }
+    const envOverride = process.env.CLAUDE_CLI_IDLE_TIMEOUT_MS?.trim();
+    if (!envOverride)
+        return DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS;
+    const parsed = Number(envOverride);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS;
+}
+/** Grace period between the idle timeout's SIGTERM and its follow-up
+ * SIGKILL — long enough for a well-behaved process to exit on SIGTERM,
+ * short enough that a stuck one is not left running indefinitely. */
+const CLAUDE_CLI_IDLE_KILL_GRACE_MS = 5000;
+function runClaudeCli(args, input, signal, idleTimeoutMsOverride) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        // cwd is set explicitly to the platform temp directory, never
+        // inherited from the caller's own working directory — see the file
+        // header's ISOLATION paragraph: a project CLAUDE.md/.mcp.json live
+        // relative to cwd, and the caller's cwd is often the very repository
+        // this call must not see into.
+        const child = spawn('claude', args, { env: allowedEnv(process.env), cwd: tmpdir() });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const idleTimeoutMs = claudeCliIdleTimeoutMs(idleTimeoutMsOverride);
+        // Placeholder only — reassigned by the first resetIdleTimer() call
+        // below, mirroring session.ts's own HeldSession.idleTimer placeholder.
+        let idleTimer = setTimeout(() => { }, 0);
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(idleTimer);
+            // Terminate the still-running subprocess — an abort must not leave
+            // it running to completion in the background after the caller has
+            // already been told the call failed. This is the half an
+            // entry-only check cannot do.
+            child.kill();
+            reject(abortReason(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        // Fires only when NOTHING has arrived on stdout or stderr for
+        // idleTimeoutMs straight — resetIdleTimer() (called from both data
+        // handlers below) pushes this back out on every chunk, so a call
+        // that is genuinely working, however long it takes in total, is
+        // never killed here — only real silence is (see
+        // DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS's own doc comment for why tool
+        // execution inside the CLI is included in "genuinely working"). A
+        // child that has gone silent is killed (SIGTERM, then SIGKILL after
+        // a short grace) and this rejects with a generic, named error
+        // carrying `.code` (CLAUDE_CLI_IDLE_TIMEOUT_CODE) and `.timeoutMs`
+        // a caller can match on structurally. chatImpl's own catch below
+        // rethrows this exactly as constructed — wrapping it would strip
+        // those fields. This file never maps the failure onto any one
+        // caller's own outcome vocabulary (e.g. a reviewer's could-not-run)
+        // — that mapping belongs to that caller's own layer, not this one's.
+        const onIdleTimeout = () => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            child.kill('SIGTERM');
+            const killTimer = setTimeout(() => {
+                child.kill('SIGKILL');
+            }, CLAUDE_CLI_IDLE_KILL_GRACE_MS);
+            if (typeof killTimer.unref === 'function')
+                killTimer.unref();
+            reject(Object.assign(new Error(`claude CLI produced no output for ${String(idleTimeoutMs)}ms`), {
+                code: CLAUDE_CLI_IDLE_TIMEOUT_CODE,
+                timeoutMs: idleTimeoutMs,
+            }));
+        };
+        const resetIdleTimer = () => {
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(onIdleTimeout, idleTimeoutMs);
+            if (typeof idleTimer.unref === 'function')
+                idleTimer.unref();
+        };
+        resetIdleTimer();
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(idleTimer);
+            signal?.removeEventListener('abort', onAbort);
+            fn();
+        };
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+            resetIdleTimer();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+            resetIdleTimer();
+        });
+        // e.g. ENOENT — claude is not on PATH at all. A spawn-level failure,
+        // distinct from a non-zero exit; both end up refusing (see chat()).
+        child.on('error', (err) => finish(() => reject(err)));
+        child.on('close', (exitCode, signal) => finish(() => resolve({ stdout, stderr, exitCode, signal })));
+        // #289: `child.stdin` is its own stream — a write failure on it
+        // (EPIPE, when claude exits before reading stdin) emits 'error'
+        // THERE, not on `child`; with no listener, Node throws. Swallowed
+        // deliberately, not forwarded to reject(): the same exit also fires
+        // 'close' below, carrying the real exit code/stderr chat()'s
+        // non-zero-exit path already reports — rejecting here instead would
+        // race 'close' and can lose, surfacing a bare "write EPIPE" instead
+        // of that typed failure. Full rationale + regression test design:
+        // CHANGELOG.md (0.29.1).
+        child.stdin.on('error', () => { });
+        child.stdin.write(input);
+        child.stdin.end();
+    });
+}
+/** Shared by `chat()`'s session branch and `chatWithToolLoop()`: warns,
+ * rather than silently discarding, when a turn invoked more than one
+ * model — see `determinePrimaryModel`'s own doc comment for why only one
+ * is ever reported as `TokenUsage.model`. */
+function warnIfMultipleModels(sawMultipleModels, breakdown, scope) {
+    if (!sawMultipleModels)
+        return;
+    console.warn(`${scope}: this call invoked more than one model — ${breakdown}. TokenUsage.model reports ` +
+        "only the entry matching the reply's own usage figures; the others are named here rather " +
+        'than silently discarded, because TokenUsage has no field for a per-call model breakdown.');
+}
+/**
+ * `chat()`'s session branch — one turn on a held session rather than a
+ * fresh spawn. See this file's header SESSION-HOLDING TRANSPORT section
+ * for the mechanism; this function is deliberately small, reusing the
+ * single-shot path's own `determinePrimaryModel`/`shapeUsage`/
+ * `resolveCliVersion` so the two paths report usage identically.
+ */
+async function chatOnSession(session, options) {
+    if (options.turns.length === 0) {
+        throw new Error('claudeCli.chat() requires at least one turn');
+    }
+    if (options.turns.length > 1) {
+        throw new Error('claudeCli.chat(): a held session already carries the prior turns — pass only the ONE ' +
+            'new message per call, not the full history again (the session already has it). See ' +
+            "ClaudeCliChatOptions's own doc comment.");
+    }
+    if (options.apiKey != null) {
+        throw new Error("claudeCli.chat() does not accept apiKey — it always uses the CLI's own logged-in " +
+            'subscription session, never a supplied credential.');
+    }
+    throwIfAborted(options.abortSignal);
+    const result = await runSessionTurn({
+        session,
+        systemPrompt: options.systemPrompt,
+        message: contentToText(options.turns[0].content),
+        tools: [],
+        maxToolCalls: 0,
+        model: options.model,
+        signal: options.abortSignal,
+    });
+    const { model, sawMultipleModels, breakdown } = determinePrimaryModel(result.usage, result.modelUsage);
+    warnIfMultipleModels(sawMultipleModels, breakdown, 'claudeCli.chat');
+    const substrateVersion = await resolveCliVersion();
+    const usageRecord = shapeUsage(result.usage, model, substrateVersion, result.totalCostUsd, 
+    // Held session: `session_id` is shared across every turn, so `uuid`
+    // (the envelope's real per-turn-unique field, when present) is what
+    // becomes `providerRequestId` here — never `session_id` itself.
+    result.uuid, result.sessionId);
+    await fireUsageHook(options.onUsage, usageRecord, 'claudeCli.chat');
+    return {
+        content: result.text,
+        usage: usageRecord,
+        stopReason: result.stopReason,
+    };
+}
+/**
+ * Single-shot call through `claude -p` — or, when `options.session` is
+ * supplied, one turn on a held session (see this file's header). See the
+ * file header for every flag's justification and every
+ * refuse-rather-than-substitute mechanism.
+ */
+export async function chat(options) {
+    const requestModel = options.model ?? 'default';
+    return withGenAISpan({ provider: 'anthropic', requestModel }, async () => {
+        const reply = await chatImpl(options);
+        return { result: reply, outcome: genAIOutcomeFromUsage(reply.usage) };
+    });
+}
+/** {@link chat}'s original body, wrapped by the export above in a GenAI
+ * CLIENT span (#70's `withGenAISpan`) — covering BOTH the fresh-spawn path
+ * below and the held-session turn via `chatOnSession`, since from a
+ * caller's perspective both are the same `chat()` call. */
+async function chatImpl(options) {
+    if (options.session) {
+        return chatOnSession(options.session, options);
+    }
+    if (options.turns.length === 0) {
+        throw new Error('claudeCli.chat() requires at least one turn');
+    }
+    throwIfAborted(options.abortSignal);
+    if (options.apiKey != null) {
+        // Refused, not silently ignored — see the file header's PAYLOAD
+        // CONTRACT paragraph.
+        throw new Error("claudeCli.chat() does not accept apiKey — it always uses the CLI's own logged-in " +
+            'subscription session, never a supplied credential.');
+    }
+    const args = buildArgs(options.systemPrompt, options.model);
+    const input = buildStreamInputLine(joinTurns(options.turns));
+    // options.onProgress is accepted per the shared ChatOptions contract but
+    // never invoked — see the file header's `onProgress` paragraph for why
+    // this is a disclosed limitation, not a gap. options.maxTokens is
+    // likewise accepted and never used — see the file header's MODEL
+    // PINNING / maxTokens paragraph.
+    let spawned;
+    try {
+        spawned = await runClaudeCli(args, input, options.abortSignal, options.idleTimeoutMs);
+    }
+    catch (err) {
+        if (options.abortSignal?.aborted) {
+            // Killed and rejected by runClaudeCli's abort wiring — rethrow the
+            // signal's own reason as-is (matching throwIfAborted's contract)
+            // rather than reporting an aborted call as an ordinary spawn
+            // failure.
+            throw err;
+        }
+        if (err instanceof Error && err.code === CLAUDE_CLI_IDLE_TIMEOUT_CODE) {
+            // Already a complete, named failure — see runClaudeCli's own idle
+            // timeout and DEFAULT_CLAUDE_CLI_IDLE_TIMEOUT_MS's doc comment.
+            // Rethrown exactly as constructed: wrapping it in the generic
+            // spawn-failure message below would strip the
+            // `.code`/`.timeoutMs` fields a caller matches on structurally.
+            throw err;
+        }
+        // Spawn-level failure (e.g. claude not on PATH). No fallback — see the
+        // file header's PAYLOAD CONTRACT paragraph.
+        throw new Error(`claudeCli.chat(): could not run the claude CLI — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (spawned.exitCode !== 0) {
+        // No fallback here either — a non-zero exit refuses, it never retries
+        // against a different credential path. describeExit tells a
+        // signal-terminated close apart from a bare null exit code — see
+        // SpawnResult. describeNonZeroExitReason recovers the REAL failure
+        // reason from stdout's own result event rather than reporting only
+        // the bare exit code — see its own doc comment for why stdout, not
+        // just stderr, has to be read here, and for why the separate
+        // spawn-failure message above is untouched by this.
+        throw new Error(`${describeExit('claude -p', spawned)}${describeNonZeroExitReason(spawned)}`);
+    }
+    const events = parseStreamEvents(spawned.stdout);
+    // THE TOOL-SAFETY VERIFICATION — see the file header. Runs before
+    // anything else on a successful exit, unconditionally: the promise
+    // this call makes about tool reachability is checked against the
+    // CLI's own observable, not assumed from the flag alone.
+    assertNoBuiltinToolsReachable(events);
+    const parsed = findResultEvent(events);
+    if (parsed?.is_error) {
+        // Confirmed real: the CLI can exit 0 while its own payload says
+        // is_error: true — see the file header. Exit code alone is not a
+        // sufficient failure signal for this adapter. subtype is included
+        // for diagnostic context only, never read as a second signal — a
+        // confirmed real envelope carried subtype: "success" alongside
+        // is_error: true.
+        throw new Error(`claude -p reported is_error: true (subtype=${parsed.subtype ?? 'unknown'})` +
+            (parsed.result ? ` — ${parsed.result}` : ''));
+    }
+    let text;
+    if (parsed && typeof parsed.result === 'string') {
+        text = parsed.result;
+    }
+    else {
+        text = spawned.stdout;
+        console.warn('claudeCli.chat(): the stream-json output did not carry a {"type":"result",...} event ' +
+            'with a string "result" field — treating the raw stdout as text. The real envelope has ' +
+            'been observed and this shape is confirmed (see the file header); this fallback is for ' +
+            'a shape that does not match it, e.g. a malformed stream or a future CLI change.');
+    }
+    const { model, sawMultipleModels, breakdown } = determinePrimaryModel(parsed?.usage, parsed?.modelUsage);
+    if (sawMultipleModels) {
+        console.warn(`claudeCli.chat(): this call invoked more than one model — ${breakdown}. ` +
+            `TokenUsage.model reports only "${model}" (the entry matching the reply's own usage ` +
+            'figures); the others are named here rather than silently discarded, because ' +
+            'TokenUsage has no field for a per-call model breakdown.');
+    }
+    const substrateVersion = await resolveCliVersion();
+    const usageRecord = shapeUsage(parsed?.usage, model, substrateVersion, parsed?.total_cost_usd, 
+    // One-shot: this path spawns a fresh `claude` process — and
+    // therefore a fresh session — every call, so `session_id` genuinely
+    // IS unique per call here (unlike the held-session path, where the
+    // same id is reused across every turn — see chatOnSession's own
+    // call site). No separate `sessionId` is passed: it would just
+    // duplicate this same value.
+    parsed?.session_id, undefined);
+    await fireUsageHook(options.onUsage, usageRecord, 'claudeCli.chat');
+    return {
+        content: text,
+        usage: usageRecord,
+        stopReason: parsed?.stop_reason ?? 'end_turn',
+    };
+}
+/**
+ * REFUSES, unconditionally — see this file's header SESSION-HOLDING
+ * TRANSPORT section for why: this transport has no point where a
+ * `tool_use` exists without already having been executed, so there is
+ * nothing for a single-shot "return the tool_use, let the caller run
+ * it" function to do. Use {@link chatWithToolLoop} instead, with your
+ * executor supplied up front.
+ */
+export async function chatWithTools(_options) {
+    throw new Error('claudeCli.chatWithTools() is not supported on this transport — tool calls run through an ' +
+        'embedded MCP server that claude itself invokes as part of its own turn, so there is no ' +
+        'point where a tool_use exists without already having been executed for a caller to run ' +
+        'separately. Use claudeCli.chatWithToolLoop() instead, with your executor supplied up front.');
+}
+/**
+ * Run the model with tools available, through the embedded MCP bridge —
+ * see this file's header SESSION-HOLDING TRANSPORT section for how this
+ * differs from every other adapter's `chatWithToolLoop` (one `claude`
+ * turn, not a loop of separate model calls).
+ */
+export async function chatWithToolLoop(options) {
+    const requestModel = options.model ?? 'default';
+    return withGenAISpan({ provider: 'anthropic', requestModel }, async () => {
+        const result = await chatWithToolLoopImpl(options);
+        return { result, outcome: genAIOutcomeFromUsage(result.usage) };
+    });
+}
+/** {@link chatWithToolLoop}'s original body, wrapped by the export above
+ * in a GenAI CLIENT span (#70's `withGenAISpan`). */
+async function chatWithToolLoopImpl(options) {
+    if (options.turns.length === 0) {
+        throw new Error('claudeCli.chatWithToolLoop() requires at least one turn');
+    }
+    if (options.tools.length === 0) {
+        throw new Error('claudeCli.chatWithToolLoop() requires at least one tool');
+    }
+    if (options.apiKey != null) {
+        throw new Error("claudeCli.chatWithToolLoop() does not accept apiKey — it always uses the CLI's own " +
+            'logged-in subscription session, never a supplied credential.');
+    }
+    throwIfAborted(options.abortSignal);
+    if (options.session && options.turns.length > 1) {
+        throw new Error('claudeCli.chatWithToolLoop(): a held session already carries the prior turns — pass ' +
+            'only the ONE new message per call when session is supplied, not the full history ' +
+            "again. See ClaudeCliChatWithToolLoopOptions's own doc comment.");
+    }
+    const session = options.session ?? createSession();
+    const ownsSession = !options.session;
+    try {
+        const result = await runSessionTurn({
+            session,
+            systemPrompt: options.systemPrompt,
+            message: joinTurns(options.turns),
+            tools: options.tools,
+            executor: options.executor,
+            maxToolCalls: options.maxIterations ?? 5,
+            model: options.model,
+            signal: options.abortSignal,
+        });
+        const { model, sawMultipleModels, breakdown } = determinePrimaryModel(result.usage, result.modelUsage);
+        warnIfMultipleModels(sawMultipleModels, breakdown, 'claudeCli.chatWithToolLoop');
+        const substrateVersion = await resolveCliVersion();
+        const usageRecord = shapeUsage(result.usage, model, substrateVersion, result.totalCostUsd, 
+        // Held session: `session_id` is shared across every turn, so
+        // `uuid` (the envelope's real per-turn-unique field, when
+        // present) is what becomes `providerRequestId` here.
+        result.uuid, result.sessionId);
+        await fireUsageHook(options.onUsage, usageRecord, 'claudeCli.chatWithToolLoop');
+        if (options.onIteration) {
+            try {
+                await options.onIteration({
+                    iteration: result.assistantEventCount,
+                    toolUses: result.toolUses,
+                    stopReason: result.stopReason,
+                });
+            }
+            catch (err) {
+                console.warn('claudeCli.chatWithToolLoop: onIteration callback threw', err);
+            }
+        }
+        return {
+            text: result.text,
+            toolUses: result.toolUses,
+            toolResults: result.toolResults,
+            iterations: result.assistantEventCount,
+            usage: usageRecord,
+            permissionDenials: result.permissionDenials,
+        };
+    }
+    finally {
+        if (ownsSession) {
+            await closeSession(session);
+        }
+    }
+}
+export const claudeCli = {
+    PROVIDER,
+    chat,
+    chatWithTools,
+    chatWithToolLoop,
+    createSession,
+    closeSession,
+};
+//# sourceMappingURL=index.js.map