swarm_sdk 2.0.2 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2cedd1197d0fea1e52b40531ecb6d6f030524436c3164c109bce37da1db883b
-  data.tar.gz: ac77a97bd54374a9049de888e0dfc4a1b1c99d5a4fdc2c01fabe20e54a7cd83b
+  metadata.gz: 2d1058470f6d37e95003807ae0ea2201aa587c8026417a5d8a793cbd59b80b46
+  data.tar.gz: 266b8559bf752f72a6db3a8b47fae0890d6aa34f3edf7d66a61e6a4cb9c28d6c
 SHA512:
-  metadata.gz: 9d1dfdd64d1247e15a3fea9ce56b0d28657e85a5f9d706d1a2ce9c72700226cf443dcdc691596710d2e948816a3fb5d93fe1520f3bc798df78a2b6a91e9a2085
-  data.tar.gz: b54ae2918f3cb04eb2a49a80faecc2aac1a878cd14828cc3287705eae22ba4da09780c8e38a54c5d048cf4eb1fec75e523dc609192758f6ad60294467d68df01
+  metadata.gz: cb6a9ccd6fa58cf55c062201f23391ebe10476894d5fc7f4838fbf90ade073d9e438257c0a007e20a636bba35764de8c434e381fdbc9114354e76c9d87252239
+  data.tar.gz: f281689946db6a04ab879f23fc922d7d06d3719a68f515e316b3497cc0ce0e075428623518e6f3ba9cee235f5b0389e2360406c49479a1b9e7c7a22ec533fcec

data/lib/swarm_sdk/agent/builder.rb

@@ -44,7 +44,7 @@ module SwarmSDK
         @headers = {}
         @timeout = nil
         @mcp_servers = []
-        @include_default_tools = true
+        @disable_default_tools = nil # nil = include all default tools
         @bypass_permissions = false
         @coding_agent = nil # nil = not set (will default to false in Definition)
         @assume_model_exists = nil
@@ -124,9 +124,19 @@ module SwarmSDK
         @mcp_servers << server_config
       end
 
-      # Set include_default_tools flag (deprecated - use tools method with include_default parameter)
-      def include_default_tools(enabled)
-        @include_default_tools = enabled
+      # Disable default tools
+      #
+      # @param value [Boolean, Array<Symbol>]
+      #   - true: Disable ALL default tools
+      #   - Array of symbols: Disable specific tools (e.g., [:Think, :TodoWrite])
+      #
+      # @example Disable all default tools
+      #   disable_default_tools true
+      #
+      # @example Disable specific tools
+      #   disable_default_tools [:Think, :TodoWrite]
+      def disable_default_tools(value)
+        @disable_default_tools = value
       end
 
       # Set bypass_permissions flag
@@ -188,7 +198,8 @@ module SwarmSDK
       def tools(*tool_names, include_default: true, replace: false)
         @tools = Set.new if replace
         @tools.merge(tool_names.map(&:to_sym))
-        @include_default_tools = include_default
+        # When include_default is false, disable all default tools
+        @disable_default_tools = true unless include_default
       end
 
       # Add tools from all_agents configuration
@@ -342,7 +353,7 @@ module SwarmSDK
         agent_config[:headers] = @headers if @headers.any?
         agent_config[:timeout] = @timeout if @timeout
         agent_config[:mcp_servers] = @mcp_servers if @mcp_servers.any?
-        agent_config[:include_default_tools] = @include_default_tools
+        agent_config[:disable_default_tools] = @disable_default_tools unless @disable_default_tools.nil?
         agent_config[:bypass_permissions] = @bypass_permissions
         agent_config[:coding_agent] = @coding_agent
         agent_config[:assume_model_exists] = @assume_model_exists unless @assume_model_exists.nil?

data/lib/swarm_sdk/agent/definition.rb

@@ -38,7 +38,7 @@ module SwarmSDK
         :parameters,
         :headers,
         :timeout,
-        :include_default_tools,
+        :disable_default_tools,
         :coding_agent,
         :default_permissions,
         :agent_permissions,
@@ -77,8 +77,11 @@ module SwarmSDK
         # This prevents RubyLLM from trying to validate models in its registry
         @assume_model_exists = true
 
-        # include_default_tools defaults to true if not specified
-        @include_default_tools = config.key?(:include_default_tools) ? config[:include_default_tools] : true
+        # disable_default_tools can be:
+        # - nil/not set: include all default tools (default behavior)
+        # - true: disable ALL default tools
+        # - Array of symbols: disable specific tools (e.g., [:Think, :TodoWrite])
+        @disable_default_tools = config[:disable_default_tools]
 
         # coding_agent defaults to false if not specified
         # When true, includes the base system prompt for coding tasks
@@ -117,7 +120,7 @@ module SwarmSDK
         {
           name: @name,
           description: @description,
-          model: @model,
+          model: SwarmSDK::Models.resolve_alias(@model), # Resolve model aliases
           directory: @directory,
           tools: @tools,
           delegates_to: @delegates_to,
@@ -130,7 +133,7 @@ module SwarmSDK
           headers: @headers,
           timeout: @timeout,
           bypass_permissions: @bypass_permissions,
-          include_default_tools: @include_default_tools,
+          disable_default_tools: @disable_default_tools,
           coding_agent: @coding_agent,
           assume_model_exists: @assume_model_exists,
           max_concurrent_tools: @max_concurrent_tools,
@@ -224,7 +227,7 @@ module SwarmSDK
           else
             rendered_base
           end
-        elsif @include_default_tools
+        elsif default_tools_enabled?
           # Non-coding agent: optionally include TODO/Scratchpad sections if default tools available
           non_coding_base = render_non_coding_base_prompt
 
@@ -242,6 +245,13 @@ module SwarmSDK
         end
       end
 
+      # Check if default tools are enabled (i.e., not disabled)
+      #
+      # @return [Boolean] True if default tools should be included
+      def default_tools_enabled?
+        @disable_default_tools != true
+      end
+
       def render_base_system_prompt
         cwd = @directory || Dir.pwd
         platform = RUBY_PLATFORM

data/lib/swarm_sdk/configuration.rb

@@ -116,6 +116,11 @@ module SwarmSDK
       return unless @config[:swarm]
 
       @all_agents_config = @config[:swarm][:all_agents] || {}
+
+      # Convert disable_default_tools array elements to symbols
+      if @all_agents_config[:disable_default_tools].is_a?(Array)
+        @all_agents_config[:disable_default_tools] = @all_agents_config[:disable_default_tools].map(&:to_sym)
+      end
     end
 
     def load_hooks_config
@@ -212,6 +217,9 @@ module SwarmSDK
           # Merge headers: all_agents.headers + agent.headers
           # Agent values override all_agents values for same keys
           merged[:headers] = (merged[:headers] || {}).merge(value || {})
+        when :disable_default_tools
+          # Convert array elements to symbols if it's an array
+          merged[key] = value.is_a?(Array) ? value.map(&:to_sym) : value
         else
           # For everything else (model, provider, base_url, timeout, coding_agent, etc.),
           # agent value overrides all_agents value

data/lib/swarm_sdk/swarm/builder.rb

@@ -278,7 +278,7 @@ module SwarmSDK
         # Don't apply assume_model_exists from markdown - let DSL overrides or auto-enable handle it
         # builder.assume_model_exists(config[:assume_model_exists]) unless config[:assume_model_exists].nil?
         builder.bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
-        builder.include_default_tools(config[:include_default_tools]) unless config[:include_default_tools].nil?
+        builder.disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
 
         # Add tools from markdown
         if config[:tools]&.any?

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -12,7 +12,7 @@ module SwarmSDK
     #
     # This encapsulates all tool-related logic that was previously in Swarm.
     class ToolConfigurator
-      # Default tools available to all agents (unless include_default_tools: false)
+      # Default tools available to all agents (unless disable_default_tools is set)
       DEFAULT_TOOLS = [
         :Read,
         :Grep,
@@ -20,7 +20,9 @@ module SwarmSDK
         :TodoWrite,
         :ScratchpadWrite,
         :ScratchpadRead,
-        :ScratchpadList,
+        :ScratchpadGlob,
+        :ScratchpadGrep,
+        :Think,
       ].freeze
 
       def initialize(swarm, scratchpad)
@@ -72,9 +74,17 @@ module SwarmSDK
         when :ScratchpadWrite
           Tools::ScratchpadWrite.create_for_scratchpad(@scratchpad)
         when :ScratchpadRead
-          Tools::ScratchpadRead.create_for_scratchpad(@scratchpad)
-        when :ScratchpadList
-          Tools::ScratchpadList.create_for_scratchpad(@scratchpad)
+          Tools::ScratchpadRead.create_for_scratchpad(@scratchpad, agent_name)
+        when :ScratchpadEdit
+          Tools::ScratchpadEdit.create_for_scratchpad(@scratchpad, agent_name)
+        when :ScratchpadMultiEdit
+          Tools::ScratchpadMultiEdit.create_for_scratchpad(@scratchpad, agent_name)
+        when :ScratchpadGlob
+          Tools::ScratchpadGlob.create_for_scratchpad(@scratchpad)
+        when :ScratchpadGrep
+          Tools::ScratchpadGrep.create_for_scratchpad(@scratchpad)
+        when :Think
+          Tools::Think.new
         else
           # Regular tools - get class from registry and instantiate
           tool_class = Tools::Registry.get(tool_name_sym)
@@ -133,13 +143,14 @@ module SwarmSDK
         end
       end
 
-      # Register default tools for agents that have include_default_tools enabled
+      # Register default tools for agents (unless disabled)
       #
       # @param chat [AgentChat] The chat instance
       # @param agent_name [Symbol] Agent name
       # @param agent_definition [AgentDefinition] Agent definition
       def register_default_tools(chat, agent_name:, agent_definition:)
-        return unless agent_definition.include_default_tools
+        # If disable_default_tools is true, skip all default tools
+        return if agent_definition.disable_default_tools == true
 
         # Get explicit tool names to avoid duplicates
         explicit_tool_names = agent_definition.tools.map { |t| t[:name] }.to_set
@@ -148,6 +159,9 @@ module SwarmSDK
           # Skip if already registered explicitly
           next if explicit_tool_names.include?(tool_name)
 
+          # Skip if tool is in the disable list
+          next if tool_disabled?(tool_name, agent_definition.disable_default_tools)
+
           tool_instance = create_tool_instance(tool_name, agent_name, agent_definition.directory)
 
           # Resolve permissions for default tool (same logic as AgentDefinition)
@@ -166,6 +180,25 @@ module SwarmSDK
         end
       end
 
+      # Check if a tool should be disabled based on disable_default_tools config
+      #
+      # @param tool_name [Symbol] Tool name to check
+      # @param disable_config [nil, Boolean, Array<Symbol>] Disable configuration
+      # @return [Boolean] True if tool should be disabled
+      def tool_disabled?(tool_name, disable_config)
+        return false if disable_config.nil?
+
+        if disable_config == true
+          # Disable all default tools
+          true
+        elsif disable_config.is_a?(Array)
+          # Disable only tools in the array
+          disable_config.include?(tool_name)
+        else
+          false
+        end
+      end
+
       # Register agent delegation tools
       #
       # Creates delegation tools that allow one agent to call another.

data/lib/swarm_sdk/swarm.rb

@@ -129,7 +129,8 @@ module SwarmSDK
     # @param name [String] Human-readable swarm name
     # @param global_concurrency [Integer] Max concurrent LLM calls across entire swarm
     # @param default_local_concurrency [Integer] Default max concurrent tool calls per agent
-    def initialize(name:, global_concurrency: DEFAULT_GLOBAL_CONCURRENCY, default_local_concurrency: DEFAULT_LOCAL_CONCURRENCY)
+    # @param scratchpad [Tools::Stores::Scratchpad, nil] Optional scratchpad instance (for testing)
+    def initialize(name:, global_concurrency: DEFAULT_GLOBAL_CONCURRENCY, default_local_concurrency: DEFAULT_LOCAL_CONCURRENCY, scratchpad: nil)
       @name = name
       @global_concurrency = global_concurrency
       @default_local_concurrency = default_local_concurrency
@@ -138,7 +139,11 @@ module SwarmSDK
       @global_semaphore = Async::Semaphore.new(@global_concurrency)
 
       # Shared scratchpad for all agents
-      @scratchpad = Tools::Stores::Scratchpad.new
+      # Use provided scratchpad (for testing) or create persistent one
+      @scratchpad = scratchpad || begin
+        scratchpad_path = File.join(Dir.pwd, ".swarm", "scratchpad.json")
+        Tools::Stores::Scratchpad.new(persist_to: scratchpad_path)
+      end
 
       # Hook registry for named hooks and swarm defaults
       @hook_registry = Hooks::Registry.new

data/lib/swarm_sdk/tools/registry.rb

@@ -19,7 +19,9 @@ module SwarmSDK
         TodoWrite: :special, # Requires agent context for todo tracking
         ScratchpadWrite: :special, # Requires scratchpad instance
         ScratchpadRead: :special, # Requires scratchpad instance
-        ScratchpadList: :special, # Requires scratchpad instance
+        ScratchpadGlob: :special, # Requires scratchpad instance
+        ScratchpadGrep: :special, # Requires scratchpad instance
+        Think: SwarmSDK::Tools::Think,
       }.freeze
 
       class << self

data/lib/swarm_sdk/tools/scratchpad_edit.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for editing scratchpad entries with exact string replacement
+    #
+    # Performs exact string replacements in scratchpad content.
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadEdit < RubyLLM::Tool
+      define_method(:name) { "ScratchpadEdit" }
+
+      description <<~DESC
+        Performs exact string replacements in scratchpad entries.
+        Works like the Edit tool but operates on scratchpad content instead of files.
+        You must use ScratchpadRead on the entry before editing it.
+        When editing text from ScratchpadRead output, ensure you preserve the exact indentation as it appears AFTER the line number prefix.
+        The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual content to match.
+        Never include any part of the line number prefix in the old_string or new_string.
+        The edit will FAIL if old_string is not unique in the entry. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
+        Use replace_all for replacing and renaming strings across the entry.
+      DESC
+
+      param :file_path,
+        desc: "Path to the scratchpad entry (e.g., 'analysis/report', 'parallel/batch1/task_0')",
+        required: true
+
+      param :old_string,
+        desc: "The exact text to replace (must match exactly including whitespace)",
+        required: true
+
+      param :new_string,
+        desc: "The text to replace it with (must be different from old_string)",
+        required: true
+
+      param :replace_all,
+        desc: "Replace all occurrences of old_string (default false)",
+        required: false
+
+      class << self
+        # Create a ScratchpadEdit tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @param agent_name [Symbol, String] Agent identifier for tracking reads
+        # @return [ScratchpadEdit] Tool instance
+        def create_for_scratchpad(scratchpad, agent_name)
+          new(scratchpad, agent_name)
+        end
+      end
+
+      # Initialize with scratchpad instance and agent name
+      #
+      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+      # @param agent_name [Symbol, String] Agent identifier
+      def initialize(scratchpad, agent_name)
+        super() # Call RubyLLM::Tool's initialize
+        @scratchpad = scratchpad
+        @agent_name = agent_name.to_sym
+      end
+
+      # Execute the tool
+      #
+      # @param file_path [String] Path to scratchpad entry
+      # @param old_string [String] Text to replace
+      # @param new_string [String] Replacement text
+      # @param replace_all [Boolean] Replace all occurrences
+      # @return [String] Success message or error
+      def execute(file_path:, old_string:, new_string:, replace_all: false)
+        # Validate inputs
+        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+        return validation_error("old_string is required") if old_string.nil? || old_string.empty?
+        return validation_error("new_string is required") if new_string.nil?
+
+        # old_string and new_string must be different
+        if old_string == new_string
+          return validation_error("old_string and new_string must be different. They are currently identical.")
+        end
+
+        # Read current content (this will raise ArgumentError if entry doesn't exist)
+        content = scratchpad.read(file_path: file_path)
+
+        # Enforce read-before-edit
+        unless Stores::ScratchpadReadTracker.entry_read?(@agent_name, file_path)
+          return validation_error(
+            "Cannot edit scratchpad entry without reading it first. " \
+              "You must use ScratchpadRead on 'scratchpad://#{file_path}' before editing it. " \
+              "This ensures you have the current content to match against.",
+          )
+        end
+
+        # Check if old_string exists in content
+        unless content.include?(old_string)
+          return validation_error(<<~ERROR.chomp)
+            old_string not found in scratchpad entry. Make sure it matches exactly, including all whitespace and indentation.
+            Do not include line number prefixes from ScratchpadRead tool output.
+          ERROR
+        end
+
+        # Count occurrences
+        occurrences = content.scan(old_string).count
+
+        # If not replace_all and multiple occurrences, error
+        if !replace_all && occurrences > 1
+          return validation_error(<<~ERROR.chomp)
+            Found #{occurrences} occurrences of old_string.
+            Either provide more surrounding context to make the match unique, or use replace_all: true to replace all occurrences.
+          ERROR
+        end
+
+        # Perform replacement
+        new_content = if replace_all
+          content.gsub(old_string, new_string)
+        else
+          content.sub(old_string, new_string)
+        end
+
+        # Get existing entry metadata
+        entries = scratchpad.list
+        existing_entry = entries.find { |e| e[:path] == file_path }
+
+        # Write updated content back (preserving the title)
+        scratchpad.write(
+          file_path: file_path,
+          content: new_content,
+          title: existing_entry[:title],
+        )
+
+        # Build success message
+        replaced_count = replace_all ? occurrences : 1
+        "Successfully replaced #{replaced_count} occurrence(s) in scratchpad://#{file_path}"
+      rescue ArgumentError => e
+        validation_error(e.message)
+      end
+
+      private
+
+      attr_reader :scratchpad
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/{scratchpad_list.rb → scratchpad_glob.rb}

@@ -2,28 +2,34 @@
 
 module SwarmSDK
   module Tools
-    # Tool for listing scratchpad entries with metadata
+    # Tool for searching scratchpad entries by glob pattern
     #
-    # Lists available scratchpad entries with titles and sizes.
-    # Supports filtering by path prefix.
-    class ScratchpadList < RubyLLM::Tool
-      define_method(:name) { "ScratchpadList" }
+    # Finds scratchpad entries matching a glob pattern (like filesystem glob).
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadGlob < RubyLLM::Tool
+      define_method(:name) { "ScratchpadGlob" }
 
       description <<~DESC
-        List available scratchpad entries with titles and metadata.
-        Use this to discover what content is available in scratchpad memory.
-        Optionally filter by path prefix.
+        Search scratchpad entries by glob pattern.
+        Works like filesystem glob - use * for wildcards, ** for recursive matching.
+        Use this to discover entries matching specific patterns.
+
+        Examples:
+        - "parallel/*" - all entries directly under parallel/
+        - "parallel/**" - all entries under parallel/ (recursive)
+        - "*/report" - all entries named "report" in any top-level directory
+        - "analysis/*/result_*" - entries like "analysis/foo/result_1"
       DESC
 
-      param :prefix,
-        desc: "Filter by path prefix (e.g., 'parallel/', 'analysis/'). Leave empty to list all entries.",
-        required: false
+      param :pattern,
+        desc: "Glob pattern to match (e.g., '**/*.txt', 'parallel/*/task_*')",
+        required: true
 
       class << self
-        # Create a ScratchpadList tool for a specific scratchpad instance
+        # Create a ScratchpadGlob tool for a specific scratchpad instance
         #
         # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-        # @return [ScratchpadList] Tool instance
+        # @return [ScratchpadGlob] Tool instance
         def create_for_scratchpad(scratchpad)
           new(scratchpad)
         end
@@ -39,19 +45,17 @@ module SwarmSDK
 
       # Execute the tool
       #
-      # @param prefix [String, nil] Optional path prefix filter
-      # @return [String] Formatted list of entries
-      def execute(prefix: nil)
-        entries = scratchpad.list(prefix: prefix)
+      # @param pattern [String] Glob pattern to match
+      # @return [String] Formatted list of matching entries
+      def execute(pattern:)
+        entries = scratchpad.glob(pattern: pattern)
 
         if entries.empty?
-          return "Scratchpad is empty" if prefix.nil? || prefix.empty?
-
-          return "No entries found with prefix '#{prefix}'"
+          return "No entries found matching pattern '#{pattern}'"
         end
 
         result = []
-        result << "Scratchpad contents (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
+        result << "Scratchpad entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
 
         entries.each do |entry|
           result << "  scratchpad://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"

data/lib/swarm_sdk/tools/scratchpad_grep.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for searching scratchpad content by pattern
+    #
+    # Searches content stored in scratchpad entries using regex patterns.
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadGrep < RubyLLM::Tool
+      define_method(:name) { "ScratchpadGrep" }
+
+      description <<~DESC
+        Search scratchpad content by pattern (like grep).
+        Use regex patterns to search content within scratchpad entries.
+        Returns matching entries and optionally line numbers and content.
+
+        Output modes:
+        - files_with_matches: Only list paths containing matches (default)
+        - content: Show matching lines with line numbers
+        - count: Show number of matches per file
+      DESC
+
+      param :pattern,
+        desc: "Regular expression pattern to search for",
+        required: true
+
+      param :case_insensitive,
+        desc: "Perform case-insensitive search (default: false)",
+        required: false
+
+      param :output_mode,
+        desc: "Output mode: 'files_with_matches' (default), 'content', or 'count'",
+        required: false
+
+      class << self
+        # Create a ScratchpadGrep tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @return [ScratchpadGrep] Tool instance
+        def create_for_scratchpad(scratchpad)
+          new(scratchpad)
+        end
+      end
+
+      # Initialize with scratchpad instance
+      #
+      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+      def initialize(scratchpad)
+        super() # Call RubyLLM::Tool's initialize
+        @scratchpad = scratchpad
+      end
+
+      # Execute the tool
+      #
+      # @param pattern [String] Regex pattern to search for
+      # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+      # @param output_mode [String] Output mode
+      # @return [String] Formatted search results
+      def execute(pattern:, case_insensitive: false, output_mode: "files_with_matches")
+        results = scratchpad.grep(
+          pattern: pattern,
+          case_insensitive: case_insensitive,
+          output_mode: output_mode,
+        )
+
+        format_results(results, pattern, output_mode)
+      rescue ArgumentError => e
+        validation_error(e.message)
+      rescue RegexpError => e
+        validation_error("Invalid regex pattern: #{e.message}")
+      end
+
+      private
+
+      attr_reader :scratchpad
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def format_results(results, pattern, output_mode)
+        case output_mode
+        when "files_with_matches"
+          format_files_with_matches(results, pattern)
+        when "content"
+          format_content(results, pattern)
+        when "count"
+          format_count(results, pattern)
+        else
+          validation_error("Invalid output_mode: #{output_mode}")
+        end
+      end
+
+      def format_files_with_matches(paths, pattern)
+        if paths.empty?
+          return "No matches found for pattern '#{pattern}'"
+        end
+
+        result = []
+        result << "Scratchpad entries matching '#{pattern}' (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
+        paths.each do |path|
+          result << "  scratchpad://#{path}"
+        end
+        result.join("\n")
+      end
+
+      def format_content(results, pattern)
+        if results.empty?
+          return "No matches found for pattern '#{pattern}'"
+        end
+
+        total_matches = results.sum { |r| r[:matches].size }
+        output = []
+        output << "Scratchpad entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
+        output << ""
+
+        results.each do |result|
+          output << "scratchpad://#{result[:path]}:"
+          result[:matches].each do |match|
+            output << "  #{match[:line_number]}: #{match[:content]}"
+          end
+          output << ""
+        end
+
+        output.join("\n").rstrip
+      end
+
+      def format_count(results, pattern)
+        if results.empty?
+          return "No matches found for pattern '#{pattern}'"
+        end
+
+        total_matches = results.sum { |r| r[:count] }
+        output = []
+        output << "Scratchpad entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
+
+        results.each do |result|
+          output << "  scratchpad://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
+        end
+
+        output.join("\n")
+      end
+    end
+  end
+end