# `Codex.Thread.Options`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.0/lib/codex/thread/options.ex#L1)

Per-thread configuration options.

The historical `:exec` selector remains the compatibility label for the
default core-backed subprocess lane. It does not imply direct ownership of
the Erlang `:exec` worker or raw subprocess lifecycle in `codex_sdk`.

# `approvals_reviewer`

```elixir
@type approvals_reviewer() :: :user | :auto_review | :guardian_subagent
```

# `ask_for_approval`

```elixir
@type ask_for_approval() ::
  :untrusted
  | :on_failure
  | :on_request
  | :never
  | String.t()
  | granular_approval_policy()
```

# `collaboration_mode`

```elixir
@type collaboration_mode() :: Codex.Protocol.CollaborationMode.t()
```

# `color`

```elixir
@type color() :: :always | :never | :auto | String.t()
```

# `config_override`

```elixir
@type config_override() :: String.t() | {String.t() | atom(), config_override_value()}
```

# `config_override_value`

```elixir
@type config_override_value() ::
  config_override_value_scalar()
  | [config_override_value()]
  | %{optional(String.t() | atom()) => config_override_value()}
```

# `dynamic_tool`

```elixir
@type dynamic_tool() :: %{required(String.t()) => term()}
```

# `granular_approval_policy`

```elixir
@type granular_approval_policy() :: %{
  :type => :granular,
  optional(:sandbox_approval) => boolean(),
  optional(:rules) => boolean(),
  optional(:skill_approval) => boolean(),
  optional(:request_permissions) => boolean(),
  optional(:mcp_elicitations) => boolean()
}
```

# `history_mode`

```elixir
@type history_mode() :: :legacy | :paginated | String.t()
```

# `history_persistence`

```elixir
@type history_persistence() :: String.t()
```

# `model_verbosity`

```elixir
@type model_verbosity() :: :low | :medium | :high | String.t()
```

# `network_access`

```elixir
@type network_access() :: :enabled | :restricted
```

# `permission_profile`

```elixir
@type permission_profile() ::
  String.t() | atom() | %{optional(String.t() | atom()) => term()}
```

# `personality`

```elixir
@type personality() :: Codex.Protocol.ConfigTypes.personality()
```

# `rate_limit_opts`

```elixir
@type rate_limit_opts() :: keyword()
```

# `reasoning_summary`

```elixir
@type reasoning_summary() :: :auto | :concise | :detailed | :none | String.t()
```

# `retry_opts`

```elixir
@type retry_opts() :: keyword()
```

# `sandbox`

```elixir
@type sandbox() ::
  :default
  | :strict
  | :permissive
  | :read_only
  | :workspace_write
  | :danger_full_access
  | :external_sandbox
  | {:external_sandbox, network_access()}
  | String.t()
```

# `sandbox_policy`

```elixir
@type sandbox_policy() :: %{
  optional(:type) => sandbox_policy_type(),
  optional(:writable_roots) => [String.t()],
  optional(:network_access) => boolean() | :enabled | :restricted | String.t(),
  optional(:exclude_tmpdir_env_var) => boolean(),
  optional(:exclude_slash_tmp) => boolean()
}
```

# `sandbox_policy_type`

```elixir
@type sandbox_policy_type() ::
  :danger_full_access
  | :read_only
  | :workspace_write
  | :external_sandbox
  | String.t()
```

# `service_tier`

```elixir
@type service_tier() :: :auto | :default | :flex | :priority | String.t()
```

# `t`

```elixir
@type t() :: %Codex.Thread.Options{
  additional_directories: [String.t()],
  allow_provider_model_fallback: boolean() | nil,
  apply_patch_freeform_enabled: boolean() | nil,
  approval_hook: module() | nil,
  approval_policy: module() | nil,
  approval_timeout_ms: pos_integer(),
  approvals_reviewer: approvals_reviewer() | nil,
  ask_for_approval: ask_for_approval() | nil,
  attachments: [map()] | [],
  auto_run: boolean(),
  base_instructions: String.t() | nil,
  collaboration_mode: collaboration_mode() | nil,
  color: color() | nil,
  compact_prompt: String.t() | nil,
  config: map() | nil,
  config_overrides: [config_override()],
  dangerously_bypass_approvals_and_sandbox: boolean(),
  developer_instructions: String.t() | nil,
  dynamic_tools: [dynamic_tool()],
  environments: [map()] | nil,
  ephemeral: boolean() | nil,
  experimental_raw_events: boolean(),
  file_search: Codex.FileSearch.t() | nil,
  full_auto: boolean(),
  history_max_bytes: non_neg_integer() | nil,
  history_mode: String.t() | nil,
  history_persistence: history_persistence() | nil,
  ignore_rules: boolean(),
  ignore_user_config: boolean(),
  initial_turns_page: map() | nil,
  labels: map(),
  local_provider: String.t() | nil,
  metadata: map(),
  model: String.t() | nil,
  model_context_window: pos_integer() | nil,
  model_provider: String.t() | nil,
  model_reasoning_summary: reasoning_summary() | nil,
  model_supports_reasoning_summaries: boolean() | nil,
  model_verbosity: model_verbosity() | nil,
  network_access_enabled: boolean() | nil,
  oss: boolean(),
  output_last_message: String.t() | nil,
  output_schema: map() | nil,
  permission_profile: permission_profile() | nil,
  persist_extended_history: boolean() | nil,
  personality: personality() | nil,
  profile: String.t() | nil,
  rate_limit: boolean() | nil,
  rate_limit_opts: rate_limit_opts() | nil,
  request_max_retries: pos_integer() | nil,
  retry: boolean() | nil,
  retry_opts: retry_opts() | nil,
  runtime_workspace_roots: [String.t()] | nil,
  sandbox: sandbox(),
  sandbox_policy: sandbox_policy() | sandbox_policy_type() | nil,
  selected_capability_roots: [map()] | nil,
  service_name: String.t() | nil,
  service_tier: service_tier() | nil,
  shell_environment_policy: map() | nil,
  show_raw_agent_reasoning: boolean(),
  skills_enabled: boolean() | nil,
  skip_git_repo_check: boolean(),
  stream_idle_timeout_ms: pos_integer() | nil,
  stream_max_retries: pos_integer() | nil,
  thread_source: String.t() | nil,
  transport: transport(),
  unified_exec_enabled: boolean() | nil,
  view_image_tool_enabled: boolean() | nil,
  web_search_enabled: boolean(),
  web_search_mode: web_search_mode(),
  web_search_mode_explicit: boolean(),
  working_directory: String.t() | nil
}
```

# `thread_source`

```elixir
@type thread_source() ::
  :user
  | :subagent
  | :sub_agent
  | :memory_consolidation
  | {:feature, String.t()}
  | String.t()
```

# `transport`

```elixir
@type transport() :: :exec | {:app_server, pid()}
```

# `web_search_mode`

```elixir
@type web_search_mode() :: Codex.Protocol.ConfigTypes.web_search_mode()
```

# `new`

```elixir
@spec new(map() | keyword() | t()) :: {:ok, t()} | {:error, term()}
```

Builds a thread options struct from various inputs.

---

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