claude-agent-sdk 0.17.0 → 0.19.0

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,
@@ -525,7 +571,16 @@ module ClaudeAgentSDK
 
   # Permission update configuration
   class PermissionUpdate < Type
-    attr_accessor :type, :rules, :behavior, :mode, :directories, :destination
+    attr_accessor :type, :behavior, :mode, :directories, :destination
+    attr_reader :rules
+
+    # Wire-format parity with Python PermissionUpdate.from_dict (#920): the CLI
+    # sends rules as camelCase hashes ({toolName:, ruleContent:}); hydrate them
+    # into PermissionRuleValue (Type#assign_attribute normalizes the camelCase
+    # keys). Already-typed PermissionRuleValue entries pass through unchanged.
+    def rules=(value)
+      @rules = value&.map { |rule| rule.is_a?(Hash) ? PermissionRuleValue.new(rule) : rule }
+    end
 
     def to_h
       result = { type: @type }
@@ -888,6 +943,22 @@ module ClaudeAgentSDK
     end
   end
 
+  # Fallback for hook events the SDK does not yet model. Carries the wire
+  # event name and the complete raw payload so no fields are lost (Python
+  # passes hook input through as a raw dict, so unknown events lose
+  # nothing there).
+  class UnknownHookInput < BaseHookInput
+    attr_accessor :raw_input
+
+    def initialize(attributes = {})
+      super
+      # Direct assignment: BaseHookInput exposes hook_event_name as
+      # attr_reader only, and Type#assign_attribute silently drops keys
+      # without public setters.
+      @hook_event_name = attributes[:hook_event_name] || attributes['hook_event_name']
+    end
+  end
+
   # Setup hook specific output
   class SetupHookSpecificOutput < Type
     attr_accessor :additional_context
@@ -1480,10 +1551,10 @@ module ClaudeAgentSDK
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
                   :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
                   :can_use_tool, :hooks, :user,
-                  :agents, :setting_sources,
+                  :agents, :setting_sources, :skills,
                   :output_format, :max_budget_usd, :max_thinking_tokens,
                   :fallback_model, :plugins, :debug_stderr,
-                  :betas, :tools, :sandbox, :append_allowed_tools,
+                  :betas, :tools, :sandbox,
                   :thinking, :effort, :observers, :task_budget,
                   :session_store, :session_store_flush, :load_timeout_ms
     attr_reader :bare, :fork_session, :enable_file_checkpointing,
@@ -1596,8 +1667,11 @@ module ClaudeAgentSDK
       defaults = ClaudeAgentSDK.default_options
       return attributes unless defaults.any?
 
-      # Start from configured defaults (deep dup hashes to prevent mutation)
-      result = defaults.transform_values { |v| v.is_a?(Hash) ? v.dup : v }
+      # Start from configured defaults. Container values are recursively
+      # duped so per-instance mutation (options.allowed_tools << 'Bash')
+      # can never corrupt the global defaults; non-container leaves
+      # (Strings, Procs, SdkMcpServer instances) intentionally keep identity.
+      result = deep_dup_containers(defaults)
       attributes.each do |key, value|
         default_val = result[key]
         result[key] = if value.nil?
@@ -1610,6 +1684,16 @@ module ClaudeAgentSDK
       end
       result
     end
+
+    # Recurse ONLY into Hash/Array; leaves keep object identity (observer
+    # factories, callbacks, SDK MCP server instances must not be duped).
+    def deep_dup_containers(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, deep_dup_containers(v)] }
+      when Array then value.map { |v| deep_dup_containers(v) }
+      else value
+      end
+    end
   end
 
   # SDK MCP Tool definition

data/lib/claude_agent_sdk/version.rb

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