claude_agent 0.7.15 → 0.7.16

data/lib/claude_agent/conversation.rb

@@ -226,13 +226,38 @@ module ClaudeAgent
       [ callbacks, conversation_kwargs, options_kwargs ]
     end
 
+    # Symbol → CLI permission mode mapping
+    SYMBOL_PERMISSION_MODES = {
+      default: "default",
+      accept_edits: "acceptEdits",
+      plan: "plan",
+      bypass_permissions: "bypassPermissions",
+      dont_ask: "dontAsk"
+    }.freeze
+
     def build_options(options_kwargs, conversation_kwargs)
       permission = conversation_kwargs[:on_permission]
 
-      if permission.respond_to?(:call)
-        options_kwargs[:can_use_tool] = permission
-      elsif permission == :queue || permission.nil?
+      case permission
+      when PermissionPolicy
+        options_kwargs[:can_use_tool] = permission.to_can_use_tool
+      when Symbol
+        if (mode = SYMBOL_PERMISSION_MODES[permission])
+          options_kwargs[:permission_mode] = mode
+        elsif permission == :queue
+          options_kwargs[:permission_queue] = true unless options_kwargs.key?(:can_use_tool)
+        end
+      when nil
         options_kwargs[:permission_queue] = true unless options_kwargs.key?(:can_use_tool)
+      else
+        if permission.respond_to?(:call)
+          options_kwargs[:can_use_tool] = permission
+        end
+      end
+
+      # Handle HookRegistry in hooks option
+      if options_kwargs[:hooks].is_a?(HookRegistry)
+        options_kwargs[:hooks] = options_kwargs[:hooks].to_hooks_hash
       end
 
       Options.new(**options_kwargs)

data/lib/claude_agent/errors.rb

@@ -87,6 +87,9 @@ module ClaudeAgent
   # Raised when an invalid option is provided
   class ConfigurationError < Error; end
 
+  # Raised when a resource is not found (Stripe convention)
+  class NotFoundError < Error; end
+
   # Raised when an operation is aborted/cancelled (TypeScript SDK parity)
   #
   # This error is raised when an operation is explicitly cancelled,

data/lib/claude_agent/event_handler.rb

@@ -54,6 +54,20 @@ module ClaudeAgent
     # All known events
     EVENTS = (META_EVENTS + TYPE_EVENTS + DECOMPOSED_EVENTS).freeze
 
+    # Create an EventHandler with block-based DSL.
+    #
+    # @example
+    #   handler = ClaudeAgent::EventHandler.define do
+    #     on_text { |t| print t }
+    #     on_result { |r| puts "\nCost: $#{r.total_cost_usd}" }
+    #   end
+    #
+    # @yield [self] Block evaluated in the context of the new handler
+    # @return [EventHandler]
+    def self.define(&block)
+      new.tap { |h| h.instance_eval(&block) }
+    end
+
     def initialize
       @handlers = Hash.new { |h, k| h[k] = [] }
       @pending_tool_uses = {}

data/lib/claude_agent/hook_registry.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Declarative hook registry with Ruby-friendly method names.
+  #
+  # Maps idiomatic Ruby method names to CLI hook event names and
+  # compiles to the Hash format consumed by Options#hooks.
+  #
+  # @example Basic usage
+  #   hooks = ClaudeAgent::HookRegistry.new do |h|
+  #     h.before_tool_use(/Bash/) { |input, ctx| { continue_: true } }
+  #     h.after_tool_use("Read") { |input, ctx| { continue_: true } }
+  #   end
+  #
+  # @example Module-level convenience
+  #   ClaudeAgent.hooks do |h|
+  #     h.on_session_start { |input, ctx| { continue_: true } }
+  #   end
+  #
+  class HookRegistry
+    # Ruby method name → CLI event name mapping
+    EVENT_MAP = {
+      before_tool_use: "PreToolUse",
+      after_tool_use: "PostToolUse",
+      after_tool_use_failure: "PostToolUseFailure",
+      on_notification: "Notification",
+      on_user_prompt_submit: "UserPromptSubmit",
+      on_session_start: "SessionStart",
+      on_session_end: "SessionEnd",
+      on_stop: "Stop",
+      on_subagent_start: "SubagentStart",
+      on_subagent_stop: "SubagentStop",
+      before_compact: "PreCompact",
+      after_compact: "PostCompact",
+      on_permission_request: "PermissionRequest",
+      on_setup: "Setup",
+      on_teammate_idle: "TeammateIdle",
+      on_task_completed: "TaskCompleted",
+      on_elicitation: "Elicitation",
+      on_elicitation_result: "ElicitationResult",
+      on_config_change: "ConfigChange",
+      on_worktree_create: "WorktreeCreate",
+      on_worktree_remove: "WorktreeRemove",
+      on_instructions_loaded: "InstructionsLoaded"
+    }.freeze
+
+    # @param block [Proc] DSL block yielding self
+    def initialize(&block)
+      @matchers = Hash.new { |h, k| h[k] = [] }
+      yield self if block_given?
+    end
+
+    # Define DSL methods for each event
+    EVENT_MAP.each do |method_name, cli_event|
+      define_method(method_name) do |matcher = nil, timeout: nil, &callback|
+        @matchers[cli_event] << HookMatcher.new(
+          matcher: normalize_matcher(matcher),
+          callbacks: [ callback ],
+          timeout: timeout
+        )
+        self
+      end
+    end
+
+    # Compile to the hooks Hash format consumed by Options.
+    #
+    # @return [Hash{String => Array<HookMatcher>}]
+    def to_hooks_hash
+      @matchers.transform_values(&:dup)
+    end
+
+    # Merge another HookRegistry additively (concatenates matchers per event).
+    #
+    # @param other [HookRegistry] Registry to merge
+    # @return [HookRegistry] New registry with combined matchers
+    def merge(other)
+      merged = self.class.new
+      @matchers.each { |event, matchers| matchers.each { |m| merged.instance_variable_get(:@matchers)[event] << m } }
+      other.instance_variable_get(:@matchers).each { |event, matchers| matchers.each { |m| merged.instance_variable_get(:@matchers)[event] << m } }
+      merged
+    end
+
+    # Whether any hooks have been registered.
+    # @return [Boolean]
+    def empty?
+      @matchers.empty?
+    end
+
+    # Number of total matchers across all events.
+    # @return [Integer]
+    def size
+      @matchers.values.sum(&:size)
+    end
+
+    private
+
+    def normalize_matcher(matcher)
+      case matcher
+      when Regexp
+        matcher.source
+      when String
+        matcher
+      when nil
+        nil
+      else
+        matcher.to_s
+      end
+    end
+  end
+end

data/lib/claude_agent/mcp/server.rb

@@ -35,11 +35,33 @@ module ClaudeAgent
       # @param name [String] Server name
       # @param tools [Array<Tool>] Tools to expose
       # @param logger [Logger, nil] Optional logger instance
+      # @yield [self] Optional block for DSL-style tool definition
+      #
+      # @example Block DSL
+      #   server = ClaudeAgent::MCP::Server.new(name: "calc") do |s|
+      #     s.tool("add", "Add numbers", { a: :number, b: :number }) { |args| args[:a] + args[:b] }
+      #   end
+      #
       def initialize(name:, tools: [], logger: nil)
         @name = name.to_s
         @tools = {}
         @logger = logger
         tools.each { |tool| add_tool(tool) }
+        yield self if block_given?
+      end
+
+      # Define and add a tool in one step (DSL convenience)
+      #
+      # @param name [String] Tool name
+      # @param description [String] Tool description
+      # @param schema [Hash] Input schema
+      # @param annotations [Hash, nil] MCP tool annotations
+      # @yield [Hash] Tool arguments
+      # @return [Tool] The created tool
+      def tool(name, description, schema = {}, annotations: nil, &handler)
+        new_tool = Tool.new(name: name, description: description, schema: schema, annotations: annotations, &handler)
+        add_tool(new_tool)
+        new_tool
       end
 
       # Add a tool to the server

data/lib/claude_agent/mcp/tool.rb

@@ -73,12 +73,12 @@ module ClaudeAgent
 
       private
 
-      # Normalize schema from simple Ruby types to JSON Schema
+      # Normalize schema from simple Ruby types or symbol shortcuts 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) }
+        # Convert simple {name: Type} or {name: :type_symbol} format to JSON Schema
+        if schema.is_a?(Hash) && schema.values.all? { |v| v.is_a?(Class) || v.is_a?(Module) || v.is_a?(Symbol) }
           {
             type: "object",
             properties: schema.transform_values { |type| type_to_schema(type) },
@@ -96,7 +96,28 @@ module ClaudeAgent
           schema.key?(:properties) || schema.key?("properties")
       end
 
+      # Symbol type shortcuts for schema definitions
+      SYMBOL_TYPE_MAP = {
+        string: "string",
+        str: "string",
+        integer: "integer",
+        int: "integer",
+        number: "number",
+        float: "number",
+        numeric: "number",
+        boolean: "boolean",
+        bool: "boolean",
+        array: "array",
+        object: "object",
+        hash: "object"
+      }.freeze
+
       def type_to_schema(type)
+        if type.is_a?(Symbol)
+          json_type = SYMBOL_TYPE_MAP[type] || "string"
+          return { type: json_type }
+        end
+
         case type.to_s
         when "String"
           { type: "string" }

data/lib/claude_agent/message.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Shared interface for all message and content block types.
+  #
+  # Provides a consistent API across the 22+ message types and 8 content
+  # block types without interfering with `Data.define` inheritance.
+  #
+  # @example Universal text extraction
+  #   message.text_content  # works on AssistantMessage, UserMessage, TextBlock, etc.
+  #
+  # @example Duck-type checks
+  #   message.session_message?   # has uuid + session_id?
+  #   message.identifiable?      # has uuid?
+  #
+  # @example Pattern matching
+  #   case message
+  #   in { type: :assistant }
+  #     puts message.text_content
+  #   in { type: :result }
+  #     puts message.cost
+  #   end
+  #
+  module Message
+    # Universal text extraction across all message and content block types.
+    #
+    # @return [String] Extracted text (empty string if no text available)
+    def text_content
+      case self
+      when AssistantMessage
+        text
+      when UserMessage, UserMessageReplay
+        content.is_a?(String) ? content : ""
+      when TextBlock
+        text
+      when ThinkingBlock
+        thinking
+      when StreamEvent
+        delta_text || ""
+      when ToolProgressMessage
+        ""
+      when ResultMessage
+        ""
+      when GenericMessage
+        raw.is_a?(Hash) ? (raw[:text] || raw["text"] || "").to_s : ""
+      else
+        respond_to?(:text) ? (text || "").to_s : ""
+      end
+    end
+
+    # Whether this message carries session identity (uuid + session_id).
+    #
+    # @return [Boolean]
+    def session_message?
+      respond_to?(:uuid) && respond_to?(:session_id) &&
+        !uuid.nil? && !session_id.nil?
+    end
+
+    # Whether this message has a UUID.
+    #
+    # @return [Boolean]
+    def identifiable?
+      respond_to?(:uuid) && !uuid.nil?
+    end
+
+    # Override deconstruct_keys to include :type for pattern matching.
+    #
+    # Allows `case msg; in { type: :assistant }` to work naturally.
+    #
+    # Data#deconstruct_keys stops early if it encounters a non-member key,
+    # so we filter out :type (a virtual key) before delegating to super.
+    #
+    # @param keys [Array<Symbol>, nil]
+    # @return [Hash]
+    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
+
+  # Prepend Message in all message types (prepend needed to override Data#deconstruct_keys)
+  MESSAGE_TYPES.each { |klass| klass.prepend(Message) }
+
+  # Prepend Message in all content block types
+  CONTENT_BLOCK_TYPES.each { |klass| klass.prepend(Message) }
+end

data/lib/claude_agent/options.rb

@@ -122,10 +122,20 @@ module ClaudeAgent
               "Must set allow_dangerously_skip_permissions: true to use bypassPermissions mode"
       end
 
+      # Auto-compile PermissionPolicy to can_use_tool lambda
+      if can_use_tool.is_a?(PermissionPolicy)
+        @can_use_tool = can_use_tool.to_can_use_tool
+      end
+
       if can_use_tool && !can_use_tool.respond_to?(:call)
         raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
       end
 
+      # Auto-compile HookRegistry to hooks hash
+      if hooks.is_a?(HookRegistry)
+        @hooks = hooks.to_hooks_hash
+      end
+
       if on_elicitation && !on_elicitation.respond_to?(:call)
         raise ConfigurationError, "on_elicitation must be callable (Proc, Lambda, or object responding to #call)"
       end

data/lib/claude_agent/permission_policy.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Declarative permission policy builder.
+  #
+  # Compiles allow/deny rules into a `can_use_tool` lambda for use
+  # with Options and Conversation. Rules are evaluated in order;
+  # first match wins.
+  #
+  # @example Basic usage
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow "Read", "Grep", "Glob"
+  #     p.deny "Bash", message: "Bash not allowed"
+  #     p.deny_all
+  #   end
+  #
+  # @example With regex matching
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow_matching(/^mcp__/)
+  #     p.deny_all
+  #   end
+  #
+  # @example With custom handler for unmatched tools
+  #   policy = ClaudeAgent::PermissionPolicy.new do |p|
+  #     p.allow "Read"
+  #     p.ask { |name, input, ctx| PermissionResultAllow.new }
+  #   end
+  #
+  # @example Module-level convenience
+  #   ClaudeAgent.permissions do |p|
+  #     p.allow "Read", "Grep"
+  #     p.deny "Bash"
+  #   end
+  #
+  class PermissionPolicy
+    # @param block [Proc] DSL block yielding self
+    def initialize(&block)
+      @rules = []
+      @fallback = nil
+      yield self if block_given?
+    end
+
+    # Allow specific tools by exact name.
+    #
+    # @param tool_names [Array<String>] Tool names to allow
+    # @return [self]
+    def allow(*tool_names)
+      tool_names.flatten.each do |name|
+        @rules << { type: :exact, name: name.to_s, action: :allow }
+      end
+      self
+    end
+
+    # Deny specific tools by exact name.
+    #
+    # @param tool_names [Array<String>] Tool names to deny
+    # @param message [String] Denial message
+    # @param interrupt [Boolean] Whether to interrupt the conversation
+    # @return [self]
+    def deny(*tool_names, message: "", interrupt: false)
+      tool_names.flatten.each do |name|
+        @rules << { type: :exact, name: name.to_s, action: :deny, message: message, interrupt: interrupt }
+      end
+      self
+    end
+
+    # Allow tools matching a pattern.
+    #
+    # @param pattern [Regexp, String] Pattern to match against tool names
+    # @return [self]
+    def allow_matching(pattern)
+      @rules << { type: :pattern, pattern: to_regexp(pattern), action: :allow }
+      self
+    end
+
+    # Deny tools matching a pattern.
+    #
+    # @param pattern [Regexp, String] Pattern to match against tool names
+    # @param message [String] Denial message
+    # @param interrupt [Boolean] Whether to interrupt the conversation
+    # @return [self]
+    def deny_matching(pattern, message: "", interrupt: false)
+      @rules << { type: :pattern, pattern: to_regexp(pattern), action: :deny, message: message, interrupt: interrupt }
+      self
+    end
+
+    # Set a custom handler for tools that don't match any rule.
+    #
+    # @yield [name, input, context] Called for unmatched tools
+    # @return [self]
+    def ask(&handler)
+      @fallback = handler
+      self
+    end
+
+    # Set fallback to allow all unmatched tools.
+    # @return [self]
+    def allow_all
+      @fallback = :allow
+      self
+    end
+
+    # Set fallback to deny all unmatched tools.
+    #
+    # @param message [String] Denial message for unmatched tools
+    # @return [self]
+    def deny_all(message: "Denied by policy")
+      @fallback = { action: :deny, message: message }
+      self
+    end
+
+    # Compile this policy into a `can_use_tool` lambda.
+    #
+    # @return [Proc] Lambda compatible with Options#can_use_tool
+    def to_can_use_tool
+      rules = @rules.dup.freeze
+      fallback = @fallback
+
+      ->(tool_name, tool_input, context) {
+        # Check rules in order, first match wins
+        rules.each do |rule|
+          next unless matches?(rule, tool_name)
+
+          case rule[:action]
+          when :allow
+            return PermissionResultAllow.new
+          when :deny
+            return PermissionResultDeny.new(message: rule[:message], interrupt: rule[:interrupt])
+          end
+        end
+
+        # No rule matched, use fallback
+        case fallback
+        when :allow
+          PermissionResultAllow.new
+        when Hash
+          PermissionResultDeny.new(message: fallback[:message])
+        when Proc
+          fallback.call(tool_name, tool_input, context)
+        else
+          # Default: allow (no policy restriction)
+          PermissionResultAllow.new
+        end
+      }
+    end
+
+    # Whether any rules have been defined.
+    # @return [Boolean]
+    def empty?
+      @rules.empty? && @fallback.nil?
+    end
+
+    private
+
+    def matches?(rule, tool_name)
+      case rule[:type]
+      when :exact
+        rule[:name] == tool_name.to_s
+      when :pattern
+        rule[:pattern].match?(tool_name.to_s)
+      else
+        false
+      end
+    end
+
+    def to_regexp(pattern)
+      case pattern
+      when Regexp then pattern
+      when String then Regexp.new(pattern)
+      else raise ArgumentError, "Pattern must be a Regexp or String, got #{pattern.class}"
+      end
+    end
+  end
+end