claude-agent-sdk 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a12b68451568e5428820499fb4bf42401596477ea74d6b25a8fad3637b70178
-  data.tar.gz: d0465a73a3cbe17d3775d65d83978c16527548f9f752f8786b606f2c8c1c3713
+  metadata.gz: c2722d8b996148ef678484d587c1fcd88aaa68d9f3a380b342ad81b784f558cc
+  data.tar.gz: ce8a7d155a9c21fcddd4ad4dee0ec2b728d5397bb378d0b4c53f867febbc9cf0
 SHA512:
-  metadata.gz: 8051e5090a5361c74eb67506cec3021c69da07e9150b41cce91c674af759f7f03a3b9547e08abf0297f17bd32441cc3d04e1ea62fb92c47168841fd9991e5669
-  data.tar.gz: c70f056865cd07758f372b35bf7e8a14571f88b4ae4189c41ef26309a637068593293d1057aba021c8c4d184821a384962e7547048d66d2c615090067d796231
+  metadata.gz: 4a73b55a0228259e19e847683c4acccc6ac319f355f7d7fe9c8fd01dbc642e6ff7de767217b770dd95b8e3e847f280f46b49a7888f534278529b576412c29a7a
+  data.tar.gz: 5a1012c3ebd9a59f2a97476210b41873d616f053e7c02ba7c2bb385968f8134fb13b9f13730bb0c404b41877cc169dbde7c94f2d87b461671377492934511d0f

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-08-09
+
+### Fixed
+- **Skill names in `ClaudeAgentOptions#skills` are now validated** (port of Python SDK [#1145](https://github.com/anthropics/claude-agent-sdk-python/pull/1145), v0.2.129). Names were formatted into the `--allowedTools` value unchecked; the CLI splits that value into permission rules on commas and spaces outside parentheses with no escape sequences, so a name carrying a delimiter could not be passed through reliably. The command builder now validates each name and fails closed with `ArgumentError` (`TypeError` for non-String entries). Rejected: parentheses, commas, control characters (C0, DEL, C1), U+FEFF, empty names; a literal `*` and wildcard suffixes (`:*`, ` *`); and shapes that parse but can never match the listed skill — surrounding whitespace (Unicode-aware, unlike `String#strip`), a leading `/`, consecutive backslashes, a trailing unpaired backslash, and byte sequences that cannot form valid UTF-8 (Ruby's analogue of Python's surrogate check). Ordinary names are unaffected, including plugin-qualified names, interior spaces, single backslashes, and non-ASCII; valid non-UTF-8 strings are converted so the argv join cannot raise `Encoding::CompatibilityError`.
+  - **Breaking:** `skills: ['*']` and `skills: ['plugin:*']` now raise — use `skills: 'all'`, or a `Skill(...)` rule in `allowed_tools` for prefix matching. `skills: [' name']` and `skills: ['/name']` now raise as well; both previously built a rule that could never match, so the skill was silently unavailable.
+
 ## [0.28.0] - 2026-07-31
 
 ### Changed

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

data/lib/claude_agent_sdk/command_builder.rb

@@ -9,6 +9,16 @@ module ClaudeAgentSDK
   class CommandBuilder
     EXTRA_ARG_FLAG_REGEXP = /\A[a-z0-9][a-z0-9-]*\z/
 
+    # Parentheses and commas are delimiters to the --allowedTools tokenizer;
+    # control characters (C0, DEL, C1) never appear in a skill directory name.
+    # U+FEFF is here rather than in the whitespace checks below because the
+    # CLI trims it as whitespace and [[:space:]] does not match it.
+    SKILL_NAME_INVALID_CHARS = /[(),\u0000-\u001F\u007F-\u009F\uFEFF]/
+
+    # Unicode-aware edge whitespace: the CLI and Skill tool trim Unicode
+    # whitespace, and Ruby's String#strip is ASCII-only.
+    SKILL_NAME_EDGE_WHITESPACE = /\A[[:space:]]+|[[:space:]]+\z/
+
     def initialize(cli_path, options)
       @cli_path = cli_path
       @options = options
@@ -93,26 +103,89 @@ module ClaudeAgentSDK
     # entry, no duplicates) and default setting_sources to user+project so
     # skill files are actually discovered. Explicit setting_sources (including
     # []) is never overridden. Non-mutating; returns the effective pair.
-    # Justified divergence: a non-'all' String raises (NoMethodError on #each)
-    # instead of Python's quirk of iterating its characters.
+    # Each listed name is validated before being formatted into a rule (see
+    # #validate_skill_name). Both SDKs reject non-list, non-'all' shapes
+    # loudly; this raises ArgumentError where Python raises TypeError.
     def skills_defaults
       allowed_tools = @options.allowed_tools.dup
       setting_sources = @options.setting_sources&.dup
       skills = @options.skills
       return [allowed_tools, setting_sources] if skills.nil?
 
-      # Fail loudly with a clear message instead of a bare NoMethodError from
-      # deep inside build for skills: :all / 'pdf' / Hash typos (and instead
-      # of Python's quirk of iterating a String's characters).
       valid = skills == "all" || skills.is_a?(Array)
       raise ArgumentError, "skills must be 'all' or an Array of skill names (got #{skills.inspect})" unless valid
 
-      entries = skills == "all" ? ["Skill"] : skills.map { |name| "Skill(#{name})" }
+      entries = skills == "all" ? ["Skill"] : skills.map { |name| "Skill(#{validate_skill_name(name)})" }
       entries.each { |entry| allowed_tools << entry unless allowed_tools.include?(entry) }
       setting_sources = %w[user project] if setting_sources.nil?
       [allowed_tools, setting_sources]
     end
 
+    # Reject skill names that cannot ride safely in a Skill(name) rule
+    # (port of Python SDK #1145). Names from options.skills are formatted
+    # into the --allowedTools value, which the CLI splits into rules on
+    # commas and spaces outside parentheses. That tokenizer honors no escape
+    # sequences -- escaping exists only in the per-rule grammar, applied
+    # after splitting -- so a name carrying a delimiter cannot be passed
+    # through reliably: what it tokenizes into depends on what surrounds it.
+    #
+    # Names that tokenize cleanly but can never match the listed skill are
+    # rejected too, so a dead rule fails loudly here instead of silently
+    # granting nothing. Returns the name as a UTF-8 String so later argv
+    # joins cannot raise Encoding::CompatibilityError.
+    def validate_skill_name(name) # rubocop:disable Metrics/MethodLength
+      raise TypeError, "Skill names must be strings, got #{name.class}: #{name.inspect}" unless name.is_a?(String)
+
+      # Ruby's analogue of Python's surrogate check: a lone surrogate (or any
+      # other broken byte sequence) is unrepresentable in valid UTF-8, and no
+      # CLI-discovered skill name contains one.
+      utf8 = begin
+        name.encode(Encoding::UTF_8)
+      rescue EncodingError
+        nil
+      end
+      if utf8.nil? || !utf8.valid_encoding?
+        raise ArgumentError, "Invalid skill name #{name.inspect}: contains bytes that cannot form " \
+                             "valid UTF-8 (such as a surrogate code point), which can never match " \
+                             "a skill the CLI discovered."
+      end
+
+      stripped = utf8.gsub(SKILL_NAME_EDGE_WHITESPACE, "")
+      raise ArgumentError, "Skill names must be non-empty strings" if stripped.empty?
+
+      if utf8 != stripped
+        raise ArgumentError, "Invalid skill name #{name.inspect}: leading or trailing whitespace " \
+                             "can never match -- the Skill tool trims the invoked name."
+      end
+      if SKILL_NAME_INVALID_CHARS.match?(utf8)
+        raise ArgumentError, "Invalid skill name #{name.inspect}: parentheses, commas, control " \
+                             "characters, and byte-order marks are not allowed. Names match the " \
+                             "skill's directory name, or 'plugin:skill' for plugin-qualified skills."
+      end
+      raise ArgumentError, "Invalid skill name '*': use skills: 'all' to enable every skill." if utf8 == "*"
+
+      if utf8.end_with?(":*", " *")
+        raise ArgumentError, "Invalid skill name #{name.inspect}: wildcard-suffix names are not " \
+                             "allowed; list each skill by its exact name."
+      end
+      if utf8.start_with?("/")
+        raise ArgumentError, "Invalid skill name #{name.inspect}: skill names may not start with " \
+                             "'/'. The skills option takes the canonical name, not the " \
+                             "slash-command form."
+      end
+      if utf8.include?("\\\\")
+        raise ArgumentError, "Invalid skill name #{name.inspect}: consecutive backslashes are not " \
+                             "allowed -- the per-rule parser collapses them, so the rule would " \
+                             "name a different skill."
+      end
+      if utf8.end_with?("\\")
+        raise ArgumentError, "Invalid skill name #{name.inspect}: names may not end with an " \
+                             "unpaired backslash."
+      end
+
+      utf8
+    end
+
     def append_disallowed_tools(cmd)
       cmd.push("--disallowedTools", @options.disallowed_tools.join(",")) unless @options.disallowed_tools.empty?
     end

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async