claude_agent 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962eff5c1e28589e347c1096e8c9683714b58bc95d56f281256580311bf0b87f
-  data.tar.gz: e482f60ed6579f9b364e2947b970fca1eaf35c6eec02e5669d557b9c5caf15bc
+  metadata.gz: 791bfc30df3cce213645d97676501c53e0acd5cbcedeacadbd61b810469c2be5
+  data.tar.gz: 5cdf1984dd821ce465165e6887dcb430989669692924d747e4a23d49f7aae0ad
 SHA512:
-  metadata.gz: 03fc463581c3dc92b0f3d121e7f59f252b746e0a049f4eb505ef14938799de397f4cb64cd01fca09946c8be38b767205792a06f51cfa968abd880eebc2b7d79c
-  data.tar.gz: a3407945fe4b87957c898ca2872f869b62cd520db7afbf76602aa5105febcb2a95dc5a66131b68ad0254b8b7f922ecc387394f96bd78ac9da2227443f3cb2a33
+  metadata.gz: 6824f825982dc3066a6512f9d2d8a84253f6b861916b76917792ab9bf5a7f52a026105de09ab357e0a99a9cd289a77f6f7574c3e71569d1f8d2bcfa6fb31997d
+  data.tar.gz: df13b541959f5962c385b5295508b89f03471c2617e0b787747e130cddae9d2d74b512d3c2a63a9d959290d10c2d3f676241dec9f4ffc4a51caea12717e7eacf

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-01-11
+
+### Added
+- V2 Session API for multi-turn conversations (`unstable_v2_create_session`, `unstable_v2_resume_session`, `unstable_v2_prompt`)
+- `Session` class for stateful conversation management
+- `SessionOptions` data type for V2 API configuration
+
+### Fixed
+- `Options#initialize` now correctly handles nil values without overriding defaults
+
 ## [0.1.0] - 2026-01-10
 
 ### Added

data/SPEC.md

@@ -3,8 +3,8 @@
 This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
 
 **Reference Versions:**
-- TypeScript SDK: v0.2.3 (npm package)
-- Python SDK: Latest from GitHub (commit 55372da)
+- TypeScript SDK: v0.2.5 (npm package)
+- Python SDK: Latest from GitHub (commit 3b7e3ba)
 - Ruby SDK: This repository
 
 ---
@@ -64,12 +64,12 @@ Configuration options for SDK queries and clients.
 | `sandbox`                         |     ✅      |   ✅    |  ✅   | Sandbox settings                                            |
 | `settingSources`                  |     ✅      |   ✅    |  ✅   | Which settings to load                                      |
 | `plugins`                         |     ✅      |   ✅    |  ✅   | Plugin configurations                                       |
-| `betas`                           |     ✅      |   ✅    |  ✅   | Beta features (e.g., context-1m)                            |
+| `betas`                           |     ✅      |   ✅    |  ✅   | Beta features (e.g., context-1m-2025-08-07)                 |
 | `abortController`                 |     ✅      |   ❌    |  ✅   | Cancellation controller                                     |
 | `stderr`                          |     ✅      |   ✅    |  ✅   | Stderr callback                                             |
 | `spawnClaudeCodeProcess`          |     ✅      |   ❌    |  ✅   | Custom spawn function                                       |
 | `pathToClaudeCodeExecutable`      |     ✅      |   ✅    |  ✅   | Custom CLI path                                             |
-| `executable`                      |     ✅      |   ❌    |  ❌   | JS runtime (bun/deno/node)                                  |
+| `executable`                      |     ✅      |   ❌    |  ❌   | JS runtime (node/bun/deno)                                  |
 | `executableArgs`                  |     ✅      |   ❌    |  ❌   | JS runtime args                                             |
 | `extraArgs`                       |     ✅      |   ✅    |  ✅   | Extra CLI arguments                                         |
 | `user`                            |     ❌      |   ✅    |  ✅   | User identifier                                             |
@@ -289,7 +289,7 @@ Permission handling and updates.
 | `updatedPermissions` |     ✅      |   ✅    |  ✅   |
 | `message` (deny)     |     ✅      |   ✅    |  ✅   |
 | `interrupt` (deny)   |     ✅      |   ✅    |  ✅   |
-| `toolUseID`          |     ✅      |   ❌    |  ❌   |
+| `toolUseID`          |     ✅      |   ❌    |  ✅   |
 
 ### Permission Update Types
 
@@ -316,7 +316,7 @@ Permission handling and updates.
 
 | Field            | TypeScript | Python | Ruby | Notes                     |
 |------------------|:----------:|:------:|:----:|---------------------------|
-| `signal`         |     ✅      |   ✅    |  ❌   | Abort signal              |
+| `signal`         |     ✅      |   ✅    |  ✅   | Abort signal              |
 | `suggestions`    |     ✅      |   ✅    |  ✅   | Permission suggestions    |
 | `blockedPath`    |     ✅      |   ✅    |  ✅   | Blocked file path         |
 | `decisionReason` |     ✅      |   ❌    |  ✅   | Why permission triggered  |
@@ -392,10 +392,10 @@ Session management and resumption.
 
 | Feature                     | TypeScript | Python | Ruby | Notes                     |
 |-----------------------------|:----------:|:------:|:----:|---------------------------|
-| `SDKSession` interface      |     ✅      |   ❌    |  ❌   | Multi-turn session object |
-| `unstable_v2_createSession` |     ✅      |   ❌    |  ❌   | Create new session        |
-| `unstable_v2_resumeSession` |     ✅      |   ❌    |  ❌   | Resume existing session   |
-| `unstable_v2_prompt`        |     ✅      |   ❌    |  ❌   | One-shot prompt           |
+| `SDKSession` interface      |     ✅      |   ❌    |  ✅   | Multi-turn session object |
+| `unstable_v2_createSession` |     ✅      |   ❌    |  ✅   | Create new session        |
+| `unstable_v2_resumeSession` |     ✅      |   ❌    |  ✅   | Resume existing session   |
+| `unstable_v2_prompt`        |     ✅      |   ❌    |  ✅   | One-shot prompt           |
 
 ---
 
@@ -541,7 +541,9 @@ Public API surface for SDK clients.
 - Primary reference for API surface (most comprehensive)
 - Source is bundled/minified, but `sdk.d.ts` provides complete type definitions
 - Includes unstable V2 session API
-- Version 0.2.3 adds `maxOutputTokens` field to `ModelUsage`
+- Version 0.2.5 includes `maxOutputTokens` field in `ModelUsage`
+- Adds `deno` as supported executable option
+- Includes experimental `criticalSystemReminder_EXPERIMENTAL` for agent definitions
 
 ### Python SDK
 - Full source available
@@ -556,3 +558,4 @@ Public API surface for SDK clients.
 - Complete control protocol support
 - Dedicated Client class for multi-turn conversations
 - Full hook event support including all 12 events
+- Full V2 Session API support (unstable)

data/lib/claude_agent/options.rb

@@ -60,7 +60,9 @@ module ClaudeAgent
     attr_accessor(*ATTRIBUTES)
 
     def initialize(**kwargs)
-      merged = DEFAULTS.merge(kwargs)
+      # Remove nil values so they don't override defaults
+      filtered = kwargs.compact
+      merged = DEFAULTS.merge(filtered)
       ATTRIBUTES.each do |attr|
         instance_variable_set(:"@#{attr}", merged[attr])
       end

data/lib/claude_agent/permissions.rb

@@ -5,11 +5,12 @@ module ClaudeAgent
   #
   # @example Allow with modified input
   #   PermissionResultAllow.new(
-  #     updated_input: input.merge("safe" => true)
+  #     updated_input: input.merge("safe" => true),
+  #     tool_use_id: "tool_123"
   #   )
   #
-  PermissionResultAllow = Data.define(:updated_input, :updated_permissions) do
-    def initialize(updated_input: nil, updated_permissions: nil)
+  PermissionResultAllow = Data.define(:updated_input, :updated_permissions, :tool_use_id) do
+    def initialize(updated_input: nil, updated_permissions: nil, tool_use_id: nil)
       super
     end
 
@@ -21,6 +22,7 @@ module ClaudeAgent
       h = { behavior: "allow" }
       h[:updatedInput] = updated_input if updated_input
       h[:updatedPermissions] = updated_permissions&.map { |p| p.respond_to?(:to_h) ? p.to_h : p } if updated_permissions
+      h[:toolUseID] = tool_use_id if tool_use_id
       h
     end
   end
@@ -30,11 +32,12 @@ module ClaudeAgent
   # @example Deny with message
   #   PermissionResultDeny.new(
   #     message: "Operation not allowed",
-  #     interrupt: true
+  #     interrupt: true,
+  #     tool_use_id: "tool_123"
   #   )
   #
-  PermissionResultDeny = Data.define(:message, :interrupt) do
-    def initialize(message: "", interrupt: false)
+  PermissionResultDeny = Data.define(:message, :interrupt, :tool_use_id) do
+    def initialize(message: "", interrupt: false, tool_use_id: nil)
       super
     end
 
@@ -43,7 +46,9 @@ module ClaudeAgent
     end
 
     def to_h
-      { behavior: "deny", message: message, interrupt: interrupt }
+      h = { behavior: "deny", message: message, interrupt: interrupt }
+      h[:toolUseID] = tool_use_id if tool_use_id
+      h
     end
   end
 
@@ -141,7 +146,8 @@ module ClaudeAgent
   #     blocked_path: "/etc/passwd",
   #     decision_reason: "Path outside allowed directories",
   #     tool_use_id: "tool_123",
-  #     agent_id: "agent_456"
+  #     agent_id: "agent_456",
+  #     signal: abort_signal
   #   )
   #
   ToolPermissionContext = Data.define(
@@ -149,14 +155,16 @@ module ClaudeAgent
     :blocked_path,
     :decision_reason,
     :tool_use_id,
-    :agent_id
+    :agent_id,
+    :signal
   ) do
     def initialize(
       permission_suggestions: nil,
       blocked_path: nil,
       decision_reason: nil,
       tool_use_id: nil,
-      agent_id: nil
+      agent_id: nil,
+      signal: nil
     )
       super
     end

data/lib/claude_agent/session.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # V2 Session options (subset of full Options)
+  # V2 API - UNSTABLE
+  # @alpha
+  #
+  # @example
+  #   options = SessionOptions.new(
+  #     model: "claude-sonnet-4-5-20250929",
+  #     permission_mode: "acceptEdits"
+  #   )
+  #
+  SessionOptions = Data.define(
+    :model,
+    :path_to_claude_code_executable,
+    :env,
+    :allowed_tools,
+    :disallowed_tools,
+    :can_use_tool,
+    :hooks,
+    :permission_mode
+  ) do
+    def initialize(
+      model:,
+      path_to_claude_code_executable: nil,
+      env: nil,
+      allowed_tools: nil,
+      disallowed_tools: nil,
+      can_use_tool: nil,
+      hooks: nil,
+      permission_mode: nil
+    )
+      super
+    end
+  end
+
+  # V2 API - UNSTABLE
+  # Multi-turn session interface for persistent conversations.
+  #
+  # This provides a simpler interface than the full Client class,
+  # matching the TypeScript SDK's SDKSession interface.
+  #
+  # @alpha
+  #
+  # @example Create a session and send messages
+  #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
+  #   session.send("Hello!")
+  #   session.stream.each { |msg| puts msg.inspect }
+  #   session.close
+  #
+  class Session
+    attr_reader :session_id, :options
+
+    def initialize(options)
+      @options = options.is_a?(SessionOptions) ? options : SessionOptions.new(**options)
+      @client = nil
+      @session_id = nil
+      @closed = false
+    end
+
+    # Send a message to the agent
+    #
+    # @param message [String, UserMessage] The message to send
+    # @return [void]
+    def send(message)
+      ensure_connected!
+      content = message.is_a?(String) ? message : message
+      @client.send_message(content)
+    end
+
+    # Stream messages from the agent
+    #
+    # @return [Enumerator<message>] An enumerator of messages
+    # @yield [message] Each message received from the agent
+    def stream(&block)
+      ensure_connected!
+      if block_given?
+        @client.receive_response(&block)
+      else
+        @client.receive_response
+      end
+    end
+
+    # Close the session
+    #
+    # @return [void]
+    def close
+      return if @closed
+      @client&.disconnect
+      @closed = true
+    end
+
+    # Check if session is closed
+    #
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    def ensure_connected!
+      raise AbortError, "Session is closed" if @closed
+      return if @client&.connected?
+
+      @client = Client.new(options: build_client_options)
+      @client.connect
+      update_session_id
+    end
+
+    def build_client_options
+      Options.new(
+        model: @options.model,
+        cli_path: @options.path_to_claude_code_executable,
+        env: @options.env,
+        allowed_tools: @options.allowed_tools,
+        disallowed_tools: @options.disallowed_tools,
+        can_use_tool: @options.can_use_tool,
+        hooks: @options.hooks,
+        permission_mode: @options.permission_mode
+      )
+    end
+
+    def update_session_id
+      # Session ID is typically extracted from the first system message
+      # but since we don't have it immediately, we leave it nil until available
+      @session_id = @client.server_info&.dig("session_id")
+    end
+  end
+
+  class << self
+    # V2 API - UNSTABLE
+    # Create a persistent session for multi-turn conversations.
+    #
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [Session] A new session instance
+    # @alpha
+    #
+    # @example
+    #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_create_session(options)
+      Session.new(options)
+    end
+
+    # V2 API - UNSTABLE
+    # Resume an existing session by ID.
+    #
+    # @param session_id [String] The session ID to resume
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [Session] A session configured to resume the specified session
+    # @alpha
+    #
+    # @example
+    #   session = ClaudeAgent.unstable_v2_resume_session("session-abc123", model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_resume_session(session_id, options)
+      # For resumption, we need to pass the resume option through
+      # Since SessionOptions doesn't have resume, we handle it in the Client options
+      session = Session.new(options)
+      session.instance_variable_set(:@resume_session_id, session_id)
+
+      # Override build_client_options to include resume
+      session.define_singleton_method(:build_client_options) do
+        Options.new(
+          model: @options.model,
+          cli_path: @options.path_to_claude_code_executable,
+          env: @options.env,
+          allowed_tools: @options.allowed_tools,
+          disallowed_tools: @options.disallowed_tools,
+          can_use_tool: @options.can_use_tool,
+          hooks: @options.hooks,
+          permission_mode: @options.permission_mode,
+          resume: @resume_session_id
+        )
+      end
+
+      session
+    end
+
+    # V2 API - UNSTABLE
+    # One-shot convenience function for single prompts.
+    #
+    # @param message [String] The prompt message
+    # @param options [Hash, SessionOptions] Session configuration
+    # @return [ResultMessage] The result of the query
+    # @alpha
+    #
+    # @example
+    #   result = ClaudeAgent.unstable_v2_prompt("What files are here?", model: "claude-sonnet-4-5-20250929")
+    #
+    def unstable_v2_prompt(message, options)
+      session = unstable_v2_create_session(options)
+      begin
+        session.send(message)
+        result = nil
+        session.stream.each do |msg|
+          result = msg if msg.is_a?(ResultMessage)
+        end
+        result
+      ensure
+        session.close
+      end
+    end
+  end
+end

data/lib/claude_agent/types.rb

@@ -83,7 +83,7 @@ module ClaudeAgent
   # Per-model usage statistics returned in result messages (TypeScript SDK parity)
   #
   # @example
-  #   usage = ModelUsage.new(input_tokens: 100, output_tokens: 50, cost_usd: 0.01)
+  #   usage = ModelUsage.new(input_tokens: 100, output_tokens: 50, cost_usd: 0.01, max_output_tokens: 4096)
   #
   ModelUsage = Data.define(
     :input_tokens,
@@ -92,7 +92,8 @@ module ClaudeAgent
     :cache_creation_input_tokens,
     :web_search_requests,
     :cost_usd,
-    :context_window
+    :context_window,
+    :max_output_tokens
   ) do
     def initialize(
       input_tokens: 0,
@@ -101,7 +102,8 @@ module ClaudeAgent
       cache_creation_input_tokens: 0,
       web_search_requests: 0,
       cost_usd: 0.0,
-      context_window: nil
+      context_window: nil,
+      max_output_tokens: nil
     )
       super
     end

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/claude_agent.rb

@@ -22,6 +22,7 @@ require_relative "claude_agent/mcp/tool"
 require_relative "claude_agent/mcp/server"
 require_relative "claude_agent/query"
 require_relative "claude_agent/client"
+require_relative "claude_agent/session"            # V2 Session API (unstable)
 
 module ClaudeAgent
   # Re-export key classes at module level for convenience

data/sig/claude_agent.rbs

@@ -122,8 +122,9 @@ module ClaudeAgent
     attr_reader web_search_requests: Integer
     attr_reader cost_usd: Float
     attr_reader context_window: Integer?
+    attr_reader max_output_tokens: Integer?
 
-    def initialize: (?input_tokens: Integer, ?output_tokens: Integer, ?cache_read_input_tokens: Integer, ?cache_creation_input_tokens: Integer, ?web_search_requests: Integer, ?cost_usd: Float, ?context_window: Integer?) -> void
+    def initialize: (?input_tokens: Integer, ?output_tokens: Integer, ?cache_read_input_tokens: Integer, ?cache_creation_input_tokens: Integer, ?web_search_requests: Integer, ?cost_usd: Float, ?context_window: Integer?, ?max_output_tokens: Integer?) -> void
   end
 
   class SDKPermissionDenial
@@ -687,8 +688,9 @@ module ClaudeAgent
   class PermissionResultAllow
     attr_reader updated_input: Hash[String, untyped]?
     attr_reader updated_permissions: Array[PermissionUpdate]?
+    attr_reader tool_use_id: String?
 
-    def initialize: (?updated_input: Hash[String, untyped]?, ?updated_permissions: Array[PermissionUpdate]?) -> void
+    def initialize: (?updated_input: Hash[String, untyped]?, ?updated_permissions: Array[PermissionUpdate]?, ?tool_use_id: String?) -> void
     def behavior: () -> "allow"
     def to_h: () -> Hash[Symbol, untyped]
   end
@@ -696,8 +698,9 @@ module ClaudeAgent
   class PermissionResultDeny
     attr_reader message: String
     attr_reader interrupt: bool
+    attr_reader tool_use_id: String?
 
-    def initialize: (?message: String, ?interrupt: bool) -> void
+    def initialize: (?message: String, ?interrupt: bool, ?tool_use_id: String?) -> void
     def behavior: () -> "deny"
     def to_h: () -> Hash[Symbol, untyped]
   end
@@ -728,8 +731,9 @@ module ClaudeAgent
     attr_reader decision_reason: String?
     attr_reader tool_use_id: String?
     attr_reader agent_id: String?
+    attr_reader signal: AbortSignal?
 
-    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?) -> void
+    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?, ?signal: AbortSignal?) -> void
   end
 
   # Client
@@ -909,4 +913,39 @@ module ClaudeAgent
       def to_config: () -> Hash[Symbol, untyped]
     end
   end
+
+  # V2 Session API - UNSTABLE
+  # @alpha
+
+  # V2 Session options (subset of full Options)
+  class SessionOptions
+    attr_reader model: String
+    attr_reader path_to_claude_code_executable: String?
+    attr_reader env: Hash[String, String]?
+    attr_reader allowed_tools: Array[String]?
+    attr_reader disallowed_tools: Array[String]?
+    attr_reader can_use_tool: (^(String, Hash[String, untyped], untyped) -> permission_result)?
+    attr_reader hooks: Hash[String, Array[HookMatcher]]?
+    attr_reader permission_mode: String?
+
+    def initialize: (model: String, ?path_to_claude_code_executable: String?, ?env: Hash[String, String]?, ?allowed_tools: Array[String]?, ?disallowed_tools: Array[String]?, ?can_use_tool: (^(String, Hash[String, untyped], untyped) -> permission_result)?, ?hooks: Hash[String, Array[HookMatcher]]?, ?permission_mode: String?) -> void
+  end
+
+  # V2 Session interface for multi-turn conversations
+  class Session
+    attr_reader session_id: String?
+    attr_reader options: SessionOptions
+
+    def initialize: (Hash[Symbol, untyped] | SessionOptions options) -> void
+    def send: (String | UserMessage message) -> void
+    def stream: () -> Enumerator[message, void]
+             | () { (message) -> void } -> void
+    def close: () -> void
+    def closed?: () -> bool
+  end
+
+  # V2 API module-level methods
+  def self.unstable_v2_create_session: (Hash[Symbol, untyped] | SessionOptions options) -> Session
+  def self.unstable_v2_resume_session: (String session_id, Hash[Symbol, untyped] | SessionOptions options) -> Session
+  def self.unstable_v2_prompt: (String message, Hash[Symbol, untyped] | SessionOptions options) -> ResultMessage
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Thomas Carr
@@ -63,6 +63,7 @@ files:
 - lib/claude_agent/permissions.rb
 - lib/claude_agent/query.rb
 - lib/claude_agent/sandbox_settings.rb
+- lib/claude_agent/session.rb
 - lib/claude_agent/spawn.rb
 - lib/claude_agent/transport/base.rb
 - lib/claude_agent/transport/subprocess.rb