claude-agent-sdk 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c6c249367872221d23d090bf162658963a287f88abb9f62a5037e1b85977949
-  data.tar.gz: a09ae1f2ecd82344afa972c3e8c74d9032ae85b5084bf96d72b0d834d45fa839
+  metadata.gz: 49a855001019149f2348998742683b3589966a6b97464e815b1fd44abb01ab51
+  data.tar.gz: af1826c40f4e8cb6c1910b6ca81b2fa3e01dc83442b4373f5e912b0a1d4af871
 SHA512:
-  metadata.gz: c608d05dfe74cbd90ec64836f7c6b3808357db831debbd268e35ef30699867c7f5409ecb101c01dbf899229a14f17bea10ad8d8ed0f359778ae04ad6b87a2c3f
-  data.tar.gz: 2f1bf0d44b541104d7fba0433b32260c8cda247d79f7f36f46d1aedfed93afea6fb55bbc26657210686602703ea0727e27d7056670f5eda66f23886164f28033
+  metadata.gz: b5322fb7d911240d064985742c6817d8f9ccb0918c30ec7b27aca012c657ee0b5c1a648f6714cc471ca32b15acf8d7f72d6bf2f938d8b4811d9a0ba497a3f662
+  data.tar.gz: 3ea02aa3ef4da8a98e876c18605f2bffcd5edca9e6ca719bfa70de925463030e8cb1793916bf1681f7fcb432f044398dfdbb5480fb295a11673736977c772347

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.14.0] - 2026-04-08 — Python SDK v0.1.51–0.1.56 Parity
+
+### Added
+
+#### Type Completeness
+- `AssistantMessage`: `message_id`, `stop_reason`, `session_id`, `uuid` fields (populated from CLI message data)
+- `AgentDefinition`: `disallowed_tools`, `max_turns`, `initial_prompt`, `background`, `effort`, `permission_mode` fields (serialized to CLI via initialize request)
+- `ToolPermissionContext`: `tool_use_id`, `agent_id` fields for distinguishing parallel permission requests and sub-agent context
+- `PERMISSION_MODES`: added `dontAsk` and `auto` values
+
+#### New Types and Options
+- `SystemPromptFile` class — loads system prompt from a file path via `--system-prompt-file` CLI flag
+- `TaskBudget` class — API-side token budget, passed as `--task-budget` CLI flag
+- `ForkSessionResult` class — returned by `fork_session()` with the new session ID
+- `session_id` option on `ClaudeAgentOptions` — specify a custom session ID via `--session-id` CLI flag
+- `task_budget` option on `ClaudeAgentOptions`
+
+#### Session Management
+- `ClaudeAgentSDK.delete_session(session_id:, directory:)` — hard-deletes a session JSONL file
+- `ClaudeAgentSDK.fork_session(session_id:, directory:, up_to_message_id:, title:)` — filesystem-level fork with UUID remapping, sidechain filtering, content-replacement forwarding, and auto-generated titles
+- `offset` parameter on `ClaudeAgentSDK.list_sessions` for cursor-based pagination
+
+#### Client Introspection
+- `Client#get_context_usage` / `Query#get_context_usage` — sends `get_context_usage` control request for context window breakdown (tokens by category, model, MCP tools, memory files, etc.)
+
+#### MCP Robustness
+- `SdkMcpTool#meta` field and `_meta` forwarding in `tools/list` responses — prevents silent truncation of large tool results (>50K chars) by forwarding `anthropic/maxResultSizeChars` through the MCP `_meta` field
+- `create_tool` auto-populates `_meta` from `annotations[:maxResultSizeChars]` when present
+
 ## [0.13.1] - 2026-04-05
 
 ### Fixed

data/README.md

@@ -106,7 +106,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.13.0'
+gem 'claude-agent-sdk', '~> 0.13.1'
 ```
 
 And then execute:
@@ -130,6 +130,20 @@ gem install claude-agent-sdk
 
 If you're using [Claude Code](https://claude.ai/claude-code) or another agentic coding tool that supports [skills](https://skills.sh), you can install the SDK skill:
 
+**Option 1: Via Plugin Marketplace (recommended)**
+
+This repo is a Claude Code plugin marketplace. Add it once, then install the skill:
+
+```bash
+# Add the marketplace
+/plugin marketplace add ya-luotao/claude-agent-sdk-ruby
+
+# Install the plugin
+/plugin install claude-agent-ruby@claude-agent-sdk-ruby
+```
+
+**Option 2: Via skills.sh**
+
 ```bash
 npx skills add https://github.com/ya-luotao/claude-agent-sdk-ruby --skill claude-agent-sdk-ruby
 ```
@@ -949,6 +963,9 @@ end
 # List sessions for a specific directory
 sessions = ClaudeAgentSDK.list_sessions(directory: '/path/to/project', limit: 10)
 
+# Paginate with offset
+page2 = ClaudeAgentSDK.list_sessions(directory: '.', limit: 10, offset: 10)
+
 # Include git worktree sessions
 sessions = ClaudeAgentSDK.list_sessions(directory: '.', include_worktrees: true)
 ```
@@ -1005,7 +1022,34 @@ ClaudeAgentSDK.tag_session(
 )
 ```
 
-> **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.
+### Deleting a Session
+
+```ruby
+# Hard-delete a session (removes the JSONL file permanently)
+ClaudeAgentSDK.delete_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  directory: '/path/to/project'  # optional
+)
+```
+
+### Forking a Session
+
+```ruby
+# Fork a session into a new branch with fresh UUIDs
+result = ClaudeAgentSDK.fork_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  title: 'Experiment branch'  # optional, auto-generated if omitted
+)
+puts result.session_id  # UUID of the new forked session
+
+# Fork up to a specific message (partial fork)
+result = ClaudeAgentSDK.fork_session(
+  session_id: '550e8400-e29b-41d4-a716-446655440000',
+  up_to_message_id: 'message-uuid-here'
+)
+```
+
+> **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. `fork_session` uses `O_CREAT | O_EXCL` to prevent race conditions.
 
 ## Observability (OpenTelemetry / Langfuse)
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -70,7 +70,11 @@ module ClaudeAgentSDK
         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
-        usage: data.dig(:message, :usage)
+        usage: data.dig(:message, :usage),
+        message_id: data.dig(:message, :id),
+        stop_reason: data.dig(:message, :stop_reason),
+        session_id: data[:session_id],
+        uuid: data[:uuid]
       )
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -89,10 +89,16 @@ module ClaudeAgentSDK
             description: agent_def.description,
             prompt: agent_def.prompt,
             tools: agent_def.tools,
+            disallowedTools: agent_def.disallowed_tools,
             model: agent_def.model,
             skills: agent_def.skills,
             memory: agent_def.memory,
-            mcpServers: agent_def.mcp_servers
+            mcpServers: agent_def.mcp_servers,
+            initialPrompt: agent_def.initial_prompt,
+            maxTurns: agent_def.max_turns,
+            background: agent_def.background,
+            effort: agent_def.effort,
+            permissionMode: agent_def.permission_mode
           }.compact
         end
       end
@@ -283,7 +289,9 @@ module ClaudeAgentSDK
 
       context = ToolPermissionContext.new(
         signal: nil,
-        suggestions: request_data[:permission_suggestions] || []
+        suggestions: request_data[:permission_suggestions] || [],
+        tool_use_id: request_data[:tool_use_id],
+        agent_id: request_data[:agent_id]
       )
 
       response = @can_use_tool.call(
@@ -805,6 +813,12 @@ module ClaudeAgentSDK
 
     public
 
+    # Get a breakdown of current context window usage by category.
+    # @return [Hash] Context usage response with categories, totalTokens, maxTokens, etc.
+    def get_context_usage
+      send_control_request({ subtype: 'get_context_usage' })
+    end
+
     # Get current MCP server connection status (only works with streaming mode)
     # @return [Hash] MCP status information, including mcpServers list
     def get_mcp_status

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -66,6 +66,7 @@ module ClaudeAgentSDK
           inputSchema: convert_input_schema(tool.input_schema)
         }
         entry[:annotations] = tool.annotations if tool.annotations
+        entry[:_meta] = tool.meta if tool.meta
         entry
       end
     end
@@ -400,15 +401,23 @@ module ClaudeAgentSDK
   #       { content: [{ type: 'text', text: "Result: #{result}" }] }
   #     end
   #   end
-  def self.create_tool(name, description, input_schema, annotations: nil, &handler)
+  def self.create_tool(name, description, input_schema, annotations: nil, meta: nil, &handler)
     raise ArgumentError, 'Block required for tool handler' unless handler
 
+    # Auto-populate _meta with maxResultSizeChars from annotations if present
+    resolved_meta = meta
+    if resolved_meta.nil? && annotations
+      max_chars = annotations[:maxResultSizeChars] || annotations['maxResultSizeChars']
+      resolved_meta = { 'anthropic/maxResultSizeChars' => max_chars } if max_chars
+    end
+
     SdkMcpTool.new(
       name: name,
       description: description,
       input_schema: input_schema,
       handler: handler,
-      annotations: annotations
+      annotations: annotations,
+      meta: resolved_meta
     )
   end
 

data/lib/claude_agent_sdk/session_mutations.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'securerandom'
 require_relative 'sessions'
 
 module ClaudeAgentSDK
-  # Session mutation functions: rename and tag sessions.
+  # Session mutation functions: rename, tag, delete, and fork 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 SessionMutations # rubocop:disable Metrics/ModuleLength
     module_function
 
     # Rename a session by appending a custom-title entry.
@@ -60,8 +61,245 @@ module ClaudeAgentSDK
       append_to_session(session_id, data, directory)
     end
 
+    # Delete a session by removing its JSONL file.
+    #
+    # This is a hard delete — the file is removed permanently. For soft-delete
+    # semantics, use tag_session(id, '__hidden') and filter on listing instead.
+    #
+    # @param session_id [String] UUID of the session to delete
+    # @param directory [String, nil] Project directory path
+    # @raise [ArgumentError] if session_id is invalid
+    # @raise [Errno::ENOENT] if the session file cannot be found
+    def delete_session(session_id:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      result = find_session_file_with_dir(session_id, directory)
+      raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}" unless result
+
+      path = result[0]
+
+      begin
+        File.delete(path)
+      rescue Errno::ENOENT
+        raise Errno::ENOENT, "Session #{session_id} not found"
+      end
+    end
+
+    # Fork a session into a new branch with fresh UUIDs.
+    #
+    # Creates a copy of the session transcript (or a prefix up to up_to_message_id)
+    # with remapped UUIDs and a new session ID. Sidechains are filtered out,
+    # progress entries are excluded from the written output but used for
+    # parentUuid chain walking.
+    #
+    # @param session_id [String] UUID of the session to fork
+    # @param directory [String, nil] Project directory path
+    # @param up_to_message_id [String, nil] Truncate the fork at this message UUID
+    # @param title [String, nil] Custom title for the fork (auto-generated if omitted)
+    # @return [ForkSessionResult] Result containing the new session ID
+    # @raise [ArgumentError] if session_id or up_to_message_id is invalid
+    # @raise [Errno::ENOENT] if the session file cannot be found
+    def fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil) # rubocop:disable Metrics/MethodLength
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !up_to_message_id.match?(Sessions::UUID_RE)
+
+      result = find_session_file_with_dir(session_id, directory)
+      raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}" unless result
+
+      file_path, project_dir = result
+      content = File.read(file_path)
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if content.empty?
+
+      transcript, content_replacements = parse_fork_transcript(content, session_id)
+      transcript.reject! { |e| e['isSidechain'] }
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
+
+      if up_to_message_id
+        cutoff = transcript.index { |e| e['uuid'] == up_to_message_id }
+        raise ArgumentError, "Message #{up_to_message_id} not found in session #{session_id}" unless cutoff
+
+        transcript = transcript[0..cutoff]
+      end
+
+      # Build UUID mapping (including progress entries for parentUuid chain walk)
+      uuid_mapping = {}
+      transcript.each { |e| uuid_mapping[e['uuid']] = SecureRandom.uuid }
+
+      by_uuid = transcript.to_h { |e| [e['uuid'], e] }
+
+      # Filter out progress messages from written output
+      writable = transcript.reject { |e| e['type'] == 'progress' }
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if writable.empty?
+
+      forked_session_id = SecureRandom.uuid
+      now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ')
+
+      lines = writable.each_with_index.map do |original, i|
+        build_forked_entry(original, i, writable.size, uuid_mapping, by_uuid,
+                           forked_session_id, session_id, now)
+      end
+
+      # Append content-replacement entry if any
+      if content_replacements && !content_replacements.empty?
+        lines << JSON.generate({
+                                 'type' => 'content-replacement',
+                                 'sessionId' => forked_session_id,
+                                 'replacements' => content_replacements
+                               })
+      end
+
+      # Derive title
+      fork_title = title&.strip
+      if fork_title.nil? || fork_title.empty?
+        head = content[0, Sessions::LITE_READ_BUF_SIZE] || ''
+        tail = content.length > Sessions::LITE_READ_BUF_SIZE ? content[-Sessions::LITE_READ_BUF_SIZE..] : head
+        base = Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
+               Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
+               Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
+               Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
+               Sessions.extract_first_prompt_from_head(head) ||
+               'Forked session'
+        fork_title = "#{base} (fork)"
+      end
+
+      lines << JSON.generate({
+                               'type' => 'custom-title',
+                               'sessionId' => forked_session_id,
+                               'customTitle' => fork_title
+                             })
+
+      fork_path = File.join(project_dir, "#{forked_session_id}.jsonl")
+      io = nil
+      fd = IO.sysopen(fork_path, File::WRONLY | File::CREAT | File::EXCL, 0o600)
+      begin
+        io = IO.new(fd)
+        io.write("#{lines.join("\n")}\n")
+      ensure
+        if io
+          io.close
+        else
+          IO.for_fd(fd).close rescue nil # rubocop:disable Style/RescueModifier
+        end
+      end
+
+      ForkSessionResult.new(session_id: forked_session_id)
+    end
+
     # -- Private helpers --
 
+    # Locate the JSONL file for a session and return [file_path, project_dir].
+    def find_session_file_with_dir(session_id, directory)
+      file_name = "#{session_id}.jsonl"
+      return find_in_directory(file_name, directory) if directory
+
+      find_in_all_projects(file_name)
+    end
+
+    def find_in_directory(file_name, directory)
+      path = File.realpath(directory).unicode_normalize(:nfc)
+      result = try_project_dir(file_name, Sessions.find_project_dir(path))
+      return result if result
+
+      worktree_paths = begin
+        Sessions.detect_worktrees(path)
+      rescue Errno::ENOENT, Errno::EACCES
+        []
+      end
+      worktree_paths.each do |wt_path|
+        next if wt_path == path
+
+        result = try_project_dir(file_name, Sessions.find_project_dir(wt_path))
+        return result if result
+      end
+      nil
+    end
+
+    def try_project_dir(file_name, project_dir)
+      return nil unless project_dir
+
+      candidate = File.join(project_dir, file_name)
+      File.exist?(candidate) ? [candidate, project_dir] : nil
+    end
+
+    def find_in_all_projects(file_name)
+      projects_dir = File.join(Sessions.config_dir, 'projects')
+      return nil unless File.directory?(projects_dir)
+
+      Dir.children(projects_dir).each do |child|
+        pd = File.join(projects_dir, child)
+        next unless File.directory?(pd)
+
+        candidate = File.join(pd, file_name)
+        return [candidate, pd] if File.exist?(candidate)
+      end
+      nil
+    end
+
+    # Parse a fork transcript, extracting entries and content-replacement data.
+    def parse_fork_transcript(content, _session_id)
+      transcript = []
+      content_replacements = nil
+
+      content.each_line do |line|
+        entry = JSON.parse(line.strip)
+        next unless entry.is_a?(Hash) && entry['uuid']
+
+        if entry['type'] == 'content-replacement'
+          content_replacements = entry['replacements']
+          next
+        end
+        transcript << entry
+      rescue JSON::ParserError
+        next
+      end
+
+      [transcript, content_replacements]
+    end
+
+    # Build a single forked entry with remapped UUIDs.
+    def build_forked_entry(original, index, total, uuid_mapping, by_uuid,
+                           forked_session_id, source_session_id, now)
+      new_uuid = uuid_mapping[original['uuid']]
+
+      # Resolve parentUuid, skipping progress ancestors
+      new_parent_uuid = resolve_parent_uuid(original['parentUuid'], by_uuid, uuid_mapping)
+
+      # Only update timestamp on the last message
+      timestamp = index == total - 1 ? now : (original['timestamp'] || now)
+
+      # Remap logicalParentUuid — unlike parentUuid (which walks the chain and nils on miss),
+      # logicalParentUuid preserves the original UUID when unmapped because it may reference
+      # a message outside the forked range (e.g., a prior conversation branch).
+      logical_parent = original['logicalParentUuid']
+      new_logical_parent = logical_parent ? (uuid_mapping[logical_parent] || logical_parent) : logical_parent
+
+      forked = original.merge(
+        'uuid' => new_uuid,
+        'parentUuid' => new_parent_uuid,
+        'logicalParentUuid' => new_logical_parent,
+        'sessionId' => forked_session_id,
+        'timestamp' => timestamp,
+        'isSidechain' => false,
+        'forkedFrom' => { 'sessionId' => source_session_id, 'messageUuid' => original['uuid'] }
+      )
+      %w[teamName agentName slug sourceToolAssistantUUID].each { |k| forked.delete(k) }
+
+      JSON.generate(forked)
+    end
+
+    # Walk up parentUuid chain skipping progress entries.
+    def resolve_parent_uuid(parent_id, by_uuid, uuid_mapping)
+      while parent_id
+        parent = by_uuid[parent_id]
+        break unless parent
+        return uuid_mapping[parent_id] if parent['type'] != 'progress'
+
+        parent_id = parent['parentUuid']
+      end
+      nil
+    end
+
     def append_to_session(session_id, data, directory)
       file_name = "#{session_id}.jsonl"
 
@@ -156,7 +394,10 @@ module ClaudeAgentSDK
       'Other'
     end
 
-    private_class_method :append_to_session, :append_to_session_in_directory,
+    private_class_method :find_session_file_with_dir,
+                         :find_in_directory, :try_project_dir, :find_in_all_projects,
+                         :parse_fork_transcript, :build_forked_entry, :resolve_parent_uuid,
+                         :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

@@ -302,17 +302,19 @@ module ClaudeAgentSDK
     # List sessions for a directory (or all sessions)
     # @param directory [String, nil] Working directory to list sessions for
     # @param limit [Integer, nil] Maximum number of sessions to return
+    # @param offset [Integer] Number of sessions to skip (for pagination)
     # @param include_worktrees [Boolean] Whether to include git worktree sessions
     # @return [Array<SDKSessionInfo>] Sessions sorted by last_modified descending
-    def list_sessions(directory: nil, limit: nil, include_worktrees: true)
+    def list_sessions(directory: nil, limit: nil, offset: 0, include_worktrees: true)
       sessions = if directory
                    list_sessions_for_directory(directory, include_worktrees)
                  else
                    list_all_sessions
                  end
 
-      # Sort by last_modified descending
+      # Sort by last_modified descending, then apply offset and limit
       sessions.sort_by! { |s| -s.last_modified }
+      sessions = sessions[offset..] || [] if offset.positive?
       sessions = sessions.first(limit) if limit
       sessions
     end

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -74,13 +74,18 @@ module ClaudeAgentSDK
         cmd.concat(['--system-prompt', ''])
       elsif @options.system_prompt.is_a?(String)
         cmd.concat(['--system-prompt', @options.system_prompt])
+      elsif @options.system_prompt.is_a?(SystemPromptFile)
+        cmd.concat(['--system-prompt-file', @options.system_prompt.path])
       elsif @options.system_prompt.is_a?(SystemPromptPreset)
         # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
         # Only --append-system-prompt is passed if append text is provided
         cmd.concat(['--append-system-prompt', @options.system_prompt.append]) if @options.system_prompt.append
       elsif @options.system_prompt.is_a?(Hash)
         prompt_type = @options.system_prompt[:type] || @options.system_prompt['type']
-        if prompt_type == 'preset'
+        if prompt_type == 'file'
+          prompt_path = @options.system_prompt[:path] || @options.system_prompt['path']
+          cmd.concat(['--system-prompt-file', prompt_path]) if prompt_path
+        elsif prompt_type == 'preset'
           append = @options.system_prompt[:append] || @options.system_prompt['append']
           # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
           cmd.concat(['--append-system-prompt', append]) if append
@@ -96,6 +101,7 @@ module ClaudeAgentSDK
       cmd.concat(['--permission-mode', @options.permission_mode]) if @options.permission_mode
       cmd << '--continue' if @options.continue_conversation
       cmd.concat(['--resume', @options.resume]) if @options.resume
+      cmd.concat(['--session-id', @options.session_id]) if @options.session_id
 
       # Settings handling with sandbox merge
       build_settings_args(cmd)
@@ -103,6 +109,16 @@ module ClaudeAgentSDK
       # Budget limit option
       cmd.concat(['--max-budget-usd', @options.max_budget_usd.to_s]) if @options.max_budget_usd
 
+      # Task budget (API-side token budget)
+      if @options.task_budget
+        total = if @options.task_budget.is_a?(TaskBudget)
+                  @options.task_budget.total
+                else
+                  @options.task_budget[:total] || @options.task_budget['total']
+                end
+        cmd.concat(['--task-budget', total.to_s]) if total
+      end
+
       # Thinking configuration (takes precedence over deprecated max_thinking_tokens)
       thinking_tokens = resolve_thinking_tokens
       cmd.concat(['--max-thinking-tokens', thinking_tokens.to_s]) unless thinking_tokens.nil?

data/lib/claude_agent_sdk/types.rb

@@ -2,7 +2,7 @@
 
 module ClaudeAgentSDK
   # Type constants for permission modes
-  PERMISSION_MODES = %w[default acceptEdits plan bypassPermissions].freeze
+  PERMISSION_MODES = %w[default acceptEdits plan bypassPermissions dontAsk auto].freeze
 
   # Type constants for setting sources
   SETTING_SOURCES = %w[user project local].freeze
@@ -121,14 +121,20 @@ module ClaudeAgentSDK
 
   # Assistant message with content blocks
   class AssistantMessage
-    attr_accessor :content, :model, :parent_tool_use_id, :error, :usage
+    attr_accessor :content, :model, :parent_tool_use_id, :error, :usage,
+                  :message_id, :stop_reason, :session_id, :uuid
 
-    def initialize(content:, model:, parent_tool_use_id: nil, error: nil, usage: nil)
+    def initialize(content:, model:, parent_tool_use_id: nil, error: nil, usage: nil,
+                   message_id: nil, stop_reason: nil, session_id: nil, uuid: 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
+      @message_id = message_id # Unique message identifier from the API (message.id)
+      @stop_reason = stop_reason # Why the assistant stopped (e.g., "end_turn", "max_tokens")
+      @session_id = session_id # Session the message belongs to
+      @uuid = uuid # Unique message UUID in the session transcript
     end
   end
 
@@ -597,16 +603,25 @@ module ClaudeAgentSDK
 
   # Agent definition configuration
   class AgentDefinition
-    attr_accessor :description, :prompt, :tools, :model, :skills, :memory, :mcp_servers
+    attr_accessor :description, :prompt, :tools, :disallowed_tools, :model, :skills, :memory, :mcp_servers,
+                  :initial_prompt, :max_turns, :background, :effort, :permission_mode
 
-    def initialize(description:, prompt:, tools: nil, model: nil, skills: nil, memory: nil, mcp_servers: nil)
+    def initialize(description:, prompt:, tools: nil, disallowed_tools: nil, model: nil, skills: nil,
+                   memory: nil, mcp_servers: nil, initial_prompt: nil, max_turns: nil,
+                   background: nil, effort: nil, permission_mode: nil)
       @description = description
       @prompt = prompt
       @tools = tools
+      @disallowed_tools = disallowed_tools # Array of tool names to disallow
       @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
+      @initial_prompt = initial_prompt # Initial prompt sent when agent starts
+      @max_turns = max_turns # Maximum conversation turns for the agent
+      @background = background # Whether this agent runs in background
+      @effort = effort # "low", "medium", "high", "max", or Integer
+      @permission_mode = permission_mode # Permission mode for the agent
     end
   end
 
@@ -660,11 +675,13 @@ module ClaudeAgentSDK
 
   # Tool permission context
   class ToolPermissionContext
-    attr_accessor :signal, :suggestions
+    attr_accessor :signal, :suggestions, :tool_use_id, :agent_id
 
-    def initialize(signal: nil, suggestions: [])
+    def initialize(signal: nil, suggestions: [], tool_use_id: nil, agent_id: nil)
       @signal = signal
       @suggestions = suggestions
+      @tool_use_id = tool_use_id # Unique ID for this tool call within the assistant message
+      @agent_id = agent_id # Sub-agent ID if running within an agent context
     end
   end
 
@@ -1678,6 +1695,44 @@ module ClaudeAgentSDK
     end
   end
 
+  # Result of a session fork operation
+  class ForkSessionResult
+    attr_accessor :session_id
+
+    def initialize(session_id:)
+      @session_id = session_id
+    end
+  end
+
+  # API-side task budget in tokens.
+  # When set, the model is made aware of its remaining token budget so it can
+  # pace tool use and wrap up before the limit.
+  class TaskBudget
+    attr_accessor :total
+
+    def initialize(total:)
+      @total = total
+    end
+
+    def to_h
+      { total: @total }
+    end
+  end
+
+  # System prompt file configuration — loads system prompt from a file path
+  class SystemPromptFile
+    attr_accessor :type, :path
+
+    def initialize(path:)
+      @type = 'file'
+      @path = path
+    end
+
+    def to_h
+      { type: @type, path: @path }
+    end
+  end
+
   # System prompt preset configuration
   class SystemPromptPreset
     attr_accessor :type, :preset, :append
@@ -1712,7 +1767,7 @@ module ClaudeAgentSDK
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
-                  :continue_conversation, :resume, :max_turns, :disallowed_tools,
+                  :continue_conversation, :resume, :session_id, :max_turns, :disallowed_tools,
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
                   :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
                   :can_use_tool, :hooks, :user, :include_partial_messages,
@@ -1720,7 +1775,7 @@ module ClaudeAgentSDK
                   :output_format, :max_budget_usd, :max_thinking_tokens,
                   :fallback_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools,
-                  :thinking, :effort, :bare, :observers
+                  :thinking, :effort, :bare, :observers, :task_budget
 
     # Non-nil defaults for options that need them.
     # Keys absent from here default to nil.
@@ -1783,14 +1838,15 @@ module ClaudeAgentSDK
 
   # SDK MCP Tool definition
   class SdkMcpTool
-    attr_accessor :name, :description, :input_schema, :handler, :annotations
+    attr_accessor :name, :description, :input_schema, :handler, :annotations, :meta
 
-    def initialize(name:, description:, input_schema:, handler:, annotations: nil)
+    def initialize(name:, description:, input_schema:, handler:, annotations: nil, meta: nil)
       @name = name
       @description = description
       @input_schema = input_schema
       @handler = handler
       @annotations = annotations # MCP tool annotations (e.g., { title: '...', readOnlyHint: true })
+      @meta = meta # MCP _meta field (e.g., { 'anthropic/maxResultSizeChars' => 100000 })
     end
   end
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -82,10 +82,11 @@ module ClaudeAgentSDK
   # List sessions for a directory (or all sessions)
   # @param directory [String, nil] Working directory to list sessions for
   # @param limit [Integer, nil] Maximum number of sessions to return
+  # @param offset [Integer] Number of sessions to skip (for pagination)
   # @param include_worktrees [Boolean] Whether to include git worktree sessions
   # @return [Array<SDKSessionInfo>] Sessions sorted by last_modified descending
-  def self.list_sessions(directory: nil, limit: nil, include_worktrees: true)
-    Sessions.list_sessions(directory: directory, limit: limit, include_worktrees: include_worktrees)
+  def self.list_sessions(directory: nil, limit: nil, offset: 0, include_worktrees: true)
+    Sessions.list_sessions(directory: directory, limit: limit, offset: offset, include_worktrees: include_worktrees)
   end
 
   # Read metadata for a single session by ID (no full directory scan)
@@ -122,6 +123,24 @@ module ClaudeAgentSDK
     SessionMutations.tag_session(session_id: session_id, tag: tag, directory: directory)
   end
 
+  # Delete a session by removing its JSONL file (hard delete).
+  # @param session_id [String] UUID of the session to delete
+  # @param directory [String, nil] Project directory path
+  def self.delete_session(session_id:, directory: nil)
+    SessionMutations.delete_session(session_id: session_id, directory: directory)
+  end
+
+  # Fork a session into a new branch with fresh UUIDs.
+  # @param session_id [String] UUID of the session to fork
+  # @param directory [String, nil] Project directory path
+  # @param up_to_message_id [String, nil] Truncate the fork at this message UUID
+  # @param title [String, nil] Custom title for the fork
+  # @return [ForkSessionResult] Result containing the new session ID
+  def self.fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil)
+    SessionMutations.fork_session(session_id: session_id, directory: directory,
+                                  up_to_message_id: up_to_message_id, title: title)
+  end
+
   def self.query(prompt:, options: nil, &block)
     return enum_for(:query, prompt: prompt, options: options) unless block
 
@@ -455,6 +474,15 @@ module ClaudeAgentSDK
       @query_handler&.instance_variable_get(:@initialization_result)
     end
 
+    # Get a breakdown of current context window usage by category.
+    # Returns token counts per category (system prompt, tools, messages, etc.),
+    # total/max tokens, model info, MCP tools, memory files, and more.
+    # @return [Hash] Context usage response
+    def get_context_usage
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.get_context_usage
+    end
+
     # Get current MCP server connection status (only works with streaming mode)
     # @return [Hash] MCP status information, including mcpServers list
     def get_mcp_status

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async