swarm_memory 2.1.2 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b83e33e8fe0bbfda5910aa6e3cb0da9815166741b6590e22d0321d31d1c4aa39
-  data.tar.gz: 6c72c5174ec20553d1db8c9677b8a48e7bf475b0a689ccdea4c8755eedf8971e
+  metadata.gz: 8422c40d79fb0c2adcd9e1de9a4cfdf289ced49ef27507969ea797c4187a0ee1
+  data.tar.gz: 875f1429c37f2485d32641a7d96c9cae5db226a5bc2fc3e2f8c1443946e021b9
 SHA512:
-  metadata.gz: 53ce80b29bad1e1d3c8e86a629d87f092fb005508127b57e90a90acc9e3fa4130bdd8b7946810aa0801a1cfef014d6a789e5458fab2e9034aa589cc768df2d0e
-  data.tar.gz: f2c7a903a638748eee87f40a05bad00d8bcd0fd267bc2f1ca2cad667f489d9fec6887934373b29505f97b97cc46d9eba6ab20c9de23d6522d86a38a595d9265a
+  metadata.gz: 298c0506a2f486aab1ad29c9f6e4605fe3fbb91fb17f7e3ee913b046f97a9d347312afd686e4bf26d28d6329c8974d421d39ee488e04bf2bc4cde22fea8cdc8c
+  data.tar.gz: c472ec8754b18a2a8d0ab1ae1a0dc391b2f4fffc2de670831272938d81e51a6716c81343b174afa8833d256e28a728fdd198e0bb2b6d92e13adc085c786d2abc

data/lib/claude_swarm/configuration.rb

@@ -69,19 +69,43 @@ module ClaudeSwarm
       validate_directories unless has_before_commands?
     end
 
-    def interpolate_env_vars!(obj)
+    def interpolate_env_vars!(obj, path = [])
       case obj
       when String
-        interpolate_env_string(obj)
+        # Skip interpolation for any values inside MCP configurations
+        # Check if we're inside an mcps array element (path like: [..., "instances", <name>, "mcps", <index>, ...])
+        if in_mcp_config?(path)
+          obj
+        else
+          interpolate_env_string(obj)
+        end
       when Hash
-        obj.transform_values! { |v| interpolate_env_vars!(v) }
+        obj.each do |key, value|
+          obj[key] = interpolate_env_vars!(value, path + [key])
+        end
+        obj
       when Array
-        obj.map! { |v| interpolate_env_vars!(v) }
+        obj.map!.with_index { |v, i| interpolate_env_vars!(v, path + [i]) }
       else
         obj
       end
     end
 
+    def in_mcp_config?(path)
+      # Check if we're inside an MCP configuration
+      # Pattern: [..., "instances", instance_name, "mcps", index, ...]
+      return false if path.size < 4
+
+      # Find the position of "mcps" in the path
+      mcps_index = path.rindex("mcps")
+      return false unless mcps_index
+
+      # Check if this is under instances and followed by an array index
+      return false if mcps_index < 2
+
+      path[mcps_index - 2] == "instances" && path[mcps_index + 1].is_a?(Integer)
+    end
+
     def interpolate_env_string(str)
       str.gsub(ENV_VAR_WITH_DEFAULT_PATTERN) do |_match|
         env_var = Regexp.last_match(1)

data/lib/claude_swarm/mcp_generator.rb

@@ -183,21 +183,17 @@ module ClaudeSwarm
         args.push("--claude-session-id", claude_session_id) if claude_session_id
       end
 
-      # Capture environment variables needed for Ruby and Bundler to work properly
-      # This includes both BUNDLE_* variables and Ruby-specific variables
+      # Capture environment variables needed for running claude-swarm
+      # We intentionally exclude Bundler variables to ensure we use the system-installed gem
       required_env = {}
 
-      # Bundle-specific variables
-      ENV.each do |k, v|
-        required_env[k] = v if k.start_with?("BUNDLE_")
-      end
-
-      # Claude Swarm-specific variables
+      # Claude Swarm-specific variables (always needed)
       ENV.each do |k, v|
         required_env[k] = v if k.start_with?("CLAUDE_SWARM_")
       end
 
       # Ruby-specific variables that MCP servers need
+      # Exclude RUBYOPT and RUBYLIB to avoid Bundler interference
       [
         "RUBY_ROOT",
         "RUBY_ENGINE",
@@ -205,8 +201,6 @@ module ClaudeSwarm
         "GEM_ROOT",
         "GEM_HOME",
         "GEM_PATH",
-        "RUBYOPT",
-        "RUBYLIB",
         "PATH",
       ].each do |key|
         required_env[key] = ENV[key] if ENV[key]

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "1.0.5"
+  VERSION = "1.0.6"
 end

data/lib/swarm_cli/commands/mcp_serve.rb

@@ -29,7 +29,7 @@ module SwarmCLI
 
         # Validate the swarm configuration
         begin
-          SwarmSDK::Swarm.load(config_path)
+          SwarmSDK.load_file(config_path)
         rescue SwarmSDK::ConfigurationError => e
           $stderr.puts "Error: Invalid swarm configuration: #{e.message}"
           exit(1)
@@ -92,7 +92,7 @@ module SwarmCLI
 
           define_method(:call) do |task:, description: nil, thinking_budget: nil|
             # Load swarm for each execution (ensures fresh state)
-            swarm = SwarmSDK::Swarm.load(self.class.config_path)
+            swarm = SwarmSDK.load_file(self.class.config_path)
 
             # Build prompt with thinking budget if provided
             prompt = task

data/lib/swarm_cli/config_loader.rb

@@ -4,7 +4,7 @@ module SwarmCLI
   # ConfigLoader handles loading swarm configurations from both YAML and Ruby DSL files.
   #
   # Supports:
-  # - YAML files (.yml, .yaml) - loaded via SwarmSDK::Swarm.load
+  # - YAML files (.yml, .yaml) - loaded via SwarmSDK.load_file
   # - Ruby DSL files (.rb) - executed and expected to return a SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance
   #
   # @example Load YAML config
@@ -18,7 +18,7 @@ module SwarmCLI
       # Load a swarm configuration from file (YAML or Ruby DSL)
       #
       # Detects file type by extension:
-      # - .yml, .yaml -> Load as YAML using SwarmSDK::Swarm.load
+      # - .yml, .yaml -> Load as YAML using SwarmSDK.load_file
       # - .rb -> Execute as Ruby DSL and expect SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance
       #
       # @param path [String, Pathname] Path to configuration file
@@ -50,7 +50,7 @@ module SwarmCLI
       # @param path [Pathname] Path to YAML file
       # @return [SwarmSDK::Swarm] Configured swarm instance
       def load_yaml(path)
-        SwarmSDK::Swarm.load(path.to_s)
+        SwarmSDK.load_file(path.to_s)
       rescue SwarmSDK::ConfigurationError => e
         # Re-raise with CLI context
         raise ConfigurationError, "Configuration error in #{path}: #{e.message}"

data/lib/swarm_cli/version.rb

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

data/lib/swarm_memory/adapters/base.rb

@@ -7,11 +7,11 @@ module SwarmMemory
     # Subclasses must implement all public methods to provide
     # different storage backends (filesystem, Redis, SQLite, etc.)
     class Base
-      # Maximum size per entry (1MB)
-      MAX_ENTRY_SIZE = 1_000_000
+      # Maximum size per entry (3MB)
+      MAX_ENTRY_SIZE = 3_000_000
 
-      # Maximum total storage size (100MB)
-      MAX_TOTAL_SIZE = 100_000_000
+      # Maximum total storage size (100GB)
+      MAX_TOTAL_SIZE = 100_000_000_000
 
       # Write content to storage
       #

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

@@ -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)