claude_agent 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2d8740456b8efad6aadef1d23c3979de66aac32836f40d87db7f9d5766505fb
-  data.tar.gz: aaed4a958504810589552f424094edf52d86732f81780d5525208dab297cb964
+  metadata.gz: 3d8b88e03dcf883a968958f700a7dd765fbdae8553934b45e967594ad81f9bba
+  data.tar.gz: fd16c0e625ed0df2c548c39378e167af73a21c2fa6d7b61cacc351d9cbde78d2
 SHA512:
-  metadata.gz: a4b3f2d325aad7faa519896e90016a9518ad8285a45dd315936712f0e10548cb2fec0ba77efb191b86aeb265a2bdb43ecb9bb49115efe097092a2fe5a0d250cb
-  data.tar.gz: f98723ebf5568c280ac6ea69b767da4d1065760a9eeee1d3ad990191d3553ddbf8deb3ee6cca36a1cd08fe0c8e82125026ec4ba95c158abe36406b8ec173fead
+  metadata.gz: e4c7ba1adad712135d2934405b758324f2477e71b7914769deb07ba07fe4a025ca11f2c04a0ec46e3d2fe6954cf02288097ef914eb62c7874aca229aa4cd9c6c
+  data.tar.gz: c608d6c49ffb80c0c0aa96a4dca2f042f280060a73f473e271b1b0d099a368239fedf3194264f82f825fc5d8d76dfa4986c44563929f3a83f09773af96f84654

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-02-07
+
+### Added
+- Configurable logging via `ClaudeAgent.logger` (module-level) and `Options#logger` (per-query)
+  - `NullLogger` default for zero overhead when logging is not configured
+  - `ClaudeAgent.debug!` convenience method for quick stderr debug logging
+  - Backward-compatible with `CLAUDE_AGENT_DEBUG` env var
+  - Log points across transport, control protocol, message parser, MCP server, query, and client
+
+### Fixed
+- `can_use_tool` callback now works without hooks or MCP servers configured
+  - `PermissionResultAllow` and `PermissionResultDeny` (`Data.define` types) are now correctly recognized in `handle_can_use_tool` instead of silently falling through to allow
+  - `normalize_hook_response` now handles `Data.define` return types from hook callbacks
+- Allow responses without explicit `updated_input` now fall back to the original input (Python SDK parity)
+
+### Changed
+- Always use streaming mode with control protocol initialization (Python/TypeScript SDK parity)
+  - Removes fragile conditional gate on hooks/MCP/can_use_tool
+  - `send_initialize` handshake is now always sent in streaming mode
+
+### Added
+- Auto-set `permission_prompt_tool_name` to `"stdio"` when `can_use_tool` is configured (Python/TypeScript SDK parity)
+
 ## [0.7.3] - 2026-02-06
 
 ### Added

data/README.md

@@ -818,6 +818,61 @@ session = ClaudeAgent.unstable_v2_create_session(options)
 | `RewindFilesResult`   | Result of rewind_files (can_rewind, error, files_changed, insertions, deletions) |
 | `SDKPermissionDenial` | Permission denial info (tool_name, tool_use_id, tool_input)                      |
 
+## Logging
+
+The SDK includes optional logging with zero overhead when disabled. All log output is silent by default.
+
+### Quick Debug
+
+```ruby
+# Enable debug logging to stderr
+ClaudeAgent.debug!
+
+# Or to a file
+ClaudeAgent.debug!(output: File.open("claude_agent.log", "a"))
+```
+
+### Custom Logger
+
+Set any `Logger`-compatible instance at the module level:
+
+```ruby
+ClaudeAgent.logger = Logger.new($stderr, level: :info)
+```
+
+### Per-Query Logger
+
+Override the module-level logger for a specific query or client:
+
+```ruby
+my_logger = Logger.new("query.log", level: :debug)
+
+ClaudeAgent.query(prompt: "Hello", options: ClaudeAgent::Options.new(logger: my_logger))
+
+# Or with Client
+client = ClaudeAgent::Client.new(options: ClaudeAgent::Options.new(logger: my_logger))
+```
+
+### Log Output
+
+When enabled, the SDK logs events across transport, protocol, parsing, MCP, and query layers:
+
+```
+[ClaudeAgent] [12:00:00.123] INFO  -- transport: Process spawned (pid=12345)
+[ClaudeAgent] [12:00:00.456] DEBUG -- protocol: Sending control request: initialize (req_1_abc)
+[ClaudeAgent] [12:00:01.789] INFO  -- protocol: Permission decision for Bash: allow
+[ClaudeAgent] [12:00:02.100] INFO  -- query: Query complete (3.45s, cost=$0.012)
+```
+
+### Log Levels
+
+| Level | What's Logged |
+|-------|---------------|
+| ERROR | Control request failures, unknown message types |
+| WARN  | Force kills, JSON parse errors during buffering, unknown MCP tools |
+| INFO  | Process spawn/close, protocol start/stop, permission decisions, tool calls, query start/completion with timing |
+| DEBUG | Full commands, message types received, control request/response routing, reader thread lifecycle |
+
 ## Environment Variables
 
 The SDK sets these automatically:
@@ -825,6 +880,12 @@ The SDK sets these automatically:
 - `CLAUDE_CODE_ENTRYPOINT=sdk-rb`
 - `CLAUDE_AGENT_SDK_VERSION=<version>`
 
+Enable debug logging via environment variable:
+
+```bash
+export CLAUDE_AGENT_DEBUG=1
+```
+
 Skip version checking (for development):
 
 ```bash

data/Rakefile

@@ -43,7 +43,7 @@ RuboCop::RakeTask.new
 namespace :rbs do
   desc "Validate RBS signatures (syntax + type resolution)"
   task :validate do
-    sh "bundle exec rbs -I sig validate"
+    sh "bundle exec rbs -r logger -I sig validate"
   end
 
   desc "Parse RBS files (syntax check only, faster)"

data/SPEC.md

@@ -7,7 +7,7 @@ This document provides a comprehensive specification of the Claude Agent SDK, co
 - Python SDK: v0.1.31 from GitHub (commit 4b19642)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-02-06
+**Last Updated:** 2026-02-07
 
 ---
 
@@ -37,7 +37,7 @@ Configuration options for SDK queries and clients.
 | `model`                           |     ✅      |   ✅    |  ✅   | Claude model identifier                                      |
 | `fallbackModel`                   |     ✅      |   ✅    |  ✅   | Fallback if primary fails                                    |
 | `systemPrompt`                    |     ✅      |   ✅    |  ✅   | String or preset object                                      |
-| `appendSystemPrompt`              |     ✅      |   ❌    |  ✅   | Append to system prompt (TS SDK has via preset)              |
+| `appendSystemPrompt`              |     ✅      |   ✅    |  ✅   | Append to system prompt (via preset)                         |
 | `tools`                           |     ✅      |   ✅    |  ✅   | Array or preset                                              |
 | `allowedTools`                    |     ✅      |   ✅    |  ✅   | Auto-allowed tools                                           |
 | `disallowedTools`                 |     ✅      |   ✅    |  ✅   | Blocked tools                                                |
@@ -249,23 +249,23 @@ Event hooks for intercepting and modifying SDK behavior.
 
 ### Hook Events
 
-| Event                | TypeScript | Python | Ruby | Notes                     |
-|----------------------|:----------:|:------:|:----:|---------------------------|
-| `PreToolUse`         |     ✅      |   ✅    |  ✅   | Before tool execution     |
-| `PostToolUse`        |     ✅      |   ✅    |  ✅   | After tool execution      |
-| `PostToolUseFailure` |     ✅      |   ✅    |  ✅   | After tool failure        |
-| `Notification`       |     ✅      |   ✅    |  ✅   | System notifications      |
-| `UserPromptSubmit`   |     ✅      |   ✅    |  ✅   | User message submitted    |
-| `SessionStart`       |     ✅      |   ❌    |  ✅   | Session starts            |
-| `SessionEnd`         |     ✅      |   ❌    |  ✅   | Session ends              |
-| `Stop`               |     ✅      |   ✅    |  ✅   | Agent stops               |
-| `SubagentStart`      |     ✅      |   ✅    |  ✅   | Subagent starts           |
-| `SubagentStop`       |     ✅      |   ✅    |  ✅   | Subagent stops            |
-| `PreCompact`         |     ✅      |   ✅    |  ✅   | Before compaction         |
-| `PermissionRequest`  |     ✅      |   ✅    |  ✅   | Permission requested      |
-| `Setup`              |     ✅      |   ❌    |  ✅   | Initial setup/maintenance |
-| `TeammateIdle`       |     ✅      |   ❌    |  ✅   | Teammate idle (v0.2.33)   |
-| `TaskCompleted`      |     ✅      |   ❌    |  ✅   | Task completed (v0.2.33)  |
+| Event                | TypeScript | Python | Ruby | Notes                             |
+|----------------------|:----------:|:------:|:----:|-----------------------------------|
+| `PreToolUse`         |     ✅      |   ✅    |  ✅   | Before tool execution             |
+| `PostToolUse`        |     ✅      |   ✅    |  ✅   | After tool execution              |
+| `PostToolUseFailure` |     ✅      |   ✅    |  ✅   | After tool failure (Py v0.1.26)   |
+| `Notification`       |     ✅      |   ✅    |  ✅   | System notifications (Py v0.1.29) |
+| `UserPromptSubmit`   |     ✅      |   ✅    |  ✅   | User message submitted            |
+| `SessionStart`       |     ✅      |   ❌    |  ✅   | Session starts                    |
+| `SessionEnd`         |     ✅      |   ❌    |  ✅   | Session ends                      |
+| `Stop`               |     ✅      |   ✅    |  ✅   | Agent stops                       |
+| `SubagentStart`      |     ✅      |   ✅    |  ✅   | Subagent starts (Py v0.1.29)      |
+| `SubagentStop`       |     ✅      |   ✅    |  ✅   | Subagent stops                    |
+| `PreCompact`         |     ✅      |   ✅    |  ✅   | Before compaction                 |
+| `PermissionRequest`  |     ✅      |   ✅    |  ✅   | Permission requested (Py v0.1.29) |
+| `Setup`              |     ✅      |   ❌    |  ✅   | Initial setup/maintenance         |
+| `TeammateIdle`       |     ✅      |   ❌    |  ✅   | Teammate idle (v0.2.33)           |
+| `TaskCompleted`      |     ✅      |   ❌    |  ✅   | Task completed (v0.2.33)          |
 
 ### Hook Input Types
 
@@ -631,16 +631,16 @@ Public API surface for SDK clients.
 
 ### Client Class
 
-| Feature              | TypeScript |       Python        |          Ruby           | Notes                                                                            |
-|----------------------|:----------:|:-------------------:|:-----------------------:|----------------------------------------------------------------------------------|
-| Multi-turn client    |     ❌      | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions                                                             |
-| `connect()`          |    N/A     |          ✅          |            ✅            | Start session                                                                    |
-| `disconnect()`       |    N/A     |          ✅          |            ✅            | End session                                                                      |
-| `send_message()`     |    N/A     |          ✅          |            ✅            | Send user message                                                                |
-| `receive_response()` |    N/A     |          ✅          |            ✅            | Receive until result                                                             |
-| `stream_input()`     |    N/A     |          ❌          |            ✅            | Stream input messages                                                            |
-| `abort!()`           |    N/A     |          ❌          |            ✅            | Abort operations                                                                 |
-| Control methods      |    N/A     |       Partial       |            ✅            | interrupt, setPermissionMode, setModel, rewindFiles (Python); all methods (Ruby) |
+| Feature              | TypeScript |       Python        |          Ruby           | Notes                                                                               |
+|----------------------|:----------:|:-------------------:|:-----------------------:|-------------------------------------------------------------------------------------|
+| Multi-turn client    |     ❌      | ✅ `ClaudeSDKClient` | ✅ `ClaudeAgent::Client` | Interactive sessions                                                                |
+| `connect()`          |    N/A     |          ✅          |            ✅            | Start session                                                                       |
+| `disconnect()`       |    N/A     |          ✅          |            ✅            | End session                                                                         |
+| `send_message()`     |    N/A     |          ✅          |            ✅            | Send user message                                                                   |
+| `receive_response()` |    N/A     |          ✅          |            ✅            | Receive until result                                                                |
+| `stream_input()`     |    N/A     |          ❌          |            ✅            | Stream input messages                                                               |
+| `abort!()`           |    N/A     |          ❌          |            ✅            | Abort operations                                                                    |
+| Control methods      |    N/A     |       Partial       |            ✅            | interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus (Python); all (Ruby) |
 
 ### Transport
 
@@ -670,16 +670,13 @@ Public API surface for SDK clients.
 - `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
 
 ### Python SDK
-- 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()`, `get_server_info()`
+- Full source available with `Transport` abstract class
+- Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus
 - Missing hooks: SessionStart, SessionEnd, Setup, TeammateIdle, TaskCompleted
 - Missing permission modes: `delegate`, `dontAsk`
 - Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`
-- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`
-- Has `additionalContext` in `PreToolUseHookSpecificOutput` (added in v0.1.30)
-- Has `create_sdk_mcp_server`, `tool()` helper, and MCP tool annotations (added in v0.1.30/v0.1.31)
+- `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`
+- Has SDK MCP server support with `tool()` helper and annotations
 
 ### Ruby SDK (This Repository)
 - Full TypeScript SDK v0.2.34 feature parity (v0.2.34 contains no new SDK features beyond a Claude Code version bump)

data/lib/claude_agent/client.rb

@@ -72,9 +72,11 @@ module ClaudeAgent
 
       ENV["CLAUDE_CODE_ENTRYPOINT"] = "sdk-rb-client"
 
+      logger.info("client") { "Connecting" }
       @protocol = ControlProtocol.new(transport: @transport, options: @options)
       @server_info = @protocol.start(streaming: true)
       @connected = true
+      logger.info("client") { "Connected" }
 
       send_message(prompt) if prompt
     end
@@ -85,6 +87,7 @@ module ClaudeAgent
     def disconnect
       return unless @connected
 
+      logger.info("client") { "Disconnecting" }
       @protocol&.stop
       @protocol = nil
       @connected = false
@@ -105,6 +108,7 @@ module ClaudeAgent
     # @return [void]
     def send_message(content, session_id: "default", uuid: nil)
       require_connection!
+      logger.debug("client") { "Sending message (session=#{session_id})" }
       @protocol.send_user_message(content, session_id: session_id, uuid: uuid)
     end
 
@@ -336,6 +340,10 @@ module ClaudeAgent
 
     private
 
+    def logger
+      @options.effective_logger
+    end
+
     def require_connection!
       raise CLIConnectionError, "Not connected" unless @connected
     end

data/lib/claude_agent/control_protocol.rb

@@ -30,7 +30,7 @@ module ClaudeAgent
     def initialize(transport:, options: nil)
       @transport = transport
       @options = options || Options.new
-      @parser = MessageParser.new
+      @parser = MessageParser.new(logger: @options.effective_logger)
       @server_info = nil
 
       # Control protocol state
@@ -57,15 +57,18 @@ module ClaudeAgent
     # @param prompt [String, nil] Initial prompt for non-streaming mode
     # @return [Hash, nil] Server info from initialization
     def start(streaming: true, prompt: nil)
+      logger.info("protocol") { "Starting control protocol (streaming=#{streaming})" }
       @transport.connect(streaming: streaming, prompt: prompt)
       @running = true
 
       # Start background reader thread
       @reader_thread = Thread.new { reader_loop }
+      logger.debug("protocol") { "Reader thread started" }
 
-      # Initialize if we have hooks or SDK MCP servers
-      if streaming && (options.has_hooks? || options.has_sdk_mcp_servers?)
+      # Always send initialize in streaming mode (Python/TypeScript SDK parity)
+      if streaming
         @server_info = send_initialize
+        logger.info("protocol") { "Initialize complete" }
       end
 
       @server_info
@@ -74,6 +77,7 @@ module ClaudeAgent
     # Stop the control protocol
     # @return [void]
     def stop
+      logger.info("protocol") { "Stopping control protocol" }
       @running = false
       @transport.end_input
       @reader_thread&.join(5)
@@ -143,8 +147,7 @@ module ClaudeAgent
           # Re-raise abort errors
           raise
         rescue => e
-          # Log parsing errors but continue
-          warn "[ClaudeAgent] Message parse error: #{e.message}" if ENV["CLAUDE_AGENT_DEBUG"]
+          logger.warn("protocol") { "Message parse error: #{e.message}" }
         end
       end
     end
@@ -457,16 +460,9 @@ module ClaudeAgent
     #
     def set_mcp_servers(servers)
       # Convert servers hash to format expected by CLI
-      servers_config = servers.transform_values do |config|
-        if config.is_a?(Hash)
-          # Skip SDK servers (they're handled locally) - only send process-based servers
-          next nil if config[:type] == "sdk" || config["type"] == "sdk"
-
-          config
-        else
-          config
-        end
-      end.compact
+      servers_config = servers.reject do |_, config|
+        config.is_a?(Hash) && (config[:type] == "sdk" || config["type"] == "sdk")
+      end
 
       response = send_control_request(subtype: "mcp_set_servers", servers: servers_config)
 
@@ -479,6 +475,10 @@ module ClaudeAgent
 
     private
 
+    def logger
+      @options.effective_logger
+    end
+
     # Background thread that reads messages and routes them
     def reader_loop
       @transport.read_messages do |raw|
@@ -491,19 +491,22 @@ module ClaudeAgent
         break unless @running
 
         if raw["type"] == "control_request"
+          logger.debug("protocol") { "Control request received: #{raw.dig("request", "subtype")}" }
           handle_control_request(raw)
         elsif raw["type"] == "control_response"
+          logger.debug("protocol") { "Control response received: #{raw.dig("response", "request_id")}" }
           handle_control_response(raw)
         else
           # SDK message - queue for consumer
+          logger.debug("protocol") { "Queued message: #{raw["type"]}" }
           @message_queue.push(raw)
         end
       end
     rescue IOError, Errno::EPIPE
-      # Transport closed
+      logger.debug("protocol") { "Reader thread exiting: transport closed" }
       @running = false
     rescue AbortError
-      # Abort signal raised
+      logger.debug("protocol") { "Reader thread exiting: abort signal" }
       @running = false
     end
 
@@ -572,7 +575,10 @@ module ClaudeAgent
     # @param request [Hash] Request data
     # @return [Hash] Response
     def handle_can_use_tool(request)
-      return { behavior: "allow" } unless options.can_use_tool
+      unless options.can_use_tool
+        logger.info("protocol") { "Permission decision for #{request["tool_name"]}: allow (no callback)" }
+        return { behavior: "allow" }
+      end
 
       tool_name = request["tool_name"]
       input = request["input"] || {}
@@ -587,27 +593,14 @@ module ClaudeAgent
 
       result = options.can_use_tool.call(tool_name, input, context)
 
-      # Normalize result
-      if result.is_a?(Hash)
-        if result[:behavior] == "allow"
-          response = { behavior: "allow" }
-          response[:updatedInput] = result[:updated_input] if result[:updated_input]
-          if result[:updated_permissions]
-            response[:updatedPermissions] = result[:updated_permissions].map do |p|
-              p.respond_to?(:to_h) ? p.to_h : p
-            end
-          end
-          response
-        else
-          {
-            behavior: "deny",
-            message: result[:message] || "",
-            interrupt: result[:interrupt] || false
-          }
-        end
-      else
-        { behavior: "allow" }
+      normalized = result.to_h
+      logger.info("protocol") { "Permission decision for #{tool_name}: #{normalized[:behavior]}" }
+
+      if normalized[:behavior] == "allow" && !normalized.key?(:updatedInput)
+        normalized[:updatedInput] = input
       end
+
+      normalized
     end
 
     # Handle hook callback request
@@ -619,7 +612,11 @@ module ClaudeAgent
       tool_use_id = request["tool_use_id"]
 
       callback = @hook_callbacks[callback_id]
-      return {} unless callback
+      unless callback
+        logger.debug("protocol") { "Hook callback not found: #{callback_id}" }
+        return {}
+      end
+      logger.debug("protocol") { "Hook callback: #{callback_id}" }
 
       context = { tool_use_id: tool_use_id }
       result = callback.call(input, context)
@@ -634,6 +631,7 @@ module ClaudeAgent
     def handle_mcp_message(request)
       server_name = request["server_name"]
       message = request["message"]
+      logger.debug("protocol") { "MCP message for #{server_name}: #{message["method"]}" }
 
       # Find SDK MCP server
       server_config = options.mcp_servers[server_name]
@@ -667,6 +665,8 @@ module ClaudeAgent
     # @param result [Hash] Raw result from callback
     # @return [Hash] Normalized response
     def normalize_hook_response(result)
+      result = result.to_h
+
       response = HOOK_RESPONSE_KEYS.each_with_object({}) do |(ruby_key, json_key), acc|
         acc[json_key] = result[ruby_key] if result.key?(ruby_key)
       end
@@ -713,6 +713,7 @@ module ClaudeAgent
       @abort_signal&.check!
 
       request_id = generate_request_id
+      logger.debug("protocol") { "Sending control request: #{subtype} (#{request_id})" }
 
       request = {
         type: "control_request",
@@ -749,6 +750,7 @@ module ClaudeAgent
       end
 
       if response["subtype"] == "error"
+        logger.error("protocol") { "Control request failed: #{subtype} - #{response["error"]}" }
         raise Error, response["error"] || "Unknown error"
       end
 

data/lib/claude_agent/logging.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module ClaudeAgent
+  # Null logger that discards all output with zero overhead.
+  #
+  # All log methods return +true+ immediately without performing any I/O.
+  # This is the default logger, ensuring logging adds no cost when not configured.
+  #
+  # @example
+  #   logger = ClaudeAgent::NullLogger.new
+  #   logger.info("transport") { "This is discarded" }  # => true
+  #
+  class NullLogger < Logger
+    def initialize
+      super(File::NULL)
+      @level = Logger::DEBUG
+    end
+
+    def add(_severity = nil, _message = nil, _progname = nil)
+      true
+    end
+
+    def debug(...)  = true
+    def info(...)   = true
+    def warn(...)   = true
+    def error(...)  = true
+    def fatal(...)  = true
+    def unknown(...) = true
+
+    def debug?  = false
+    def info?   = false
+    def warn?   = false
+    def error?  = false
+    def fatal?  = false
+  end
+
+  # Compact log formatter with gem name tag.
+  #
+  # Output format:
+  #   [ClaudeAgent] [12:00:00.123] DEBUG -- transport: Spawning CLI
+  #
+  LOG_FORMATTER = proc do |severity, time, progname, msg|
+    "[ClaudeAgent] [#{time.strftime("%H:%M:%S.%L")}] #{severity.ljust(5)} -- #{progname}: #{msg}\n"
+  end
+
+  class << self
+    # Module-level logger used by all components unless overridden per-query.
+    #
+    # Defaults to {NullLogger} for zero overhead. Set to any +Logger+-compatible
+    # instance to enable logging.
+    #
+    # @return [Logger]
+    #
+    # @example
+    #   ClaudeAgent.logger = Logger.new($stderr, level: :info)
+    #
+    def logger
+      @logger ||= default_logger
+    end
+
+    # Set the module-level logger.
+    #
+    # @param logger [Logger] A Logger-compatible instance
+    # @return [Logger]
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # Enable debug-level logging to stderr (or a custom output).
+    #
+    # Convenience method for quick debugging. Creates a +Logger+ with
+    # a compact formatter and DEBUG level.
+    #
+    # @param output [IO] Output destination (default: +$stderr+)
+    # @return [Logger] The configured logger
+    #
+    # @example
+    #   ClaudeAgent.debug!
+    #   ClaudeAgent.debug!(output: $stdout)
+    #   ClaudeAgent.debug!(output: File.open("debug.log", "a"))
+    #
+    def debug!(output: $stderr)
+      self.logger = Logger.new(output, level: Logger::DEBUG).tap do |l|
+        l.formatter = LOG_FORMATTER
+      end
+    end
+
+    private
+
+    def default_logger
+      if ENV["CLAUDE_AGENT_DEBUG"]
+        Logger.new($stderr, level: Logger::DEBUG).tap do |l|
+          l.formatter = LOG_FORMATTER
+        end
+      else
+        NullLogger.new
+      end
+    end
+  end
+end

data/lib/claude_agent/mcp/server.rb

@@ -34,9 +34,11 @@ module ClaudeAgent
 
       # @param name [String] Server name
       # @param tools [Array<Tool>] Tools to expose
-      def initialize(name:, tools: [])
+      # @param logger [Logger, nil] Optional logger instance
+      def initialize(name:, tools: [], logger: nil)
         @name = name.to_s
         @tools = {}
+        @logger = logger
         tools.each { |tool| add_tool(tool) }
       end
 
@@ -61,6 +63,7 @@ module ClaudeAgent
         method = message["method"]
         params = message["params"] || {}
         id = message["id"]
+        logger.debug("mcp.#{@name}") { "Handling: #{method}" }
 
         result = case method
         when "initialize"
@@ -114,15 +117,21 @@ module ClaudeAgent
 
         tool = @tools[tool_name]
         unless tool
+          logger.warn("mcp.#{@name}") { "Unknown tool: #{tool_name}" }
           return {
             content: [ { type: "text", text: "Unknown tool: #{tool_name}" } ],
             isError: true
           }
         end
 
+        logger.info("mcp.#{@name}") { "Tool call: #{tool_name}" }
         tool.call(arguments)
       end
 
+      def logger
+        @logger || ClaudeAgent.logger
+      end
+
       def jsonrpc_response(id, result)
         {
           jsonrpc: "2.0",

data/lib/claude_agent/message_parser.rb

@@ -8,6 +8,11 @@ module ClaudeAgent
   #   message = parser.parse({"type" => "assistant", "message" => {...}})
   #
   class MessageParser
+    # @param logger [Logger, nil] Optional logger instance
+    def initialize(logger: nil)
+      @logger = logger
+    end
+
     # Parse a raw message hash into a typed message object
     #
     # @param raw [Hash] Raw message from CLI
@@ -15,6 +20,7 @@ module ClaudeAgent
     # @raise [MessageParseError] If message cannot be parsed
     def parse(raw)
       type = raw["type"]
+      logger.debug("parser") { "Parsing message: #{type}" }
 
       case type
       when "user"
@@ -52,12 +58,17 @@ module ClaudeAgent
       when "tool_use_summary"
         parse_tool_use_summary_message(raw)
       else
+        logger.error("parser") { "Unknown message type: #{type}" }
         raise MessageParseError.new("Unknown message type: #{type}", raw_message: raw)
       end
     end
 
     private
 
+    def logger
+      @logger || ClaudeAgent.logger
+    end
+
     # Fetch a value from a hash, trying both snake_case and camelCase keys
     # @param raw [Hash] The hash to fetch from
     # @param snake_key [Symbol, String] The snake_case key to try

data/lib/claude_agent/options.rb

@@ -62,6 +62,7 @@ module ClaudeAgent
       abort_controller spawn_claude_code_process
       init init_only maintenance
       debug debug_file
+      logger
     ].freeze
 
     attr_accessor(*ATTRIBUTES)
@@ -127,6 +128,12 @@ module ClaudeAgent
       abort_controller&.signal
     end
 
+    # Resolved logger: per-instance override or module-level default
+    # @return [Logger]
+    def effective_logger
+      @logger || ClaudeAgent.logger
+    end
+
     private
 
     # --- CLI Argument Builders ---
@@ -207,8 +214,7 @@ module ClaudeAgent
       [].tap do |args|
         args.push("--settings", settings) if settings
         if sandbox
-          sandbox_json = sandbox.respond_to?(:to_h) ? sandbox.to_h : sandbox
-          args.push("--sandbox", JSON.generate(sandbox_json))
+          args.push("--sandbox", JSON.generate(sandbox.to_h))
         end
       end
     end
@@ -234,7 +240,7 @@ module ClaudeAgent
         args.push("--json-schema", JSON.generate(output_format)) if output_format
         args.push("--include-partial-messages") if include_partial_messages
         if agents
-          agents_hash = agents.transform_values { |a| a.respond_to?(:to_h) ? a.to_h : a }
+          agents_hash = agents.transform_values(&:to_h)
           args.push("--agents", JSON.generate(agents_hash))
         end
       end
@@ -280,6 +286,13 @@ module ClaudeAgent
         raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
       end
 
+      # Auto-set permission_prompt_tool_name to "stdio" when can_use_tool is configured
+      # (Python/TypeScript SDK parity) so the CLI routes permission prompts through the
+      # control protocol instead of interactive terminal prompts
+      if can_use_tool && !permission_prompt_tool_name
+        @permission_prompt_tool_name = "stdio"
+      end
+
       if max_turns && (!max_turns.is_a?(Integer) || max_turns < 1)
         raise ConfigurationError, "max_turns must be a positive integer"
       end

data/lib/claude_agent/permissions.rb

@@ -21,7 +21,7 @@ module ClaudeAgent
     def to_h
       h = { behavior: "allow" }
       h[:updatedInput] = updated_input if updated_input
-      h[:updatedPermissions] = updated_permissions&.map { |p| p.respond_to?(:to_h) ? p.to_h : p } if updated_permissions
+      h[:updatedPermissions] = updated_permissions&.map(&:to_h) if updated_permissions
       h[:toolUseID] = tool_use_id if tool_use_id
       h
     end

data/lib/claude_agent/query.rb

@@ -85,46 +85,35 @@ module ClaudeAgent
       Enumerator.new do |yielder|
         # Set entrypoint environment variable
         ENV["CLAUDE_CODE_ENTRYPOINT"] = "sdk-rb"
+        query_logger = options.effective_logger
+        query_logger.info("query") { "Starting query" }
+        query_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-        # Determine mode based on hooks/MCP servers
-        streaming = options.has_hooks? || options.has_sdk_mcp_servers?
-
-        if streaming
-          # Use streaming mode with control protocol
-          protocol = ControlProtocol.new(transport: transport, options: options)
-          begin
-            # Register abort handler if abort controller is provided
-            if options.abort_signal
-              options.abort_signal.on_abort do
-                protocol.abort! rescue nil
-              end
+        # Always use streaming mode with control protocol (Python/TypeScript SDK parity)
+        protocol = ControlProtocol.new(transport: transport, options: options)
+        begin
+          # Register abort handler if abort controller is provided
+          if options.abort_signal
+            options.abort_signal.on_abort do
+              protocol.abort! rescue nil
             end
+          end
 
-            protocol.start(streaming: true)
-            protocol.send_user_message(prompt)
-            transport.end_input unless options.has_hooks? || options.has_sdk_mcp_servers?
+          protocol.start(streaming: true)
+          protocol.send_user_message(prompt)
 
-            protocol.each_message do |message|
-              yielder << message
-              break if message.is_a?(ResultMessage)
-            end
-          ensure
-            protocol.stop
-          end
-        else
-          # Simple mode - just send prompt and read responses
-          parser = MessageParser.new
-          begin
-            transport.connect(streaming: false, prompt: prompt)
+          protocol.each_message do |message|
+            query_logger.debug("query") { "Received: #{message.class.name.split("::").last}" }
+            yielder << message
 
-            transport.read_messages do |raw|
-              message = parser.parse(raw)
-              yielder << message
-              break if message.is_a?(ResultMessage)
+            if message.is_a?(ResultMessage)
+              elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - query_start
+              query_logger.info("query") { "Query complete (#{elapsed.round(2)}s, cost=$#{message.total_cost_usd || "?"})" }
+              break
             end
-          ensure
-            transport.close
           end
+        ensure
+          protocol.stop
         end
       end
     end

data/lib/claude_agent/transport/subprocess.rb

@@ -88,6 +88,9 @@ module ClaudeAgent
         end
 
         @connected = true
+        logger.info("transport") { "Process spawned (pid=#{@wait_thread&.pid || @process&.pid rescue "?"})" }
+        logger.debug("transport") { "Command: #{cmd.join(" ")}" }
+        logger.debug("transport") { "Working dir: #{working_directory}" }
 
         # Always start stderr reader to prevent pipe buffer from filling up
         start_stderr_reader if @stderr
@@ -115,6 +118,7 @@ module ClaudeAgent
         raise CLIConnectionError, "Not connected" unless @connected
         raise CLIConnectionError, "stdin closed" unless @stdin && !@stdin.closed?
 
+        logger.debug("transport") { "Write: #{data.bytesize} bytes" }
         @mutex.synchronize do
           @stdin.write(data)
           @stdin.write("\n") unless data.end_with?("\n")
@@ -139,8 +143,10 @@ module ClaudeAgent
 
           begin
             message = JSON.parse(line)
+            logger.debug("transport") { "Received: #{message["type"] || "unknown"}" }
             yield message
           rescue JSON::ParserError
+            logger.warn("transport") { "JSON parse error, buffering (#{@buffer.bytesize} bytes)" }
             # Buffer partial JSON (in case of split lines)
             @buffer << line
             if @buffer.bytesize > @max_buffer_size
@@ -192,6 +198,7 @@ module ClaudeAgent
         @connected = false
         @stdin = @stdout = @stderr = @wait_thread = nil
 
+        logger.info("transport") { "Transport closed (exit_status=#{exit_status.inspect})" }
         exit_status
       end
 
@@ -264,6 +271,7 @@ module ClaudeAgent
       # Force kill the CLI process (SIGKILL)
       # @return [void]
       def kill
+        logger.warn("transport") { "Force killing CLI process" }
         # Use custom process kill if available
         if @process&.respond_to?(:kill)
           @mutex.synchronize { @killed = true }
@@ -302,6 +310,10 @@ module ClaudeAgent
         paths.find { |p| !p.empty? && File.executable?(p) } || "claude"
       end
 
+      def logger
+        @options.effective_logger
+      end
+
       def check_cli_version!
         version_output = `#{@cli_path} -v 2>&1`.strip
         # Parse version like "claude 2.1.0" or just "2.1.0"
@@ -312,6 +324,7 @@ module ClaudeAgent
         end
 
         found_version = version_match[1]
+        logger.debug("transport") { "CLI version: #{found_version}" }
         unless version_satisfies?(found_version, MINIMUM_CLI_VERSION)
           raise CLIVersionError.new(found_version)
         end

data/lib/claude_agent/version.rb

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

data/lib/claude_agent.rb

@@ -4,6 +4,7 @@ require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/hash/keys"
 
 require_relative "claude_agent/version"
+require_relative "claude_agent/logging"
 require_relative "claude_agent/errors"
 require_relative "claude_agent/types"              # TypeScript SDK parity types
 require_relative "claude_agent/sandbox_settings"   # Sandbox configuration types

data/sig/claude_agent.rbs

@@ -1,6 +1,28 @@
 module ClaudeAgent
   VERSION: String
 
+  # Null logger that discards all output with zero overhead
+  class NullLogger < Logger
+    def initialize: () -> void
+    def add: (?Integer? severity, ?untyped message, ?String? progname) -> true
+    def debug: (*untyped) -> true
+    def info: (*untyped) -> true
+    def warn: (*untyped) -> true
+    def error: (*untyped) -> true
+    def fatal: (*untyped) -> true
+    def unknown: (*untyped) -> true
+    def debug?: () -> false
+    def info?: () -> false
+    def warn?: () -> false
+    def error?: () -> false
+    def fatal?: () -> false
+  end
+
+  # Module-level logger
+  def self.logger: () -> Logger
+  def self.logger=: (Logger logger) -> Logger
+  def self.debug!: (?output: IO) -> Logger
+
   # One-shot query to Claude Code CLI
   def self.query: (
     prompt: String,
@@ -316,6 +338,9 @@ module ClaudeAgent
     attr_accessor debug: bool
     attr_accessor debug_file: String?
 
+    # Logging
+    attr_accessor logger: Logger?
+
     # Abort control (TypeScript SDK parity)
     attr_accessor abort_controller: AbortController?
 
@@ -328,6 +353,7 @@ module ClaudeAgent
     def has_hooks?: () -> bool
     def has_sdk_mcp_servers?: () -> bool
     def abort_signal: () -> AbortSignal?
+    def effective_logger: () -> Logger
   end
 
   # Content block types
@@ -646,7 +672,7 @@ module ClaudeAgent
 
   # Message parser
   class MessageParser
-    def initialize: () -> void
+    def initialize: (?logger: Logger?) -> void
     def parse: (Hash[String, untyped] raw) -> message
   end
 
@@ -1029,7 +1055,7 @@ module ClaudeAgent
       attr_reader name: String
       attr_reader tools: Hash[String, Tool]
 
-      def initialize: (name: String, ?tools: Array[Tool]) -> void
+      def initialize: (name: String, ?tools: Array[Tool], ?logger: Logger?) -> void
       def add_tool: (Tool tool) -> void
       def remove_tool: (String name) -> Tool?
       def handle_message: (Hash[String, untyped] message) -> Hash[Symbol, untyped]?

data/sig/manifest.yaml

@@ -1,5 +1,6 @@
 dependencies:
   - name: json
+  - name: logger
   - name: timeout
   - name: open3
   - name: mutex_m

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.4
 platform: ruby
 authors:
 - Thomas Carr
@@ -56,6 +56,7 @@ files:
 - lib/claude_agent/control_protocol.rb
 - lib/claude_agent/errors.rb
 - lib/claude_agent/hooks.rb
+- lib/claude_agent/logging.rb
 - lib/claude_agent/mcp/server.rb
 - lib/claude_agent/mcp/tool.rb
 - lib/claude_agent/message_parser.rb