swarm_memory 2.1.1 → 2.1.3

data/lib/swarm_memory/core/storage.rb

@@ -95,22 +95,82 @@ module SwarmMemory
         )
       end
 
-      # Read content from storage
+      # Read content from storage, automatically following stub redirects
       #
       # @param file_path [String] Path to read from
       # @return [String] Content at the path
       def read(file_path:)
-        normalized_path = PathNormalizer.normalize(file_path)
-        @adapter.read(file_path: normalized_path)
+        entry = read_entry(file_path: file_path)
+        entry.content
       end
 
-      # Read full entry with metadata
+      # Read full entry with metadata, automatically following stub redirects
+      #
+      # Stub redirects are created by MemoryDefrag when merging/moving entries.
+      # This method transparently follows redirect chains up to 5 levels deep.
       #
       # @param file_path [String] Path to read from
+      # @param visited [Array<String>] Internal: tracks visited paths to detect circular redirects
       # @return [Entry] Full entry object
-      def read_entry(file_path:)
+      # @raise [ArgumentError] If path not found, circular redirect detected, or too many redirects
+      def read_entry(file_path:, visited: [])
         normalized_path = PathNormalizer.normalize(file_path)
-        @adapter.read_entry(file_path: normalized_path)
+
+        # Detect circular redirects immediately
+        if visited.include?(normalized_path)
+          cycle = visited + [normalized_path]
+          raise ArgumentError,
+            "Circular redirect detected in memory storage: #{cycle.join(" → ")}\n\n" \
+              "This indicates corrupted stub files. Please run MemoryDefrag to repair:\n  " \
+              "MemoryDefrag(action: \"analyze\")"
+        end
+
+        # Check depth limit (prevent infinite chains)
+        if visited.size >= 5
+          chain = visited + [normalized_path]
+          raise ArgumentError,
+            "Memory redirect chain too deep (>5 redirects): #{chain.join(" → ")}\n\n" \
+              "This indicates fragmented memory storage. Please run maintenance:\n  " \
+              "MemoryDefrag(action: \"full\", dry_run: true)  # Preview first\n  " \
+              "MemoryDefrag(action: \"full\", dry_run: false) # Execute"
+        end
+
+        # Read entry from adapter
+        begin
+          entry = @adapter.read_entry(file_path: normalized_path)
+        rescue ArgumentError
+          # If this is a redirect target that doesn't exist, provide helpful error
+          if visited.empty?
+            # Not a redirect, just re-raise original error
+            raise
+          else
+            original_path = visited.first
+            raise ArgumentError,
+              "memory://#{original_path} was redirected to memory://#{normalized_path}, but the target was not found.\n\n" \
+                "The original entry may have been merged or moved incorrectly. " \
+                "Run MemoryDefrag to identify and fix broken redirects:\n  " \
+                "MemoryDefrag(action: \"analyze\")"
+          end
+        end
+
+        # Check if this is a stub redirect
+        if entry.metadata && entry.metadata["stub"] == true
+          redirect_target = entry.metadata["redirect_to"]
+
+          # Validate redirect target exists
+          if redirect_target.nil? || redirect_target.strip.empty?
+            raise ArgumentError,
+              "memory://#{normalized_path} is a stub with invalid redirect metadata.\n\n" \
+                "This should never happen (stubs are created by MemoryDefrag). " \
+                "The stub file may be corrupted. Please report this as a bug."
+          end
+
+          # Follow redirect recursively, tracking visited paths
+          return read_entry(file_path: redirect_target, visited: visited + [normalized_path])
+        end
+
+        # Not a stub, return the entry
+        entry
       end
 
       # Delete an entry

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

@@ -207,6 +207,19 @@ module SwarmMemory
         agent_definition.memory_enabled?
       end
 
+      # Contribute to agent serialization
+      #
+      # Preserves memory configuration when agents are cloned (e.g., in NodeOrchestrator).
+      # This allows memory configuration to persist across node transitions.
+      #
+      # @param agent_definition [Agent::Definition] Agent definition
+      # @return [Hash] Memory config to include in to_h
+      def serialize_config(agent_definition:)
+        return {} unless agent_definition.memory
+
+        { memory: agent_definition.memory }
+      end
+
       # Lifecycle: Agent initialized
       #
       # Filters tools by mode (removing non-mode tools), registers LoadSkill,
@@ -237,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)
@@ -285,8 +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.nil? || prompt.empty?
 
         # Adaptive threshold based on query length
         # Short queries use lower threshold as they have less semantic richness

data/lib/swarm_memory/optimization/defragmenter.rb

@@ -747,7 +747,11 @@ module SwarmMemory
       # @param to [String] Target path
       # @param reason [String] Reason (merged, moved)
       # @return [void]
+      # @raise [ArgumentError] If target path or reason is nil/empty
       def create_stub(from:, to:, reason:)
+        raise ArgumentError, "Cannot create stub without target path" if to.nil? || to.strip.empty?
+        raise ArgumentError, "Cannot create stub without reason" if reason.nil? || reason.strip.empty?
+
         stub_content = "# #{reason} → #{to}\n\nThis entry was #{reason} into #{to}."
 
         @adapter.write(

data/lib/swarm_memory/tools/memory_edit.rb

@@ -85,6 +85,7 @@ module SwarmMemory
 
       param :replace_all,
         desc: "Replace all occurrences of old_string (default false)",
+        type: :boolean,
         required: false
 
       # Initialize with storage instance and agent name
@@ -123,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_glob.rb

@@ -100,6 +100,8 @@ module SwarmMemory
         desc: "Glob pattern - target concept/, fact/, skill/, or experience/ only (e.g., 'skill/**', 'concept/ruby/*', 'fact/people/*.md')",
         required: true
 
+      MAX_RESULTS = 500 # Limit results to prevent overwhelming output
+
       # Initialize with storage instance
       #
       # @param storage [Core::Storage] Storage instance
@@ -124,6 +126,14 @@ module SwarmMemory
           return "No entries found matching pattern '#{pattern}'"
         end
 
+        # Limit results
+        if entries.count > MAX_RESULTS
+          entries = entries.take(MAX_RESULTS)
+          truncated = true
+        else
+          truncated = false
+        end
+
         result = []
         result << "Memory entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
 
@@ -131,7 +141,20 @@ module SwarmMemory
           result << "  memory://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
         end
 
-        result.join("\n")
+        output = result.join("\n")
+
+        # Add system reminder if truncated
+        if truncated
+          output += <<~REMINDER
+
+            <system-reminder>
+            Results limited to first #{MAX_RESULTS} matches (sorted by most recently modified).
+            Consider using a more specific pattern to narrow your search.
+            </system-reminder>
+          REMINDER
+        end
+
+        output
       rescue ArgumentError => e
         validation_error(e.message)
       end

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/tools/memory_write.rb

@@ -45,8 +45,8 @@ module SwarmMemory
         TAGS ARE CRITICAL: Think "What would I search for in 6 months?" For skills especially, be VERY comprehensive with tags - they're your search index.
 
         EXAMPLES:
-        - For concept: tags: ['ruby', 'oop', 'classes', 'inheritance', 'methods']
-        - For skill: tags: ['debugging', 'api', 'http', 'errors', 'trace', 'network', 'rest']
+        - For concept: tags: (JSON) "['ruby', 'oop', 'classes', 'inheritance', 'methods']"
+        - For skill: tags: (JSON) "['debugging', 'api', 'http', 'errors', 'trace', 'network', 'rest']"
       DESC
 
       param :file_path,

data/lib/swarm_memory/version.rb

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

data/lib/swarm_memory.rb

@@ -28,7 +28,14 @@ require_relative "swarm_memory/version"
 # Setup Zeitwerk loader
 require "zeitwerk"
 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

@@ -186,9 +186,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] || []
@@ -335,6 +339,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)