claude_swarm 1.0.10 → 1.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7137a9b3f3fd37de3a81a9b3f4b1b6fe5b3173248284f4c6ce0af628f2f140cd
-  data.tar.gz: 447a2c03a49e23e2ba1750d05922b84e95df7bebfd5dbeacc3331cefa6882b8e
+  metadata.gz: f29b35b5b6dadfd9638907704a3bc204ebd35ba3c7e95c4bfafb0ff7ed1f44ed
+  data.tar.gz: e6e005f4dc472961daaa02f094c8d044a76018628a0e7d07ea6ed55ab0d830b6
 SHA512:
-  metadata.gz: d8bd44b19b45e5482d141520c84589a08b646bfa2691b48d233e2c844745d1084081e16e23971a71f71bda796c85c3e6a599be33bbf839b2bc2d8d626b8a3cf1
-  data.tar.gz: 2600e70853d9d590075c3c172e3bea65a75795d0a667ab4dffa8361c6bc3a4d829643ac64eac42f2fb260639759326ab5af00d36cda2538634f4d0656ca94628
+  metadata.gz: 0bd8988be66a9514cc80732a5d66b52fc737f44f67b1949271230fbb083e3a8fcc95a515b1bc5fd2688b51449cc04e5e162c70f66de14531075f4f6606bd2002
+  data.tar.gz: 5aa8a44f9dc5bd935b380ab59654e2e382726a977ea404ebe8c20401df29536425f50619857ae87a6b3ee4674377b83fa3a211b73fc232bc2ff1ce7af61df128

data/{CHANGELOG.md → CHANGELOG.claude-swarm.md}

@@ -1,3 +1,6 @@
+## [1.0.11]
+- Fix: load prompt_file for main instance in orchestrator: https://github.com/parruda/swarm/pull/183
+
 ## [1.0.10]
 
 ### Changed

data/CLAUDE.md

@@ -146,7 +146,6 @@ swarm = SwarmSDK.load_file("swarm.yml")
 - **MemoryWrite** - Create/update memory entries with semantic indexing
 - **MemoryRead** - Retrieve memory entries with optional semantic search
 - **MemoryEdit** - Edit specific memory entries
-- **MemoryMultiEdit** - Batch edit multiple entries
 - **MemoryDelete** - Remove memory entries
 - **MemoryGrep** - Search memory content with regex
 - **MemoryGlob** - Find memory entries by pattern

data/decisions/2025-11-22-001-global-agent-registry.md

@@ -0,0 +1,172 @@
+# Decision: Global Agent Registry for SwarmSDK
+
+**Date:** 2025-11-22
+**Status:** Implemented
+
+## Context
+
+Users wanted the ability to declare agents in separate files and reference them by name in swarm definitions. This promotes:
+- Code reuse across multiple swarms
+- Separation of concerns (agent definitions vs swarm composition)
+- Cleaner organization for large projects
+
+## Decision
+
+Implement a global `AgentRegistry` that stores agent configuration blocks and allows referencing them in `SwarmSDK.build` and `SwarmSDK.workflow` definitions.
+
+### API Design
+
+```ruby
+# Register agent in separate file (e.g., agents/backend.rb)
+SwarmSDK.agent :backend do
+  model "claude-sonnet-4"
+  description "Backend developer"
+  system_prompt "You build APIs"
+  tools :Read, :Edit, :Bash
+end
+
+# Reference in swarm definition
+SwarmSDK.build do
+  name "Dev Team"
+  lead :backend
+
+  agent :backend  # Lookup from registry
+end
+
+# Extend with overrides
+SwarmSDK.build do
+  name "Extended Team"
+  lead :backend
+
+  agent :backend do
+    tools :CustomTool  # Adds to registry tools
+  end
+end
+```
+
+### Key Design Decisions
+
+1. **Proc Storage (not Lambda)**
+   - Procs work naturally with `instance_eval` DSL semantics
+   - Flexible arity handling suits DSL blocks
+   - Blocks passed to methods are already Procs
+
+2. **Class with Class Methods (not Singleton)**
+   - Simpler than full Singleton pattern
+   - Easier to test with `AgentRegistry.clear`
+   - Class methods feel natural for global registry
+
+3. **Duplicate Registration Error**
+   - Raises `ArgumentError` if registering same name twice
+   - Prevents accidental overwrites across files
+   - User must call `SwarmSDK.clear_agent_registry!` to reset
+
+4. **Registry Takes Precedence**
+   - When `agent :name do ... end` is called and agent is registered:
+     - Registry config is applied first
+     - Block becomes overrides (additive)
+   - Promotes DRY principle - registry is source of truth
+
+5. **No Thread Safety**
+   - SwarmSDK uses fiber-based concurrency (Async gem)
+   - Single-threaded execution means no race conditions
+   - Documented limitation for multi-threaded environments
+
+6. **Delegation is Swarm-Specific (Best Practice)**
+   - Don't set `delegates_to` in registry agent definitions
+   - Delegation targets depend on which agents exist in each swarm
+   - Set `delegates_to` as an override when referencing the agent in a swarm
+   - This makes agents truly reusable across different swarm compositions
+
+## Implementation
+
+### New Files
+- `lib/swarm_sdk/agent_registry.rb` - AgentRegistry class
+
+### Modified Files
+- `lib/swarm_sdk.rb` - Added `SwarmSDK.agent` and `SwarmSDK.clear_agent_registry!`
+- `lib/swarm_sdk/builders/base_builder.rb` - Added registry lookup to `#agent` method
+
+### Test Coverage
+- 26 tests covering:
+  - Registry class methods (register, get, registered?, names, clear)
+  - Module methods (agent, clear_agent_registry!)
+  - Registry lookup in Swarm and Workflow builders
+  - Registry + overrides behavior
+  - Multiple swarms sharing registry
+  - Error handling
+  - Edge cases
+
+## Alternatives Considered
+
+1. **Explicit Syntax (`agent :name, from: :registry`)**
+   - Rejected: Too verbose for common use case
+   - Current behavior is intuitive (no args = lookup)
+
+2. **Warning on Shadow**
+   - Rejected: Too noisy, users might ignore
+   - Error-free operation preferred
+
+3. **Thread-Safe Implementation**
+   - Rejected: Unnecessary complexity for fiber-based model
+   - The definitions should be eager loaded in the app that is using the SDK
+   - Documented limitation acceptable
+
+## Enhancement: Workflow Node Registry Fallback
+
+Added automatic agent resolution in workflow nodes. When `agent(:name)` is called inside a node:
+
+1. First checks if agent is defined at workflow level
+2. If not found, checks the global AgentRegistry
+3. If still not found, raises ConfigurationError
+
+This allows powerful patterns like:
+
+```ruby
+# agents/shared.rb
+SwarmSDK.agent :shared_analyzer do
+  model "claude-sonnet-4"
+  description "Shared analyzer"
+end
+
+# workflow.rb
+SwarmSDK.workflow do
+  name "Pipeline"
+  start_node :analyze
+
+  # No need to define shared_analyzer here!
+
+  node :analyze do
+    agent(:shared_analyzer)  # Auto-resolved from registry
+  end
+end
+```
+
+The fallback also resolves delegation targets:
+
+```ruby
+node :process do
+  agent(:main_agent).delegates_to(:helper_agent)
+  # Both resolved from registry
+end
+```
+
+### Implementation
+- Modified `Workflow::Builder#build_workflow` to call `resolve_missing_agents_from_registry`
+- Added `collect_referenced_agents` to gather all agents from nodes (including delegates_to)
+- Resolution happens at build time before agent definitions are built
+
+## Consequences
+
+### Positive
+- Clean separation of agent definitions from swarm composition
+- Easy code reuse across swarms
+- Intuitive API that matches existing DSL patterns
+- Works with both Swarm and Workflow builders
+- Workflow nodes automatically resolve agents from registry
+- Delegation targets also auto-resolve from registry
+
+### Negative
+- Global state (mitigated by clear method for testing)
+- Not thread-safe (documented limitation)
+- Must require agent files before building swarms

data/docs/v2/CHANGELOG.swarm_cli.md

@@ -5,6 +5,18 @@ All notable changes to SwarmCLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.7]
+
+### Dependencies
+
+- Updated `swarm_sdk` to `~> 2.5.1`
+
+## [2.1.6]
+- Bump SDK and memory gem versions
+
+## [2.1.5]
+- Bump SDK gem version
+
 ## [2.1.4]
 
 ### Changed

data/docs/v2/CHANGELOG.swarm_memory.md

@@ -5,6 +5,145 @@ All notable changes to SwarmMemory will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.3]
+
+### Fixed
+
+- **Hybrid search weight configuration**: Fixed bug where `semantic_weight` and `keyword_weight` from config weren't being passed to SemanticIndex
+  - **Issue**: SDK plugin extracted weights from config but didn't pass them to Storage/SemanticIndex
+  - **Fix**: Storage now accepts and passes weight parameters through to SemanticIndex
+  - **Impact**: Per-agent weight configuration now works correctly (was only used for logging before)
+  - **Files**: `lib/swarm_memory/core/storage.rb:23-35`, `lib/swarm_memory/integration/sdk_plugin.rb:130-150`
+
+- **YAML config with string keys**: Fixed bug where Hash configs with string keys would fail adapter initialization
+  - **Issue**: Adapters expect symbol keyword arguments, but YAML configs have string keys
+  - **Fix**: Symbolize adapter option keys in create_storage for Hash configs
+  - **Impact**: YAML configurations now work correctly with all adapters
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:113-118`
+
+### Added
+
+- **DSL methods for weights**: Added `semantic_weight()` and `keyword_weight()` methods to MemoryConfig
+  - **Before**: `option(:semantic_weight, 0.8)`
+  - **After**: `semantic_weight(0.8)` (cleaner syntax, consistent with `directory()` and `mode()`)
+  - **Backward compatible**: `option()` method still works
+  - **Files**: `lib/swarm_memory/dsl/memory_config.rb:87-122`
+
+### Changed
+
+- **Automatic semantic fallback**: Hybrid search now falls back to pure semantic scoring when keyword_score is 0
+  - **Before**: semantic=0.92, keyword=0.0 → final=0.46 (penalized by 50/50 weights)
+  - **After**: semantic=0.92, keyword=0.0 → final=0.92 (no penalty when no tag matches)
+  - **Rationale**: Prevents excellent semantic matches from being penalized when there's no keyword/tag overlap
+  - **Impact**: Improved recall for queries with no tag matches
+  - **Files**: `lib/swarm_memory/core/semantic_index.rb:195-201`
+
+## [2.2.2]
+
+### Dependencies
+
+- Updated `swarm_sdk` to `~> 2.5.1`
+
+## [2.2.1]
+
+### Fixed
+
+- **MemoryEdit metadata preservation**: MemoryEdit now preserves all metadata when updating entry content
+  - **Issue**: MemoryEdit was only preserving title, losing tags, confidence, domain, and other metadata
+  - **Fix**: Pass `metadata: entry.metadata` to storage.write to preserve all existing metadata
+  - **Impact**: Prevents metadata loss when editing memory entries
+  - **Files**: `lib/swarm_memory/tools/memory_edit.rb:169`
+
+## [2.2.0]
+
+### Added
+
+- **Per-Adapter Threshold Configuration**: Semantic search thresholds can now be configured per-adapter in YAML
+  - **Fallback chain**: `adapter_config → ENV var → hardcoded_default` (config wins over ENV)
+  - **Supported threshold keys**:
+    - `discovery_threshold` (default: 0.35) - Main similarity threshold for normal queries
+    - `discovery_threshold_short` (default: 0.25) - Threshold for queries with <10 words
+    - `adaptive_word_cutoff` (default: 10) - Word count to switch between thresholds
+    - `semantic_weight` (default: 0.5) - Hybrid search semantic weight
+    - `keyword_weight` (default: 0.5) - Hybrid search keyword weight
+  - **Use cases**: Per-agent threshold tuning, adapter-specific optimization (pgvector vs FAISS), multi-tenant customization
+  - **Backward compatible**: ENV vars still work as deployment-level override
+  - **Zero config required**: Sensible defaults work out of the box
+  - **Example**:
+    ```yaml
+    memory:
+      adapter: multi_bank_postgres
+      agent_id: researcher
+      discovery_threshold: 0.5
+      discovery_threshold_short: 0.3
+      semantic_weight: 0.6
+    ```
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb`
+  - **Tests**: 4 new tests validating threshold extraction and fallback behavior
+
+- **Custom Adapter Support**: SwarmMemory now fully supports custom storage adapters
+  - **Custom adapter options pass-through**: All YAML config keys (except `directory`, `adapter`, `mode`) are now passed to adapter constructor
+  - **Example configuration**:
+    ```yaml
+    memory:
+      adapter: multi_bank_postgres
+      agent_id: business_consultant
+      default_bank: working
+      banks:
+        working: { max_size: 10485760 }
+        long_term: { max_size: 52428800 }
+      bank_access:
+        archive: read_only
+    ```
+  - **Enables**: PostgreSQL, MySQL, Redis, S3, and any custom storage backend
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:290-310`
+  - **Tests**: 2 new tests for custom adapter option pass-through
+
+### Changed
+
+- **BREAKING: `storage_enabled?` renamed to `memory_configured?`** in SDKPlugin
+  - **Improved logic**: Filesystem adapter requires `directory`, custom adapters can use any configuration keys
+  - **Better validation**: Custom adapters are recognized as valid even without `directory` key
+  - **Adapter validation**: Each adapter validates its own requirements during initialization
+  - **No backward compatibility**: `storage_enabled?` method removed entirely (breaking change)
+  - **Migration**: Update any code calling `plugin.storage_enabled?()` to use `plugin.memory_configured?()`
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:202-235`
+  - **Tests**: 3 new tests for custom adapter recognition
+
+### Removed
+
+- **MemoryMultiEdit tool**: Removed in favor of simpler MemoryEdit tool
+  - **Rationale**: Memory entries are small (typically < 100 lines), making batch edits unnecessary
+  - **Alternative**: Use multiple `MemoryEdit` calls for sequential edits
+  - **Simplification**: Reduces API complexity and LLM error surface (JSON parameter was error-prone)
+  - **Files removed**: `lib/swarm_memory/tools/memory_multi_edit.rb`
+  - **Tool count**: Memory tools reduced from 8 to 7 (MemoryWrite, MemoryRead, MemoryEdit, MemoryDelete, MemoryGlob, MemoryGrep, MemoryDefrag)
+
+### Benefits
+
+- ✅ **Eliminates need for monkey patches** when building custom adapters
+- ✅ **Makes SwarmMemory fully extensible** for any storage backend
+- ✅ **Per-agent threshold tuning** for optimal semantic search accuracy
+- ✅ **Multi-tenant customization** with per-adapter configuration
+- ✅ **Clearer semantics** (memory vs storage terminology)
+- ✅ **Better error messages** (adapters validate themselves)
+
+## [2.1.7]
+
+### Dependencies
+
+- Updated `ruby_llm_swarm` to `~> 1.9.5`
+
+## [2.1.6]
+- Fix files included in the gem
+
+## [2.1.5]
+
+### Fixed
+- **Fixed Zeitwerk naming convention**: Renamed `lib/swarm_memory/errors.rb` to `lib/swarm_memory/error.rb` to match the `SwarmMemory::Error` constant it defines
+  - Fixes `Zeitwerk::Loader.eager_load_all` failures with "uninitialized constant SwarmMemory::Errors" errors
+  - Properly follows Zeitwerk file naming conventions where `error.rb` defines `Error` class
+
 ## [2.1.4]
 
 ### Changed

data/docs/v2/CHANGELOG.swarm_sdk.md

@@ -5,6 +5,254 @@ All notable changes to SwarmSDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.1]
+
+### Dependencies
+
+- Updated `ruby_llm_swarm-mcp` to `~> 0.8.1`
+
+## [2.5.0]
+
+### Added
+
+- **Custom Tool Registration**: Simple API for registering custom tools without creating full plugins
+  - **`SwarmSDK.register_tool(ToolClass)`**: Register with inferred name (e.g., `WeatherTool` → `:Weather`)
+  - **`SwarmSDK.register_tool(:Name, ToolClass)`**: Register with explicit name
+  - **`SwarmSDK.custom_tool_registered?(:Name)`**: Check if tool is registered
+  - **`SwarmSDK.custom_tools`**: List all registered custom tool names
+  - **`SwarmSDK.unregister_tool(:Name)`**: Remove a registered tool
+  - **`SwarmSDK.clear_custom_tools!`**: Clear all registered tools (useful for testing)
+  - **Tool lookup order**: Plugin tools → Custom tools → Built-in tools
+  - **Context support**: Tools can declare `creation_requirements` for agent context (`:agent_name`, `:directory`)
+  - **Name consistency**: `NamedToolWrapper` ensures registered name is used for tool lookup
+  - **Validation**: Prevents overriding built-in tools or plugin tools
+  - **Use case**: Simple, stateless tools that don't need plugin lifecycle hooks or storage
+  - **Example**:
+    ```ruby
+    class WeatherTool < RubyLLM::Tool
+      description "Get weather for a city"
+      param :city, type: "string", required: true
+
+      def execute(city:)
+        "Weather in #{city}: Sunny"
+      end
+    end
+
+    SwarmSDK.register_tool(WeatherTool)
+
+    SwarmSDK.build do
+      name "Assistant"
+      lead :helper
+
+      agent :helper do
+        model "claude-sonnet-4"
+        description "Weather assistant"
+        system_prompt "You help with weather"
+        tools :Weather  # Use the registered tool
+      end
+    end
+    ```
+  - **Files**: `lib/swarm_sdk/custom_tool_registry.rb`, `lib/swarm_sdk.rb`, `lib/swarm_sdk/swarm/tool_configurator.rb`
+  - **Tests**: 32 comprehensive tests (unit + integration)
+
+### Changed
+
+- **BREAKING: Plugin API method renamed**: `storage_enabled?` → `memory_configured?` in Plugin base class
+  - **Rationale**: "memory" is the user-facing concept, "storage" is internal implementation detail
+  - **Better semantics**: "Is memory configured?" vs "Is storage enabled?"
+  - **No backward compatibility**: `storage_enabled?` method removed entirely (breaking change)
+  - **Impact**: Custom plugins implementing `storage_enabled?` must rename to `memory_configured?`
+  - **Migration**: Update plugin classes to implement `memory_configured?` instead of `storage_enabled?`
+  - **Files**: `lib/swarm_sdk/plugin.rb:142-148`
+  - **Updated callers**:
+    - `lib/swarm_sdk/swarm/agent_initializer.rb:572`
+    - `lib/swarm_sdk/agent/system_prompt_builder.rb:151`
+    - `lib/swarm_sdk/swarm/tool_configurator.rb:270`
+  - **Tests**: All plugin-related tests updated
+
+## [2.4.6]
+- Use a fork of ruby_llm-mcp that requires ruby_llm_swarm instead of ruby_llm
+
+## [2.4.5]
+
+### Fixed
+
+- **Context Window Tracking Bug**: Fixed model lookup using wrong source for context window data
+  - **Issue**: Changes to `models.json` had no effect on context window tracking - SDK always returned 0%
+  - **Root cause**: `fetch_real_model_info` was using `RubyLLM.models.find()` instead of `SwarmSDK::Models.find()`
+  - **Fix**: Changed model lookup to use `SwarmSDK::Models.find()` first, falling back to `RubyLLM.models.find()`
+  - **Impact**: Context window percentage now correctly calculated from SwarmSDK's models.json
+  - **Files**: `lib/swarm_sdk/agent/chat_helpers/llm_configuration.rb`
+
+### Added
+
+- **Per-Agent Context Breakdown**: Real-time and historical context usage metrics per agent
+  - **`Swarm#context_breakdown`**: Returns live context metrics for all agents including:
+    - Token counts: `input_tokens`, `output_tokens`, `total_tokens`, `cached_tokens`, `cache_creation_tokens`, `effective_input_tokens`
+    - Context limits: `context_limit`, `usage_percentage`, `tokens_remaining`
+    - Cost metrics: `input_cost`, `output_cost`, `total_cost`
+  - **`Result#per_agent_usage`**: Extracts per-agent usage from execution logs (for historical analysis)
+  - **`swarm_stop` event enhancement**: Now includes `per_agent_usage` field with complete breakdown
+  - **Use cases**: Monitor token consumption, track costs per agent, identify context-heavy agents
+  - **Example**:
+    ```ruby
+    breakdown = swarm.context_breakdown
+    breakdown[:backend]
+    # => {
+    #   input_tokens: 15000,
+    #   output_tokens: 5000,
+    #   total_tokens: 20000,
+    #   cached_tokens: 2000,
+    #   context_limit: 200000,
+    #   usage_percentage: 10.0,
+    #   tokens_remaining: 180000,
+    #   input_cost: 0.045,
+    #   output_cost: 0.075,
+    #   total_cost: 0.12
+    # }
+    ```
+  - **Files**: `lib/swarm_sdk/swarm.rb`, `lib/swarm_sdk/result.rb`, `lib/swarm_sdk/swarm/hook_triggers.rb`, `lib/swarm_sdk/swarm/logging_callbacks.rb`
+
+- **Cumulative Cost Tracking in TokenTracking**: New methods for calculating conversation costs
+  - **`cumulative_input_cost`**: Calculate total input cost based on tokens and model pricing
+  - **`cumulative_output_cost`**: Calculate total output cost based on tokens and model pricing
+  - **`cumulative_total_cost`**: Sum of input and output costs
+  - **Pricing source**: Uses `@real_model_info.pricing` from SwarmSDK's models.json
+  - **Files**: `lib/swarm_sdk/agent/chat_helpers/token_tracking.rb`
+
+- **ModelInfo Class**: Wrapper class for model data with method access
+  - **`SwarmSDK::Models::ModelInfo`**: Replaces raw Hash returns from `Models.find()`
+  - **Attributes**: `id`, `name`, `provider`, `family`, `context_window`, `max_output_tokens`, `knowledge_cutoff`, `modalities`, `capabilities`, `pricing`, `metadata`
+  - **Files**: `lib/swarm_sdk/models.rb`
+
+### Tests
+
+- **28 new tests** covering:
+  - `TokenTracking` cost methods (24 tests): context_limit, cumulative costs, pricing edge cases
+  - `Swarm#context_breakdown` (5 tests): structure, metrics, delegation instances, lazy initialization
+
+## [2.4.4]
+
+### Added
+
+- **Environment Variable Interpolation Control**: New `env_interpolation` setting to disable YAML variable interpolation
+  - **Global config**: `SwarmSDK.configure { |c| c.env_interpolation = false }`
+  - **Environment variable**: `SWARM_SDK_ENV_INTERPOLATION=false`
+  - **Per-load override**: `SwarmSDK.load(yaml, env_interpolation: false)` or `SwarmSDK.load_file(path, env_interpolation: false)`
+  - **Priority order**: per-load parameter > global config > environment variable > default (true)
+  - **Use cases**:
+    - Testing YAML files without setting environment variables
+    - Loading configs where `${...}` syntax should be preserved literally
+    - Security: preventing accidental environment variable exposure
+  - **Example**:
+    ```ruby
+    # Disable globally
+    SwarmSDK.configure do |config|
+      config.env_interpolation = false
+    end
+
+    # Disable for specific load
+    swarm = SwarmSDK.load_file("config.yml", env_interpolation: false)
+    ```
+  - **Files**: `lib/swarm_sdk/config.rb`, `lib/swarm_sdk/configuration.rb`, `lib/swarm_sdk/configuration/parser.rb`, `lib/swarm_sdk.rb`
+  - **Tests**: Comprehensive tests in `config_test.rb` and `configuration_test.rb`
+
+## [2.4.3]
+
+### Added
+
+- **Global Agent Registry**: Declare agents in separate files and reference them by name across swarms
+  - **`SwarmSDK.agent(:name) { ... }`**: Register agents globally for reuse across multiple swarms
+  - **`SwarmSDK.clear_agent_registry!`**: Clear all registrations (useful for testing)
+  - **Registry lookup in builders**: `agent :name` (no block) fetches from global registry
+  - **Registry + overrides**: `agent :name do ... end` applies registry config then override block
+  - **Duplicate registration error**: Raises `ArgumentError` if registering same name twice
+  - **Workflow node auto-resolution**: Agents referenced in nodes automatically resolve from registry
+    - Checks workflow-level definitions first, then falls back to global registry
+    - Includes delegation targets (`delegates_to`) in auto-resolution
+  - **Best practice**: Don't set `delegates_to` in registry—delegation is swarm-specific. Set it as an override in each swarm.
+  - **Use case**: Define agents once in separate files, compose into multiple swarms without duplication
+  - **Example**:
+    ```ruby
+    # agents/backend.rb
+    SwarmSDK.agent :backend do
+      model "claude-sonnet-4"
+      description "Backend developer"
+      tools :Read, :Edit, :Bash
+    end
+
+    # swarm.rb
+    SwarmSDK.build do
+      name "Dev Team"
+      lead :backend
+      agent :backend  # Pulls from registry
+    end
+
+    # workflow.rb - agents auto-resolve in nodes
+    SwarmSDK.workflow do
+      name "Pipeline"
+      start_node :build
+      node(:build) { agent(:backend) }  # Auto-resolved from registry
+    end
+    ```
+  - **Files**: `lib/swarm_sdk/agent_registry.rb`, `lib/swarm_sdk.rb`, `lib/swarm_sdk/builders/base_builder.rb`, `lib/swarm_sdk/workflow/builder.rb`
+  - **Tests**: 32 comprehensive tests in `test/swarm_sdk/agent_registry_test.rb`
+
+## [2.4.2]
+
+### Fixed
+
+- **Duplicate event emission bug**: Fixed agent_stop and agent_step events being emitted twice
+  - Root cause: `setup_logging` was being called twice during agent initialization
+  - First call in `agent_initializer.rb` when `LogStream.emitter` was set
+  - Second call in `emit_retroactive_agent_start_events` via `setup_logging_for_all_agents`
+  - Fix: Made `ContextTracker#setup_logging` idempotent with `@logging_setup` guard
+  - Prevents duplicate callback registration on `on_end_message`, `on_tool_result`, and `on_tool_call`
+
+### Added
+
+- **Event deduplication tests**: Comprehensive test suite to prevent regression
+  - `test_agent_stop_event_not_duplicated` - Ensures agent_stop emitted exactly once
+  - `test_agent_step_event_not_duplicated` - Ensures agent_step emitted exactly once per tool response
+  - `test_tool_call_event_not_duplicated` - Ensures tool_call emitted exactly once per invocation
+  - `test_tool_result_event_not_duplicated` - Ensures tool_result emitted exactly once
+  - `test_setup_logging_idempotency` - Verifies idempotent behavior across multiple executions
+  - `test_comprehensive_event_counts_*` - Validates exact event counts for various scenarios
+
+### Dependencies
+
+- Updated `ruby_llm_swarm` to `~> 1.9.5`
+- Added `openssl` (`~> 3.3.2`) dependency
+
+## [2.4.1]
+- Fix gemspec issues
+
+## [2.4.0]
+
+### Breaking Changes
+
+- **Centralized Configuration System**: Unified all configuration into `SwarmSDK::Config`
+  - **New API**: `SwarmSDK.config` replaces `SwarmSDK.settings`
+  - **Removed**: `SwarmSDK::Settings` class removed entirely
+  - **Removed**: `SwarmSDK.settings` method removed
+  - **Removed**: `SwarmSDK.reset_settings!` → use `SwarmSDK.reset_config!`
+  - **Removed**: Tool constants (DEFAULT_TIMEOUT_MS, MAX_OUTPUT_LENGTH, etc.)
+  - **API key proxying**: All API keys automatically proxy to `RubyLLM.config`
+  - **Override all defaults**: Every constant in Defaults module can now be overridden at runtime
+  - **Priority**: explicit value → ENV variable → Defaults module constant
+  - **Lazy ENV loading**: Thread-safe with double-check locking
+  - **Migration**:
+    - `SwarmSDK.settings.allow_filesystem_tools` → `SwarmSDK.config.allow_filesystem_tools`
+    - `SwarmSDK.reset_settings!` → `SwarmSDK.reset_config!`
+    - Tool constants → `SwarmSDK.config.*` methods (e.g., `SwarmSDK.config.bash_command_timeout`)
+
+### Fixed
+
+- **Base URL Configuration Bug**: Custom provider contexts now properly use configured API keys
+  - Previously: `configure_provider_base_url` read ENV directly, ignoring `RubyLLM.config`
+  - Now: Uses `SwarmSDK.config.openai_api_key` and other configured values
+  - Better error messages when API keys are missing for non-local endpoints
+
 ## [2.3.0]
 
 ### Breaking Changes
@@ -271,7 +519,7 @@ old[:metadata] = old.delete(:swarm)
   - **Documentation**: Complete guide in `docs/v2/guides/snapshots.md` with examples and comparisons
 
 - **System-Wide Filesystem Tools Control**: Global security setting to disable filesystem tools across all agents
-  - **`SwarmSDK.settings.allow_filesystem_tools`** - Global setting to enable/disable filesystem tools (default: true)
+  - **`SwarmSDK.config.allow_filesystem_tools`** - Global setting to enable/disable filesystem tools (default: true)
   - **Environment variable**: `SWARM_SDK_ALLOW_FILESYSTEM_TOOLS` - Set via environment for production deployments
   - **Parameter override**: `allow_filesystem_tools:` parameter in `SwarmSDK.build`, `load`, and `load_file`
   - **Filesystem tools**: Read, Write, Edit, MultiEdit, Grep, Glob, Bash