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)>,
}Fields§
§binary: PathBuf§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: boolfalse 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: boolForce 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: boolEnable tool search: sets ENABLE_TOOL_SEARCH=1. Source: chunk-dnmy4w56.js:189
include_partial: boolStream partial chunks (--include-partial-messages).
hooks: HookRegistryHook 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: DurationHow 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: boolStart 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.