claude_agent 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 962eff5c1e28589e347c1096e8c9683714b58bc95d56f281256580311bf0b87f
-  data.tar.gz: e482f60ed6579f9b364e2947b970fca1eaf35c6eec02e5669d557b9c5caf15bc
+  metadata.gz: c630af2842675c8aa126588105617fa1af823c437ef1095029b3f7e9efbc982c
+  data.tar.gz: 16199aa31e03d542bf9128356594a0ea6659a16ecfba7fa2b3e1a97429662ef2
 SHA512:
-  metadata.gz: 03fc463581c3dc92b0f3d121e7f59f252b746e0a049f4eb505ef14938799de397f4cb64cd01fca09946c8be38b767205792a06f51cfa968abd880eebc2b7d79c
-  data.tar.gz: a3407945fe4b87957c898ca2872f869b62cd520db7afbf76602aa5105febcb2a95dc5a66131b68ad0254b8b7f922ecc387394f96bd78ac9da2227443f3cb2a33
+  metadata.gz: 8f555706af9480e572d8f310a73ab0d1294b9eaf6b162146364032450bbad86f0a2e962649f12e74e48dae4155fd1929221efd46a349253d1bf96ad09249db54
+  data.tar.gz: fbf3a236589cad360dbfff15dfa8164a353a973e211e5f4ab4802d8b383d803359a137a9a312478bbd0175f7b866c4f40795f55c6d8b2eb8f028992f403b5182

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-01-16
+
+### Added
+- `agent` option for specifying main thread agent name (TypeScript SDK v0.2.9 parity)
+- `model` field in `SessionStartInput` hook input
+
+## [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/README.md

@@ -1,6 +1,6 @@
 # ClaudeAgent
 
-A Ruby SDK for building AI-powered applications with [Claude Code](https://docs.anthropic.com/en/docs/claude-code). This library wraps the Claude Code CLI, providing both simple one-shot queries and interactive bidirectional sessions.
+Ruby gem for building AI-powered applications with the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview). This library essentially wraps the Claude Code CLI, providing both simple one-shot queries and interactive bidirectional sessions.
 
 ## Requirements
 
@@ -95,6 +95,9 @@ options = ClaudeAgent::Options.new(
   cwd: "/path/to/project",
   add_dirs: ["/additional/path"],
 
+  # Agent configuration
+  agent: "my-agent",  # Agent name for main thread
+
   # Session management
   resume: "session-id",
   continue_conversation: true,
@@ -456,7 +459,7 @@ All available hook events:
 | PostToolUseFailure | `PostToolUseFailureInput` | tool_name, tool_input, error, tool_use_id, is_interrupt |
 | Notification       | `NotificationInput`       | message, title, notification_type                       |
 | UserPromptSubmit   | `UserPromptSubmitInput`   | prompt                                                  |
-| SessionStart       | `SessionStartInput`       | source, agent_type                                      |
+| SessionStart       | `SessionStartInput`       | source, agent_type, model                               |
 | SessionEnd         | `SessionEndInput`         | reason                                                  |
 | Stop               | `StopInput`               | stop_hook_active                                        |
 | SubagentStart      | `SubagentStartInput`      | agent_id, agent_type                                    |
@@ -591,6 +594,88 @@ puts client.account_info.email
 client.disconnect
 ```
 
+## V2 Session API (Unstable)
+
+> **⚠️ Alpha API**: This API is unstable and may change without notice.
+
+The V2 Session API provides a simpler interface for multi-turn conversations, matching the TypeScript SDK's `SDKSession` interface.
+
+### Create a Session
+
+```ruby
+# Create a new session
+session = ClaudeAgent.unstable_v2_create_session(
+  model: "claude-sonnet-4-5-20250514",
+  permission_mode: "acceptEdits"
+)
+
+# Send a message
+session.send("Hello, Claude!")
+
+# Stream responses
+session.stream.each do |msg|
+  case msg
+  when ClaudeAgent::AssistantMessage
+    puts msg.text
+  when ClaudeAgent::ResultMessage
+    puts "Done! Cost: $#{msg.total_cost_usd}"
+  end
+end
+
+# Continue the conversation
+session.send("Tell me more")
+session.stream.each { |msg| puts msg.text if msg.is_a?(ClaudeAgent::AssistantMessage) }
+
+# Close when done
+session.close
+```
+
+### Resume a Session
+
+```ruby
+# Resume an existing session by ID
+session = ClaudeAgent.unstable_v2_resume_session(
+  "session-abc123",
+  model: "claude-sonnet-4-5-20250514"
+)
+
+session.send("What were we discussing?")
+session.stream.each { |msg| puts msg.text if msg.is_a?(ClaudeAgent::AssistantMessage) }
+session.close
+```
+
+### One-Shot Prompt
+
+```ruby
+# Simple one-shot prompt (auto-closes session)
+result = ClaudeAgent.unstable_v2_prompt(
+  "What is 2 + 2?",
+  model: "claude-sonnet-4-5-20250514"
+)
+
+puts "Success: #{result.success?}"
+puts "Cost: $#{result.total_cost_usd}"
+```
+
+### SessionOptions
+
+The V2 API uses a simplified options type:
+
+```ruby
+options = ClaudeAgent::SessionOptions.new(
+  model: "claude-sonnet-4-5-20250514",           # Required
+  permission_mode: "acceptEdits",                 # Optional
+  allowed_tools: ["Read", "Grep"],                # Optional
+  disallowed_tools: ["Write"],                    # Optional
+  can_use_tool: ->(name, input, ctx) { ... },    # Optional
+  hooks: { "PreToolUse" => [...] },               # Optional
+  env: { "MY_VAR" => "value" },                   # Optional
+  path_to_claude_code_executable: "/custom/path"  # Optional
+)
+
+session = ClaudeAgent.unstable_v2_create_session(options)
+```
+
 ## Types Reference
 
 ### Return Types

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.9 (npm package)
+- Python SDK: v0.1.20 from GitHub (commit 04da88d)
 - Ruby SDK: This repository
 
 ---
@@ -64,13 +64,14 @@ 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)                 |
+| `agent`                           |     ✅      |   ❌    |  ✅   | Agent name for main thread                                  |
 | `abortController`                 |     ✅      |   ❌    |  ✅   | Cancellation controller                                     |
 | `stderr`                          |     ✅      |   ✅    |  ✅   | Stderr callback                                             |
 | `spawnClaudeCodeProcess`          |     ✅      |   ❌    |  ✅   | Custom spawn function                                       |
 | `pathToClaudeCodeExecutable`      |     ✅      |   ✅    |  ✅   | Custom CLI path                                             |
-| `executable`                      |     ✅      |   ❌    |  ❌   | JS runtime (bun/deno/node)                                  |
-| `executableArgs`                  |     ✅      |   ❌    |  ❌   | JS runtime args                                             |
+| `executable`                      |     ✅      |  N/A   | N/A  | JS runtime (node/bun/deno) - JS-specific                    |
+| `executableArgs`                  |     ✅      |  N/A   | N/A  | JS runtime args - JS-specific                               |
 | `extraArgs`                       |     ✅      |   ✅    |  ✅   | Extra CLI arguments                                         |
 | `user`                            |     ❌      |   ✅    |  ✅   | User identifier                                             |
 
@@ -289,7 +290,7 @@ Permission handling and updates.
 | `updatedPermissions` |     ✅      |   ✅    |  ✅   |
 | `message` (deny)     |     ✅      |   ✅    |  ✅   |
 | `interrupt` (deny)   |     ✅      |   ✅    |  ✅   |
-| `toolUseID`          |     ✅      |   ❌    |  ❌   |
+| `toolUseID`          |     ✅      |   ❌    |  ✅   |
 
 ### Permission Update Types
 
@@ -316,7 +317,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 +393,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           |
 
 ---
 
@@ -531,6 +532,7 @@ Public API surface for SDK clients.
 
 - ✅ = Fully implemented
 - ❌ = Not implemented
+- N/A = Not applicable (language-specific feature)
 - Partial = Partially implemented
 
 ---
@@ -541,18 +543,24 @@ 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.9 adds `agent` option for specifying main thread agent
+- Adds `deno` as supported executable option
+- Includes experimental `criticalSystemReminder_EXPERIMENTAL` for agent definitions
+- `SessionStartHookInput` includes `model` field
 
 ### Python SDK
-- Full source available
+- Full source available (v0.1.20)
 - Fewer control protocol features than TypeScript
 - Does not support SessionStart/SessionEnd/Notification hooks due to setup limitations
 - Missing several permission modes (delegate, dontAsk)
 - `excludedCommands` in sandbox now supported
+- `tool_use_id` now included in PreToolUseHookInput
 
 ### Ruby SDK (This Repository)
-- Aims for TypeScript SDK parity
+- Full TypeScript SDK feature parity achieved
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - 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)
+- `executable`/`executableArgs` marked N/A (JS runtime options not applicable to Ruby)

data/lib/claude_agent/hooks.rb

@@ -141,14 +141,16 @@ module ClaudeAgent
   # Input for SessionStart hook (TypeScript SDK parity)
   #
   class SessionStartInput < BaseHookInput
-    attr_reader :source, :agent_type
+    attr_reader :source, :agent_type, :model
 
     # @param source [String] One of: "startup", "resume", "clear", "compact"
     # @param agent_type [String, nil] Type of agent if running in subagent context
-    def initialize(source:, agent_type: nil, **kwargs)
+    # @param model [String, nil] Model being used for this session
+    def initialize(source:, agent_type: nil, model: nil, **kwargs)
       super(hook_event_name: "SessionStart", **kwargs)
       @source = source
       @agent_type = agent_type
+      @model = model
     end
   end
 

data/lib/claude_agent/options.rb

@@ -50,7 +50,7 @@ module ClaudeAgent
       continue_conversation resume fork_session resume_session_at
       max_turns max_budget_usd max_thinking_tokens
       strict_mcp_config mcp_servers hooks
-      settings sandbox cwd add_dirs env user
+      settings sandbox cwd add_dirs env user agent
       cli_path extra_args agents setting_sources plugins
       include_partial_messages output_format enable_file_checkpointing
       persist_session betas max_buffer_size stderr_callback
@@ -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
@@ -204,6 +206,7 @@ module ClaudeAgent
     def environment_args
       [].tap do |args|
         args.push("--user", user) if user
+        args.push("--agent", agent) if agent
         add_dirs.each { |dir| args.push("--add-dir", dir.to_s) }
         args.push("--setting-sources", setting_sources.join(",")) if setting_sources&.any?
         plugins.each do |plugin|

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.3.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
@@ -278,6 +279,7 @@ module ClaudeAgent
     attr_accessor add_dirs: Array[String]
     attr_accessor env: Hash[String, String]
     attr_accessor user: String?
+    attr_accessor agent: String?
 
     # CLI configuration
     attr_accessor cli_path: String?
@@ -632,8 +634,9 @@ module ClaudeAgent
   class SessionStartInput < BaseHookInput
     attr_reader source: String
     attr_reader agent_type: String?
+    attr_reader model: String?
 
-    def initialize: (source: String, ?agent_type: String?, **untyped) -> void
+    def initialize: (source: String, ?agent_type: String?, ?model: String?, **untyped) -> void
   end
 
   class SessionEndInput < BaseHookInput
@@ -687,8 +690,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 +700,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 +733,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 +915,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.3.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