claude-agent-sdk 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 408fe2ed3f2f1f00866e3cef0b1795e67dc50dafd3292fc016985f62c10f1b6e
-  data.tar.gz: 045b04fee0681072fe7e99c81ab7a99d51d2eec362baf282a45c8d825cc38135
+  metadata.gz: b739ecaa08f1ddc9bc97ffdf639deca97a69da0251ec7b4ec975c7994c76c4b7
+  data.tar.gz: c85fe94b25b9b18c7de7d842cdeef7d0059c40cf829f33a963a4c6a215b4f999
 SHA512:
-  metadata.gz: 91b04e46d137103527e3af91d089acc01be96b69a8b0e6902eecb603654567ee826c8284ac0f9b797f180af64220ecfe0d71c3ab6f5e755e03525d596fcff85e
-  data.tar.gz: fb7e3d0a535522e98ed3c7a0180f1ac35ca5057a29dfdb3429b07cd896375672c0c94e114d92809325680f599ca39d8dee2f7fc3a658a73fabd744cf4a987946
+  metadata.gz: 7c1e37466bb844a9bcb4be7206881051e097e45181b64554f1e1299602a00f0ad88f1ffcefd73796e118715595bcef83cfd8e63138e2f537e2b6312428767e2c
+  data.tar.gz: daa2ba1268fdf355b426fec710b28254eaa4db61ff45017fe444f05b1499986f13aa2b1273997a52f64c061ce84a6cd7efda897d977c5d753323511c05184399

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-07-03
+
+Final batch (Batch D) from the 2026-07-03 full-codebase audit, closing it out: tests/docs/examples plus the three recorded split-verdict findings (P1-P3). Minor because the conformance suite gained a contract (an adapter that passed 0.21.0 can now fail contract 16) and new API surface (`check_uuid_dedupe:`).
+
+### Fixed
+- OTel observer: the next turn's prompt is no longer dropped from the new trace after an interrupted turn or `/clear` (a superseding init with no ResultMessage) — prompts arriving while the current trace already has its input are buffered for the next trace instead of being latched out; a prompt queued mid-turn now labels its own trace too.
+- Disk session listings no longer misclassify a session as a sidechain from a nested `"isSidechain":true` inside a structured field: the first line is parsed and the top-level key checked (same as the store fold), with the substring heuristic kept only for window-truncated first lines.
+- SDK MCP servers: propertyless object schemas (`{ type: 'object', additionalProperties: ... }`, `oneOf`, accept-anything forms) now pass through intact instead of being mangled into nonsense parameter lists ("additionalProperties" advertised as a required string param).
+- `import_session_to_store` skips an unparseable trailing line with a warning (an ordinary interrupted-CLI artifact every read path already tolerates) instead of aborting mid-import with a raw `JSON::ParserError` and leaving a partial store import behind.
+- Redis reference adapter: the delete cascade now WATCHes the subkey set, so a concurrent eager-mode append can no longer orphan a freshly-created subagent list forever; both the Redis and Postgres reference adapters stamp mtimes through a monotonic guard (like S3) so a backward clock step can't misdirect `--continue`.
+- Redis example spec no longer FLUSHDBs whatever `SESSION_STORE_REDIS_URL` points at — it uses a random key prefix per run with prefix-scoped cleanup, like the Postgres spec.
+
+### Added
+- Conformance suite contract 16: `list_sessions` must return exactly one row per session under multiple appends (the naive one-row-per-append implementation previously passed every contract, then showed N duplicate sessions in pickers). Contract 4 now also asserts `append([])` cannot create a phantom key. New opt-in `check_uuid_dedupe:` flag asserts the advisory retried-batch uuid-dedupe recommendation.
+- `--continue` with a store that implements `list_session_summaries` skips sidechain candidates via the summary sidecar instead of downloading every candidate's full transcript.
+
+### Changed
+- `RUN_INTEGRATION=1` now actually runs the real-CLI integration suite (the old tautological placeholder suite is gone; `RUN_REAL_INTEGRATION` remains as an alias). The real suite still self-skips without a `claude` CLI or `ANTHROPIC_API_KEY`.
+- Packaged docs/README now link to examples and repo files via absolute GitHub URLs — the relative links were dead in installed gems and on rubydoc.info (examples/ and assets/ are not packaged).
+
 ## [0.21.0] - 2026-07-03
 
 Design-decision fix batch (Batch C) from the 2026-07-03 full-codebase audit (`AUDIT-2026-07-03.md`, PR #43), plus three teardown-race hardenings from its adversarial review. Minor (not patch) because three fixes change observable behavior for previously-broken flows: a missing settings file with sandbox no longer raises, a raising initial prompt stream no longer notifies observers, and teardown can now preserve (instead of delete) the materialized resume dir.

data/README.md

@@ -1,6 +1,6 @@
 # Claude Agent SDK for Ruby
 
-![Claude Agent SDK for Ruby banner](assets/claude-agent-sdk-ruby-banner.png)
+![Claude Agent SDK for Ruby banner](https://raw.githubusercontent.com/ya-luotao/claude-agent-sdk-ruby/main/assets/claude-agent-sdk-ruby-banner.png)
 
 [![Gem Version](https://badge.fury.io/rb/claude-agent-sdk.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/claude-agent-sdk)
 
@@ -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.21.0'
+gem 'claude-agent-sdk', '~> 0.22.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -144,7 +144,7 @@ ClaudeAgentSDK.query(prompt: stream) do |message|
 end
 ```
 
-See [examples/streaming_input_example.rb](examples/streaming_input_example.rb) and [examples/quick_start.rb](examples/quick_start.rb).
+See [examples/streaming_input_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/streaming_input_example.rb) and [examples/quick_start.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/quick_start.rb).
 
 ## `Client` — Bidirectional Sessions
 
@@ -220,49 +220,49 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 | Example | Description |
 |---------|-------------|
-| [quick_start.rb](examples/quick_start.rb) | Basic `query()` usage with options |
-| [client_example.rb](examples/client_example.rb) | Interactive Client usage |
-| [message_types_example.rb](examples/message_types_example.rb) | Handling all 24 SDK message types |
-| [streaming_input_example.rb](examples/streaming_input_example.rb) | Streaming input for multi-turn conversations |
-| [session_resumption_example.rb](examples/session_resumption_example.rb) | Multi-turn conversations with session persistence |
-| [structured_output_example.rb](examples/structured_output_example.rb) | JSON schema structured output |
-| [error_handling_example.rb](examples/error_handling_example.rb) | Error handling with `AssistantMessage.error` |
-| [bare_mode_example.rb](examples/bare_mode_example.rb) | Minimal startup with `bare: true` |
-| [sandbox_example.rb](examples/sandbox_example.rb) | Full sandbox settings (network, filesystem, violations) |
+| [quick_start.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/quick_start.rb) | Basic `query()` usage with options |
+| [client_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/client_example.rb) | Interactive Client usage |
+| [message_types_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/message_types_example.rb) | Handling all 24 SDK message types |
+| [streaming_input_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/streaming_input_example.rb) | Streaming input for multi-turn conversations |
+| [session_resumption_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb) | Multi-turn conversations with session persistence |
+| [structured_output_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb) | JSON schema structured output |
+| [error_handling_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb) | Error handling with `AssistantMessage.error` |
+| [bare_mode_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb) | Minimal startup with `bare: true` |
+| [sandbox_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb) | Full sandbox settings (network, filesystem, violations) |
 
 ### MCP Servers
 
 | Example | Description |
 |---------|-------------|
-| [mcp_calculator.rb](examples/mcp_calculator.rb) | Custom tools with SDK MCP servers |
-| [mcp_resources_prompts_example.rb](examples/mcp_resources_prompts_example.rb) | MCP resources and prompts |
-| [http_mcp_server_example.rb](examples/http_mcp_server_example.rb) | HTTP/SSE MCP server configuration |
+| [mcp_calculator.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) | Custom tools with SDK MCP servers |
+| [mcp_resources_prompts_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) | MCP resources and prompts |
+| [http_mcp_server_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb) | HTTP/SSE MCP server configuration |
 
 ### Hooks & Permissions
 
 | Example | Description |
 |---------|-------------|
-| [hooks_example.rb](examples/hooks_example.rb) | Using hooks to control tool execution |
-| [advanced_hooks_example.rb](examples/advanced_hooks_example.rb) | Typed hook inputs/outputs |
-| [lifecycle_hooks_example.rb](examples/lifecycle_hooks_example.rb) | All 27 hook events |
-| [permission_callback_example.rb](examples/permission_callback_example.rb) | Dynamic tool permission control |
+| [hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb) | Using hooks to control tool execution |
+| [advanced_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb) | Typed hook inputs/outputs |
+| [lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb) | All 27 hook events |
+| [permission_callback_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb) | Dynamic tool permission control |
 
 ### Advanced
 
 | Example | Description |
 |---------|-------------|
-| [budget_control_example.rb](examples/budget_control_example.rb) | Budget control with `max_budget_usd` |
-| [fallback_model_example.rb](examples/fallback_model_example.rb) | Fallback model configuration |
-| [extended_thinking_example.rb](examples/extended_thinking_example.rb) | Extended thinking |
-| [e2b_transport_example.rb](examples/e2b_transport_example.rb) | Custom transport running CLI in an E2B microVM |
+| [budget_control_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb) | Budget control with `max_budget_usd` |
+| [fallback_model_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb) | Fallback model configuration |
+| [extended_thinking_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/extended_thinking_example.rb) | Extended thinking |
+| [e2b_transport_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) | Custom transport running CLI in an E2B microVM |
 
 ### Observability & Rails
 
 | Example | Description |
 |---------|-------------|
-| [otel_langfuse_example.rb](examples/otel_langfuse_example.rb) | OpenTelemetry tracing with Langfuse backend |
-| [rails_actioncable_example.rb](examples/rails_actioncable_example.rb) | ActionCable streaming to frontend |
-| [rails_background_job_example.rb](examples/rails_background_job_example.rb) | Background jobs with session resumption |
+| [otel_langfuse_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) | OpenTelemetry tracing with Langfuse backend |
+| [rails_actioncable_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb) | ActionCable streaming to frontend |
+| [rails_background_job_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb) | Background jobs with session resumption |
 
 ## Available Tools
 

data/docs/client.md

@@ -76,7 +76,7 @@ client = ClaudeAgentSDK::Client.new(
 
 ### Reference: running `claude` inside an E2B sandbox
 
-[`examples/e2b_transport_example.rb`](../examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
+[`examples/e2b_transport_example.rb`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
 
 ```
 ClaudeAgentSDK::Client (host)

data/docs/configuration.md

@@ -35,7 +35,7 @@ ClaudeAgentSDK.query(prompt: "Create a profile for a software engineer", options
 end
 ```
 
-See [examples/structured_output_example.rb](../examples/structured_output_example.rb).
+See [examples/structured_output_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb).
 
 ## Thinking Configuration
 
@@ -91,7 +91,7 @@ ClaudeAgentSDK.query(prompt: "Explain recursion", options: options) do |message|
 end
 ```
 
-See [examples/budget_control_example.rb](../examples/budget_control_example.rb).
+See [examples/budget_control_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb).
 
 ## Fallback Model
 
@@ -102,7 +102,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
-See [examples/fallback_model_example.rb](../examples/fallback_model_example.rb).
+See [examples/fallback_model_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb).
 
 ## Beta Features
 
@@ -155,7 +155,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 )
 ```
 
-See [examples/sandbox_example.rb](../examples/sandbox_example.rb).
+See [examples/sandbox_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb).
 
 ## Bare Mode
 
@@ -186,7 +186,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 **What still works:** skills (via `/skill-name`), explicit `--add-dir` CLAUDE.md, `--settings`, `--mcp-config`, `--agents`, `--plugin-dir`, API key from `ANTHROPIC_API_KEY` env var.
 
-See [examples/bare_mode_example.rb](../examples/bare_mode_example.rb).
+See [examples/bare_mode_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb).
 
 ## File Checkpointing & Rewind
 

data/docs/errors.md

@@ -18,7 +18,7 @@ ClaudeAgentSDK.query(prompt: "Hello") do |message|
 end
 ```
 
-See [examples/error_handling_example.rb](../examples/error_handling_example.rb).
+See [examples/error_handling_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb).
 
 ## Exception Handling
 
@@ -92,4 +92,4 @@ end
 | `CLIJSONDecodeError` | JSON parsing issues |
 | `MessageParseError` | Message parsing issues |
 
-See [lib/claude_agent_sdk/errors.rb](../lib/claude_agent_sdk/errors.rb) for all error types.
+See [lib/claude_agent_sdk/errors.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/errors.rb) for all error types.

data/docs/hooks-and-permissions.md

@@ -19,7 +19,7 @@ All hook input objects include common fields like `session_id`, `transcript_path
 - `SubagentStart` → `SubagentStartHookInput` (`agent_id`, `agent_type`)
 - `PermissionRequest` → `PermissionRequestHookInput` (`tool_name`, `tool_input`, `permission_suggestions`)
 
-All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](../lib/claude_agent_sdk/types.rb) and [examples/lifecycle_hooks_example.rb](../examples/lifecycle_hooks_example.rb).
+All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
 ### Example: Blocking Dangerous Commands
 
@@ -67,7 +67,7 @@ Async do
 end.wait
 ```
 
-See [examples/hooks_example.rb](../examples/hooks_example.rb), [examples/advanced_hooks_example.rb](../examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](../examples/lifecycle_hooks_example.rb).
+See [examples/hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb), [examples/advanced_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
 
 ## Permission Callbacks
 
@@ -107,4 +107,4 @@ Async do
 end.wait
 ```
 
-See [examples/permission_callback_example.rb](../examples/permission_callback_example.rb).
+See [examples/permission_callback_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb).

data/docs/mcp-servers.md

@@ -150,4 +150,4 @@ server = ClaudeAgentSDK.create_sdk_mcp_server(
 )
 ```
 
-See [examples/mcp_calculator.rb](../examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](../examples/mcp_resources_prompts_example.rb) for complete examples.
+See [examples/mcp_calculator.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) for complete examples.

data/docs/observability.md

@@ -147,4 +147,4 @@ end
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [MyObserver.new])
 ```
 
-See [examples/otel_langfuse_example.rb](../examples/otel_langfuse_example.rb) for a complete multi-tool example.
+See [examples/otel_langfuse_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) for a complete multi-tool example.

data/docs/rails.md

@@ -193,7 +193,7 @@ end
 Then every `ClaudeAgentSDK.query` and `Client` session automatically gets traced — no per-call wiring needed. The lambda factory ensures each request gets its own observer with isolated span state, safe for concurrent Puma/Sidekiq workers.
 
 See:
-- [examples/rails_actioncable_example.rb](../examples/rails_actioncable_example.rb)
-- [examples/rails_background_job_example.rb](../examples/rails_background_job_example.rb)
-- [examples/session_resumption_example.rb](../examples/session_resumption_example.rb)
-- [examples/http_mcp_server_example.rb](../examples/http_mcp_server_example.rb)
+- [examples/rails_actioncable_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb)
+- [examples/rails_background_job_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb)
+- [examples/session_resumption_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb)
+- [examples/http_mcp_server_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb)

data/docs/sessions.md

@@ -172,7 +172,7 @@ 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
+[`examples/session_stores/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
 production checklist.
 
 ### Store-backed helpers

data/docs/types.md

@@ -1,6 +1,6 @@
 # Types Reference
 
-See [lib/claude_agent_sdk/types.rb](../lib/claude_agent_sdk/types.rb) for complete type definitions.
+See [lib/claude_agent_sdk/types.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) for complete type definitions.
 
 ## Message Types
 

data/lib/claude_agent_sdk/instrumentation/otel.rb

@@ -50,16 +50,32 @@ module ClaudeAgentSDK
         @root_span = nil
         @root_context = nil
         @tool_spans = {} # tool_use_id => span
-        @first_user_input = nil # capture first user prompt for trace input
+        @first_user_input = nil # first user prompt of the current trace
+        @pending_prompt = nil # prompt that belongs to the NEXT trace (see on_user_prompt)
         @last_assistant_text = nil # capture last assistant text for trace output
       end
 
       def on_user_prompt(prompt)
-        return if @first_user_input # only capture the first prompt
-
-        @first_user_input = prompt.to_s
-        # If root span already exists, set immediately; otherwise start_trace will apply it
-        @root_span&.set_attribute('input.value', truncate(@first_user_input)) unless @first_user_input.empty?
+        text = prompt.to_s
+        return if text.empty?
+
+        if @root_span.nil?
+          # Pre-init: buffered for the trace start_trace is about to open.
+          # First prompt wins as the trace input.
+          @first_user_input ||= text
+        elsif @first_user_input.nil?
+          # Open trace with no input yet (init arrived before the prompt).
+          @first_user_input = text
+          @root_span.set_attribute('input.value', truncate(text))
+        else
+          # The open trace already has its input, so this prompt belongs to
+          # the NEXT trace: either the current turn was interrupted (/clear —
+          # a superseding init follows with no ResultMessage) or the user
+          # queued the next turn mid-stream (its init follows the current
+          # ResultMessage). A first-prompt-forever latch here dropped these
+          # prompts from the new trace entirely.
+          @pending_prompt ||= text
+        end
       end
 
       def on_message(message)
@@ -96,6 +112,10 @@ module ClaudeAgentSDK
       def on_close
         finish_open_spans
         reset_session_buffers
+        # Unlike the per-trace buffers, the pending next-trace prompt survives
+        # end_trace/supersede resets by design — but the session is over now,
+        # and a reused observer must not leak it into the next session.
+        @pending_prompt = nil
       end
 
       private
@@ -112,6 +132,11 @@ module ClaudeAgentSDK
         superseding = !@root_span.nil?
         finish_open_spans
         reset_session_buffers if superseding
+        # A prompt that arrived while the previous trace already had its input
+        # was buffered for THIS trace; it wins over a younger post-end prompt
+        # because it came first chronologically.
+        @first_user_input = @pending_prompt if @pending_prompt
+        @pending_prompt = nil
 
         attrs = {
           # gen_ai semantic conventions (recognized by Langfuse, Datadog, etc.)

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -25,16 +25,23 @@ module ClaudeAgentSDK
   end
 
   # A prebuilt JSON Schema is detected by type == 'object' (String or Symbol)
-  # AND a Hash properties value. Deliberately stricter than Python's rule:
-  # Ruby's simple-schema idiom uses Symbols as type VALUES, so
+  # with properties either ABSENT or a Hash. Properties-present-but-not-Hash
+  # falls through to the simple idiom, which uses Symbols as type VALUES —
   # { type: :string, properties: :string } is a legal simple schema with
-  # params literally named type/properties.
+  # params literally named type/properties. Propertyless object schemas
+  # ({ type: 'object', additionalProperties: ... } / oneOf / empty-object
+  # accept-anything forms) previously fell into the simple branch and were
+  # mangled into nonsense parameter lists ("additionalProperties" as a
+  # required string param). A $ref-only schema without type: 'object' remains
+  # indistinguishable from a params hash — declare the type alongside $ref.
   def self.prebuilt_json_schema?(schema)
     return false unless schema.is_a?(Hash)
 
     type_val = schema[:type] || schema['type']
-    props_val = schema[:properties] || schema['properties']
-    (type_val.is_a?(String) || type_val.is_a?(Symbol)) && type_val.to_s == 'object' && props_val.is_a?(Hash)
+    return false unless (type_val.is_a?(String) || type_val.is_a?(Symbol)) && type_val.to_s == 'object'
+    return true unless schema.key?(:properties) || schema.key?('properties')
+
+    (schema[:properties] || schema['properties']).is_a?(Hash)
   end
 
   # Single source of truth for tool input schemas: prebuilt schemas are

data/lib/claude_agent_sdk/session_resume.rb

@@ -168,9 +168,15 @@ module ClaudeAgentSDK
       end
       return nil if sessions.nil? || sessions.empty?
 
+      sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s)
+
       sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
         sid = cand['session_id']
         next unless sid.is_a?(String) && sid.match?(Sessions::UUID_RE)
+        # Skip known sidechains without downloading their transcript: the
+        # newest keys are often sidechains, and full-loading each one made
+        # --continue O(sum of transcript sizes) instead of O(candidates).
+        next if sidechain_flags&.fetch(sid, false)
 
         loaded = load_candidate(store, project_key, sid, timeout_s)
         next if loaded.nil?
@@ -183,6 +189,26 @@ module ClaudeAgentSDK
       nil
     end
 
+    # session_id => true for sessions the summary sidecar marks as sidechains;
+    # nil when the store doesn't implement list_session_summaries or the call
+    # fails (callers then fall back to checking each full load). The per-load
+    # isSidechain check above stays even on the summary path: a missing or
+    # stale sidecar row costs one extra load, never a wrong resume.
+    def sidechain_flags_from_summaries(store, project_key, timeout_s)
+      return nil unless SessionStore.implements?(store, :list_session_summaries)
+
+      rows = with_timeout(timeout_s, 'SessionStore#list_session_summaries') do
+        store.list_session_summaries(project_key)
+      end
+      Array(rows).each_with_object({}) do |row, acc|
+        sid = row.is_a?(Hash) ? row['session_id'] : nil
+        acc[sid] = row.dig('data', 'is_sidechain') == true if sid
+      end
+    # NotImplementedError is a ScriptError that with_timeout does not wrap.
+    rescue StandardError, NotImplementedError
+      nil
+    end
+
     # Adapters contractually report mtime as an epoch-ms Numeric (the
     # conformance suite asserts it), but SQL timestamps naturally arrive as
     # ISO-8601 Strings through JSON. Unary minus on a String is String#-@

data/lib/claude_agent_sdk/sessions.rb

@@ -373,14 +373,26 @@ module ClaudeAgentSDK
       head, tail = read_head_tail(file_path, stat.size)
 
       # Check first line for sidechain
-      first_line = head.lines.first || ''
-      return nil if first_line.include?('"isSidechain":true') || first_line.include?('"isSidechain": true')
+      return nil if sidechain_first_line?(head.lines.first || '')
 
       build_session_info(file_path, head, tail, stat, project_path)
     rescue StandardError
       nil
     end
 
+    # Sidechain classification parses the first line and reads the top-level
+    # key — the same key the store fold reads (`entry['isSidechain'] == true`).
+    # The old raw substring scan also matched "isSidechain":true nested inside
+    # a structured field, hiding the session from disk listings only. A first
+    # line truncated by the read window can't be shape-checked and keeps the
+    # substring heuristic.
+    def sidechain_first_line?(line)
+      entry = JSON.parse(line)
+      entry.is_a?(Hash) && entry['isSidechain'] == true
+    rescue StandardError
+      line.include?('"isSidechain":true') || line.include?('"isSidechain": true')
+    end
+
     def read_head_tail(file_path, size)
       head = tail = nil
       File.open(file_path, 'rb') do |f|
@@ -974,11 +986,23 @@ module ClaudeAgentSDK
       # encoding: transcripts are UTF-8 regardless of locale; without it a
       # LANG=C process raises Encoding::InvalidByteSequenceError on the first
       # multibyte line, aborting the import mid-way (Python pins utf-8 here).
-      File.foreach(file_path, encoding: 'UTF-8') do |line|
+      File.foreach(file_path, encoding: 'UTF-8').with_index(1) do |line, lineno|
         line = line.chomp
         next if line.empty?
 
-        batch << JSON.parse(line)
+        begin
+          entry = JSON.parse(line)
+        rescue JSON::ParserError
+          # A truncated trailing line is an ordinary interrupted-CLI artifact;
+          # every read path tolerates it (parse_jsonl_entries skips bad
+          # lines), and raising here aborted mid-import, leaving a partial
+          # store import behind. Skip the line, but say so — import is an
+          # explicit user operation.
+          warn "Claude SDK: import_session_to_store skipped unparseable line #{lineno} of #{file_path}"
+          next
+        end
+
+        batch << entry
         nbytes += line.bytesize
         next unless batch.length >= batch_size || nbytes >= TranscriptMirrorBatcher::MAX_PENDING_BYTES
 

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -13,10 +13,13 @@ module ClaudeAgentSDK
 
     module_function
 
-    # Assert the 15 SessionStore behavioral contracts against an adapter.
+    # Assert the 16 SessionStore behavioral contracts against an adapter.
     #
     # Contracts 1-14 mirror the Python SDK's run_session_store_conformance.
-    # Contract 15 is a Ruby SDK extension locking empty-subpath delete
+    # Contract 16 (Ruby extension) locks one-row-per-session `list_sessions`
+    # under multiple appends — the naive one-row-per-append implementation
+    # passed every other contract and then showed N duplicate sessions in
+    # pickers. Contract 15 is a Ruby SDK extension locking empty-subpath delete
     # coherence ('' == no subpath, the same addressing append/load already
     # use in every implementation in both SDKs); it runs only for stores
     # implementing #delete, and skip_optional: %w[delete] excludes the
@@ -38,7 +41,15 @@ module ClaudeAgentSDK
     # @param skip_optional [Array<String>] optional method names to skip.
     #   Contracts for an optional method are also skipped automatically when the
     #   store does not override it.
-    def run_session_store_conformance(make_store, skip_optional: [])
+    # @param check_uuid_dedupe [Boolean] additionally assert the ADVISORY
+    #   uuid-dedupe recommendation: re-appending a batch that overlaps a prior
+    #   write (exactly what the mirror batcher's retry can produce) must not
+    #   duplicate entries sharing a uuid. The SessionStore contract phrases
+    #   this as a "should" and the shipped reference adapters deliberately
+    #   skip it (duplicates largely self-heal through last-wins summary folds,
+    #   though resumed transcripts can still show repeated turns), so this
+    #   defaults to off. Turn it on if your adapter dedupes.
+    def run_session_store_conformance(make_store, skip_optional: [], check_uuid_dedupe: false)
       skip_optional = skip_optional.map(&:to_s)
       invalid = skip_optional - OPTIONAL_METHODS
       raise ConformanceError, "unknown optional methods in skip_optional: #{invalid}" unless invalid.empty?
@@ -56,6 +67,7 @@ module ClaudeAgentSDK
       check_list_session_summaries(fresh, has_list_sessions, has_delete) if has_list_summaries
       check_delete(fresh, has_list_subkeys, has_list_sessions) if has_delete
       check_list_subkeys(fresh) if has_list_subkeys
+      check_uuid_dedupe_contract(fresh) if check_uuid_dedupe
       nil
     end
 
@@ -86,11 +98,21 @@ module ClaudeAgentSDK
                  entry('uuid' => 'm', 'n' => 3), entry('uuid' => 'b', 'n' => 4)],
                 'multiple appends must preserve call order')
 
-      # 4. append([]) is a no-op.
+      # 4. append([]) is a no-op — including on a never-written key, which
+      # must NOT come into existence (a phantom key surfaces as an empty
+      # session in listings; documented on InMemorySessionStore, previously
+      # never asserted).
       store = fresh.call
       store.append(key, [entry('uuid' => 'a', 'n' => 1)])
       store.append(key, [])
       assert_eq(store.load(key), [entry('uuid' => 'a', 'n' => 1)], 'append([]) must be a no-op')
+      phantom = { 'project_key' => key['project_key'], 'session_id' => 'phantom' }
+      store.append(phantom, [])
+      assert(store.load(phantom).nil?, 'append([]) to an unwritten key must not create it')
+      if has_list_sessions
+        listed = store.list_sessions(key['project_key']).map { |s| s['session_id'] }
+        assert(!listed.include?('phantom'), 'append([]) must not surface a phantom session in list_sessions')
+      end
 
       # 5. subpath keys are stored independently of main.
       store = fresh.call
@@ -134,6 +156,16 @@ module ClaudeAgentSDK
                    [entry('n' => 1)])
       assert_eq(store.list_sessions('proj').map { |s| s['session_id'] }, ['main'],
                 'list_sessions must exclude subagent subpaths')
+
+      # 16. one row per session regardless of how many appends built it. A
+      # one-row-per-append implementation passed every other contract (the
+      # multi-append guard existed only for list_session_summaries) and then
+      # showed N duplicate sessions in pickers.
+      store = fresh.call
+      multi = { 'project_key' => 'proj', 'session_id' => 'multi' }
+      3.times { |i| store.append(multi, [entry('uuid' => "u#{i}", 'n' => i)]) }
+      assert_eq(store.list_sessions('proj').map { |s| s['session_id'] }, ['multi'],
+                'list_sessions must return exactly one row per session after multiple appends')
     end
 
     # -- Optional: list_session_summaries ----------------------------------
@@ -259,6 +291,19 @@ module ClaudeAgentSDK
                 'list_subkeys of an unknown session must be empty')
     end
 
+    # -- Opt-in: uuid dedupe (advisory) --------------------------------------
+
+    # A retried mirror batch can overlap a prior write (timeout abandons the
+    # in-flight append, which may still land). Adapters that opt in promise
+    # load reflects each uuid once, in first-seen order.
+    def check_uuid_dedupe_contract(fresh)
+      store = fresh.call
+      store.append(key, [entry('uuid' => 'r1', 'n' => 1), entry('uuid' => 'r2', 'n' => 2)])
+      store.append(key, [entry('uuid' => 'r2', 'n' => 2), entry('uuid' => 'r3', 'n' => 3)]) # retry overlap
+      assert_eq(store.load(key).map { |e| e['uuid'] }, %w[r1 r2 r3],
+                'a retried batch overlapping a prior write must dedupe by entry uuid')
+    end
+
     # -- helpers -----------------------------------------------------------
 
     def key
@@ -303,7 +348,7 @@ module ClaudeAgentSDK
     end
 
     private_class_method :check_append_and_load, :check_list_sessions, :check_list_session_summaries,
-                         :check_delete, :check_list_subkeys, :key, :entry, :epoch_ms?, :optional?,
-                         :summaries_by_id, :assert, :assert_eq
+                         :check_delete, :check_list_subkeys, :check_uuid_dedupe_contract, :key, :entry,
+                         :epoch_ms?, :optional?, :summaries_by_id, :assert, :assert_eq
   end
 end

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Community Contributors