claude_agent 0.7.14 → 0.7.16

data/docs/queries.md

@@ -0,0 +1,227 @@
+# One-Shot Queries
+
+One-shot queries send a single prompt to the Claude Code CLI and return the response. No persistent connection or multi-turn state is maintained. For multi-turn conversations, see `Conversation`.
+
+The SDK provides three query methods at increasing levels of control:
+
+| Method                   | Returns               | Config integration         | Streaming            | Best for                             |
+|--------------------------|-----------------------|----------------------------|----------------------|--------------------------------------|
+| `ClaudeAgent.ask`        | `TurnResult`          | Yes (merges global config) | Block form           | Most applications                    |
+| `ClaudeAgent.query_turn` | `TurnResult`          | No (explicit Options)      | Block + EventHandler | Custom transports, event dispatch    |
+| `ClaudeAgent.query`      | `Enumerator<Message>` | No (explicit Options)      | Enumerator           | Full control over message processing |
+
+## ClaudeAgent.ask
+
+The primary entry point. Merges per-request keyword arguments with the global `Configuration`, builds an `Options` instance, and delegates to `query_turn`.
+
+```ruby
+turn = ClaudeAgent.ask("What is 2+2?")
+puts turn.text   # => "4"
+puts turn.cost   # => 0.002
+```
+
+### With configuration overrides
+
+Keyword arguments override global config for this request only:
+
+```ruby
+turn = ClaudeAgent.ask("Fix the bug in auth.rb",
+  model: "opus",
+  max_turns: 5,
+  permission_mode: "acceptEdits"
+)
+```
+
+### With callbacks
+
+Pass `on_*` lambdas to receive events as they stream in. The method still returns a `TurnResult` after the turn completes.
+
+```ruby
+turn = ClaudeAgent.ask("Explain Ruby GC",
+  on_text: ->(text) { print text },
+  on_tool_use: ->(tool) { puts "\nUsing: #{tool.name}" },
+  on_result: ->(result) { puts "\nCost: $#{result.total_cost_usd}" }
+)
+```
+
+Available callback keys correspond to `EventHandler` events: `on_text`, `on_thinking`, `on_tool_use`, `on_tool_result`, `on_result`, `on_assistant`, `on_stream_event`, `on_message` (catch-all), and others. See `EventHandler::EVENTS` for the full list.
+
+### With streaming block
+
+The block receives each raw message as it arrives:
+
+```ruby
+turn = ClaudeAgent.ask("Explain Ruby GC") do |msg|
+  case msg
+  when ClaudeAgent::AssistantMessage
+    print msg.text
+  when ClaudeAgent::ResultMessage
+    puts "\nDone in #{msg.duration_ms}ms"
+  end
+end
+```
+
+### With explicit Options
+
+Pass a pre-built `Options` to bypass the global `Configuration` entirely:
+
+```ruby
+opts = ClaudeAgent::Options.new(
+  model: "claude-sonnet-4-5-20250514",
+  max_turns: 3,
+  permission_mode: "acceptEdits",
+  tools: ["Read", "Bash"]
+)
+
+turn = ClaudeAgent.ask("List files in /tmp", options: opts)
+```
+
+### With global configuration
+
+Set defaults once, then call `ask` without repeating them:
+
+```ruby
+ClaudeAgent.configure do |c|
+  c.model = "opus"
+  c.max_turns = 10
+  c.permission_mode = "acceptEdits"
+end
+
+# These calls inherit the global config
+turn = ClaudeAgent.ask("Fix the failing test")
+turn = ClaudeAgent.ask("Now update the docs", max_turns: 3)  # override max_turns
+```
+
+## ClaudeAgent.query_turn
+
+Wraps `query` and accumulates all messages into a `TurnResult`. Use this when you need to pass an explicit `Options` or `EventHandler` without going through `Configuration`.
+
+```ruby
+def query_turn(prompt:, options: nil, transport: nil, events: nil, &block)
+```
+
+### Basic usage
+
+```ruby
+turn = ClaudeAgent.query_turn(prompt: "What is 2+2?")
+puts turn.text
+puts turn.cost
+```
+
+### With EventHandler
+
+Build an `EventHandler` for typed event dispatch:
+
+```ruby
+events = ClaudeAgent::EventHandler.new
+  .on_text { |text| print text }
+  .on_tool_use { |tool| puts "Tool: #{tool.name}" }
+  .on_result { |r| puts "\nCost: $#{r.total_cost_usd}" }
+
+turn = ClaudeAgent.query_turn(
+  prompt: "Refactor the parser",
+  options: ClaudeAgent::Options.new(model: "opus", max_turns: 5),
+  events: events
+)
+```
+
+### With block
+
+The block receives each message, just like the block form of `ask`:
+
+```ruby
+turn = ClaudeAgent.query_turn(prompt: "Explain closures") do |msg|
+  print msg.text if msg.is_a?(ClaudeAgent::AssistantMessage)
+end
+
+puts turn.session_id
+```
+
+### With custom transport
+
+Inject a transport for testing or custom subprocess management:
+
+```ruby
+transport = ClaudeAgent::Transport::Subprocess.new(options: opts)
+turn = ClaudeAgent.query_turn(prompt: "Hello", options: opts, transport: transport)
+```
+
+## ClaudeAgent.query
+
+The lowest-level one-shot interface. Returns an `Enumerator` that yields each `Message` as it arrives from the CLI. You are responsible for iterating and interpreting message types.
+
+```ruby
+def query(prompt:, options: nil, transport: nil)
+```
+
+### Basic usage with case statement
+
+```ruby
+ClaudeAgent.query(prompt: "What is 2+2?").each do |message|
+  case message
+  when ClaudeAgent::SystemMessage
+    # Init message with session metadata
+  when ClaudeAgent::AssistantMessage
+    print message.text
+  when ClaudeAgent::UserMessage
+    # Tool results (system-generated)
+  when ClaudeAgent::StreamEvent
+    # Streaming deltas
+  when ClaudeAgent::ResultMessage
+    puts "\nCost: $#{message.total_cost_usd}"
+    puts "Duration: #{message.duration_ms}ms"
+    puts "Session: #{message.session_id}"
+  end
+end
+```
+
+### Collecting all messages
+
+```ruby
+messages = ClaudeAgent.query(prompt: "Hello").to_a
+result = messages.find { |m| m.is_a?(ClaudeAgent::ResultMessage) }
+puts result.total_cost_usd
+```
+
+### With custom options
+
+```ruby
+options = ClaudeAgent::Options.new(
+  model: "claude-sonnet-4-5-20250514",
+  max_turns: 5,
+  permission_mode: "acceptEdits"
+)
+
+ClaudeAgent.query(prompt: "Fix the bug", options: options).each do |message|
+  # ...
+end
+```
+
+## TurnResult
+
+All three methods ultimately produce a `TurnResult` (for `query`, you build one yourself or use `query_turn`). Key accessors:
+
+| Accessor          | Type            | Description                                 |
+|-------------------|-----------------|---------------------------------------------|
+| `text`            | `String`        | All assistant text concatenated             |
+| `thinking`        | `String`        | All thinking content concatenated           |
+| `tool_uses`       | `Array`         | Tool use blocks from assistant messages     |
+| `tool_results`    | `Array`         | Tool result blocks from user messages       |
+| `tool_executions` | `Array<Hash>`   | Matched `{ tool_use:, tool_result: }` pairs |
+| `result`          | `ResultMessage` | Final result message (nil if incomplete)    |
+| `cost`            | `Float`         | Total cost in USD                           |
+| `usage`           | `Hash`          | Token usage breakdown                       |
+| `duration_ms`     | `Integer`       | Wall-clock duration                         |
+| `session_id`      | `String`        | Session ID for resumption                   |
+| `model`           | `String`        | Model used                                  |
+| `success?`        | `Boolean`       | Whether the turn completed without error    |
+| `error?`          | `Boolean`       | Whether the turn ended with an error        |
+| `messages`        | `Array`         | All raw messages received                   |
+
+## Choosing the Right Method
+
+**Use `ask`** when you want the simplest path with global configuration support. This is the right choice for most applications.
+
+**Use `query_turn`** when you need explicit `Options` or `EventHandler` without going through `Configuration`, or when injecting a custom transport.
+
+**Use `query`** when you need full control over message iteration -- for example, to build custom accumulators, forward messages to another system, or handle message types that `TurnResult` does not expose.

data/docs/sessions.md

@@ -0,0 +1,335 @@
+# Sessions
+
+Claude Code CLI persists every conversation as a session on disk. The SDK can find, inspect, mutate, fork, and resume these sessions without spawning a CLI subprocess -- all operations read and write the session JSONL files directly.
+
+## Session Resource
+
+The `Session` class wraps `SessionInfo` with a rich, Rails-like API for discovering and working with past sessions.
+
+### Finding a Session
+
+Use `Session.find` for a safe lookup that returns `nil` when the session does not exist, or `Session.retrieve` when you want an exception on missing sessions.
+
+```ruby
+# Returns Session or nil (targeted lookup by ID, not a full scan)
+session = ClaudeAgent::Session.find("abc-123-def-456")
+
+# Returns Session or raises ClaudeAgent::NotFoundError
+session = ClaudeAgent::Session.retrieve("abc-123-def-456")
+```
+
+Both accept an optional `dir:` keyword to scope the search to a specific project directory:
+
+```ruby
+session = ClaudeAgent::Session.find("abc-123-def-456", dir: "/path/to/project")
+```
+
+### Listing Sessions
+
+```ruby
+# All sessions across all projects, sorted by last modified (most recent first)
+sessions = ClaudeAgent::Session.all
+
+# With optional filters
+sessions = ClaudeAgent::Session.where(dir: "/path/to/project", limit: 10)
+```
+
+### Fields
+
+Every `Session` exposes the following attributes:
+
+| Field           | Type             | Description                                                                       |
+|-----------------|------------------|-----------------------------------------------------------------------------------|
+| `session_id`    | `String`         | UUID of the session.                                                              |
+| `summary`       | `String`         | Display summary: custom title, last auto-summary, first prompt, or `"(session)"`. |
+| `last_modified` | `Integer`        | Last modification time as epoch milliseconds.                                     |
+| `file_size`     | `Integer`        | Size of the session JSONL file in bytes.                                          |
+| `custom_title`  | `String`, `nil`  | User-assigned title, if any.                                                      |
+| `first_prompt`  | `String`, `nil`  | First meaningful user prompt (truncated to 200 chars).                            |
+| `git_branch`    | `String`, `nil`  | Git branch active during the session.                                             |
+| `cwd`           | `String`, `nil`  | Working directory the session was started in.                                     |
+| `tag`           | `String`, `nil`  | User-assigned tag, if any.                                                        |
+| `created_at`    | `Integer`, `nil` | Creation timestamp (epoch milliseconds), if available.                            |
+
+```ruby
+session = ClaudeAgent::Session.retrieve("abc-123-def-456")
+
+puts session.summary        # => "Fix login bug"
+puts session.git_branch     # => "fix/login"
+puts session.custom_title   # => nil (no custom title set)
+puts session.cwd            # => "/Users/dev/myapp"
+```
+
+### Messages
+
+`session.messages` returns a chainable, `Enumerable` `SessionMessageRelation`. Messages are loaded lazily on first access.
+
+```ruby
+session = ClaudeAgent::Session.retrieve("abc-123-def-456")
+
+# All messages
+session.messages.each { |m| puts "#{m.type}: #{m.uuid}" }
+
+# Pagination via .where
+session.messages.where(limit: 10).to_a
+session.messages.where(limit: 10, offset: 5).to_a
+
+# Enumerable methods work directly
+session.messages.first
+session.messages.count
+session.messages.select { |m| m.type == "assistant" }
+session.messages.map(&:uuid)
+```
+
+Each message in the relation is a `SessionMessage` with these fields:
+
+| Field                | Type            | Description                                       |
+|----------------------|-----------------|---------------------------------------------------|
+| `type`               | `String`        | `"user"` or `"assistant"`.                        |
+| `uuid`               | `String`        | Message UUID.                                     |
+| `session_id`         | `String`        | Session UUID this message belongs to.             |
+| `message`            | `Hash`          | Raw message payload (role, content blocks, etc.). |
+| `parent_tool_use_id` | `String`, `nil` | Parent tool use ID for tool result messages.      |
+
+### Mutations
+
+#### Renaming
+
+```ruby
+session.rename("My descriptive title")
+session.custom_title  # => "My descriptive title"
+```
+
+Appends a `custom-title` JSONL entry to the session file. The `custom_title` attribute is updated in place.
+
+#### Tagging
+
+```ruby
+session.tag_session("important")
+session.tag  # => "important"
+
+# Clear the tag
+session.tag_session(nil)
+session.tag  # => nil
+```
+
+Appends a `tag` JSONL entry. Unicode zero-width and directional characters are automatically stripped from tag values.
+
+Both mutations return `self` for chaining:
+
+```ruby
+session.rename("Refactored auth module").tag_session("refactor")
+```
+
+### Forking
+
+Create a new session by copying an existing one. All UUIDs in the forked session are remapped to fresh values.
+
+```ruby
+# Fork the entire session
+forked = session.fork
+forked.session_id  # => new UUID
+
+# Fork up to a specific message (inclusive)
+forked = session.fork(up_to: "message-uuid-here")
+
+# Fork with a custom title
+forked = session.fork(title: "Branch: try alternative approach")
+```
+
+The returned value is a new `Session` instance pointing to the forked session file.
+
+### Reloading
+
+Re-read session metadata from disk to pick up external changes:
+
+```ruby
+session.reload
+session.summary  # reflects current file state
+```
+
+Raises `ClaudeAgent::NotFoundError` if the session file no longer exists.
+
+### Resuming
+
+Open a `Conversation` that continues from this session. The CLI restores full conversation context from the session transcript.
+
+```ruby
+# Block form -- auto-closes when the block exits
+session.resume(model: "opus") do |c|
+  turn = c.say("Continue where we left off")
+  puts turn.text
+end
+
+# Without a block -- caller is responsible for closing
+conversation = session.resume(max_turns: 5)
+conversation.say("What did we discuss last time?")
+conversation.close
+```
+
+Accepts the same keyword arguments as `Conversation.new`.
+
+## Functional API
+
+The module-level methods provide direct access to session operations without wrapping results in `Session` objects. These return the underlying data types (`SessionInfo`, `SessionMessage`, `ForkSessionResult`) and are useful when you need lower-level control.
+
+### `ClaudeAgent.list_sessions`
+
+```ruby
+# All sessions
+sessions = ClaudeAgent.list_sessions
+# => Array<SessionInfo>
+
+# Scoped to a directory with pagination
+sessions = ClaudeAgent.list_sessions(
+  dir: "/path/to/project",
+  limit: 20,
+  offset: 10,
+  include_worktrees: true   # default: true
+)
+```
+
+When `dir` is inside a git repository and `include_worktrees` is `true`, sessions from all git worktree paths are included automatically.
+
+### `ClaudeAgent.get_session_info`
+
+Targeted lookup of a single session by UUID. Returns `SessionInfo` or `nil`.
+
+```ruby
+info = ClaudeAgent.get_session_info("abc-123-def-456")
+info = ClaudeAgent.get_session_info("abc-123-def-456", dir: "/path/to/project")
+```
+
+### `ClaudeAgent.get_session_messages`
+
+Read the conversation transcript for a session. Returns user and assistant messages in chronological order, reconstructing the main conversation thread from branches and forks.
+
+```ruby
+messages = ClaudeAgent.get_session_messages("abc-123-def-456")
+# => Array<SessionMessage>
+
+messages = ClaudeAgent.get_session_messages("abc-123-def-456",
+  dir: "/path/to/project",
+  limit: 10,
+  offset: 5
+)
+```
+
+### `ClaudeAgent.rename_session`
+
+```ruby
+ClaudeAgent.rename_session("abc-123-def-456", "New title")
+ClaudeAgent.rename_session("abc-123-def-456", "New title", dir: "/path/to/project")
+```
+
+Raises `ArgumentError` if the title is empty, `ClaudeAgent::Error` if the session is not found.
+
+### `ClaudeAgent.tag_session`
+
+```ruby
+ClaudeAgent.tag_session("abc-123-def-456", "important")
+ClaudeAgent.tag_session("abc-123-def-456", nil)  # clear tag
+ClaudeAgent.tag_session("abc-123-def-456", "v2", dir: "/path/to/project")
+```
+
+Raises `ClaudeAgent::Error` if the session is not found.
+
+### `ClaudeAgent.fork_session`
+
+```ruby
+result = ClaudeAgent.fork_session("abc-123-def-456")
+# => ForkSessionResult
+
+result.session_id  # => new UUID
+
+result = ClaudeAgent.fork_session("abc-123-def-456",
+  up_to_message_id: "msg-uuid",
+  title: "Forked conversation",
+  dir: "/path/to/project"
+)
+```
+
+Raises `ArgumentError` if `up_to_message_id` is provided but not found in the session transcript.
+
+## V2 Session API (Unstable)
+
+> **Warning:** The V2 Session API is unstable and may change without notice in any release. It is marked `@alpha` in the source and should not be used in production.
+
+The V2 API provides a lower-level, multi-turn session interface that maps directly to the TypeScript SDK's `SDKSession` pattern. Unlike `Conversation`, it gives you explicit control over send/stream cycles.
+
+### Creating a Session
+
+```ruby
+session = ClaudeAgent.unstable_v2_create_session(
+  model: "claude-sonnet-4-5-20250929",
+  permission_mode: "acceptEdits"
+)
+```
+
+### Sending and Streaming
+
+```ruby
+session.send("Hello, Claude!")
+
+session.stream.each do |msg|
+  case msg
+  when ClaudeAgent::AssistantMessage
+    print msg.text
+  when ClaudeAgent::ResultMessage
+    puts "\nDone!"
+  end
+end
+```
+
+### Resuming
+
+```ruby
+session = ClaudeAgent.unstable_v2_resume_session(
+  "session-abc-123",
+  model: "claude-sonnet-4-5-20250929"
+)
+session.send("Continue our conversation")
+session.stream.each { |msg| puts msg.inspect }
+session.close
+```
+
+### One-Shot Prompt
+
+```ruby
+result = ClaudeAgent.unstable_v2_prompt(
+  "What files are in this directory?",
+  model: "claude-sonnet-4-5-20250929"
+)
+puts result.text
+```
+
+### SessionOptions
+
+`SessionOptions` is a `Data.define` type with the following fields:
+
+| Field                            | Type            | Description                                        |
+|----------------------------------|-----------------|----------------------------------------------------|
+| `model`                          | `String`        | Model identifier (required).                       |
+| `path_to_claude_code_executable` | `String`, `nil` | Custom path to the Claude Code CLI binary.         |
+| `env`                            | `Hash`, `nil`   | Environment variables to pass to the CLI process.  |
+| `allowed_tools`                  | `Array`, `nil`  | Tools the agent is allowed to use.                 |
+| `disallowed_tools`               | `Array`, `nil`  | Tools the agent is not allowed to use.             |
+| `can_use_tool`                   | `Proc`, `nil`   | Callback for dynamic tool permission decisions.    |
+| `hooks`                          | `Hash`, `nil`   | Hook configuration.                                |
+| `permission_mode`                | `String`, `nil` | Permission mode (e.g., `"acceptEdits"`, `"plan"`). |
+
+### Lifecycle
+
+Always close V2 sessions when done to clean up the underlying CLI subprocess:
+
+```ruby
+session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
+begin
+  session.send("Do something")
+  session.stream.each { |msg| process(msg) }
+ensure
+  session.close
+end
+
+session.closed?  # => true
+```

data/lib/claude_agent/abort_controller.rb

@@ -34,6 +34,17 @@ module ClaudeAgent
     def abort(reason = nil)
       @signal.abort!(reason)
     end
+
+    # Reset the controller so it can be reused for another turn.
+    #
+    # After calling {#abort}, the controller is in an aborted state
+    # and cannot be reused without resetting. Call this before the
+    # next operation, or use {Conversation} which auto-resets.
+    #
+    # @return [void]
+    def reset!
+      @signal.reset!
+    end
   end
 
   # Signal object that tracks abort state (TypeScript SDK parity)
@@ -93,6 +104,19 @@ module ClaudeAgent
       raise AbortError, reason if aborted?
     end
 
+    # Reset the signal so the controller can be reused.
+    #
+    # No-op if the signal has not been aborted.
+    #
+    # @return [void]
+    def reset!
+      @mutex.synchronize do
+        return unless @aborted
+        @aborted = false
+        @reason = nil
+      end
+    end
+
     # @api private
     # Trigger the abort
     # @param reason [String, nil] Reason for aborting

data/lib/claude_agent/client/commands.rb

@@ -220,6 +220,38 @@ module ClaudeAgent
 
         @protocol.mcp_clear_auth(server_name)
       end
+
+      # Cancel a queued async user message (TypeScript SDK v0.2.76 parity)
+      #
+      # Drops a previously queued user message before it is processed.
+      #
+      # @param message_uuid [String] UUID of the message to cancel
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   client.cancel_async_message("msg-uuid-123")
+      #
+      def cancel_async_message(message_uuid)
+        require_connection!
+
+        @protocol.cancel_async_message(message_uuid)
+      end
+
+      # Get effective merged settings (TypeScript SDK v0.2.76 parity)
+      #
+      # Returns the current effective settings after merging all layers.
+      #
+      # @return [Hash] Merged settings
+      #
+      # @example
+      #   settings = client.get_settings
+      #   puts settings["model"]
+      #
+      def get_settings
+        require_connection!
+
+        @protocol.get_settings
+      end
     end
   end
 end

data/lib/claude_agent/client.rb

@@ -189,17 +189,23 @@ module ClaudeAgent
     # Receive messages until a ResultMessage, accumulating into a TurnResult
     #
     # Dispatches events to registered handlers (see {#on}).
+    # On abort, raises {AbortError} with the partial {TurnResult} attached.
     #
     # @yield [Message] Each message as it arrives (optional)
     # @return [TurnResult] The completed turn
+    # @raise [AbortError] If abort signal is triggered (with partial_turn attached)
     def receive_turn
       require_connection!
 
       turn = TurnResult.new
-      receive_response do |message|
-        turn << message
-        @event_handler.handle(message)
-        yield message if block_given?
+      begin
+        receive_response do |message|
+          turn << message
+          @event_handler.handle(message)
+          yield message if block_given?
+        end
+      rescue AbortError => e
+        raise AbortError.new(e.message, partial_turn: turn)
       end
       @event_handler.reset!
       turn