claude_agent 0.7.14 → 0.7.16

data/docs/events.md

@@ -0,0 +1,225 @@
+# Events
+
+The `EventHandler` dispatches typed events as messages flow through a conversation turn, replacing manual `case` statements over raw message types.
+
+Three event layers fire for every message, in order:
+
+1. **Catch-all** -- `:message` fires for every message regardless of type.
+2. **Type-based** -- the message's `type` fires (e.g., `:assistant`, `:result`, `:stream_event`).
+3. **Decomposed** -- convenience events extracted from rich content (`:text`, `:thinking`, `:tool_use`, `:tool_result`).
+
+## Quick start
+
+### Block DSL with `EventHandler.define`
+
+Build a handler in a single expression using the block DSL. The block is evaluated in the context of the new handler, so `on_*` methods are available directly:
+
+```ruby
+handler = ClaudeAgent::EventHandler.define do
+  on_text    { |text| print text }
+  on_result  { |r| puts "\nCost: $#{r.total_cost_usd}" }
+  on_tool_use { |tool| puts "Tool: #{tool.display_label}" }
+end
+```
+
+Pass the handler to `query_turn`:
+
+```ruby
+turn = ClaudeAgent.query_turn(prompt: "Explain Ruby", events: handler)
+```
+
+### Traditional construction
+
+Create an instance and chain `on_*` calls. Each returns `self`, so calls can be chained:
+
+```ruby
+handler = ClaudeAgent::EventHandler.new
+  .on_text      { |text| print text }
+  .on_thinking  { |thought| $stderr.puts "[thinking] #{thought}" }
+  .on_tool_use  { |tool| puts "Using: #{tool.display_label}" }
+  .on_result    { |r| puts "\nDone (cost=$#{r.total_cost_usd})" }
+```
+
+Or register handlers one at a time:
+
+```ruby
+handler = ClaudeAgent::EventHandler.new
+handler.on_text { |text| print text }
+handler.on_result { |r| puts "Done!" }
+```
+
+### Via Conversation
+
+`Conversation.new` accepts `on_*` keyword arguments for any event. These are registered on the underlying `Client` and persist across turns:
+
+```ruby
+conversation = ClaudeAgent::Conversation.new(
+  model: "claude-sonnet-4-5-20250514",
+  on_text:          ->(text) { print text },
+  on_thinking:      ->(thought) { $stderr.puts thought },
+  on_tool_use:      ->(tool) { puts "Tool: #{tool.display_label}" },
+  on_tool_result:   ->(result, tool_use) { puts "Result for #{tool_use&.name}" },
+  on_result:        ->(r) { puts "\nCost: $#{r.total_cost_usd}" },
+  on_message:       ->(msg) { log(msg) },
+  on_stream_event:  ->(evt) { handle_stream(evt) },
+  on_status:        ->(status) { show_status(status) },
+  on_tool_progress: ->(prog) { update_spinner(prog) }
+)
+
+turn = conversation.say("Fix the bug in auth.rb")
+conversation.close
+```
+
+`on_stream` is an alias for `on_text`:
+
+```ruby
+conversation = ClaudeAgent::Conversation.new(
+  on_stream: ->(text) { print text }
+)
+```
+
+### Via Client
+
+Register event handlers directly on a `Client`. Handlers persist across turns and fire automatically during `receive_turn` and `send_and_receive`:
+
+```ruby
+client = ClaudeAgent::Client.new
+client.on_text { |text| print text }
+client.on_tool_use { |tool| puts "Using: #{tool.display_label}" }
+client.on_result { |r| puts "\nDone!" }
+
+client.connect
+turn = client.send_and_receive("Fix the bug")
+client.disconnect
+```
+
+The generic `on` method also works:
+
+```ruby
+client.on(:text) { |text| print text }
+client.on(:stream_event) { |evt| handle_stream(evt) }
+```
+
+### Via one-shot query
+
+Pass an `events:` keyword to `ClaudeAgent.query_turn` for one-shot queries:
+
+```ruby
+events = ClaudeAgent::EventHandler.define do
+  on_text   { |text| print text }
+  on_result { |r| puts "\nCost: $#{r.total_cost_usd}" }
+end
+
+turn = ClaudeAgent.query_turn(prompt: "Explain concurrency", events: events)
+puts turn.text
+```
+
+The handler's `reset!` is called automatically when the turn completes.
+
+## Standalone usage
+
+Create a handler and dispatch messages manually with `handle`:
+
+```ruby
+handler = ClaudeAgent::EventHandler.new
+handler.on_text { |text| print text }
+handler.on_tool_use { |tool| log_tool(tool) }
+handler.on_tool_result { |result, tool_use| log_result(result, tool_use) }
+
+client.receive_response.each { |msg| handler.handle(msg) }
+handler.reset!
+```
+
+`handle` fires events in order:
+
+1. `:message` (catch-all)
+2. `message.type` (type-based)
+3. Decomposed events extracted from the message content
+
+Call `reset!` between turns to clear internal state (pending tool use tracking). When used via `Client` or `query_turn`, this is called automatically.
+
+## Tool use and tool result pairing
+
+The handler tracks pending tool uses internally. When a `:tool_result` event fires, it receives both the result block and the original tool use block that triggered it:
+
+```ruby
+handler.on_tool_use do |tool|
+  puts "Requested: #{tool.name} (#{tool.id})"
+end
+
+handler.on_tool_result do |result, tool_use|
+  puts "Result for: #{tool_use&.name}"  # tool_use is the matched ToolUseBlock
+  puts "Error: #{result.is_error}" if result.is_error
+end
+```
+
+The `tool_use` argument is `nil` if no matching tool use was found (which should not happen in normal operation).
+
+## Utility methods
+
+### `has_handlers?`
+
+Returns whether any handlers have been registered:
+
+```ruby
+handler = ClaudeAgent::EventHandler.new
+handler.has_handlers?  # => false
+
+handler.on_text { |t| print t }
+handler.has_handlers?  # => true
+```
+
+### `reset!`
+
+Clears turn-level tracking state (pending tool uses). Does not remove registered handlers:
+
+```ruby
+handler.reset!  # Clear pending tool uses between turns
+```
+
+## Event reference
+
+### Meta events
+
+| Event      | Receives           | Description                         |
+|------------|--------------------|-------------------------------------|
+| `:message` | Any message object | Fires for every message (catch-all) |
+
+### Type-based events
+
+Each fires when a message with the matching `type` is received. The handler receives the full message object.
+
+| Event                   | Description                                           |
+|-------------------------|-------------------------------------------------------|
+| `:user`                 | User message                                          |
+| `:assistant`            | Assistant message (contains text, thinking, tool use) |
+| `:system`               | System message (init, session info)                   |
+| `:result`               | End-of-turn result (cost, usage, session ID)          |
+| `:stream_event`         | Raw stream event                                      |
+| `:compact_boundary`     | Context window compaction boundary                    |
+| `:status`               | Status update                                         |
+| `:tool_progress`        | Tool execution progress                               |
+| `:hook_response`        | Hook execution response                               |
+| `:auth_status`          | Authentication status                                 |
+| `:task_notification`    | Background task notification                          |
+| `:hook_started`         | Hook execution started                                |
+| `:hook_progress`        | Hook execution progress                               |
+| `:tool_use_summary`     | Tool use summary                                      |
+| `:task_started`         | Background task started                               |
+| `:task_progress`        | Background task progress                              |
+| `:rate_limit_event`     | Rate limit information                                |
+| `:prompt_suggestion`    | Suggested follow-up prompt                            |
+| `:files_persisted`      | File checkpoint persisted                             |
+| `:elicitation_complete` | Elicitation completed                                 |
+| `:local_command_output` | Local command output                                  |
+
+### Decomposed events
+
+Extracted from the content of assistant and user messages. These fire after the type-based event.
+
+| Event          | Receives                                   | Description                                                             |
+|----------------|--------------------------------------------|-------------------------------------------------------------------------|
+| `:text`        | `String`                                   | Concatenated text from an assistant message                             |
+| `:thinking`    | `String`                                   | Concatenated thinking from an assistant message                         |
+| `:tool_use`    | `ToolUseBlock` or `ServerToolUseBlock`     | A tool use request from an assistant message                            |
+| `:tool_result` | `ToolResultBlock`, `ToolUseBlock` or `nil` | A tool result from a user message, paired with its originating tool use |

data/docs/getting-started.md

@@ -0,0 +1,310 @@
+# Getting Started
+
+This guide walks you through the ClaudeAgent Ruby SDK from first install to multi-turn conversations. Each section builds on the last, starting with the simplest API.
+
+## Requirements
+
+- **Ruby 3.2+** (the SDK uses `Data.define` for immutable types)
+- **Claude Code CLI v2.0.0+** ([install guide](https://code.claude.com/docs/en/getting-started))
+
+Verify both are available:
+
+```bash
+ruby -v    # >= 3.2.0
+claude -v  # >= 2.0.0
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "claude_agent"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install claude_agent
+```
+
+## Your First Query
+
+The fastest way to get a response is `ClaudeAgent.ask`. It sends a single prompt and returns a `TurnResult`:
+
+```ruby
+require "claude_agent"
+
+turn = ClaudeAgent.ask("What is the capital of France?")
+puts turn.text
+# => "The capital of France is Paris."
+```
+
+`TurnResult` gives you structured access to everything that happened during the turn:
+
+```ruby
+turn = ClaudeAgent.ask("Explain Ruby's GIL in one sentence.")
+
+puts turn.text           # Combined text from all assistant messages
+puts turn.cost           # Total cost in USD (e.g., 0.003)
+puts turn.duration_ms    # Wall-clock time in milliseconds
+puts turn.session_id     # Session ID (for resuming later)
+puts turn.model          # Model that handled the request
+puts turn.tool_uses.size # Number of tools Claude invoked
+puts turn.success?       # true if no errors
+```
+
+### Passing Options
+
+Override defaults with keyword arguments:
+
+```ruby
+turn = ClaudeAgent.ask("Fix the bug in auth.rb",
+  model: "opus",
+  max_turns: 5,
+  permission_mode: "acceptEdits"
+)
+```
+
+## Streaming
+
+Pass a block to `ask` to receive each message as it arrives:
+
+```ruby
+turn = ClaudeAgent.ask("Explain how TCP works") do |message|
+  case message
+  when ClaudeAgent::AssistantMessage
+    print message.text
+  when ClaudeAgent::ResultMessage
+    puts "\n--- Done (cost: $#{message.total_cost_usd}) ---"
+  end
+end
+```
+
+The block receives every message in the protocol stream. The return value is still a `TurnResult` with the full accumulated data.
+
+### Streaming with Callbacks
+
+For cleaner streaming, use `on_stream` to receive just the text:
+
+```ruby
+turn = ClaudeAgent.ask("Write a haiku about Ruby",
+  on_stream: ->(text) { print text }
+)
+puts "\nCost: $#{turn.cost}"
+```
+
+## Multi-Turn Conversations
+
+Use `ClaudeAgent.chat` for back-and-forth conversations. The block form auto-closes the connection when done:
+
+```ruby
+ClaudeAgent.chat do |c|
+  c.say("What files are in the current directory?")
+  c.say("Which one is the largest?")
+  c.say("Show me the first 10 lines of that file.")
+
+  puts "Total cost: $#{c.total_cost}"
+end
+```
+
+Each call to `say` returns a `TurnResult`:
+
+```ruby
+ClaudeAgent.chat(model: "opus") do |c|
+  turn = c.say("Write a function that reverses a string")
+  puts turn.text
+
+  turn = c.say("Now add error handling")
+  puts turn.text
+  puts "Tools used: #{turn.tool_uses.map(&:name).join(", ")}"
+end
+```
+
+### Without a Block
+
+If you need the conversation to outlive a block, skip it:
+
+```ruby
+conversation = ClaudeAgent.chat(model: "sonnet")
+conversation.say("Hello")
+conversation.say("Tell me more")
+conversation.close  # Always close when done
+```
+
+### Streaming in Conversations
+
+Pass `on_stream` to print text as it arrives:
+
+```ruby
+ClaudeAgent.chat(on_stream: ->(text) { print text }) do |c|
+  c.say("What is 2+2?")
+  puts  # newline after streamed output
+  c.say("Now multiply that by 10")
+  puts
+end
+```
+
+Or stream per-turn with a block on `say`:
+
+```ruby
+ClaudeAgent.chat do |c|
+  c.say("Explain monads") do |message|
+    print message.text if message.is_a?(ClaudeAgent::AssistantMessage)
+  end
+end
+```
+
+## Global Configuration
+
+Set defaults that apply to every `ask` and `chat` call:
+
+```ruby
+ClaudeAgent.model = "opus"
+ClaudeAgent.max_turns = 10
+ClaudeAgent.permission_mode = "acceptEdits"
+ClaudeAgent.system_prompt = "You are a helpful coding assistant."
+```
+
+Or configure in bulk:
+
+```ruby
+ClaudeAgent.configure do |c|
+  c.model = "opus"
+  c.max_turns = 10
+  c.permission_mode = "acceptEdits"
+  c.system_prompt = "You are a helpful coding assistant."
+  c.max_budget_usd = 1.0
+  c.cwd = "/path/to/project"
+end
+```
+
+Per-request keyword arguments always override global defaults:
+
+```ruby
+ClaudeAgent.model = "sonnet"
+
+# This request uses opus despite the global default
+turn = ClaudeAgent.ask("Complex question", model: "opus")
+```
+
+Reset to defaults with:
+
+```ruby
+ClaudeAgent.reset_config!
+```
+
+See [Configuration](configuration.md) for the full list of options.
+
+## The Conversation Class
+
+For full control, use `ClaudeAgent::Conversation` directly. It supports callbacks, permission handling, tool tracking, and session management.
+
+```ruby
+conversation = ClaudeAgent::Conversation.open(
+  model: "opus",
+  max_turns: 10,
+  permission_mode: "acceptEdits",
+  on_stream: ->(text) { print text },
+  on_tool_use: ->(tool) { puts "\nUsing tool: #{tool.name}" },
+  on_result: ->(result) { puts "\nTurn cost: $#{result.total_cost_usd}" }
+) do |c|
+  c.say("Read the file config.rb and explain what it does")
+  c.say("Refactor it to use keyword arguments")
+
+  puts "Session: #{c.session_id}"
+  puts "Total cost: $#{c.total_cost}"
+  puts "Turns: #{c.turns.size}"
+end
+```
+
+### Available Callbacks
+
+| Callback         | Receives                        | When                                      |
+|------------------|---------------------------------|-------------------------------------------|
+| `on_stream`      | `String`                        | Each text chunk as it streams             |
+| `on_text`        | `String`                        | Full text from each assistant message     |
+| `on_thinking`    | `String`                        | Thinking/reasoning content                |
+| `on_tool_use`    | `ToolUseBlock`                  | Claude requests a tool                    |
+| `on_tool_result` | `ToolResultBlock, ToolUseBlock` | Tool result arrives (paired with request) |
+| `on_result`      | `ResultMessage`                 | Turn completes                            |
+| `on_message`     | `Message`                       | Every message (catch-all)                 |
+
+### Permission Handling
+
+By default, Conversation queues permission requests for you to handle. You can also set a mode or provide a custom callback:
+
+```ruby
+# Use a CLI permission mode
+ClaudeAgent::Conversation.open(on_permission: :accept_edits) do |c|
+  c.say("Fix the typo in README.md")
+end
+
+# Or provide a lambda
+ClaudeAgent::Conversation.open(
+  on_permission: ->(tool_name, input, ctx) {
+    ClaudeAgent::PermissionResultAllow.new
+  }
+) do |c|
+  c.say("Update the config file")
+end
+```
+
+For declarative permission rules, see [Permissions](permissions.md).
+
+## Resuming Sessions
+
+Every turn returns a `session_id`. Save it to resume the conversation later:
+
+```ruby
+# First session
+session_id = nil
+ClaudeAgent.chat do |c|
+  c.say("Let's work on the authentication module")
+  session_id = c.session_id
+end
+
+# Later — resume where you left off
+ClaudeAgent.resume_conversation(session_id) do |c|
+  c.say("Continue with the tests we discussed")
+end
+```
+
+`resume_conversation` returns a `Conversation`, so it supports the same block form and callbacks.
+
+You can also resume via `Conversation.resume` directly:
+
+```ruby
+conversation = ClaudeAgent::Conversation.resume(session_id,
+  on_stream: ->(text) { print text }
+)
+conversation.say("Pick up where we left off")
+conversation.close
+```
+
+### Listing Past Sessions
+
+Browse previous sessions without spawning a CLI process:
+
+```ruby
+sessions = ClaudeAgent.list_sessions(dir: "/path/to/project", limit: 10)
+sessions.each do |session|
+  puts "#{session.session_id}: #{session.title} (#{session.updated_at})"
+end
+```
+
+## What's Next
+
+- [Configuration](configuration.md) -- full list of options, permission modes, and sandbox settings
+- [Conversations](conversations.md) -- advanced multi-turn patterns, tool tracking, and abort handling
+- [Permissions](permissions.md) -- declarative permission policies and the `can_use_tool` callback
+- [Hooks](hooks.md) -- lifecycle hooks for tool use, session events, and more
+- [Messages](messages.md) -- all message types, content blocks, and the event system
+- [MCP Servers](mcp-servers.md) -- integrating external tools via Model Context Protocol
+- [Sessions](sessions.md) -- listing, reading, forking, and managing past sessions