claude_agent 0.7.15 → 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/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Global configuration object (Stripe-style).
+  #
+  # Holds default values for all configurable Options fields. When a
+  # query, conversation, or ask/chat call is made without explicit
+  # Options, these defaults are merged with per-request overrides to
+  # produce the final Options instance.
+  #
+  # @example Module-level setters
+  #   ClaudeAgent.model = "claude-sonnet-4-5-20250514"
+  #   ClaudeAgent.permission_mode = "acceptEdits"
+  #   ClaudeAgent.max_turns = 10
+  #
+  # @example Block-based bulk config
+  #   ClaudeAgent.configure do |c|
+  #     c.model = "claude-sonnet-4-5-20250514"
+  #     c.permission_mode = "acceptEdits"
+  #     c.max_turns = 10
+  #   end
+  #
+  # @example Per-request overrides (via ask)
+  #   ClaudeAgent.ask("Fix the bug", model: "opus", max_turns: 5)
+  #
+  class Configuration
+    # Tier 1: Module-level delegators (set once at boot)
+    TIER1_FIELDS = %i[
+      model permission_mode max_turns max_budget_usd
+      system_prompt append_system_prompt cli_path cwd
+      sandbox debug effort persist_session fallback_model
+    ].freeze
+
+    # Tier 2: Per-request overrides (common kwargs on ask/chat)
+    TIER2_FIELDS = %i[
+      tools allowed_tools disallowed_tools thinking output_format
+    ].freeze
+
+    # Tier 3: Advanced (accessible via config.xxx= or raw Options.new)
+    TIER3_FIELDS = %i[
+      mcp_servers hooks env extra_args agents setting_sources settings
+      plugins betas spawn_claude_code_process agent add_dirs
+      max_buffer_size stderr_callback include_partial_messages
+      enable_file_checkpointing prompt_suggestions strict_mcp_config
+      tool_config agent_progress_summaries max_thinking_tokens
+      debug_file
+    ].freeze
+
+    # All configurable fields
+    ALL_FIELDS = (TIER1_FIELDS + TIER2_FIELDS + TIER3_FIELDS).freeze
+
+    attr_accessor(*ALL_FIELDS)
+
+    # Global PermissionPolicy
+    attr_accessor :default_permissions
+
+    # Global HookRegistry
+    attr_accessor :default_hooks
+
+    # Global MCP server registrations
+    attr_accessor :default_mcp_servers
+
+    # Create a new Configuration with all fields at nil/default.
+    #
+    # @return [Configuration]
+    def self.setup
+      new
+    end
+
+    def initialize
+      @default_mcp_servers = {}
+    end
+
+    # Merge config defaults with per-request keyword overrides to produce an Options instance.
+    #
+    # nil overrides are ignored (config default wins). Explicit non-nil overrides win.
+    #
+    # @param overrides [Hash] Per-request keyword overrides
+    # @return [Options]
+    def to_options(**overrides)
+      merged = {}
+
+      ALL_FIELDS.each do |field|
+        config_val = public_send(field)
+        override_val = overrides.key?(field) ? overrides[field] : nil
+
+        # Per-request override wins if provided; config default otherwise
+        if overrides.key?(field)
+          merged[field] = override_val
+        elsif !config_val.nil?
+          merged[field] = config_val
+        end
+      end
+
+      # Forward any extra keys not in ALL_FIELDS (e.g., can_use_tool, permission_queue, etc.)
+      overrides.each do |key, value|
+        merged[key] = value unless ALL_FIELDS.include?(key)
+      end
+
+      # Wire in global permissions if no per-request can_use_tool provided
+      if default_permissions && !merged.key?(:can_use_tool) && !default_permissions.empty?
+        merged[:can_use_tool] = default_permissions.to_can_use_tool
+      end
+
+      # Wire in global hooks (additive merge with per-request hooks)
+      if default_hooks && !default_hooks.empty?
+        request_hooks = merged[:hooks]
+        global_hooks = default_hooks.to_hooks_hash
+        if request_hooks.is_a?(Hash)
+          # Merge: global + request (request hooks take precedence for same event)
+          combined = global_hooks.dup
+          request_hooks.each do |event, matchers|
+            combined[event] = (combined[event] || []) + Array(matchers)
+          end
+          merged[:hooks] = combined
+        else
+          merged[:hooks] = global_hooks
+        end
+      end
+
+      # Wire in global MCP servers
+      if !default_mcp_servers.empty? && !merged.key?(:mcp_servers)
+        merged[:mcp_servers] = default_mcp_servers.dup
+      end
+
+      Options.new(**merged)
+    end
+  end
+end