claude-agent-sdk 0.16.10 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebf4d55c080946d0311e12f6afb60f595da80945b19579aa84f7d58536e84792
-  data.tar.gz: 1e9dc70ab01a74b4326ce6d1bf375162e5f3cc1ab5a7ac6102ef78b5635a2552
+  metadata.gz: abd1a08c12369ca6417cc28946a153f2f641ba38e1770026ff53ae36465da34c
+  data.tar.gz: c1a35168f601b9bf8f6680cf66565c6f06f26f0c4817d2e5a8afbe2923b0935d
 SHA512:
-  metadata.gz: 2a14aef3b12d83964e8487f56d80d2c35ab7ebab39255272e9789ee132aa73cf99dc5f31e6082ffc38c65c8cc2a519e4a4290944fbd00db83df6798cfcdaee34
-  data.tar.gz: 4d1c7552f077549723955c06fb357cdff4ee9b9f0bd0402de5471539679be4fab6639b42b269dba66c46a148b27af69e6f5d33c4d43484be38dd3ac47268146a
+  metadata.gz: 8fe246f00316a5d6d704e30d4a6df1d732be3d494d47fc222fe44738d7fc17914fd281a36b6fdf5200ddf69e7a8f2b4f6d471ec48799d0005375097a0d535ef8
+  data.tar.gz: 82cb35a8b05262b407014fd704eef12ac00f13bbb15f428c40e402b4fc6eb9576fd61b6f328bc4b00dc356365e2a16c18f6e5f97156877c0f7f4c23b499f8e96

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-06-10
+
+### Added
+- **Pluggable `SessionStore` adapter subsystem** — mirror Claude Code session transcripts to external storage (S3/Redis/Postgres/…) and resume from it, at parity with the Python SDK (#837 and follow-ups) and TypeScript SDK. The subprocess still writes to local disk; the adapter receives a secondary copy.
+  - **`SessionStore`** base class (6-method contract: `append`/`load` required; `list_sessions`/`list_session_summaries`/`delete`/`list_subkeys` optional, probed via `SessionStore.implements?` so duck-typed adapters need not subclass) and **`InMemorySessionStore`** reference implementation. All keys/entries cross the boundary as Hashes with **string keys** (JSON-round-trip safe for JSONB/Redis backends).
+  - **`ClaudeAgentSDK::Testing.run_session_store_conformance(make_store)`** — a 15-contract behavioral test suite for adapter authors (shipped in the gem, framework-agnostic; raises `ConformanceError` on violation).
+  - **Live mirroring** (on both `ClaudeAgentSDK.query` and `ClaudeAgentSDK::Client`): setting `ClaudeAgentOptions#session_store` emits `--session-mirror`; a `TranscriptMirrorBatcher` coalesces the CLI's `transcript_mirror` frames per file and flushes to `SessionStore#append` on each `result` (or 500-entry / 1 MiB overflow). `session_store_flush: "eager"` flushes after every frame. Append ordering is preserved across concurrent flushes (fiber-aware `Async::Semaphore`); the user store call runs on a `FiberBoundary` thread bounded by a fixed 60 s send timeout (`TranscriptMirrorBatcher::SEND_TIMEOUT_SECONDS`; `load_timeout_ms` bounds resume-materialization store calls instead); failures retry (3 attempts, 0.2/0.8 s backoff) then surface as a **`MirrorErrorMessage`** on the message stream. A failing store never disrupts the session (the local transcript is already durable).
+  - **Resume from store** (both entry points): pairing `session_store` with `resume`/`continue_conversation` materializes the session (and its subagent transcripts) from the store into a temp `CLAUDE_CONFIG_DIR` before spawn, repoints the subprocess at it, and cleans it up after the subprocess exits (on disconnect, one-shot teardown, **and** reactor cancellation). Store-supplied subagent subpaths are validated against path traversal; copied `.credentials.json` has its single-use `refreshToken` redacted; macOS Keychain credentials are bridged when needed.
+  - **Store-backed reads** (counterparts to the local readers): `ClaudeAgentSDK.list_sessions_from_store` (summary fast-path + gap-fill + pagination; a single failing row degrades to an empty summary rather than aborting the listing), `.get_session_info_from_store`, `.get_session_messages_from_store`, `.list_subagents_from_store`, `.get_subagent_messages_from_store`.
+  - **Store-backed mutations** (counterparts to the local mutators): `ClaudeAgentSDK.rename_session_via_store`, `.tag_session_via_store`, `.delete_session_via_store` (a no-op on WORM/append-only stores that don't implement `#delete`), and `.fork_session_via_store` (the UUID-remap fork transform run directly over the loaded entries — no JSONL round-trip; the fallback title is derived from the source's `customTitle`/`aiTitle`/first prompt).
+  - **Reference adapters** under `examples/session_stores/` (S3, Redis, Postgres) — copy-in implementations, each validated against `run_session_store_conformance`. Backend client gems live in the optional `:examples` Bundler group so a default install stays dependency-free.
+  - **`ClaudeAgentSDK.import_session_to_store`** — replay a local on-disk session (and subagents) into a store for migration / mirror-gap backfill.
+  - **`ClaudeAgentSDK.project_key_for_directory`** and **`.fold_session_summary`** helpers; `ClaudeAgentOptions` gains `session_store`, `session_store_flush` (`"batched"`/`"eager"`), and `load_timeout_ms`. `SessionStore` + `enable_file_checkpointing`, or `continue_conversation` without `list_sessions`, are rejected at connect with a clear error.
+
+### Changed
+- `Client#connect` now fully tears the client down (subprocess reaped, temp resume dir removed) when any part of connect fails — previously a failure while sending the initial prompt could leave a half-connected client behind. Matches the Python/TypeScript SDKs.
+- A negative `limit:` now returns `[]` consistently across every session reader (`list_sessions`, `get_session_messages`, and all store-backed counterparts) instead of raising `ArgumentError` from an internal `Array#first` on some paths.
+
+### Fixed
+- `fork_session` / `fork_session_via_store` now fall back to the documented `"Forked session (fork)"` title for sessions with no title and no extractable first prompt (previously wrote a literal `" (fork)"`).
+
 ## [0.16.10] - 2026-06-04
 
 ### Added

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.16.10'
+gem 'claude-agent-sdk', '~> 0.17.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/sessions.md

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

data/lib/claude_agent_sdk/command_builder.rb

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

data/lib/claude_agent_sdk/fiber_boundary.rb

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

data/lib/claude_agent_sdk/message_parser.rb

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

data/lib/claude_agent_sdk/query.rb

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

data/lib/claude_agent_sdk/session_mutations.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'securerandom'
 require 'fileutils'
 require_relative 'sessions'
+require_relative 'session_store'
 
 module ClaudeAgentSDK
   # Session mutation functions: rename, tag, delete, and fork sessions.
@@ -114,7 +115,7 @@ module ClaudeAgentSDK
     # @return [ForkSessionResult] Result containing the new session ID
     # @raise [ArgumentError] if session_id or up_to_message_id is invalid
     # @raise [Errno::ENOENT] if the session file cannot be found
-    def fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil) # rubocop:disable Metrics/MethodLength
+    def fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
 
       raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !up_to_message_id.match?(Sessions::UUID_RE)
@@ -127,60 +128,13 @@ module ClaudeAgentSDK
       raise ArgumentError, "Session #{session_id} has no messages to fork" if file_size.zero?
 
       transcript, content_replacements = parse_fork_transcript(file_path, session_id)
-      transcript.reject! { |e| e['isSidechain'] }
-      raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
-
-      if up_to_message_id
-        cutoff = transcript.index { |e| e['uuid'] == up_to_message_id }
-        raise ArgumentError, "Message #{up_to_message_id} not found in session #{session_id}" unless cutoff
-
-        transcript = transcript[0..cutoff]
-      end
-
-      # Build UUID mapping (including progress entries for parentUuid chain walk)
-      uuid_mapping = {}
-      transcript.each { |e| uuid_mapping[e['uuid']] = SecureRandom.uuid }
-
-      by_uuid = transcript.to_h { |e| [e['uuid'], e] }
-
-      # Filter out progress messages from written output
-      writable = transcript.reject { |e| e['type'] == 'progress' }
-      raise ArgumentError, "Session #{session_id} has no messages to fork" if writable.empty?
-
-      forked_session_id = SecureRandom.uuid
-      now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ')
-
-      lines = writable.each_with_index.map do |original, i|
-        build_forked_entry(original, i, writable.size, uuid_mapping, by_uuid,
-                           forked_session_id, session_id, now)
-      end
-
-      # Append content-replacement entry if any. The entry needs `uuid` and
-      # `timestamp` so a *second* fork of this forked session can re-ingest
-      # it — `parse_fork_transcript` gates content-replacement on the entry
-      # being a valid hash with a matching `sessionId`, and the CLI's own
-      # tools index entries by uuid. Matches Python's `_emit_fork_to_disk`.
-      if content_replacements && !content_replacements.empty?
-        lines << JSON.generate({
-                                 'type' => 'content-replacement',
-                                 'sessionId' => forked_session_id,
-                                 'replacements' => content_replacements,
-                                 'uuid' => SecureRandom.uuid,
-                                 'timestamp' => now
-                               })
-      end
-
-      # Derive title — only read head/tail chunks when we need to generate one
-      fork_title = title&.strip
-      fork_title = "#{derive_fork_title(file_path, file_size)} (fork)" if fork_title.nil? || fork_title.empty?
-
-      lines << JSON.generate({
-                               'type' => 'custom-title',
-                               'sessionId' => forked_session_id,
-                               'customTitle' => fork_title,
-                               'uuid' => SecureRandom.uuid,
-                               'timestamp' => now
-                             })
+      # The fork transform is shared with fork_session_via_store; the disk path
+      # derives the fallback title from the file's head/tail bytes (only when no
+      # explicit title is given).
+      forked_session_id, lines = build_fork_lines(
+        transcript, content_replacements, session_id, up_to_message_id, title,
+        -> { derive_fork_title(file_path, file_size) }
+      )
 
       fork_path = File.join(project_dir, "#{forked_session_id}.jsonl")
       io = nil
@@ -199,6 +153,104 @@ module ClaudeAgentSDK
       ForkSessionResult.new(session_id: forked_session_id)
     end
 
+    # ---- SessionStore-backed mutations (store counterparts to the disk ops) ----
+
+    # Rename a session by appending a custom-title entry to a SessionStore.
+    # Store-backed counterpart to rename_session. Unlike the disk variant, the
+    # appended entry carries a fresh uuid + ISO timestamp so adapters that dedupe
+    # by entry["uuid"] (per the SessionStore#append contract) treat it correctly.
+    #
+    # @raise [ArgumentError] if session_id is invalid or title is empty
+    def rename_session_via_store(session_store:, session_id:, title:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      stripped = title.strip
+      raise ArgumentError, 'title must be non-empty' if stripped.empty?
+
+      key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
+      session_store.append(key, [{
+                             'type' => 'custom-title',
+                             'customTitle' => stripped,
+                             'sessionId' => session_id,
+                             'uuid' => SecureRandom.uuid,
+                             'timestamp' => iso_now
+                           }])
+      nil
+    end
+
+    # Tag a session by appending a tag entry to a SessionStore. Store-backed
+    # counterpart to tag_session. Pass nil to clear the tag. Tags are
+    # Unicode-sanitized before storing.
+    #
+    # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+    def tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+
+      if tag
+        sanitized = sanitize_unicode(tag).strip
+        raise ArgumentError, 'tag must be non-empty (use nil to clear)' if sanitized.empty?
+
+        tag = sanitized
+      end
+
+      key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
+      session_store.append(key, [{
+                             'type' => 'tag',
+                             'tag' => tag || '',
+                             'sessionId' => session_id,
+                             'uuid' => SecureRandom.uuid,
+                             'timestamp' => iso_now
+                           }])
+      nil
+    end
+
+    # Delete a session from a SessionStore. Store-backed counterpart to
+    # delete_session. If the store does not implement #delete, deletion is a
+    # no-op (appropriate for WORM/append-only backends, per the SessionStore
+    # contract). Whether subagent subkeys are also removed depends on the
+    # store's delete({session_id}) cascade semantics (InMemorySessionStore
+    # cascades; custom stores may not).
+    #
+    # @raise [ArgumentError] if session_id is invalid
+    def delete_session_via_store(session_store:, session_id:, directory: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      return unless SessionStore.implements?(session_store, :delete)
+
+      key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
+      session_store.delete(key)
+      nil
+    end
+
+    # Fork a session into a new branch with fresh UUIDs via a SessionStore.
+    # Store-backed counterpart to fork_session. Runs the fork transform directly
+    # over the objects returned by store.load — no JSONL round-trip on disk. A
+    # storage-layer copy is NOT sufficient: the transform remaps every UUID,
+    # rewrites sessionId, and stamps forkedFrom, so the data must pass through
+    # this process once.
+    #
+    # @raise [ArgumentError] if session_id/up_to_message_id is invalid or the session has no messages
+    # @raise [Errno::ENOENT] if the source session is not found in the store
+    def fork_session_via_store(session_store:, session_id:, directory: nil, up_to_message_id: nil, title: nil)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !up_to_message_id.match?(Sessions::UUID_RE)
+
+      project_key = Sessions.project_key_for_directory(directory)
+      raw = session_store.load('project_key' => project_key, 'session_id' => session_id)
+      raise Errno::ENOENT, "Session #{session_id} not found" if raw.nil? || raw.empty?
+
+      transcript, content_replacements = partition_fork_entries(raw, session_id)
+      forked_session_id, lines = build_fork_lines(
+        transcript, content_replacements, session_id, up_to_message_id, title,
+        -> { derive_title_from_entries(raw) }
+      )
+
+      dst_key = { 'project_key' => project_key, 'session_id' => forked_session_id }
+      # build_fork_lines emits compact JSON strings; re-parse to objects so the
+      # store receives the same shape it would from the mirror path.
+      session_store.append(dst_key, lines.map { |line| JSON.parse(line) })
+      ForkSessionResult.new(session_id: forked_session_id)
+    end
+
     # -- Private helpers --
 
     # Locate the JSONL file for a session and return [file_path, project_dir].
@@ -286,9 +338,138 @@ module ClaudeAgentSDK
       [transcript, content_replacements]
     end
 
+    # Current UTC time as a millisecond-precision ISO-8601 'Z' string, matching
+    # the timestamp shape the CLI writes into transcripts.
+    def iso_now
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ')
+    end
+
+    # Core fork transform shared by the disk and SessionStore paths. Filters
+    # sidechains, applies the optional up_to_message_id slice (inclusive),
+    # remaps every UUID (keeping progress entries in the chain walk but out of
+    # the written output), rewrites sessionId/forkedFrom, and appends the
+    # content-replacement and custom-title trailers (each with a fresh uuid +
+    # timestamp). Returns [forked_session_id, lines] where each line is a
+    # compact JSON string with no trailing newline.
+    #
+    # +derive_title+ is a callable invoked ONLY when no explicit +title+ is
+    # given, so the disk path's head/tail byte scan and the store path's
+    # entry-object scan each run only when needed.
+    def build_fork_lines(transcript, content_replacements, session_id, up_to_message_id, title, derive_title) # rubocop:disable Metrics/MethodLength
+      transcript = transcript.reject { |e| e['isSidechain'] }
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
+
+      if up_to_message_id
+        cutoff = transcript.index { |e| e['uuid'] == up_to_message_id }
+        raise ArgumentError, "Message #{up_to_message_id} not found in session #{session_id}" unless cutoff
+
+        transcript = transcript[0..cutoff]
+      end
+
+      # Build UUID mapping (including progress entries for the parentUuid chain walk).
+      uuid_mapping = {}
+      transcript.each { |e| uuid_mapping[e['uuid']] = SecureRandom.uuid }
+      by_uuid = transcript.to_h { |e| [e['uuid'], e] }
+
+      # Filter progress messages out of the written output (UI-only chain links).
+      writable = transcript.reject { |e| e['type'] == 'progress' }
+      raise ArgumentError, "Session #{session_id} has no messages to fork" if writable.empty?
+
+      forked_session_id = SecureRandom.uuid
+      now = iso_now
+
+      lines = writable.each_with_index.map do |original, i|
+        build_forked_entry(original, i, writable.size, uuid_mapping, by_uuid,
+                           forked_session_id, session_id, now)
+      end
+
+      # Append content-replacement entry if any. The entry needs `uuid` and
+      # `timestamp` so a *second* fork of this forked session can re-ingest it,
+      # and so adapters that dedupe by uuid handle it correctly.
+      if content_replacements && !content_replacements.empty?
+        lines << JSON.generate({
+                                 'type' => 'content-replacement',
+                                 'sessionId' => forked_session_id,
+                                 'replacements' => content_replacements,
+                                 'uuid' => SecureRandom.uuid,
+                                 'timestamp' => now
+                               })
+      end
+
+      # Derive title: explicit > original customTitle > original aiTitle > first
+      # prompt, suffixed with " (fork)" when derived. listSessions reads the LAST
+      # custom-title from the tail, so this trailer is what surfaces.
+      fork_title = title&.strip
+      fork_title = "#{derive_title.call || 'Forked session'} (fork)" if fork_title.nil? || fork_title.empty?
+
+      lines << JSON.generate({
+                               'type' => 'custom-title',
+                               'sessionId' => forked_session_id,
+                               'customTitle' => fork_title,
+                               'uuid' => SecureRandom.uuid,
+                               'timestamp' => now
+                             })
+
+      [forked_session_id, lines]
+    end
+
+    # Partition already-parsed store entries into [transcript, content_replacements],
+    # mirroring parse_fork_transcript for the store path (which has no JSONL file
+    # to stream). Only TRANSCRIPT_TYPES entries with a string uuid form the body;
+    # content-replacement records whose sessionId matches the source are collected
+    # (concatenated across compaction rounds).
+    def partition_fork_entries(raw, source_session_id)
+      transcript = []
+      content_replacements = []
+      raw.each do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry_type = entry['type']
+        if TRANSCRIPT_TYPES.include?(entry_type) && entry['uuid'].is_a?(String)
+          transcript << entry
+        elsif entry_type == 'content-replacement' && entry['sessionId'] == source_session_id &&
+              entry['replacements'].is_a?(Array)
+          content_replacements.concat(entry['replacements'])
+        end
+      end
+      [transcript, content_replacements]
+    end
+
+    # Derive a fork title by scanning already-parsed store entries — the store
+    # path's analogue of derive_fork_title's head/tail byte scan. Last occurrence
+    # wins for both customTitle and aiTitle; customTitle beats aiTitle; the first
+    # user prompt is the final fallback. Returns nil when nothing is found (the
+    # caller supplies the "Forked session" default). This scans the RAW entries,
+    # not the partitioned transcript (which drops customTitle/aiTitle metadata) —
+    # the store half of #837's P0-1 fix.
+    def derive_title_from_entries(raw)
+      custom = nil
+      ai = nil
+      raw.each do |e|
+        next unless e.is_a?(Hash)
+
+        ct = e['customTitle']
+        custom = ct if ct.is_a?(String) && !ct.empty?
+        at = e['aiTitle']
+        ai = at if at.is_a?(String) && !at.empty?
+      end
+      return custom if custom
+      return ai if ai
+
+      # First-prompt fallback: re-serialize to a JSONL string and reuse the head
+      # extractor so skip-patterns/truncation match the disk path exactly.
+      # extract_first_prompt_from_head returns '' (truthy in Ruby!) when no
+      # prompt qualifies — normalize to nil so the caller's 'Forked session'
+      # default actually fires (Python appends `or None` here for this reason).
+      jsonl = "#{raw.map { |e| JSON.generate(e) }.join("\n")}\n"
+      title = Sessions.extract_first_prompt_from_head(jsonl)
+      title.nil? || title.empty? ? nil : title
+    end
+
     # Derive a fork title from the source file's head/tail chunks without
     # slurping the entire file. Matches the lookup order used for
-    # SDKSessionInfo.custom_title / ai_title / first_prompt.
+    # SDKSessionInfo.custom_title / ai_title / first_prompt. Returns nil when
+    # nothing is found (build_fork_lines supplies the "Forked session" default).
     def derive_fork_title(file_path, file_size)
       buf_size = [Sessions::LITE_READ_BUF_SIZE, file_size].min
       File.open(file_path, 'rb') do |f|
@@ -299,12 +480,15 @@ module ClaudeAgentSDK
                else
                  head
                end
-        Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
-          Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
-          Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
-          Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
-          Sessions.extract_first_prompt_from_head(head) ||
-          'Forked session'
+        title = Sessions.extract_json_string_field(tail, 'customTitle', last: true) ||
+                Sessions.extract_json_string_field(head, 'customTitle', last: true) ||
+                Sessions.extract_json_string_field(tail, 'aiTitle', last: true) ||
+                Sessions.extract_json_string_field(head, 'aiTitle', last: true) ||
+                Sessions.extract_first_prompt_from_head(head)
+        # extract_first_prompt_from_head returns '' (truthy in Ruby!) when no
+        # prompt qualifies — normalize to nil so the 'Forked session' default
+        # fires (Python appends `or None` here for the same reason).
+        title.nil? || title.empty? ? nil : title
       end
     end
 
@@ -449,6 +633,7 @@ module ClaudeAgentSDK
                          :find_in_directory, :try_project_dir, :find_in_all_projects,
                          :parse_fork_transcript, :derive_fork_title, :build_forked_entry, :resolve_parent_uuid,
                          :append_to_session, :append_to_session_in_directory,
-                         :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category
+                         :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category,
+                         :iso_now, :build_fork_lines, :partition_fork_entries, :derive_title_from_entries
   end
 end