claude-agent-sdk 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49a855001019149f2348998742683b3589966a6b97464e815b1fd44abb01ab51
-  data.tar.gz: af1826c40f4e8cb6c1910b6ca81b2fa3e01dc83442b4373f5e912b0a1d4af871
+  metadata.gz: 2a7bc7ca34128ea7dd30f519fcef30ce934b1c05e8387e97f626ba6a0d19d5dc
+  data.tar.gz: e61274c9565ebb637d67917803d9c68b21964e4b91e0fa9d128ce8615efb4ff3
 SHA512:
-  metadata.gz: b5322fb7d911240d064985742c6817d8f9ccb0918c30ec7b27aca012c657ee0b5c1a648f6714cc471ca32b15acf8d7f72d6bf2f938d8b4811d9a0ba497a3f662
-  data.tar.gz: 3ea02aa3ef4da8a98e876c18605f2bffcd5edca9e6ca719bfa70de925463030e8cb1793916bf1681f7fcb432f044398dfdbb5480fb295a11673736977c772347
+  metadata.gz: 9c25ff87ec00eb19004445c112dd83b5dd180707d64ac3d916b54d7a7e733fccdb2d60973b73f1b06530393df8a0e02a60d1bafa8742e6bc685c52fdea4675f6
+  data.tar.gz: 49ee14d69651954d2615a1e5630637636d12b85c957c1d433c7d37bfdd8e6279cc2b8e9f7a7c0d4bc122374609bd66695696f3c3f5ea29ff7ee7a41f8f3bf570

data/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.1] - 2026-04-09
+
+### Fixed
+- **Thinking configuration**: Use `--thinking adaptive` / `--thinking disabled` CLI flags instead of mapping to `--max-thinking-tokens`. Previously, `ThinkingConfigAdaptive` was mapped to `--max-thinking-tokens 32000` (fixed budget) and `ThinkingConfigDisabled` to `--max-thinking-tokens 0`, which put the CLI into the wrong mode. Only `ThinkingConfigEnabled` now uses `--max-thinking-tokens`. (Parity with [Python SDK #796](https://github.com/anthropics/claude-agent-sdk-python/pull/796))
+
+### Added
+- **`exclude_dynamic_sections`** on `SystemPromptPreset`: When set to `true`, the CLI strips per-user dynamic sections (working directory, auto-memory, git status) from the preset system prompt and re-injects them into the first user message. This makes the system prompt byte-identical across users, enabling cross-user prompt-caching hits. Sent via `excludeDynamicSections` in the initialize control message; older CLIs silently ignore it. (Parity with [Python SDK #797](https://github.com/anthropics/claude-agent-sdk-python/pull/797))
+
 ## [0.14.0] - 2026-04-08 — Python SDK v0.1.51–0.1.56 Parity
 
 ### Added

data/README.md

@@ -128,11 +128,7 @@ gem install claude-agent-sdk
 
 ### Agentic Coding Skill
 
-If you're using [Claude Code](https://claude.ai/claude-code) or another agentic coding tool that supports [skills](https://skills.sh), you can install the SDK skill:
-
-**Option 1: Via Plugin Marketplace (recommended)**
-
-This repo is a Claude Code plugin marketplace. Add it once, then install the skill:
+If you're using [Claude Code](https://claude.ai/claude-code), this repo is a Claude Code plugin marketplace. Add it once, then install the skill:
 
 ```bash
 # Add the marketplace
@@ -142,12 +138,6 @@ This repo is a Claude Code plugin marketplace. Add it once, then install the ski
 /plugin install claude-agent-ruby@claude-agent-sdk-ruby
 ```
 
-**Option 2: Via skills.sh**
-
-```bash
-npx skills add https://github.com/ya-luotao/claude-agent-sdk-ruby --skill claude-agent-sdk-ruby
-```
-
 This skill teaches your AI coding assistant about the SDK's APIs, patterns, and best practices, making it easier to get help writing code that uses this SDK.
 
 ## Quick Start
@@ -734,12 +724,12 @@ For complete examples, see [examples/structured_output_example.rb](examples/stru
 Control extended thinking behavior with typed configuration objects. The `thinking` option takes precedence over the deprecated `max_thinking_tokens`.
 
 ```ruby
-# Adaptive thinking — uses a default budget of 32,000 tokens
+# Adaptive thinking — CLI dynamically adjusts budget based on task complexity
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
   thinking: ClaudeAgentSDK::ThinkingConfigAdaptive.new
 )
 
-# Enabled thinking with custom budget
+# Enabled thinking with explicit token budget
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
   thinking: ClaudeAgentSDK::ThinkingConfigEnabled.new(budget_tokens: 50_000)
 )
@@ -760,6 +750,22 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 > **Note:** When `system_prompt` is `nil` (the default), the SDK passes `--system-prompt ""` to the CLI, which suppresses the default Claude Code system prompt. To use the default system prompt, use a `SystemPromptPreset`.
 
+### Cross-User Prompt Caching
+
+When running a multi-user fleet with shared preset prompts, enable `exclude_dynamic_sections` to make the system prompt byte-identical across users for prompt-caching hits:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+  system_prompt: ClaudeAgentSDK::SystemPromptPreset.new(
+    preset: 'claude_code',
+    append: '...your shared domain instructions...',
+    exclude_dynamic_sections: true
+  )
+)
+```
+
+When set, the CLI strips per-user dynamic sections (working directory, auto-memory, git status) from the system prompt and re-injects them into the first user message instead. Older CLIs silently ignore this option.
+
 ## Budget Control
 
 Use `max_budget_usd` to set a spending cap for your queries:
@@ -1575,9 +1581,9 @@ end
 | `PermissionResultAllow` | Permission callback result to allow tool use |
 | `PermissionResultDeny` | Permission callback result to deny tool use |
 | `AgentDefinition` | Agent definition with description, prompt, tools, model, skills, memory, mcp_servers |
-| `ThinkingConfigAdaptive` | Adaptive thinking mode (32,000 token default budget) |
+| `ThinkingConfigAdaptive` | Adaptive thinking mode (CLI dynamically adjusts budget) |
 | `ThinkingConfigEnabled` | Enabled thinking with explicit `budget_tokens` |
-| `ThinkingConfigDisabled` | Disabled thinking (0 tokens) |
+| `ThinkingConfigDisabled` | Disabled thinking |
 | `SdkMcpTool` | SDK MCP tool definition with name, description, input_schema, handler, annotations |
 | `McpStdioServerConfig` | MCP server config for stdio transport |
 | `McpSSEServerConfig` | MCP server config for SSE transport |

data/lib/claude_agent_sdk/query.rb

@@ -25,13 +25,15 @@ module ClaudeAgentSDK
     STREAM_CLOSE_TIMEOUT_ENV_VAR = 'CLAUDE_CODE_STREAM_CLOSE_TIMEOUT'
     DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS = 60.0
 
-    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil)
+    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
+                   exclude_dynamic_sections: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
       @hooks = hooks || {}
       @sdk_mcp_servers = sdk_mcp_servers || {}
       @agents = agents
+      @exclude_dynamic_sections = exclude_dynamic_sections
 
       # Control protocol state
       @pending_control_responses = {}
@@ -109,6 +111,7 @@ module ClaudeAgentSDK
         hooks: hooks_config.empty? ? nil : hooks_config,
         agents: agents_dict
       }
+      request[:excludeDynamicSections] = @exclude_dynamic_sections unless @exclude_dynamic_sections.nil?
 
       response = send_control_request(request)
       @initialized = true

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -120,8 +120,7 @@ module ClaudeAgentSDK
       end
 
       # Thinking configuration (takes precedence over deprecated max_thinking_tokens)
-      thinking_tokens = resolve_thinking_tokens
-      cmd.concat(['--max-thinking-tokens', thinking_tokens.to_s]) unless thinking_tokens.nil?
+      build_thinking_args(cmd)
 
       # Effort level (valid values: low, medium, high, max)
       cmd.concat(['--effort', @options.effort.to_s]) if @options.effort
@@ -494,8 +493,6 @@ module ClaudeAgentSDK
       @ready
     end
 
-    DEFAULT_ADAPTIVE_THINKING_TOKENS = 32_000
-
     private
 
     def build_settings_args(cmd)
@@ -599,18 +596,18 @@ module ClaudeAgentSDK
       JSON.parse(File.read(path))
     end
 
-    def resolve_thinking_tokens
+    def build_thinking_args(cmd)
       if @options.thinking
         case @options.thinking
         when ThinkingConfigAdaptive
-          DEFAULT_ADAPTIVE_THINKING_TOKENS
+          cmd.concat(['--thinking', 'adaptive'])
         when ThinkingConfigEnabled
-          @options.thinking.budget_tokens
+          cmd.concat(['--max-thinking-tokens', @options.thinking.budget_tokens.to_s])
         when ThinkingConfigDisabled
-          0
+          cmd.concat(['--thinking', 'disabled'])
         end
       elsif @options.max_thinking_tokens
-        @options.max_thinking_tokens
+        cmd.concat(['--max-thinking-tokens', @options.max_thinking_tokens.to_s])
       end
     end
   end

data/lib/claude_agent_sdk/types.rb

@@ -1735,17 +1735,19 @@ module ClaudeAgentSDK
 
   # System prompt preset configuration
   class SystemPromptPreset
-    attr_accessor :type, :preset, :append
+    attr_accessor :type, :preset, :append, :exclude_dynamic_sections
 
-    def initialize(preset:, append: nil)
+    def initialize(preset:, append: nil, exclude_dynamic_sections: nil)
       @type = 'preset'
       @preset = preset
       @append = append
+      @exclude_dynamic_sections = exclude_dynamic_sections
     end
 
     def to_h
       result = { type: @type, preset: @preset }
       result[:append] = @append if @append
+      result[:exclude_dynamic_sections] = @exclude_dynamic_sections unless @exclude_dynamic_sections.nil?
       result
     end
   end

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -340,6 +340,10 @@ module ClaudeAgentSDK
       # Convert hooks to internal format
       hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
 
+      # Extract exclude_dynamic_sections from preset system prompt for the
+      # initialize request (older CLIs ignore unknown initialize fields)
+      exclude_dynamic_sections = extract_exclude_dynamic_sections(configured_options.system_prompt)
+
       # Create Query handler
       @query_handler = Query.new(
         transport: @transport,
@@ -347,7 +351,8 @@ module ClaudeAgentSDK
         can_use_tool: configured_options.can_use_tool,
         hooks: hooks,
         sdk_mcp_servers: sdk_mcp_servers,
-        agents: configured_options.agents
+        agents: configured_options.agents,
+        exclude_dynamic_sections: exclude_dynamic_sections
       )
 
       # Start query handler and initialize
@@ -527,5 +532,19 @@ module ClaudeAgentSDK
       end
       internal_hooks
     end
+
+    def extract_exclude_dynamic_sections(system_prompt)
+      if system_prompt.is_a?(SystemPromptPreset)
+        eds = system_prompt.exclude_dynamic_sections
+        return eds if [true, false].include?(eds)
+      elsif system_prompt.is_a?(Hash)
+        type = system_prompt[:type] || system_prompt['type']
+        if type == 'preset'
+          eds = system_prompt.fetch(:exclude_dynamic_sections) { system_prompt['exclude_dynamic_sections'] }
+          return eds if [true, false].include?(eds)
+        end
+      end
+      nil
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-07 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async