claude-agent-sdk 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35da7de1ea5624dce1116d0c031a6141549e1d554434f3636cf47f5bcc81ca70
-  data.tar.gz: f9093848753fc2b583aed232d30013c8f328e36c6a958dc44f7d30c6ff319ae8
+  metadata.gz: b739ecaa08f1ddc9bc97ffdf639deca97a69da0251ec7b4ec975c7994c76c4b7
+  data.tar.gz: c85fe94b25b9b18c7de7d842cdeef7d0059c40cf829f33a963a4c6a215b4f999
 SHA512:
-  metadata.gz: f73779c80dfced4d4600384853900a68d658db1dcb9a73813949c49bced1593641a8b68085d83d6127178a533cb5a6daf2d045ffdaac4f526fc8d21f24db3636
-  data.tar.gz: 8e1022e4c20937b7464f46636636d2d9c6c160dfce9937617d1b56c5fae1c0abce401e6d9795fe4b566d2c59ba6e628c6c8dbf6e090278743eeac54a9a8a8489
+  metadata.gz: 7c1e37466bb844a9bcb4be7206881051e097e45181b64554f1e1299602a00f0ad88f1ffcefd73796e118715595bcef83cfd8e63138e2f537e2b6312428767e2c
+  data.tar.gz: daa2ba1268fdf355b426fec710b28254eaa4db61ff45017fe444f05b1499986f13aa2b1273997a52f64c061ce84a6cd7efda897d977c5d753323511c05184399

data/CHANGELOG.md

@@ -7,6 +7,39 @@ 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.
+
+### Fixed
+- `Query#close` (and therefore `Client#disconnect`) is now safe to call from any thread. Calling it from a FiberBoundary worker — e.g. a tool handler, hook, or permission callback ending the session — crashed with `NoMethodError` (nil `Fiber.scheduler`) and left the read/child tasks running, hanging the enclosing reactor. A transient reactor-side watcher now serves closes marshaled from foreign threads with identical semantics; once the reactor is gone, close falls back to a direct (fiber-dead-safe) teardown. `close` is also idempotent now — concurrent or repeated closes no longer re-run teardown against half-torn-down state.
+- Eager-mode mirror failures during the last flush of a stream are reported before the `'end'` sentinel: the `MirrorErrorMessage` for an in-flight dropped batch could previously be enqueued after `'end'` and never delivered, violating the documented "failures surface as MirrorErrorMessage" guarantee.
+- Disk session listings no longer report tool-argument text as the session summary/title: the head/tail byte-scans for `summary`/`customTitle`/`aiTitle`/`lastPrompt` now verify each match against the top level of its containing JSONL line (the same keys the SessionStore fold reads), so keys nested inside tool_use inputs (subagent/teammate tool arguments) are ignored. Lines truncated at the 64KB window edge keep the raw-scan value.
+- Resume-from-store teardown no longer deletes the only copy of turns the mirror failed to persist: when the batcher dropped batches (tracked via `TranscriptMirrorBatcher#batches_dropped?` / `Query#mirror_batches_dropped?`, including drains cancelled mid-flight), the materialized temp `CLAUDE_CONFIG_DIR` is preserved — credential copies scrubbed, transcripts kept, warning with the path — instead of removed.
+- A missing settings file with `sandbox` set now warns and continues with sandbox-only settings (Python parity) instead of raising `CLIConnectionError`.
+- `Client#connect` no longer fires observer `on_error` for a raising initial Enumerator prompt: input-stream errors are swallowed-with-warn (documented `Observer#on_error` contract, `query()` and Python parity). Notifying them also marked still-live OTel traces as failed.
+- Postgres reference adapter (`examples/session_stores/postgres_session_store.rb`): all DB round-trips now serialize through an internal mutex — mirror appends run on fresh worker threads and can overlap after a send-timeout abandon, which pg's single-connection thread rules forbid. The "a single PG::Connection suffices" concurrency guidance was wrong and has been rewritten.
+
 ## [0.20.0] - 2026-07-03
 
 Behavioral fix batch (Batch B) from the 2026-07-03 full-codebase audit (`AUDIT-2026-07-03.md`, PR #42). Every fix aligns code with a documented contract or Python SDK behavior and changes behavior only for inputs that previously produced wrong results, hangs, or crashes. Minor (not patch) because two fixes raise where the SDK previously reported success: a signal-killed CLI now raises `ProcessError`, and assistant messages without `message.model` now raise `MessageParseError`.

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.20.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

@@ -152,6 +152,12 @@ during resume materialization, default `60_000`).
 > `.claude/*` still applies (it resolves from `cwd`), and hooks/options passed
 > programmatically via `ClaudeAgentOptions` are unaffected. This matches the
 > Python and TypeScript SDKs.
+>
+> The temp dir is deleted at disconnect — **unless the mirror dropped batches**
+> (adapter failures that exhausted retries, surfaced as `MirrorErrorMessage`):
+> the store copy is then incomplete and the temp dir holds the only copy of the
+> dropped turns, so the SDK scrubs the credential copies, keeps the transcripts,
+> and warns with the preserved path so you can import them into the store.
 
 ### Implementing an adapter
 
@@ -166,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/command_builder.rb

@@ -376,7 +376,14 @@ module ClaudeAgentSDK
     end
 
     def load_settings_file(path)
-      raise CLIConnectionError, "Settings file not found: #{path}" unless File.file?(path)
+      # Missing file: warn and continue with sandbox-only settings (Python
+      # parity: logger.warning("Settings file not found: ...") and an empty
+      # settings object). Raising here turned a misconfiguration the CLI
+      # tolerates into a hard connect failure.
+      unless File.file?(path)
+        warn "Claude SDK: Settings file not found: #{path}"
+        return {}
+      end
 
       JSON.parse(File.read(path))
     end

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/query.rb

@@ -77,6 +77,16 @@ module ClaudeAgentSDK
       @closed = false
       @initialization_result = nil
       @transcript_mirror_batcher = nil
+
+      # Cross-thread close marshaling (see #close). Thread::Queue is the one
+      # primitive that is both fiber-scheduler-aware on the reactor side and
+      # thread-safe on the caller side (push -> scheduler#unblock).
+      @close_requests = ::Thread::Queue.new
+      @close_watcher = nil
+      @owning_scheduler = nil
+      # First-caller-wins guard for close_now (see there).
+      @close_mutex = Mutex.new
+      @close_started = false
     end
 
     # Initialize control protocol if in streaming mode
@@ -178,7 +188,24 @@ module ClaudeAgentSDK
       parent = Async::Task.current?
       raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
 
+      @owning_scheduler = Fiber.scheduler
       @task = parent.async { read_messages }
+      # Reactor-side agent for #close calls arriving from foreign threads
+      # (FiberBoundary callbacks, plain user threads): Async::Task#stop needs
+      # the owning thread's Fiber.scheduler, so the off-thread caller hands the
+      # whole close over and waits. Transient: must never keep the reactor
+      # alive, and is stopped automatically when the parent task finishes.
+      # One-shot: after serving a close it is done; a reactor-side close wakes
+      # it via @close_requests.close (pop -> nil) so it exits without serving.
+      @close_watcher = parent.async(transient: true) do
+        if (reply = @close_requests.pop)
+          begin
+            close
+          ensure
+            reply << true
+          end
+        end
+      end
     end
 
     # Spawn a child task that is stopped by #close (mirrors the Python SDK's
@@ -206,6 +233,14 @@ module ClaudeAgentSDK
       @transcript_mirror_batcher = batcher
     end
 
+    # True when the mirror dropped at least one batch (store copy incomplete).
+    # Meaningful after #close, which runs the final flush. Consulted by the
+    # resume-from-store teardown to decide whether the materialized temp dir
+    # holds the only copy of some turns and must be preserved.
+    def mirror_batches_dropped?
+      !!@transcript_mirror_batcher&.batches_dropped?
+    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
@@ -1152,8 +1187,45 @@ module ClaudeAgentSDK
       end
     end
 
-    # Close the query and transport
+    # Close the query and transport.
+    #
+    # Callable from any thread. Async::Task#stop needs the reactor's
+    # Fiber.scheduler (per-thread), which foreign callers — FiberBoundary
+    # workers running a tool handler / hook that calls client.disconnect, or
+    # plain user threads — don't have; stopping from one raised NoMethodError
+    # and left the read/child tasks running. Such callers hand the close to
+    # the reactor-side watcher (spawned in #start) and wait for it to finish,
+    # so close semantics are identical regardless of the calling thread.
     def close
+      if @close_watcher&.alive? && !Fiber.scheduler.equal?(@owning_scheduler)
+        marshal_close_to_reactor
+      else
+        # Same scheduler (reactor-side caller, including the watcher itself),
+        # or no live watcher: when the reactor is gone its task fibers are
+        # dead, so stopping them no longer touches Fiber.scheduler.
+        close_now
+      end
+    end
+
+    private
+
+    def close_now
+      # First caller wins: a reactor-side close racing a watcher-served
+      # foreign close (or a repeated disconnect) must not re-run teardown
+      # against half-torn-down state — transport.close can suspend mid-reap,
+      # and a second pass would race it. Later callers return immediately;
+      # the SDK's outer teardown ensures (query() / Client#disconnect) close
+      # the transport independently, so nothing is left dangling even if the
+      # first pass failed partway.
+      first_caller = @close_mutex.synchronize do
+        if @close_started
+          false
+        else
+          @close_started = true
+        end
+      end
+      return unless first_caller
+
       @closed = true
       # Wake pending control-request waiters (same shape as the read-loop
       # rescue broadcast): close stops the read task with Async::Stop, which
@@ -1171,10 +1243,43 @@ module ClaudeAgentSDK
       # Stop tracked child tasks (e.g. stream_input) before the read task and
       # transport so a parked input stream can never keep the reactor alive
       # (mirrors Python close() cancelling _child_tasks).
-      @child_tasks.each(&:stop)
-      @child_tasks.clear
-      @task&.stop
+      begin
+        @child_tasks.each(&:stop)
+        @child_tasks.clear
+        @task&.stop
+      rescue NoMethodError, FiberError => e
+        # Schedulerless fallback close (the watcher died unserved) racing
+        # reactor teardown: a task fiber can still be unwinding, and stopping
+        # it needs the owning thread's Fiber.scheduler. The dying reactor
+        # stops its own tasks; the transport close below (plain IO + kill)
+        # still runs. On the reactor itself this is a real bug — re-raise.
+        raise unless Fiber.scheduler.nil?
+
+        warn "Claude SDK: skipped stopping tasks during off-reactor close: #{e.message}"
+      end
       @transport.close
+      # Release a still-parked close watcher: pop returns nil and it exits
+      # without serving. Any foreign-thread close arriving after this point
+      # falls back to a direct close (safe — the fibers are now dead).
+      @close_requests.close
+    end
+
+    # Hand the close to the reactor and wait for completion. Polls watcher
+    # liveness instead of waiting forever: if the reactor shuts down
+    # concurrently (the transient watcher is stopped without serving the
+    # request), no reply will ever arrive — fall back to a direct close,
+    # which is safe once the reactor's fibers are dead.
+    def marshal_close_to_reactor
+      reply = ::Thread::Queue.new
+      @close_requests << reply
+      loop do
+        return if reply.pop(timeout: 0.1)
+        break unless @close_watcher&.alive?
+      end
+      close_now
+    rescue ClosedQueueError
+      # The push raced a reactor-side close_now that closed @close_requests.
+      close_now
     end
   end
 end

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

@@ -28,6 +28,23 @@ module ClaudeAgentSDK
     def cleanup
       SessionResume.rmtree_with_retry(@config_dir)
     end
+
+    # Teardown when the transcript mirror dropped batches: the CLI's
+    # authoritative transcript lives in this temp dir, and the store copy is
+    # missing the dropped turns — deleting the dir would permanently lose
+    # them. Keep the transcripts (projects/), remove the redacted credential
+    # copies, and tell the user where the data is so they can import it into
+    # the store manually. Never raises.
+    def preserve_transcripts
+      ['.credentials.json', '.claude.json'].each do |name|
+        FileUtils.rm_f(File.join(@config_dir, name))
+      end
+      warn "Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. " \
+           "Preserving the session transcript under #{File.join(@config_dir, 'projects')} instead of " \
+           'deleting it — import it into your session store, then remove the directory.'
+    rescue StandardError => e
+      warn "Claude SDK: failed to scrub preserved transcript dir #{@config_dir}: #{e.message}"
+    end
   end
 
   # Materialize a SessionStore-backed resume into a temp CLAUDE_CONFIG_DIR.
@@ -151,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?
@@ -166,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

@@ -213,6 +213,65 @@ module ClaudeAgentSDK
       result
     end
 
+    # Byte-scan for `"key":"` like extract_json_string_field, but verify each
+    # match by JSON-parsing its containing line and reading the key at the TOP
+    # LEVEL of the entry. The raw scan also matches keys nested inside
+    # tool_use inputs (real transcripts carry unescaped `"summary":"..."` in
+    # subagent/teammate tool arguments), which made the disk path report
+    # tool-argument text as the session summary/title while the store fold —
+    # which reads only top-level keys — disagreed. A line that doesn't parse
+    # (truncated at the head/tail window edge) keeps the raw-scan value: its
+    # top-level shape can't be checked, and dropping it would regress the
+    # common case of a true entry cut by the 64KB window.
+    def extract_top_level_string_field(text, key, last: false)
+      positions = field_match_positions(text, key)
+      positions.reverse! if last
+      parsed_lines = {}
+      positions.each do |idx, value_start|
+        line_start = (text.rindex("\n", idx) || -1) + 1
+        entry = parsed_lines.fetch(line_start) do
+          parsed_lines[line_start] = parse_containing_line(text, line_start, idx)
+        end
+        if entry
+          value = entry[key]
+          return value if value.is_a?(String)
+
+          next # parseable line without a top-level string value: nested/false match
+        end
+        value = extract_json_string_value(text, value_start)
+        return unescape_json_string(value) if value
+      end
+      nil
+    end
+
+    # Match positions of both compact and spaced `"key":` patterns, sorted by
+    # position so first/last selection is by document order (the pattern-major
+    # order of extract_json_string_field is wrong when spacings mix).
+    def field_match_positions(text, key)
+      positions = []
+      ["\"#{key}\":\"", "\"#{key}\": \""].each do |pattern|
+        pos = 0
+        while (idx = text.index(pattern, pos))
+          value_start = idx + pattern.length
+          positions << [idx, value_start]
+          pos = value_start
+        end
+      end
+      positions.sort_by!(&:first)
+      positions
+    end
+
+    # Parse the JSONL line containing byte offset +idx+. Returns the entry
+    # Hash, {} for parseable non-Hash lines (a match inside one is nested by
+    # definition), or nil when the line doesn't parse (window truncation).
+    def parse_containing_line(text, line_start, idx)
+      line_end = text.index("\n", idx) || text.length
+      entry = JSON.parse(text[line_start...line_end])
+      entry.is_a?(Hash) ? entry : {}
+    rescue StandardError
+      nil
+    end
+
     # Extract string value starting at pos (handles escapes)
     def extract_json_string_value(text, start)
       pos = start
@@ -314,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|
@@ -341,15 +412,19 @@ module ClaudeAgentSDK
       # Head fallback covers short sessions where the title entry may not be in tail.
       # Each candidate passes through presence so a blank value (e.g. a
       # trailing title-clearing entry) falls through instead of short-circuiting.
-      custom_title = presence(extract_json_string_field(tail, 'customTitle', last: true)) ||
-                     presence(extract_json_string_field(head, 'customTitle', last: true)) ||
-                     presence(extract_json_string_field(tail, 'aiTitle', last: true)) ||
-                     presence(extract_json_string_field(head, 'aiTitle', last: true))
+      # Summary-chain fields use the top-level-verified scan: a raw byte scan
+      # also matches these keys nested inside tool_use inputs, reporting tool
+      # arguments as the session title/summary (and diverging from the store
+      # fold, which reads top-level keys only).
+      custom_title = presence(extract_top_level_string_field(tail, 'customTitle', last: true)) ||
+                     presence(extract_top_level_string_field(head, 'customTitle', last: true)) ||
+                     presence(extract_top_level_string_field(tail, 'aiTitle', last: true)) ||
+                     presence(extract_top_level_string_field(head, 'aiTitle', last: true))
       first_prompt = extract_first_prompt_from_head(head)
       # lastPrompt tail entry shows what the user was most recently doing.
       summary = custom_title ||
-                presence(extract_json_string_field(tail, 'lastPrompt', last: true)) ||
-                presence(extract_json_string_field(tail, 'summary', last: true)) ||
+                presence(extract_top_level_string_field(tail, 'lastPrompt', last: true)) ||
+                presence(extract_top_level_string_field(tail, 'summary', last: true)) ||
                 first_prompt
       return nil if summary.nil? || summary.strip.empty?
 
@@ -911,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/transcript_mirror_batcher.rb

@@ -55,12 +55,24 @@ module ClaudeAgentSDK
       @pending = []
       @pending_entries = 0
       @pending_bytes = 0
+      # Batches that exhausted retries (or could not be keyed) and never
+      # reached the store. Written only under @lock; read cross-thread by
+      # #batches_dropped? (a plain Integer read is safe under the GVL).
+      @dropped_batches = 0
       # Fiber-aware lock: the critical section blocks on SessionStore#append
       # (a thread hop), so a Thread::Mutex would deadlock the reactor. The
       # semaphore serializes drains so append ordering matches enqueue order.
       @lock = Async::Semaphore.new(1)
     end
 
+    # True when at least one batch of entries never reached the store — the
+    # mirror copy is incomplete. Consulted at teardown by the resume-from-store
+    # cleanup so the materialized temp dir (which then holds the only copy of
+    # the dropped turns) is preserved instead of deleted.
+    def batches_dropped?
+      @dropped_batches.positive?
+    end
+
     # Buffer a frame; schedule an eager background flush if thresholds are
     # exceeded. Synchronous and fire-and-forget.
     #
@@ -112,27 +124,47 @@ module ClaudeAgentSDK
       @pending_bytes = 0
 
       errors = []
-      @lock.acquire do
-        # Emptiness is checked INSIDE the lock (matching the Python batcher):
-        # an empty #flush/#close still serializes behind any in-flight or
-        # queued drain, so they are true barriers — at result-yield and at
-        # teardown the store really is up to date, and Query#close can't stop
-        # the read task while a detached batch is still being appended.
-        next if items.empty?
-
-        do_flush(items, errors)
-      rescue StandardError => e
-        # do_flush already guards each append; this guards any remaining path
-        # so the "never raises" contract holds against future regressions.
-        warn "Claude SDK: TranscriptMirrorBatcher drain failed: #{e.message}"
-      end
-
-      # Report errors after releasing the lock so a slow on_error callback can't
-      # block subsequent drains (which only need the lock for append ordering).
-      errors.each do |key, message|
-        @on_error.call(key, message)
-      rescue StandardError => e
-        warn "Claude SDK: TranscriptMirrorBatcher on_error callback raised: #{e.message}"
+      # Cancellation (Async::Stop — not a StandardError) delivered while
+      # waiting on the lock or inside the append's thread join loses the
+      # detached items without either rescue firing. Teardown would then read
+      # batches_dropped? as false and delete a materialized resume dir holding
+      # the only copy of these entries — count the batch as dropped unless the
+      # flush path ran to completion (do_flush counts its own failures).
+      accounted = items.empty?
+      begin
+        @lock.acquire do
+          # Emptiness is checked INSIDE the lock (matching the Python batcher):
+          # an empty #flush/#close still serializes behind any in-flight or
+          # queued drain, so they are true barriers — at result-yield and at
+          # teardown the store really is up to date, and Query#close can't stop
+          # the read task while a detached batch is still being appended.
+          next if items.empty?
+
+          begin
+            do_flush(items, errors)
+          rescue StandardError => e
+            # do_flush already guards each append; this guards any remaining path
+            # so the "never raises" contract holds against future regressions.
+            @dropped_batches += 1
+            warn "Claude SDK: TranscriptMirrorBatcher drain failed: #{e.message}"
+          end
+          accounted = true
+
+          # Report errors BEFORE releasing the lock: flush/close are barriers, so
+          # a caller observing flush completion must also observe the error
+          # report. Reporting after release let an in-flight eager drain enqueue
+          # its MirrorErrorMessage after the read loop's 'end' sentinel — past
+          # the point where consumers stop dequeuing, i.e. never delivered. The
+          # production on_error (Query#report_mirror_error) is a non-blocking
+          # queue push, so holding the lock across it costs nothing.
+          errors.each do |key, message|
+            @on_error.call(key, message)
+          rescue StandardError => e
+            warn "Claude SDK: TranscriptMirrorBatcher on_error callback raised: #{e.message}"
+          end
+        end
+      ensure
+        @dropped_batches += 1 unless accounted
       end
     end
 
@@ -149,6 +181,7 @@ module ClaudeAgentSDK
 
         key = SessionStores.file_path_to_session_key(file_path, @projects_dir)
         if key.nil?
+          @dropped_batches += 1
           warn "Claude SDK: [SessionStore] dropping mirror frame: filePath #{file_path} is not under " \
                "#{@projects_dir} -- subprocess CLAUDE_CONFIG_DIR likely differs from parent (custom env / container?)"
           next
@@ -180,8 +213,11 @@ module ClaudeAgentSDK
         end
       end
 
-      errors << [key, last_err.to_s] unless succeeded
-      warn "Claude SDK: TranscriptMirrorBatcher flush failed for #{file_path}: #{last_err}" unless succeeded
+      return if succeeded
+
+      @dropped_batches += 1
+      errors << [key, last_err.to_s]
+      warn "Claude SDK: TranscriptMirrorBatcher flush failed for #{file_path}: #{last_err}"
     end
 
     # Run SessionStore#append (user code) on a plain thread via FiberBoundary,

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -555,8 +555,13 @@ module ClaudeAgentSDK
         ensure
           # Remove the materialized resume temp dir (which holds a redacted
           # .credentials.json copy) AFTER the subprocess has exited, even when
-          # close itself raises.
-          materialized&.cleanup
+          # close itself raises — unless the mirror dropped batches: the store
+          # copy is then incomplete and the temp dir holds the only copy of
+          # the dropped turns, so it is preserved (scrubbed of credentials)
+          # with a warning instead of deleted.
+          if materialized
+            query_handler&.mirror_batches_dropped? ? materialized.preserve_transcripts : materialized.cleanup
+          end
         end
       end
     end.wait
@@ -909,6 +914,10 @@ module ClaudeAgentSDK
       # state, and removes the materialized temp dir (which holds a redacted
       # .credentials.json copy) — so disconnect can never leave the client
       # half-open or leak the temp dir. The original error still propagates.
+      # Keep a handle on the query handler past the nil-out below: whether the
+      # mirror dropped batches is only final AFTER #close ran its last flush,
+      # and the materialized-dir decision at the bottom needs to ask it.
+      query_handler = @query_handler
       begin
         @query_handler&.close
       ensure
@@ -918,9 +927,17 @@ module ClaudeAgentSDK
         ensure
           @transport = nil
           @connected = false
-          # Remove the materialized resume temp dir AFTER the subprocess exited.
+          # Remove the materialized resume temp dir AFTER the subprocess
+          # exited — unless the mirror dropped batches: the store copy is then
+          # incomplete and the temp dir holds the only copy of the dropped
+          # turns, so it is preserved (scrubbed of credentials) with a warning
+          # instead of deleted.
           if @materialized
-            @materialized.cleanup
+            if query_handler&.mirror_batches_dropped?
+              @materialized.preserve_transcripts
+            else
+              @materialized.cleanup
+            end
             @materialized = nil
           end
         end
@@ -997,22 +1014,13 @@ module ClaudeAgentSDK
         # yielding deadlocked connect — and serialized Hash messages with
         # to_s (Ruby inspect, not JSON). stream_input JSON-generates Hashes
         # and is tracked on the Query so close() stops it. Stream errors are
-        # notified to observers once, then swallowed-with-warn by
-        # stream_input (Python parity) — they no longer abort connect.
+        # swallowed-with-warn by stream_input (Python parity) — they don't
+        # abort connect, and observers are NOT notified (the documented
+        # Observer#on_error contract; notifying a swallowed error would mark
+        # a still-live OTel trace as failed). Same behavior as query()'s
+        # streaming path.
         observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers)
-        notifying = error_notifying_stream(observed)
-        @query_handler.spawn_task { @query_handler.stream_input(notifying) }
-      end
-    end
-
-    # Wrap a stream so a raising user enumerator fires on_error exactly once
-    # before stream_input's swallow-with-warn handling takes over.
-    def error_notifying_stream(stream)
-      Enumerator.new do |yielder|
-        stream.each { |message| yielder << message }
-      rescue StandardError => e
-        notify_error(e)
-        raise
+        @query_handler.spawn_task { @query_handler.stream_input(observed) }
       end
     end
 

metadata

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