claude_agent 0.7.9 → 0.7.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90d9094d4e4428fc7dfc1e452759403a92f2e4badf5d1ac5f2f90e950c511255
-  data.tar.gz: fd2a8407c794aa672a4b03a774a6573dac3682bc09b8fe666170b90f5bd9f79a
+  metadata.gz: d1029f92c20c52b0d86d2942e3bb681fe0b0810ee14e5c848dc3f918a60969bb
+  data.tar.gz: 13b11ee08fd011a9787a404b389c0c1290619eeec15abd4d7bde3885235daf61
 SHA512:
-  metadata.gz: ce7d705ebe01a38ad1ac86a8caeaabd700831e200e73f134c9adef507b6f7b695effece63ae902849ee408714c3ae576930012dbbefe2b05da403d0de8549317
-  data.tar.gz: 7f06c5b0b5ed5ad798442672ad8ca969a0fdefc414a4c273e86911df0e171d24d5a378b9a88117bd3c60092a6affb5219d06cc58dd0107245643b571e2236440
+  metadata.gz: c7a0c0d980c96d6ebb4875916b15a7a9c49d6e6f657021722b54794951c9cb5cabad0589b4a7120210390aa0a9b27d4238e902bf6d26e141489a667bac8c9efa
+  data.tar.gz: 72e41cc15471827325a75f67de90bef61fe0b42ebedd36dd5b88a6c942d5fcba51caafbb83005a6eea560baa2be73b4b38bc765026c58f287e1d802c61e09c57

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.10] - 2026-02-26
+
+### Added
+- `Session.find(id, dir:)` — find a past session by UUID, returns `Session` or `nil`
+- `Session.all` — list all past sessions as `Session` objects
+- `Session.where(dir:, limit:)` — query sessions with optional directory and limit filters
+- `Session#messages` — returns a chainable, `Enumerable` `SessionMessageRelation` for reading transcript messages
+- `SessionMessageRelation#where(limit:, offset:)` — paginate messages with immutable chaining
+- `ClaudeAgent.get_session_messages(session_id, dir:, limit:, offset:)` — read session transcripts from disk (TypeScript SDK v0.2.59 parity)
+- `SessionMessage` type — message from a session transcript with `type`, `uuid`, `session_id`, `message`
+- `SessionPaths` module — shared path infrastructure for session discovery (extracted from `ListSessions`)
+
+### Changed
+- Renamed `Session` (V2 multi-turn API) to `V2Session` to free the `Session` name for the finder API
+- `unstable_v2_create_session`, `unstable_v2_resume_session`, and `unstable_v2_prompt` now return `V2Session`
+
 ## [0.7.9] - 2026-02-25
 
 ### Added

data/README.md

@@ -1180,14 +1180,20 @@ client.disconnect
 
 ## Session Discovery
 
-List past Claude Code sessions from disk without spawning a CLI subprocess:
+Find and inspect past Claude Code sessions from disk without spawning a CLI subprocess.
+
+### Session.find / Session.all
 
 ```ruby
-# All sessions (most recent first)
-sessions = ClaudeAgent.list_sessions
+# Find a specific session by ID
+session = ClaudeAgent::Session.find("abc-123-def")
+session = ClaudeAgent::Session.find("abc-123-def", dir: "/my/project")
+
+# List all sessions (most recent first)
+sessions = ClaudeAgent::Session.all
 
-# Scoped to a project directory (includes git worktree siblings)
-sessions = ClaudeAgent.list_sessions(dir: "/path/to/project", limit: 10)
+# Filter by directory, limit results
+sessions = ClaudeAgent::Session.where(dir: "/path/to/project", limit: 10)
 
 sessions.each do |s|
   puts "#{s.summary} (#{s.git_branch || 'no branch'})"
@@ -1197,7 +1203,27 @@ sessions.each do |s|
 end
 ```
 
-Each session is a `SessionInfo` with these fields:
+### Reading Messages
+
+`Session#messages` returns a chainable, `Enumerable` relation:
+
+```ruby
+session = ClaudeAgent::Session.find("abc-123-def")
+
+# All messages
+session.messages.each { |m| puts "#{m.type}: #{m.uuid}" }
+
+# Paginated
+session.messages.where(limit: 10).map(&:uuid)
+session.messages.where(offset: 5, limit: 10).to_a
+
+# Enumerable methods work
+session.messages.first
+session.messages.count
+session.messages.select { |m| m.type == "assistant" }
+```
+
+### Session Fields
 
 | Field            | Type            | Description                                      |
 |------------------|-----------------|--------------------------------------------------|
@@ -1210,11 +1236,24 @@ Each session is a `SessionInfo` with these fields:
 | `git_branch`     | `String\|nil`   | Git branch the session was on                    |
 | `cwd`            | `String\|nil`   | Working directory of the session                 |
 
+### Functional API
+
+The lower-level functional API is also available:
+
+```ruby
+# List sessions (returns SessionInfo objects)
+infos = ClaudeAgent.list_sessions(dir: "/path/to/project", limit: 10)
+
+# Read messages directly
+messages = ClaudeAgent.get_session_messages("abc-123-def", limit: 10, offset: 5)
+```
+
+### Resume a Past Session
+
 Use with `Conversation.resume` to pick up where you left off:
 
 ```ruby
-sessions = ClaudeAgent.list_sessions(dir: Dir.pwd, limit: 5)
-session = sessions.first
+session = ClaudeAgent::Session.where(dir: Dir.pwd, limit: 5).first
 
 conversation = ClaudeAgent.resume_conversation(session.session_id)
 turn = conversation.say("Continue where we left off")
@@ -1307,23 +1346,26 @@ session = ClaudeAgent.unstable_v2_create_session(options)
 
 ### Return Types
 
-| Type                  | Purpose                                                                          |
-|-----------------------|----------------------------------------------------------------------------------|
-| `TurnResult`          | Complete agent turn with text, tools, usage, and status accessors                |
-| `ToolActivity`        | Tool use/result pair with turn index and timing                                  |
-| `CumulativeUsage`     | Running totals of tokens, cost, turns, and duration                              |
-| `PermissionRequest`   | Deferred permission promise resolvable from any thread                           |
-| `PermissionQueue`     | Thread-safe queue of pending permission requests                                 |
-| `EventHandler`        | Typed event callback registry                                                    |
-| `SlashCommand`        | Available slash commands (name, description, argument_hint)                      |
-| `ModelInfo`           | Available models (value, display_name, description)                              |
-| `McpServerStatus`     | MCP server status (name, status, server_info)                                    |
-| `AccountInfo`         | Account information (email, organization, subscription_type)                     |
-| `ModelUsage`          | Per-model usage stats (input_tokens, output_tokens, cost_usd)                    |
-| `McpSetServersResult` | Result of set_mcp_servers (added, removed, errors)                               |
-| `RewindFilesResult`   | Result of rewind_files (can_rewind, error, files_changed, insertions, deletions) |
-| `SessionInfo`         | Session metadata from `list_sessions` (session_id, summary, git_branch, cwd)     |
-| `SDKPermissionDenial` | Permission denial info (tool_name, tool_use_id, tool_input)                      |
+| Type                     | Purpose                                                                          |
+|--------------------------|----------------------------------------------------------------------------------|
+| `TurnResult`             | Complete agent turn with text, tools, usage, and status accessors                |
+| `ToolActivity`           | Tool use/result pair with turn index and timing                                  |
+| `CumulativeUsage`        | Running totals of tokens, cost, turns, and duration                              |
+| `PermissionRequest`      | Deferred permission promise resolvable from any thread                           |
+| `PermissionQueue`        | Thread-safe queue of pending permission requests                                 |
+| `EventHandler`           | Typed event callback registry                                                    |
+| `SlashCommand`           | Available slash commands (name, description, argument_hint)                      |
+| `ModelInfo`              | Available models (value, display_name, description)                              |
+| `McpServerStatus`        | MCP server status (name, status, server_info)                                    |
+| `AccountInfo`            | Account information (email, organization, subscription_type)                     |
+| `ModelUsage`             | Per-model usage stats (input_tokens, output_tokens, cost_usd)                    |
+| `McpSetServersResult`    | Result of set_mcp_servers (added, removed, errors)                               |
+| `RewindFilesResult`      | Result of rewind_files (can_rewind, error, files_changed, insertions, deletions) |
+| `Session`                | Session finder with `.find`, `.all`, `#messages` (wraps SessionInfo)             |
+| `SessionMessageRelation` | Chainable, Enumerable query object for session messages                          |
+| `SessionInfo`            | Session metadata from `list_sessions` (session_id, summary, git_branch, cwd)     |
+| `SessionMessage`         | Message from a session transcript (type, uuid, session_id, message)              |
+| `SDKPermissionDenial`    | Permission denial info (tool_name, tool_use_id, tool_input)                      |
 
 ## Logging
 

data/SPEC.md

@@ -3,11 +3,11 @@
 This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
 
 **Reference Versions:**
-- TypeScript SDK: v0.2.56 (npm package)
-- Python SDK: v0.1.43 from GitHub (commit 9d758dd)
+- TypeScript SDK: v0.2.61 (npm package)
+- Python SDK: v0.1.44 from GitHub (commit 7297bdc)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-02-25
+**Last Updated:** 2026-02-26
 
 ---
 
@@ -524,9 +524,35 @@ Session management and resumption.
 
 ### Session Discovery
 
-| Feature          | TypeScript | Python | Ruby | Notes                                      |
-|------------------|:----------:|:------:|:----:|--------------------------------------------|
-| `listSessions()` |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| Feature                | TypeScript | Python | Ruby | Notes                                            |
+|------------------------|:----------:|:------:|:----:|--------------------------------------------------|
+| `listSessions()`       |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53)       |
+| `getSessionMessages()` |     ✅      |   ❌    |  ✅   | Read session transcript messages (v0.2.59)       |
+
+#### ListSessionsOptions
+
+| Field   | TypeScript | Python | Ruby | Notes                                     |
+|---------|:----------:|:------:|:----:|-------------------------------------------|
+| `dir`   |     ✅      |   ❌    |  ✅   | Project directory (includes worktrees)    |
+| `limit` |     ✅      |   ❌    |  ✅   | Maximum number of sessions to return      |
+
+#### GetSessionMessagesOptions
+
+| Field    | TypeScript | Python | Ruby | Notes                                        |
+|----------|:----------:|:------:|:----:|----------------------------------------------|
+| `dir`    |     ✅      |   ❌    |  ✅   | Project directory to find session in         |
+| `limit`  |     ✅      |   ❌    |  ✅   | Maximum number of messages to return         |
+| `offset` |     ✅      |   ❌    |  ✅   | Number of messages to skip from the start    |
+
+#### SessionMessage Fields
+
+| Field                | TypeScript | Python | Ruby | Notes                            |
+|----------------------|:----------:|:------:|:----:|----------------------------------|
+| `type`               |     ✅      |   ❌    |  ✅   | 'user' or 'assistant'            |
+| `uuid`               |     ✅      |   ❌    |  ✅   | Message UUID                     |
+| `session_id`         |     ✅      |   ❌    |  ✅   | Session ID                       |
+| `message`            |     ✅      |   ❌    |  ✅   | Raw message content              |
+| `parent_tool_use_id` |     ✅      |   ❌    |  ✅   | Parent tool use ID (always null) |
 
 #### SDKSessionInfo Fields
 
@@ -649,9 +675,10 @@ Public API surface for SDK clients.
 
 ### Standalone Functions
 
-| Feature          |    TypeScript    | Python | Ruby | Notes                                      |
-|------------------|:----------------:|:------:|:----:|--------------------------------------------|
-| `listSessions()` | ✅ `listSessions` |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| Feature                | TypeScript | Python | Ruby | Notes                                      |
+|------------------------|:----------:|:------:|:----:|--------------------------------------------|
+| `listSessions()`       |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| `getSessionMessages()` |     ✅      |   ❌    |  ✅   | Read session transcript (v0.2.59)          |
 
 ### Query Interface
 
@@ -727,7 +754,9 @@ Public API surface for SDK clients.
 - v0.2.51: Added `TaskProgressMessage` for real-time background agent progress reporting
 - v0.2.52: Added `mcp_authenticate`/`mcp_clear_auth` control requests for MCP server authentication
 - v0.2.53: Added `listSessions()` for discovering and listing past sessions with `SDKSessionInfo` metadata
-- v0.2.54 – v0.2.56: CLI parity updates (no new SDK-facing features)
+- v0.2.54 – v0.2.58: CLI parity updates (no new SDK-facing features)
+- v0.2.59: Added `getSessionMessages()` for reading session transcript history with pagination (limit/offset)
+- v0.2.61: CLI parity update (no new SDK-facing features)
 
 ### Python SDK
 - Full source available with `Transport` abstract class
@@ -741,10 +770,10 @@ Public API surface for SDK clients.
 - Added `thinking` config and `effort` option in v0.1.36
 - Handles `rate_limit_event` and unknown message types gracefully (v0.1.40)
 - Client has `get_server_info()` for accessing the initialization result (v0.1.31+)
-- v0.1.42 – v0.1.43: CLI parity updates (no new SDK-facing features)
+- v0.1.42 – v0.1.44: CLI parity updates (no new SDK-facing features; latest commit bumps bundled CLI to v2.1.61)
 
 ### Ruby SDK (This Repository)
-- Feature parity with TypeScript SDK v0.2.56
+- Feature parity with TypeScript SDK v0.2.61
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations

data/lib/claude_agent/get_session_messages.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeAgent
+  # Reads a session's conversation transcript from its JSONL file.
+  #
+  # Given a session UUID, finds the session file on disk, parses all messages,
+  # reconstructs the main conversation thread (handling branches and forks),
+  # filters to user/assistant messages, and returns SessionMessage objects
+  # with optional pagination.
+  #
+  # Matches the TypeScript SDK's getSessionMessages() (v0.2.59).
+  #
+  # @example Basic usage
+  #   messages = ClaudeAgent.get_session_messages("abc-123-def")
+  #   messages.each { |m| puts "#{m.type}: #{m.message}" }
+  #
+  # @example With pagination
+  #   messages = ClaudeAgent.get_session_messages("abc-123-def", limit: 10, offset: 5)
+  #
+  module GetSessionMessages
+    # Valid message types to include when parsing JSONL lines.
+    PARSEABLE_TYPES = %w[user assistant progress system attachment].freeze
+
+    class << self
+      # Read session messages with optional pagination.
+      #
+      # @param session_id [String] UUID of the session to read
+      # @param dir [String, nil] Project directory to find the session in
+      # @param limit [Integer, nil] Maximum number of messages to return
+      # @param offset [Integer, nil] Number of messages to skip from the start
+      # @return [Array<SessionMessage>] User/assistant messages, or empty array if not found
+      def call(session_id, dir: nil, limit: nil, offset: nil)
+        return [] unless SessionPaths::UUID_PATTERN.match?(session_id)
+
+        content = find_session_file(session_id, dir)
+        return [] unless content
+
+        raw_messages = parse_jsonl(content)
+        thread = reconstruct_thread(raw_messages)
+        result = thread.select { |msg| include_message?(msg) }.map { |msg| to_session_message(msg) }
+
+        off = offset || 0
+        if limit && limit > 0
+          result.slice(off, limit) || []
+        elsif off > 0
+          result.slice(off..) || []
+        else
+          result
+        end
+      end
+
+      private
+
+      # Locate and read a session JSONL file from disk.
+      #
+      # @param session_id [String] Session UUID
+      # @param dir [String, nil] Optional project directory to scope search
+      # @return [String, nil] File contents or nil
+      def find_session_file(session_id, dir)
+        filename = "#{session_id}.jsonl"
+
+        if dir
+          resolved = SessionPaths.realpath(dir)
+          project_dir = SessionPaths.find_project_dir(resolved)
+          if project_dir
+            content = read_session_content(project_dir, filename)
+            return content if content
+          end
+
+          # Try worktrees
+          worktrees = SessionPaths.git_worktrees(resolved)
+          worktrees.each do |wt|
+            next if wt == resolved
+            wt_project_dir = SessionPaths.find_project_dir(wt)
+            if wt_project_dir
+              content = read_session_content(wt_project_dir, filename)
+              return content if content
+            end
+          end
+
+          nil
+        else
+          # Search all project directories
+          base = SessionPaths.projects_dir
+          return nil unless File.directory?(base)
+
+          Dir.entries(base).each do |entry|
+            next if entry.start_with?(".")
+            entry_path = File.join(base, entry)
+            next unless File.directory?(entry_path)
+            content = read_session_content(entry_path, filename)
+            return content if content
+          end
+
+          nil
+        end
+      end
+
+      # Read a session file's full contents.
+      #
+      # @param dir [String] Directory containing the file
+      # @param filename [String] JSONL filename
+      # @return [String, nil] File contents or nil
+      def read_session_content(dir, filename)
+        path = File.join(dir, filename)
+        File.read(path, encoding: "UTF-8")
+      rescue SystemCallError
+        nil
+      end
+
+      # Parse JSONL content into raw message hashes.
+      # Only includes messages with valid types and a uuid field.
+      #
+      # @param content [String] JSONL file contents
+      # @return [Array<Hash>] Parsed message hashes
+      def parse_jsonl(content)
+        messages = []
+        content.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          begin
+            parsed = JSON.parse(line)
+            type = parsed["type"]
+            next unless PARSEABLE_TYPES.include?(type) && parsed["uuid"].is_a?(String)
+            messages << parsed
+          rescue JSON::ParserError
+            next
+          end
+        end
+        messages
+      end
+
+      # Reconstruct the main conversation thread from raw messages.
+      #
+      # Handles branches, forks, and sidechains by:
+      # 1. Building UUID -> message and UUID -> index maps
+      # 2. Finding leaf messages (messages with no children)
+      # 3. Walking up parentUuid chains to find user/assistant ancestors
+      # 4. Picking the best leaf (highest file position, prefer main thread)
+      # 5. Walking from best leaf to root to build chronological thread
+      #
+      # @param messages [Array<Hash>] All parsed messages from JSONL
+      # @return [Array<Hash>] Chronologically ordered main thread messages
+      def reconstruct_thread(messages)
+        # Build UUID -> message map
+        by_uuid = {}
+        messages.each { |msg| by_uuid[msg["uuid"]] = msg }
+
+        # Build UUID -> file index map (position in file)
+        index_map = {}
+        messages.each_with_index { |msg, i| index_map[msg["uuid"]] = i }
+
+        # Find parent UUIDs (messages that have children pointing to them)
+        parent_uuids = Set.new
+        messages.each do |msg|
+          parent_uuids.add(msg["parentUuid"]) if msg["parentUuid"]
+        end
+
+        # Find leaf messages (no children point to them)
+        leaves = messages.reject { |msg| parent_uuids.include?(msg["uuid"]) }
+
+        # For each leaf, walk up parentUuid chain to find nearest user/assistant ancestor
+        candidates = []
+        leaves.each do |leaf|
+          current = leaf
+          seen = Set.new
+          while current
+            break if seen.include?(current["uuid"])
+            seen.add(current["uuid"])
+            if current["type"] == "user" || current["type"] == "assistant"
+              candidates << current
+              break
+            end
+            current = current["parentUuid"] ? by_uuid[current["parentUuid"]] : nil
+          end
+        end
+
+        return [] if candidates.empty?
+
+        # Filter out sidechain/team/meta candidates
+        main_candidates = candidates.reject do |msg|
+          msg["isSidechain"] || msg["teamName"] || msg["isMeta"]
+        end
+
+        # Pick best: highest file position index
+        pick_best = ->(arr) {
+          arr.max_by { |msg| index_map[msg["uuid"]] || -1 }
+        }
+
+        best_leaf = main_candidates.empty? ? pick_best.call(candidates) : pick_best.call(main_candidates)
+
+        # Walk from best leaf back to root, building chronological thread
+        thread = []
+        visited = Set.new
+        current = best_leaf
+        while current
+          break if visited.include?(current["uuid"])
+          visited.add(current["uuid"])
+          thread.unshift(current) # prepend for chronological order
+          current = current["parentUuid"] ? by_uuid[current["parentUuid"]] : nil
+        end
+
+        thread
+      end
+
+      # Whether a message should be included in the final output.
+      #
+      # @param msg [Hash] Raw message hash
+      # @return [Boolean]
+      def include_message?(msg)
+        return false unless msg["type"] == "user" || msg["type"] == "assistant"
+        return false if msg["isMeta"]
+        return false if msg["isSidechain"]
+        return false if msg["teamName"]
+        true
+      end
+
+      # Transform a raw message hash into a SessionMessage.
+      #
+      # @param msg [Hash] Raw message hash from JSONL
+      # @return [SessionMessage]
+      def to_session_message(msg)
+        SessionMessage.new(
+          type: msg["type"],
+          uuid: msg["uuid"],
+          session_id: msg["sessionId"],
+          message: msg["message"],
+          parent_tool_use_id: nil
+        )
+      end
+    end
+  end
+end

data/lib/claude_agent/list_sessions.rb

@@ -17,9 +17,7 @@ module ClaudeAgent
   #
   module ListSessions
     # Constants matching TypeScript SDK
-    MAX_SLUG_LENGTH = 200
     BUFFER_SIZE = 65_536 # 64KB
-    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
 
     # Patterns for filtering non-meaningful user prompts (matches TypeScript MM regex)
     META_MESSAGE_PATTERN = /\A(?:<local-command-stdout>|<session-start-hook>|<tick>|<goal>|\[Request interrupted by user[^\]]*\]|\s*<ide_opened_file>[\s\S]*<\/ide_opened_file>\s*\z|\s*<ide_selection>[\s\S]*<\/ide_selection>\s*\z)/
@@ -44,57 +42,6 @@ module ClaudeAgent
 
       private
 
-      # --- Directory Encoding ---
-
-      # Encode a project directory path to a slug for the projects directory.
-      # Matches the TypeScript SDK's q9 function exactly.
-      #
-      # @param path [String] Absolute directory path
-      # @return [String] Encoded slug
-      def encode_project_dir(path)
-        slug = path.gsub(/[^a-zA-Z0-9]/, "-")
-        return slug if slug.length <= MAX_SLUG_LENGTH
-
-        hash = java_string_hash(path)
-        "#{slug[0, MAX_SLUG_LENGTH]}-#{hash}"
-      end
-
-      # Java-style string hash (matches TypeScript DM function).
-      # Computes hash = ((hash << 5) - hash + charCode) as 32-bit signed integer,
-      # then returns absolute value in base 36.
-      #
-      # @param str [String]
-      # @return [String] Base-36 hash
-      def java_string_hash(str)
-        hash = 0
-        str.each_char do |c|
-          hash = ((hash << 5) - hash + c.ord) & 0xFFFFFFFF
-          # Convert to signed 32-bit integer
-          hash -= 0x100000000 if hash >= 0x80000000
-        end
-        hash.abs.to_s(36)
-      end
-
-      # --- Config Paths ---
-
-      # @return [String] Claude config directory
-      def config_dir
-        (ENV["CLAUDE_CONFIG_DIR"] || File.join(Dir.home, ".claude"))
-      end
-
-      # @return [String] Projects directory within config
-      def projects_dir
-        File.join(config_dir, "projects")
-      end
-
-      # Get the expected project directory path for a given working directory.
-      #
-      # @param path [String] Working directory
-      # @return [String] Full path to project sessions directory
-      def project_dir_for(path)
-        File.join(projects_dir, encode_project_dir(path))
-      end
-
       # --- Session File Reading ---
 
       # Read head and tail buffers from a session file.
@@ -329,7 +276,7 @@ module ClaudeAgent
           next unless entry.end_with?(".jsonl")
 
           stem = entry[0...-6] # Remove .jsonl extension
-          next unless UUID_PATTERN.match?(stem)
+          next unless SessionPaths::UUID_PATTERN.match?(stem)
 
           full_path = File.join(dir_path, entry)
           session = parse_session_file(full_path, stem)
@@ -339,63 +286,6 @@ module ClaudeAgent
         sessions
       end
 
-      # Look up the project directory for a given path, handling hash suffix fallback.
-      # Matches TypeScript's tQ function.
-      #
-      # @param path [String] Working directory
-      # @return [String, nil] Project directory path or nil
-      def find_project_dir(path)
-        expected = project_dir_for(path)
-        return expected if File.directory?(expected)
-
-        # Try prefix matching for hash-suffixed directories
-        slug = encode_project_dir(path)
-        return nil if slug.length <= MAX_SLUG_LENGTH
-
-        prefix = slug[0, MAX_SLUG_LENGTH]
-        base = projects_dir
-        return nil unless File.directory?(base)
-
-        Dir.entries(base).each do |entry|
-          next if entry.start_with?(".")
-          next unless File.directory?(File.join(base, entry))
-          return File.join(base, entry) if entry.start_with?("#{prefix}-")
-        end
-
-        nil
-      end
-
-      # --- Worktree Support ---
-
-      # Get git worktree paths for a directory.
-      #
-      # @param dir [String] Working directory
-      # @return [Array<String>] Worktree paths
-      def git_worktrees(dir)
-        output = nil
-        IO.popen([ "git", "worktree", "list", "--porcelain" ], chdir: dir, err: File::NULL) do |io|
-          Timeout.timeout(5) { output = io.read }
-        end
-
-        return [] unless output
-
-        output.lines
-          .select { |line| line.start_with?("worktree ") }
-          .map { |line| line[9..].strip.unicode_normalize(:nfc) }
-      rescue SystemCallError, Timeout::Error, Errno::ENOENT
-        []
-      end
-
-      # Resolve symlinks and normalize a path.
-      #
-      # @param path [String]
-      # @return [String]
-      def realpath(path)
-        File.realpath(path).unicode_normalize(:nfc)
-      rescue SystemCallError
-        path.unicode_normalize(:nfc)
-      end
-
       # --- Listing Modes ---
 
       # List sessions for a specific directory, including worktree siblings.
@@ -405,28 +295,28 @@ module ClaudeAgent
       # @param limit [Integer, nil]
       # @return [Array<SessionInfo>]
       def list_for_directory(dir, limit)
-        resolved = realpath(dir)
-        worktrees = git_worktrees(resolved)
+        resolved = SessionPaths.realpath(dir)
+        worktrees = SessionPaths.git_worktrees(resolved)
 
         # Simple case: not in a worktree (or single worktree)
         if worktrees.length <= 1
-          project_dir = find_project_dir(resolved)
+          project_dir = SessionPaths.find_project_dir(resolved)
           return [] unless project_dir
           return sort_and_limit(scan_project_dir(project_dir), limit)
         end
 
         # Complex case: multiple worktrees - scan all related project directories
-        base = projects_dir
+        base = SessionPaths.projects_dir
 
         # Build prefix list from worktree paths (longest first for matching)
-        prefixes = worktrees.map { |wt| { path: wt, prefix: encode_project_dir(wt) } }
+        prefixes = worktrees.map { |wt| { path: wt, prefix: SessionPaths.encode_project_dir(wt) } }
         prefixes.sort_by! { |p| -p[:prefix].length }
 
         all_sessions = []
         seen_dirs = Set.new
 
         # First: sessions from the exact directory
-        project_dir = find_project_dir(resolved)
+        project_dir = SessionPaths.find_project_dir(resolved)
         if project_dir
           seen_dirs.add(File.basename(project_dir))
           all_sessions.concat(scan_project_dir(project_dir))
@@ -442,7 +332,7 @@ module ClaudeAgent
 
             prefixes.each do |p|
               prefix = p[:prefix]
-              if entry == prefix || (prefix.length >= MAX_SLUG_LENGTH && entry.start_with?("#{prefix[0, MAX_SLUG_LENGTH]}-"))
+              if entry == prefix || (prefix.length >= SessionPaths::MAX_SLUG_LENGTH && entry.start_with?("#{prefix[0, SessionPaths::MAX_SLUG_LENGTH]}-"))
                 seen_dirs.add(entry)
                 all_sessions.concat(scan_project_dir(entry_path))
                 break
@@ -460,7 +350,7 @@ module ClaudeAgent
       # @param limit [Integer, nil]
       # @return [Array<SessionInfo>]
       def list_all(limit)
-        base = projects_dir
+        base = SessionPaths.projects_dir
         return [] unless File.directory?(base)
 
         all_sessions = []

data/lib/claude_agent/session.rb

@@ -49,7 +49,7 @@ module ClaudeAgent
   #   session.stream.each { |msg| puts msg.inspect }
   #   session.close
   #
-  class Session
+  class V2Session
     attr_reader :session_id, :options
 
     def initialize(options)
@@ -141,7 +141,7 @@ module ClaudeAgent
     #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
     #
     def unstable_v2_create_session(options)
-      Session.new(options)
+      V2Session.new(options)
     end
 
     # V2 API - UNSTABLE
@@ -158,7 +158,7 @@ module ClaudeAgent
     def unstable_v2_resume_session(session_id, options)
       # For resumption, we need to pass the resume option through
       # Since SessionOptions doesn't have resume, we handle it in the Client options
-      session = Session.new(options)
+      session = V2Session.new(options)
       session.instance_variable_set(:@resume_session_id, session_id)
 
       # Override build_client_options to include resume
@@ -204,4 +204,72 @@ module ClaudeAgent
       end
     end
   end
+
+  # Historical session finder with Rails-like API.
+  #
+  # Wraps SessionInfo with a rich interface for finding sessions
+  # and querying their message transcripts.
+  #
+  # @example Find a session by ID
+  #   session = ClaudeAgent::Session.find("abc-123")
+  #   session.summary  # => "Fix login bug"
+  #
+  # @example List all sessions
+  #   sessions = ClaudeAgent::Session.all(limit: 10)
+  #
+  # @example Query messages with chainable relation
+  #   session.messages.where(limit: 5).each { |m| puts m.type }
+  #
+  class Session
+    attr_reader :session_id, :summary, :last_modified, :file_size,
+                :custom_title, :first_prompt, :git_branch, :cwd
+
+    def initialize(session_info)
+      @session_id = session_info.session_id
+      @summary = session_info.summary
+      @last_modified = session_info.last_modified
+      @file_size = session_info.file_size
+      @custom_title = session_info.custom_title
+      @first_prompt = session_info.first_prompt
+      @git_branch = session_info.git_branch
+      @cwd = session_info.cwd
+      @dir = session_info.cwd
+    end
+
+    # Returns a chainable, Enumerable relation for this session's messages.
+    #
+    # @return [SessionMessageRelation]
+    def messages
+      SessionMessageRelation.new(session_id, dir: @dir)
+    end
+
+    class << self
+      # Find a session by its UUID.
+      #
+      # @param session_id [String] UUID of the session
+      # @param dir [String, nil] Directory to scope the search
+      # @return [Session, nil] The session, or nil if not found
+      def find(session_id, dir: nil)
+        sessions = ListSessions.call(dir: dir)
+        info = sessions.find { |s| s.session_id == session_id }
+        info ? new(info) : nil
+      end
+
+      # List all sessions.
+      #
+      # @return [Array<Session>]
+      def all
+        ListSessions.call.map { |info| new(info) }
+      end
+
+      # Query sessions with optional filters.
+      #
+      # @param dir [String, nil] Directory to scope sessions to
+      # @param limit [Integer, nil] Maximum number of sessions to return
+      # @return [Array<Session>]
+      def where(dir: nil, limit: nil)
+        ListSessions.call(dir: dir, limit: limit).map { |info| new(info) }
+      end
+    end
+  end
 end

data/lib/claude_agent/session_message_relation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Chainable, lazy query object for session transcript messages.
+  #
+  # Wraps GetSessionMessages with an Enumerable interface and
+  # Rails-style `where` chaining for pagination.
+  #
+  # @example Basic usage
+  #   relation = SessionMessageRelation.new("abc-123")
+  #   relation.each { |m| puts m.type }
+  #
+  # @example Chaining
+  #   relation.where(limit: 10).map(&:uuid)
+  #   relation.where(offset: 5, limit: 10).to_a
+  #
+  class SessionMessageRelation
+    include Enumerable
+
+    def initialize(session_id, dir: nil, limit: nil, offset: nil)
+      @session_id = session_id
+      @dir = dir
+      @limit = limit
+      @offset = offset
+    end
+
+    # Return a new relation with updated pagination parameters.
+    #
+    # @param limit [Integer, nil] Maximum number of messages
+    # @param offset [Integer, nil] Number of messages to skip
+    # @return [SessionMessageRelation]
+    def where(limit: @limit, offset: @offset)
+      self.class.new(@session_id, dir: @dir, limit: limit, offset: offset)
+    end
+
+    # Iterate over messages. Required by Enumerable.
+    #
+    # @yield [SessionMessage] Each message in the result set
+    # @return [Enumerator] if no block given
+    def each(&block)
+      results.each(&block)
+    end
+
+    # Materialize the relation into an array.
+    #
+    # @return [Array<SessionMessage>]
+    def to_a
+      results.dup
+    end
+
+    private
+
+    def results
+      @results ||= GetSessionMessages.call(
+        @session_id, dir: @dir, limit: @limit, offset: @offset
+      )
+    end
+  end
+end

data/lib/claude_agent/session_paths.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module ClaudeAgent
+  # Shared path/directory infrastructure for session discovery.
+  #
+  # Provides methods to locate Claude Code session files on disk,
+  # encode project directory paths, and resolve git worktrees.
+  # Used by both ListSessions and GetSessionMessages.
+  #
+  module SessionPaths
+    MAX_SLUG_LENGTH = 200
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    module_function
+
+    # @return [String] Claude config directory
+    def config_dir
+      (ENV["CLAUDE_CONFIG_DIR"] || File.join(Dir.home, ".claude"))
+    end
+
+    # @return [String] Projects directory within config
+    def projects_dir
+      File.join(config_dir, "projects")
+    end
+
+    # Get the expected project directory path for a given working directory.
+    #
+    # @param path [String] Working directory
+    # @return [String] Full path to project sessions directory
+    def project_dir_for(path)
+      File.join(projects_dir, encode_project_dir(path))
+    end
+
+    # Encode a project directory path to a slug for the projects directory.
+    # Matches the TypeScript SDK's q9 function exactly.
+    #
+    # @param path [String] Absolute directory path
+    # @return [String] Encoded slug
+    def encode_project_dir(path)
+      slug = path.gsub(/[^a-zA-Z0-9]/, "-")
+      return slug if slug.length <= MAX_SLUG_LENGTH
+
+      hash = java_string_hash(path)
+      "#{slug[0, MAX_SLUG_LENGTH]}-#{hash}"
+    end
+
+    # Java-style string hash (matches TypeScript DM function).
+    # Computes hash = ((hash << 5) - hash + charCode) as 32-bit signed integer,
+    # then returns absolute value in base 36.
+    #
+    # @param str [String]
+    # @return [String] Base-36 hash
+    def java_string_hash(str)
+      hash = 0
+      str.each_char do |c|
+        hash = ((hash << 5) - hash + c.ord) & 0xFFFFFFFF
+        # Convert to signed 32-bit integer
+        hash -= 0x100000000 if hash >= 0x80000000
+      end
+      hash.abs.to_s(36)
+    end
+
+    # Look up the project directory for a given path, handling hash suffix fallback.
+    # Matches TypeScript's tQ function.
+    #
+    # @param path [String] Working directory
+    # @return [String, nil] Project directory path or nil
+    def find_project_dir(path)
+      expected = project_dir_for(path)
+      return expected if File.directory?(expected)
+
+      # Try prefix matching for hash-suffixed directories
+      slug = encode_project_dir(path)
+      return nil if slug.length <= MAX_SLUG_LENGTH
+
+      prefix = slug[0, MAX_SLUG_LENGTH]
+      base = projects_dir
+      return nil unless File.directory?(base)
+
+      Dir.entries(base).each do |entry|
+        next if entry.start_with?(".")
+        next unless File.directory?(File.join(base, entry))
+        return File.join(base, entry) if entry.start_with?("#{prefix}-")
+      end
+
+      nil
+    end
+
+    # Resolve symlinks and normalize a path.
+    #
+    # @param path [String]
+    # @return [String]
+    def realpath(path)
+      File.realpath(path).unicode_normalize(:nfc)
+    rescue SystemCallError
+      path.unicode_normalize(:nfc)
+    end
+
+    # Get git worktree paths for a directory.
+    #
+    # @param dir [String] Working directory
+    # @return [Array<String>] Worktree paths
+    def git_worktrees(dir)
+      output = nil
+      IO.popen([ "git", "worktree", "list", "--porcelain" ], chdir: dir, err: File::NULL) do |io|
+        Timeout.timeout(5) { output = io.read }
+      end
+
+      return [] unless output
+
+      output.lines
+        .select { |line| line.start_with?("worktree ") }
+        .map { |line| line[9..].strip.unicode_normalize(:nfc) }
+    rescue SystemCallError, Timeout::Error, Errno::ENOENT
+      []
+    end
+  end
+end

data/lib/claude_agent/types.rb

@@ -213,6 +213,22 @@ module ClaudeAgent
     end
   end
 
+  # Message from a session transcript returned by get_session_messages (TypeScript SDK v0.2.59 parity)
+  #
+  # @example
+  #   msg = SessionMessage.new(
+  #     type: "user",
+  #     uuid: "abc-123",
+  #     session_id: "def-456",
+  #     message: { "role" => "user", "content" => [{ "type" => "text", "text" => "Hello" }] }
+  #   )
+  #
+  SessionMessage = Data.define(:type, :uuid, :session_id, :message, :parent_tool_use_id) do
+    def initialize(type:, uuid:, session_id:, message:, parent_tool_use_id: nil)
+      super
+    end
+  end
+
   AgentDefinition = Data.define(
     :description,
     :prompt,

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.9"
+  VERSION = "0.7.10"
 end

data/lib/claude_agent.rb

@@ -30,8 +30,11 @@ require_relative "claude_agent/tool_activity"
 require_relative "claude_agent/query"
 require_relative "claude_agent/client"
 require_relative "claude_agent/conversation"
+require_relative "claude_agent/session_paths"        # Shared session path infrastructure
 require_relative "claude_agent/list_sessions"       # Session discovery (TypeScript SDK v0.2.53 parity)
-require_relative "claude_agent/session"            # V2 Session API (unstable)
+require_relative "claude_agent/get_session_messages"    # Session transcript reading (TypeScript SDK v0.2.59 parity)
+require_relative "claude_agent/session_message_relation" # Chainable message query object
+require_relative "claude_agent/session"                  # Session finder + V2 Session API (unstable)
 
 module ClaudeAgent
   class << self
@@ -56,6 +59,21 @@ module ClaudeAgent
       ListSessions.call(dir: dir, limit: limit)
     end
 
+    # Read messages from a past session's transcript
+    #
+    # Reads the session JSONL file from disk, reconstructs the main conversation
+    # thread, and returns user/assistant messages with optional pagination.
+    #
+    # @param session_id [String] UUID of the session to read
+    # @param dir [String, nil] Project directory to find the session in.
+    #   When nil, searches all projects.
+    # @param limit [Integer, nil] Maximum number of messages to return.
+    # @param offset [Integer, nil] Number of messages to skip from the start.
+    # @return [Array<SessionMessage>]
+    def get_session_messages(session_id, dir: nil, limit: nil, offset: nil)
+      GetSessionMessages.call(session_id, dir: dir, limit: limit, offset: offset)
+    end
+
     # Resume a previous Conversation by session ID
     #
     # @param session_id [String] Session ID to resume

data/sig/claude_agent.rbs

@@ -215,6 +215,17 @@ module ClaudeAgent
     def initialize: (session_id: String, summary: String, last_modified: Integer, file_size: Integer, ?custom_title: String?, ?first_prompt: String?, ?git_branch: String?, ?cwd: String?) -> void
   end
 
+  # Session transcript message returned by get_session_messages (TypeScript SDK v0.2.59 parity)
+  class SessionMessage
+    attr_reader type: String
+    attr_reader uuid: String
+    attr_reader session_id: String
+    attr_reader message: untyped
+    attr_reader parent_tool_use_id: nil
+
+    def initialize: (type: String, uuid: String, session_id: String, message: untyped, ?parent_tool_use_id: nil) -> void
+  end
+
   # Agent definition for custom subagents (TypeScript SDK parity)
   class AgentDefinition
     attr_reader description: String
@@ -1181,16 +1192,37 @@ module ClaudeAgent
 
   # Session discovery
   def self.list_sessions: (?dir: String?, ?limit: Integer?) -> Array[SessionInfo]
+  def self.get_session_messages: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> Array[SessionMessage]
+
+  # Shared session path infrastructure
+  module SessionPaths
+    MAX_SLUG_LENGTH: Integer
+    UUID_PATTERN: Regexp
+
+    def self.config_dir: () -> String
+    def self.projects_dir: () -> String
+    def self.project_dir_for: (String path) -> String
+    def self.encode_project_dir: (String path) -> String
+    def self.java_string_hash: (String str) -> String
+    def self.find_project_dir: (String path) -> String?
+    def self.realpath: (String path) -> String
+    def self.git_worktrees: (String dir) -> Array[String]
+  end
 
   # ListSessions module
   module ListSessions
-    MAX_SLUG_LENGTH: Integer
     BUFFER_SIZE: Integer
-    UUID_PATTERN: Regexp
 
     def self.call: (?dir: String?, ?limit: Integer?) -> Array[SessionInfo]
   end
 
+  # GetSessionMessages module (TypeScript SDK v0.2.59 parity)
+  module GetSessionMessages
+    PARSEABLE_TYPES: Array[String]
+
+    def self.call: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> Array[SessionMessage]
+  end
+
   # Convenience methods
   def self.conversation: (**untyped) -> Conversation
   def self.resume_conversation: (String session_id, **untyped) -> Conversation
@@ -1423,7 +1455,7 @@ module ClaudeAgent
   end
 
   # V2 Session interface for multi-turn conversations
-  class Session
+  class V2Session
     attr_reader session_id: String?
     attr_reader options: SessionOptions
 
@@ -1436,7 +1468,37 @@ module ClaudeAgent
   end
 
   # V2 API module-level methods
-  def self.unstable_v2_create_session: (Hash[Symbol, untyped] | SessionOptions options) -> Session
-  def self.unstable_v2_resume_session: (String session_id, Hash[Symbol, untyped] | SessionOptions options) -> Session
+  def self.unstable_v2_create_session: (Hash[Symbol, untyped] | SessionOptions options) -> V2Session
+  def self.unstable_v2_resume_session: (String session_id, Hash[Symbol, untyped] | SessionOptions options) -> V2Session
   def self.unstable_v2_prompt: (String message, Hash[Symbol, untyped] | SessionOptions options) -> ResultMessage
+
+  # Chainable, lazy query object for session transcript messages
+  class SessionMessageRelation
+    include Enumerable[SessionMessage]
+
+    def initialize: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> void
+    def where: (?limit: Integer?, ?offset: Integer?) -> SessionMessageRelation
+    def each: () { (SessionMessage) -> void } -> void
+            | () -> Enumerator[SessionMessage, void]
+    def to_a: () -> Array[SessionMessage]
+  end
+
+  # Historical session finder with Rails-like API
+  class Session
+    attr_reader session_id: String
+    attr_reader summary: String
+    attr_reader last_modified: Integer
+    attr_reader file_size: Integer
+    attr_reader custom_title: String?
+    attr_reader first_prompt: String?
+    attr_reader git_branch: String?
+    attr_reader cwd: String?
+
+    def initialize: (SessionInfo session_info) -> void
+    def messages: () -> SessionMessageRelation
+
+    def self.find: (String session_id, ?dir: String?) -> Session?
+    def self.all: () -> Array[Session]
+    def self.where: (?dir: String?, ?limit: Integer?) -> Array[Session]
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.9
+  version: 0.7.10
 platform: ruby
 authors:
 - Thomas Carr
@@ -59,6 +59,7 @@ files:
 - lib/claude_agent/cumulative_usage.rb
 - lib/claude_agent/errors.rb
 - lib/claude_agent/event_handler.rb
+- lib/claude_agent/get_session_messages.rb
 - lib/claude_agent/hooks.rb
 - lib/claude_agent/list_sessions.rb
 - lib/claude_agent/logging.rb
@@ -73,6 +74,8 @@ files:
 - lib/claude_agent/query.rb
 - lib/claude_agent/sandbox_settings.rb
 - lib/claude_agent/session.rb
+- lib/claude_agent/session_message_relation.rb
+- lib/claude_agent/session_paths.rb
 - lib/claude_agent/spawn.rb
 - lib/claude_agent/tool_activity.rb
 - lib/claude_agent/transport/base.rb