--- url: >- https://adk.nht.io/api/@nhtio/adk/batteries/llm/claude_code_cli/types/interfaces/ClaudeCodeCliAdapterOptions.md description: >- Configuration options for the {@link @nhtio/adk/batteries/llm/claude_code_cli!ClaudeCodeCliAdapter}. --- # Interface: ClaudeCodeCliAdapterOptions Defined in: [src/batteries/llm/claude\_code\_cli/types.ts:199](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L199) Configuration options for the [@nhtio/adk/batteries/llm/claude\_code\_cli!ClaudeCodeCliAdapter](../../adapter/classes/ClaudeCodeCliAdapter.md). ## Properties | Property | Type | Description | Defined in | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `addDir?` | `string`\[] | Additional directories to allow tool access to, forwarded to `--add-dir`. | [src/batteries/llm/claude\_code\_cli/types.ts:228](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L228) | | `apiKey?` | `string` | Forwarded as `ANTHROPIC_API_KEY`. Exactly one of `apiKey`/`authToken` must be set. | [src/batteries/llm/claude\_code\_cli/types.ts:220](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L220) | | `appendSystemPrompt?` | `string` | Forwarded verbatim to `--append-system-prompt`, appending to Claude Code's OWN system prompt — a wholly separate channel from this battery's rendered `-p` history prompt. No merge/concatenation logic against the history prompt itself. | [src/batteries/llm/claude\_code\_cli/types.ts:218](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L218) | | `authToken?` | `string` | Forwarded as `ANTHROPIC_AUTH_TOKEN`. Exactly one of `apiKey`/`authToken` must be set. Empirically confirmed to work under `--bare`. | [src/batteries/llm/claude\_code\_cli/types.ts:222](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L222) | | `autoAck?` | `boolean` | Whether the executor acks automatically on a tool-call-free terminal answer. | [src/batteries/llm/claude\_code\_cli/types.ts:297](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L297) | | `autoDetectElectronHost?` | `boolean` | Whether to auto-detect an Electron main-process host (`process.versions.electron !== undefined`) and default the wrapper's spawn env to include `ELECTRON_RUN_AS_NODE: '1'` — the documented Electron mechanism for making a spawned copy of the Electron binary behave as plain Node instead of booting a full second Electron app that runs the wrapper script as its main script. Default `true`; every plain-Node host is unaffected either way (`process.versions.electron` is `undefined` there, so this default is inert), and this can be disabled if a consumer has their own mitigation or supplies `wrapperExecPath` instead. **Remarks** **This option is a resource optimization, not a correctness requirement.** Earlier revisions of this doc comment (pre-issue-#42-Part-A) framed it as the fix for an Electron host hanging indefinitely; that is no longer accurate and this paragraph corrects it. The wrapper's own explicit `process.exit(0)` on the normal-completion path (issue #42, Part A) now guarantees a clean exit unconditionally, regardless of whether this option is enabled, disabled, or defeated by a disabled `RunAsNode` fuse — correctness no longer depends on this option at all. What it still controls is which of two ways a spawned Electron binary reaches that same clean exit: Measured (this fix's own investigation, scratch harnesses against a real copy of `Electron.app`, both with the `RunAsNode` Electron Fuse left at its default (ON) and explicitly disabled via `npx @electron/fuses`, and separately re-measured end-to-end against the BUILT wrapper after Part A landed): - Fuse ON, `ELECTRON_RUN_AS_NODE=1` (this option's default effect): spawned copy runs as plain Node (`process.type === undefined`) — cheap, no GPU/network/renderer utility processes ever boot. Exits 0. - Fuse ON, no env var (this option disabled): spawned copy boots as a full Electron app (`process.type === 'browser'`) — measurably more expensive (GPU process, network service process, etc., all spun up and torn down for a wrapper that never needed any of them). Still exits 0 with Part A in place. - Fuse OFF, either way: `ELECTRON_RUN_AS_NODE` is silently ignored by the Electron runtime itself — this option categorically cannot make the spawned copy behave as plain Node once the fuse is disabled. The spawned copy boots as a full Electron app regardless (the same "expensive" path as the previous bullet). With Part A in place, it still exits 0 — just wastefully, having booted machinery it didn't need. `child_process.fork()` from within a genuine Electron main process throws synchronously in this state (`"...fork() is not supported when the runAsNode fuse is disabled; use utilityProcess.fork() instead"`), and Electron's own suggested replacement, `utilityProcess.fork()`, throws synchronously the instant a non-`'ignore'` stdin is requested (`"stdin value other than ignore is not supported."`) — incompatible with this wrapper's NDJSON-over-stdin protocol regardless of fuse state, so neither is a substitute spawn mechanism. `wrapperExecPath` (pointing at a real bundled Node binary) remains the recommended mitigation for a fuse-disabled Electron host — not because it is needed for the process to exit (Part A already guarantees that), but because it avoids the resource cost of booting a full Electron app per dispatch, the same reason this option exists at all when the fuse is enabled. | [src/batteries/llm/claude\_code\_cli/types.ts:400](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L400) | | `baseURL?` | `string` | Forwarded as `ANTHROPIC_BASE_URL`. Valid with either auth mechanism. | [src/batteries/llm/claude\_code\_cli/types.ts:224](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L224) | | `bucketOrder?` | [`ChatCompletionsBucketOrder`](../../../../type-aliases/ChatCompletionsBucketOrder.md) | Determines order of the system-prompt content buckets in history assembly. | [src/batteries/llm/claude\_code\_cli/types.ts:301](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L301) | | `claudeBin?` | `string` | Path to the `claude` binary. Defaults to `'claude'` (resolved via `PATH`). | [src/batteries/llm/claude\_code\_cli/types.ts:212](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L212) | | `contextWindow?` | `number` | Size of the model's token context window for the ADK pre-flight guard. | [src/batteries/llm/claude\_code\_cli/types.ts:236](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L236) | | `cwd?` | `string` | Working directory for the grandchild `claude` process. | [src/batteries/llm/claude\_code\_cli/types.ts:226](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L226) | | `disableErrorReporting?` | `boolean` | Mapped to `DISABLE_ERROR_REPORTING` on the grandchild's env, never a CLI flag. | [src/batteries/llm/claude\_code\_cli/types.ts:264](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L264) | | `disableNonessentialTraffic?` | `boolean` | Mapped to `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` on the grandchild's env, never a CLI flag. | [src/batteries/llm/claude\_code\_cli/types.ts:266](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L266) | | `disableTelemetry?` | `boolean` | Mapped to `DISABLE_TELEMETRY` on the grandchild's env, never a CLI flag. | [src/batteries/llm/claude\_code\_cli/types.ts:262](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L262) | | `disallowedTools?` | `string`\[] | Tool names to exclude from the bridged MCP tool set BEFORE it ever reaches the wrapper — the real enforcement point (see the battery's design notes on why `--allowedTools` cannot do this once `--dangerously-skip-permissions` is set). Never emitted as its own CLI flag. | [src/batteries/llm/claude\_code\_cli/types.ts:234](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L234) | | `disposeGraceMs?` | `number` | Grace period (ms) the graceful-shutdown sequence waits for the wrapper/grandchild to exit before escalating. Default 2000. | [src/batteries/llm/claude\_code\_cli/types.ts:258](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L258) | | `execa?` | [`ExecaResolver`](../type-aliases/ExecaResolver.md) | The `execa` function or an async resolver for it. Defaults to a lazy dynamic import of the `execa` package (optional peer). | [src/batteries/llm/claude\_code\_cli/types.ts:202](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L202) | | `extraArgs?` | [`ClaudeCodeCliExtraArg`](../../wire/interfaces/ClaudeCodeCliExtraArg.md)\[] | A strict, structured allowlist escape hatch for genuinely orthogonal CLI flags (`--effort`/`--agent`/`--betas`/`--json-schema`/`--name`/`--prompt-suggestions`). Validated at options-construction time; never accepts a flag capable of touching tool/permission/MCP/ session-state configuration, and never accepts a value string starting with `-`. | [src/batteries/llm/claude\_code\_cli/types.ts:324](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L324) | | `fallbackModel?` | `string`\[] | Forwarded to `--fallback-model` as one comma-joined value. | [src/batteries/llm/claude\_code\_cli/types.ts:247](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L247) | | `forwardSubagentText?` | `boolean` | Forwarded to `--forward-subagent-text` when true. Default false — subagent text is invisible by default (documented v1 limitation). | [src/batteries/llm/claude\_code\_cli/types.ts:299](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L299) | | `helpers?` | [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype)<[`ClaudeCodeCliHelpers`](ClaudeCodeCliHelpers.md)> | Optional overrides for the translation helpers. | [src/batteries/llm/claude\_code\_cli/types.ts:307](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L307) | | `maxBudgetUsd?` | `number` | Forwarded to `--max-budget-usd`. Always available. | [src/batteries/llm/claude\_code\_cli/types.ts:245](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L245) | | ~~`maxTurns?`~~ | `number` | **Deprecated** Single-turn dispatch is the fixed battery contract. Only `1` is accepted; the option is ignored because argv always carries `--max-turns 1`. | [src/batteries/llm/claude\_code\_cli/types.ts:243](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L243) | | `mcpToolIdleTimeoutMs?` | `number` | Mapped to `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` on the grandchild's env, never a CLI flag. Default unset (falls through to the CLI's own 5-minute default). | [src/batteries/llm/claude\_code\_cli/types.ts:260](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L260) | | `model` | `string` | Required. The Claude model identifier, forwarded to `--model`. | [src/batteries/llm/claude\_code\_cli/types.ts:249](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L249) | | `replayCompatibility?` | readonly `string`\[] | List of replay labels supported by the assistant. | [src/batteries/llm/claude\_code\_cli/types.ts:305](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L305) | | `selfIdentity?` | `string` | Unique identity label for the assistant instance. | [src/batteries/llm/claude\_code\_cli/types.ts:268](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L268) | | `spoolStore?` | [`SpoolStore`](../../../../../common/type-aliases/SpoolStore.md) | Backing store for spooled tool results; defaults to a per-dispatch in-memory store. | [src/batteries/llm/claude\_code\_cli/types.ts:309](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L309) | | `startupTimeoutMs?` | `number` | Adapter-side startup watchdog (ms), spanning from the wrapper's spawn through BOTH the wrapper's own `ready` event AND Claude's `system/init` stream-json event. Default 45\_000. | [src/batteries/llm/claude\_code\_cli/types.ts:256](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L256) | | `streamIdleTimeoutMs?` | `number` | Adapter-side, ADK-owned stream-idle watchdog (ms). Reset on every raw stdout byte from the wrapper. Default 60\_000. | [src/batteries/llm/claude\_code\_cli/types.ts:251](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L251) | | `thoughtSurfacing?` | `"all"` | `"all-self"` | `"latest-self"` | Determines which thoughts are surfaced back to the model. | [src/batteries/llm/claude\_code\_cli/types.ts:303](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L303) | | `tokenEncoding?` | | [`TokenEncodingId`](../../../../../type-aliases/TokenEncodingId.md) | `null` | Tokenizer encoding configuration for token counting. | [src/batteries/llm/claude\_code\_cli/types.ts:238](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L238) | | `toolCallIdFilter?` | [`ToolCallIdFilterFn`](../../../../type-aliases/ToolCallIdFilterFn.md) | Ingress hook for adapting the wrapper's per-spawn `requestId` into the ADK-facing tool-call id. **Remarks** Unlike every other Chat-family battery (where this hook is opt-in and its absence means pass-through), this battery's wrapper protocol resets its `requestId` counter to `"0"` on EVERY spawn (see `mcp_bridge.ts`), and a fresh wrapper is spawned per dispatch ITERATION — so a multi-iteration turn structurally guarantees a same-id collision the moment a second tool-calling iteration occurs, not merely as a vendor/model quirk. Concretely, a same-id collision trips one of two DIFFERENT id-tracking structures depending on the shape of the turn: `DispatchExecutorHelpers.reportToolCall`'s own internal per-dispatch bookkeeping (an id -> stream-state map local to `dispatch_runner.ts`'s `#buildHelpers`, which throws `tool call "" is already complete` on a duplicate) if the earlier call with that id already completed within the SAME dispatch's helpers instance; or `ctx.turnToolCalls` (the `Set` `deCollideToolCallIds` itself inspects to pick a fresh id) if the collision is against a call recorded in an EARLIER iteration of the same turn. These are two distinct pieces of state, not one — this option's default only needs to satisfy the second, since @nhtio/adk!deCollideToolCallIds renames the id BEFORE it ever reaches `reportToolCall`, which is what prevents both. Left unset, this defaults to @nhtio/adk!deCollideToolCallIds — NOT identity pass-through — so the crash this option exists to prevent cannot happen by omission; set an explicit filter (or `(id) => id` to opt back into raw pass-through) only if a different id strategy is required. The wrapper's OWN `requestId` (used to correlate the `tool_call_response` written back over the wire) is never affected by this hook — only the ADK-facing `ToolCall.id`/`callId` are renamed. | [src/batteries/llm/claude\_code\_cli/types.ts:295](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L295) | | `unsupportedMediaPolicy?` | [`UnsupportedMediaPolicy`](../../../transformers_js/type-aliases/UnsupportedMediaPolicy.md) | Policy for handling a [@nhtio/adk!Media](../../../../../common/classes/Media.md) whose modality cannot be represented in the INBOUND (`-p` prompt) direction. | [src/batteries/llm/claude\_code\_cli/types.ts:311](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L311) | | `unsupportedResultMediaPolicy?` | [`UnsupportedMediaPolicy`](../../../transformers_js/type-aliases/UnsupportedMediaPolicy.md) | Policy for handling a [@nhtio/adk!Media](../../../../../common/classes/Media.md) whose modality cannot be represented in the OUTBOUND (MCP tool-result) direction. A real, independently-settable branch — defaults to the same value as `unsupportedMediaPolicy` when omitted, but can diverge. | [src/batteries/llm/claude\_code\_cli/types.ts:317](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L317) | | `wrapperEnv?` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string` | `undefined`> | Additional environment variables merged into the wrapper's spawn env, applied AFTER `autoDetectElectronHost`'s own `ELECTRON_RUN_AS_NODE` default — so a key set here (including explicit `undefined`, which deletes the key from the child's env entirely) always wins over that default. Everything else about the parent's own `process.env` is inherited as-is (execa's normal behavior); this is only for additions/overrides, not a replacement env map. | [src/batteries/llm/claude\_code\_cli/types.ts:352](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L352) | | `wrapperExecPath?` | `string` | Overrides the executable spawned for the wrapper process. Defaults to `process.execPath` — on an Electron main process (issue #42), `process.execPath` there is the Electron binary itself, not a Node binary, so spawning it boots a copy of Electron rather than plain Node unless `ELECTRON_RUN_AS_NODE` is both set (see `autoDetectElectronHost`) AND honored — which it is not once the host's packaged binary has its `RunAsNode` Fuse disabled; the env var is silently ignored in that case and the spawned copy boots as a full Electron app regardless. As of issue #42 Part A, this no longer affects whether the wrapper exits cleanly (it always does, via an explicit `process.exit(0)`) — it only affects resource cost: a full Electron app boots GPU/ network/renderer utility processes the wrapper never needed, for every dispatch. Set this to an actual Node binary path (e.g. one a consumer bundles alongside their Electron app specifically to run this battery) to avoid that cost — most valuable when `process.versions.electron` is set AND the host's fuse is disabled, since `autoDetectElectronHost`'s own `ELECTRON_RUN_AS_NODE` mitigation cannot help at all in that specific case (see its own doc comment for the measured evidence), but worthwhile even with the fuse enabled if avoiding the Electron-boot cost matters more than the small code-path difference. Has no effect on the `claude` grandchild binary itself (`claudeBin`), only on the wrapper's own host process. | [src/batteries/llm/claude\_code\_cli/types.ts:344](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L344) | | `wrapperPath?` | `string` | Overridable path to the built wrapper asset. Defaults to `resolveDefaultWrapperPath()`, falling back to a package-self-reference lookup if that path does not exist on disk (e.g. this adapter was bundled by a consumer, relocating it outside `@nhtio/adk`'s own directory tree). Set this explicitly if both of those fail — surfaced as [@nhtio/adk/batteries/llm/claude\_code\_cli!E\_CLAUDE\_CODE\_CLI\_WRAPPER\_NOT\_FOUND](../../exceptions/variables/E_CLAUDE_CODE_CLI_WRAPPER_NOT_FOUND.md). | [src/batteries/llm/claude\_code\_cli/types.ts:210](https://github.com/NHTIO/ADK/blob/v1.20261003.0/src/src/batteries/llm/claude_code_cli/types.ts#L210) |