claude_agent 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72db3aeea7a724d0271a3fc8bb0bd7900425a34e7114e526e9bfe8bbbe26e19f
-  data.tar.gz: a31e9321dc56507d0a05d8319e50fded02aaa420a9709a0970a298826ea2f4ad
+  metadata.gz: db922e35ad5e88546f17fe9d51a42d05ea0dbe5ae5b13f0f9733857b5bc467b2
+  data.tar.gz: 55b2aceec109d36a624fb0c2fa1979b440f05758e01b894f962b5c27c02bfdb9
 SHA512:
-  metadata.gz: 54d586a6a4e368adf4b64ec8afdbf4b04ad165473e81bcf8e0c244c7c04ac5c524b6c1186e34dd7bf6c31cc3b521da6d5526b187a30d147c3839ba5b708056ae
-  data.tar.gz: 4af34d4756c9559570ea9c8d0ed9819ae98827773eed4332d9cc7bc50c8b5edc6584c0ee25fbfa197c3bc79513acace10ee88ec3bf1674141afcfe213ead2f02
+  metadata.gz: 1163853d431c1203309bb1926204034c9a77ab581deb52f3400cb266751a18a308be66342e8a31f7d2eae1a30767f68fb0255df35844097d733e34397345e56a
+  data.tar.gz: 8c99d3eb98b28a31abfd704e800fc8df816132037d8c30329a2f575a88b2debe02afd3dde48842edfcd78235268484e638119209712e9a82dccde725b0f908a4

data/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-02-03
+
 ## [0.7.0] - 2026-01-31
 
 ### Added

data/SPEC.md

@@ -3,11 +3,11 @@
 This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
 
 **Reference Versions:**
-- TypeScript SDK: v0.2.27 (npm package)
-- Python SDK: v0.1.26 from GitHub (commit 438ddf7)
+- TypeScript SDK: v0.2.31 (npm package)
+- Python SDK: v0.1.29 from GitHub (commit 7519c96)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-01-31
+**Last Updated:** 2026-02-03
 
 ---
 
@@ -80,6 +80,8 @@ Configuration options for SDK queries and clients.
 | `init`                            |     ✅      |   ❌    |  ✅   | Run Setup hooks (init trigger), then continue (hidden CLI)   |
 | `initOnly`                        |     ✅      |   ❌    |  ✅   | Run Setup hooks (init trigger), then exit (hidden CLI)       |
 | `maintenance`                     |     ✅      |   ❌    |  ✅   | Run Setup hooks (maintenance trigger), continue (hidden CLI) |
+| `debug`                           |     ✅      |   ❌    |  ✅   | Enable verbose debug logging                                 |
+| `debugFile`                       |     ✅      |   ❌    |  ✅   | Write debug logs to specific file path                       |
 
 ---
 
@@ -126,6 +128,7 @@ Messages exchanged between SDK and CLI.
 | `errors`             |     ✅      |   ❌    |  ✅   | Error messages           |
 | `uuid`               |     ✅      |   ❌    |  ✅   | Message UUID             |
 | `session_id`         |     ✅      |   ✅    |  ✅   | Session ID               |
+| `stop_reason`        |     ✅      |   ❌    |  ✅   | Why model stopped        |
 
 #### Result Subtypes
 
@@ -249,15 +252,15 @@ Event hooks for intercepting and modifying SDK behavior.
 | `PreToolUse`         |     ✅      |   ✅    |  ✅   | Before tool execution     |
 | `PostToolUse`        |     ✅      |   ✅    |  ✅   | After tool execution      |
 | `PostToolUseFailure` |     ✅      |   ✅    |  ✅   | After tool failure        |
-| `Notification`       |     ✅      |   ❌    |  ✅   | System notifications      |
+| `Notification`       |     ✅      |   ✅    |  ✅   | System notifications      |
 | `UserPromptSubmit`   |     ✅      |   ✅    |  ✅   | User message submitted    |
 | `SessionStart`       |     ✅      |   ❌    |  ✅   | Session starts            |
 | `SessionEnd`         |     ✅      |   ❌    |  ✅   | Session ends              |
 | `Stop`               |     ✅      |   ✅    |  ✅   | Agent stops               |
-| `SubagentStart`      |     ✅      |   ❌    |  ✅   | Subagent starts           |
+| `SubagentStart`      |     ✅      |   ✅    |  ✅   | Subagent starts           |
 | `SubagentStop`       |     ✅      |   ✅    |  ✅   | Subagent stops            |
 | `PreCompact`         |     ✅      |   ✅    |  ✅   | Before compaction         |
-| `PermissionRequest`  |     ✅      |   ❌    |  ✅   | Permission requested      |
+| `PermissionRequest`  |     ✅      |   ✅    |  ✅   | Permission requested      |
 | `Setup`              |     ✅      |   ❌    |  ✅   | Initial setup/maintenance |
 
 ### Hook Input Types
@@ -267,15 +270,15 @@ Event hooks for intercepting and modifying SDK behavior.
 | `PreToolUseHookInput`         |     ✅      |   ✅    |  ✅   |
 | `PostToolUseHookInput`        |     ✅      |   ✅    |  ✅   |
 | `PostToolUseFailureHookInput` |     ✅      |   ✅    |  ✅   |
-| `NotificationHookInput`       |     ✅      |   ❌    |  ✅   |
+| `NotificationHookInput`       |     ✅      |   ✅    |  ✅   |
 | `UserPromptSubmitHookInput`   |     ✅      |   ✅    |  ✅   |
 | `SessionStartHookInput`       |     ✅      |   ❌    |  ✅   |
 | `SessionEndHookInput`         |     ✅      |   ❌    |  ✅   |
 | `StopHookInput`               |     ✅      |   ✅    |  ✅   |
-| `SubagentStartHookInput`      |     ✅      |   ❌    |  ✅   |
+| `SubagentStartHookInput`      |     ✅      |   ✅    |  ✅   |
 | `SubagentStopHookInput`       |     ✅      |   ✅    |  ✅   |
 | `PreCompactHookInput`         |     ✅      |   ✅    |  ✅   |
-| `PermissionRequestHookInput`  |     ✅      |   ❌    |  ✅   |
+| `PermissionRequestHookInput`  |     ✅      |   ✅    |  ✅   |
 | `SetupHookInput`              |     ✅      |   ❌    |  ✅   |
 
 ### Hook Output Types
@@ -655,46 +658,21 @@ Public API surface for SDK clients.
 - Primary reference for API surface (most comprehensive)
 - Source is bundled/minified, but `sdk.d.ts` provides complete type definitions
 - Includes unstable V2 session API
-- Adds `deno` as supported executable option
-- Includes experimental `criticalSystemReminder_EXPERIMENTAL` for agent definitions
-- `SessionStartHookInput` includes `model` field
-- v0.2.12+ adds `Setup` hook event for init/maintenance
-- v0.2.12+ adds `skills` and `maxTurns` to AgentDefinition
-- v0.2.12+ adds `TaskNotificationMessage` for background task completion
-- v0.2.12+ adds `user` option to SDKSessionOptions
-- v0.2.19 adds `mcp_reconnect` and `mcp_toggle` control requests
-- v0.2.19 adds `HookStartedMessage`, `HookProgressMessage`, and `ToolUseSummaryMessage`
-- v0.2.25 adds `SDKFilesPersistedEvent` message type for file persistence confirmation
-- v0.2.25 adds `McpClaudeAIProxyServerConfig` (`claudeai-proxy` type) for managed proxy servers
-- v0.2.21 adds `reconnectMcpServer()` and `toggleMcpServer()` query methods
-- v0.2.21 adds `config`, `scope`, `tools` fields and `disabled` status to `McpServerStatus`
-- v0.2.27 adds optional `annotations` support to `tool()` helper for MCP tool hints
+- `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
 
 ### Python SDK
-- Full source available (v0.1.26)
-- Now has `Transport` abstract class and several query control methods
-- Supports `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`, `stream_input()`, `close()`, `get_mcp_status()` in query
-- Client also supports `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`
-- Does not support SessionStart/SessionEnd/Notification/SubagentStart/PermissionRequest/Setup hooks
-- Missing several permission modes (delegate, dontAsk)
-- Missing `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `strictMcpConfig`
-- Missing `init`/`initOnly`/`maintenance` Setup hook options
-- `excludedCommands` in sandbox now supported
-- v0.1.25 adds `PostToolUseFailure` hook event support
-- v0.1.25 adds `permissionDecisionReason` to `PreToolUseHookSpecificOutput`
-- v0.1.26 bumps bundled CLI to v2.1.27 (no new SDK features beyond PostToolUseFailure)
-- `additionalContext` supported in `UserPromptSubmitHookSpecificOutput`
-- `PreToolUseHookInput` does not include `tool_use_id` (unlike TypeScript)
+- Full source available
+- Has `Transport` abstract class and several query control methods
+- Query supports: `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`, `stream_input()`, `close()`, `get_mcp_status()`
+- Client supports: `interrupt()`, `set_permission_mode()`, `set_model()`, `rewind_files()`, `get_mcp_status()`
+- Missing hooks: SessionStart, SessionEnd, Setup
+- Missing permission modes: `delegate`, `dontAsk`
+- Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`
 - `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`
 
 ### Ruby SDK (This Repository)
-- Full TypeScript SDK feature parity
+- Full TypeScript SDK v0.2.31 feature parity
 - Ruby-idiomatic patterns (Data.define, snake_case)
-- Complete control protocol support
+- Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations
-- Full hook event support including all 13 events
-- Full V2 Session API support (unstable)
-- `executable`/`executableArgs` marked N/A (JS runtime options not applicable to Ruby)
-- Added: `FilesPersistedEvent` message type (new in TS v0.2.25)
-- `claudeai-proxy` MCP server type handled transparently via Hash-based config passthrough (new in TS v0.2.25)
-- Added: MCP tool `annotations` support (new in TS v0.2.27)
+- `executable`/`executableArgs` marked N/A (JS runtime options)

data/lib/claude_agent/message_parser.rb

@@ -143,7 +143,8 @@ module ClaudeAgent
         structured_output: fetch_dual(raw, :structured_output),
         errors: raw["errors"],
         permission_denials: permission_denials,
-        model_usage: fetch_dual(raw, :model_usage)
+        model_usage: fetch_dual(raw, :model_usage),
+        stop_reason: fetch_dual(raw, :stop_reason)
       )
     end
 

data/lib/claude_agent/messages.rb

@@ -181,7 +181,8 @@ module ClaudeAgent
     :structured_output,
     :errors,             # Array<String> for error subtypes
     :permission_denials, # Array<SDKPermissionDenial>
-    :model_usage         # Hash with per-model usage breakdown
+    :model_usage,        # Hash with per-model usage breakdown
+    :stop_reason         # Why the model stopped generating (TypeScript SDK parity)
   ) do
     def initialize(
       subtype:,
@@ -196,7 +197,8 @@ module ClaudeAgent
       structured_output: nil,
       errors: nil,
       permission_denials: nil,
-      model_usage: nil
+      model_usage: nil,
+      stop_reason: nil
     )
       super
     end

data/lib/claude_agent/options.rb

@@ -41,7 +41,9 @@ module ClaudeAgent
       betas: [],
       init: false,
       init_only: false,
-      maintenance: false
+      maintenance: false,
+      debug: false,
+      debug_file: nil
     }.freeze
 
     # All configurable attributes
@@ -59,6 +61,7 @@ module ClaudeAgent
       persist_session betas max_buffer_size stderr_callback
       abort_controller spawn_claude_code_process
       init init_only maintenance
+      debug debug_file
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -88,6 +91,7 @@ module ClaudeAgent
         args.concat(environment_args)
         args.concat(output_args)
         args.concat(setup_hook_args)
+        args.concat(debug_args)
         args.concat(extra_cli_args)
       end
     end
@@ -243,6 +247,13 @@ module ClaudeAgent
       end
     end
 
+    def debug_args
+      [].tap do |args|
+        args.push("--debug") if debug
+        args.push("--debug-file", debug_file) if debug_file
+      end
+    end
+
     def extra_cli_args
       [].tap do |args|
         extra_args.each do |key, value|

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

data/sig/claude_agent.rbs

@@ -301,6 +301,8 @@ module ClaudeAgent
     # Buffering & debugging
     attr_accessor max_buffer_size: Integer?
     attr_accessor stderr_callback: (^(String) -> void)?
+    attr_accessor debug: bool
+    attr_accessor debug_file: String?
 
     # Abort control (TypeScript SDK parity)
     attr_accessor abort_controller: AbortController?
@@ -463,6 +465,7 @@ module ClaudeAgent
     attr_reader errors: Array[String]?
     attr_reader permission_denials: Array[SDKPermissionDenial]?
     attr_reader model_usage: Hash[String, untyped]?
+    attr_reader stop_reason: String?
 
     def initialize: (
       subtype: String,
@@ -477,7 +480,8 @@ module ClaudeAgent
       ?structured_output: untyped,
       ?errors: Array[String]?,
       ?permission_denials: Array[SDKPermissionDenial]?,
-      ?model_usage: Hash[String, untyped]?
+      ?model_usage: Hash[String, untyped]?,
+      ?stop_reason: String?
     ) -> void
 
     def type: () -> :result

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Thomas Carr