claude_agent 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 791bfc30df3cce213645d97676501c53e0acd5cbcedeacadbd61b810469c2be5
-  data.tar.gz: 5cdf1984dd821ce465165e6887dcb430989669692924d747e4a23d49f7aae0ad
+  metadata.gz: c630af2842675c8aa126588105617fa1af823c437ef1095029b3f7e9efbc982c
+  data.tar.gz: 16199aa31e03d542bf9128356594a0ea6659a16ecfba7fa2b3e1a97429662ef2
 SHA512:
-  metadata.gz: 6824f825982dc3066a6512f9d2d8a84253f6b861916b76917792ab9bf5a7f52a026105de09ab357e0a99a9cd289a77f6f7574c3e71569d1f8d2bcfa6fb31997d
-  data.tar.gz: df13b541959f5962c385b5295508b89f03471c2617e0b787747e130cddae9d2d74b512d3c2a63a9d959290d10c2d3f676241dec9f4ffc4a51caea12717e7eacf
+  metadata.gz: 8f555706af9480e572d8f310a73ab0d1294b9eaf6b162146364032450bbad86f0a2e962649f12e74e48dae4155fd1929221efd46a349253d1bf96ad09249db54
+  data.tar.gz: fbf3a236589cad360dbfff15dfa8164a353a973e211e5f4ab4802d8b383d803359a137a9a312478bbd0175f7b866c4f40795f55c6d8b2eb8f028992f403b5182

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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.5 (npm package)
-- Python SDK: Latest from GitHub (commit 3b7e3ba)
+- TypeScript SDK: v0.2.9 (npm package)
+- Python SDK: v0.1.20 from GitHub (commit 04da88d)
 - Ruby SDK: This repository
 
 ---
@@ -65,12 +65,13 @@ Configuration options for SDK queries and clients.
 | `settingSources`                  |     ✅      |   ✅    |  ✅   | Which settings to load                                      |
 | `plugins`                         |     ✅      |   ✅    |  ✅   | Plugin configurations                                       |
 | `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 (node/bun/deno)                                  |
-| `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                                             |
 
@@ -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,21 +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.5 includes `maxOutputTokens` field in `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
@@ -206,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/version.rb

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

data/sig/claude_agent.rbs

@@ -279,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?
@@ -633,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas Carr