swarm_sdk 2.0.3 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9aba64a75c41f9957bb3e11afbe0dd5a5fc6422793fda5d3fb829ac0042cbe18
-  data.tar.gz: 4f403fb7d107fa712a8b847775fea1140a03904cf066b8e848b914f4b3c573e3
+  metadata.gz: 2d1058470f6d37e95003807ae0ea2201aa587c8026417a5d8a793cbd59b80b46
+  data.tar.gz: 266b8559bf752f72a6db3a8b47fae0890d6aa34f3edf7d66a61e6a4cb9c28d6c
 SHA512:
-  metadata.gz: 204b9d889968b2d582557b06169d02828abd4c365b00e2a6551cc7f4c44a2ec7ae452a55d1e25b59fdc8a0b10c486c365cce2b2332d02f0d54b502ec6667af75
-  data.tar.gz: ae46da01755ef0c98b162c7c2be3c51ba8831dbbdd10301f937e0eed0260f9694b7514658d437e9d65d9cc58e06d7a877600ec29fd48eb773eec8514d74440b1
+  metadata.gz: cb6a9ccd6fa58cf55c062201f23391ebe10476894d5fc7f4838fbf90ade073d9e438257c0a007e20a636bba35764de8c434e381fdbc9114354e76c9d87252239
+  data.tar.gz: f281689946db6a04ab879f23fc922d7d06d3719a68f515e316b3497cc0ce0e075428623518e6f3ba9cee235f5b0389e2360406c49479a1b9e7c7a22ec533fcec

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -20,7 +20,8 @@ module SwarmSDK
         :TodoWrite,
         :ScratchpadWrite,
         :ScratchpadRead,
-        :ScratchpadList,
+        :ScratchpadGlob,
+        :ScratchpadGrep,
         :Think,
       ].freeze
 
@@ -73,9 +74,15 @@ 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

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,8 @@ 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
 

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

data/lib/swarm_sdk/tools/scratchpad_multi_edit.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for performing multiple edits to a scratchpad entry
+    #
+    # Applies multiple edit operations sequentially to a single scratchpad entry.
+    # Each edit sees the result of all previous edits, allowing for
+    # coordinated multi-step transformations.
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadMultiEdit < RubyLLM::Tool
+      define_method(:name) { "ScratchpadMultiEdit" }
+
+      description <<~DESC
+        Performs multiple exact string replacements in a single scratchpad entry.
+        Edits are applied sequentially, so later edits see the results of earlier ones.
+        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.
+        Each 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 :edits_json,
+        type: "string",
+        desc: <<~DESC.chomp,
+          JSON array of edit operations. Each edit must have:
+          old_string (exact text to replace),
+          new_string (replacement text),
+          and optionally replace_all (boolean, default false).
+          Example: [{"old_string":"foo","new_string":"bar","replace_all":false}]
+        DESC
+        required: true
+
+      class << self
+        # Create a ScratchpadMultiEdit tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @param agent_name [Symbol, String] Agent identifier for tracking reads
+        # @return [ScratchpadMultiEdit] 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 edits_json [String] JSON array of edit operations
+      # @return [String] Success message or error
+      def execute(file_path:, edits_json:)
+        # Validate inputs
+        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+
+        # Parse JSON
+        edits = begin
+          JSON.parse(edits_json)
+        rescue JSON::ParserError
+          nil
+        end
+
+        return validation_error("Invalid JSON format. Please provide a valid JSON array of edit operations.") if edits.nil?
+
+        return validation_error("edits must be an array") unless edits.is_a?(Array)
+        return validation_error("edits array cannot be empty") if edits.empty?
+
+        # 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
+
+        # Validate edit operations
+        validated_edits = []
+        edits.each_with_index do |edit, index|
+          unless edit.is_a?(Hash)
+            return validation_error("Edit at index #{index} must be a hash/object with old_string and new_string")
+          end
+
+          # Convert string keys to symbols for consistency
+          edit = edit.transform_keys(&:to_sym)
+
+          unless edit[:old_string]
+            return validation_error("Edit at index #{index} missing required field 'old_string'")
+          end
+
+          unless edit[:new_string]
+            return validation_error("Edit at index #{index} missing required field 'new_string'")
+          end
+
+          # old_string and new_string must be different
+          if edit[:old_string] == edit[:new_string]
+            return validation_error("Edit at index #{index}: old_string and new_string must be different")
+          end
+
+          validated_edits << {
+            old_string: edit[:old_string].to_s,
+            new_string: edit[:new_string].to_s,
+            replace_all: edit[:replace_all] == true,
+            index: index,
+          }
+        end
+
+        # Apply edits sequentially
+        results = []
+        current_content = content
+
+        validated_edits.each do |edit|
+          # Check if old_string exists in current content
+          unless current_content.include?(edit[:old_string])
+            return error_with_results(
+              <<~ERROR.chomp,
+                Edit #{edit[:index]}: 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.
+                Note: This edit follows #{edit[:index]} previous edit(s) which may have changed the content.
+              ERROR
+              results,
+            )
+          end
+
+          # Count occurrences
+          occurrences = current_content.scan(edit[:old_string]).count
+
+          # If not replace_all and multiple occurrences, error
+          if !edit[:replace_all] && occurrences > 1
+            return error_with_results(
+              <<~ERROR.chomp,
+                Edit #{edit[:index]}: Found #{occurrences} occurrences of old_string.
+                Either provide more surrounding context to make the match unique, or set replace_all: true to replace all occurrences.
+              ERROR
+              results,
+            )
+          end
+
+          # Perform replacement
+          new_content = if edit[:replace_all]
+            current_content.gsub(edit[:old_string], edit[:new_string])
+          else
+            current_content.sub(edit[:old_string], edit[:new_string])
+          end
+
+          # Record result
+          replaced_count = edit[:replace_all] ? occurrences : 1
+          results << {
+            index: edit[:index],
+            status: "success",
+            occurrences: replaced_count,
+            message: "Replaced #{replaced_count} occurrence(s)",
+          }
+
+          # Update content for next edit
+          current_content = new_content
+        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: current_content,
+          title: existing_entry[:title],
+        )
+
+        # Build success message
+        total_replacements = results.sum { |r| r[:occurrences] }
+        message = "Successfully applied #{validated_edits.size} edit(s) to scratchpad://#{file_path}\n"
+        message += "Total replacements: #{total_replacements}\n\n"
+        message += "Details:\n"
+        results.each do |result|
+          message += "  Edit #{result[:index]}: #{result[:message]}\n"
+        end
+
+        message
+      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
+
+      def error_with_results(message, results)
+        output = "<tool_use_error>InputValidationError: #{message}\n\n"
+
+        if results.any?
+          output += "Previous successful edits before error:\n"
+          results.each do |result|
+            output += "  Edit #{result[:index]}: #{result[:message]}\n"
+          end
+          output += "\n"
+        end
+
+        output += "Note: The scratchpad entry has NOT been modified. All or nothing approach - if any edit fails, no changes are saved.</tool_use_error>"
+        output
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/scratchpad_read.rb

@@ -23,26 +23,33 @@ module SwarmSDK
         # Create a ScratchpadRead tool for a specific scratchpad instance
         #
         # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @param agent_name [Symbol, String] Agent identifier for tracking reads
         # @return [ScratchpadRead] Tool instance
-        def create_for_scratchpad(scratchpad)
-          new(scratchpad)
+        def create_for_scratchpad(scratchpad, agent_name)
+          new(scratchpad, agent_name)
         end
       end
 
-      # Initialize with scratchpad instance
+      # Initialize with scratchpad instance and agent name
       #
       # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
-      def initialize(scratchpad)
+      # @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 read from
-      # @return [String] Content at the path or error message
+      # @return [String] Content at the path with line numbers, or error message
       def execute(file_path:)
-        scratchpad.read(file_path: file_path)
+        # Register this read in the tracker
+        Stores::ScratchpadReadTracker.register_read(@agent_name, file_path)
+
+        content = scratchpad.read(file_path: file_path)
+        format_with_line_numbers(content)
       rescue ArgumentError => e
         validation_error(e.message)
       end
@@ -54,6 +61,20 @@ module SwarmSDK
       def validation_error(message)
         "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
       end
+
+      # Format content with line numbers (same format as Read tool)
+      #
+      # @param content [String] Content to format
+      # @return [String] Content with line numbers
+      def format_with_line_numbers(content)
+        lines = content.lines
+        output_lines = lines.each_with_index.map do |line, idx|
+          line_number = idx + 1
+          display_line = line.chomp
+          "#{line_number.to_s.rjust(6)}→#{display_line}"
+        end
+        output_lines.join("\n")
+      end
     end
   end
 end

data/lib/swarm_sdk/tools/stores/scratchpad.rb

@@ -22,9 +22,17 @@ module SwarmSDK
         # Represents a single scratchpad entry with metadata
         Entry = Struct.new(:content, :title, :created_at, :size, keyword_init: true)
 
-        def initialize
+        # Initialize scratchpad with optional persistence
+        #
+        # @param persist_to [String, nil] Path to JSON file for persistence (nil = no persistence)
+        def initialize(persist_to: nil)
           @entries = {}
           @total_size = 0
+          @persist_to = persist_to
+          @mutex = Mutex.new
+
+          # Load existing data if persistence is enabled
+          load_from_file if @persist_to && File.exist?(@persist_to)
         end
 
         # Write content to scratchpad
@@ -35,44 +43,49 @@ module SwarmSDK
         # @raise [ArgumentError] If size limits are exceeded
         # @return [Entry] The created entry
         def write(file_path:, content:, title:)
-          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
-          raise ArgumentError, "content is required" if content.nil?
-          raise ArgumentError, "title is required" if title.nil? || title.to_s.strip.empty?
+          @mutex.synchronize do
+            raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
+            raise ArgumentError, "content is required" if content.nil?
+            raise ArgumentError, "title is required" if title.nil? || title.to_s.strip.empty?
 
-          content_size = content.bytesize
+            content_size = content.bytesize
 
-          # Check entry size limit
-          if content_size > MAX_ENTRY_SIZE
-            raise ArgumentError, "Content exceeds maximum size (#{format_bytes(MAX_ENTRY_SIZE)}). " \
-              "Current: #{format_bytes(content_size)}"
-          end
+            # Check entry size limit
+            if content_size > MAX_ENTRY_SIZE
+              raise ArgumentError, "Content exceeds maximum size (#{format_bytes(MAX_ENTRY_SIZE)}). " \
+                "Current: #{format_bytes(content_size)}"
+            end
 
-          # Calculate new total size
-          existing_entry = @entries[file_path]
-          existing_size = existing_entry ? existing_entry.size : 0
-          new_total_size = @total_size - existing_size + content_size
-
-          # Check total size limit
-          if new_total_size > MAX_TOTAL_SIZE
-            raise ArgumentError, "Scratchpad full (#{format_bytes(MAX_TOTAL_SIZE)} limit). " \
-              "Current: #{format_bytes(@total_size)}, " \
-              "Would be: #{format_bytes(new_total_size)}. " \
-              "Clear old entries or use smaller content."
-          end
+            # Calculate new total size
+            existing_entry = @entries[file_path]
+            existing_size = existing_entry ? existing_entry.size : 0
+            new_total_size = @total_size - existing_size + content_size
+
+            # Check total size limit
+            if new_total_size > MAX_TOTAL_SIZE
+              raise ArgumentError, "Scratchpad full (#{format_bytes(MAX_TOTAL_SIZE)} limit). " \
+                "Current: #{format_bytes(@total_size)}, " \
+                "Would be: #{format_bytes(new_total_size)}. " \
+                "Clear old entries or use smaller content."
+            end
+
+            # Create entry
+            entry = Entry.new(
+              content: content,
+              title: title,
+              created_at: Time.now,
+              size: content_size,
+            )
 
-          # Create entry
-          entry = Entry.new(
-            content: content,
-            title: title,
-            created_at: Time.now,
-            size: content_size,
-          )
+            # Update storage
+            @entries[file_path] = entry
+            @total_size = new_total_size
 
-          # Update storage
-          @entries[file_path] = entry
-          @total_size = new_total_size
+            # Persist to file if enabled
+            save_to_file if @persist_to
 
-          entry
+            entry
+          end
         end
 
         # Read content from scratchpad
@@ -112,6 +125,74 @@ module SwarmSDK
           end.sort_by { |e| e[:path] }
         end
 
+        # Search entries by glob pattern (like filesystem glob)
+        #
+        # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
+        # @return [Array<Hash>] Array of matching entry metadata (path, title, size, created_at)
+        def glob(pattern:)
+          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
+
+          # Convert glob pattern to regex
+          regex = glob_to_regex(pattern)
+
+          # Filter entries by pattern
+          matching_entries = @entries.select { |path, _| regex.match?(path) }
+
+          # Return metadata sorted by path
+          matching_entries.map do |path, entry|
+            {
+              path: path,
+              title: entry.title,
+              size: entry.size,
+              created_at: entry.created_at,
+            }
+          end.sort_by { |e| e[:path] }
+        end
+
+        # Search entry content by pattern (like grep)
+        #
+        # @param pattern [String] Regular expression pattern to search for
+        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+        # @param output_mode [String] Output mode: "files_with_matches" (default), "content", or "count"
+        # @return [Array<Hash>, String] Results based on output_mode
+        def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
+          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
+
+          # Create regex from pattern
+          flags = case_insensitive ? Regexp::IGNORECASE : 0
+          regex = Regexp.new(pattern, flags)
+
+          case output_mode
+          when "files_with_matches"
+            # Return just the paths that match
+            matching_paths = @entries.select { |_path, entry| regex.match?(entry.content) }
+              .map { |path, _| path }
+              .sort
+            matching_paths
+          when "content"
+            # Return paths with matching lines
+            results = []
+            @entries.each do |path, entry|
+              matching_lines = []
+              entry.content.each_line.with_index(1) do |line, line_num|
+                matching_lines << { line_number: line_num, content: line.chomp } if regex.match?(line)
+              end
+              results << { path: path, matches: matching_lines } unless matching_lines.empty?
+            end
+            results.sort_by { |r| r[:path] }
+          when "count"
+            # Return paths with match counts
+            results = []
+            @entries.each do |path, entry|
+              count = entry.content.scan(regex).size
+              results << { path: path, count: count } if count > 0
+            end
+            results.sort_by { |r| r[:path] }
+          else
+            raise ArgumentError, "Invalid output_mode: #{output_mode}. Must be 'files_with_matches', 'content', or 'count'"
+          end
+        end
+
         # Clear all entries
         #
         # @return [void]
@@ -134,6 +215,26 @@ module SwarmSDK
 
         private
 
+        # Convert glob pattern to regex
+        #
+        # @param pattern [String] Glob pattern
+        # @return [Regexp] Regular expression
+        def glob_to_regex(pattern)
+          # Escape special regex characters except glob wildcards
+          escaped = Regexp.escape(pattern)
+
+          # Convert glob wildcards to regex
+          # ** matches any number of directories (including zero)
+          escaped = escaped.gsub('\*\*', ".*")
+          # * matches anything except directory separator
+          escaped = escaped.gsub('\*', "[^/]*")
+          # ? matches single character except directory separator
+          escaped = escaped.gsub('\?', "[^/]")
+
+          # Anchor to start and end
+          Regexp.new("\\A#{escaped}\\z")
+        end
+
         # Format bytes to human-readable size
         #
         # @param bytes [Integer] Number of bytes
@@ -147,6 +248,68 @@ module SwarmSDK
             "#{bytes}B"
           end
         end
+
+        # Save scratchpad data to JSON file
+        #
+        # @return [void]
+        def save_to_file
+          return unless @persist_to
+
+          # Convert entries to serializable format
+          data = {
+            version: 1,
+            total_size: @total_size,
+            entries: @entries.transform_values do |entry|
+              {
+                content: entry.content,
+                title: entry.title,
+                created_at: entry.created_at.iso8601,
+                size: entry.size,
+              }
+            end,
+          }
+
+          # Ensure directory exists
+          dir = File.dirname(@persist_to)
+          FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+
+          # Write to file atomically (write to temp file, then rename)
+          temp_file = "#{@persist_to}.tmp"
+          File.write(temp_file, JSON.pretty_generate(data))
+          File.rename(temp_file, @persist_to)
+        end
+
+        # Load scratchpad data from JSON file
+        #
+        # @return [void]
+        def load_from_file
+          return unless @persist_to && File.exist?(@persist_to)
+
+          data = JSON.parse(File.read(@persist_to))
+
+          # Restore entries
+          @entries = data["entries"].transform_values do |entry_data|
+            Entry.new(
+              content: entry_data["content"],
+              title: entry_data["title"],
+              created_at: Time.parse(entry_data["created_at"]),
+              size: entry_data["size"],
+            )
+          end
+
+          # Restore total size
+          @total_size = data["total_size"]
+        rescue JSON::ParserError => e
+          # If file is corrupted, log warning and start fresh
+          warn("Warning: Failed to load scratchpad from #{@persist_to}: #{e.message}. Starting with empty scratchpad.")
+          @entries = {}
+          @total_size = 0
+        rescue StandardError => e
+          # If any other error occurs, log warning and start fresh
+          warn("Warning: Failed to load scratchpad from #{@persist_to}: #{e.message}. Starting with empty scratchpad.")
+          @entries = {}
+          @total_size = 0
+        end
       end
     end
   end

data/lib/swarm_sdk/tools/stores/scratchpad_read_tracker.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # ScratchpadReadTracker manages read-entry tracking for all agents
+      #
+      # This module maintains a global registry of which scratchpad entries each agent
+      # has read during their conversation. This enables enforcement of the
+      # "read-before-edit" rule that ensures agents have context before modifying entries.
+      #
+      # Each agent maintains an independent set of read entries, keyed by agent identifier.
+      module ScratchpadReadTracker
+        @read_entries = {}
+        @mutex = Mutex.new
+
+        class << self
+          # Register that an agent has read a scratchpad entry
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @param entry_path [String] The scratchpad entry path
+          def register_read(agent_id, entry_path)
+            @mutex.synchronize do
+              @read_entries[agent_id] ||= Set.new
+              @read_entries[agent_id] << entry_path
+            end
+          end
+
+          # Check if an agent has read a scratchpad entry
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @param entry_path [String] The scratchpad entry path
+          # @return [Boolean] true if the agent has read this entry
+          def entry_read?(agent_id, entry_path)
+            @mutex.synchronize do
+              return false unless @read_entries[agent_id]
+
+              @read_entries[agent_id].include?(entry_path)
+            end
+          end
+
+          # Clear read history for an agent (useful for testing)
+          #
+          # @param agent_id [Symbol] The agent identifier
+          def clear(agent_id)
+            @mutex.synchronize do
+              @read_entries.delete(agent_id)
+            end
+          end
+
+          # Clear all read history (useful for testing)
+          def clear_all
+            @mutex.synchronize do
+              @read_entries.clear
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.0.3"
+  VERSION = "2.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.0.4
 platform: ruby
 authors:
 - Paulo Arruda
@@ -142,11 +142,15 @@ files:
 - lib/swarm_sdk/tools/path_resolver.rb
 - lib/swarm_sdk/tools/read.rb
 - lib/swarm_sdk/tools/registry.rb
-- lib/swarm_sdk/tools/scratchpad_list.rb
+- lib/swarm_sdk/tools/scratchpad_edit.rb
+- lib/swarm_sdk/tools/scratchpad_glob.rb
+- lib/swarm_sdk/tools/scratchpad_grep.rb
+- lib/swarm_sdk/tools/scratchpad_multi_edit.rb
 - lib/swarm_sdk/tools/scratchpad_read.rb
 - lib/swarm_sdk/tools/scratchpad_write.rb
 - lib/swarm_sdk/tools/stores/read_tracker.rb
 - lib/swarm_sdk/tools/stores/scratchpad.rb
+- lib/swarm_sdk/tools/stores/scratchpad_read_tracker.rb
 - lib/swarm_sdk/tools/stores/todo_manager.rb
 - lib/swarm_sdk/tools/think.rb
 - lib/swarm_sdk/tools/todo_write.rb