claude_agent 0.7.14 → 0.7.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b6188550282e29001c6bf2996842b5c11cd013de37aeeded995c982cef67399
-  data.tar.gz: 33e7d2e6b000d5f085093f236fd531c136e3711be170c3af4c11715fbdedda77
+  metadata.gz: df8d1374efdac7201f83dd2afc3b0042c44162b5ba58c650305b58c63c60397e
+  data.tar.gz: 957bd07189e6d3cf46771367088e9897ce993d2d2944d6108afd1352e2f19f01
 SHA512:
-  metadata.gz: b5ec2de8caa5ef32681e671645dd6d6540d58f86221c3d99186cc7ab7e9a076b892fe41c16e2472b94399c296439b5ceba72f573eb0b218b8b2ff507661d162f
-  data.tar.gz: c00a1312f295f1f15949cac076155750b2259f5412cfb0cbe6acffa8bcb789927887bb58ebacdc94fd92fa492851f985b975a14bb31abe68b78e23ce4fda8c5d
+  metadata.gz: 8dc4b9ec494ac9337b7860f4250361366184f6ca983c3b5f9754ac5050966708f0d220a6b5975dff49ab4badd47e6f24b3104467b2a9e511cc3e95114f3cb5fc
+  data.tar.gz: fe0357e27da9036fe90a740fecaa64eb5ce95736e7c5566cef0e746080eb014e9a55adb17372b34520d1985fa5d838806cc57e395170c8e2e1766a95563c0336

data/.claude/rules/conventions.md

@@ -587,36 +587,86 @@ validate! \
 
 ## Advanced Patterns
 
-### Global Coordinator (Use Sparingly)
+### Stripe-Style Global Configuration
 
-For CLI applications that need shared state:
+Module-level config with `Forwardable` delegators for common fields. A `Configuration`
+object holds defaults; `to_options(**overrides)` merges per-request overrides and returns
+the internal `Options` type.
 
 ```ruby
-# lib/gem_name/cli.rb
-COORDINATOR = Coordinator.new
+module GemName
+  require "forwardable"
+
+  @config = Configuration.setup
+
+  class << self
+    extend Forwardable
+    attr_reader :config
+
+    def_delegators :@config, :model, :model=,
+                             :max_turns, :max_turns=
 
-class Cli::Base
-  def initialize(*)
-    super
-    initialize_coordinator unless COORDINATOR.configured?
+    def configure = yield(@config)
+    def reset_config! = @config = Configuration.setup
   end
 end
+
+# Usage:
+GemName.model = "opus"
+GemName.configure { |c| c.max_turns = 10 }
 ```
 
-### Factory Methods in Coordinator
+### DSL Builder Pattern
+
+Declarative builders that compile to the format consumed by internal plumbing.
+The builder accumulates rules/matchers, then `to_*` produces the final artifact.
 
 ```ruby
-class Coordinator
-  def app(role: nil, host: nil)
-    Commands::App.new(config, role: role, host: host)
+class PermissionPolicy
+  def initialize(&block)
+    @rules = []
+    yield self if block_given?
   end
 
-  def builder
-    @builder ||= Commands::Builder.new(config)
+  def allow(*names)
+    names.each { |n| @rules << { name: n, action: :allow } }
+    self
   end
 
-  def configured?
-    @config.present?
+  def to_can_use_tool
+    rules = @rules.dup.freeze
+    ->(tool_name, input, ctx) { ... }
   end
 end
 ```
+
+Key conventions:
+- Constructor takes `&block` and yields `self`
+- Methods return `self` for chaining
+- `to_*` method compiles to the internal format
+- `empty?` predicate for skipping when unconfigured
+
+### Prepending Modules into Data.define Types
+
+To add shared behavior (like `deconstruct_keys` overrides) to `Data.define` classes,
+use `prepend` not `include`. Data.define generates methods on the class itself, so
+`include` would be shadowed. When overriding `deconstruct_keys`, filter virtual keys
+out before calling `super` — Data's implementation stops early on unknown member keys.
+
+```ruby
+module Message
+  def deconstruct_keys(keys)
+    if keys.nil?
+      { type: type }.merge(super)
+    elsif keys.include?(:type)
+      member_keys = keys - [ :type ]
+      base = member_keys.empty? ? {} : super(member_keys)
+      { type: type }.merge(base)
+    else
+      super
+    end
+  end
+end
+
+MESSAGE_TYPES.each { |klass| klass.prepend(Message) }
+```

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.16] - 2026-03-15
+
+## [0.7.15] - 2026-03-15
+
+### Added
+- `AbortError#partial_turn` carries the in-progress `TurnResult` when a turn is aborted, eliminating the need for separate extraction paths on cancellation
+- `StreamEvent` typed accessors: `delta_text`, `delta_type`, `thinking_text`, `content_index` for convenient access without hash-digging into raw event data
+- `PermissionRequest#display_label` and `#summary` delegate to `ToolUseBlock` formatting, removing the need to construct dummy blocks for display
+- `AbortController#reset!` and `AbortSignal#reset!` allow reuse across turns; `Conversation#say` auto-resets at turn start
+- `PostCompact` hook event with `PostCompactInput` type (`trigger` and `compact_summary` fields) (TypeScript SDK v0.2.76 parity)
+- `cancel_async_message` control request to drop queued user messages by UUID (TypeScript SDK v0.2.76 parity)
+- `get_settings` control request to read effective merged settings (TypeScript SDK v0.2.76 parity)
+- `fork_session` standalone function to branch a session from a specific point with UUID remapping (TypeScript SDK v0.2.76 parity)
+- `ForkSessionResult` data type returned by `fork_session`
+
+### Changed
+- `TurnResult#text` now falls back to accumulated streaming deltas when no `AssistantMessage` text is available (e.g., on abort mid-stream)
+- `Conversation#say` resets the tool tracker at the **start** of each turn instead of the end, so tracker data survives abort and remains accessible until the next `say()` call
+- `Client#receive_turn` catches `AbortError` and re-raises with the partial `TurnResult` attached
+
 ## [0.7.14] - 2026-03-14
 
 ### Fixed

data/CLAUDE.md

@@ -1,6 +1,23 @@
 # ClaudeAgent Ruby SDK
 
-Ruby SDK for building autonomous AI agents that interact with Claude Code CLI. See [README.md](README.md) for API usage, message types, configuration, and examples.
+Ruby SDK for building autonomous AI agents that interact with Claude Code CLI. See [README.md](README.md) for a quick start, and the [docs/](docs/) folder for full guides:
+
+| Guide                                      | What's in it                                         |
+|--------------------------------------------|------------------------------------------------------|
+| [Getting Started](docs/getting-started.md) | Install, first queries, multi-turn basics            |
+| [Configuration](docs/configuration.md)     | Global config, Options, sandbox, agents              |
+| [Conversations](docs/conversations.md)     | Multi-turn API, TurnResult, callbacks, tool tracking |
+| [Queries](docs/queries.md)                 | One-shot: ask, query_turn, query                     |
+| [Permissions](docs/permissions.md)         | PermissionPolicy DSL, can_use_tool, queue            |
+| [Hooks](docs/hooks.md)                     | HookRegistry DSL, hook events, input types           |
+| [MCP Tools](docs/mcp.md)                   | In-process tools, servers, schemas                   |
+| [Events](docs/events.md)                   | EventHandler, typed callbacks                        |
+| [Messages](docs/messages.md)               | 22 message types, 8 content blocks, pattern matching |
+| [Sessions](docs/sessions.md)               | Session discovery, mutations, forking                |
+| [Client](docs/client.md)                   | Low-level bidirectional API                          |
+| [Errors](docs/errors.md)                   | Error hierarchy                                      |
+| [Logging](docs/logging.md)                 | Debug logging, log levels                            |
+| [Architecture](docs/architecture.md)       | Internal design, data flow                           |
 
 ## Stack
 
@@ -36,11 +53,14 @@ bin/release VERSION                # Release gem (e.g., bin/release 1.2.0)
 
 ## Conventions
 
-- **Immutable data types**: All messages and options use `Data.define`
+- **Immutable data types**: All messages and content blocks use `Data.define`, frozen at construction
 - **Frozen string literals**: Every file starts with `# frozen_string_literal: true`
-- **Message polymorphism**: Use `case` statements or `is_a?()` for content block types
+- **Message module**: All message/block types include `ClaudeAgent::Message` (text_content, pattern matching)
+- **Stripe-style config**: `ClaudeAgent.model = "opus"`, `ClaudeAgent.configure { |c| ... }`, `Configuration#to_options`
+- **Convenience entry points**: `ClaudeAgent.ask(prompt)` (one-shot), `ClaudeAgent.chat { |c| ... }` (multi-turn)
+- **DSL builders**: `PermissionPolicy` and `HookRegistry` compile to lambdas/hashes consumed by Options
 - **Error hierarchy**: All errors inherit from `ClaudeAgent::Error` with context (exit code, stderr, etc.)
-- **Protocol flow**: Transport → ControlProtocol → MessageParser → typed message objects
+- **Protocol flow**: Configuration → Options → Transport → ControlProtocol → MessageParser → typed messages
 
 ## Testing Notes