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
| 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 |
apiKey? | string | Forwarded as ANTHROPIC_API_KEY. Exactly one of apiKey/authToken must be set. | src/batteries/llm/claude_code_cli/types.ts:220 |
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 |
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 |
autoAck? | boolean | Whether the executor acks automatically on a tool-call-free terminal answer. | src/batteries/llm/claude_code_cli/types.ts:297 |
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 |
baseURL? | string | Forwarded as ANTHROPIC_BASE_URL. Valid with either auth mechanism. | src/batteries/llm/claude_code_cli/types.ts:224 |
bucketOrder? | ChatCompletionsBucketOrder | Determines order of the system-prompt content buckets in history assembly. | src/batteries/llm/claude_code_cli/types.ts:301 |
claudeBin? | string | Path to the claude binary. Defaults to 'claude' (resolved via PATH). | src/batteries/llm/claude_code_cli/types.ts:212 |
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 |
cwd? | string | Working directory for the grandchild claude process. | src/batteries/llm/claude_code_cli/types.ts:226 |
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 |
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 |
disableTelemetry? | boolean | Mapped 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? | 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 |
execa? | ExecaResolver | 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 |
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? | 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 |
helpers? | Partial<ClaudeCodeCliHelpers> | Optional overrides for the translation helpers. | src/batteries/llm/claude_code_cli/types.ts:307 |
maxBudgetUsd? | number | Forwarded to --max-budget-usd. Always available. | src/batteries/llm/claude_code_cli/types.ts:245 |
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 |
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 |
model | string | Required. 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? | string | Unique identity label for the assistant instance. | src/batteries/llm/claude_code_cli/types.ts:268 |
spoolStore? | SpoolStore | Backing store for spooled tool results; defaults to a per-dispatch in-memory store. | src/batteries/llm/claude_code_cli/types.ts:309 |
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 |
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 |
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 | null | Tokenizer encoding configuration for token counting. | src/batteries/llm/claude_code_cli/types.ts:238 |
toolCallIdFilter? | ToolCallIdFilterFn | 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 "<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? | UnsupportedMediaPolicy | Policy 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? | UnsupportedMediaPolicy | Policy 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? | 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 |
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. | src/batteries/llm/claude_code_cli/types.ts:210 |