Struct Options 

pub struct Options {

    pub allowed_tools: Vec<String>,
    pub disallowed_tools: Vec<String>,
    pub permission_mode: PermissionMode,
    pub can_use_tool: Option<CanUseToolFn>,
    pub cwd: Option<String>,
    pub model: Option<String>,
    pub fallback_model: Option<String>,
    pub effort: Option<Effort>,
    pub max_turns: Option<u32>,
    pub max_budget_usd: Option<f64>,
    pub context_budget: Option<u64>,
    pub compaction_model: Option<String>,
    pub compaction_provider: Option<Box<dyn LlmProvider>>,
    pub system_prompt: Option<SystemPrompt>,
    pub thinking: Option<ThinkingConfig>,
    pub hooks: HashMap<HookEvent, Vec<HookCallbackMatcher>>,
    pub hook_dirs: Vec<PathBuf>,
    pub mcp_servers: HashMap<String, McpServerConfig>,
    pub agents: HashMap<String, AgentDefinition>,
    pub continue_session: bool,
    pub resume: Option<String>,
    pub fork_session: bool,
    pub session_id: Option<String>,
    pub setting_sources: Vec<SettingSource>,
    pub debug: bool,
    pub debug_file: Option<String>,
    pub include_partial_messages: bool,
    pub persist_session: bool,
    pub enable_file_checkpointing: bool,
    pub env: HashMap<String, String>,
    pub additional_directories: Vec<String>,
    pub env_blocklist: Vec<String>,
    pub output_format: Option<Value>,
    pub sandbox: Option<SandboxSettings>,
    pub tool_config: Option<ToolConfig>,
    pub plugins: Vec<PluginConfig>,
    pub prompt_suggestions: bool,
    pub external_tool_handler: Option<ExternalToolHandlerFn>,
    pub custom_tool_definitions: Vec<CustomToolDefinition>,
    pub followup_rx: Option<UnboundedReceiver<String>>,
    pub api_key: Option<String>,
    pub attachments: Vec<QueryAttachment>,
    pub provider: Option<Box<dyn LlmProvider>>,
    pub pre_compact_handler: Option<PreCompactHandlerFn>,
    pub max_tokens: Option<u32>,
    pub summary_max_tokens: Option<u32>,
    pub min_keep_messages: Option<usize>,
    pub max_tool_result_bytes: Option<usize>,
    pub prune_threshold_pct: Option<u8>,
    pub prune_tool_result_max_chars: Option<usize>,
}

Configuration options for a query.

Fields

allowed_tools: Vec<String>

Tools to auto-approve without prompting.

disallowed_tools: Vec<String>

Tools to always deny.

permission_mode: PermissionMode

Permission mode for the session.

can_use_tool: Option<CanUseToolFn>

Custom permission function for tool usage.

cwd: Option<String>

Current working directory.

model: Option<String>

Claude model to use.

fallback_model: Option<String>

Fallback model if primary fails.

effort: Option<Effort>

Controls reasoning depth.

max_turns: Option<u32>

Maximum agentic turns (tool-use round trips).

max_budget_usd: Option<f64>

Maximum budget in USD.

context_budget: Option<u64>

Context budget in tokens. When input_tokens from the API response exceeds this threshold, older messages are compacted into a summary. Recommended: ~80% of the model’s context window (e.g. 160_000 for 200k).

compaction_model: Option<String>

Model to use for generating compaction summaries. Falls back to the primary model if the compaction call fails.

compaction_provider: Option<Box<dyn LlmProvider>>

Optional separate LLM provider for compaction (e.g. use Anthropic for compaction while the primary provider is OpenAI). If None, the primary provider is used.

system_prompt: Option<SystemPrompt>

System prompt configuration.

thinking: Option<ThinkingConfig>

Thinking configuration.

hooks: HashMap<HookEvent, Vec<HookCallbackMatcher>>

Hook callbacks for events.

hook_dirs: Vec<PathBuf>

Directories to scan for HOOK.md-based hooks. Discovered hooks are merged into the programmatic hooks map at query time.

mcp_servers: HashMap<String, McpServerConfig>

MCP server configurations.

agents: HashMap<String, AgentDefinition>

Programmatically defined subagents.

continue_session: bool

Continue the most recent conversation.

resume: Option<String>

Session ID to resume.

fork_session: bool

Fork session when resuming.

session_id: Option<String>

Use a specific UUID for the session.

setting_sources: Vec<SettingSource>

Control which filesystem settings to load.

debug: bool

Enable debug mode.

debug_file: Option<String>

Write debug logs to a specific file.

include_partial_messages: bool

Include partial message events.

persist_session: bool

When false, disables session persistence to disk.

enable_file_checkpointing: bool

Enable file change tracking for rewinding.

env: HashMap<String, String>

Environment variables.

additional_directories: Vec<String>

Additional directories Claude can access.

env_blocklist: Vec<String>

Environment variable names to strip from child processes (e.g. Bash). These keys will be removed via env_remove when spawning subprocesses, preventing the agent from reading them through shell commands.

output_format: Option<Value>

Structured output schema.

sandbox: Option<SandboxSettings>

Sandbox settings.

tool_config: Option<ToolConfig>

Tool configuration.

plugins: Vec<PluginConfig>

Plugin configurations.

prompt_suggestions: bool

Enable prompt suggestions.

external_tool_handler: Option<ExternalToolHandlerFn>

External tool handler for custom tools.

Called before the built-in executor. If it returns Some(ToolResult), the built-in executor is skipped for that tool call.

custom_tool_definitions: Vec<CustomToolDefinition>

Custom tool definitions (JSON schemas) sent to the API alongside built-in tools.

These are typically used with external_tool_handler to register and handle tools that aren’t part of the built-in set (e.g. MemorySearch, VaultGet).

followup_rx: Option<UnboundedReceiver<String>>

Receiver for followup messages injected during an active agent loop.

At each iteration boundary (before calling the API), the loop drains all pending messages from this channel and appends them as user messages.

api_key: Option<String>

Explicit API key. When set, bypasses the ANTHROPIC_API_KEY env var lookup.

attachments: Vec<QueryAttachment>

File attachments to include in the first user message (images, PDFs, etc.).

provider: Option<Box<dyn LlmProvider>>

LLM provider to use. If None, defaults to AnthropicProvider::from_env().

pre_compact_handler: Option<PreCompactHandlerFn>

Pre-compaction handler: called with messages about to be discarded during conversation compaction, allowing the host to persist key facts.

max_tokens: Option<u32>

Maximum tokens for LLM API responses. Overrides DEFAULT_MAX_TOKENS.

summary_max_tokens: Option<u32>

Max tokens for the compaction summary response.

min_keep_messages: Option<usize>

Minimum number of messages to keep at the end during compaction.

max_tool_result_bytes: Option<usize>

Maximum size in bytes for any single tool result. Results exceeding this limit are truncated. Also strips base64 data URIs and hex blobs. Defaults to [sanitize::DEFAULT_MAX_TOOL_RESULT_BYTES] (50 000) when None.

prune_threshold_pct: Option<u8>

Percentage of context_budget at which lightweight tool-result pruning triggers. Defaults to [compact::DEFAULT_PRUNE_THRESHOLD_PCT] (70) when None.

prune_tool_result_max_chars: Option<usize>

Tool results longer than this (in chars) are candidates for pruning. Defaults to [compact::DEFAULT_PRUNE_TOOL_RESULT_MAX_CHARS] (2 000) when None.

Implementations

impl Options

pub fn builder() -> OptionsBuilder

Create a new Options builder.

Trait Implementations

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.