claude_agent 0.7.14 → 0.7.16

data/lib/claude_agent/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Global configuration object (Stripe-style).
+  #
+  # Holds default values for all configurable Options fields. When a
+  # query, conversation, or ask/chat call is made without explicit
+  # Options, these defaults are merged with per-request overrides to
+  # produce the final Options instance.
+  #
+  # @example Module-level setters
+  #   ClaudeAgent.model = "claude-sonnet-4-5-20250514"
+  #   ClaudeAgent.permission_mode = "acceptEdits"
+  #   ClaudeAgent.max_turns = 10
+  #
+  # @example Block-based bulk config
+  #   ClaudeAgent.configure do |c|
+  #     c.model = "claude-sonnet-4-5-20250514"
+  #     c.permission_mode = "acceptEdits"
+  #     c.max_turns = 10
+  #   end
+  #
+  # @example Per-request overrides (via ask)
+  #   ClaudeAgent.ask("Fix the bug", model: "opus", max_turns: 5)
+  #
+  class Configuration
+    # Tier 1: Module-level delegators (set once at boot)
+    TIER1_FIELDS = %i[
+      model permission_mode max_turns max_budget_usd
+      system_prompt append_system_prompt cli_path cwd
+      sandbox debug effort persist_session fallback_model
+    ].freeze
+
+    # Tier 2: Per-request overrides (common kwargs on ask/chat)
+    TIER2_FIELDS = %i[
+      tools allowed_tools disallowed_tools thinking output_format
+    ].freeze
+
+    # Tier 3: Advanced (accessible via config.xxx= or raw Options.new)
+    TIER3_FIELDS = %i[
+      mcp_servers hooks env extra_args agents setting_sources settings
+      plugins betas spawn_claude_code_process agent add_dirs
+      max_buffer_size stderr_callback include_partial_messages
+      enable_file_checkpointing prompt_suggestions strict_mcp_config
+      tool_config agent_progress_summaries max_thinking_tokens
+      debug_file
+    ].freeze
+
+    # All configurable fields
+    ALL_FIELDS = (TIER1_FIELDS + TIER2_FIELDS + TIER3_FIELDS).freeze
+
+    attr_accessor(*ALL_FIELDS)
+
+    # Global PermissionPolicy
+    attr_accessor :default_permissions
+
+    # Global HookRegistry
+    attr_accessor :default_hooks
+
+    # Global MCP server registrations
+    attr_accessor :default_mcp_servers
+
+    # Create a new Configuration with all fields at nil/default.
+    #
+    # @return [Configuration]
+    def self.setup
+      new
+    end
+
+    def initialize
+      @default_mcp_servers = {}
+    end
+
+    # Merge config defaults with per-request keyword overrides to produce an Options instance.
+    #
+    # nil overrides are ignored (config default wins). Explicit non-nil overrides win.
+    #
+    # @param overrides [Hash] Per-request keyword overrides
+    # @return [Options]
+    def to_options(**overrides)
+      merged = {}
+
+      ALL_FIELDS.each do |field|
+        config_val = public_send(field)
+        override_val = overrides.key?(field) ? overrides[field] : nil
+
+        # Per-request override wins if provided; config default otherwise
+        if overrides.key?(field)
+          merged[field] = override_val
+        elsif !config_val.nil?
+          merged[field] = config_val
+        end
+      end
+
+      # Forward any extra keys not in ALL_FIELDS (e.g., can_use_tool, permission_queue, etc.)
+      overrides.each do |key, value|
+        merged[key] = value unless ALL_FIELDS.include?(key)
+      end
+
+      # Wire in global permissions if no per-request can_use_tool provided
+      if default_permissions && !merged.key?(:can_use_tool) && !default_permissions.empty?
+        merged[:can_use_tool] = default_permissions.to_can_use_tool
+      end
+
+      # Wire in global hooks (additive merge with per-request hooks)
+      if default_hooks && !default_hooks.empty?
+        request_hooks = merged[:hooks]
+        global_hooks = default_hooks.to_hooks_hash
+        if request_hooks.is_a?(Hash)
+          # Merge: global + request (request hooks take precedence for same event)
+          combined = global_hooks.dup
+          request_hooks.each do |event, matchers|
+            combined[event] = (combined[event] || []) + Array(matchers)
+          end
+          merged[:hooks] = combined
+        else
+          merged[:hooks] = global_hooks
+        end
+      end
+
+      # Wire in global MCP servers
+      if !default_mcp_servers.empty? && !merged.key?(:mcp_servers)
+        merged[:mcp_servers] = default_mcp_servers.dup
+      end
+
+      Options.new(**merged)
+    end
+  end
+end

data/lib/claude_agent/control_protocol/commands.rb

@@ -299,6 +299,34 @@ module ClaudeAgent
           errors: response["errors"] || {}
         )
       end
+      # Cancel a queued async user message (TypeScript SDK v0.2.76 parity)
+      #
+      # Drops a previously queued user message before it is processed.
+      #
+      # @param message_uuid [String] UUID of the message to cancel
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   protocol.cancel_async_message("msg-uuid-123")
+      #
+      def cancel_async_message(message_uuid)
+        send_control_request(subtype: "cancel_async_message", message_uuid: message_uuid)
+      end
+
+      # Get effective merged settings (TypeScript SDK v0.2.76 parity)
+      #
+      # Returns the current effective settings after merging all layers
+      # (user, project, local, flag, etc.).
+      #
+      # @return [Hash] Merged settings
+      #
+      # @example
+      #   settings = protocol.get_settings
+      #   puts settings["model"]
+      #
+      def get_settings
+        send_control_request(subtype: "get_settings")
+      end
     end
   end
 end

data/lib/claude_agent/conversation.rb

@@ -100,12 +100,21 @@ module ClaudeAgent
     # Send a message and receive the complete turn result.
     #
     # Auto-connects on first call. Appends to conversation history.
+    # Resets the tool tracker and abort signal at the start of each turn
+    # so they are fresh for the new operation.
+    #
+    # On abort, raises {AbortError} with the partial {TurnResult} attached.
+    # The tool tracker retains its state from the aborted turn until the
+    # next call to {#say}.
     #
     # @param prompt [String, Array] The message content
     # @yield [Message] Each message as it streams in (optional)
     # @return [TurnResult] The completed turn
+    # @raise [AbortError] If abort signal is triggered (with partial_turn attached)
     def say(prompt, &block)
       ensure_connected!
+      @tool_tracker&.reset!
+      @options.abort_signal&.reset!
 
       logger.debug("conversation") { "Turn #{@turns.size}: sending message" }
 
@@ -116,7 +125,6 @@ module ClaudeAgent
 
       @turns << turn
       build_tool_activities(turn, @turns.size - 1)
-      @tool_tracker&.reset!
 
       logger.info("conversation") { "Turn #{@turns.size - 1} complete (#{turn.tool_uses.size} tools, cost=$#{total_cost})" }
 
@@ -218,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,17 +87,34 @@ 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,
   # such as through a user interrupt or abort signal.
   #
-  # @example
-  #   raise ClaudeAgent::AbortError, "Operation cancelled by user"
+  # When raised from {Client#receive_turn} or {Conversation#say},
+  # carries a partial {TurnResult} with whatever was accumulated
+  # before cancellation (text, tool executions, usage).
+  #
+  # @example Accessing partial results
+  #   begin
+  #     turn = conversation.say("Fix the bug")
+  #   rescue ClaudeAgent::AbortError => e
+  #     turn = e.partial_turn
+  #     puts turn.text         # accumulated text (from stream events if needed)
+  #     puts turn.tool_uses    # tools that were called before abort
+  #   end
   #
   class AbortError < Error
-    def initialize(message = "Operation was aborted")
-      super
+    # @return [TurnResult, nil] Partial turn accumulated before abort
+    attr_reader :partial_turn
+
+    def initialize(message = "Operation was aborted", partial_turn: nil)
+      @partial_turn = partial_turn
+      super(message)
     end
   end
 end

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/fork_session.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module ClaudeAgent
+  # Fork a session by creating a new session file with remapped UUIDs.
+  #
+  # Reads all JSONL entries from the source session, optionally truncates
+  # at a given message UUID, remaps all UUIDs to fresh values, and writes
+  # a new session file in the same project directory.
+  #
+  # @example Basic fork
+  #   result = ClaudeAgent.fork_session("abc-123-...")
+  #   puts result.session_id
+  #
+  # @example Fork with truncation and title
+  #   result = ClaudeAgent.fork_session(
+  #     "abc-123-...",
+  #     up_to_message_id: "msg-456-...",
+  #     title: "Forked conversation"
+  #   )
+  #
+  module ForkSession
+    UUID_FIELDS = %w[uuid parentUuid].freeze
+    SESSION_ID_FIELDS = %w[session_id sessionId].freeze
+
+    module_function
+
+    # Fork a session, creating a new session file with remapped UUIDs.
+    #
+    # @param session_id [String] UUID of the source session
+    # @param up_to_message_id [String, nil] If provided, truncate at this message UUID (inclusive)
+    # @param title [String, nil] If provided, append a custom-title entry
+    # @param dir [String, nil] Project directory to find the session in
+    # @return [ForkSessionResult] Result with the new session ID
+    # @raise [ArgumentError] If session_id is not a valid UUID
+    # @raise [Error] If the session file is not found
+    def call(session_id, up_to_message_id: nil, title: nil, dir: nil)
+      SessionMutations.send(:validate_session_id!, session_id)
+
+      source_path = SessionMutations.send(:find_session_file, session_id, dir: dir)
+      raise Error, "Session not found: #{session_id}" unless source_path
+
+      lines = File.readlines(source_path, chomp: true)
+      entries = lines.filter_map do |line|
+        next if line.strip.empty?
+        JSON.parse(line)
+      end
+
+      # Truncate at up_to_message_id (inclusive)
+      if up_to_message_id
+        cut_index = entries.index { |e| e["uuid"] == up_to_message_id }
+        raise ArgumentError, "Message not found: #{up_to_message_id}" unless cut_index
+        entries = entries[0..cut_index]
+      end
+
+      # Generate new session ID and UUID map
+      new_session_id = SecureRandom.uuid
+      uuid_map = build_uuid_map(entries)
+
+      # Remap all entries
+      remapped = entries.map { |entry| remap_entry(entry, uuid_map, new_session_id) }
+
+      # Append custom-title entry if requested
+      if title
+        remapped << {
+          "type" => "custom-title",
+          "customTitle" => title.to_s,
+          "sessionId" => new_session_id
+        }
+      end
+
+      # Write new session file in the same directory as the source
+      dest_path = File.join(File.dirname(source_path), "#{new_session_id}.jsonl")
+      File.open(dest_path, "w") do |f|
+        remapped.each { |entry| f.write("#{JSON.generate(entry)}\n") }
+      end
+
+      ForkSessionResult.new(session_id: new_session_id)
+    end
+
+    # Build a map of old UUIDs to new UUIDs from all entries.
+    # @param entries [Array<Hash>]
+    # @return [Hash<String, String>]
+    def build_uuid_map(entries)
+      map = {}
+      entries.each do |entry|
+        UUID_FIELDS.each do |field|
+          value = entry[field]
+          next unless value.is_a?(String) && !value.empty?
+          map[value] ||= SecureRandom.uuid
+        end
+      end
+      map
+    end
+
+    # Remap UUID and session_id fields in an entry.
+    # @param entry [Hash] Original entry
+    # @param uuid_map [Hash<String, String>] Old UUID to new UUID mapping
+    # @param new_session_id [String] New session ID
+    # @return [Hash] Remapped entry
+    def remap_entry(entry, uuid_map, new_session_id)
+      result = entry.dup
+
+      UUID_FIELDS.each do |field|
+        result[field] = uuid_map[result[field]] if result.key?(field) && uuid_map.key?(result[field])
+      end
+
+      SESSION_ID_FIELDS.each do |field|
+        result[field] = new_session_id if result.key?(field)
+      end
+
+      result
+    end
+  end
+end

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/hooks.rb

@@ -14,6 +14,7 @@ module ClaudeAgent
     SubagentStart
     SubagentStop
     PreCompact
+    PostCompact
     PermissionRequest
     Setup
     TeammateIdle
@@ -184,6 +185,9 @@ module ClaudeAgent
     required: [ :trigger ],
     optional: { custom_instructions: nil }
 
+  BaseHookInput.define_input "PostCompact",
+    required: [ :trigger, :compact_summary ]
+
   BaseHookInput.define_input "PermissionRequest",
     required: [ :tool_name, :tool_input ],
     optional: { permission_suggestions: nil }

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" }