Struct Options 

pub struct Options {

    pub binary: String,
    pub cwd: Option<PathBuf>,
    pub resume: Option<String>,
    pub model: Option<String>,
    pub permission_mode: PermissionMode,
    pub can_use_tool: Option<Arc<dyn CanUseToolCallback>>,
    pub auto_approve_tool: Option<Arc<dyn Fn(&str) -> bool + Send + Sync>>,
    pub mcp_servers: Vec<(String, McpServer)>,
    pub external_mcp_servers: HashMap<String, McpServerConfig>,
    pub hooks: Hooks,
    pub allowed_tools: Vec<String>,
    pub permission_prompt_tool_name: Option<String>,
    pub minimum_cli_version: Option<String>,
    pub system_prompt: Option<SystemPromptKind>,
    pub max_turns: Option<u64>,
    pub session_id: Option<String>,
    pub plugins: Vec<SdkPluginConfig>,
    pub env: HashMap<String, String>,
    pub extra_args: HashMap<String, Option<String>>,
    pub effort: Option<SubagentEffort>,
    pub tee_inbound: Option<Arc<dyn Fn(&str) + Send + Sync>>,
    pub tee_outbound: Option<Arc<dyn Fn(&str) + Send + Sync>>,
}

Configuration for one Client invocation.

Construct via OptionsBuilder rather than populating directly.

Fields

binary: String

Path or name of the claude binary to spawn.

cwd: Option<PathBuf>

Working directory for the subprocess. None → inherit current cwd.

resume: Option<String>

Session id to resume. Passed as --resume <id>. None → new session.

model: Option<String>

Model name. Passed as --model <name>. None → binary default.

permission_mode: PermissionMode

Permission flow.

can_use_tool: Option<Arc<dyn CanUseToolCallback>>

Optional permission callback. When set, the claude binary asks this callback before invoking any tool.

auto_approve_tool: Option<Arc<dyn Fn(&str) -> bool + Send + Sync>>

Optional auto-approve predicate. When the CLI asks via can_use_tool whether a particular tool can run, forge-sdk consults this predicate first; tools that match are auto-approved without invoking the can_use_tool callback. Caller (forge-workspace via forge-agent) typically supplies a closure that auto-approves any tool whose name starts with the mcp__<server>__ prefix of one of its in-process MCP servers (e.g. mcp__forge__agents__whoami) - those servers are already opted into by the user’s forge.toml so a permission prompt would just be noise.

mcp_servers: Vec<(String, McpServer)>

In-process MCP servers. Each entry maps a server name (used in the mcp__<server>__<tool> prefix the model sees) to a built McpServer.

external_mcp_servers: HashMap<String, McpServerConfig>

External MCP servers - stdio / SSE / HTTP. Mirrors the non-SDK variants of the CLI’s ClaudeAgentOptions.mcp_servers . Registered alongside in-process servers in the --mcp-config JSON.

hooks: Hooks

Registered hooks. Empty by default.

allowed_tools: Vec<String>

Tool names the model is allowed to invoke. Passed to the CLI as --allowedTools <comma,list>. Empty means “no explicit allowlist”.

permission_prompt_tool_name: Option<String>

Orthogonal permission-prompt tool. When set, passed as --permission-prompt-tool <name>.

minimum_cli_version: Option<String>

Minimum claude binary version required. Default >= 2.0.0. When Some, Client::spawn runs <binary> --version once and checks the reported major version is at least the first component.

system_prompt: Option<SystemPromptKind>

System prompt configuration. None = inherit CLI default. Some emits --system-prompt, --system-prompt-file, or --append-system-prompt depending on variant.

max_turns: Option<u64>

Turn limit. --max-turns <n>.

session_id: Option<String>

Explicit session id for a new session (distinct from resume). --session-id <id>.

plugins: Vec<SdkPluginConfig>

Local plugins. Wire shape: list[SdkPluginConfig].

env: HashMap<String, String>

Environment variables added to the subprocess env.

extra_args: HashMap<String, Option<String>>

Arbitrary forward flags - {"flag": Some("v")} emits --flag v, {"flag": None} emits a bare --flag.

effort: Option<SubagentEffort>

Reasoning-effort hint. --effort <level> - the CLI’s effort is a literal-or-integer carried via SubagentEffort (named for its origin on the subagent declaration shape, but the session-level effort uses the same wire enum).

tee_inbound: Option<Arc<dyn Fn(&str) + Send + Sync>>

Inbound wire tee. When set, the SDK invokes callback(line) for every stream-json line read from the subprocess stdout BEFORE decoding. Used by forge-test-harness to capture the raw wire bytes for conformance baselines. The callback receives lines without a trailing newline.

tee_outbound: Option<Arc<dyn Fn(&str) + Send + Sync>>

Outbound wire tee. When set, the SDK invokes callback(line) for every stream-json line about to be written to the subprocess stdin. Counterpart to tee_inbound. The callback receives lines without a trailing newline (the SDK strips it before invoking).

Trait Implementations

impl Clone for Options

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Options

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

Formats the value using the given formatter.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.