claude-agent-sdk 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52b6649f2a72ef33e746d168e4016dcc72c1439157fbe5b971edbd55b0a0d404
-  data.tar.gz: a344cc38d96ef7185630c1e1518a5cf6d08a855f40b39092728236d5a48df50d
+  metadata.gz: '03965bed10e6220b6f00d32ad789aa5c743c7c74f5625f046bd58c0137f1ccae'
+  data.tar.gz: c1460d6d10d52ddb5e0ece51e3b5eab2c6d5962d8a7ead7a07661e1ee63aaf99
 SHA512:
-  metadata.gz: 18a32d856585a36aa39a9aa586829a305c099cd4686a338e6f1df5310490abb81808821940a6be5d6c830a1fc86cb1cd95dab5ca8e2c5737574e3e91da513f5f
-  data.tar.gz: c6dadb9b32d373e1fac9246b5bafc8456f3779cf0187abceb7bd85ecdd96b823c95c49c751db9bcd4b384ceb34141057b9e48d4540366d1e3d7d951a69e0aa7f
+  metadata.gz: 52e72c3cf52957c54965300787f213add70236025b7fd5de309aabba4fcb9243e1ff973141f4c0ae85aefddf3b182ac49a737a2696bd5f57893ca031af70999d
+  data.tar.gz: 3472c21997df7a77cf96eafd6f08671f77574321b23cbb8128d81364b2c523b64617c624c63f70a7a64f0bd6e1d3de807430bfd570e12ba989dda80163704417

data/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.10.0] - 2026-03-20
+
+Port of Python SDK v0.1.48 features for feature parity.
+
+### Added
+
+#### Session Mutations
+- `ClaudeAgentSDK.rename_session(session_id:, title:, directory:)` — rename a session by appending a custom-title JSONL entry
+- `ClaudeAgentSDK.tag_session(session_id:, tag:, directory:)` — tag a session (pass `nil` to clear); tags are Unicode-sanitized
+- `SessionMutations` module with `rename_session`, `tag_session`, and internal Unicode sanitization helpers
+- Ported from Python SDK's `_internal/session_mutations.py` with TOCTOU-safe `O_WRONLY | O_APPEND` file operations
+
+#### AssistantMessage Usage
+- `usage` attribute on `AssistantMessage` — token usage data from the API response
+- `MessageParser` populates `usage` from `data.dig(:message, :usage)`
+
+#### AgentDefinition Fields
+- `skills`, `memory`, `mcp_servers` attributes on `AgentDefinition`
+- Serialized as `skills`, `memory`, `mcpServers` (camelCase) in the CLI wire protocol initialize request
+
+#### TaskUsage Typed Class
+- `TaskUsage` class with `total_tokens`, `tool_uses`, `duration_ms` attributes
+- `TaskUsage.from_hash` factory supporting symbol, string, camelCase, and snake_case keys
+
+### Removed
+
+#### FGTS Environment Variable
+- Removed auto-setting of `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` environment variable when `include_partial_messages` is enabled — Python SDK v0.1.48 reverted this because it causes HTTP 400 errors on LiteLLM proxies, Bedrock, and Vertex with Claude 4.5 models. The `--include-partial-messages` CLI flag remains the correct mechanism.
+
 ## [0.9.0] - 2026-03-12
 
 Port of Python SDK v0.1.48 parity improvements.

data/README.md

@@ -6,7 +6,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/claude-agent-sdk.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/claude-agent-sdk)
 
-### Feature Parity with Python SDK (v0.1.46)
+### Feature Parity with Python SDK (v0.1.48)
 
 | Feature | Python | Ruby |
 |---------|:------:|:----:|
@@ -25,11 +25,13 @@
 | Beta features (1M context) | ✅ | ✅ |
 | File checkpointing & rewind | ✅ | ✅ |
 | Session browsing (`list_sessions`, `get_session_messages`) | ✅ | ✅ |
+| Session mutations (`rename_session`, `tag_session`) | ✅ | ✅ |
 | Task message types (started/progress/notification) | ✅ | ✅ |
 | MCP server control (reconnect/toggle/stop) | ✅ | ✅ |
 | Subagent context on hook inputs | ✅ | ✅ |
 | Typed MCP status response | ✅ | ✅ |
 | `stop_reason` on `ResultMessage` | ✅ | ✅ |
+| `usage` on `AssistantMessage` | ✅ | ✅ |
 | Fallback model | ✅ | ✅ |
 | Plugin support | ✅ | ✅ |
 | Rails integration (configure block, ActionCable) | — | ✅ |
@@ -137,6 +139,7 @@ Both SDKs spawn `claude` CLI as a subprocess with stream-JSON over stdin/stdout.
 - [Sandbox Settings](#sandbox-settings)
 - [File Checkpointing & Rewind](#file-checkpointing--rewind)
 - [Session Browsing](#session-browsing)
+- [Session Mutations](#session-mutations)
 - [Rails Integration](#rails-integration)
 - [Types](#types)
 - [Error Handling](#error-handling)
@@ -153,7 +156,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.8.0'
+gem 'claude-agent-sdk', '~> 0.10.0'
 ```
 
 And then execute:
@@ -934,6 +937,39 @@ Each `SessionMessage` includes `type` (`"user"` or `"assistant"`), `uuid`, `sess
 
 > **Note:** Session browsing reads `~/.claude/projects/` JSONL files directly. It respects the `CLAUDE_CONFIG_DIR` environment variable and automatically detects git worktrees.
 
+## Session Mutations
+
+Rename or tag sessions programmatically — no CLI subprocess required.
+
+### Renaming a Session
+
+```ruby
+# Rename a session (appends a custom-title JSONL entry)
+ClaudeAgentSDK.rename_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  title: 'My refactoring session',
+  directory: '/path/to/project'  # optional
+)
+```
+
+### Tagging a Session
+
+```ruby
+# Tag a session (Unicode-sanitized before storing)
+ClaudeAgentSDK.tag_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  tag: 'experiment'
+)
+
+# Clear a tag
+ClaudeAgentSDK.tag_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  tag: nil
+)
+```
+
+> **Note:** Session mutations use append-only JSONL writes with `O_WRONLY | O_APPEND` (no `O_CREAT`) for TOCTOU safety. They are safe to call while the session is open in a CLI process.
+
 ## Rails Integration
 
 The SDK integrates well with Rails applications. Here are common patterns:
@@ -1120,7 +1156,8 @@ class AssistantMessage
   attr_accessor :content,           # Array<ContentBlock>
                 :model,             # String
                 :parent_tool_use_id,# String | nil
-                :error              # String | nil ('authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'unknown')
+                :error,             # String | nil ('authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'unknown')
+                :usage              # Hash | nil - Token usage info from the API response
 end
 ```
 
@@ -1276,7 +1313,7 @@ end
 | `HookMatcher` | Hook configuration with matcher pattern and timeout |
 | `PermissionResultAllow` | Permission callback result to allow tool use |
 | `PermissionResultDeny` | Permission callback result to deny tool use |
-| `AgentDefinition` | Agent definition with description, prompt, tools, model |
+| `AgentDefinition` | Agent definition with description, prompt, tools, model, skills, memory, mcp_servers |
 | `ThinkingConfigAdaptive` | Adaptive thinking mode (32,000 token default budget) |
 | `ThinkingConfigEnabled` | Enabled thinking with explicit `budget_tokens` |
 | `ThinkingConfigDisabled` | Disabled thinking (0 tokens) |
@@ -1290,6 +1327,7 @@ end
 | `McpServerInfo` | MCP server name and version |
 | `McpToolInfo` | MCP tool name, description, and annotations |
 | `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
+| `TaskUsage` | Typed usage data (`total_tokens`, `tool_uses`, `duration_ms`) with `from_hash` factory |
 | `SDKSessionInfo` | Session metadata from `list_sessions` |
 | `SessionMessage` | Single message from `get_session_messages` |
 | `SandboxSettings` | Sandbox settings for isolated command execution |

data/lib/claude_agent_sdk/message_parser.rb

@@ -61,7 +61,8 @@ module ClaudeAgentSDK
         content: content_blocks,
         model: data.dig(:message, :model),
         parent_tool_use_id: data[:parent_tool_use_id],
-        error: data[:error] # authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
+        error: data[:error], # authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
+        usage: data.dig(:message, :usage)
       )
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -89,7 +89,10 @@ module ClaudeAgentSDK
             description: agent_def.description,
             prompt: agent_def.prompt,
             tools: agent_def.tools,
-            model: agent_def.model
+            model: agent_def.model,
+            skills: agent_def.skills,
+            memory: agent_def.memory,
+            mcpServers: agent_def.mcp_servers
           }.compact
         end
       end

data/lib/claude_agent_sdk/session_mutations.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'sessions'
+
+module ClaudeAgentSDK
+  # Session mutation functions: rename and tag sessions.
+  #
+  # Ported from Python SDK's _internal/session_mutations.py.
+  # Appends typed metadata entries to the session's JSONL file,
+  # matching the CLI pattern. Safe to call from any SDK host process.
+  module SessionMutations
+    module_function
+
+    # Rename a session by appending a custom-title entry.
+    #
+    # list_sessions reads the LAST custom-title from the file tail, so
+    # repeated calls are safe — the most recent wins.
+    #
+    # @param session_id [String] UUID of the session to rename
+    # @param title [String] New session title (whitespace stripped)
+    # @param directory [String, nil] Project directory path
+    # @raise [ArgumentError] if session_id is invalid or title is empty
+    # @raise [Errno::ENOENT] if the session file cannot be found
+    def rename_session(session_id:, title:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      stripped = title.strip
+      raise ArgumentError, 'title must be non-empty' if stripped.empty?
+
+      data = "#{JSON.generate({ type: 'custom-title', customTitle: stripped, sessionId: session_id },
+                              space_size: 0)}\n"
+
+      append_to_session(session_id, data, directory)
+    end
+
+    # Tag a session. Pass nil to clear the tag.
+    #
+    # Appends a {type:'tag',tag:<tag>,sessionId:<id>} JSONL entry.
+    # Tags are Unicode-sanitized before storing.
+    #
+    # @param session_id [String] UUID of the session to tag
+    # @param tag [String, nil] Tag string, or nil to clear
+    # @param directory [String, nil] Project directory path
+    # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+    # @raise [Errno::ENOENT] if the session file cannot be found
+    def tag_session(session_id:, tag:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      if tag
+        sanitized = sanitize_unicode(tag).strip
+        raise ArgumentError, 'tag must be non-empty (use nil to clear)' if sanitized.empty?
+
+        tag = sanitized
+      end
+
+      data = "#{JSON.generate({ type: 'tag', tag: tag || '', sessionId: session_id },
+                              space_size: 0)}\n"
+
+      append_to_session(session_id, data, directory)
+    end
+
+    # -- Private helpers --
+
+    def append_to_session(session_id, data, directory)
+      file_name = "#{session_id}.jsonl"
+
+      if directory
+        append_to_session_in_directory(session_id, data, file_name, directory)
+      else
+        append_to_session_global(session_id, data, file_name)
+      end
+    end
+
+    def append_to_session_in_directory(session_id, data, file_name, directory)
+      path = File.realpath(directory).unicode_normalize(:nfc)
+
+      # Try the exact/prefix-matched project directory first.
+      project_dir = Sessions.find_project_dir(path)
+      return if project_dir && try_append(File.join(project_dir, file_name), data)
+
+      # Worktree fallback
+      begin
+        worktree_paths = Sessions.detect_worktrees(path)
+      rescue StandardError
+        worktree_paths = []
+      end
+
+      found = worktree_paths.any? do |wt_path|
+        next false if wt_path == path
+
+        wt_project_dir = Sessions.find_project_dir(wt_path)
+        wt_project_dir && try_append(File.join(wt_project_dir, file_name), data)
+      end
+      return if found
+
+      raise Errno::ENOENT, "Session #{session_id} not found in project directory for #{directory}"
+    end
+
+    def append_to_session_global(session_id, data, file_name)
+      projects_dir = File.join(Sessions.config_dir, 'projects')
+      raise Errno::ENOENT, "Session #{session_id} not found (no projects directory)" unless File.directory?(projects_dir)
+
+      found = Dir.children(projects_dir).any? do |child|
+        candidate = File.join(projects_dir, child, file_name)
+        try_append(candidate, data)
+      end
+      return if found
+
+      raise Errno::ENOENT, "Session #{session_id} not found in any project directory"
+    end
+
+    # Try appending to a path.
+    #
+    # Opens with WRONLY | APPEND (no CREAT) so the open fails with
+    # ENOENT if the file does not exist. Returns false for missing
+    # files or zero-byte files; true on successful write.
+    def try_append(path, data)
+      file = File.open(path, File::WRONLY | File::APPEND)
+      begin
+        return false if file.stat.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+
+        file.write(data)
+        true
+      ensure
+        file.close
+      end
+    rescue Errno::ENOENT, Errno::ENOTDIR
+      false
+    end
+
+    # Unicode sanitization — ported from Python SDK / TS sanitization.ts
+    #
+    # Iteratively applies NFKC normalization and strips format/private-use/
+    # unassigned characters until stable (max 10 iterations).
+    UNICODE_STRIP_RE = /[\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff\ue000-\uf8ff]/
+    FORMAT_CATEGORIES = %w[Cf Co Cn].freeze
+
+    def sanitize_unicode(value)
+      current = value
+      10.times do
+        previous = current
+        current = current.unicode_normalize(:nfkc)
+        current = current.each_char.reject { |c| FORMAT_CATEGORIES.include?(unicode_category(c)) }.join
+        current = current.gsub(UNICODE_STRIP_RE, '')
+        break if current == previous
+      end
+      current
+    end
+
+    # Returns the Unicode general category for a character (e.g., 'Cf', 'Lu', 'Ll').
+    def unicode_category(char)
+      # Ruby doesn't have a built-in unicodedata.category(), but we can
+      # check the specific categories we care about using regex properties.
+      return 'Cf' if char.match?(/\p{Cf}/)
+      return 'Co' if char.match?(/\p{Co}/)
+      return 'Cn' if char.match?(/\p{Cn}/)
+
+      'Other'
+    end
+
+    private_class_method :append_to_session, :append_to_session_in_directory,
+                         :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category
+  end
+end

data/lib/claude_agent_sdk/sessions.rb

@@ -491,9 +491,12 @@ module ClaudeAgentSDK
     end
 
     private_class_method :list_sessions_for_directory, :list_all_sessions,
-                         :deduplicate_sessions, :detect_worktrees,
+                         :deduplicate_sessions,
                          :find_session_file, :parse_jsonl_entries,
                          :build_conversation_chain, :walk_to_leaf, :walk_to_root,
                          :filter_visible_messages, :read_head_tail, :build_session_info
+
+    # These remain accessible for SessionMutations:
+    # config_dir, sanitize_path, find_project_dir, detect_worktrees
   end
 end

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -181,9 +181,6 @@ module ClaudeAgentSDK
       process_env = ENV.to_h.merge('CLAUDECODE' => nil, 'CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
       process_env['CLAUDE_CODE_ENTRYPOINT'] ||= 'sdk-rb'
       process_env['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = 'true' if @options.enable_file_checkpointing
-      if @options.include_partial_messages
-        process_env['CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING'] ||= '1'
-      end
       process_env['PWD'] = @cwd.to_s if @cwd
 
       # Determine stderr handling

data/lib/claude_agent_sdk/types.rb

@@ -104,13 +104,14 @@ module ClaudeAgentSDK
 
   # Assistant message with content blocks
   class AssistantMessage
-    attr_accessor :content, :model, :parent_tool_use_id, :error
+    attr_accessor :content, :model, :parent_tool_use_id, :error, :usage
 
-    def initialize(content:, model:, parent_tool_use_id: nil, error: nil)
+    def initialize(content:, model:, parent_tool_use_id: nil, error: nil, usage: nil)
       @content = content
       @model = model
       @parent_tool_use_id = parent_tool_use_id
       @error = error # One of: authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
+      @usage = usage # Token usage info from the API response
     end
   end
 
@@ -127,6 +128,27 @@ module ClaudeAgentSDK
   # Task lifecycle notification statuses
   TASK_NOTIFICATION_STATUSES = %w[completed failed stopped].freeze
 
+  # Typed usage data for task progress and notifications
+  class TaskUsage
+    attr_accessor :total_tokens, :tool_uses, :duration_ms
+
+    def initialize(total_tokens: 0, tool_uses: 0, duration_ms: 0)
+      @total_tokens = total_tokens
+      @tool_uses = tool_uses
+      @duration_ms = duration_ms
+    end
+
+    def self.from_hash(hash)
+      return nil unless hash.is_a?(Hash)
+
+      new(
+        total_tokens: hash[:total_tokens] || hash['total_tokens'] || hash[:totalTokens] || hash['totalTokens'] || 0,
+        tool_uses: hash[:tool_uses] || hash['tool_uses'] || hash[:toolUses] || hash['toolUses'] || 0,
+        duration_ms: hash[:duration_ms] || hash['duration_ms'] || hash[:durationMs] || hash['durationMs'] || 0
+      )
+    end
+  end
+
   # Task started system message (subagent/background task started)
   class TaskStartedMessage < SystemMessage
     attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type
@@ -285,13 +307,16 @@ module ClaudeAgentSDK
 
   # Agent definition configuration
   class AgentDefinition
-    attr_accessor :description, :prompt, :tools, :model
+    attr_accessor :description, :prompt, :tools, :model, :skills, :memory, :mcp_servers
 
-    def initialize(description:, prompt:, tools: nil, model: nil)
+    def initialize(description:, prompt:, tools: nil, model: nil, skills: nil, memory: nil, mcp_servers: nil)
       @description = description
       @prompt = prompt
       @tools = tools
       @model = model
+      @skills = skills # Array of skill names
+      @memory = memory # One of: 'user', 'project', 'local'
+      @mcp_servers = mcp_servers # Array of server names or config hashes
     end
   end
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -11,6 +11,7 @@ require_relative 'claude_agent_sdk/query'
 require_relative 'claude_agent_sdk/sdk_mcp_server'
 require_relative 'claude_agent_sdk/streaming'
 require_relative 'claude_agent_sdk/sessions'
+require_relative 'claude_agent_sdk/session_mutations'
 require 'async'
 require 'securerandom'
 
@@ -78,6 +79,22 @@ module ClaudeAgentSDK
     Sessions.get_session_messages(session_id: session_id, directory: directory, limit: limit, offset: offset)
   end
 
+  # Rename a session by appending a custom-title entry
+  # @param session_id [String] UUID of the session to rename
+  # @param title [String] New session title
+  # @param directory [String, nil] Project directory path
+  def self.rename_session(session_id:, title:, directory: nil)
+    SessionMutations.rename_session(session_id: session_id, title: title, directory: directory)
+  end
+
+  # Tag a session. Pass nil to clear the tag.
+  # @param session_id [String] UUID of the session to tag
+  # @param tag [String, nil] Tag string, or nil to clear
+  # @param directory [String, nil] Project directory path
+  def self.tag_session(session_id:, tag:, directory: nil)
+    SessionMutations.tag_session(session_id: session_id, tag: tag, directory: directory)
+  end
+
   def self.query(prompt:, options: nil, &block)
     return enum_for(:query, prompt: prompt, options: options) unless block
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-03-12 00:00:00.000000000 Z
+date: 2026-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -109,6 +109,7 @@ files:
 - lib/claude_agent_sdk/message_parser.rb
 - lib/claude_agent_sdk/query.rb
 - lib/claude_agent_sdk/sdk_mcp_server.rb
+- lib/claude_agent_sdk/session_mutations.rb
 - lib/claude_agent_sdk/sessions.rb
 - lib/claude_agent_sdk/streaming.rb
 - lib/claude_agent_sdk/subprocess_cli_transport.rb