claude-agent-sdk 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ca7129acd0fb9330d1a49307fde85efff7febaf503bcbda5dbe63d82b3f6476
-  data.tar.gz: 49568fac24a25b129c9f97e5a8ef6c2cd0a3f4db6be6f721c69be7ea31261da5
+  metadata.gz: cbcc1484868ae2ed502513727fd7df53192fc0177eed594433ad7c0332b3287a
+  data.tar.gz: b052d3f7993aa1f4d5a2b4fc3bdb01f7cf974f939c67e82a7bac173cb0b65a8f
 SHA512:
-  metadata.gz: 54a7f40056f3b97db66a31e34dab0d659432731bef991e7262b32d0a09efd419248ea6f150fe2906292b281f293b964dde85cb0e7b9bdd7d220b0d8fb57a8441
-  data.tar.gz: 430e1f1d708a2b75b425523fd87d1a0aab8ef68850def2c66205fcb0d20552f374d2f92feb03217a301410d5b016d7c465eeac97b0aacfc497bafea0412c69ff
+  metadata.gz: b50d94d3879214f2bed9c42e4fe20a989c84e5de26a36a907c1b1093dc344a66a6b37e53a3d60a997f92ce84b4795871d55da32056a235a70617e4dd0cf85552
+  data.tar.gz: 7899caf95b4c5da6e5f4e004ae57456e19e18b6d2be35469e88bd14f1333be4d3053fa8138dd037616c9a15ce2a9985164d065bbdb0026af90b759b31646cddb

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-06-29
+
+### Added
+- `TaskUpdatedMessage` — typed `system`/`task_updated` lifecycle events (Python SDK 0.2.101 / #1016 parity). A background task's terminal state can arrive *only* as a `task_updated` patch with no accompanying `TaskNotificationMessage` (e.g. a `TaskStop`-killed task reports `status: 'killed'` here), so consumers tracking active task IDs no longer hang waiting for a notification that never comes. `status` is derived from `patch['status']` (parsed defensively — a non-Hash/absent patch falls back to `{}`, `task_id` defaults to `''` so it is never nil, and parsing never raises). New `TASK_UPDATED_STATUSES` and `TERMINAL_TASK_STATUSES` constants; the latter spans both lifecycle vocabularies (`task_notification` reports `stopped`, `task_updated` reports the raw `killed`) so a terminal status from *either* message clears active-task tracking.
+
+### Fixed
+- Malformed CLI message content now raises a descriptive `MessageParseError` instead of an opaque `TypeError`/`NoMethodError` (Python SDK #1058 parity): a non-Hash content block (e.g. a bare String) and an assistant `content` that is not an Array are both caught with a clear message carrying the full payload, rather than crashing deep inside block parsing on `block[:type]`.
+
 ## [0.18.0] - 2026-06-12
 
 ### Added

data/README.md

@@ -68,7 +68,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.18.0'
+gem 'claude-agent-sdk', '~> 0.19.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/types.md

@@ -42,22 +42,30 @@ System message with metadata. Task lifecycle events are typed subclasses.
 
 ```ruby
 class SystemMessage
-  attr_accessor :subtype,  # String ('init', 'task_started', 'task_progress', 'task_notification', etc.)
+  attr_accessor :subtype,  # String ('init', 'task_started', 'task_progress', 'task_notification', 'task_updated', etc.)
                 :data      # Hash
 end
 
 # Typed subclasses (all inherit from SystemMessage, so is_a?(SystemMessage) still works)
 class TaskStartedMessage < SystemMessage
-  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type
+  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type, :workflow_name, :prompt
 end
 
 class TaskProgressMessage < SystemMessage
-  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name
+  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary
 end
 
 class TaskNotificationMessage < SystemMessage
   attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
 end
+
+# Background task lifecycle state change. `status` is derived from patch["status"].
+# A terminal task can arrive *only* as a TaskUpdatedMessage (no TaskNotificationMessage) —
+# e.g. a TaskStop-killed task reports status "killed" here. Clear tracked task IDs on a
+# terminal status (see TERMINAL_TASK_STATUSES) from *either* message.
+class TaskUpdatedMessage < SystemMessage
+  attr_accessor :task_id, :patch, :status, :uuid, :session_id
+end
 ```
 
 ### ResultMessage
@@ -183,5 +191,7 @@ end
 | `HOOK_EVENTS` | Available hook events |
 | `ASSISTANT_MESSAGE_ERRORS` | Possible error types in AssistantMessage |
 | `TASK_NOTIFICATION_STATUSES` | Task lifecycle notification statuses (`completed`, `failed`, `stopped`) |
+| `TASK_UPDATED_STATUSES` | `task_updated` patch statuses (`pending`, `running`, `paused`, `completed`, `failed`, `killed`) |
+| `TERMINAL_TASK_STATUSES` | Statuses meaning a task has finished — spans both vocabularies (`completed`, `failed`, `stopped`, `killed`); clear active-task tracking on any of these |
 | `MCP_SERVER_CONNECTION_STATUSES` | MCP server connection states (`connected`, `failed`, `needs-auth`, `pending`, `disabled`) |
 | `EFFORT_LEVELS` | Effort levels (`low`, `medium`, `high`, `xhigh`, `max`) |

data/lib/claude_agent_sdk/message_parser.rb

@@ -51,7 +51,7 @@ module ClaudeAgentSDK
       raise MessageParseError.new("Missing content in user message", data: data) unless content
 
       if content.is_a?(Array)
-        content_blocks = content.map { |block| parse_content_block(block) }
+        content_blocks = parse_content_blocks(content, data)
         UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id,
                         tool_use_result: tool_use_result)
       else
@@ -63,8 +63,9 @@ module ClaudeAgentSDK
     def self.parse_assistant_message(data)
       content = data.dig(:message, :content)
       raise MessageParseError.new("Missing content in assistant message", data: data) unless content
+      raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data) unless content.is_a?(Array)
 
-      content_blocks = content.map { |block| parse_content_block(block) }
+      content_blocks = parse_content_blocks(content, data)
       AssistantMessage.new(
         content: content_blocks,
         model: data.dig(:message, :model),
@@ -96,7 +97,14 @@ module ClaudeAgentSDK
       'elicitation_complete' => ElicitationCompleteMessage,
       'task_started' => TaskStartedMessage,
       'task_progress' => TaskProgressMessage,
-      'task_notification' => TaskNotificationMessage
+      'task_notification' => TaskNotificationMessage,
+      # task_updated carries `status` inside `patch` (not at the top level) and
+      # defaults task_id to "" — it derives those defensively in its own
+      # constructor (see TaskUpdatedMessage), so it dispatches through the table
+      # like every other system subtype. `data` is always symbol-keyed here:
+      # `parse` rejects any message lacking a `:type` symbol key, so a
+      # string-keyed hash never reaches these classes.
+      'task_updated' => TaskUpdatedMessage
     }.freeze
 
     def self.parse_system_message(data)
@@ -132,6 +140,18 @@ module ClaudeAgentSDK
       PromptSuggestionMessage.new(data)
     end
 
+    # Maps a content Array to typed blocks, guarding each element. A non-Hash
+    # block (e.g. a bare String or nil from a malformed CLI message) raises a
+    # descriptive MessageParseError carrying the full message rather than an
+    # opaque TypeError/NoMethodError from `block[:type]` deep in parsing.
+    def self.parse_content_blocks(content, data)
+      content.map do |block|
+        raise MessageParseError.new("Invalid content block (expected Hash, got #{block.class})", data: data) unless block.is_a?(Hash)
+
+        parse_content_block(block)
+      end
+    end
+
     # Accepts blocks with either symbol or string keys — live CLI messages
     # arrive symbol-keyed (parsed via `symbolize_names: true`), session
     # transcripts arrive string-keyed (parsed via `symbolize_names: false`).

data/lib/claude_agent_sdk/types.rb

@@ -333,6 +333,19 @@ module ClaudeAgentSDK
   # Task lifecycle notification statuses
   TASK_NOTIFICATION_STATUSES = %w[completed failed stopped].freeze
 
+  # Possible status values reported inside a `task_updated` patch.
+  # pending/running/paused are non-terminal; completed/failed/killed are
+  # terminal. Note: task_updated reports the raw "killed"; the CLI maps that to
+  # "stopped" only when it emits a task_notification.
+  TASK_UPDATED_STATUSES = %w[pending running paused completed failed killed].freeze
+
+  # Task statuses that mean the task has finished and should be cleared from any
+  # "active task" tracking. Spans both lifecycle vocabularies: task_notification
+  # reports "stopped" (the CLI's mapped form of a killed task) while task_updated
+  # reports the raw "killed". Treat the status of a TaskNotificationMessage and a
+  # TaskUpdatedMessage the same way.
+  TERMINAL_TASK_STATUSES = %w[completed failed stopped killed].freeze
+
   # Typed usage data for task progress and notifications
   class TaskUsage < Type
     attr_accessor :total_tokens, :tool_uses, :duration_ms
@@ -356,11 +369,44 @@ module ClaudeAgentSDK
     attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary
   end
 
-  # Task notification system message (task completed/failed/stopped)
+  # Task notification system message (task completed/failed/stopped).
+  #
+  # Note: not every terminal task emits this message. Background tasks may
+  # instead report completion only via a TaskUpdatedMessage whose patch["status"]
+  # is terminal (see TERMINAL_TASK_STATUSES). Consumers tracking active task IDs
+  # should clear them on a terminal status from *either* message.
   class TaskNotificationMessage < SystemMessage
     attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
   end
 
+  # Task updated system message (background task lifecycle state change).
+  #
+  # The CLI emits system/task_updated events as a task moves through its
+  # lifecycle. `patch` carries the changed fields (e.g. status, end_time); when
+  # patch["status"] is terminal (see TERMINAL_TASK_STATUSES) the task has
+  # finished. A background task's terminal state can arrive *only* as a
+  # TaskUpdatedMessage with no accompanying TaskNotificationMessage — e.g. a task
+  # stopped via TaskStop reports status "killed" here and the matching
+  # notification is sometimes suppressed. Consumers tracking active task IDs
+  # should clear them on a terminal status from *either* message.
+  #
+  # Parsed defensively in the constructor — a lifecycle event must never raise:
+  # `status` is derived from patch["status"] (not a top-level field); a non-Hash
+  # or absent patch falls back to {}; and `task_id` defaults to "" (never nil,
+  # matching the Python SDK) so consumers can rely on it always being a String.
+  # The full patch is preserved on `#patch` for callers that need more than the
+  # status.
+  class TaskUpdatedMessage < SystemMessage
+    attr_accessor :task_id, :patch, :status, :uuid, :session_id
+
+    def initialize(attributes = {})
+      super
+      @task_id ||= ''
+      @patch = {} unless @patch.is_a?(Hash)
+      @status = @patch[:status]
+    end
+  end
+
   # Result message with cost and usage information
   class ResultMessage < Type
     attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async