v0.17.0

Added

• Pluggable SessionStore adapter subsystem — mirror Claude Code session transcripts to external storage (S3/Redis/Postgres/…) and resume from it, at parity with the Python and TypeScript SDKs. The subprocess still writes to local disk; the adapter receives a secondary copy.
  • SessionStore base class (append/load required; list_sessions/list_session_summaries/delete/list_subkeys optional, probed via SessionStore.implements? so duck-typed adapters need not subclass) and InMemorySessionStore for tests.
  • Live mirroring on both ClaudeAgentSDK.query and ClaudeAgentSDK::Client: a TranscriptMirrorBatcher coalesces the CLI's transcript_mirror frames and flushes to SessionStore#append per turn (or on 500-entry / 1 MiB overflow); session_store_flush: "eager" flushes every frame. Failures retry, then surface as a MirrorErrorMessage — a failing store never disrupts the session.
  • Resume from store: pair session_store with resume/continue_conversation — the session (and its subagent transcripts) is materialized into a temp CLAUDE_CONFIG_DIR before spawn and cleaned up afterwards. Store-supplied subpaths are validated against traversal; copied credentials have the single-use refreshToken redacted.
  • Store-backed reads & mutations: list_sessions_from_store, get_session_info_from_store, get_session_messages_from_store, list_subagents_from_store, get_subagent_messages_from_store, rename_session_via_store, tag_session_via_store, delete_session_via_store, fork_session_via_store.
  • ClaudeAgentSDK.import_session_to_store — replay a local on-disk session (and subagents) into a store for migration/backfill.
  • Conformance kit: ClaudeAgentSDK::Testing.run_session_store_conformance — a 15-contract behavioral suite for adapter authors, shipped in the gem.
  • Reference adapters under examples/session_stores/ (S3, Redis, Postgres) — copy-in implementations, each validated against the conformance kit. Backend client gems live in the optional :examples Bundler group, so a default install stays dependency-free.
  • New options: session_store, session_store_flush ("batched"/"eager"), load_timeout_ms.

Changed

• Client#connect now fully tears the client down (subprocess reaped, temp resume dir removed) when any part of connect fails — previously a failure while sending the initial prompt could leave a half-connected client behind. Matches the Python/TypeScript SDKs.
• A negative limit: now returns [] consistently across every session reader (list_sessions, get_session_messages, and all store-backed counterparts) instead of raising ArgumentError on some paths.

Fixed

• fork_session / fork_session_via_store now fall back to the documented "Forked session (fork)" title for sessions with no title and no extractable first prompt (previously wrote a literal " (fork)").

Usage

store = ClaudeAgentSDK::InMemorySessionStore.new # or your S3/Redis/Postgres adapter

# Mirror while streaming
ClaudeAgentSDK.query(
  prompt: 'Hello!',
  options: ClaudeAgentSDK::ClaudeAgentOptions.new(session_store: store)
) { |msg| }

# Resume later from the store — no local JSONL needed
ClaudeAgentSDK.query(
  prompt: 'Continue',
  options: ClaudeAgentSDK::ClaudeAgentOptions.new(session_store: store, resume: 'session-uuid')
) { |msg| }

See docs/sessions.md and the adapter production checklist.

What's changed

• #37 Port pluggable SessionStore subsystem (mirror + resume + read + import) — @ya-luotao

Full Changelog: v0.16.10...v0.17.0

---

gem install claude-agent-sdk -v 0.17.0