claude_agent 0.1.0

data/.claude/rules/releases.md

@@ -0,0 +1,177 @@
+# Release Conventions
+
+Guidelines for versioning and releasing the claude_agent gem.
+
+## Semantic Versioning
+
+Follow [Semantic Versioning 2.0.0](https://semver.org/):
+
+| Version Part | When to Increment                  | Example           |
+|--------------|------------------------------------|-------------------|
+| **MAJOR**    | Breaking API changes               | `1.0.0` → `2.0.0` |
+| **MINOR**    | New features (backward compatible) | `1.0.0` → `1.1.0` |
+| **PATCH**    | Bug fixes (backward compatible)    | `1.0.0` → `1.0.1` |
+
+### Pre-release Versions
+
+For beta/alpha releases, append a pre-release identifier:
+
+```
+1.0.0-alpha.1
+1.0.0-beta.1
+1.0.0-rc.1
+```
+
+## Changelog Format
+
+Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format:
+
+```markdown
+## [Unreleased]
+
+## [1.2.0] - 2025-03-15
+
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Deprecated
+- Feature scheduled for removal
+
+### Removed
+- Deleted feature description
+
+### Fixed
+- Bug fix description
+
+### Security
+- Security patch description
+```
+
+### Changelog Guidelines
+
+1. **Maintain [Unreleased]** - Always keep an Unreleased section at the top
+2. **Add entries as you work** - Don't wait until release time
+3. **User-focused language** - Write for gem users, not developers
+4. **Link to issues/PRs** - Reference GitHub issues when relevant
+5. **Newest first** - Most recent version at top
+
+### What to Include
+
+| Include | Exclude |
+|---------|---------|
+| API additions/changes | Internal refactors |
+| Bug fixes users might hit | Code style changes |
+| Deprecation notices | Test-only changes |
+| Breaking changes (prominent) | Documentation typos |
+| Security fixes | Dependency updates (minor) |
+
+## Release Process
+
+### Prerequisites
+
+Before releasing:
+
+1. All tests pass (`bundle exec rake`)
+2. CHANGELOG.md has entry for new version
+3. No uncommitted changes
+4. On `main` branch (or confirm if not)
+
+### Release Command
+
+```bash
+bin/release VERSION
+```
+
+Example:
+```bash
+bin/release 1.2.0
+```
+
+### What the Script Does
+
+1. Validates version format (semantic versioning)
+2. Checks CHANGELOG.md has entry for version
+3. Updates `lib/claude_agent/version.rb`
+4. Updates `Gemfile.lock`
+5. Commits with message "Release vX.Y.Z"
+6. Creates annotated tag `vX.Y.Z`
+7. Pushes commit and tag to remote
+8. Builds and publishes gem to RubyGems
+
+### Post-Release
+
+After running `bin/release`:
+
+1. Create GitHub release at the new tag
+2. Add `## [Unreleased]` section to CHANGELOG.md
+
+## Version Bumping Guidelines
+
+### When to Bump MAJOR (Breaking)
+
+- Removing public methods/classes
+- Changing method signatures (required params)
+- Changing return types
+- Renaming public constants
+- Dropping Ruby version support
+
+### When to Bump MINOR (Feature)
+
+- Adding new public methods/classes
+- Adding optional parameters
+- New configuration options
+- New message types or content blocks
+
+### When to Bump PATCH (Fix)
+
+- Bug fixes
+- Documentation corrections
+- Performance improvements (no API change)
+- Internal refactoring (no API change)
+
+## Example Release Workflow
+
+```bash
+# 1. Ensure tests pass
+bundle exec rake
+
+# 2. Update CHANGELOG.md
+# Add entry under [Unreleased], then rename to version:
+## [1.2.0] - 2025-03-15
+
+### Added
+- New `Client#foo` method for bar functionality
+
+### Fixed
+- Resolved timeout issue in subprocess transport
+
+# 3. Commit changelog
+git add CHANGELOG.md
+git commit -m "docs: update changelog for 1.2.0"
+
+# 4. Release
+bin/release 1.2.0
+
+# 5. Add new Unreleased section
+# Edit CHANGELOG.md to add:
+## [Unreleased]
+
+# 6. Commit
+git add CHANGELOG.md
+git commit -m "docs: add unreleased section"
+git push
+```
+
+## Gem Metadata
+
+The gemspec includes these URIs for RubyGems.org:
+
+```ruby
+spec.metadata["source_code_uri"] = spec.homepage
+spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+```
+
+This enables the "Changelog" link on the RubyGems.org gem page.

data/.claude/rules/testing.md

@@ -0,0 +1,267 @@
+# Testing Conventions
+
+SDK-specific testing guidance. For general patterns (base classes, mocking, structure), see `conventions.md`.
+
+## Running Tests
+
+```bash
+bundle exec rake test                                    # Unit tests only
+bundle exec rake test_integration                        # Integration tests (requires CLI v2.0.0+)
+bundle exec rake test_all                                # All tests
+bundle exec ruby -Itest test/claude_agent/test_foo.rb   # Single file
+
+# Binstubs
+bin/test                                                 # Unit tests only
+bin/test-integration                                     # Integration tests
+bin/test-all                                             # All tests
+```
+
+## Directory Structure
+
+```
+test/
+├── test_helper.rb              # Central setup, requires, base class
+├── integration_helper.rb       # Base class for integration tests
+├── support/                    # Shared mocks, test transports, helpers
+│   └── mock_transport.rb
+├── claude_agent/               # Unit tests (mirrors lib/claude_agent/)
+│   ├── test_client.rb
+│   ├── test_options.rb
+│   └── mcp/
+│       └── test_tool.rb
+├── integration/                # Integration tests (require Claude CLI)
+│   ├── test_query.rb
+│   ├── test_client.rb
+│   └── ...
+└── fixtures/                   # JSON fixtures for parser tests
+    ├── assistant_message.json
+    └── tool_use_response.json
+```
+
+## File Naming
+
+| Component     | Convention                         |
+|---------------|------------------------------------|
+| Test files    | `test_{module}.rb`                 |
+| Test classes  | `TestClaudeAgent{Module}`          |
+| Support files | `mock_{name}.rb`, `fake_{name}.rb` |
+
+## Extracting Test Support
+
+Large mocks and fakes belong in `test/support/`, not inline:
+
+```ruby
+# test/support/mock_transport.rb
+class MockTransport < ClaudeAgent::Transport::Base
+  attr_reader :written_messages
+
+  def initialize(responses: [])
+    super()
+    @responses = responses
+    @written_messages = []
+  end
+
+  def write(data)
+    @written_messages << JSON.parse(data)
+  end
+
+  def read_messages
+    @responses.each { |r| yield r }
+  end
+
+  # ... minimal interface implementation
+end
+```
+
+```ruby
+# test/test_helper.rb
+require "claude_agent"
+require "minitest/autorun"
+require "mocha/minitest"
+
+Dir[File.join(__dir__, "support", "**", "*.rb")].each { |f| require f }
+```
+
+## Testing Data.define Types
+
+This SDK uses `Data.define` for immutable message types:
+
+```ruby
+test "data type attributes" do
+  block = ClaudeAgent::TextBlock.new(text: "hello")
+
+  assert_equal "hello", block.text
+  assert_equal :text, block.type
+  assert block.frozen?
+  assert_equal({ type: "text", text: "hello" }, block.to_h)
+end
+
+test "optional fields default to nil" do
+  block = ClaudeAgent::ToolResultBlock.new(tool_use_id: "123")
+  assert_nil block.content
+  assert_nil block.is_error
+end
+```
+
+## Testing String and Symbol Keys
+
+JSON parses to string keys, Ruby prefers symbols. Always test both:
+
+```ruby
+test "accepts symbol keys" do
+  block = ClaudeAgent::ImageContentBlock.new(
+    source: { type: "base64", media_type: "image/png", data: "..." }
+  )
+  assert_equal "base64", block.source_type
+end
+
+test "accepts string keys" do
+  block = ClaudeAgent::ImageContentBlock.new(
+    source: { "type" => "base64", "media_type" => "image/png", "data" => "..." }
+  )
+  assert_equal "base64", block.source_type
+end
+```
+
+## Fixtures vs Inline Data
+
+**Use fixtures** for:
+- Complex JSON structures reused across tests
+- Large response payloads
+- Realistic CLI output samples
+
+**Use inline data** for:
+- Simple, single-use test cases
+- When the data structure IS the test (e.g., edge cases)
+
+```ruby
+# test/fixtures/assistant_with_tool_use.json
+{
+  "type": "assistant",
+  "message": {
+    "model": "claude",
+    "content": [
+      { "type": "text", "text": "Let me read that" },
+      { "type": "tool_use", "id": "tool_123", "name": "Read", "input": {} }
+    ]
+  }
+}
+```
+
+```ruby
+# Usage
+test "parses complex message" do
+  data = json_fixture("assistant_with_tool_use")
+  message = parser.parse(data)
+
+  assert message.has_tool_use?
+end
+```
+
+## Testing CLI Interaction
+
+### Prefer Mocha over manual mocks
+
+```ruby
+test "spawns subprocess with correct args" do
+  Process.expects(:spawn).with(
+    "claude", "--print", "--output-format", "json",
+    has_entries(chdir: Dir.pwd)
+  ).returns(123)
+
+  transport.start
+end
+```
+
+### Use MockTransport for Client tests
+
+```ruby
+test "sends user message" do
+  transport = MockTransport.new(responses: [result_message])
+  client = ClaudeAgent::Client.new(transport: transport)
+  client.connect
+
+  client.send_message("Hello")
+
+  assert_equal 1, transport.written_messages.size
+  assert_equal "user", transport.written_messages.first["type"]
+end
+```
+
+### Capturing I/O
+
+Use Minitest's built-in `capture_io`:
+
+```ruby
+test "logs to stderr" do
+  _, err = capture_io { client.send_message("test") }
+  assert_match(/sending message/, err)
+end
+```
+
+## Error Testing
+
+Test error hierarchy and context fields:
+
+```ruby
+test "error includes context" do
+  error = ClaudeAgent::ProcessError.new(
+    "CLI failed",
+    exit_code: 1,
+    stderr: "error details"
+  )
+
+  assert_equal 1, error.exit_code
+  assert_equal "error details", error.stderr
+  assert_match(/CLI failed/, error.message)
+end
+
+test "error inheritance" do
+  error = ClaudeAgent::ProcessError.new("test")
+  assert_kind_of ClaudeAgent::Error, error
+  assert_kind_of StandardError, error
+end
+```
+
+## Integration Tests
+
+Integration tests live in `test/integration/` and inherit from `IntegrationTestCase`:
+
+```ruby
+# test/integration/test_query.rb
+require_relative "../integration_helper"
+
+class TestIntegrationQuery < IntegrationTestCase
+  test "real query returns result" do
+    messages = ClaudeAgent.query(prompt: "Say hello", options: test_options).to_a
+    result = messages.find { |m| m.is_a?(ClaudeAgent::ResultMessage) }
+
+    assert_not_nil result
+    assert result.success?
+  end
+end
+```
+
+The `IntegrationTestCase` base class:
+- Skips tests unless `INTEGRATION=true` is set (automatic with `rake test_integration`)
+- Skips if Claude CLI is not installed
+- Provides `test_options` helper with sensible defaults
+
+## What to Test
+
+| Component      | Focus Areas                                 |
+|----------------|---------------------------------------------|
+| Options        | Default values, validation, CLI arg mapping |
+| Messages       | Parsing, field access, type discrimination  |
+| Content Blocks | All block types, to_h serialization         |
+| Client         | Message sending, streaming, error handling  |
+| Transport      | Process lifecycle, I/O handling             |
+| Errors         | Hierarchy, context fields, messages         |
+| MCP            | Tool definition, server config              |
+
+## Test Coverage Guidelines
+
+- High coverage on public API surface
+- Don't test private methods directly—test through public interface
+- Cover edge cases: nil values, empty collections, invalid input
+- Test both success and failure paths

data/.claude/settings.json

@@ -0,0 +1,49 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle:*)",
+      "Bash(gem:*)",
+      "Bash(rbs:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git show:*)",
+      "Bash(git status:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git branch:*)",
+      "Bash(git fetch:*)",
+      "Bash(git worktree:*)",
+      "Bash(git mv:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh run view:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(ps:*)",
+      "Bash(lsof:*)",
+      "Bash(wc:*)",
+      "Bash(mkdir:*)",
+      "Bash(bin/rbs-validate:*)",
+      "Bash(bin/setup:*)",
+      "Bash(bin/test:*)",
+      "Bash(bin/test-integration:*)",
+      "Bash(bin/test-all:*)",
+      "Bash(bin/update-reference-sdks:*)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:docs.claude.com)"
+    ],
+    "deny": [],
+    "ask": [],
+    "additionalDirectories": [],
+    "defaultMode": "default"
+  },
+  "hooks": {},
+  "env": {},
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  }
+}

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-10
+
+### Added
+- MVP implementation of the Claude Agent SDK for Ruby

data/CLAUDE.md

@@ -0,0 +1,94 @@
+# ClaudeAgent Ruby SDK
+
+Ruby SDK for building autonomous AI agents that interact with Claude Code CLI.
+
+## Stack
+
+- **Ruby** 3.2+ (uses `Data.define` for immutable types)
+- **Minitest** for testing
+- **RuboCop** with `rubocop-rails-omakase` for linting
+- **RBS** for type signatures (in `sig/`)
+- **No external API clients** - communicates with Claude Code CLI via JSON Lines protocol
+
+## Workflow
+
+```bash
+bin/setup                          # Install dependencies
+bundle exec rake                   # Run unit tests + rbs + rubocop (default)
+bundle exec rake test              # Unit tests only
+bundle exec rake test_integration  # Integration tests (requires CLI v2.0.0+)
+bundle exec rake test_all          # All tests (requires CLI v2.0.0+)
+bundle exec rake rbs               # Validate RBS signatures
+bundle exec rake rbs:parse         # RBS syntax check only (faster)
+bundle exec rake rbs:prototype     # Generate RBS from lib/ (for new code)
+bundle exec rubocop                # Lint only
+bin/console                        # IRB with gem loaded
+
+# Binstubs
+bin/test                           # Unit tests only
+bin/test-integration               # Integration tests
+bin/test-all                       # All tests
+bin/rbs-validate                   # Validate RBS signatures
+bin/release VERSION                # Release gem (e.g., bin/release 1.2.0)
+```
+
+## Architecture
+
+| Component                   | Purpose                                            |
+|-----------------------------|----------------------------------------------------|
+| `Query`                     | One-shot stateless prompts                         |
+| `Client`                    | Multi-turn bidirectional conversations             |
+| `ControlProtocol`           | Handles handshake, hooks, permissions, MCP routing |
+| `Transport::Subprocess`     | Spawns CLI, manages stdin/stdout                   |
+| `MCP::Tool` / `MCP::Server` | Custom tool definitions                            |
+
+## Conventions
+
+- **Immutable data types**: All messages and options use `Data.define`
+- **Frozen string literals**: Every file starts with `# frozen_string_literal: true`
+- **Message polymorphism**: Use `case` statements or `is_a?()` for content block types
+- **Error hierarchy**: All errors inherit from `ClaudeAgent::Error` with context (exit code, stderr, etc.)
+- **Protocol flow**: Transport → ControlProtocol → MessageParser → typed message objects
+
+## Key Patterns
+
+```ruby
+# One-shot query
+result = ClaudeAgent.query("prompt", model: "sonnet")
+
+# Interactive client
+client = ClaudeAgent::Client.new(options)
+client.send_message("prompt") { |msg| handle(msg) }
+
+# Content blocks are polymorphic
+message.content.each do |block|
+  case block
+  when ClaudeAgent::TextBlock then ...
+  when ClaudeAgent::ToolUseBlock then ...
+  end
+end
+```
+
+## Testing Notes
+
+- Unit tests in `test/claude_agent/` - run without Claude CLI
+- Integration tests in `test/integration/` - require Claude Code CLI v2.0.0+
+- Integration tests are skipped by default; set `INTEGRATION=true` to run them
+- Skip CLI version check with `CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK=true`
+
+## Releasing
+
+Uses [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/) format.
+
+```bash
+# 1. Update CHANGELOG.md with version entry
+# 2. Commit the changelog
+git commit -am "docs: update changelog for X.Y.Z"
+
+# 3. Run the release script
+bin/release X.Y.Z
+```
+
+The release script validates the changelog, updates version.rb, commits, tags, and publishes to RubyGems.
+
+See `.claude/rules/releases.md` for detailed conventions.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Thomas Carr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.