claude-agent-sdk 0.16.9 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cecc40526ae74334f69cf7f62b2362f14b223e31f040001c65dd285ee59dc31
-  data.tar.gz: cfa4deba728a02e5e4fa6909056db0a4855336d927fa0266adce005fe22d1e56
+  metadata.gz: abd1a08c12369ca6417cc28946a153f2f641ba38e1770026ff53ae36465da34c
+  data.tar.gz: c1a35168f601b9bf8f6680cf66565c6f06f26f0c4817d2e5a8afbe2923b0935d
 SHA512:
-  metadata.gz: 148d0a96b29a71793a3242ee75dc2ecc8052c96a76265133638202dcc930673aa783942688c28d9ee00a0b67830349b35ab6003d5b3cc5ce1290ae53acbb9978
-  data.tar.gz: 1c2a8b0297130b1b2f5b7342b487a75dbec500cad41299d3cf9a506b2618c8a12ed0289eaa9ae679dea0ebd15003d0b4219421ffe10af15579d59c776b89e27b
+  metadata.gz: 8fe246f00316a5d6d704e30d4a6df1d732be3d494d47fc222fe44738d7fc17914fd281a36b6fdf5200ddf69e7a8f2b4f6d471ec48799d0005375097a0d535ef8
+  data.tar.gz: 82cb35a8b05262b407014fd704eef12ac00f13bbb15f428c40e402b4fc6eb9576fd61b6f328bc4b00dc356365e2a16c18f6e5f97156877c0f7f4c23b499f8e96

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-06-10
+
+### Added
+- **Pluggable `SessionStore` adapter subsystem** — mirror Claude Code session transcripts to external storage (S3/Redis/Postgres/…) and resume from it, at parity with the Python SDK (#837 and follow-ups) and TypeScript SDK. The subprocess still writes to local disk; the adapter receives a secondary copy.
+  - **`SessionStore`** base class (6-method contract: `append`/`load` required; `list_sessions`/`list_session_summaries`/`delete`/`list_subkeys` optional, probed via `SessionStore.implements?` so duck-typed adapters need not subclass) and **`InMemorySessionStore`** reference implementation. All keys/entries cross the boundary as Hashes with **string keys** (JSON-round-trip safe for JSONB/Redis backends).
+  - **`ClaudeAgentSDK::Testing.run_session_store_conformance(make_store)`** — a 15-contract behavioral test suite for adapter authors (shipped in the gem, framework-agnostic; raises `ConformanceError` on violation).
+  - **Live mirroring** (on both `ClaudeAgentSDK.query` and `ClaudeAgentSDK::Client`): setting `ClaudeAgentOptions#session_store` emits `--session-mirror`; a `TranscriptMirrorBatcher` coalesces the CLI's `transcript_mirror` frames per file and flushes to `SessionStore#append` on each `result` (or 500-entry / 1 MiB overflow). `session_store_flush: "eager"` flushes after every frame. Append ordering is preserved across concurrent flushes (fiber-aware `Async::Semaphore`); the user store call runs on a `FiberBoundary` thread bounded by a fixed 60 s send timeout (`TranscriptMirrorBatcher::SEND_TIMEOUT_SECONDS`; `load_timeout_ms` bounds resume-materialization store calls instead); failures retry (3 attempts, 0.2/0.8 s backoff) then surface as a **`MirrorErrorMessage`** on the message stream. A failing store never disrupts the session (the local transcript is already durable).
+  - **Resume from store** (both entry points): pairing `session_store` with `resume`/`continue_conversation` materializes the session (and its subagent transcripts) from the store into a temp `CLAUDE_CONFIG_DIR` before spawn, repoints the subprocess at it, and cleans it up after the subprocess exits (on disconnect, one-shot teardown, **and** reactor cancellation). Store-supplied subagent subpaths are validated against path traversal; copied `.credentials.json` has its single-use `refreshToken` redacted; macOS Keychain credentials are bridged when needed.
+  - **Store-backed reads** (counterparts to the local readers): `ClaudeAgentSDK.list_sessions_from_store` (summary fast-path + gap-fill + pagination; a single failing row degrades to an empty summary rather than aborting the listing), `.get_session_info_from_store`, `.get_session_messages_from_store`, `.list_subagents_from_store`, `.get_subagent_messages_from_store`.
+  - **Store-backed mutations** (counterparts to the local mutators): `ClaudeAgentSDK.rename_session_via_store`, `.tag_session_via_store`, `.delete_session_via_store` (a no-op on WORM/append-only stores that don't implement `#delete`), and `.fork_session_via_store` (the UUID-remap fork transform run directly over the loaded entries — no JSONL round-trip; the fallback title is derived from the source's `customTitle`/`aiTitle`/first prompt).
+  - **Reference adapters** under `examples/session_stores/` (S3, Redis, Postgres) — copy-in implementations, each validated against `run_session_store_conformance`. Backend client gems live in the optional `:examples` Bundler group so a default install stays dependency-free.
+  - **`ClaudeAgentSDK.import_session_to_store`** — replay a local on-disk session (and subagents) into a store for migration / mirror-gap backfill.
+  - **`ClaudeAgentSDK.project_key_for_directory`** and **`.fold_session_summary`** helpers; `ClaudeAgentOptions` gains `session_store`, `session_store_flush` (`"batched"`/`"eager"`), and `load_timeout_ms`. `SessionStore` + `enable_file_checkpointing`, or `continue_conversation` without `list_sessions`, are rejected at connect with a clear error.
+
+### Changed
+- `Client#connect` now fully tears the client down (subprocess reaped, temp resume dir removed) when any part of connect fails — previously a failure while sending the initial prompt could leave a half-connected client behind. Matches the Python/TypeScript SDKs.
+- A negative `limit:` now returns `[]` consistently across every session reader (`list_sessions`, `get_session_messages`, and all store-backed counterparts) instead of raising `ArgumentError` from an internal `Array#first` on some paths.
+
+### Fixed
+- `fork_session` / `fork_session_via_store` now fall back to the documented `"Forked session (fork)"` title for sessions with no title and no extractable first prompt (previously wrote a literal `" (fork)"`).
+
+## [0.16.10] - 2026-06-04
+
+### Added
+- `ClaudeAgentOptions#strict_mcp_config` — forwarded as `--strict-mcp-config`. When `true`, the CLI uses **only** the MCP servers passed via `mcp_servers`, ignoring project `.mcp.json`, user/global settings, and plugin-provided servers, for a fully deterministic server set. Defaults to `false`. (Parity with [Python SDK #915](https://github.com/anthropics/claude-agent-sdk-python/pull/915))
+- `ClaudeAgentOptions#include_hook_events` — forwarded as `--include-hook-events`. When `true`, the CLI emits hook lifecycle events (PreToolUse, PostToolUse, Stop, etc.) into the message stream. The parser already maps these to `HookStartedMessage` / `HookProgressMessage` / `HookResponseMessage` (the CLI simply never emitted them without this flag). Defaults to `false`. (Parity with [Python SDK #917](https://github.com/anthropics/claude-agent-sdk-python/pull/917))
+- `SandboxNetworkConfig#denied_domains` (`deniedDomains`) and `#allow_mach_lookup` (`allowMachLookup`) — completes the sandbox network allowlist field set. `denied_domains` blocks domains even when matched by `allowed_domains`; `allow_mach_lookup` is a macOS-only list of XPC/Mach service names to allow (supports a trailing wildcard). Completes [Python SDK #893](https://github.com/anthropics/claude-agent-sdk-python/pull/893) — `denied_domains` and `allow_mach_lookup` were the last two fields the Ruby port had not yet landed.
+- **Orphaned-subprocess cleanup**: `SubprocessCLITransport` now tracks live CLI subprocesses in a class-level, mutex-guarded `Set` and registers an `at_exit` handler that sends `SIGTERM` to any still running when the parent Ruby process exits. This prevents leaked `claude` processes when callers crash or exit before reaching `#close`. The handler skips already-exited processes (`Process::Waiter#alive?`) and swallows errors so it never interrupts interpreter shutdown. (Parity with [Python SDK #916](https://github.com/anthropics/claude-agent-sdk-python/pull/916))
+
 ## [0.16.9] - 2026-05-25
 
 ### 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.16.9'
+gem 'claude-agent-sdk', '~> 0.17.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/sessions.md

@@ -99,3 +99,82 @@ ClaudeAgentSDK.query(
 ```
 
 `resume_session_at` requires `resume`; the SDK raises `ArgumentError` from `CommandBuilder` when this constraint is violated, matching the underlying CLI's validation but surfacing it synchronously in the caller's stack.
+
+## Mirroring to a `SessionStore`
+
+By default Claude Code writes session transcripts to local disk under
+`CLAUDE_CONFIG_DIR`. A **`SessionStore`** adapter mirrors that transcript to
+external storage (S3, Redis, Postgres, …) so sessions survive beyond the local
+machine and can be resumed elsewhere. The subprocess still writes locally; the
+adapter receives a secondary copy and resume can rehydrate from it.
+
+Set `session_store:` on the options — it works on **both** `ClaudeAgentSDK.query`
+and `ClaudeAgentSDK::Client`:
+
+```ruby
+store = ClaudeAgentSDK::InMemorySessionStore.new # or your own adapter
+
+ClaudeAgentSDK.query(
+  prompt: 'Hello!',
+  options: ClaudeAgentSDK::ClaudeAgentOptions.new(session_store: store)
+) { |message| } # transcript_mirror frames are appended to the store as they stream
+
+# Resume later from the store (no local JSONL needed):
+ClaudeAgentSDK.query(
+  prompt: 'Continue',
+  options: ClaudeAgentSDK::ClaudeAgentOptions.new(session_store: store, resume: 'previous-session-id')
+) { |message| }
+```
+
+Relevant options: `session_store`, `session_store_flush` (`"batched"` default, or
+`"eager"` to flush after every frame), and `load_timeout_ms` (per store call
+during resume materialization, default `60_000`).
+
+> **Store-backed resume runs against a bare temp `CLAUDE_CONFIG_DIR`.** Only the
+> transcript plus `.credentials.json` (redacted) and `.claude.json` are
+> materialized into it — user-scope `settings.json` (hooks, `permissions`),
+> user `CLAUDE.md`, `agents/`, `skills/`, and `plugins/` from your real config
+> dir are **not** visible to the subprocess, so a store-backed resume can
+> behave differently from a plain `resume:` of the same session. Project-level
+> `.claude/*` still applies (it resolves from `cwd`), and hooks/options passed
+> programmatically via `ClaudeAgentOptions` are unaffected. This matches the
+> Python and TypeScript SDKs.
+
+### Implementing an adapter
+
+Subclass `ClaudeAgentSDK::SessionStore` (or duck-type it). Only `#append` and
+`#load` are required; `#list_sessions`, `#delete`, `#list_subkeys`, and
+`#list_session_summaries` are optional and probed via `SessionStore.implements?`.
+Validate your adapter with the shipped, framework-agnostic conformance harness:
+
+```ruby
+require 'claude_agent_sdk/testing/session_store_conformance'
+ClaudeAgentSDK::Testing.run_session_store_conformance(-> { MyStore.new(...) })
+```
+
+Copy-in reference adapters for **S3, Redis, and Postgres** live in
+[`examples/session_stores/`](../examples/session_stores/README.md), each with a
+production checklist.
+
+### Store-backed helpers
+
+The browsing/mutation helpers above have store-backed counterparts that take a
+`session_store:` and operate on the store instead of local disk:
+
+- Reads: `list_sessions_from_store`, `get_session_info_from_store`,
+  `get_session_messages_from_store`, `list_subagents_from_store`,
+  `get_subagent_messages_from_store`. Unlike the disk readers (where a nil
+  `directory:` searches every project directory), the store helpers key every
+  read by `project_key` and a nil `directory:` defaults to the **current
+  working directory** — the `SessionStore` interface has no way to enumerate
+  project keys (parity with the Python SDK).
+- Mutations: `rename_session_via_store`, `tag_session_via_store`,
+  `delete_session_via_store` (a no-op on append-only stores without `#delete`),
+  `fork_session_via_store`.
+- Migration: `import_session_to_store` replays a local on-disk session (and its
+  subagents) into a store.
+
+```ruby
+ClaudeAgentSDK.rename_session_via_store(session_store: store, session_id: '550e8400-...', title: 'Renamed')
+forked = ClaudeAgentSDK.fork_session_via_store(session_store: store, session_id: '550e8400-...')
+```

data/lib/claude_agent_sdk/command_builder.rb

@@ -277,6 +277,10 @@ module ClaudeAgentSDK
       cmd.push("--include-partial-messages") if @options.include_partial_messages
       cmd.push("--fork-session") if @options.fork_session
       cmd.push("--bare") if @options.bare
+      cmd.push("--include-hook-events") if @options.include_hook_events
+      cmd.push("--strict-mcp-config") if @options.strict_mcp_config
+      # When a session_store is set, ask the CLI to emit transcript_mirror frames.
+      cmd.push("--session-mirror") if @options.session_store
     end
 
     def append_plugins(cmd)

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -28,15 +28,27 @@ module ClaudeAgentSDK
   # so SDK loops yielding user callbacks must keep loop control outside the
   # invoked block (see `Client#receive_response`).
   module FiberBoundary
+    # Raised by .invoke when a timeout-bounded call exceeds its allotted time.
+    # The worker thread is abandoned (cancellation is best-effort; the
+    # in-flight call may still complete).
+    class JoinTimeout < StandardError; end
+
     module_function
 
     # Run the given block on a plain thread when a Fiber scheduler is active.
     # Returns the block's value. Exceptions propagate to the caller.
-    def invoke(&block)
-      return block.call unless Fiber.scheduler
+    #
+    # With +timeout+ (seconds) the thread hop happens unconditionally — even
+    # without a scheduler — so the bound is enforced in plain synchronous code
+    # too; JoinTimeout is raised when it expires.
+    def invoke(timeout: nil, &block)
+      return block.call if timeout.nil? && !Fiber.scheduler
 
       thread = Thread.new(&block)
       thread.report_on_exception = false
+      return thread.value if timeout.nil?
+      raise JoinTimeout, "timed out after #{timeout}s" unless thread.join(timeout)
+
       thread.value
     end
   end

data/lib/claude_agent_sdk/message_parser.rb

@@ -87,6 +87,7 @@ module ClaudeAgentSDK
       'status' => StatusMessage,
       'api_retry' => APIRetryMessage,
       'local_command_output' => LocalCommandOutputMessage,
+      'mirror_error' => MirrorErrorMessage,
       'hook_started' => HookStartedMessage,
       'hook_progress' => HookProgressMessage,
       'hook_response' => HookResponseMessage,

data/lib/claude_agent_sdk/query.rb

@@ -56,6 +56,7 @@ module ClaudeAgentSDK
       @initialized = false
       @closed = false
       @initialization_result = nil
+      @transcript_mirror_batcher = nil
     end
 
     # Initialize control protocol if in streaming mode
@@ -150,6 +151,28 @@ module ClaudeAgentSDK
       @task = parent.async { read_messages }
     end
 
+    # Install the transcript-mirror batcher fed by `transcript_mirror` frames
+    # (Client mode with a session_store). nil disables mirroring.
+    def set_transcript_mirror_batcher(batcher)
+      @transcript_mirror_batcher = batcher
+    end
+
+    # Synthesize a `mirror_error` system message and put it on the SDK message
+    # stream so consumers learn a mirror batch was dropped after exhausting
+    # retries. Non-blocking: the message queue is unbounded, so unlike the
+    # Python SDK there is no buffer-full drop path.
+    def report_mirror_error(key, error)
+      session_id = key && (key['session_id'] || key[:session_id])
+      @message_queue.enqueue(
+        type: 'system',
+        subtype: 'mirror_error',
+        error: error,
+        key: key,
+        uuid: SecureRandom.uuid,
+        session_id: session_id || ''
+      )
+    end
+
     private
 
     def control_request_timeout_seconds
@@ -200,10 +223,20 @@ module ClaudeAgentSDK
           task = request_id ? @inflight_control_request_tasks[request_id] : nil
           task&.stop
           next
+        when 'transcript_mirror'
+          # session_store mirror frame — fed to the batcher, never surfaced to
+          # consumers. camelCase on the wire; transport symbolizes keys.
+          @transcript_mirror_batcher&.enqueue(message[:filePath] || message[:file_path], message[:entries] || [])
+          next
         else
-          if message[:type] == 'result' && !@first_result_received
-            @first_result_received = true
-            @first_result_condition.signal
+          if message[:type] == 'result'
+            # Flush the mirror before signaling/yielding the result so a
+            # consumer observing the result sees an up-to-date store for the turn.
+            flush_transcript_mirror
+            unless @first_result_received
+              @first_result_received = true
+              @first_result_condition.signal
+            end
           end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
@@ -232,12 +265,30 @@ module ClaudeAgentSDK
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: e })
     ensure
-      unless @first_result_received
-        @first_result_received = true
-        @first_result_condition.signal
+      # Catch entries from a turn that ended without a `result` (early EOF /
+      # transport error) so they aren't dropped. The flush can suspend (lock
+      # acquire / thread join), so Async::Stop delivered mid-flush would skip
+      # the rest of this block — the nested ensure guarantees the signal and
+      # the end sentinel (which have no suspension points) are still delivered,
+      # mirroring the Python port's shielded flush + send_nowait sentinel.
+      begin
+        flush_transcript_mirror
+      ensure
+        unless @first_result_received
+          @first_result_received = true
+          @first_result_condition.signal
+        end
+        # Always signal end of stream
+        @message_queue.enqueue({ type: 'end' })
       end
-      # Always signal end of stream
-      @message_queue.enqueue({ type: 'end' })
+    end
+
+    # Flush the transcript-mirror batcher, swallowing errors — a mirror failure
+    # must never propagate into the read loop or its teardown.
+    def flush_transcript_mirror
+      @transcript_mirror_batcher&.flush
+    rescue StandardError => e
+      warn "Claude SDK: transcript mirror flush failed: #{e.message}"
     end
 
     def handle_control_response(message)
@@ -976,6 +1027,9 @@ module ClaudeAgentSDK
     # Close the query and transport
     def close
       @closed = true
+      # Final mirror flush BEFORE stopping the read task, so the last turn's
+      # entries reach the store. #close on the batcher never raises.
+      @transcript_mirror_batcher&.close
       @task&.stop
       @transport.close
     end