claude_swarm 1.0.6 → 1.0.7

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)

data/lib/swarm_sdk/agent/chat.rb

@@ -150,6 +150,7 @@ module SwarmSDK
         raise StateError, "Agent context not set. Call setup_context first." unless @agent_context
 
         @context_tracker.setup_logging
+        inject_llm_instrumentation
       end
 
       # Emit model lookup warning if one occurred during initialization
@@ -164,6 +165,8 @@ module SwarmSDK
         LogStream.emit(
           type: "model_lookup_warning",
           agent: agent_name,
+          swarm_id: @agent_context&.swarm_id,
+          parent_swarm_id: @agent_context&.parent_swarm_id,
           model: @model_lookup_error[:model],
           error_message: @model_lookup_error[:error_message],
           suggestions: @model_lookup_error[:suggestions].map { |s| { id: s.id, name: s.name, context_window: s.context_window } },
@@ -221,6 +224,17 @@ module SwarmSDK
         !@active_skill_path.nil?
       end
 
+      # Clear conversation history
+      #
+      # Removes all messages from the conversation history and clears tool executions.
+      # Used by composable swarms when keep_context: false is specified.
+      #
+      # @return [void]
+      def clear_conversation
+        @messages.clear if @messages.respond_to?(:clear)
+        @context_manager&.clear_ephemeral
+      end
+
       # Override ask to inject system reminders and periodic TodoWrite reminders
       #
       # Note: This is called BEFORE HookIntegration#ask (due to module include order),
@@ -230,63 +244,74 @@ module SwarmSDK
       # @param options [Hash] Additional options to pass to complete
       # @return [RubyLLM::Message] LLM response
       def ask(prompt, **options)
-        # Check if this is the first user message
-        is_first = SystemReminderInjector.first_message?(self)
-
-        if is_first
-          # Collect plugin reminders first
-          plugin_reminders = collect_plugin_reminders(prompt, is_first_message: true)
-
-          # Build full prompt with embedded plugin reminders
-          full_prompt = prompt
-          plugin_reminders.each do |reminder|
-            full_prompt = "#{full_prompt}\n\n#{reminder}"
-          end
-
-          # Inject first message reminders (includes system reminders + toolset + after)
-          # SystemReminderInjector will embed all reminders in the prompt via add_message
-          SystemReminderInjector.inject_first_message_reminders(self, full_prompt)
+        # Serialize ask() calls to prevent message corruption from concurrent fibers
+        # Uses Async::Semaphore (not Mutex) because SwarmSDK runs in fiber context
+        # This protects against parallel delegation scenarios where multiple delegation
+        # instances call the same underlying primary agent (e.g., tester@frontend and
+        # tester@backend both calling database in parallel).
+        @ask_semaphore ||= Async::Semaphore.new(1)
+
+        @ask_semaphore.acquire do
+          # Check if this is the first user message
+          is_first = SystemReminderInjector.first_message?(self)
+
+          if is_first
+            # Collect plugin reminders first
+            plugin_reminders = collect_plugin_reminders(prompt, is_first_message: true)
+
+            # Build full prompt with embedded plugin reminders
+            full_prompt = prompt
+            plugin_reminders.each do |reminder|
+              full_prompt = "#{full_prompt}\n\n#{reminder}"
+            end
 
-          # Trigger user_prompt hook manually since we're bypassing the normal ask flow
-          if @hook_executor
-            hook_result = trigger_user_prompt(prompt)
+            # Inject first message reminders (includes system reminders + toolset + after)
+            # SystemReminderInjector will embed all reminders in the prompt via add_message
+            SystemReminderInjector.inject_first_message_reminders(self, full_prompt)
+
+            # Trigger user_prompt hook manually since we're bypassing the normal ask flow
+            if @hook_executor
+              # Extract source from options if provided, default to "user"
+              source = options[:source] || "user"
+              hook_result = trigger_user_prompt(prompt, source: source)
+
+              # Check if hook halted execution
+              if hook_result[:halted]
+                # Return a halted message instead of calling LLM
+                return RubyLLM::Message.new(
+                  role: :assistant,
+                  content: hook_result[:halt_message],
+                  model_id: model.id,
+                )
+              end
 
-            # Check if hook halted execution
-            if hook_result[:halted]
-              # Return a halted message instead of calling LLM
-              return RubyLLM::Message.new(
-                role: :assistant,
-                content: hook_result[:halt_message],
-                model_id: model.id,
-              )
+              # NOTE: We ignore modified_prompt for first message since reminders already injected
             end
 
-            # NOTE: We ignore modified_prompt for first message since reminders already injected
-          end
+            # Call complete to get LLM response
+            complete(**options)
+          else
+            # Build prompt with embedded reminders (if needed)
+            full_prompt = prompt
+
+            # Add periodic TodoWrite reminder if needed (only if agent has TodoWrite tool)
+            if tools.key?("TodoWrite") && SystemReminderInjector.should_inject_todowrite_reminder?(self, @last_todowrite_message_index)
+              full_prompt = "#{full_prompt}\n\n#{SystemReminderInjector::TODOWRITE_PERIODIC_REMINDER}"
+              # Update tracking
+              @last_todowrite_message_index = SystemReminderInjector.find_last_todowrite_index(self)
+            end
 
-          # Call complete to get LLM response
-          complete(**options)
-        else
-          # Build prompt with embedded reminders (if needed)
-          full_prompt = prompt
-
-          # Add periodic TodoWrite reminder if needed
-          if SystemReminderInjector.should_inject_todowrite_reminder?(self, @last_todowrite_message_index)
-            full_prompt = "#{full_prompt}\n\n#{SystemReminderInjector::TODOWRITE_PERIODIC_REMINDER}"
-            # Update tracking
-            @last_todowrite_message_index = SystemReminderInjector.find_last_todowrite_index(self)
-          end
+            # Collect plugin reminders and embed them
+            plugin_reminders = collect_plugin_reminders(full_prompt, is_first_message: false)
+            plugin_reminders.each do |reminder|
+              full_prompt = "#{full_prompt}\n\n#{reminder}"
+            end
 
-          # Collect plugin reminders and embed them
-          plugin_reminders = collect_plugin_reminders(full_prompt, is_first_message: false)
-          plugin_reminders.each do |reminder|
-            full_prompt = "#{full_prompt}\n\n#{reminder}"
+            # Normal ask behavior for subsequent messages
+            # This calls super which goes to HookIntegration's ask override
+            # HookIntegration will call add_message, and we'll extract reminders there
+            super(full_prompt, **options)
           end
-
-          # Normal ask behavior for subsequent messages
-          # This calls super which goes to HookIntegration's ask override
-          # HookIntegration will call add_message, and we'll extract reminders there
-          super(full_prompt, **options)
         end
       end
 
@@ -674,7 +699,15 @@ module SwarmSDK
       # This is needed for setting agent_name and other provider-specific settings.
       #
       # @return [RubyLLM::Provider::Base] Provider instance
-      attr_reader :provider, :global_semaphore, :local_semaphore, :real_model_info, :context_tracker, :context_manager
+      attr_reader :provider, :global_semaphore, :local_semaphore, :real_model_info, :context_tracker, :context_manager, :agent_context, :last_todowrite_message_index, :active_skill_path
+
+      # Setters for snapshot/restore
+      attr_writer :last_todowrite_message_index, :active_skill_path
+
+      # Expose messages array (inherited from RubyLLM::Chat but not publicly accessible)
+      #
+      # @return [Array<RubyLLM::Message>] Conversation messages
+      attr_reader :messages
 
       # Get context window limit for the current model
       #
@@ -718,6 +751,37 @@ module SwarmSDK
         messages.select { |msg| msg.role == :assistant }.sum { |msg| msg.output_tokens || 0 }
       end
 
+      # Calculate cumulative cached tokens across all assistant messages
+      #
+      # Cached tokens are portions of prompts served from the provider's cache.
+      # OpenAI reports this automatically for prompts >1024 tokens.
+      # Anthropic/Bedrock expose cache control via Content::Raw blocks.
+      #
+      # @return [Integer] Total cached tokens used in conversation
+      def cumulative_cached_tokens
+        messages.select { |msg| msg.role == :assistant }.sum { |msg| msg.cached_tokens || 0 }
+      end
+
+      # Calculate cumulative cache creation tokens
+      #
+      # Cache creation tokens are written to the cache (Anthropic/Bedrock only).
+      # These are charged at the normal input rate when first created.
+      #
+      # @return [Integer] Total tokens written to cache
+      def cumulative_cache_creation_tokens
+        messages.select { |msg| msg.role == :assistant }.sum { |msg| msg.cache_creation_tokens || 0 }
+      end
+
+      # Calculate effective input tokens (excluding cache hits)
+      #
+      # This represents the actual tokens charged for input, excluding cached portions.
+      # Useful for accurate cost tracking when using prompt caching.
+      #
+      # @return [Integer] Actual input tokens charged (input minus cached)
+      def effective_input_tokens
+        cumulative_input_tokens - cumulative_cached_tokens
+      end
+
       # Calculate total tokens used (input + output)
       #
       # @return [Integer] Total tokens used in conversation
@@ -777,6 +841,85 @@ module SwarmSDK
 
       private
 
+      # Inject LLM instrumentation middleware for API request/response logging
+      #
+      # This middleware captures HTTP requests/responses to LLM providers and
+      # emits structured events via LogStream. Only injected when logging is enabled.
+      #
+      # @return [void]
+      def inject_llm_instrumentation
+        # Safety checks
+        return unless @provider
+
+        faraday_conn = @provider.connection&.connection
+        return unless faraday_conn
+
+        # Check if middleware is already present to prevent duplicates
+        return if @llm_instrumentation_injected
+
+        # Get provider name for logging
+        provider_name = @provider.class.name.split("::").last.downcase
+
+        # Inject middleware at beginning of stack (position 0)
+        # This ensures we capture raw requests before any transformations
+        # Use fully qualified name to ensure Zeitwerk loads it
+        faraday_conn.builder.insert(
+          0,
+          SwarmSDK::Agent::LLMInstrumentationMiddleware,
+          on_request: method(:handle_llm_api_request),
+          on_response: method(:handle_llm_api_response),
+          provider_name: provider_name,
+        )
+
+        # Mark as injected to prevent duplicates
+        @llm_instrumentation_injected = true
+
+        RubyLLM.logger.debug("SwarmSDK: Injected LLM instrumentation middleware for agent #{@agent_name}")
+      rescue StandardError => e
+        # Don't fail initialization if instrumentation fails
+        RubyLLM.logger.error("SwarmSDK: Failed to inject LLM instrumentation: #{e.message}")
+      end
+
+      # Handle LLM API request event
+      #
+      # Emits llm_api_request event via LogStream with request details.
+      #
+      # @param data [Hash] Request data from middleware
+      # @return [void]
+      def handle_llm_api_request(data)
+        return unless LogStream.emitter
+
+        LogStream.emit(
+          type: "llm_api_request",
+          agent: @agent_name,
+          swarm_id: @agent_context&.swarm_id,
+          parent_swarm_id: @agent_context&.parent_swarm_id,
+          **data,
+        )
+      rescue StandardError => e
+        RubyLLM.logger.error("SwarmSDK: Error emitting llm_api_request event: #{e.message}")
+      end
+
+      # Handle LLM API response event
+      #
+      # Emits llm_api_response event via LogStream with response details.
+      #
+      # @param data [Hash] Response data from middleware
+      # @return [void]
+      def handle_llm_api_response(data)
+        return unless LogStream.emitter
+
+        LogStream.emit(
+          type: "llm_api_response",
+          agent: @agent_name,
+          swarm_id: @agent_context&.swarm_id,
+          parent_swarm_id: @agent_context&.parent_swarm_id,
+          **data,
+        )
+      rescue StandardError => e
+        RubyLLM.logger.error("SwarmSDK: Error emitting llm_api_response event: #{e.message}")
+      end
+
       # Call LLM with retry logic for transient failures
       #
       # Retries up to 10 times with fixed 10-second delays for:
@@ -802,10 +945,13 @@ module SwarmSDK
               LogStream.emit(
                 type: "llm_retry_exhausted",
                 agent: @agent_name,
+                swarm_id: @agent_context&.swarm_id,
+                parent_swarm_id: @agent_context&.parent_swarm_id,
                 model: @model&.id,
                 attempts: attempts,
                 error_class: e.class.name,
                 error_message: e.message,
+                error_backtrace: e.backtrace,
               )
               raise
             end
@@ -814,11 +960,14 @@ module SwarmSDK
             LogStream.emit(
               type: "llm_retry_attempt",
               agent: @agent_name,
+              swarm_id: @agent_context&.swarm_id,
+              parent_swarm_id: @agent_context&.parent_swarm_id,
               model: @model&.id,
               attempt: attempts,
               max_retries: max_retries,
               error_class: e.class.name,
               error_message: e.message,
+              error_backtrace: e.backtrace,
               retry_delay: delay,
             )