Struct ClientConfig 

pub struct ClientConfig {

    pub prompt: String,
    pub cli_path: Option<PathBuf>,
    pub cwd: Option<PathBuf>,
    pub model: Option<String>,
    pub fallback_model: Option<String>,
    pub system_prompt: Option<SystemPrompt>,
    pub max_turns: Option<u32>,
    pub max_budget_usd: Option<f64>,
    pub max_thinking_tokens: Option<u32>,
    pub allowed_tools: Vec<String>,
    pub disallowed_tools: Vec<String>,
    pub permission_mode: PermissionMode,
    pub can_use_tool: Option<CanUseToolCallback>,
    pub resume: Option<String>,
    pub hooks: Vec<HookMatcher>,
    pub mcp_servers: McpServers,
    pub message_callback: Option<MessageCallback>,
    pub env: HashMap<String, String>,
    pub verbose: bool,
    pub output_format: String,
    pub extra_args: BTreeMap<String, Option<String>>,
    pub connect_timeout: Option<Duration>,
    pub close_timeout: Option<Duration>,
    pub read_timeout: Option<Duration>,
    pub default_hook_timeout: Duration,
    pub version_check_timeout: Option<Duration>,
    pub cancellation_token: Option<CancellationToken>,
    pub stderr_callback: Option<Arc<dyn Fn(String) + Send + Sync>>,
}

Configuration for a Claude Code SDK client session.

Use ClientConfig::builder() to construct.

Fields

prompt: String

The prompt text to send to Claude.

cli_path: Option<PathBuf>

Path to the Claude CLI binary. If None, auto-discovered via find_cli().

cwd: Option<PathBuf>

Working directory for the Claude process.

model: Option<String>

Model to use (e.g., "claude-sonnet-4-5").

fallback_model: Option<String>

Fallback model if the primary is unavailable.

system_prompt: Option<SystemPrompt>

System prompt configuration.

max_turns: Option<u32>

Maximum number of agentic turns before stopping.

max_budget_usd: Option<f64>

Maximum USD budget for the session.

max_thinking_tokens: Option<u32>

Maximum thinking tokens per turn.

allowed_tools: Vec<String>

Explicitly allowed tool names.

disallowed_tools: Vec<String>

Explicitly disallowed tool names.

permission_mode: PermissionMode

Permission mode for the session.

can_use_tool: Option<CanUseToolCallback>

Callback invoked when the CLI requests tool use permission.

resume: Option<String>

Resume an existing session by ID.

hooks: Vec<HookMatcher>

Lifecycle hooks to register for the session.

mcp_servers: McpServers

External MCP server configurations.

message_callback: Option<MessageCallback>

Optional message callback for observe/filter.

env: HashMap<String, String>

Extra environment variables to pass to the CLI process.

verbose: bool

Enable verbose (debug) output from the CLI.

output_format: String

Output format. Defaults to "json" for SDK use.

extra_args: BTreeMap<String, Option<String>>

Arbitrary extra CLI flags to pass through to the Claude process.

Keys are flag names (without the -- prefix). Values are optional:

• Some("value") produces --key value
• None produces --key (boolean-style flag)

Uses BTreeMap to guarantee deterministic CLI arg ordering across invocations (important for reproducible test snapshots).

Example

use std::collections::BTreeMap;
use claude_cli_sdk::ClientConfig;

let config = ClientConfig::builder()
    .prompt("hello")
    .extra_args(BTreeMap::from([
        ("replay-user-messages".into(), None),
        ("context-window".into(), Some("200000".into())),
    ]))
    .build();

connect_timeout: Option<Duration>

Deadline for process spawn + init message. None = wait forever.

Default: Some(30s).

close_timeout: Option<Duration>

Deadline for child.wait() during close. On expiry the process is killed. None = wait forever.

Default: Some(10s).

read_timeout: Option<Duration>

Per-message recv deadline. None = wait forever (default).

This is for detecting hung/zombie processes, not for limiting turn time — Claude turns can legitimately take minutes.

default_hook_timeout: Duration

Fallback timeout for hook callbacks when HookMatcher::timeout is None.

Default: 30 seconds.

version_check_timeout: Option<Duration>

Deadline for the --version check in check_cli_version(). None = wait forever.

Default: Some(5s).

cancellation_token: Option<CancellationToken>

Optional cancellation token for cooperative cancellation.

When cancelled, in-flight streams yield Error::Cancelled and the background reader task shuts down cleanly.

stderr_callback: Option<Arc<dyn Fn(String) + Send + Sync>>

Optional callback for CLI stderr output.

Implementations

impl ClientConfig

pub fn builder() -> ClientConfigBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building ClientConfig. On the builder, call .prompt(...), .cli_path(...)(optional), .cwd(...)(optional), .model(...)(optional), .fallback_model(...)(optional), .system_prompt(...)(optional), .max_turns(...)(optional), .max_budget_usd(...)(optional), .max_thinking_tokens(...)(optional), .allowed_tools(...)(optional), .disallowed_tools(...)(optional), .permission_mode(...)(optional), .can_use_tool(...)(optional), .resume(...)(optional), .hooks(...)(optional), .mcp_servers(...)(optional), .message_callback(...)(optional), .env(...)(optional), .verbose(...)(optional), .output_format(...)(optional), .extra_args(...)(optional), .connect_timeout(...)(optional), .close_timeout(...)(optional), .read_timeout(...)(optional), .default_hook_timeout(...)(optional), .version_check_timeout(...)(optional), .cancellation_token(...)(optional), .stderr_callback(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of ClientConfig.

impl ClientConfig

pub fn validate(&self) -> Result<()>

Validate the configuration, returning an error for invalid settings.

Checks:

• If cwd is set, it must exist and be a directory.

This is called automatically by Client::new().

pub fn to_cli_args(&self) -> Vec<String>

Build the CLI argument list for spawning the Claude process.

This does NOT include the binary path itself — just the arguments.

pub fn to_env(&self) -> HashMap<String, String>

Build the environment variable map for the CLI process.

Merges SDK defaults with self.env (user-supplied env takes precedence) and any SDK-internal env vars.

SDK defaults:

• CLAUDE_CODE_SDK_ORIGINATOR=claude_cli_sdk_rs — telemetry originator
• CI=true — headless mode (suppress interactive prompts)
• TERM=dumb — prevent ANSI escape sequences in output

Trait Implementations

impl Debug for ClientConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.