claude_swarm 1.0.5 → 1.0.7

data/lib/swarm_memory/core/storage_read_tracker.rb

@@ -2,40 +2,77 @@
 
 module SwarmMemory
   module Core
-    # StorageReadTracker manages read-entry tracking for all agents
+    # StorageReadTracker manages read-entry tracking for all agents with content digest verification
     #
     # This module maintains a global registry of which memory 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.
+    # has read during their conversation along with SHA256 digests of the content.
+    # This enables enforcement of the "read-before-edit" rule that ensures agents
+    # have context before modifying entries, AND prevents editing entries that have
+    # changed externally since being read.
     #
-    # Each agent maintains an independent set of read entries, keyed by agent identifier.
+    # Each agent maintains an independent map of read entries to content digests.
     module StorageReadTracker
-      @read_entries = {}
+      @read_entries = {} # { agent_id => { entry_path => sha256_digest } }
       @mutex = Mutex.new
 
       class << self
-        # Register that an agent has read a storage entry
+        # Register that an agent has read a storage entry with content digest
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [void]
-        def register_read(agent_id, entry_path)
+        # @param content [String] Entry content (for digest calculation)
+        # @return [String] The calculated SHA256 digest
+        def register_read(agent_id, entry_path, content)
           @mutex.synchronize do
-            @read_entries[agent_id] ||= Set.new
-            @read_entries[agent_id] << entry_path
+            @read_entries[agent_id] ||= {}
+            digest = Digest::SHA256.hexdigest(content)
+            @read_entries[agent_id][entry_path] = digest
+            digest
           end
         end
 
-        # Check if an agent has read a storage entry
+        # Check if an agent has read an entry AND content hasn't changed
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [Boolean] true if the agent has read this entry
-        def entry_read?(agent_id, entry_path)
+        # @param storage [Storage] Storage instance to read current content
+        # @return [Boolean] true if agent read entry and content matches
+        def entry_read?(agent_id, entry_path, storage)
           @mutex.synchronize do
             return false unless @read_entries[agent_id]
 
-            @read_entries[agent_id].include?(entry_path)
+            stored_digest = @read_entries[agent_id][entry_path]
+            return false unless stored_digest
+
+            # Check if entry still matches stored digest
+            begin
+              current_content = storage.read(file_path: entry_path)
+              current_digest = Digest::SHA256.hexdigest(current_content)
+              current_digest == stored_digest
+            rescue StandardError
+              false # Entry deleted or inaccessible
+            end
+          end
+        end
+
+        # Get all read entries with digests for snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @return [Hash] { entry_path => digest }
+        def get_read_entries(agent_id)
+          @mutex.synchronize do
+            @read_entries[agent_id]&.dup || {}
+          end
+        end
+
+        # Restore read entries with digests from snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @param entries_with_digests [Hash] { entry_path => digest }
+        # @return [void]
+        def restore_read_entries(agent_id, entries_with_digests)
+          @mutex.synchronize do
+            @read_entries[agent_id] = entries_with_digests.dup
           end
         end
 

data/lib/swarm_memory/integration/cli_registration.rb

@@ -13,8 +13,9 @@ module SwarmMemory
         #
         # @return [void]
         def register!
-          # Only register if SwarmCLI is present
-          return unless defined?(SwarmCLI)
+          # Only register if SwarmCLI::CommandRegistry is available
+          # Check for the specific class, not just the module
+          return unless defined?(SwarmCLI::CommandRegistry)
 
           # Load CLI commands explicitly (Zeitwerk might not have loaded it yet)
           require_relative "../cli/commands"

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -250,9 +250,12 @@ module SwarmMemory
           :interactive # Default
         end
 
-        # Store storage and mode for this agent
-        @storages[agent_name] = storage
-        @modes[agent_name] = mode
+        # V7.0: Extract base name for storage tracking (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+
+        # Store storage and mode using BASE NAME
+        @storages[base_name] = storage # ← Changed from agent_name to base_name
+        @modes[base_name] = mode # ← Changed from agent_name to base_name
 
         # Get mode-specific tools
         allowed_tools = tools_for_mode(mode)
@@ -298,9 +301,12 @@ module SwarmMemory
       # @param is_first_message [Boolean] True if first message
       # @return [Array<String>] System reminders (0-2 reminders)
       def on_user_message(agent_name:, prompt:, is_first_message:)
-        storage = @storages[agent_name]
+        # V7.0: Extract base name for storage lookup (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+        storage = @storages[base_name] # ← Changed from agent_name to base_name
+
         return [] unless storage&.semantic_index
-        return [] if prompt.empty?
+        return [] if prompt.nil? || prompt.empty?
 
         # Adaptive threshold based on query length
         # Short queries use lower threshold as they have less semantic richness

data/lib/swarm_memory/tools/memory_edit.rb

@@ -124,8 +124,8 @@ module SwarmMemory
         # Read current content (this will raise ArgumentError if entry doesn't exist)
         content = @storage.read(file_path: file_path)
 
-        # Enforce read-before-edit
-        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+        # Enforce read-before-edit with content verification
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path, @storage)
           return validation_error(
             "Cannot edit memory entry without reading it first. " \
               "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \

data/lib/swarm_memory/tools/memory_multi_edit.rb

@@ -140,8 +140,8 @@ module SwarmMemory
         # Read current content (this will raise ArgumentError if entry doesn't exist)
         content = @storage.read(file_path: file_path)
 
-        # Enforce read-before-edit
-        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+        # Enforce read-before-edit with content verification
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path, @storage)
           return validation_error(
             "Cannot edit memory entry without reading it first. " \
               "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \

data/lib/swarm_memory/tools/memory_read.rb

@@ -64,12 +64,12 @@ module SwarmMemory
       # @param file_path [String] Path to read from
       # @return [String] JSON with content and metadata
       def execute(file_path:)
-        # Register this read in the tracker
-        Core::StorageReadTracker.register_read(@agent_name, file_path)
-
         # Read full entry with metadata
         entry = @storage.read_entry(file_path: file_path)
 
+        # Register this read in the tracker with content digest
+        Core::StorageReadTracker.register_read(@agent_name, file_path, entry.content)
+
         # Always return JSON format (metadata always exists - at minimum title)
         format_as_json(entry)
       rescue ArgumentError => e

data/lib/swarm_memory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmMemory
-  VERSION = "2.1.2"
+  VERSION = "2.1.3"
 end

data/lib/swarm_memory.rb

@@ -31,6 +31,11 @@ loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, ".rb")
 loader.push_dir("#{__dir__}/swarm_memory", namespace: SwarmMemory)
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "dsl" => "DSL",
+  "sdk_plugin" => "SDKPlugin",
+)
 loader.setup
 
 # Explicitly load DSL components and extensions to inject into SwarmSDK

data/lib/swarm_sdk/agent/builder.rb

@@ -24,6 +24,13 @@ module SwarmSDK
       # Expose mcp_servers for tests
       attr_reader :mcp_servers
 
+      # Get tools list as array for validation
+      #
+      # @return [Array<Symbol>] List of tools
+      def tools_list
+        @tools.to_a
+      end
+
       def initialize(name)
         @name = name
         @description = nil
@@ -52,6 +59,7 @@ module SwarmSDK
         @permissions_config = {}
         @default_permissions = {} # Set by SwarmBuilder from all_agents
         @memory_config = nil
+        @shared_across_delegations = nil # nil = not set (will default to false in Definition)
       end
 
       # Set/get agent model
@@ -267,6 +275,30 @@ module SwarmSDK
         @permissions_config = PermissionsBuilder.build(&block)
       end
 
+      # Configure delegation isolation mode
+      #
+      # @param enabled [Boolean] If true, allows sharing instances across delegations (old behavior)
+      #                          If false (default), creates isolated instances per delegation
+      # @return [self] Returns self for method chaining
+      #
+      # @example
+      #   shared_across_delegations true  # Allow sharing (old behavior)
+      def shared_across_delegations(enabled)
+        @shared_across_delegations = enabled
+        self
+      end
+
+      # Set permissions directly from hash (for YAML translation)
+      #
+      # This is intentionally separate from permissions() to keep the DSL clean.
+      # Called by Configuration when translating YAML permissions.
+      #
+      # @param hash [Hash] Permissions configuration hash
+      # @return [void]
+      def permissions_hash=(hash)
+        @permissions_config = hash || {}
+      end
+
       # Check if model has been explicitly set (not default)
       #
       # Used by Swarm::Builder to determine if all_agents model should apply.
@@ -374,6 +406,7 @@ module SwarmSDK
         agent_config[:permissions] = @permissions_config if @permissions_config.any?
         agent_config[:default_permissions] = @default_permissions if @default_permissions.any?
         agent_config[:memory] = @memory_config if @memory_config
+        agent_config[:shared_across_delegations] = @shared_across_delegations unless @shared_across_delegations.nil?
 
         # Convert DSL hooks to HookDefinition format
         agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?

data/lib/swarm_sdk/agent/chat/context_tracker.rb

@@ -13,6 +13,25 @@ module SwarmSDK
       # - Check context warnings
       #
       # This is a stateful helper that's instantiated per Agent::Chat instance.
+      #
+      # ## Thread Safety and Fiber-Local Storage
+      #
+      # IMPORTANT: LogStream.emit calls in this class DO NOT explicitly pass
+      # swarm_id, parent_swarm_id, or execution_id. These values are automatically
+      # injected from Fiber-local storage (Fiber[:swarm_id], etc.) by LogStream.emit.
+      #
+      # Why: In threaded environments (Puma, Sidekiq), swarm/agent instances may be
+      # reused across multiple requests/jobs. If we explicitly pass @agent_context.swarm_id,
+      # callbacks would use STALE values from the first request, causing events to be
+      # lost or misattributed.
+      #
+      # By relying on Fiber-local storage, each request/job gets the correct context
+      # even when reusing the same swarm instance. Fiber storage is set at the start
+      # of Swarm#execute and inherited by child fibers (tool calls, delegations).
+      #
+      # This design works correctly in both:
+      # - Single-threaded environments (rails runner, console)
+      # - Multi-threaded environments (Puma, Sidekiq)
       class ContextTracker
         include LoggingHelpers
 
@@ -74,11 +93,20 @@ module SwarmSDK
             # Mark threshold as hit and emit warning
             @agent_context.hit_warning_threshold?(threshold)
 
+            # Emit context_threshold_hit event for snapshot reconstruction
+            LogStream.emit(
+              type: "context_threshold_hit",
+              agent: @agent_context.name,
+              threshold: threshold,
+              current_usage_percentage: current_percentage.round(2),
+            )
+
             # Trigger automatic compression at 60% threshold
             if threshold == Context::COMPRESSION_THRESHOLD
               trigger_automatic_compression
             end
 
+            # Emit legacy context_limit_warning for backwards compatibility
             LogStream.emit(
               type: "context_limit_warning",
               agent: @agent_context.name,
@@ -107,6 +135,9 @@ module SwarmSDK
               cumulative_input_tokens: @chat.cumulative_input_tokens,
               cumulative_output_tokens: @chat.cumulative_output_tokens,
               cumulative_total_tokens: @chat.cumulative_total_tokens,
+              cumulative_cached_tokens: @chat.cumulative_cached_tokens,
+              cumulative_cache_creation_tokens: @chat.cumulative_cache_creation_tokens,
+              effective_input_tokens: @chat.effective_input_tokens,
               context_limit: @chat.context_limit,
               tokens_used_percentage: "#{@chat.context_usage_percentage}%",
               tokens_remaining: @chat.tokens_remaining,
@@ -118,6 +149,8 @@ module SwarmSDK
           {
             input_tokens: message.input_tokens,
             output_tokens: message.output_tokens,
+            cached_tokens: message.cached_tokens,
+            cache_creation_tokens: message.cache_creation_tokens,
             total_tokens: (message.input_tokens || 0) + (message.output_tokens || 0),
             input_cost: cost_info[:input_cost],
             output_cost: cost_info[:output_cost],

data/lib/swarm_sdk/agent/chat/hook_integration.rb

@@ -77,12 +77,15 @@ module SwarmSDK
         # system reminders are handled.
         #
         # @param prompt [String] User prompt
-        # @param options [Hash] Additional options
+        # @param options [Hash] Additional options (may include source: "user" or "delegation")
         # @return [RubyLLM::Message] LLM response
         def ask(prompt, **options)
+          # Extract source for hook tracking (not passed to RubyLLM)
+          source = options.delete(:source) || "user"
+
           # Trigger user_prompt hook before sending to LLM (can halt or modify prompt)
           if @hook_executor
-            hook_result = trigger_user_prompt(prompt)
+            hook_result = trigger_user_prompt(prompt, source: source)
 
             # Check if hook halted execution
             if hook_result[:halted]
@@ -186,9 +189,13 @@ module SwarmSDK
         def trigger_post_tool_use(result, tool_call:)
           return result unless @hook_executor
 
+          # Extract tracking digest for Read/MemoryRead tools
+          metadata_with_digest = extract_tool_tracking_digest(tool_call, result)
+
           context = build_hook_context(
             event: :post_tool_use,
             tool_result: wrap_tool_result(tool_call.id, tool_call.name, result),
+            metadata: metadata_with_digest,
           )
 
           agent_hooks = @hook_agent_hooks[:post_tool_use] || []
@@ -251,8 +258,9 @@ module SwarmSDK
         # Can halt execution or append hook stdout to prompt.
         #
         # @param prompt [String] User's message/prompt
+        # @param source [String] Source of the prompt ("user" or "delegation")
         # @return [Hash] { halted: bool, halt_message: String, modified_prompt: String }
-        def trigger_user_prompt(prompt)
+        def trigger_user_prompt(prompt, source: "user")
           return { halted: false, modified_prompt: prompt } unless @hook_executor
 
           # Filter out delegation tools from tools list
@@ -278,6 +286,7 @@ module SwarmSDK
               provider: model.provider,
               tools: actual_tools,
               delegates_to: delegate_agents,
+              source: source,
               timestamp: Time.now.utc.iso8601,
             },
           )
@@ -335,6 +344,43 @@ module SwarmSDK
           )
         end
 
+        # Extract tracking digest for Read/MemoryRead tools
+        #
+        # Queries the appropriate tracker after tool execution to get the digest
+        # that was calculated and stored during the read operation.
+        #
+        # @param tool_call [RubyLLM::ToolCall] Tool call with arguments
+        # @param result [Object] Tool execution result (to check for errors)
+        # @return [Hash] Metadata hash with digest if applicable
+        def extract_tool_tracking_digest(tool_call, result)
+          # Only add digest for successful Read/MemoryRead tool calls
+          return {} if result.is_a?(StandardError)
+          return {} unless ["Read", "MemoryRead"].include?(tool_call.name)
+
+          # Extract path from arguments
+          path = case tool_call.name
+          when "Read"
+            tool_call.arguments[:file_path] || tool_call.arguments["file_path"]
+          when "MemoryRead"
+            tool_call.arguments[:file_path] || tool_call.arguments["file_path"]
+          end
+
+          return {} unless path
+
+          # Query tracker for digest
+          digest = case tool_call.name
+          when "Read"
+            Tools::Stores::ReadTracker.get_read_files(@agent_context.name)[File.expand_path(path)]
+          when "MemoryRead"
+            # Only query if SwarmMemory is loaded (optional dependency)
+            if defined?(SwarmMemory::Core::StorageReadTracker)
+              SwarmMemory::Core::StorageReadTracker.get_read_entries(@agent_context.name)[path]
+            end
+          end
+
+          digest ? { read_digest: digest, read_path: path } : {}
+        end
+
         # Wrap a tool result in our Hooks::ToolResult value object
         #
         # @param tool_call_id [String] Tool call ID

data/lib/swarm_sdk/agent/chat/system_reminder_injector.rb

@@ -12,23 +12,6 @@ module SwarmSDK
       #
       # This class is stateless - it operates on the chat's message history.
       class SystemReminderInjector
-        # System reminder to inject BEFORE the first user message
-        BEFORE_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
-          <system-reminder>
-          As you answer the user's questions, you can use the following context:
-
-          # important-instruction-reminders
-
-          Do what has been asked; nothing more, nothing less.
-          NEVER create files unless they're absolutely necessary for achieving your goal.
-          ALWAYS prefer editing an existing file to creating a new one.
-          NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-
-          IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
-
-          </system-reminder>
-        REMINDER
-
         # System reminder to inject AFTER the first user message
         AFTER_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
           <system-reminder>Your todo list is currently empty. DO NOT mention this to the user. If this task requires multiple steps: (1) FIRST analyze the scope by searching/reading files, (2) SECOND create a COMPLETE todo list with ALL tasks before starting work, (3) THIRD execute tasks one by one. Only skip the todo list for simple single-step tasks. Do not mention this message to the user.</system-reminder>
@@ -51,16 +34,14 @@ module SwarmSDK
             chat.messages.none? { |msg| msg.role == :user }
           end
 
-          # Inject first message reminders (before + after user message)
+          # Inject first message reminders
           #
-          # This manually constructs the first message sequence with system reminders
-          # sandwiching the actual user prompt.
+          # This manually constructs the first message sequence with system reminders.
           #
           # Sequence:
-          # 1. BEFORE_FIRST_MESSAGE_REMINDER (general reminders)
+          # 1. User's actual prompt
           # 2. Toolset reminder (list of available tools)
-          # 3. User's actual prompt
-          # 4. AFTER_FIRST_MESSAGE_REMINDER (todo list reminder)
+          # 3. AFTER_FIRST_MESSAGE_REMINDER (todo list reminder - only if TodoWrite available)
           #
           # @param chat [Agent::Chat] The chat instance
           # @param prompt [String] The user's actual prompt
@@ -68,12 +49,15 @@ module SwarmSDK
           def inject_first_message_reminders(chat, prompt)
             # Build user message with embedded reminders
             # Reminders are embedded in the content, not separate messages
-            full_content = [
+            parts = [
               prompt,
-              BEFORE_FIRST_MESSAGE_REMINDER,
               build_toolset_reminder(chat),
-              AFTER_FIRST_MESSAGE_REMINDER,
-            ].join("\n\n")
+            ]
+
+            # Only include todo list reminder if agent has TodoWrite tool
+            parts << AFTER_FIRST_MESSAGE_REMINDER if chat.tools.key?("TodoWrite")
+
+            full_content = parts.join("\n\n")
 
             # Extract reminders and add clean prompt to persistent history
             reminders = chat.context_manager.extract_system_reminders(full_content)