swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/hooks/tool_call.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Represents a tool call in the hooks system
+    #
+    # This is a simple value object that wraps tool call information
+    # from RubyLLM in a consistent, immutable format for hooks.
+    #
+    # @example Access tool call information in a hook
+    #   swarm.add_callback(:pre_tool_use) do |context|
+    #     puts "Tool: #{context.tool_call.name}"
+    #     puts "Parameters: #{context.tool_call.parameters.inspect}"
+    #   end
+    class ToolCall
+      attr_reader :id, :name, :parameters
+
+      # @param id [String] Unique identifier for this tool call
+      # @param name [String] Name of the tool being called
+      # @param parameters [Hash] Parameters passed to the tool
+      def initialize(id:, name:, parameters:)
+        @id = id
+        @name = name
+        @parameters = parameters
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] Hash with id, name, and parameters
+      def to_h
+        { id: @id, name: @name, parameters: @parameters }
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/tool_result.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Represents the result of a tool execution
+    #
+    # This is a simple value object that wraps tool execution results
+    # in a consistent format for post-tool-use hooks.
+    #
+    # @example Access tool result in a hook
+    #   swarm.add_callback(:post_tool_use) do |context|
+    #     if context.tool_result.success?
+    #       puts "Tool succeeded: #{context.tool_result.content}"
+    #     else
+    #       puts "Tool failed: #{context.tool_result.error}"
+    #     end
+    #   end
+    class ToolResult
+      attr_reader :tool_call_id, :tool_name, :content, :success, :error
+
+      # @param tool_call_id [String] ID of the tool call this result corresponds to
+      # @param tool_name [String] Name of the tool that was executed
+      # @param content [String, nil] Result content (if successful)
+      # @param success [Boolean] Whether the tool execution succeeded
+      # @param error [String, nil] Error message (if failed)
+      def initialize(tool_call_id:, tool_name:, content: nil, success: true, error: nil)
+        @tool_call_id = tool_call_id
+        @tool_name = tool_name
+        @content = content
+        @success = success
+        @error = error
+      end
+
+      # Check if the tool execution succeeded
+      #
+      # @return [Boolean] true if successful
+      def success?
+        @success
+      end
+
+      # Check if the tool execution failed
+      #
+      # @return [Boolean] true if failed
+      def failure?
+        !@success
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] Hash with all result attributes
+      def to_h
+        {
+          tool_call_id: @tool_call_id,
+          tool_name: @tool_name,
+          content: @content,
+          success: @success,
+          error: @error,
+        }
+      end
+    end
+  end
+end

data/lib/swarm_sdk/log_collector.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # LogCollector manages subscriber callbacks for log events.
+  #
+  # This module acts as an emitter implementation that forwards events
+  # to user-registered callbacks. It's designed to be set as the LogStream
+  # emitter during swarm execution.
+  #
+  # ## Usage
+  #
+  #   # Register a callback (before execution starts)
+  #   LogCollector.on_log do |event|
+  #     puts JSON.generate(event)
+  #   end
+  #
+  #   # Freeze callbacks (after all registrations, before Async execution)
+  #   LogCollector.freeze!
+  #
+  #   # During execution, LogStream calls emit
+  #   LogCollector.emit(type: "user_prompt", agent: :backend)
+  #
+  # ## Fiber Safety
+  #
+  # LogCollector is fiber-safe because:
+  # - All callbacks registered before Async execution starts
+  # - freeze! makes @callbacks immutable
+  # - emit() only reads the frozen array (no mutations)
+  #
+  module LogCollector
+    class << self
+      # Register a callback to receive log events
+      #
+      # Must be called before freeze! is called.
+      #
+      # @yield [Hash] Log event entry
+      # @raise [StateError] If called after freeze!
+      def on_log(&block)
+        raise StateError, "Cannot register callbacks after LogCollector is frozen" if @frozen
+
+        @callbacks ||= []
+        @callbacks << block
+      end
+
+      # Emit an event to all registered callbacks
+      #
+      # @param entry [Hash] Log event entry
+      # @return [void]
+      def emit(entry)
+        # Use defensive copy for fiber safety
+        Array(@callbacks).each do |callback|
+          callback.call(entry)
+        end
+      end
+
+      # Freeze the callbacks array (call before Async execution)
+      #
+      # This prevents new callbacks from being registered and makes
+      # the array immutable for fiber safety.
+      #
+      # @return [void]
+      def freeze!
+        @callbacks&.freeze
+        @frozen = true
+      end
+
+      # Reset the collector (for test cleanup)
+      #
+      # @return [void]
+      def reset!
+        @callbacks = []
+        @frozen = false
+      end
+
+      # Check if collector is frozen
+      #
+      # @return [Boolean]
+      def frozen?
+        @frozen
+      end
+    end
+  end
+end

data/lib/swarm_sdk/log_stream.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # LogStream provides a module-level singleton for emitting log events.
+  #
+  # This allows any component (tools, providers, agents) to emit structured
+  # log events without needing references to logger instances.
+  #
+  # ## Usage
+  #
+  #   # Emit an event from anywhere in the SDK
+  #   LogStream.emit(
+  #     type: "user_prompt",
+  #     agent: :backend,
+  #     model: "claude-sonnet-4",
+  #     message_count: 5
+  #   )
+  #
+  # ## Fiber Safety
+  #
+  # LogStream is fiber-safe when following this pattern:
+  # 1. Set emitter BEFORE starting Async execution
+  # 2. During Async execution, only emit() (reads emitter)
+  # 3. Each event includes agent context for identification
+  #
+  # ## Testing
+  #
+  #   # Inject a test emitter
+  #   LogStream.emitter = TestEmitter.new
+  #   # ... run tests ...
+  #   LogStream.reset!
+  #
+  module LogStream
+    class << self
+      # Emit a log event
+      #
+      # Adds timestamp and forwards to the registered emitter.
+      #
+      # @param data [Hash] Event data (type, agent, and event-specific fields)
+      # @return [void]
+      def emit(**data)
+        return unless @emitter
+
+        entry = data.merge(timestamp: Time.now.utc.iso8601).compact
+
+        @emitter.emit(entry)
+      end
+
+      # Set the emitter (for dependency injection in tests)
+      #
+      # @param emitter [#emit] Object responding to emit(Hash)
+      attr_accessor :emitter
+
+      # Reset the emitter (for test cleanup)
+      #
+      # @return [void]
+      def reset!
+        @emitter = nil
+      end
+
+      # Check if logging is enabled
+      #
+      # @return [Boolean] true if an emitter is configured
+      def enabled?
+        !@emitter.nil?
+      end
+    end
+  end
+end

data/lib/swarm_sdk/markdown_parser.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class MarkdownParser
+    FRONTMATTER_PATTERN = /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+
+    class << self
+      def parse(content, agent_name = nil)
+        new(content, agent_name).parse
+      end
+    end
+
+    def initialize(content, agent_name = nil)
+      @content = content
+      @agent_name = agent_name
+    end
+
+    def parse
+      if @content =~ FRONTMATTER_PATTERN
+        frontmatter_yaml = Regexp.last_match(1)
+        prompt_content = Regexp.last_match(2).strip
+
+        frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Symbol], aliases: true)
+
+        unless frontmatter.is_a?(Hash)
+          raise ConfigurationError, "Invalid frontmatter format in agent definition"
+        end
+
+        # Symbolize keys for AgentDefinition
+        config = Utils.symbolize_keys(frontmatter).merge(system_prompt: prompt_content)
+
+        name = @agent_name || frontmatter["name"]
+        unless name
+          raise ConfigurationError, "Agent definition must include 'name' in frontmatter or be specified externally"
+        end
+
+        # Convert name to symbol
+        name = name.to_sym
+
+        Agent::Definition.new(name, config)
+      else
+        raise ConfigurationError, "Invalid Markdown agent definition format. Expected YAML frontmatter followed by prompt content."
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions/config.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # Config parses and validates permission configuration for tools
+    #
+    # Handles:
+    # - Allowed path patterns (allowlist)
+    # - Denied path patterns (explicit denylist)
+    # - Allowed command patterns (regex for Bash tool)
+    # - Denied command patterns (regex for Bash tool)
+    # - Relative paths converted to absolute based on agent directory
+    # - Glob pattern matching with absolute paths
+    #
+    # All paths and patterns are converted to absolute:
+    # - Patterns starting with / are kept as-is
+    # - Relative patterns are expanded against the agent's base directory
+    # - Paths starting with / are kept as-is
+    # - Relative paths are expanded against the agent's base directory
+    #
+    # Example:
+    #   config = Config.new(
+    #     {
+    #       allowed_paths: ["tmp/**/*"],
+    #       denied_paths: ["tmp/secrets/**"],
+    #       allowed_commands: ["^git (status|diff|log)$"],
+    #       denied_commands: ["^rm -rf"]
+    #     },
+    #     base_directories: ["/home/user/project"]
+    #   )
+    #   config.allowed?("tmp/file.txt")  # => true (checks /home/user/project/tmp/file.txt)
+    #   config.allowed?("tmp/secrets/key.pem")  # => false (denied takes precedence)
+    #   config.command_allowed?("git status")  # => true
+    #   config.command_allowed?("rm -rf /")  # => false (denied takes precedence)
+    class Config
+      attr_reader :allowed_patterns, :denied_patterns, :allowed_commands, :denied_commands
+
+      # Initialize permission configuration
+      #
+      # @param config_hash [Hash] Permission configuration with :allowed_paths, :denied_paths, :allowed_commands, :denied_commands
+      # @param base_directory [String] Base directory for the agent
+      def initialize(config_hash, base_directory:)
+        # Use agent's directory as the base for path resolution
+        @base_directory = File.expand_path(base_directory)
+
+        # Expand all patterns to absolute paths
+        @allowed_patterns = expand_patterns(config_hash[:allowed_paths] || [])
+        @denied_patterns = expand_patterns(config_hash[:denied_paths] || [])
+
+        # Parse command patterns (regex strings)
+        @allowed_commands = compile_regex_patterns(config_hash[:allowed_commands] || [])
+        @denied_commands = compile_regex_patterns(config_hash[:denied_commands] || [])
+      end
+
+      # Check if a path is allowed according to this configuration
+      #
+      # Rules:
+      # 1. Denied patterns take precedence and always block
+      # 2. If allowed_paths specified: must match at least one pattern (allowlist)
+      # 3. If allowed_paths NOT specified: allow everything (except denied)
+      # 4. All paths are converted to absolute for consistent matching
+      # 5. For directories used as search bases (Glob/Grep), allow if any pattern would match inside
+      #
+      # @param path [String] Path to check (relative or absolute)
+      # @param directory_search [Boolean] True if this is a directory search base (Glob/Grep)
+      # @return [Boolean] True if path is allowed
+      def allowed?(path, directory_search: false)
+        # Convert path to absolute
+        absolute_path = to_absolute_path(path)
+
+        # Denied patterns take precedence - check first
+        return false if matches_any?(@denied_patterns, absolute_path)
+
+        # If no allowed patterns, allow everything (except denied)
+        return true if @allowed_patterns.empty?
+
+        # For directory searches, check if directory is a prefix of any allowed pattern
+        # Don't check if directory exists - allow non-existent directories as search bases
+        if directory_search
+          return true if allowed_as_search_base?(absolute_path)
+        end
+
+        # Must match at least one allowed pattern
+        matches_any?(@allowed_patterns, absolute_path)
+      end
+
+      # Find the specific pattern that denies or doesn't allow a path
+      #
+      # @param path [String] Path to check (relative or absolute)
+      # @param directory_search [Boolean] True if this is a directory search base (Glob/Grep)
+      # @return [String, nil] The pattern that blocks this path, or nil if allowed
+      def find_blocking_pattern(path, directory_search: false)
+        absolute_path = to_absolute_path(path)
+
+        # Check denied patterns first
+        denied_match = @denied_patterns.find { |pattern| PathMatcher.matches?(pattern, absolute_path) }
+        return denied_match if denied_match
+
+        # Check allowed patterns
+        if @allowed_patterns.any?
+          # For directory searches, check if allowed as search base
+          # Don't check if directory exists - allow non-existent directories as search bases
+          if directory_search
+            return if allowed_as_search_base?(absolute_path)
+          end
+
+          # Check if path matches any allowed pattern
+          return if @allowed_patterns.any? { |pattern| PathMatcher.matches?(pattern, absolute_path) }
+
+          # Path doesn't match any allowed pattern
+          return "(not in allowed list)"
+        end
+
+        nil
+      end
+
+      # Convert a path to absolute form
+      #
+      # @param path [String] Path to convert
+      # @return [String] Absolute path
+      def to_absolute(path)
+        to_absolute_path(path)
+      end
+
+      # Check if a command is allowed according to this configuration
+      #
+      # Rules:
+      # 1. Denied command patterns take precedence and always block
+      # 2. If allowed_commands specified: must match at least one pattern (allowlist)
+      # 3. If allowed_commands NOT specified: allow everything (except denied)
+      #
+      # @param command [String] Command to check
+      # @return [Boolean] True if command is allowed
+      def command_allowed?(command)
+        # Denied patterns take precedence - check first
+        return false if matches_any_regex?(@denied_commands, command)
+
+        # If no allowed patterns, allow everything (except denied)
+        return true if @allowed_commands.empty?
+
+        # Must match at least one allowed pattern
+        matches_any_regex?(@allowed_commands, command)
+      end
+
+      # Find the specific pattern that denies or doesn't allow a command
+      #
+      # @param command [String] Command to check
+      # @return [String, nil] The pattern that blocks this command, or nil if allowed
+      def find_blocking_command_pattern(command)
+        # Check denied patterns first
+        denied_match = @denied_commands.find { |pattern| pattern.match?(command) }
+        return denied_match.source if denied_match
+
+        # Check allowed patterns
+        if @allowed_commands.any?
+          # Check if command matches any allowed pattern
+          return if @allowed_commands.any? { |pattern| pattern.match?(command) }
+
+          # Command doesn't match any allowed pattern
+          return "(not in allowed list)"
+        end
+
+        nil
+      end
+
+      private
+
+      # Expand patterns to absolute paths
+      #
+      # Patterns starting with / are kept as-is
+      # Relative patterns are joined with base directory
+      def expand_patterns(patterns)
+        Array(patterns).map do |pattern|
+          if pattern.to_s.start_with?("/")
+            pattern.to_s
+          else
+            File.join(@base_directory, pattern.to_s)
+          end
+        end
+      end
+
+      # Convert path to absolute
+      #
+      # Paths starting with / are kept as-is
+      # Relative paths are expanded against base directory
+      def to_absolute_path(path)
+        if path.start_with?("/")
+          path
+        else
+          File.expand_path(path, @base_directory)
+        end
+      end
+
+      # Check if path matches any pattern in the list
+      def matches_any?(patterns, path)
+        patterns.any? { |pattern| PathMatcher.matches?(pattern, path) }
+      end
+
+      # Check if a directory is allowed as a search base
+      #
+      # A directory is allowed as a search base if any allowed pattern
+      # would match files or directories inside it.
+      #
+      # @param directory_path [String] Absolute path to directory
+      # @return [Boolean] True if directory can be used as search base
+      def allowed_as_search_base?(directory_path)
+        # Normalize directory path (ensure trailing slash for comparison)
+        dir_with_slash = directory_path.end_with?("/") ? directory_path : "#{directory_path}/"
+
+        @allowed_patterns.any? do |pattern|
+          # Check if the pattern starts with this directory
+          # This means files inside this directory would match the pattern
+          pattern.start_with?(dir_with_slash) || pattern == directory_path
+        end
+      end
+
+      # Compile regex patterns from strings
+      #
+      # @param patterns [Array<String>] Array of regex pattern strings
+      # @return [Array<Regexp>] Array of compiled regex objects
+      def compile_regex_patterns(patterns)
+        Array(patterns).map do |pattern|
+          Regexp.new(pattern)
+        rescue RegexpError => e
+          raise ConfigurationError, "Invalid regex pattern '#{pattern}': #{e.message}"
+        end
+      end
+
+      # Check if command matches any regex pattern in the list
+      #
+      # @param patterns [Array<Regexp>] Array of compiled regex patterns
+      # @param command [String] Command to check
+      # @return [Boolean] True if command matches any pattern
+      def matches_any_regex?(patterns, command)
+        patterns.any? { |pattern| pattern.match?(command) }
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions/error_formatter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # ErrorFormatter generates user-friendly error messages for permission violations
+    class ErrorFormatter
+      class << self
+        # Generate a permission denied error message
+        #
+        # @param path [String] The path that was denied
+        # @param allowed_patterns [Array<String>] List of allowed path patterns
+        # @param denied_patterns [Array<String>] List of denied path patterns
+        # @param matching_pattern [String, nil] The specific pattern that blocked this path
+        # @param tool_name [String] Name of the tool that was denied
+        # @return [String] Formatted error message with system reminder
+        def permission_denied(path:, allowed_patterns:, denied_patterns: [], matching_pattern: nil, tool_name:)
+          operation_verb = case tool_name.to_s
+          when "Read" then "read"
+          when "Write" then "write to"
+          when "Edit", "MultiEdit" then "edit"
+          when "Glob" then "access directory"
+          when "Grep" then "search in"
+          else "access"
+          end
+
+          # Build policy explanation
+          policy_info = if matching_pattern && matching_pattern != "(not in allowed list)"
+            # Show the specific denied pattern that blocked this path
+            "Blocked by policy: #{matching_pattern}"
+          elsif matching_pattern == "(not in allowed list)" && allowed_patterns.any?
+            # Show allowed patterns when path doesn't match any
+            patterns = allowed_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Path not in allowed list. Allowed paths:\n#{patterns}"
+          elsif denied_patterns.any?
+            # Show denied patterns
+            patterns = denied_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Denied paths:\n#{patterns}"
+          elsif allowed_patterns.any?
+            # Show allowed patterns
+            patterns = allowed_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Allowed paths (not matched):\n#{patterns}"
+          else
+            "No access policy configured"
+          end
+
+          reminder = <<~REMINDER
+
+            <system-reminder>
+            PERMISSION DENIED: You do not have permission to #{operation_verb} '#{path}'.
+
+            #{policy_info}
+
+            This is an UNRECOVERABLE error set by user policy. You MUST stop trying to access files matching this pattern.
+
+            Policy explanation:
+            - This policy blocks ALL files matching the pattern, not just this specific file
+            - Do not attempt to access other files matching this pattern - they will also be denied
+            - Do not try to work around this restriction by using different tool arguments
+            - The user has explicitly denied access to these resources via security policy
+
+            You should inform the user that you cannot proceed due to permission restrictions on this file pattern.
+            </system-reminder>
+          REMINDER
+
+          "Permission denied: Cannot #{operation_verb} '#{path}'#{reminder}"
+        end
+
+        # Generate a command permission denied error message
+        #
+        # @param command [String] The command that was denied
+        # @param allowed_patterns [Array<Regexp>] List of allowed command regex patterns
+        # @param denied_patterns [Array<Regexp>] List of denied command regex patterns
+        # @param matching_pattern [String, nil] The specific pattern that blocked this command
+        # @param tool_name [String] Name of the tool (typically "bash")
+        # @return [String] Formatted error message with system reminder
+        def command_permission_denied(command:, allowed_patterns:, denied_patterns: [], matching_pattern: nil, tool_name:)
+          # Build policy explanation
+          policy_info = if matching_pattern && matching_pattern != "(not in allowed list)"
+            # Show the specific denied pattern that blocked this command
+            "Blocked by policy: #{matching_pattern}"
+          elsif matching_pattern == "(not in allowed list)" && allowed_patterns.any?
+            # Show allowed patterns when command doesn't match any
+            patterns = allowed_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Command not in allowed list. Allowed command patterns:\n#{patterns}"
+          elsif denied_patterns.any?
+            # Show denied patterns
+            patterns = denied_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Denied command patterns:\n#{patterns}"
+          elsif allowed_patterns.any?
+            # Show allowed patterns
+            patterns = allowed_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Allowed command patterns (not matched):\n#{patterns}"
+          else
+            "No command policy configured"
+          end
+
+          reminder = <<~REMINDER
+
+            <system-reminder>
+            PERMISSION DENIED: You do not have permission to execute command '#{command}'.
+
+            #{policy_info}
+
+            This is an UNRECOVERABLE error set by user policy. You MUST stop trying to execute commands matching this pattern.
+
+            Policy explanation:
+            - This policy blocks ALL commands matching the pattern, not just this specific command
+            - Do not attempt to execute other commands matching this pattern - they will also be denied
+            - Do not try to work around this restriction by modifying the command slightly
+            - The user has explicitly denied access to these commands via security policy
+
+            You should inform the user that you cannot proceed due to permission restrictions on this command.
+            </system-reminder>
+          REMINDER
+
+          "Permission denied: Cannot execute command '#{command}'#{reminder}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions/path_matcher.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # PathMatcher handles glob pattern matching for file paths
+    #
+    # Supports gitignore-style glob patterns with:
+    # - Standard globs: *, **, ?, [abc], {a,b}
+    # - Recursive matching: **/* matches all nested files
+    # - Negation: !pattern to explicitly deny
+    #
+    # Examples:
+    #   PathMatcher.matches?("tmp/**/*", "tmp/foo/bar.rb")  # => true
+    #   PathMatcher.matches?("*.log", "debug.log")          # => true
+    #   PathMatcher.matches?("src/**/*.{rb,js}", "src/a/b.rb")  # => true
+    class PathMatcher
+      class << self
+        # Check if a path matches a glob pattern
+        #
+        # @param pattern [String] Glob pattern to match against
+        # @param path [String] File path to check
+        # @return [Boolean] True if path matches pattern
+        def matches?(pattern, path)
+          # Remove leading ! for negation patterns (handled by caller)
+          pattern = pattern.delete_prefix("!")
+
+          # Use File.fnmatch with pathname and extglob flags
+          # FNM_PATHNAME: ** matches directories recursively
+          # FNM_EXTGLOB: Support {a,b} patterns
+          File.fnmatch(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+        end
+      end
+    end
+  end
+end