claude_agent 0.1.0

data/lib/claude_agent/errors.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Base error class for all ClaudeAgent errors
+  class Error < StandardError; end
+
+  # Raised when the Claude Code CLI cannot be found
+  class CLINotFoundError < Error
+    def initialize(message = "Claude Code CLI not found. Please install it first.")
+      super
+    end
+  end
+
+  # Raised when the CLI version is below minimum required
+  class CLIVersionError < Error
+    MINIMUM_VERSION = "2.0.0"
+
+    def initialize(found_version = nil)
+      message = if found_version
+        "Claude Code CLI version #{found_version} is below minimum required version #{MINIMUM_VERSION}"
+      else
+        "Could not determine Claude Code CLI version. Minimum required: #{MINIMUM_VERSION}"
+      end
+      super(message)
+    end
+  end
+
+  # Raised when connection to CLI fails
+  class CLIConnectionError < Error
+    def initialize(message = "Failed to connect to Claude Code CLI")
+      super
+    end
+  end
+
+  # Raised when the CLI process exits with an error
+  class ProcessError < Error
+    attr_reader :exit_code, :stderr
+
+    def initialize(message = "CLI process failed", exit_code: nil, stderr: nil)
+      @exit_code = exit_code
+      @stderr = stderr
+      full_message = message
+      full_message += " (exit code: #{exit_code})" if exit_code
+      full_message += "\nStderr: #{stderr}" if stderr && !stderr.empty?
+      super(full_message)
+    end
+  end
+
+  # Raised when JSON parsing fails
+  class JSONDecodeError < Error
+    attr_reader :raw_content
+
+    def initialize(message = "Failed to decode JSON", raw_content: nil)
+      @raw_content = raw_content
+      full_message = message
+      full_message += "\nContent: #{raw_content[0..200]}..." if raw_content
+      super(full_message)
+    end
+  end
+
+  # Raised when message parsing fails
+  class MessageParseError < Error
+    attr_reader :raw_message
+
+    def initialize(message = "Failed to parse message", raw_message: nil)
+      @raw_message = raw_message
+      full_message = message
+      full_message += "\nRaw message: #{raw_message.inspect[0..200]}" if raw_message
+      super(full_message)
+    end
+  end
+
+  # Raised when a control protocol request times out
+  class TimeoutError < Error
+    attr_reader :request_id, :timeout_seconds
+
+    def initialize(message = "Request timed out", request_id: nil, timeout_seconds: nil)
+      @request_id = request_id
+      @timeout_seconds = timeout_seconds
+      full_message = message
+      full_message += " (request_id: #{request_id})" if request_id
+      full_message += " after #{timeout_seconds}s" if timeout_seconds
+      super(full_message)
+    end
+  end
+
+  # Raised when an invalid option is provided
+  class ConfigurationError < Error; end
+
+  # Raised when an operation is aborted/cancelled (TypeScript SDK parity)
+  #
+  # This error is raised when an operation is explicitly cancelled,
+  # such as through a user interrupt or abort signal.
+  #
+  # @example
+  #   raise ClaudeAgent::AbortError, "Operation cancelled by user"
+  #
+  class AbortError < Error
+    def initialize(message = "Operation was aborted")
+      super
+    end
+  end
+end

data/lib/claude_agent/hooks.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Hook events that can be intercepted (TypeScript SDK parity)
+  HOOK_EVENTS = %w[
+    PreToolUse
+    PostToolUse
+    PostToolUseFailure
+    Notification
+    UserPromptSubmit
+    SessionStart
+    SessionEnd
+    Stop
+    SubagentStart
+    SubagentStop
+    PreCompact
+    PermissionRequest
+  ].freeze
+
+  # Matcher configuration for hooks
+  #
+  # @example Basic usage
+  #   matcher = HookMatcher.new(
+  #     matcher: "Bash|Write",
+  #     callbacks: [->(input, context) { {continue_: true} }],
+  #     timeout: 30
+  #   )
+  #
+  HookMatcher = Data.define(:matcher, :callbacks, :timeout) do
+    def initialize(matcher:, callbacks:, timeout: nil)
+      super
+    end
+
+    # Check if this matcher matches a tool name
+    # @param tool_name [String] Tool name to check
+    # @return [Boolean]
+    def matches?(tool_name)
+      case matcher
+      when String
+        if matcher.include?("|")
+          matcher.split("|").any? { |m| tool_name == m }
+        else
+          Regexp.new(matcher).match?(tool_name)
+        end
+      when Regexp
+        matcher.match?(tool_name)
+      else
+        true
+      end
+    end
+  end
+
+  # Context passed to hook callbacks
+  #
+  HookContext = Data.define(:tool_use_id) do
+    def initialize(tool_use_id: nil)
+      super
+    end
+  end
+
+  # Base class for hook input types (TypeScript SDK parity)
+  #
+  class BaseHookInput
+    attr_reader :hook_event_name, :session_id, :transcript_path, :cwd, :permission_mode
+
+    def initialize(hook_event_name:, session_id: nil, transcript_path: nil, cwd: nil, permission_mode: nil, **kwargs)
+      @hook_event_name = hook_event_name
+      @session_id = session_id
+      @transcript_path = transcript_path
+      @cwd = cwd
+      @permission_mode = permission_mode
+    end
+  end
+
+  # Input for PreToolUse hook
+  #
+  class PreToolUseInput < BaseHookInput
+    attr_reader :tool_name, :tool_input, :tool_use_id
+
+    def initialize(tool_name:, tool_input:, tool_use_id: nil, **kwargs)
+      super(hook_event_name: "PreToolUse", **kwargs)
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_use_id = tool_use_id
+    end
+  end
+
+  # Input for PostToolUse hook
+  #
+  class PostToolUseInput < BaseHookInput
+    attr_reader :tool_name, :tool_input, :tool_response, :tool_use_id
+
+    def initialize(tool_name:, tool_input:, tool_response:, tool_use_id: nil, **kwargs)
+      super(hook_event_name: "PostToolUse", **kwargs)
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_response = tool_response
+      @tool_use_id = tool_use_id
+    end
+  end
+
+  # Input for PostToolUseFailure hook (TypeScript SDK parity)
+  #
+  class PostToolUseFailureInput < BaseHookInput
+    attr_reader :tool_name, :tool_input, :tool_use_id, :error, :is_interrupt
+
+    def initialize(tool_name:, tool_input:, error:, tool_use_id: nil, is_interrupt: nil, **kwargs)
+      super(hook_event_name: "PostToolUseFailure", **kwargs)
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_use_id = tool_use_id
+      @error = error
+      @is_interrupt = is_interrupt
+    end
+  end
+
+  # Input for Notification hook (TypeScript SDK parity)
+  #
+  class NotificationInput < BaseHookInput
+    attr_reader :message, :title, :notification_type
+
+    def initialize(message:, title: nil, notification_type: nil, **kwargs)
+      super(hook_event_name: "Notification", **kwargs)
+      @message = message
+      @title = title
+      @notification_type = notification_type
+    end
+  end
+
+  # Input for UserPromptSubmit hook
+  #
+  class UserPromptSubmitInput < BaseHookInput
+    attr_reader :prompt
+
+    def initialize(prompt:, **kwargs)
+      super(hook_event_name: "UserPromptSubmit", **kwargs)
+      @prompt = prompt
+    end
+  end
+
+  # Input for SessionStart hook (TypeScript SDK parity)
+  #
+  class SessionStartInput < BaseHookInput
+    attr_reader :source, :agent_type
+
+    # @param source [String] One of: "startup", "resume", "clear", "compact"
+    # @param agent_type [String, nil] Type of agent if running in subagent context
+    def initialize(source:, agent_type: nil, **kwargs)
+      super(hook_event_name: "SessionStart", **kwargs)
+      @source = source
+      @agent_type = agent_type
+    end
+  end
+
+  # Input for SessionEnd hook (TypeScript SDK parity)
+  #
+  class SessionEndInput < BaseHookInput
+    attr_reader :reason
+
+    def initialize(reason:, **kwargs)
+      super(hook_event_name: "SessionEnd", **kwargs)
+      @reason = reason
+    end
+  end
+
+  # Input for Stop hook
+  #
+  class StopInput < BaseHookInput
+    attr_reader :stop_hook_active
+
+    def initialize(stop_hook_active: false, **kwargs)
+      super(hook_event_name: "Stop", **kwargs)
+      @stop_hook_active = stop_hook_active
+    end
+  end
+
+  # Input for SubagentStart hook (TypeScript SDK parity)
+  #
+  class SubagentStartInput < BaseHookInput
+    attr_reader :agent_id, :agent_type
+
+    def initialize(agent_id:, agent_type:, **kwargs)
+      super(hook_event_name: "SubagentStart", **kwargs)
+      @agent_id = agent_id
+      @agent_type = agent_type
+    end
+  end
+
+  # Input for SubagentStop hook
+  #
+  class SubagentStopInput < BaseHookInput
+    attr_reader :stop_hook_active, :agent_id, :agent_transcript_path
+
+    def initialize(stop_hook_active: false, agent_id: nil, agent_transcript_path: nil, **kwargs)
+      super(hook_event_name: "SubagentStop", **kwargs)
+      @stop_hook_active = stop_hook_active
+      @agent_id = agent_id
+      @agent_transcript_path = agent_transcript_path
+    end
+  end
+
+  # Input for PreCompact hook
+  #
+  class PreCompactInput < BaseHookInput
+    attr_reader :trigger, :custom_instructions
+
+    # @param trigger [String] One of: "manual", "auto"
+    # @param custom_instructions [String, nil] Custom instructions for compaction
+    def initialize(trigger:, custom_instructions: nil, **kwargs)
+      super(hook_event_name: "PreCompact", **kwargs)
+      @trigger = trigger
+      @custom_instructions = custom_instructions
+    end
+  end
+
+  # Input for PermissionRequest hook (TypeScript SDK parity)
+  #
+  class PermissionRequestInput < BaseHookInput
+    attr_reader :tool_name, :tool_input, :permission_suggestions
+
+    def initialize(tool_name:, tool_input:, permission_suggestions: nil, **kwargs)
+      super(hook_event_name: "PermissionRequest", **kwargs)
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @permission_suggestions = permission_suggestions
+    end
+  end
+end

data/lib/claude_agent/mcp/server.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeAgent
+  module MCP
+    # In-process MCP server for hosting tools
+    #
+    # Unlike external MCP servers that run as subprocesses, SDK servers
+    # run in the same Ruby process, providing better performance and
+    # easier debugging.
+    #
+    # @example Create a server with tools
+    #   add_tool = ClaudeAgent::MCP::Tool.new(
+    #     name: "add",
+    #     description: "Add two numbers",
+    #     schema: {a: Float, b: Float}
+    #   ) { |args| args["a"] + args["b"] }
+    #
+    #   server = ClaudeAgent::MCP::Server.new(
+    #     name: "calculator",
+    #     tools: [add_tool]
+    #   )
+    #
+    # @example Use with ClaudeAgent
+    #   options = ClaudeAgent::Options.new(
+    #     mcp_servers: {
+    #       "calculator" => {type: "sdk", instance: server}
+    #     }
+    #   )
+    #
+    class Server
+      attr_reader :name, :tools
+
+      # @param name [String] Server name
+      # @param tools [Array<Tool>] Tools to expose
+      def initialize(name:, tools: [])
+        @name = name.to_s
+        @tools = {}
+        tools.each { |tool| add_tool(tool) }
+      end
+
+      # Add a tool to the server
+      # @param tool [Tool] Tool to add
+      # @return [void]
+      def add_tool(tool)
+        @tools[tool.name] = tool
+      end
+
+      # Remove a tool from the server
+      # @param name [String] Tool name
+      # @return [Tool, nil] Removed tool
+      def remove_tool(name)
+        @tools.delete(name.to_s)
+      end
+
+      # Handle an MCP message
+      # @param message [Hash] MCP JSON-RPC message
+      # @return [Hash] MCP JSON-RPC response
+      def handle_message(message)
+        method = message["method"]
+        params = message["params"] || {}
+        id = message["id"]
+
+        result = case method
+        when "initialize"
+          handle_initialize(params)
+        when "tools/list"
+          handle_tools_list(params)
+        when "tools/call"
+          handle_tools_call(params)
+        when "notifications/initialized"
+          # Acknowledgement, no response needed
+          return nil
+        else
+          return jsonrpc_error(id, -32601, "Method not found: #{method}")
+        end
+
+        jsonrpc_response(id, result)
+      rescue => e
+        jsonrpc_error(id, -32603, "Internal error: #{e.message}")
+      end
+
+      # Get MCP server configuration for options
+      # @return [Hash]
+      def to_config
+        { type: "sdk", name: @name, instance: self }
+      end
+
+      private
+
+      def handle_initialize(params)
+        {
+          protocolVersion: "2024-11-05",
+          capabilities: {
+            tools: {}
+          },
+          serverInfo: {
+            name: @name,
+            version: ClaudeAgent::VERSION
+          }
+        }
+      end
+
+      def handle_tools_list(params)
+        {
+          tools: @tools.values.map(&:to_mcp_definition)
+        }
+      end
+
+      def handle_tools_call(params)
+        tool_name = params["name"]
+        arguments = params["arguments"] || {}
+
+        tool = @tools[tool_name]
+        unless tool
+          return {
+            content: [ { type: "text", text: "Unknown tool: #{tool_name}" } ],
+            isError: true
+          }
+        end
+
+        tool.call(arguments)
+      end
+
+      def jsonrpc_response(id, result)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: result
+        }
+      end
+
+      def jsonrpc_error(id, code, message)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          error: {
+            code: code,
+            message: message
+          }
+        }
+      end
+    end
+
+    # Convenience method to create a tool
+    #
+    # @example
+    #   tool = ClaudeAgent::MCP.tool("greet", "Greet someone", {name: String}) do |args|
+    #     "Hello, #{args['name']}!"
+    #   end
+    #
+    def self.tool(name, description, schema = {}, &handler)
+      Tool.new(name: name, description: description, schema: schema, &handler)
+    end
+
+    # Convenience method to create a server
+    #
+    # @example
+    #   server = ClaudeAgent::MCP.create_server(name: "mytools", tools: [tool1, tool2])
+    #
+    def self.create_server(name:, tools: [])
+      Server.new(name: name, tools: tools)
+    end
+  end
+end

data/lib/claude_agent/mcp/tool.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  module MCP
+    # Defines a tool that can be called by Claude
+    #
+    # @example Simple tool
+    #   tool = ClaudeAgent::MCP::Tool.new(
+    #     name: "greet",
+    #     description: "Greet a person",
+    #     schema: {name: String}
+    #   ) do |args|
+    #     "Hello, #{args['name']}!"
+    #   end
+    #
+    # @example Tool with complex schema
+    #   tool = ClaudeAgent::MCP::Tool.new(
+    #     name: "calculate",
+    #     description: "Perform arithmetic",
+    #     schema: {
+    #       type: "object",
+    #       properties: {
+    #         operation: {type: "string", enum: ["add", "subtract"]},
+    #         a: {type: "number"},
+    #         b: {type: "number"}
+    #       },
+    #       required: ["operation", "a", "b"]
+    #     }
+    #   ) do |args|
+    #     case args["operation"]
+    #     when "add" then args["a"] + args["b"]
+    #     when "subtract" then args["a"] - args["b"]
+    #     end
+    #   end
+    #
+    class Tool
+      attr_reader :name, :description, :schema, :handler
+
+      # @param name [String] Tool name (must be unique within server)
+      # @param description [String] Description of what the tool does
+      # @param schema [Hash] Input schema (simple Ruby types or JSON Schema)
+      # @param handler [Proc] Block to execute when tool is called
+      def initialize(name:, description:, schema: {}, &handler)
+        @name = name.to_s
+        @description = description.to_s
+        @schema = normalize_schema(schema)
+        @handler = handler || ->(args) { raise "No handler defined for tool #{name}" }
+      end
+
+      # Call the tool with arguments
+      # @param args [Hash] Tool arguments
+      # @return [Hash] MCP response format
+      def call(args)
+        result = @handler.call(args)
+        format_result(result)
+      rescue => e
+        format_error(e)
+      end
+
+      # Convert to MCP tool definition format
+      # @return [Hash]
+      def to_mcp_definition
+        {
+          name: @name,
+          description: @description,
+          inputSchema: @schema
+        }
+      end
+
+      private
+
+      # Normalize schema from simple Ruby types to JSON Schema
+      def normalize_schema(schema)
+        return schema if json_schema?(schema)
+
+        # Convert simple {name: Type} format to JSON Schema
+        if schema.is_a?(Hash) && schema.values.all? { |v| v.is_a?(Class) || v.is_a?(Module) }
+          {
+            type: "object",
+            properties: schema.transform_values { |type| type_to_schema(type) },
+            required: schema.keys.map(&:to_s)
+          }
+        else
+          schema
+        end
+      end
+
+      def json_schema?(schema)
+        return false unless schema.is_a?(Hash)
+
+        schema.key?(:type) || schema.key?("type") ||
+          schema.key?(:properties) || schema.key?("properties")
+      end
+
+      def type_to_schema(type)
+        case type.to_s
+        when "String"
+          { type: "string" }
+        when "Integer"
+          { type: "integer" }
+        when "Float", "Numeric"
+          { type: "number" }
+        when "TrueClass", "FalseClass"
+          { type: "boolean" }
+        when "Array"
+          { type: "array" }
+        when "Hash"
+          { type: "object" }
+        else
+          { type: "string" }
+        end
+      end
+
+      def format_result(result)
+        content = case result
+        when String
+          [ { type: "text", text: result } ]
+        when Hash
+          result[:content] || [ { type: "text", text: result.to_json } ]
+        when Array
+          result
+        else
+          [ { type: "text", text: result.to_s } ]
+        end
+
+        { content: content, isError: false }
+      end
+
+      def format_error(error)
+        {
+          content: [ { type: "text", text: "Error: #{error.message}" } ],
+          isError: true
+        }
+      end
+    end
+  end
+end