claude-agent-sdk 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2722d8b996148ef678484d587c1fcd88aaa68d9f3a380b342ad81b784f558cc
-  data.tar.gz: ce8a7d155a9c21fcddd4ad4dee0ec2b728d5397bb378d0b4c53f867febbc9cf0
+  metadata.gz: e8e1fbf9996a81e6493a2fd8fd15a4922645933fccc93cd7d279763f01658d80
+  data.tar.gz: 87a8bbae7de66555c1c9d81f4791fe11ed51c385c233ec94e2541292d81f5870
 SHA512:
-  metadata.gz: 4a73b55a0228259e19e847683c4acccc6ac319f355f7d7fe9c8fd01dbc642e6ff7de767217b770dd95b8e3e847f280f46b49a7888f534278529b576412c29a7a
-  data.tar.gz: 5a1012c3ebd9a59f2a97476210b41873d616f053e7c02ba7c2bb385968f8134fb13b9f13730bb0c404b41877cc169dbde7c94f2d87b461671377492934511d0f
+  metadata.gz: 0d3ad7f14b8b231a4e64cc850acda569818f215e85b6e032e9217903ee650b6d434b7c8e95823fd8d6e3dde78177a3533e683b2cb96dc956c41f921324c3770c
+  data.tar.gz: '093dd27e1cd34afb33998236f761a2515ef787d86980a54bc5c9cc5c16635b8419800b0c6f7010e46cc959703abd12acdaf7cbc0135c3c532cdd2d94903a22de'

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-08-09
+
+### Added
+- **`ClaudeAgentSDK::CLIInstaller`** — downloads a pinned `claude` CLI binary into a project-local directory (`vendor/claude` by default) for hermetic deploys, so a Docker image or CI job runs a known CLI version instead of whatever `npm install -g` last put on `PATH`. `CLIInstaller.install(version: '2.1.220', dir: nil)` resolves `stable`/`latest` dist-tags through the official release endpoint, verifies the platform's SHA-256 from the release manifest, streams the ~280MB binary to an unpredictable sibling temp file (opened `O_EXCL`, so a pre-planted path or symlink is never written through) and renames it into place atomically (`0755`), then records the version **and** the verified checksum in a sibling `VERSION` file. `CLIInstaller.installed_path` returns the vendored binary or `nil`. Stdlib only — no new runtime dependency, and no binary shipped inside the gem. Supports macOS and Linux (glibc + musl, x86_64 + arm64, with a Rosetta 2 override so an x86_64 Ruby on Apple Silicon gets the native build); every failure raises the new `ClaudeAgentSDK::CLIInstallError`, filesystem errors included (wrapped, with `cause` preserved).
+  - **Idempotent without trusting the recorded version alone**: the shortcut re-hashes the vendored binary and skips the download only when version *and* checksum match, so a truncated or swapped binary is reinstalled rather than used. It makes no network request — repeat boots work offline.
+  - **Concurrency-safe**: an exclusive `flock` on `<dir>/.install.lock` covers dist-tag resolution and the whole check → download → record → publish sequence (last resolver wins, so a slow installer cannot downgrade a newer version published while it waited), and the `VERSION` file is written atomically (temp + rename), so parallel installs into one directory can never observe or produce a half-installed state. Temp files abandoned by an install that was killed before it could clean up are swept on the next run. Discovery (`installed_path`, `find_cli`) stays lock-free: the binary only ever changes by an atomic rename of a fully verified file, so a reader sees the intact old binary or the intact new one.
+  - **A failed install never breaks a working one**: the binary is downloaded, verified and *recorded* before the rename that publishes it, and nothing can fail after that rename. A failed upgrade therefore leaves the previously installed binary intact and runnable, with the next `install` redoing it cleanly; a failed first install leaves nothing behind.
+  - Text responses are size-capped (1KB for the version endpoint, 5MB for the manifest), and the binary download is bounded by the manifest's declared `size` when present — an over-long stream is aborted instead of filling the disk. The binary streams to disk and is never buffered in memory.
+- **CLI discovery now honors `CLAUDE_CLI_PATH` and the vendored binary.** `SubprocessCLITransport#find_cli` probes `CLAUDE_CLI_PATH` (when it points at an executable), then `CLIInstaller.installed_path`, then the existing `which claude` and common-location logic. The vendored copy deliberately outranks `PATH` — that is what makes a pinned install hermetic. `CLINotFoundError` now also mentions both escape hatches.
+
 ## [0.29.0] - 2026-08-09
 
 ### Fixed

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.29.0'
+gem 'claude-agent-sdk', '~> 0.30.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -78,6 +78,56 @@ Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
 - Node.js
 - Claude Code 2.0.0+: `npm install -g @anthropic-ai/claude-code`
 
+### Vendoring the CLI (hermetic deploys)
+
+The SDK runs the `claude` CLI as a subprocess, so a deploy is only reproducible if the CLI version is pinned with it. `CLIInstaller` downloads a pinned binary from the official release endpoint into a project-local directory (`vendor/claude` by default) — checksum-verified, no npm/Node at runtime, and nothing extra shipped inside the gem.
+
+```ruby
+require 'claude_agent_sdk'
+
+# 'stable' (default), 'latest', or a concrete version — pin it in production.
+ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
+# => "/app/vendor/claude/claude"
+
+ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220', dir: '/opt/claude')
+
+# nil unless a binary is already installed there
+ClaudeAgentSDK::CLIInstaller.installed_path
+```
+
+`install` is idempotent and safe to run concurrently, so it fits `bin/setup`, a cached Docker layer, and every process of a multi-process boot:
+
+- The install directory's `VERSION` file records the installed version **and** the SHA-256 that was verified at download time. The shortcut re-hashes the vendored binary (~0.1s for the real 245MB binary) and only skips the download when both match — a truncated, swapped or half-written binary is reinstalled instead of trusted. It makes **no network request**, so repeat boots work offline — with a pinned concrete version; `'stable'`/`'latest'` must always re-resolve through the endpoint, which is one more reason to pin in production.
+- An exclusive `flock` on `<dir>/.install.lock` covers the whole check → download → place → record sequence, so parallel installs into one directory don't race; the loser simply observes the finished install.
+
+Failures (unsupported platform, invalid version, HTTP error, response-size cap, oversized download, checksum mismatch, filesystem errors) raise `ClaudeAgentSDK::CLIInstallError`.
+
+**A failed install never breaks a working one.** The new binary is downloaded to a temp file, checksum-verified and recorded, and only then renamed into place — the rename is the last step, and nothing can fail after it. So a failed upgrade leaves the previously installed binary intact and runnable (the SDK keeps working), and the next `install` redoes it cleanly. A first install that fails leaves nothing behind at all.
+
+> The vendored directory is trusted input: anything that can write to it can replace the binary the SDK executes. Keep it inside your deploy artifact, owned by the deploy user and not world-writable, exactly as you would treat `bin/`.
+
+```dockerfile
+# Dockerfile — pin the CLI in its own cached layer
+RUN bundle exec ruby -e "require 'claude_agent_sdk'; \
+    ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')"
+```
+
+```ruby
+#!/usr/bin/env ruby
+# bin/setup
+require 'claude_agent_sdk'
+puts ClaudeAgentSDK::CLIInstaller.install(version: ENV.fetch('CLAUDE_CLI_VERSION', 'stable'))
+```
+
+Supported platforms: `darwin-arm64`, `darwin-x64` (Rosetta 2 gets the arm64 build), `linux-x64`, `linux-arm64`, and the `-musl` variants. Windows is not supported.
+
+**CLI discovery order.** With no explicit `cli_path:` in `ClaudeAgentOptions`, the transport probes in this order:
+
+1. `CLAUDE_CLI_PATH` — an explicit path to an executable, no discovery at all (a relative value is resolved against the process's working directory, not `cwd:`)
+2. The vendored binary (`CLIInstaller.installed_path`) — deliberately ahead of `PATH`, so a pinned install beats whatever is installed globally
+3. `which claude`
+4. Common install locations (`~/.claude/local/claude`, `/usr/local/bin/claude`, …)
+
 ### Agentic Coding Skill
 
 If you're using [Claude Code](https://claude.ai/claude-code), this repo is a Claude Code plugin marketplace. Add it once, then install the skill:

data/lib/claude_agent_sdk/cli_installer.rb

@@ -0,0 +1,459 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'open3'
+require 'rbconfig'
+require 'securerandom'
+require 'uri'
+require_relative 'errors'
+
+module ClaudeAgentSDK
+  # Downloads a pinned Claude Code CLI binary into a project-local directory.
+  #
+  # Motivation: the SDK shells out to `claude`, so a deploy artifact is only
+  # hermetic if the CLI version is pinned alongside it. Vendoring the ~280MB
+  # binary into the gem is a non-starter, so instead a Docker build / bin/setup
+  # step calls +install+, and SubprocessCLITransport#find_cli prefers that
+  # vendored copy over whatever is on PATH.
+  #
+  # Mirrors what https://claude.ai/install.sh does: resolve a dist-tag to a
+  # concrete version, read the release manifest for the platform's SHA-256,
+  # stream the binary down, verify it, then move it into place atomically.
+  #
+  # Stdlib only (net/http, json, digest, fileutils, rbconfig) — the gem gains
+  # no runtime dependency for this.
+  #
+  # @example Pin a version in bin/setup or a Dockerfile build step
+  #   ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
+  module CLIInstaller
+    BASE_URL = 'https://downloads.claude.ai/claude-code-releases'
+    # Dist-tags resolved through a GET to BASE_URL/<tag>.
+    DIST_TAGS = %w[stable latest].freeze
+    # Concrete version, optionally with a pre-release suffix (e.g. 2.1.220-rc1).
+    # The suffix is restricted to the semver pre-release character set: every
+    # accepted version is interpolated straight into a download URL, and a
+    # laxer `\S+` would let "2.1.220-x/../2.1.221" traverse out of the release
+    # path — silently installing something other than the pinned version.
+    VERSION_PATTERN = /\A\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?\z/
+    CHECKSUM_PATTERN = /\A[0-9a-f]{64}\z/
+    BINARY_NAME = 'claude'
+    VERSION_FILE = 'VERSION'
+    LOCK_FILE = '.install.lock'
+    # Relative to Dir.pwd, resolved at CALL time by .default_dir — an absolute
+    # constant would freeze the working directory as of require time, which is
+    # wrong for anything that chdirs (Rake tasks, bin/setup, test suites).
+    DEFAULT_DIR = File.join('vendor', 'claude')
+    # Response caps. The dist-tag endpoints return a bare version string and
+    # manifests are a few KB; anything larger is a misrouted response, not
+    # something to buffer in memory. (The binary itself streams to disk.)
+    VERSION_RESPONSE_LIMIT = 1024
+    MANIFEST_RESPONSE_LIMIT = 5 * 1024 * 1024
+    METADATA_READ_LIMIT = 4096
+
+    # Maps the running Ruby to a release-manifest platform key
+    # (darwin-arm64, darwin-x64, linux-x64, linux-arm64, and the -musl
+    # variants). Windows is not supported by this gem.
+    module Platform
+      class << self
+        def detect
+          target = ruby_platform.to_s.downcase
+          os = detect_os(target)
+          arch = detect_arch(target)
+          # A Ruby built for x86_64 running under Rosetta 2 reports darwin-x64,
+          # but the machine is arm64 — install the native binary.
+          arch = 'arm64' if os == 'darwin' && arch == 'x64' && rosetta?
+          suffix = os == 'linux' && target.include?('musl') ? '-musl' : ''
+          "#{os}-#{arch}#{suffix}"
+        end
+
+        private
+
+        def detect_os(target)
+          return 'darwin' if target.include?('darwin')
+          return 'linux' if target.include?('linux')
+
+          raise CLIInstallError,
+                "Unsupported platform #{ruby_platform.inspect} for the Claude Code CLI " \
+                '(supported: macOS and Linux; Windows is not supported by this gem)'
+        end
+
+        def detect_arch(target)
+          case target
+          when /aarch64|arm64/ then 'arm64'
+          when /x86_64|x64|amd64/ then 'x64'
+          else
+            raise CLIInstallError,
+                  "Unsupported CPU architecture in #{ruby_platform.inspect} (supported: x86_64 and arm64)"
+          end
+        end
+
+        # Single source of platform truth, and the seam the specs stub.
+        # RUBY_PLATFORM carries OS, CPU and libc on CRuby; JRuby reports a
+        # bare 'java', so fall back to the RbConfig host description there.
+        def ruby_platform
+          return RUBY_PLATFORM unless RUBY_PLATFORM == 'java'
+
+          "#{RbConfig::CONFIG['host_os']}-#{RbConfig::CONFIG['host_cpu']}"
+        end
+
+        def rosetta?
+          stdout, status = Open3.capture2('sysctl', '-n', 'sysctl.proc_translated')
+          status.success? && stdout.strip == '1'
+        rescue StandardError
+          # sysctl missing or not permitted — assume native.
+          false
+        end
+      end
+    end
+
+    # HTTPS GET with bounded redirects, timeouts, a response-size cap for text
+    # and chunked streaming for the binary. Knows nothing about releases; the
+    # specs stub .fetch_text / .download_to wholesale so no HTTP stubbing
+    # library is needed.
+    module Http
+      MAX_REDIRECTS = 5
+      OPEN_TIMEOUT_SECONDS = 10
+      READ_TIMEOUT_SECONDS = 60
+
+      class << self
+        # +limit+ bounds how many bytes are buffered: the caller knows the
+        # expected shape of the response, and an unbounded read of a misrouted
+        # (or hostile) endpoint is an easy way to exhaust memory.
+        def fetch_text(url, limit:)
+          with_response(url) do |response|
+            body = +''
+            response.read_body do |chunk|
+              body << chunk
+              raise CLIInstallError, "Response from #{url} exceeds the #{limit}-byte limit" if body.bytesize > limit
+            end
+            body
+          end
+        end
+
+        # Streams the response to +path+ in chunks — the CLI binary is ~280MB
+        # and must never be materialized in memory. O_EXCL: +path+ must not
+        # exist, so a pre-planted file or symlink is never written through.
+        # +max_bytes+ (the manifest's declared size, when it has one) aborts a
+        # response that runs long instead of filling the disk before the
+        # checksum gets a chance to reject it.
+        def download_to(url, path, max_bytes: nil)
+          with_response(url) do |response|
+            written = 0
+            File.open(path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o600) do |file|
+              response.read_body do |chunk|
+                written += chunk.bytesize
+                raise CLIInstallError, "Download from #{url} exceeds the expected #{max_bytes} bytes" if over?(written, max_bytes)
+
+                file.write(chunk)
+              end
+            end
+          end
+          path
+        end
+
+        private
+
+        def over?(written, max_bytes)
+          !max_bytes.nil? && written > max_bytes
+        end
+
+        def with_response(url, redirects_left = MAX_REDIRECTS, &block)
+          uri = url.is_a?(URI::Generic) ? url : URI(url.to_s)
+          raise CLIInstallError, "Refusing to fetch non-HTTPS URL: #{uri}" unless uri.is_a?(URI::HTTPS)
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                              open_timeout: OPEN_TIMEOUT_SECONDS,
+                                              read_timeout: READ_TIMEOUT_SECONDS) do |http|
+            http.request(Net::HTTP::Get.new(uri)) do |response|
+              # Branch on the status BEFORE touching the body: a redirect or an
+              # error page must never be streamed into the target file.
+              return block.call(response) if response.is_a?(Net::HTTPSuccess)
+              return follow_redirect(uri, response, redirects_left, &block) if response.is_a?(Net::HTTPRedirection)
+
+              raise CLIInstallError, "HTTP #{response.code} #{response.message} for #{uri}"
+            end
+          end
+        rescue CLIInstallError
+          raise
+        rescue StandardError => e
+          raise CLIInstallError, "Failed to fetch #{url}: #{e.class}: #{e.message}"
+        end
+
+        def follow_redirect(uri, response, redirects_left, &block)
+          raise CLIInstallError, "Too many redirects while fetching #{uri}" if redirects_left <= 0
+
+          location = response['location'].to_s
+          raise CLIInstallError, "Redirect from #{uri} is missing a Location header" if location.empty?
+
+          with_response(URI.join(uri.to_s, location), redirects_left - 1, &block)
+        end
+      end
+    end
+
+    # Talks to the release service: dist-tag resolution, manifest lookup and
+    # URL construction. Pure remote reads — no filesystem, no state.
+    module Release
+      class << self
+        # Local, network-free check of what the caller asked for. Returns the
+        # normalized request — a dist-tag name or a concrete version — so bad
+        # input fails before the installer touches the filesystem.
+        def validate_version(version)
+          version = version.to_s.strip
+          return version if DIST_TAGS.include?(version) || version.match?(VERSION_PATTERN)
+
+          raise CLIInstallError,
+                "Invalid Claude Code CLI version #{version.inspect}: " \
+                "expected #{DIST_TAGS.join('/')} or a version like '2.1.220'"
+        end
+
+        # Turns a validated request into a concrete version: dist-tags go to
+        # the network, concrete versions are already the answer.
+        def resolve_version(validated)
+          DIST_TAGS.include?(validated) ? resolve_dist_tag(validated) : validated
+        end
+
+        # The manifest's release info for +platform+: the SHA-256 (required,
+        # validated as 64 hex chars) and the declared download size (optional
+        # — nil when absent or not a positive Integer, in which case the
+        # checksum alone vouches for the download).
+        def platform_entry(version, platform)
+          url = "#{BASE_URL}/#{version}/manifest.json"
+          platforms = parse_manifest(Http.fetch_text(url, limit: MANIFEST_RESPONSE_LIMIT), url)['platforms']
+          entry = platforms.is_a?(Hash) ? platforms[platform] : nil
+          unless entry.is_a?(Hash)
+            available = platforms.is_a?(Hash) ? platforms.keys.sort.join(', ') : 'none'
+            raise CLIInstallError, "#{url} has no entry for platform #{platform} (available: #{available})"
+          end
+
+          checksum = entry['checksum'].to_s.downcase
+          raise CLIInstallError, "#{url} has no valid sha256 checksum for #{platform}" unless checksum.match?(CHECKSUM_PATTERN)
+
+          size = entry['size']
+          { checksum: checksum, size: size.is_a?(Integer) && size.positive? ? size : nil }
+        end
+
+        def binary_url(version, platform)
+          "#{BASE_URL}/#{version}/#{platform}/#{BINARY_NAME}"
+        end
+
+        private
+
+        # The dist-tag endpoints return a bare version string. Validate it: an
+        # HTML error page or a redirect to a login screen would otherwise be
+        # pasted straight into the download URLs.
+        def resolve_dist_tag(tag)
+          url = "#{BASE_URL}/#{tag}"
+          body = Http.fetch_text(url, limit: VERSION_RESPONSE_LIMIT).to_s.strip
+          return body if body.match?(VERSION_PATTERN)
+
+          raise CLIInstallError, "#{url} did not return a version string (got #{body[0, 80].inspect})"
+        end
+
+        def parse_manifest(body, url)
+          manifest = JSON.parse(body.to_s)
+          raise CLIInstallError, "#{url} is not a JSON object" unless manifest.is_a?(Hash)
+
+          manifest
+        rescue JSON::ParserError => e
+          raise CLIInstallError, "#{url} returned malformed JSON: #{e.message}"
+        end
+      end
+    end
+
+    # The VERSION file: line 1 the installed version, line 2 the SHA-256 of the
+    # binary that was verified at install time. The checksum is what lets the
+    # idempotency shortcut trust the vendored binary without a network call —
+    # a truncated, swapped or half-written binary no longer looks installed.
+    # An older single-line VERSION file simply reads as "no metadata", which
+    # triggers a clean reinstall.
+    module Metadata
+      class << self
+        def read(dir)
+          path = File.join(dir, VERSION_FILE)
+          return nil unless File.file?(path)
+
+          version, checksum = File.read(path, METADATA_READ_LIMIT).to_s.split("\n", 3)
+          version = version.to_s.strip
+          checksum = checksum.to_s.strip.downcase
+          return nil unless version.match?(VERSION_PATTERN) && checksum.match?(CHECKSUM_PATTERN)
+
+          { version: version, checksum: checksum }
+        end
+
+        # Atomic: an unpredictable temp name opened O_EXCL, then renamed over
+        # the old file. Without this a reader could observe a half-written
+        # VERSION, or (worse) the previous version paired with a new binary.
+        def write(dir, version, checksum)
+          tmp = File.join(dir, "#{VERSION_FILE}.#{SecureRandom.hex(8)}.tmp")
+          begin
+            File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+              file.write("#{version}\n#{checksum}\n")
+            end
+            File.rename(tmp, File.join(dir, VERSION_FILE))
+          ensure
+            FileUtils.rm_f(tmp)
+          end
+        end
+      end
+    end
+
+    class << self
+      # Absolute path of the default install directory, resolved against the
+      # current working directory each time it is asked for.
+      def default_dir
+        File.expand_path(DEFAULT_DIR, Dir.pwd)
+      end
+
+      # Install the CLI into +dir+ and return the absolute path of the binary.
+      # +version+ is 'stable', 'latest', or a concrete version like '2.1.220'.
+      #
+      # Idempotent and safe to run concurrently: an exclusive lock on
+      # dir/.install.lock covers the whole check-download-place-record
+      # sequence, so parallel boots (Docker layers, `foreman start`, CI matrix
+      # jobs sharing a cache) never race each other into a partially written
+      # binary — the loser of the race observes a finished install.
+      #
+      # The shortcut re-hashes the vendored binary (~0.1s for the real 245MB
+      # binary) rather than trusting the recorded version alone, and never
+      # touches the network: repeat boots must work offline (with a pinned
+      # version — a dist-tag has to be re-resolved to be resolved at all).
+      #
+      # An upgrade never destroys a working install: see #publish.
+      def install(version: 'stable', dir: nil)
+        dir = File.expand_path(dir || default_dir)
+        # Validated (locally) first, so malformed input never creates a
+        # directory; RESOLVED inside the lock, so a dist-tag cannot be read
+        # before another installer publishes a newer version and then be used
+        # to downgrade it. Semantics: last resolver wins.
+        requested = Release.validate_version(version)
+        binary = File.join(dir, BINARY_NAME)
+        FileUtils.mkdir_p(dir)
+        with_install_lock(dir) do
+          sweep_stale_temp_files(dir)
+          resolved = Release.resolve_version(requested)
+          next binary if installed?(dir, resolved)
+
+          platform = Platform.detect
+          publish(dir, binary, resolved, platform, Release.platform_entry(resolved, platform))
+          binary
+        end
+      rescue CLIInstallError
+        raise
+      rescue SystemCallError, IOError => e
+        # Filesystem failures (EACCES on the install dir, ENOSPC mid-download,
+        # a read-only mount) reach callers as CLIInstallError like every other
+        # install failure; `cause` keeps the original for debugging.
+        raise CLIInstallError, "Failed to install the Claude Code CLI into #{dir}: #{e.class}: #{e.message}"
+      end
+
+      # Path of an already-installed binary, or nil.
+      #
+      # Deliberately lock-free, because #publish makes the lock unnecessary
+      # for readers: the binary only ever changes by a rename of a
+      # fully-downloaded, checksum-verified file, so a concurrent reader (this
+      # method, or find_cli, or the CLI being spawned) sees either the intact
+      # old binary or the intact new one — never a partial file. Taking the
+      # install lock here would put every process start behind an in-progress
+      # download for no added safety.
+      def installed_path(dir: nil)
+        path = File.join(File.expand_path(dir || default_dir), BINARY_NAME)
+        File.file?(path) && File.executable?(path) ? path : nil
+      rescue SystemCallError
+        nil
+      end
+
+      private
+
+      # Cross-process mutual exclusion for the whole install. flock is
+      # advisory and per open file description, so concurrent threads in one
+      # process contend here exactly like separate processes do.
+      def with_install_lock(dir)
+        flags = File::RDWR | File::CREAT
+        # Never follow a symlink planted at the lock path.
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(File.join(dir, LOCK_FILE), flags, 0o644) do |lock|
+          lock.flock(File::LOCK_EX)
+          begin
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+      end
+
+      # Remove temp files abandoned by an earlier install that died before its
+      # `ensure` could run (SIGKILL, power loss, OOM) — each one can be the
+      # full ~280MB, and every retry picks a fresh random name, so without
+      # this they accumulate. Safe because we hold the install lock: no other
+      # installer can have a download in flight. Never blocks the install.
+      def sweep_stale_temp_files(dir)
+        ["#{BINARY_NAME}.download.*", "#{VERSION_FILE}.*.tmp"].each do |pattern|
+          # base: keeps glob metacharacters in +dir+ (a `[` in a project path)
+          # from being interpreted as part of the pattern.
+          Dir.glob(pattern, base: dir).each { |name| FileUtils.rm_f(File.join(dir, name)) }
+        end
+      rescue StandardError
+        nil
+      end
+
+      # True only when the vendored binary is byte-for-byte the one recorded
+      # by a previous install of this exact version. No network access.
+      def installed?(dir, version)
+        binary = installed_path(dir: dir)
+        return false unless binary
+
+        recorded = Metadata.read(dir)
+        return false unless recorded && recorded[:version] == version
+
+        Digest::SHA256.file(binary).hexdigest == recorded[:checksum]
+      rescue SystemCallError
+        false
+      end
+
+      # Download, verify, record, then swap the binary in — in that order.
+      #
+      # The rename is deliberately LAST, because it is the only step with no
+      # possible failure after it. That ordering is what keeps a failed
+      # upgrade from destroying a working install:
+      #
+      #   * download/checksum/metadata failure → the old binary and its old
+      #     metadata are untouched; the install that was already there keeps
+      #     working, and nothing is left behind but the (removed) temp file.
+      #   * rename failure or a crash right before it → the old binary is
+      #     still intact and runnable; the metadata already names the new
+      #     version, whose checksum the old binary cannot match, so the next
+      #     install sees "not installed" and redoes it cleanly.
+      #
+      # (The reverse order — rename then record — briefly published a binary
+      # nothing vouched for, and a metadata failure then had to delete the
+      # freshly renamed file, taking the previous working install with it.)
+      def publish(dir, binary, version, platform, entry)
+        tmp = "#{binary}.download.#{SecureRandom.hex(8)}"
+        begin
+          fetch_verified(version, platform, entry, tmp)
+          Metadata.write(dir, version, entry[:checksum])
+          File.rename(tmp, binary)
+        ensure
+          FileUtils.rm_f(tmp)
+        end
+      end
+
+      # Download to an unpredictable sibling temp name (same filesystem, so the
+      # rename is atomic; O_EXCL, so a pre-planted path or symlink cannot be
+      # written through), bounded by the manifest's declared size, then verify
+      # and chmod. Leaves the file at +tmp+ for #publish to swap in.
+      def fetch_verified(version, platform, entry, tmp)
+        url = Release.binary_url(version, platform)
+        Http.download_to(url, tmp, max_bytes: entry[:size])
+        actual = Digest::SHA256.file(tmp).hexdigest
+        expected = entry[:checksum]
+        raise CLIInstallError, "Checksum mismatch for #{url}: expected #{expected}, got #{actual}" if actual != expected
+
+        File.chmod(0o755, tmp)
+      end
+    end
+  end
+end

data/lib/claude_agent_sdk/errors.rb

@@ -18,6 +18,11 @@ module ClaudeAgentSDK
     end
   end
 
+  # Raised when CLIInstaller cannot install the Claude Code CLI binary
+  # (unsupported platform, invalid/unresolvable version, HTTP failure,
+  # missing manifest entry, checksum mismatch).
+  class CLIInstallError < ClaudeSDKError; end
+
   # Raised when the CLI process fails
   class ProcessError < ClaudeSDKError
     attr_reader :exit_code, :stderr

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -8,6 +8,7 @@ require_relative 'transport'
 require_relative 'errors'
 require_relative 'version'
 require_relative 'command_builder'
+require_relative 'cli_installer'
 
 module ClaudeAgentSDK
   # Subprocess transport using Claude Code CLI
@@ -15,6 +16,7 @@ module ClaudeAgentSDK
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
     SKIP_VERSION_CHECK_ENV_VAR = 'CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK'
+    CLI_PATH_ENV_VAR = 'CLAUDE_CLI_PATH'
     VERSION_CHECK_TIMEOUT_SECONDS = 2 # mirrors Python's anyio.fail_after(2)
     RECENT_STDERR_LINES_LIMIT = 20
 
@@ -110,7 +112,36 @@ module ClaudeAgentSDK
       @stdin_mutex = Mutex.new
     end
 
+    # Probe order (first hit wins):
+    #   1. CLAUDE_CLI_PATH — explicit operator override, no discovery at all.
+    #   2. A project-local vendored binary (CLIInstaller). Deliberately ahead
+    #      of PATH: the point of a pinned, vendored CLI is that it beats
+    #      whatever version happens to be installed globally on the host.
+    #   3. `which claude`.
+    #   4. Well-known install locations.
     def find_cli
+      env_path = ENV.fetch(CLI_PATH_ENV_VAR, nil).to_s
+      unless env_path.empty?
+        # Absolutize against the CURRENT working directory, which is where the
+        # checks below resolve a relative path — the CLI is later spawned with
+        # `chdir: options.cwd`, where the same relative path would name a
+        # different file (or nothing at all). Returning the absolute form makes
+        # what we validated and what we execute the same file.
+        env_path = File.expand_path(env_path)
+        # File.file? as well as executable?: executable? is true for
+        # directories, so a directory in CLAUDE_CLI_PATH would otherwise pass
+        # here and fail much later with an opaque spawn error.
+        return env_path if File.file?(env_path) && File.executable?(env_path)
+      end
+
+      vendored = begin
+        CLIInstaller.installed_path
+      rescue StandardError
+        # e.g. Dir.pwd raising because the cwd was removed — fall through.
+        nil
+      end
+      return vendored if vendored
+
       # Try which command first (using Open3 for thread safety)
       cli = nil
       begin
@@ -141,7 +172,11 @@ module ClaudeAgentSDK
         "\nIf already installed locally, try:\n" \
         '  export PATH="$HOME/node_modules/.bin:$PATH"' \
         "\n\nOr provide the path via ClaudeAgentOptions:\n" \
-        "  ClaudeAgentOptions.new(cli_path: '/path/to/claude')"
+        "  ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
+        "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n" \
+        "  ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')" \
+        "\n\nOr point the SDK at an existing binary:\n" \
+        "  export #{CLI_PATH_ENV_VAR}=/path/to/claude"
       )
     end
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -6,6 +6,7 @@ require_relative 'claude_agent_sdk/configuration'
 require_relative 'claude_agent_sdk/types'
 require_relative 'claude_agent_sdk/observer'
 require_relative 'claude_agent_sdk/transport'
+require_relative 'claude_agent_sdk/cli_installer'
 require_relative 'claude_agent_sdk/subprocess_cli_transport'
 require_relative 'claude_agent_sdk/message_parser'
 require_relative 'claude_agent_sdk/query'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -121,6 +121,7 @@ files:
 - docs/types.md
 - lib/claude-agent-sdk.rb
 - lib/claude_agent_sdk.rb
+- lib/claude_agent_sdk/cli_installer.rb
 - lib/claude_agent_sdk/command_builder.rb
 - lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb