claude-agent-sdk 0.33.1 → 0.35.0

data/lib/claude_agent_sdk.rb

@@ -20,6 +20,10 @@ require_relative 'claude_agent_sdk/session_resume'
 require_relative 'claude_agent_sdk/session_mutations'
 require_relative 'claude_agent_sdk/fiber_boundary'
 require_relative 'claude_agent_sdk/option_warnings'
+# Rails apps only: Bundler.require runs after `require 'rails'`, so the
+# Railtie (rake tasks; the generator lives under lib/generators) is picked up
+# there and nowhere else.
+require_relative 'claude_agent_sdk/railtie' if defined?(Rails::Railtie)
 require 'async'
 require 'securerandom'
 
@@ -52,18 +56,43 @@ module ClaudeAgentSDK
   # Internal: pull live SDK MCP server instances out of an mcp_servers Hash.
   # Accepts both raw Hash configs and typed Mcp*ServerConfig objects — a
   # McpSdkServerConfig passed without .to_h previously failed the Hash-only
-  # guard, so its in-process server was silently never registered.
+  # guard, so its in-process server was silently never registered. Hash
+  # configs may use String or Symbol keys (and a Symbol :sdk type) — the
+  # recognition rule must match CommandBuilder#append_mcp_servers, which
+  # strips the instance from exactly these entries.
   def self.extract_sdk_mcp_servers(mcp_servers)
     return {} unless mcp_servers.is_a?(Hash)
 
     servers = {}
     mcp_servers.each do |name, config|
       config = config.to_h if config.is_a?(Type)
-      servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
+      next unless config.is_a?(Hash) && (config[:type] || config['type']).to_s == 'sdk'
+
+      servers[name] = config.key?(:instance) ? config[:instance] : config['instance']
     end
     servers
   end
 
+  # Internal: normalize hook lists for the control protocol. An absent or
+  # disabled event must not become an empty registration in initialize.
+  def self.convert_hooks_to_internal_format(hooks)
+    return nil unless hooks
+
+    internal_hooks = {}
+    hooks.each do |event, matchers|
+      next if matchers.nil? || matchers.empty?
+
+      entries = []
+      matchers.each do |matcher|
+        config = { matcher: matcher.matcher, hooks: matcher.hooks }
+        config[:timeout] = matcher.timeout if matcher.timeout
+        entries << config
+      end
+      internal_hooks[event.to_s] = entries unless entries.empty?
+    end
+    internal_hooks.empty? ? nil : internal_hooks
+  end
+
   # Internal: validate can_use_tool and route permission prompts over stdio.
   #
   # Shared by query() and Client#connect so both entry points enforce the
@@ -422,6 +451,7 @@ module ClaudeAgentSDK
   # rename_session). Appends a custom-title entry carrying a fresh uuid +
   # timestamp via SessionStore#append.
   # @raise [ArgumentError] if session_id is invalid or title is empty
+  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
   def self.rename_session_via_store(session_store:, session_id:, title:, directory: nil)
     SessionMutations.rename_session_via_store(session_store: session_store, session_id: session_id,
                                               title: title, directory: directory)
@@ -430,6 +460,7 @@ module ClaudeAgentSDK
   # Tag a session in a SessionStore (store-backed counterpart to tag_session).
   # Pass nil to clear the tag.
   # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
   def self.tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
     SessionMutations.tag_session_via_store(session_store: session_store, session_id: session_id,
                                            tag: tag, directory: directory)
@@ -528,7 +559,7 @@ module ClaudeAgentSDK
 
     raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
 
-    Async do
+    Async(&FiberBoundary.capture_otel_context do
       materialized = nil
       query_handler = nil
       begin
@@ -556,25 +587,7 @@ module ClaudeAgentSDK
         # Extract SDK MCP servers
         sdk_mcp_servers = extract_sdk_mcp_servers(configured_options.mcp_servers)
 
-        hooks = nil
-        if configured_options.hooks
-          hooks = {}
-          configured_options.hooks.each do |event, matchers|
-            next if matchers.nil? || matchers.empty?
-
-            entries = []
-            matchers.each do |matcher|
-              config = {
-                matcher: matcher.matcher,
-                hooks: matcher.hooks
-              }
-              config[:timeout] = matcher.timeout if matcher.timeout
-              entries << config
-            end
-            hooks[event.to_s] = entries unless entries.empty?
-          end
-          hooks = nil if hooks.empty?
-        end
+        hooks = convert_hooks_to_internal_format(configured_options.hooks)
 
         # Create Query handler for control protocol
         query_handler = Query.new(
@@ -686,7 +699,7 @@ module ClaudeAgentSDK
           end
         end
       end
-    end.wait
+    end).wait
   end
 
   # Client for bidirectional, interactive conversations with Claude Code
@@ -762,7 +775,7 @@ module ClaudeAgentSDK
     def self.open(prompt = nil, options: nil, transport_class: SubprocessCLITransport, transport_args: {})
       raise ArgumentError, 'Client.open requires a block' unless block_given?
 
-      Sync do
+      Sync(&FiberBoundary.capture_otel_context do
         client = new(options: options, transport_class: transport_class, transport_args: transport_args)
         # connect failures self-clean via connect's rescue -> disconnect ->
         # raise, and disconnect is idempotent — no double-teardown.
@@ -772,7 +785,7 @@ module ClaudeAgentSDK
         ensure
           client.disconnect
         end
-      end
+      end)
     end
 
     # Connect to Claude with optional initial prompt.
@@ -792,6 +805,7 @@ module ClaudeAgentSDK
     def connect(prompt = nil)
       return if @connected
 
+      raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)' if prompt.is_a?(Hash)
       raise ArgumentError, "prompt must be a String, an Enumerator, or nil (got #{prompt.class})" unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
 
       # Validate and configure permission settings
@@ -1050,6 +1064,19 @@ module ClaudeAgentSDK
     end
 
     # Disconnect from Claude
+    #
+    # Callable from inside a user callback (tool handler / hook /
+    # can_use_tool). With the default `callback_scheduling: :thread` the
+    # callback runs on a worker thread: the close is marshalled to the
+    # reactor, returns normally once the teardown completed, and the
+    # callback's return value is dropped (its reactor task was stopped). With
+    # `:inline` the callback's task is a child of the read task being
+    # stopped, so once the teardown has completed the deferred Async::Stop
+    # unwinds the callback — disconnect raises rather than returns there;
+    # ensure blocks run, `rescue StandardError` does not see it. The same
+    # holds, in every scheduling mode, for a streaming-input enumerator that
+    # calls disconnect: it is iterated on the reactor inside a task the close
+    # stops, so it unwinds with Async::Stop once the teardown has completed.
     def disconnect
       if @connected
         ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close,
@@ -1125,7 +1152,7 @@ module ClaudeAgentSDK
       sdk_mcp_servers = ClaudeAgentSDK.extract_sdk_mcp_servers(configured_options.mcp_servers)
 
       # Convert hooks to internal format
-      hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
+      hooks = ClaudeAgentSDK.convert_hooks_to_internal_format(configured_options.hooks)
 
       # Extract exclude_dynamic_sections and snapshot from the system prompt
       # for the initialize request (older CLIs ignore unknown initialize fields)
@@ -1236,24 +1263,6 @@ module ClaudeAgentSDK
       @query_handler.set_transcript_mirror_batcher(batcher)
     end
 
-    def convert_hooks_to_internal_format(hooks)
-      return nil unless hooks
-
-      internal_hooks = {}
-      hooks.each do |event, matchers|
-        internal_hooks[event.to_s] = []
-        matchers.each do |matcher|
-          config = {
-            matcher: matcher.matcher,
-            hooks: matcher.hooks
-          }
-          config[:timeout] = matcher.timeout if matcher.timeout
-          internal_hooks[event.to_s] << config
-        end
-      end
-      internal_hooks
-    end
-
     def writeln(string)
       write string.end_with?("\n") ? string : "#{string}\n"
     end

data/lib/generators/claude_agent_sdk/install/install_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module ClaudeAgentSDK
+  module Generators
+    # `bin/rails generate claude_agent_sdk:install` — writes the initializer,
+    # ignores the vendored CLI, and prints the next steps. Lives under
+    # lib/generators/ so Rails' generator lookup finds it by namespace.
+    class InstallGenerator < ::Rails::Generators::Base
+      # Explicit: Thor derives the namespace by snake-casing the class path,
+      # which turns ClaudeAgentSDK into "claude_agent_s_d_k".
+      namespace 'claude_agent_sdk:install'
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates config/initializers/claude_agent_sdk.rb and git-ignores the vendored Claude Code CLI.'
+
+      GITIGNORE_ENTRY = '/vendor/claude/'
+      # Spellings that already ignore the vendored CLI directory.
+      GITIGNORE_PATTERN = %r{\A/?vendor/claude/?\z}
+
+      def create_initializer
+        template 'claude_agent_sdk.rb.tt', 'config/initializers/claude_agent_sdk.rb'
+      end
+
+      def ignore_vendored_cli
+        path = File.join(destination_root, '.gitignore')
+        entry = "# Claude Code CLI vendored by `bin/rails claude_agent_sdk:install_cli`\n#{GITIGNORE_ENTRY}\n"
+        return create_file('.gitignore', entry) unless File.exist?(path)
+
+        content = File.read(path)
+        if content.each_line.any? { |line| line.strip.match?(GITIGNORE_PATTERN) }
+          say_status :identical, '.gitignore (already ignores vendor/claude)', :blue
+        else
+          append_to_file '.gitignore', gitignore_separator(content) + entry
+        end
+      end
+
+      def show_next_steps
+        say <<~MSG
+
+          Next steps:
+            1. Install the Claude Code CLI this gem is tested with into vendor/claude
+               (run it in your Dockerfile / bin/setup as well):
+                 bin/rails claude_agent_sdk:install_cli
+            2. Provide credentials to the CLI, e.g. ANTHROPIC_API_KEY in the environment.
+            3. Review config/initializers/claude_agent_sdk.rb.
+
+          Rails guide: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md
+        MSG
+      end
+
+      private
+
+      # Start the appended block on its own line, after a blank one.
+      def gitignore_separator(content)
+        return '' if content.empty?
+
+        content.end_with?("\n") ? "\n" : "\n\n"
+      end
+    end
+  end
+end

data/lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Claude Agent SDK defaults, merged into every ClaudeAgentSDK.query and
+# ClaudeAgentSDK::Client session; per-call ClaudeAgentOptions override them.
+# Guide: https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md
+
+# Uncomment together with `observers:` below (needs the opentelemetry-sdk gem).
+# require 'claude_agent_sdk/instrumentation'
+
+ClaudeAgentSDK.configure do |config|
+  config.default_options = {
+    # Model: full ID or alias ('opus', 'sonnet', 'haiku'). Unset, the CLI picks.
+    # model: 'claude-sonnet-5',
+    # model: 'claude-opus-5',
+    # model: 'claude-haiku-4-5',
+
+    # Tool permissions: 'default', 'acceptEdits', 'plan', 'dontAsk',
+    # 'bypassPermissions' (unattended jobs in a sandbox only), or 'auto'.
+    # permission_mode: 'default',
+
+    # The CLI is found in vendor/claude relative to the process cwd (Rails.root
+    # under bin/rails, Puma and most job runners). Pin it for other launchers:
+    # cli_path: Rails.root.join('vendor', 'claude', 'claude').to_s,
+
+    # OpenTelemetry tracing (Langfuse, Honeycomb, ...). A factory lambda gives
+    # every query/session its own observer — safe under Puma and job threads.
+    # observers: [-> { ClaudeAgentSDK::Instrumentation::OTelObserver.new }],
+
+    # Wraps every SDK callback (tool handlers, hooks, permission callbacks,
+    # message blocks, observers) so ActiveRecord connections go back to the
+    # pool. Not a bare `Rails.application.executor.wrap`: that deadlocks with
+    # development code reloading. See docs/rails.md ("callback_wrapper").
+    callback_wrapper: ClaudeAgentSDK::Railtie.callback_wrapper
+  }
+end

metadata

@@ -1,36 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.33.1
+  version: 0.35.0
 platform: ruby
 authors:
-- Community Contributors
+- ya-luotao
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-21 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.10'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: '0.22'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -40,7 +46,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.20'
+        version: '0.22'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -100,9 +106,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.87.0
-description: Unofficial Ruby SDK for interacting with Claude Code, supporting bidirectional
-  conversations, custom tools, and hooks. Not officially maintained by Anthropic.
-email: []
+description: 'Unofficial Ruby SDK for the Claude Code agent runtime: one-shot queries
+  and bidirectional sessions, in-process custom tools, hooks and permission callbacks.
+  Includes Rails integration (Railtie, install generator, CLI-vendoring rake task,
+  executor-aware callback wrapper), a pinned CLI installer, OpenTelemetry tracing,
+  and session transcript mirroring. Not affiliated with or officially maintained by
+  Anthropic.'
+email:
+- luotao@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -135,6 +146,7 @@ files:
 - lib/claude_agent_sdk/observer.rb
 - lib/claude_agent_sdk/option_warnings.rb
 - lib/claude_agent_sdk/query.rb
+- lib/claude_agent_sdk/railtie.rb
 - lib/claude_agent_sdk/sdk_mcp_server.rb
 - lib/claude_agent_sdk/session_mutations.rb
 - lib/claude_agent_sdk/session_resume.rb
@@ -143,11 +155,15 @@ files:
 - lib/claude_agent_sdk/sessions.rb
 - lib/claude_agent_sdk/streaming.rb
 - lib/claude_agent_sdk/subprocess_cli_transport.rb
+- lib/claude_agent_sdk/tasks.rb
+- lib/claude_agent_sdk/tasks/claude_agent_sdk.rake
 - lib/claude_agent_sdk/testing/session_store_conformance.rb
 - lib/claude_agent_sdk/transcript_mirror_batcher.rb
 - lib/claude_agent_sdk/transport.rb
 - lib/claude_agent_sdk/types.rb
 - lib/claude_agent_sdk/version.rb
+- lib/generators/claude_agent_sdk/install/install_generator.rb
+- lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt
 homepage: https://github.com/ya-luotao/claude-agent-sdk-ruby
 licenses:
 - MIT
@@ -175,5 +191,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Unofficial Ruby SDK for Claude Agent
+summary: Unofficial Ruby SDK for Claude Agent, with Rails integration
 test_files: []