Skip to main content

SessionOptions

Struct SessionOptions 

Source
pub struct SessionOptions {
Show 56 fields pub binary: PathBuf, pub cwd: Option<PathBuf>, pub model: Option<String>, pub effort: Option<Effort>, pub permission_mode: Option<PermissionMode>, pub fallback_model: Option<String>, pub thinking: Option<Thinking>, pub thinking_display: Option<ThinkingDisplay>, pub max_thinking_tokens: Option<u32>, pub max_turns: Option<u32>, pub max_budget_usd: Option<f64>, pub task_budget: Option<u32>, pub resume: Option<String>, pub resume_session_at: Option<String>, pub continue_conversation: bool, pub fork_session: bool, pub session_id: Option<String>, pub persist_session: bool, pub name: Option<String>, pub code_mode: bool, pub tool_search: bool, pub include_partial: bool, pub hooks: HookRegistry, pub can_use_tool: Option<CanUseTool>, pub mcp_servers: Vec<SdkMcpServer>, pub allowed_tools: Vec<String>, pub disallowed_tools: Vec<String>, pub tools: Option<Vec<String>>, pub add_dirs: Vec<PathBuf>, pub strict_mcp_config: bool, pub agent: Option<String>, pub append_subagent_system_prompt: Option<String>, pub plugin_dirs: Vec<PathBuf>, pub betas: Vec<String>, pub debug_file: Option<PathBuf>, pub plugin_urls: Vec<String>, pub files: Vec<String>, pub autocompact: Option<Autocompact>, pub permission_prompts: Option<PermissionPrompts>, pub worktree: Option<Option<String>>, pub bare: bool, pub safe_mode: bool, pub restricted: bool, pub disable_slash_commands: bool, pub brief: bool, pub include_hook_events: bool, pub extra_args: Vec<String>, pub control_timeout: Duration, pub on_elicitation: Option<OnElicitation>, pub on_user_dialog: Option<OnUserDialog>, pub on_stderr: Option<OnStderr>, pub setting_sources: Option<Vec<String>>, pub settings: Option<Value>, pub record: Option<PathBuf>, pub clear_env: bool, pub env: Vec<(String, String)>,
}
Expand description

How to spawn and configure the CLI process.

Fields§

§binary: PathBuf

Path of the claude executable. Default: claude (looked up on PATH).

§cwd: Option<PathBuf>

Working directory of the CLI process. None = inherit.

§model: Option<String>

--model

§effort: Option<Effort>

--effort. None = CLI default.

§permission_mode: Option<PermissionMode>

--permission-mode

§fallback_model: Option<String>

--fallback-model: models to try, in order, when the main model is busy or unavailable (AgentEvent::ModelFallback reports a switch).

§thinking: Option<Thinking>

--thinking.

§thinking_display: Option<ThinkingDisplay>

--thinking-display.

§max_thinking_tokens: Option<u32>

--max-thinking-tokens (older models; newer ones use thinking/effort).

§max_turns: Option<u32>

--max-turns: a turn stops with TurnErrorKind::MaxTurns after this many agentic turns.

§max_budget_usd: Option<f64>

--max-budget-usd: a turn stops with TurnErrorKind::MaxBudget once the session has spent this much.

§task_budget: Option<u32>

--task-budget: API-side task budget in tokens.

§resume: Option<String>

--resume <id>: continue an existing session’s transcript.

§resume_session_at: Option<String>

--resume-session-at <message id>: with resume, keep the transcript only up to this message.

§continue_conversation: bool

--continue: continue the most recent conversation in cwd.

§fork_session: bool

--fork-session: with resume/continue_conversation, continue in a new session id instead of appending to the old transcript.

§session_id: Option<String>

--session-id: use this UUID as the session id.

§persist_session: bool

false adds --no-session-persistence: no transcript is written, so the session cannot be resumed.

§name: Option<String>

--name: display name of the session.

§code_mode: bool

Force Code Mode on: Claude gets the REPL tool and works by writing JavaScript that calls its tools. The stock CLI refuses Code Mode for SDK sessions, so this runs a patched copy of binary, built once and cached (see code_mode module); the installed CLI is not modified.

§tool_search: bool

Enable tool search: sets ENABLE_TOOL_SEARCH=1. Source: chunk-dnmy4w56.js:189

§include_partial: bool

Stream partial chunks (--include-partial-messages).

§hooks: HookRegistry

Hook handlers, sent to the CLI in the initialize request.

§can_use_tool: Option<CanUseTool>

Tool-permission handler; adds --permission-prompt-tool stdio. Source: subprocess_cli.py:218

§mcp_servers: Vec<SdkMcpServer>

In-process tool servers. Their tools are added to allowed_tools automatically: the host defined them, so asking permission is noise.

§allowed_tools: Vec<String>

--allowedTools: tools that run without a permission prompt.

§disallowed_tools: Vec<String>

--disallowedTools: tools removed from the model’s toolset.

§tools: Option<Vec<String>>

--tools: the built-in tools available. Some(vec![]) = none, None = all.

§add_dirs: Vec<PathBuf>

--add-dir: extra directories tools may access.

§strict_mcp_config: bool

--strict-mcp-config: ignore MCP servers from settings files.

§agent: Option<String>

--agent: run the session as this agent.

§append_subagent_system_prompt: Option<String>

--append-subagent-system-prompt: appended to every subagent’s system prompt.

§plugin_dirs: Vec<PathBuf>

--plugin-dir: load plugins from these directories.

§betas: Vec<String>

--betas: API beta headers.

§debug_file: Option<PathBuf>

--debug-file: write the CLI’s debug log here.

§plugin_urls: Vec<String>

--plugin-url: fetch plugin .zip files for this session only.

§files: Vec<String>

--file: files to download at startup, as file_id:relative_path.

§autocompact: Option<Autocompact>

--autocompact: auto-compact window.

§permission_prompts: Option<PermissionPrompts>

--permission-prompts: who answers permission prompts.

§worktree: Option<Option<String>>

--worktree: run in a new git worktree; Some(None) names it automatically.

§bare: bool

--bare: minimal mode (no settings/plugin hooks, LSP, plugin sync, …).

§safe_mode: bool

--safe-mode: start with every customization off (CLAUDE.md, skills, plugins, hooks, MCP servers, …).

§restricted: bool

--restricted: remove the built-in tools that run commands or code, and WebFetch, unless tools names them.

§disable_slash_commands: bool

--disable-slash-commands: no skills or commands.

§brief: bool

--brief: give Claude the SendUserMessage tool.

§include_hook_events: bool

--include-hook-events: emit hook lifecycle frames (AgentEvent::System).

§extra_args: Vec<String>

Extra CLI arguments, appended verbatim — for flags this struct does not name.

§control_timeout: Duration

How long Session::control waits for the CLI’s answer.

§on_elicitation: Option<OnElicitation>

Answers MCP elicitations.

§on_user_dialog: Option<OnUserDialog>

Renders request_user_dialog dialogs.

§on_stderr: Option<OnStderr>

Receives CLI stderr lines live (the last lines are also kept for SessionError::ProcessExited).

§setting_sources: Option<Vec<String>>

--setting-sources: which settings files to load (“user”, “project”, “local”). Some(vec![]) loads none — the session ignores the user’s global CLAUDE.md, skills, permission rules and hooks, and turns get much cheaper. None = CLI default (all). Source: subprocess_cli.py:275–280

§settings: Option<Value>

--settings: inline settings object (permissions, env, shell hooks, …), or a string: path of a settings file (relative to cwd). With code_mode the file is read and passed inline with the Code Mode env var.

§record: Option<PathBuf>

Write every stdout line to this JSONL file, for replay::replay.

§clear_env: bool

Start the CLI with an empty environment plus env only. The CLI then needs at least HOME and PATH (and credentials) passed through env. false (default) inherits the parent environment, like the official SDKs.

§env: Vec<(String, String)>

Extra env vars passed to the subprocess.

Trait Implementations§

Source§

impl Clone for SessionOptions

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for SessionOptions

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for SessionOptions

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more