claude-agent-sdk 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b739ecaa08f1ddc9bc97ffdf639deca97a69da0251ec7b4ec975c7994c76c4b7
-  data.tar.gz: c85fe94b25b9b18c7de7d842cdeef7d0059c40cf829f33a963a4c6a215b4f999
+  metadata.gz: '0738568951864f8bf79353f7477f23356c0d04e60900ca346dab0bcc099dbe46'
+  data.tar.gz: 5136e71504b5078bb3e6fbcc38d34ee2151239be909d275f0972ef40a052a8ff
 SHA512:
-  metadata.gz: 7c1e37466bb844a9bcb4be7206881051e097e45181b64554f1e1299602a00f0ad88f1ffcefd73796e118715595bcef83cfd8e63138e2f537e2b6312428767e2c
-  data.tar.gz: daa2ba1268fdf355b426fec710b28254eaa4db61ff45017fe444f05b1499986f13aa2b1273997a52f64c061ce84a6cd7efda897d977c5d753323511c05184399
+  metadata.gz: 61d60a87a8202259abc051f7b642d79c3b2c49f1f53a44ad588a69669578d170415860a584ce8e487a81566b1fc51c86a76cb83b0f47f78bd051fdc07e20276e
+  data.tar.gz: f8a8b46e371a290885f33806fb3a67cf95494ed59003749c54ab68c33123d32f9d80ea3f576262201f08fefa5d14f0d4947edd2245c376a045fbdc10b5f79677

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-07-14
+
+### Added
+- `ClaudeAgentOptions.advisor_model` enables Claude Code's experimental server-side [advisor tool](https://code.claude.com/docs/en/advisor) (`--advisor` CLI flag): the main model consults a stronger advisor model at key decision points. Accepts a model alias (`'opus'`) or full model ID. Anthropic API only; the CLI validates the main-model/advisor pairing, so invalid pairings surface as `ProcessError`. Consultations appear in `AssistantMessage` content as `ServerToolUseBlock` (name `'advisor'`) and `ServerToolResultBlock` blocks, which the SDK already parsed. See `examples/advisor_example.rb` and the new "Advisor Model" section in `docs/configuration.md`.
+
 ## [0.22.0] - 2026-07-03
 
 Final batch (Batch D) from the 2026-07-03 full-codebase audit, closing it out: tests/docs/examples plus the three recorded split-verdict findings (P1-P3). Minor because the conformance suite gained a contract (an adapter that passed 0.21.0 can now fail contract 16) and new API surface (`check_uuid_dedupe:`).

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.22.0'
+gem 'claude-agent-sdk', '~> 0.23.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -207,7 +207,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 | Topic | Reference |
 |-------|-----------|
-| Structured output, thinking config, budget, fallback model, beta features, sandbox, bare mode, file checkpointing | [docs/configuration.md](docs/configuration.md) |
+| Structured output, thinking config, budget, fallback model, advisor model, beta features, sandbox, bare mode, file checkpointing | [docs/configuration.md](docs/configuration.md) |
 | Session listing, reading, renaming, tagging, deleting, forking, resume-at-message | [docs/sessions.md](docs/sessions.md) |
 | OpenTelemetry tracing, Langfuse setup, custom observers | [docs/observability.md](docs/observability.md) |
 | Rails integration (fiber safety, ActionCable, sessions, jobs, HTTP MCP, observability initializer) | [docs/rails.md](docs/rails.md) |
@@ -253,6 +253,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 |---------|-------------|
 | [budget_control_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb) | Budget control with `max_budget_usd` |
 | [fallback_model_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb) | Fallback model configuration |
+| [advisor_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) | Server-side advisor tool (`advisor_model`) |
 | [extended_thinking_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/extended_thinking_example.rb) | Extended thinking |
 | [e2b_transport_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) | Custom transport running CLI in an E2B microVM |
 

data/docs/configuration.md

@@ -104,6 +104,41 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 See [examples/fallback_model_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb).
 
+## Advisor Model
+
+Pair the main model with a stronger advisor model that Claude consults at key
+decision points (before committing to an approach, when stuck on a recurring
+error, before declaring a task done). The advisor runs server-side and
+receives the full conversation.
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  model: 'haiku',
+  advisor_model: 'opus'  # alias or full model ID, e.g. 'claude-opus-4-8'
+)
+```
+
+Advisor consultations surface in `AssistantMessage` content as
+`ServerToolUseBlock` (name `'advisor'`) and `ServerToolResultBlock`
+(`advisor_tool_result`) blocks.
+
+Notes:
+
+- Experimental; requires the Anthropic API (not available on Bedrock, Google
+  Cloud's Agent Platform, or Microsoft Foundry). Requires Claude Code CLI with
+  advisor support (v2.1.x).
+- The CLI validates the pairing — the advisor must be at least as capable as
+  the main model (e.g. a Haiku main accepts an Opus advisor; the reverse is
+  rejected). Pairing rules are CLI-version-dependent, so the SDK passes the
+  value through without validating it.
+- Advisor calls are billed at the advisor model's rates in addition to the
+  main model's usage.
+- `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` (settable via `options.env`) disables
+  the advisor tool entirely; a configured `advisor_model` is then ignored.
+
+See [examples/advisor_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) and the
+[advisor documentation](https://code.claude.com/docs/en/advisor).
+
 ## Beta Features
 
 ```ruby

data/lib/claude_agent_sdk/command_builder.rb

@@ -124,6 +124,10 @@ module ClaudeAgentSDK
     def append_model(cmd)
       cmd.push("--model", @options.model) if @options.model
       cmd.push("--fallback-model", @options.fallback_model) if @options.fallback_model
+      # Server-side advisor tool (experimental, Anthropic API only). The CLI
+      # validates the main-model/advisor pairing; pairing rules are
+      # CLI-version-dependent, so the SDK passes the value through verbatim.
+      cmd.push("--advisor", @options.advisor_model) if @options.advisor_model
     end
 
     def append_permission(cmd)

data/lib/claude_agent_sdk/types.rb

@@ -1553,7 +1553,7 @@ module ClaudeAgentSDK
                   :can_use_tool, :hooks, :user,
                   :agents, :setting_sources, :skills,
                   :output_format, :max_budget_usd, :max_thinking_tokens,
-                  :fallback_model, :plugins, :debug_stderr,
+                  :fallback_model, :advisor_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox,
                   :thinking, :effort, :observers, :task_budget,
                   :session_store, :session_store_flush, :load_timeout_ms

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.22.0'
+  VERSION = '0.23.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async