Class: ClaudeAgentSDK::ClaudeAgentOptions

Inherits:
Type
  • Object
show all
Defined in:
lib/claude_agent_sdk/types.rb

Overview

Claude Agent Options for configuring queries

Constant Summary collapse

CALLBACK_SCHEDULING_MODES = 
%i[thread inline].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Type

#[], #[]=, from_hash, #to_h, wrap

Constructor Details

#initialize(attributes = {}) ⇒ ClaudeAgentOptions

Returns a new instance of ClaudeAgentOptions.



1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
 
# File 'lib/claude_agent_sdk/types.rb', line 1730

def initialize(attributes = {})
  self.fork_session = false
  self.continue_conversation = false
  self.include_partial_messages = false
  self.enable_file_checkpointing = false
  self.include_hook_events = false
  self.strict_mcp_config = false
  self.forward_subagent_text = false

  super(merge_with_defaults(attributes || {}))

  # Non-nil defaults for options that need them.
  self.env                 ||= {}
  self.extra_args          ||= {}
  self.mcp_servers         ||= {}
  self.add_dirs            ||= []
  self.observers           ||= []
  self.allowed_tools       ||= []
  self.disallowed_tools    ||= []
  self.session_store_flush ||= 'batched'
  # 0 is a valid (immediate) timeout, so only fill in the default for nil.
  self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
  self.callback_scheduling = :thread if callback_scheduling.nil?
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class ClaudeAgentSDK::Type

Instance Attribute Details

#add_dirs ⇒ Object

Returns the value of attribute add_dirs.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def add_dirs
  @add_dirs
end

#advisor_model ⇒ Object

Returns the value of attribute advisor_model.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def advisor_model
  @advisor_model
end

#agents ⇒ Object

Returns the value of attribute agents.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def agents
  @agents
end

#allowed_tools ⇒ Object

Returns the value of attribute allowed_tools.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def allowed_tools
  @allowed_tools
end

#bare ⇒ Object

Returns the value of attribute bare.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def bare
  @bare
end

#betas ⇒ Object

Returns the value of attribute betas.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def betas
  @betas
end

#callback_scheduling ⇒ Object

Returns the value of attribute callback_scheduling.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def callback_scheduling
  @callback_scheduling
end

#callback_wrapper ⇒ Object

Returns the value of attribute callback_wrapper.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def callback_wrapper
  @callback_wrapper
end

#can_use_tool ⇒ Object

Returns the value of attribute can_use_tool.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def can_use_tool
  @can_use_tool
end

#cli_path ⇒ Object

Returns the value of attribute cli_path.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def cli_path
  @cli_path
end

#continue_conversation ⇒ Object

Returns the value of attribute continue_conversation.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def continue_conversation
  @continue_conversation
end

#cwd ⇒ Object

Returns the value of attribute cwd.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def cwd
  @cwd
end

#debug_stderr ⇒ Object

Returns the value of attribute debug_stderr.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def debug_stderr
  @debug_stderr
end

#disallowed_tools ⇒ Object

Returns the value of attribute disallowed_tools.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def disallowed_tools
  @disallowed_tools
end

#effort ⇒ Object

Returns the value of attribute effort.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def effort
  @effort
end

#enable_file_checkpointing ⇒ Object

Returns the value of attribute enable_file_checkpointing.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def enable_file_checkpointing
  @enable_file_checkpointing
end

#env ⇒ Object

Returns the value of attribute env.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def env
  @env
end

#extra_args ⇒ Object

Returns the value of attribute extra_args.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def extra_args
  @extra_args
end

#fallback_model ⇒ Object

Returns the value of attribute fallback_model.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def fallback_model
  @fallback_model
end

#fork_session ⇒ Object

Returns the value of attribute fork_session.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def fork_session
  @fork_session
end

#forward_subagent_text ⇒ Boolean

Forward subagent text and thinking blocks as messages in the stream. Defaults to false.

By default only tool_use / tool_result blocks from subagents (spawned via the Agent tool) are emitted, as AssistantMessage / UserMessage objects whose parent_tool_use_id is the spawning Agent tool_use id — enough for a progress heartbeat. When true, the subagent's text and thinking blocks are forwarded the same way, so consumers can render the full nested transcript. Matches the TypeScript SDK's forwardSubagentText.

Sent as the forwardSubagentText initialize capability rather than a CLI flag, and only when enabled, so an older CLI never sees an unknown key on the common path. Both ClaudeAgentSDK.query and ClaudeAgentSDK::Client run the control protocol, so the option applies to either entry point.

Assigning coerces to a Boolean; #forward_subagent_text? is the predicate form.

Returns:

  • (Boolean) 


1846
1847
1848
 
# File 'lib/claude_agent_sdk/types.rb', line 1846

def forward_subagent_text
  @forward_subagent_text
end

#hooks ⇒ Object

Returns the value of attribute hooks.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def hooks
  @hooks
end

#include_hook_events ⇒ Object

Returns the value of attribute include_hook_events.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def include_hook_events
  @include_hook_events
end

#include_partial_messages ⇒ Object

Returns the value of attribute include_partial_messages.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def include_partial_messages
  @include_partial_messages
end

#load_timeout_ms ⇒ Object

Returns the value of attribute load_timeout_ms.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def load_timeout_ms
  @load_timeout_ms
end

#max_budget_usd ⇒ Object

Returns the value of attribute max_budget_usd.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def max_budget_usd
  @max_budget_usd
end

#max_buffer_size ⇒ Object

Returns the value of attribute max_buffer_size.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def max_buffer_size
  @max_buffer_size
end

#max_thinking_tokens ⇒ Object

Returns the value of attribute max_thinking_tokens.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def max_thinking_tokens
  @max_thinking_tokens
end

#max_turns ⇒ Object

Returns the value of attribute max_turns.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def max_turns
  @max_turns
end

#mcp_servers ⇒ Object

Returns the value of attribute mcp_servers.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def mcp_servers
  @mcp_servers
end

#model ⇒ Object

Returns the value of attribute model.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def model
  @model
end

#observers ⇒ Object

Returns the value of attribute observers.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def observers
  @observers
end

#output_format ⇒ Object

Returns the value of attribute output_format.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def output_format
  @output_format
end

#permission_mode ⇒ Object

Returns the value of attribute permission_mode.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def permission_mode
  @permission_mode
end

#permission_prompt_tool_name ⇒ Object

Returns the value of attribute permission_prompt_tool_name.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def permission_prompt_tool_name
  @permission_prompt_tool_name
end

#plugins ⇒ Object

Returns the value of attribute plugins.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def plugins
  @plugins
end

#resume ⇒ Object

Returns the value of attribute resume.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def resume
  @resume
end

#resume_drops_turn ⇒ String?

With #resume_session_at: the UUID of the user prompt whose turn this truncating resume intends to discard.

When set, the CLI validates at load time that every transcript entry after the resume_session_at point is attributable to that turn, and refuses the resume otherwise — e.g. when the discarded range contains a queued user message or task notification the session absorbed mid-turn that the caller had not yet observed. Leave unset to keep the unvalidated truncation behavior.

Choosing the fork point. Set resume_session_at to the last transcript entry of the turn you are keeping — whatever its type — and resume_drops_turn to the prompt UUID of the turn immediately after it (e.g. the next SessionMessage of type == "user" from ClaudeAgentSDK.get_session_messages, or the uuid you supplied on a streamed user message). Note that with structured output (#output_format) or end-turn MCP tools a kept turn ends on entries after its last assistant message, so forking at the assistant UUID is refused by design.

On refusal. The CLI reports an error_during_execution result whose message starts with Resume rejected by --resume-drops-turn: — match on that text. Treat it as deterministic: clear the pending fork target and resume plainly rather than retrying the same request.

Forwarded whenever it is not nil. An empty string reaches the CLI and is rejected there as a malformed declaration rather than being dropped by the SDK, which would silently disarm the guard you believe is armed. The SDK does not validate the option combination (resume / resume_session_at); like the TypeScript and Python SDKs that is the CLI's call.

Returns:

  • (String, nil)

See Also:



1728
1729
1730
 
# File 'lib/claude_agent_sdk/types.rb', line 1728

def resume_drops_turn
  @resume_drops_turn
end

#resume_session_at ⇒ Object

Returns the value of attribute resume_session_at.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def resume_session_at
  @resume_session_at
end

#sandbox ⇒ Object

Returns the value of attribute sandbox.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def sandbox
  @sandbox
end

#session_id ⇒ Object

Returns the value of attribute session_id.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def session_id
  @session_id
end

#session_store ⇒ Object

Returns the value of attribute session_store.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def session_store
  @session_store
end

#session_store_flush ⇒ Object

Returns the value of attribute session_store_flush.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def session_store_flush
  @session_store_flush
end

#setting_sources ⇒ Object

Returns the value of attribute setting_sources.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def setting_sources
  @setting_sources
end

#settings ⇒ Object

Returns the value of attribute settings.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def settings
  @settings
end

#skills ⇒ Object

Returns the value of attribute skills.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def skills
  @skills
end

#stderr ⇒ Object

Returns the value of attribute stderr.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def stderr
  @stderr
end

#strict_mcp_config ⇒ Object

Returns the value of attribute strict_mcp_config.



1689
1690
1691
 
# File 'lib/claude_agent_sdk/types.rb', line 1689

def strict_mcp_config
  @strict_mcp_config
end

#system_prompt ⇒ Object

Returns the value of attribute system_prompt.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def system_prompt
  @system_prompt
end

#task_budget ⇒ Object

Returns the value of attribute task_budget.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def task_budget
  @task_budget
end

#thinking ⇒ Object

Returns the value of attribute thinking.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def thinking
  @thinking
end

#tools ⇒ Object

Returns the value of attribute tools.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def tools
  @tools
end

#user ⇒ Object

Returns the value of attribute user.



1678
1679
1680
 
# File 'lib/claude_agent_sdk/types.rb', line 1678

def user
  @user
end

Instance Method Details

#bare? ⇒ Boolean

Returns:

  • (Boolean) 


1770
1771
1772
 
# File 'lib/claude_agent_sdk/types.rb', line 1770

def bare?
  !!bare
end

#continue_conversation? ⇒ Boolean

Returns:

  • (Boolean) 


1802
1803
1804
 
# File 'lib/claude_agent_sdk/types.rb', line 1802

def continue_conversation?
  !!continue_conversation
end

#dup_with(**changes) ⇒ Object 



1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
 
# File 'lib/claude_agent_sdk/types.rb', line 1755

def dup_with(**changes)
  new_options = self.dup
  # A shallow #dup shares nested containers, so mutating a derived copy
  # (e.g. `variant.allowed_tools << 'Bash'`) would bleed into the base and
  # every sibling — including the security-relevant allow/deny lists.
  # Deep-dup Hash/Array containers only; non-container values (procs,
  # SDK MCP server instances, store adapters) must keep their identity.
  new_options.instance_variables.each do |ivar|
    value = new_options.instance_variable_get(ivar)
    new_options.instance_variable_set(ivar, deep_dup_containers(value)) if value.is_a?(Hash) || value.is_a?(Array)
  end
  changes.each { |key, value| new_options[key] = value }
  new_options
end

#enable_file_checkpointing? ⇒ Boolean

Returns:

  • (Boolean) 


1786
1787
1788
 
# File 'lib/claude_agent_sdk/types.rb', line 1786

def enable_file_checkpointing?
  !!enable_file_checkpointing
end

#fork_session? ⇒ Boolean

Returns:

  • (Boolean) 


1778
1779
1780
 
# File 'lib/claude_agent_sdk/types.rb', line 1778

def fork_session?
  !!fork_session
end

#forward_subagent_text? ⇒ Boolean

Returns #forward_subagent_text, as a strict Boolean.

Returns:



1849
1850
1851
 
# File 'lib/claude_agent_sdk/types.rb', line 1849

def forward_subagent_text?
  !!forward_subagent_text
end

#include_hook_events? ⇒ Boolean

Returns:

  • (Boolean) 


1810
1811
1812
 
# File 'lib/claude_agent_sdk/types.rb', line 1810

def include_hook_events?
  !!include_hook_events
end

#include_partial_messages? ⇒ Boolean

Returns:

  • (Boolean) 


1794
1795
1796
 
# File 'lib/claude_agent_sdk/types.rb', line 1794

def include_partial_messages?
  !!include_partial_messages
end

#strict_mcp_config? ⇒ Boolean

Returns:

  • (Boolean) 


1818
1819
1820
 
# File 'lib/claude_agent_sdk/types.rb', line 1818

def strict_mcp_config?
  !!strict_mcp_config
end