claude_swarm 1.0.9 → 1.0.11

data/docs/v2/CHANGELOG.swarm_sdk.md

@@ -5,10 +5,411 @@ 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).
 
-## [Unreleased]
+## [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
+
+- **Agent::Chat Abstraction Layer**: Refactored Agent::Chat from inheritance to composition with RubyLLM::Chat
+  - **Removed direct access**: SDK consumers can no longer access `.tools`, `.messages`, or `.model` directly
+  - **New abstraction methods**: SwarmSDK-specific API that hides RubyLLM internals
+    - `has_tool?(name)` - Check if tool exists by name (symbol or string)
+    - `tool_names` - Get array of tool names (symbols)
+    - `model_id` - Get model identifier string
+    - `model_provider` - Get model provider string
+    - `message_count` - Get number of messages in conversation
+    - `has_user_message?` - Check if conversation has any user messages
+    - `last_assistant_message` - Get most recent assistant message
+    - `take_snapshot` - Serialize conversation for persistence
+    - `restore_snapshot(data)` - Restore conversation from serialized data
+  - **Internal access methods**: For helper modules that need direct access
+    - `internal_messages` - Direct array of RubyLLM messages (for internal use only)
+    - `internal_tools` - Direct hash of tool instances (for internal use only)
+    - `internal_model` - Direct RubyLLM model object (for internal use only)
+  - **Migration**:
+    - `chat.tools.key?(:Read)` → `chat.has_tool?(:Read)`
+    - `chat.tools.keys` → `chat.tool_names`
+    - `chat.model.id` → `chat.model_id`
+    - `chat.model.provider` → `chat.model_provider`
+    - `chat.messages.count` → `chat.message_count`
+    - `chat.messages` (for internal modules) → `chat.internal_messages`
+  - **Improved encapsulation**: Prevents tight coupling to RubyLLM internals, making future LLM library changes easier
+  - **Files affected**:
+    - `lib/swarm_sdk/agent/chat.rb` - Core abstraction implementation
+    - `lib/swarm_sdk/swarm.rb` - Uses `tool_names` instead of `tools.keys`
+    - `lib/swarm_sdk/state_snapshot.rb` - Uses `internal_messages`
+    - `lib/swarm_sdk/state_restorer.rb` - Uses `internal_messages`
+    - `lib/swarm_sdk/context_compactor.rb` - Uses `internal_messages`
+    - `lib/swarm_sdk/agent/chat/hook_integration.rb` - Uses abstraction methods
+    - `lib/swarm_sdk/agent/chat/system_reminder_injector.rb` - Uses abstraction methods
+    - `lib/swarm_sdk/agent/chat/context_tracker.rb` - Uses `model_id`
+
+- **MAJOR REFACTORING**: Separated Swarm and Workflow into distinct, clear APIs
+  - `SwarmSDK.build` now ONLY returns `Swarm` (simple multi-agent collaboration)
+  - New `SwarmSDK.workflow` API for multi-stage workflows (returns `Workflow`)
+  - `NodeOrchestrator` class renamed to `Workflow` (clearer naming)
+  - Attempting to use nodes in `SwarmSDK.build` now raises `ConfigurationError`
+  - Snapshot version bumped to 2.0.0 (old snapshots incompatible)
+  - Snapshot structure changed: `swarm:` key renamed to `metadata:`
+
+- **YAML Configuration**: Explicit type keys for Swarm vs Workflow
+  - `swarm:` key now ONLY for Swarm configurations (requires `lead:`, cannot have `nodes:`)
+  - New `workflow:` key for Workflow configurations (requires `start_node:` and `nodes:`)
+  - Cannot have both `swarm:` and `workflow:` keys in same file
+  - Same `SwarmSDK.load_file` API works for both types (auto-detects from root key)
+
+### Added
+
+- New `SwarmSDK.workflow` DSL for building multi-stage workflows
+- **YAML `workflow:` key support**: Explicit root key for workflow configurations
+  - Clearer separation between Swarm and Workflow in YAML files
+  - Configuration class with proper separation of concerns (type detection, validation, loading)
+  - Validates type-specific requirements (e.g., `swarm:` cannot have `nodes:`)
+- Three new concern modules for shared functionality:
+  - `Concerns::Snapshotable` - Common snapshot/restore interface
+  - `Concerns::Validatable` - Common validation interface
+  - `Concerns::Cleanupable` - Common cleanup interface
+- `Builders::BaseBuilder` - Shared DSL logic for both Swarm and Workflow builders
+- Both `Swarm` and `Workflow` now implement common interface methods:
+  - `primary_agents` - Access to primary agent instances
+  - `delegation_instances_hash` - Access to delegation instances
+
+### Changed
+
+- `Workflow` (formerly `NodeOrchestrator`) internal structure simplified to match `Swarm`:
+  - Replaced `@agent_instance_cache = { primary: {}, delegations: {} }`
+  - With `@agents = {}` and `@delegation_instances = {}`
+- `Swarm::Builder` dramatically simplified: 784 lines → 208 lines (73% reduction)
+- `StateSnapshot` and `StateRestorer` no longer use type checking - rely on interface methods
+- `SnapshotFromEvents` updated to generate v2.0.0 snapshots with new structure
+- Module namespace: `Node::` renamed to `Workflow::`
+  - `Node::Builder` → `Workflow::NodeBuilder`
+  - `Node::AgentConfig` → `Workflow::AgentConfig`
+  - `Node::TransformerExecutor` → `Workflow::TransformerExecutor`
+
+### Removed
+
+- Dual-return-type pattern from `SwarmSDK.build` (no longer returns `NodeOrchestrator`)
+- ~600 lines of duplicated code across Swarm and NodeOrchestrator
+- Complex type-checking logic in StateSnapshot and StateRestorer
+
+### Migration Guide
+
+**For vanilla swarm users (no nodes):** No changes needed! Your code works as-is.
+
+**For workflow users (using Ruby DSL):** Change `SwarmSDK.build` to `SwarmSDK.workflow`:
+
+```ruby
+# Before
+SwarmSDK.build do
+  node :planning { ... }
+end
+
+# After
+SwarmSDK.workflow do
+  node :planning { ... }
+end
+```
+
+**For YAML workflow users:** Change `swarm:` key to `workflow:`:
+
+```yaml
+# Before
+version: 2
+swarm:
+  name: "Pipeline"
+  start_node: planning
+  agents: { ... }
+  nodes: { ... }
+
+# After
+version: 2
+workflow:
+  name: "Pipeline"
+  start_node: planning
+  agents: { ... }
+  nodes: { ... }
+```
+
+**For event-sourcing users:** No changes needed! `SnapshotFromEvents.reconstruct(events)` automatically generates v2.0.0 snapshots.
+
+**For snapshot storage users:** Old snapshots (v1.0.0) won't restore. Create new snapshots or convert:
+```ruby
+old[:version] = "2.0.0"
+old[:metadata] = old.delete(:swarm)
+```
+
+### Added
+
+- **Non-Blocking Execution with Cancellation Support**: Optional `wait` parameter enables task cancellation
+  - **`wait: true` (default)**: Maintains backward-compatible blocking behavior, returns `Result`
+  - **`wait: false`**: Returns `Async::Task` immediately for non-blocking execution
+  - **`task.stop`**: Cancels execution at next fiber yield point (HTTP I/O, tool boundaries)
+  - **Cooperative cancellation**: Stops when fiber yields, not immediate for synchronous operations
+  - **Proper cleanup**: MCP clients, fiber storage, and logging cleaned in task's ensure block
+  - **Cleanup on cancellation**: Ensure blocks execute when task stopped via `Async::Stop` exception
+  - **`task.wait` returns nil**: Cancelled tasks return `nil` from `wait` method
+  - **Execution flow**: Reprompting loop and all cleanup moved inside Async block
+  - **Parent cleanup**: Fiber storage cleaned after `task.wait` when `wait: true`
+  - **Examples**:
+    - Blocking: `result = swarm.execute("Build auth")` (current behavior)
+    - Non-blocking: `task = swarm.execute("Build auth", wait: false)` then `task.stop`
+  - **Files**: `lib/swarm_sdk/swarm.rb` (major refactor of execute method)
+  - **Tests**: 9 comprehensive tests in `test/swarm_sdk/execute_wait_parameter_test.rb`
+
+- **Delegation Result Event Reconstruction**: Snapshot/restore now handles delegation events properly
+  - **`delegation_result` event support**: EventsToMessages reconstructs tool result messages from delegations
+  - **Proper conversation restoration**: Delegations correctly reconstructed from event logs
+  - **Snapshot compatibility**: Enables complete state restoration including delegation history
+  - **Files**: `lib/swarm_sdk/events_to_messages.rb`
+
 - **User Prompt Source Tracking**: `user_prompt` events now include source information to distinguish user interactions from delegations
   - **`source` field**: Indicates origin of prompt - `"user"` (direct user interaction) or `"delegation"` (from delegation tool)
   - **Event filtering**: Enables filtering user prompts by source in logs and analytics
@@ -36,7 +437,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Example**: `agent(:planner).tools(:Think, :Read)` in planning node, `agent(:planner).tools(:Write, :Edit, :Bash)` in implementation node
   - **Implementation**: New `tools(*tool_names)` method on `AgentConfig`, stored in node configuration as tool override
   - **Backward compatible**: Omit `.tools()` to use agent's global tool configuration
-  - **Files**: `lib/swarm_sdk/node/agent_config.rb`, `lib/swarm_sdk/node/builder.rb`, `lib/swarm_sdk/node_orchestrator.rb`
+  - **Files**: `lib/swarm_sdk/workflow/agent_config.rb`, `lib/swarm_sdk/workflow/node_builder.rb`, `lib/swarm_sdk/workflow.rb`
+
+### Changed
+
+- **BREAKING: Delegation Tool Rebranding**: Delegation tools renamed to emphasize collaboration over task delegation
+  - **Tool naming**: `DelegateTaskToBackend` → `WorkWithBackend`
+  - **Tool parameter**: `task:` → `message:` (more flexible, supports questions and collaboration)
+  - **Tool description**: Now emphasizes working with agents, not just delegating tasks
+  - **Configurable prefix**: Added `TOOL_NAME_PREFIX` constant for easy customization
+  - **Migration**: Update code/tests using `DelegateTaskTo*` to use `WorkWith*`
+  - **Parameter migration**: Change `task:` parameter to `message:` in delegation tool calls
+  - **Rationale**: Better reflects collaborative agent relationships and flexible communication patterns
+  - **Files affected**: `lib/swarm_sdk/tools/delegate.rb`, `lib/swarm_sdk/agent/chat/context_tracker.rb`, `lib/swarm_sdk/swarm/agent_initializer.rb`, `lib/swarm_cli/interactive_repl.rb`
+  - **Tests updated**: All delegation tests updated to use new naming (18 files)
+
+### Fixed
+
+- **MCP Configuration for Non-OAuth Servers**: Fixed errors when configuring MCP servers without OAuth
+  - **Issue**: OAuth field was included in streamable config even when not configured, causing errors
+  - **Fix**: Removed `oauth` field from streamable config hash
+  - **Additional fix**: Only include `rate_limit` if explicitly configured (avoid nil values)
+  - **Impact**: MCP servers without OAuth now configure correctly without errors
+  - **Files**: `lib/swarm_sdk/swarm/mcp_configurator.rb`
 
 ## [2.2.0] - 2025-11-06
 
@@ -96,7 +519,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **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
@@ -158,7 +581,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - Enables calculating total cost/tokens for a single execution
     - Allows building complete execution traces across all agents and tools
   - **`swarm_id`**: Identifies which swarm/node emitted the event
-    - Hierarchical format for NodeOrchestrator nodes (e.g., `workflow/node:planning`)
+    - Hierarchical format for Workflow nodes (e.g., `workflow/node:planning`)
     - Tracks execution flow through nested swarms and workflow stages
   - **`parent_swarm_id`**: Identifies the parent swarm for nested execution contexts
   - **Fiber-local storage implementation**: Uses Ruby 3.2+ Fiber storage for automatic propagation
@@ -203,7 +626,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Tool state isolation**: TodoWrite, ReadTracker, and other stateful tools isolated per instance
   - **Nested delegation support**: Works correctly with multi-level delegation chains
   - **Fiber-safe concurrency**: Added `Async::Semaphore` to `Chat.ask()` to prevent message corruption when multiple delegation instances call shared agents in parallel
-  - **Atomic caching**: NodeOrchestrator caches delegation instances together with primary agents for context preservation
+  - **Atomic caching**: Workflow caches delegation instances together with primary agents for context preservation
   - **Agent name validation**: Agent names cannot contain '@' character (reserved for delegation instances)
   - **Automatic deduplication**: Duplicate entries in `delegates_to` are automatically removed
   - **Comprehensive test coverage**: 17 new tests covering isolated mode, shared mode, nested delegation, cleanup, and more
@@ -343,7 +766,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Context Preservation Across Nodes**: `reset_context` parameter for node agents
   - `agent(:name, reset_context: false)` preserves conversation history across nodes
   - Default: `reset_context: true` (fresh context for each node - safe default)
-  - NodeOrchestrator caches and reuses agent instances when `reset_context: false`
+  - Workflow caches and reuses agent instances when `reset_context: false`
   - Enables stateful workflows where agents remember previous node conversations
   - Perfect for iterative refinement, self-reflection loops, and chain-of-thought reasoning
 
@@ -359,15 +782,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Removes memory-specific code from SwarmSDK core (moved to SwarmMemory plugin)
   - Maintains backward compatibility - permissions remain in core SDK (not plugin-specific)
   - Enables clean separation between core SDK and plugin features (memory, skills, etc.)
-  - Plugins can preserve their configuration when agents are cloned in NodeOrchestrator
+  - Plugins can preserve their configuration when agents are cloned in Workflow
 
-- **NodeOrchestrator**: Configurable scratchpad sharing modes
+- **Workflow**: Configurable scratchpad sharing modes
   - `scratchpad: :enabled` - Share scratchpad across all nodes
   - `scratchpad: :per_node` - Isolated scratchpad per node
   - `scratchpad: :disabled` - No scratchpad tools (default)
 
-- **CLI ConfigLoader**: Accepts both Swarm and NodeOrchestrator instances
-  - Bug fix: CLI now correctly handles NodeOrchestrator execution
+- **CLI ConfigLoader**: Accepts both Swarm and Workflow instances
+  - Bug fix: CLI now correctly handles Workflow execution
   - Enables node workflows to work seamlessly with CLI commands
 
 - **Error handling in Agent::Chat**: More robust exception handling

data/docs/v2/README.md

@@ -1,7 +1,5 @@
 # SwarmSDK, SwarmCLI & SwarmMemory Documentation
 
-**Version 2.1**
-
 Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory - a Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.
 
 ---
@@ -63,6 +61,10 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
 - **[Ruby DSL Reference](reference/ruby-dsl.md)**
   Complete programmatic API: `SwarmSDK.build`, `SwarmSDK.load`, agent DSL, permissions DSL, node DSL, hooks
 
+### Configuration
+- **[Configuration Reference](reference/configuration_reference.md)** ⭐ NEW
+  Complete reference for all 45+ configuration options: API keys, timeouts, limits, WebFetch settings, security
+
 ### YAML Configuration
 - **[YAML Configuration Reference](reference/yaml.md)**
   Complete YAML structure: agents, tools, permissions, hooks, nodes, MCP servers
@@ -90,7 +92,7 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
   Persistent agent knowledge storage with semantic search:
   - Installation and setup
   - 4 memory categories (concept, fact, skill, experience)
-  - 9 memory tools (MemoryWrite, LoadSkill, etc.)
+  - 8 memory tools (7 memory tools + LoadSkill for dynamic tool swapping)
   - Automatic skill discovery (hybrid semantic + keyword)
   - Relationship discovery and knowledge graphs
   - Performance and troubleshooting
@@ -199,12 +201,18 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
 **Build composable/reusable swarm teams** ⭐ NEW
 → [Composable Swarms Guide](guides/composable-swarms.md)
 
+**Add custom tools to agents**
+→ [Ruby DSL Reference - Custom Tools](reference/ruby-dsl.md#custom-tool-registration)
+
 **Build a SwarmSDK plugin**
 → [Plugin System Guide](guides/plugins.md)
 
 **Build a custom storage adapter**
 → [Memory Adapter Guide](guides/memory-adapters.md)
 
+**Configure SwarmSDK settings** ⭐ NEW
+→ [Configuration Reference](reference/configuration_reference.md)
+
 **Secure swarms for production** ⭐ NEW
 → [Filesystem Tools Control](reference/ruby-dsl.md#swarmsdk.configure) | [Security Considerations](guides/complete-tutorial.md#security-considerations)
 
@@ -237,6 +245,7 @@ docs/v2/
 ├── reference/                          # Complete API references
 │   ├── architecture-flow.md            # System architecture diagram ⭐ NEW
 │   ├── execution-flow.md               # Runtime execution flow ⭐ NEW
+│   ├── configuration_reference.md      # All configuration options ⭐ NEW
 │   ├── event_payload_structures.md     # Log event payloads
 │   ├── swarm_memory_technical_details.md  # SwarmMemory deep dive
 │   ├── cli.md                          # CLI command reference
@@ -297,8 +306,8 @@ A command-line interface for running SwarmSDK swarms with two modes:
 A persistent memory system for agents with semantic search capabilities:
 - **Storage**: Hierarchical knowledge organization (concept, fact, skill, experience)
 - **Semantic Search**: FAISS-based vector similarity with local ONNX embeddings
-- **Memory Tools**: 9 tools for writing, reading, editing, and searching knowledge
-- **LoadSkill**: Dynamic tool swapping based on semantic skill discovery
+- **Memory Tools**: 7 tools for writing, reading, editing, and searching knowledge
+- **LoadSkill**: Dynamic tool swapping based on semantic skill discovery (8 tools total)
 - **Plugin Architecture**: Integrates seamlessly via SwarmSDK plugin system
 
 ### Configuration Formats
@@ -328,6 +337,7 @@ A persistent memory system for agents with semantic search capabilities:
 | **Memory Adapters** | [Adapter Guide](guides/memory-adapters.md) | [Technical Details](reference/swarm_memory_technical_details.md) |
 | **Plugins** | [Plugin Guide](guides/plugins.md) | - |
 | **Rails** | [Rails Guide](guides/rails-integration.md) | - |
+| **Configuration** | - | [Configuration Ref](reference/configuration_reference.md) |
 | **Testing** | [Tutorial Part 8](guides/complete-tutorial.md#testing-strategies) | - |
 
 ---
@@ -337,10 +347,15 @@ A persistent memory system for agents with semantic search capabilities:
 All documentation in this directory follows these principles:
 
 ✅ **100% Accurate** - All information verified against source code
+
 ✅ **Comprehensive** - Every feature documented
+
 ✅ **Progressive** - Simple → Intermediate → Advanced
+
 ✅ **Practical** - Real-world examples throughout
+
 ✅ **Both Formats** - YAML and Ruby DSL for everything
+
 ✅ **User-Focused** - Written for developers using SwarmSDK, not implementers
 
 ---