Skip to content
10 min read · 2,027 words

Interface: ClaudeCodeCliAdapterOptions ​

Defined in: src/batteries/llm/claude_code_cli/types.ts:199

Configuration options for the @nhtio/adk/batteries/llm/claude_code_cli!ClaudeCodeCliAdapter.

Properties ​

PropertyTypeDescriptionDefined in
addDir?string[]Additional directories to allow tool access to, forwarded to --add-dir.src/batteries/llm/claude_code_cli/types.ts:228
apiKey?stringForwarded as ANTHROPIC_API_KEY. Exactly one of apiKey/authToken must be set.src/batteries/llm/claude_code_cli/types.ts:220
appendSystemPrompt?stringForwarded 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
authToken?stringForwarded 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
autoAck?booleanWhether the executor acks automatically on a tool-call-free terminal answer.src/batteries/llm/claude_code_cli/types.ts:297
autoDetectElectronHost?booleanWhether 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
baseURL?stringForwarded as ANTHROPIC_BASE_URL. Valid with either auth mechanism.src/batteries/llm/claude_code_cli/types.ts:224
bucketOrder?ChatCompletionsBucketOrderDetermines order of the system-prompt content buckets in history assembly.src/batteries/llm/claude_code_cli/types.ts:301
claudeBin?stringPath to the claude binary. Defaults to 'claude' (resolved via PATH).src/batteries/llm/claude_code_cli/types.ts:212
contextWindow?numberSize of the model's token context window for the ADK pre-flight guard.src/batteries/llm/claude_code_cli/types.ts:236
cwd?stringWorking directory for the grandchild claude process.src/batteries/llm/claude_code_cli/types.ts:226
disableErrorReporting?booleanMapped to DISABLE_ERROR_REPORTING on the grandchild's env, never a CLI flag.src/batteries/llm/claude_code_cli/types.ts:264
disableNonessentialTraffic?booleanMapped to CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC on the grandchild's env, never a CLI flag.src/batteries/llm/claude_code_cli/types.ts:266
disableTelemetry?booleanMapped to DISABLE_TELEMETRY on the grandchild's env, never a CLI flag.src/batteries/llm/claude_code_cli/types.ts:262
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
disposeGraceMs?numberGrace 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
execa?ExecaResolverThe 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
extraArgs?ClaudeCodeCliExtraArg[]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
fallbackModel?string[]Forwarded to --fallback-model as one comma-joined value.src/batteries/llm/claude_code_cli/types.ts:247
forwardSubagentText?booleanForwarded 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
helpers?Partial<ClaudeCodeCliHelpers>Optional overrides for the translation helpers.src/batteries/llm/claude_code_cli/types.ts:307
maxBudgetUsd?numberForwarded to --max-budget-usd. Always available.src/batteries/llm/claude_code_cli/types.ts:245
maxTurns?numberDeprecated 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
mcpToolIdleTimeoutMs?numberMapped 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
modelstringRequired. The Claude model identifier, forwarded to --model.src/batteries/llm/claude_code_cli/types.ts:249
replayCompatibility?readonly string[]List of replay labels supported by the assistant.src/batteries/llm/claude_code_cli/types.ts:305
selfIdentity?stringUnique identity label for the assistant instance.src/batteries/llm/claude_code_cli/types.ts:268
spoolStore?SpoolStoreBacking store for spooled tool results; defaults to a per-dispatch in-memory store.src/batteries/llm/claude_code_cli/types.ts:309
startupTimeoutMs?numberAdapter-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
streamIdleTimeoutMs?numberAdapter-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
thoughtSurfacing?"all" | "all-self" | "latest-self"Determines which thoughts are surfaced back to the model.src/batteries/llm/claude_code_cli/types.ts:303
tokenEncoding?| TokenEncodingId | nullTokenizer encoding configuration for token counting.src/batteries/llm/claude_code_cli/types.ts:238
toolCallIdFilter?ToolCallIdFilterFnIngress 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 "<id>" 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<ToolCall> 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
unsupportedMediaPolicy?UnsupportedMediaPolicyPolicy for handling a @nhtio/adk!Media whose modality cannot be represented in the INBOUND (-p prompt) direction.src/batteries/llm/claude_code_cli/types.ts:311
unsupportedResultMediaPolicy?UnsupportedMediaPolicyPolicy for handling a @nhtio/adk!Media 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
wrapperEnv?Record<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
wrapperExecPath?stringOverrides 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
wrapperPath?stringOverridable 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.src/batteries/llm/claude_code_cli/types.ts:210