# `ClaudeAgentSDK.OptionBuilder`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L1)

Smart option builder for Claude Code SDK configurations.

This module provides pre-configured option sets and builder patterns for
common use cases. Instead of manually constructing `ClaudeAgentSDK.Options`
structs, you can use these convenience functions to get sensible defaults
for different environments and scenarios.

## Design Philosophy

- **Environment-aware**: Automatically adapt to dev, test, and production
- **Security-first**: Production configs are restrictive by default
- **Composable**: Mix and match presets with custom overrides
- **Practical**: Based on real-world usage patterns

## Quick Start

    # Get options for current environment
    options = ClaudeAgentSDK.OptionBuilder.for_environment()
    
    # Use a specific preset
    options = ClaudeAgentSDK.OptionBuilder.build_development_options()
    
    # Customize a preset
    options = ClaudeAgentSDK.OptionBuilder.merge(:development, %{max_turns: 15})

## Structured Outputs (JSON Schema)

Request validated JSON by providing a schema to `output_format`. This emits
`--json-schema` for compatible CLI versions (same flag used by the Python SDK 0.1.10):

    schema = %{
      "type" => "object",
      "properties" => %{"summary" => %{"type" => "string"}},
      "required" => ["summary"]
    }

    options = %Options{output_format: %{type: :json_schema, schema: schema}}

## Environment Presets

| Environment | Security | Tools | Turn Limit | Use Case |
|-------------|----------|-------|------------|----------|
| **Development** | Permissive | All tools | 10 | Local development |
| **Staging** | Moderate | Read-only | 5 | Testing/CI |
| **Production** | Restrictive | Read-only | 3 | Production analysis |

## Use Case Presets

| Preset | Tools | Purpose | Permissions |
|--------|-------|---------|-------------|
| **Analysis** | Read, Grep, Find | Code review | Read-only |
| **Documentation** | Read, Write | Doc generation | File creation |
| **Chat** | None | Simple Q&A | No tools |
| **Sandboxed** | Custom | Safe execution | Isolated |

# `available_presets`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L545)

```elixir
@spec available_presets() :: [atom()]
```

Lists all available preset names.

Useful for dynamic configuration or validation.

## Examples

    presets = ClaudeAgentSDK.OptionBuilder.available_presets()
    # => [:development, :staging, :production, :analysis, :chat, :documentation, :testing]

# `build_analysis_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L185)

```elixir
@spec build_analysis_options() :: ClaudeAgentSDK.Options.t()
```

Builds options optimized for code analysis tasks.

**Use for**: Code reviews, security audits, quality analysis

**Features**:
- Read and search tools for thorough analysis
- Higher turn limit (7) for comprehensive review
- No modification permissions for safety
- Specialized system prompt for analysis focus

## Examples

    options = ClaudeAgentSDK.OptionBuilder.build_analysis_options()
    ClaudeAgentSDK.query("Review this module for potential issues", options)

# `build_chat_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L216)

```elixir
@spec build_chat_options() :: ClaudeAgentSDK.Options.t()
```

Builds options for simple chat and Q&A interactions.

**Use for**: Help desk, documentation queries, general assistance

**Features**:
- Single turn for quick responses
- Text output for simple display
- No tool access to prevent unintended actions
- Minimal permissions

## Examples

    options = ClaudeAgentSDK.OptionBuilder.build_chat_options()
    ClaudeAgentSDK.query("What is the difference between async and sync?", options)

# `build_development_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L89)

```elixir
@spec build_development_options() :: ClaudeAgentSDK.Options.t()
```

Builds options suitable for development environment.

**Use for**: Local development, debugging, experimentation

**Features**:
- Higher turn limit (10) for complex tasks
- Verbose output for debugging
- All tools allowed for full functionality
- Edit permissions accepted for rapid iteration
- Stream JSON output for real-time feedback

## Examples

    # Basic development setup
    options = ClaudeAgentSDK.OptionBuilder.build_development_options()
    ClaudeAgentSDK.query("Help me debug this function", options)

    # Development with custom system prompt
    options = 
      ClaudeAgentSDK.OptionBuilder.build_development_options()
      |> ClaudeAgentSDK.OptionBuilder.with_system_prompt("You are a debugging expert")

# `build_documentation_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L247)

```elixir
@spec build_documentation_options() :: ClaudeAgentSDK.Options.t()
```

Builds options for documentation generation tasks.

**Use for**: API docs, README generation, code documentation

**Features**:
- Read access to understand existing code
- Write access for creating documentation files
- Higher turn limit (8) for comprehensive docs
- Accept edits mode for file creation
- Specialized prompt for documentation focus

## Examples

    options = ClaudeAgentSDK.OptionBuilder.build_documentation_options()
    ClaudeAgentSDK.query("Generate API documentation for this module", options)

# `build_production_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L153)

```elixir
@spec build_production_options() :: ClaudeAgentSDK.Options.t()
```

Builds options suitable for production environment.

**Use for**: Production monitoring, read-only analysis, customer-facing features

**Features**:
- Low turn limit (3) for efficiency
- Read-only access only
- Plan mode for safety
- Minimal tool access
- Structured JSON output

## Examples

    # Production-safe code analysis
    options = ClaudeAgentSDK.OptionBuilder.build_production_options()
    ClaudeAgentSDK.query("Explain what this function does", options)

# `build_staging_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L121)

```elixir
@spec build_staging_options() :: ClaudeAgentSDK.Options.t()
```

Builds options suitable for staging/testing environment.

**Use for**: CI/CD pipelines, automated testing, code review

**Features**:
- Moderate turn limit (5) for focused tasks
- Read-only tools for safety
- Plan mode prevents automatic changes
- Bash disabled to prevent system modifications
- JSON output for structured results

## Examples

    # Use in CI for code analysis
    options = ClaudeAgentSDK.OptionBuilder.build_staging_options()
    ClaudeAgentSDK.query("Analyze this code for security issues", options)

# `build_testing_options`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L278)

```elixir
@spec build_testing_options() :: ClaudeAgentSDK.Options.t()
```

Builds options for test generation and testing tasks.

**Use for**: Unit test creation, test analysis, quality assurance

**Features**:
- Read access to understand code under test
- Write access for creating test files
- Moderate turn limit for thorough test coverage
- Testing-focused system prompt

## Examples

    options = ClaudeAgentSDK.OptionBuilder.build_testing_options()
    ClaudeAgentSDK.query("Generate comprehensive unit tests for this module", options)

# `for_environment`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L314)

```elixir
@spec for_environment() :: ClaudeAgentSDK.Options.t()
```

Builds options for the configured build environment.

Automatically selects appropriate options based on the configured
environment (defaults to `MIX_ENV` or `:prod` when unset):
- `:dev` -> development options (permissive, verbose)
- `:test` -> staging options (moderate restrictions)
- `:prod` -> production options (restrictive, safe)

This is the recommended way to get environment-appropriate defaults.

## Examples

    # Get options for current environment
    options = ClaudeAgentSDK.OptionBuilder.for_environment()
    
    # In development, this gives you full access
    # In production, this gives you read-only access

# `merge`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L350)

```elixir
@spec merge(atom() | ClaudeAgentSDK.Options.t(), map()) :: ClaudeAgentSDK.Options.t()
```

Merges custom options with a base configuration.

Allows you to start with a preset and customize specific fields.
This is the recommended pattern for customizing presets.

## Parameters

- `base` - Base preset (atom) or Options struct
- `custom` - Map of custom options to override

## Examples

    # Start with development preset, customize turn limit
    options = ClaudeAgentSDK.OptionBuilder.merge(:development, %{max_turns: 15})
    
    # Start with analysis preset, add custom prompt
    options = ClaudeAgentSDK.OptionBuilder.merge(:analysis, %{
      system_prompt: "Focus on security vulnerabilities",
      max_turns: 10
    })
    
    # Merge with existing options
    base_options = ClaudeAgentSDK.OptionBuilder.build_chat_options()
    options = ClaudeAgentSDK.OptionBuilder.merge(base_options, %{max_turns: 3})

# `quick`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L522)

```elixir
@spec quick() :: ClaudeAgentSDK.Options.t()
```

Creates options for quick, one-off queries.

**Use for**: Simple questions, quick checks, lightweight operations

**Features**:
- Single turn limit
- Text output for simplicity
- No tools for safety
- Fast response

## Examples

    options = ClaudeAgentSDK.OptionBuilder.quick()
    ClaudeAgentSDK.query("What does this error mean?", options)

# `sandboxed`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L491)

```elixir
@spec sandboxed(String.t(), [String.t()]) :: ClaudeAgentSDK.Options.t()
```

Creates a sandboxed configuration for safe execution.

**Use for**: Untrusted code execution, isolated environments, testing

**Features**:
- Isolated to specific directory
- Bypass permissions (safe within sandbox)
- Customizable tool access
- No bash access by default

## Parameters

- `sandbox_path` - Path to sandbox directory
- `allowed_tools` - List of tools to allow (default: ["Read", "Write"])

## Examples

    # Basic sandbox
    options = ClaudeAgentSDK.OptionBuilder.sandboxed("/tmp/sandbox")
    
    # Sandbox with custom tools
    options = ClaudeAgentSDK.OptionBuilder.sandboxed("/tmp/safe", ["Read", "Write", "Grep"])

# `validate`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L572)

```elixir
@spec validate(ClaudeAgentSDK.Options.t()) ::
  {:ok, ClaudeAgentSDK.Options.t()}
  | {:warning, ClaudeAgentSDK.Options.t(), [String.t()]}
  | {:error, String.t()}
```

Validates that an options struct has sensible configuration.

Checks for common misconfigurations and provides warnings.

## Parameters

- `options` - Options struct to validate

## Returns

- `{:ok, options}` if valid
- `{:warning, options, warnings}` if valid but has warnings
- `{:error, reason}` if invalid

## Examples

    options = ClaudeAgentSDK.OptionBuilder.build_development_options()
    {:ok, _} = ClaudeAgentSDK.OptionBuilder.validate(options)

# `with_additional_tools`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L440)

```elixir
@spec with_additional_tools(ClaudeAgentSDK.Options.t(), [String.t()]) ::
  ClaudeAgentSDK.Options.t()
```

Adds additional allowed tools to any options.

## Parameters

- `options` - Options struct to modify
- `tools` - List of additional tools to allow

## Examples

    options = 
      ClaudeAgentSDK.OptionBuilder.build_production_options()
      |> ClaudeAgentSDK.OptionBuilder.with_additional_tools(["Grep"])

# `with_agent`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L715)

```elixir
@spec with_agent(ClaudeAgentSDK.Options.t(), String.t(), map()) ::
  ClaudeAgentSDK.Options.t()
```

Adds custom agent to options.

## Examples

    options = OptionBuilder.build_development_options()
    |> OptionBuilder.with_agent("security_reviewer", %{
      description: "Security-focused code reviewer",
      prompt: "You are a security expert. Review for vulnerabilities."
    })

# `with_agents`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L736)

```elixir
@spec with_agents(map()) :: ClaudeAgentSDK.Options.t()
```

Sets multiple agents at once.

## Examples

    agents = %{
      "reviewer" => %{description: "Code reviewer", prompt: "Review code"},
      "tester" => %{description: "Test generator", prompt: "Generate tests"}
    }

    options = OptionBuilder.with_agents(agents)

# `with_agents`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L741)

```elixir
@spec with_agents(ClaudeAgentSDK.Options.t(), map()) :: ClaudeAgentSDK.Options.t()
```

# `with_haiku`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L676)

```elixir
@spec with_haiku() :: ClaudeAgentSDK.Options.t()
```

Builds options for fast responses using Haiku model (default).

Best for:
- Simple queries
- Quick responses needed
- High-volume use cases
- Lowest cost option
- Default for most SDK operations

## Examples

    options = ClaudeAgentSDK.OptionBuilder.with_haiku()
    ClaudeAgentSDK.query("What is 2+2?", options)

# `with_model`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L699)

```elixir
@spec with_model(ClaudeAgentSDK.Options.t(), String.t(), String.t() | nil) ::
  ClaudeAgentSDK.Options.t()
```

Adds specific model to any options.

## Parameters

- `options` - Existing options
- `model_name` - Model name ("opus", "sonnet", "haiku", or full name like "claude-sonnet-4-5-20250929")
- `fallback` - Optional fallback model

## Examples

    options = build_development_options()
    |> with_model("opus", "sonnet")

# `with_opus`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L628)

```elixir
@spec with_opus() :: ClaudeAgentSDK.Options.t()
```

Builds options for maximum capability using Opus model.

Best for:
- Complex reasoning tasks
- Code generation requiring deep understanding
- Multi-step problem solving

Higher cost but better results.

## Examples

    options = ClaudeAgentSDK.OptionBuilder.with_opus()
    ClaudeAgentSDK.query("Architect a complex system", options)

# `with_sonnet`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L652)

```elixir
@spec with_sonnet() :: ClaudeAgentSDK.Options.t()
```

Builds options for balanced performance using Sonnet model.

Best for:
- General-purpose tasks
- Good balance of speed and capability
- Complex reasoning tasks

## Examples

    options = ClaudeAgentSDK.OptionBuilder.with_sonnet()
    ClaudeAgentSDK.query("Review this code", options)

# `with_system_prompt`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L415)

```elixir
@spec with_system_prompt(String.t()) :: ClaudeAgentSDK.Options.t()
```

Adds a custom system prompt to any options.

## Parameters

- `prompt` - System prompt to use
- `options` - Options struct to modify (optional, creates new if not provided)

## Examples

    options = ClaudeAgentSDK.OptionBuilder.with_system_prompt("You are a security expert")
    
    options = 
      ClaudeAgentSDK.OptionBuilder.build_analysis_options()
      |> ClaudeAgentSDK.OptionBuilder.with_system_prompt("You are a security expert")

# `with_system_prompt`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L420)

```elixir
@spec with_system_prompt(ClaudeAgentSDK.Options.t(), String.t()) ::
  ClaudeAgentSDK.Options.t()
```

# `with_turn_limit`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L461)

```elixir
@spec with_turn_limit(ClaudeAgentSDK.Options.t(), pos_integer()) ::
  ClaudeAgentSDK.Options.t()
```

Sets a custom turn limit for any options.

## Parameters

- `options` - Options struct to modify  
- `turns` - Maximum number of turns

## Examples

    options = 
      ClaudeAgentSDK.OptionBuilder.build_chat_options()
      |> ClaudeAgentSDK.OptionBuilder.with_turn_limit(5)

# `with_working_directory`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L388)

```elixir
@spec with_working_directory(String.t()) :: ClaudeAgentSDK.Options.t()
```

Adds a custom working directory to any options.

## Parameters

- `cwd` - Working directory path
- `options` - Options struct to modify (optional, creates new if not provided)

## Examples

    options = ClaudeAgentSDK.OptionBuilder.with_working_directory("/project")
    
    options = 
      ClaudeAgentSDK.OptionBuilder.build_development_options()
      |> ClaudeAgentSDK.OptionBuilder.with_working_directory("/project")

# `with_working_directory`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/option_builder.ex#L393)

```elixir
@spec with_working_directory(ClaudeAgentSDK.Options.t(), String.t()) ::
  ClaudeAgentSDK.Options.t()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*