claude_swarm 0.3.11 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e0bade0292291825648214e0a1a420241ec1d6ffff018831d131d5c0f532e45
-  data.tar.gz: 74d62b916f1dbde6b725e8990924839c6ace2b6de75cb812f43305d044def7b7
+  metadata.gz: 10448e995f0dfb02668037c803ef03a7c9078c35deff18643c3479ec2ff14aee
+  data.tar.gz: f362d0f8c63e91c09ee1e36405aa79aa8c3abae2f2b19a4cbfb626e686da15dd
 SHA512:
-  metadata.gz: 0f7f0b3dad9bb034a5b1cf07417df7b3cef6dc7fa88d02d4c9617db354ff0f52d7a368f678f0d2502343fdb03112cf8672f68f2dce3a77a46d769f4cc8f0afa6
-  data.tar.gz: d2c81f31e2534e4f92f519ea1b218236d68ed2e08adbd3bfdb2d0569de1a5f80a2f5b2452e3c47b75e6e4441fb70575ca1fbf381d169c0b9ee2aca4b2072c7d6
+  metadata.gz: 88ef64675a48dc613f12b50701164050bf2fcc6dc433f0b976858737b07ccb4c167b3c9e5c1775535d89b157155aa8cb95942ff468c5258b3b03cbb802db988f
+  data.tar.gz: 3d2e4dc12833979001347f97fd3e6b9c914b8f1723799104eac1e4d0f48af3e4d92edc9bb0f02b8f59ab72ee7e9f9608e9d0b78a5386e1b5ada59b54d7913128

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## [Unreleased]
 
+## [1.0.1]
+
+### Fixed
+- **Fixed require statement for fast-mcp gem**: Updated `require "fast_mcp_annotations"` to `require "fast_mcp"` to match the gem dependency change in 1.0.0
+  - The gemspec was correctly updated to use fast-mcp (~> 1.6) in 1.0.0, but the require statement was not updated
+  - This fix ensures the correct gem is loaded at runtime
+
+## [1.0.0]
+
+### Added
+- **HTTP MCP server configuration support**: Added support for HTTP-type MCP servers alongside existing stdio and SSE types
+  - HTTP servers can be configured with a `url` field
+  - Properly preserves server type (http/sse) in generated configurations
+  - Full compatibility with Claude Code's HTTP MCP server implementation
+
+### Changed
+- **Updated dependency from fast-mcp-annotations to fast-mcp gem**: Migrated to the consolidated fast-mcp gem (~> 1.6)
+  - Consolidates MCP functionality into a single, more maintainable gem
+  - Maintains all existing functionality with improved performance
+- **Updated claude-code-sdk-ruby dependency**: Minimum version requirement increased to 0.1.6
+  - Includes latest SDK improvements and bug fixes
+  - Better error handling and stability
+- **Swarm generation improvements**: Generator now avoids creating swarms with circular dependencies
+  - Prevents generation of invalid configurations
+  - Improves reliability of generated swarm templates
+
+### Fixed
+- **Empty response validation**: Added validation to prevent empty or nil responses from being passed to MCP callers
+  - ClaudeCodeExecutor now validates that Claude SDK returns non-empty result content
+  - TaskTool validates response structure and content before returning to MCP caller
+  - Clear error messages indicate when agent completes execution but provides no response
+  - Prevents silent failures when Claude SDK returns empty results
+- **Before commands directory handling**: Fixed error when before commands need to create the main instance directory
+  - Smart directory detection: if the main instance directory exists, commands run inside it (for `npm install`, etc.)
+  - If the directory doesn't exist, commands run in the parent directory (allowing `mkdir` commands to create it)
+  - Works correctly with both regular directories and Git worktrees
+  - After commands follow the same logic for consistency
+  - Fixes "No such file or directory @ dir_chdir" errors when before commands create directories
+
+### Internal
+- **Centralized JSON handling**: Added JsonHandler class for consistent JSON parsing and generation
+  - Improved error handling for malformed JSON files
+  - Standardized JSON output formatting across all modules
+- **Centralized CLAUDE_SWARM_HOME handling**: Refactored environment variable management for cleaner code
+- **Enhanced test coverage**: Added comprehensive configuration tests and enabled branch coverage in SimpleCov
+  - Extensive validation of edge cases including circular dependencies
+  - Better coverage metrics with branch coverage enabled
+
 ## [0.3.11]
 
 ### Added

data/CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Claude Swarm is a Ruby gem that orchestrates multiple Claude Code instances as a collaborative AI development team. It enables running AI agents with specialized roles, tools, and directory contexts, communicating via MCP (Model Context Protocol).
 
+SwarmCore is a complete reimagining of Claude Swarm that decouples from Claude Code and runs everything in a single process using RubyLLM for all LLM interactions. It is being developed in `lib/swarm_core`, and using the gemspec swarm-core.gemspec.
+
 ## Development Commands
 
 ### Testing

data/README.md

@@ -228,6 +228,53 @@ swarm:
     # Instance definitions...
 ```
 
+#### YAML Aliases
+
+Claude Swarm supports [YAML aliases](https://yaml.org/spec/1.2.2/#71-alias-nodes) to reduce duplication in your configuration. This is particularly useful for sharing common values like prompts, tool lists, or MCP configurations across multiple instances:
+
+```yaml
+version: 1
+swarm:
+  name: "Development Team"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer"
+      prompt: &shared_prompt "You are an expert developer following best practices"
+      allowed_tools: &standard_tools
+        - Read
+        - Edit
+        - Bash
+        - WebSearch
+      mcps: &common_mcps
+        - name: github
+          type: stdio
+          command: gh
+          args: ["mcp"]
+          
+    frontend:
+      description: "Frontend developer"
+      prompt: *shared_prompt  # Reuses the same prompt
+      allowed_tools: *standard_tools  # Reuses the same tool list
+      mcps: *common_mcps  # Reuses the same MCP servers
+      directory: ./frontend
+      
+    backend:
+      description: "Backend developer"
+      prompt: *shared_prompt  # Reuses the same prompt
+      allowed_tools: *standard_tools  # Reuses the same tool list
+      mcps: *common_mcps  # Reuses the same MCP servers
+      directory: ./backend
+```
+
+In this example:
+- `&shared_prompt` defines an anchor for the prompt string
+- `&standard_tools` defines an anchor for the tool array
+- `&common_mcps` defines an anchor for the MCP configuration
+- `*shared_prompt`, `*standard_tools`, and `*common_mcps` reference those anchors
+
+This helps maintain consistency across instances and makes configuration updates easier.
+
 #### Environment Variable Interpolation
 
 Claude Swarm supports environment variable interpolation in all configuration values using the `${ENV_VAR_NAME}` syntax:
@@ -395,6 +442,17 @@ mcps:
       X-Custom-Header: "value"
 ```
 
+#### http (HTTP-based MCP)
+```yaml
+mcps:
+  - name: http_service
+    type: http
+    url: "https://api.example.com/mcp-endpoint"
+    headers:  # Optional: custom headers for authentication
+      Authorization: "Bearer ${API_TOKEN}"
+      X-API-Key: "${API_KEY}"
+```
+
 ### Hooks Configuration
 
 Claude Swarm supports configuring [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) for each instance. Hooks allow you to run custom scripts before/after tools, on prompt submission, and more. Each instance can have its own hooks configuration.

data/lib/claude_swarm/claude_code_executor.rb

@@ -40,6 +40,11 @@ module ClaudeSwarm
             # Assistant messages only contain content blocks
             # No need to track for result extraction - result comes from Result message
           when ClaudeSDK::Messages::Result
+            # Validate that we have actual result content
+            if message.result.nil? || (message.result.is_a?(String) && message.result.strip.empty?)
+              raise ExecutionError, "Claude SDK returned an empty result. The agent completed execution but provided no response content."
+            end
+
             # Build result response in expected format
             result_response = {
               "type" => "result",
@@ -91,7 +96,7 @@ module ClaudeSwarm
         updated_at: Time.now.iso8601,
       }
 
-      File.write(state_file, JSON.pretty_generate(state_data))
+      JsonHandler.write_file!(state_file, state_data)
       logger.info { "Wrote instance state for #{@instance_name} (#{@instance_id}) with session ID: #{@session_id}" }
     rescue StandardError => e
       logger.error { "Failed to write instance state for #{@instance_name} (#{@instance_id}): #{e.message}" }
@@ -114,13 +119,13 @@ module ClaudeSwarm
     end
 
     def log_system_message(event)
-      logger.debug { "SYSTEM: #{JSON.pretty_generate(event)}" }
+      logger.debug { "SYSTEM: #{JsonHandler.pretty_generate!(event)}" }
     end
 
     def log_assistant_message(msg)
       # Assistant messages don't have stop_reason in SDK - they only have content
       content = msg["content"]
-      logger.debug { "ASSISTANT: #{JSON.pretty_generate(content)}" } if content
+      logger.debug { "ASSISTANT: #{JsonHandler.pretty_generate!(content)}" } if content
 
       # Log tool calls
       tool_calls = content&.select { |c| c["type"] == "tool_use" } || []
@@ -141,7 +146,7 @@ module ClaudeSwarm
     end
 
     def log_user_message(content)
-      logger.debug { "USER: #{JSON.pretty_generate(content)}" }
+      logger.debug { "USER: #{JsonHandler.pretty_generate!(content)}" }
     end
 
     def build_sdk_options(prompt, options)
@@ -193,7 +198,7 @@ module ClaudeSwarm
 
     def parse_mcp_config(config_path)
       # Parse MCP JSON config file and convert to SDK format
-      config = JSON.parse(File.read(config_path))
+      config = JsonHandler.parse_file!(config_path)
       mcp_servers = {}
 
       config["mcpServers"]&.each do |name, server_config|

data/lib/claude_swarm/cli.rb

@@ -406,12 +406,12 @@ module ClaudeSwarm
       desc: "Number of lines to show initially"
     def watch(session_id)
       # Find session path
-      run_symlink = File.join(File.expand_path("~/.claude-swarm/run"), session_id)
+      run_symlink = ClaudeSwarm.joined_run_dir(session_id)
       session_path = if File.symlink?(run_symlink)
         File.readlink(run_symlink)
       else
         # Search in sessions directory
-        Dir.glob(File.expand_path("~/.claude-swarm/sessions/*/*")).find do |path|
+        Dir.glob(ClaudeSwarm.joined_sessions_dir("*", "*")).find do |path|
           File.basename(path) == session_id
         end
       end
@@ -437,7 +437,7 @@ module ClaudeSwarm
       default: 10,
       desc: "Maximum number of sessions to display"
     def list_sessions
-      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+      sessions_dir = ClaudeSwarm.joined_sessions_dir
       unless Dir.exist?(sessions_dir)
         say("No sessions found", :yellow)
         return
@@ -562,12 +562,10 @@ module ClaudeSwarm
         # Load session metadata if it exists to check for worktree info
         session_metadata_file = File.join(session_path, "session_metadata.json")
         worktree_name = nil
-        if File.exist?(session_metadata_file)
-          metadata = JSON.parse(File.read(session_metadata_file))
-          if metadata["worktree"] && metadata["worktree"]["enabled"]
-            worktree_name = metadata["worktree"]["name"]
-            say("Restoring with worktree: #{worktree_name}", :green) unless options[:prompt]
-          end
+        metadata = JsonHandler.parse_file(session_metadata_file)
+        if metadata && metadata["worktree"] && metadata["worktree"]["enabled"]
+          worktree_name = metadata["worktree"]["name"]
+          say("Restoring with worktree: #{worktree_name}", :green) unless options[:prompt]
         end
 
         # Create orchestrator with restoration mode
@@ -592,7 +590,7 @@ module ClaudeSwarm
     end
 
     def find_session_path(session_id)
-      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+      sessions_dir = ClaudeSwarm.joined_sessions_dir
 
       # Search for the session ID in all projects
       Dir.glob("#{sessions_dir}/*/#{session_id}").each do |path|
@@ -604,7 +602,7 @@ module ClaudeSwarm
     end
 
     def clean_stale_symlinks(days)
-      run_dir = File.expand_path("~/.claude-swarm/run")
+      run_dir = ClaudeSwarm.joined_run_dir
       return 0 unless Dir.exist?(run_dir)
 
       cleaned = 0
@@ -633,10 +631,10 @@ module ClaudeSwarm
     end
 
     def clean_orphaned_worktrees(days)
-      worktrees_dir = File.expand_path("~/.claude-swarm/worktrees")
+      worktrees_dir = ClaudeSwarm.joined_worktrees_dir
       return 0 unless Dir.exist?(worktrees_dir)
 
-      sessions_dir = File.expand_path("~/.claude-swarm/sessions")
+      sessions_dir = ClaudeSwarm.joined_sessions_dir
       cleaned = 0
 
       Dir.glob("#{worktrees_dir}/*").each do |session_worktree_dir|

data/lib/claude_swarm/commands/ps.rb

@@ -3,10 +3,9 @@
 module ClaudeSwarm
   module Commands
     class Ps
-      RUN_DIR = File.expand_path("~/.claude-swarm/run")
-
       def execute
-        unless Dir.exist?(RUN_DIR)
+        run_dir = ClaudeSwarm.joined_run_dir
+        unless Dir.exist?(run_dir)
           puts "No active sessions"
           return
         end
@@ -14,7 +13,7 @@ module ClaudeSwarm
         sessions = []
 
         # Read all symlinks in run directory
-        Dir.glob("#{RUN_DIR}/*").each do |symlink|
+        Dir.glob("#{run_dir}/*").each do |symlink|
           next unless File.symlink?(symlink)
 
           begin
@@ -147,9 +146,10 @@ module ClaudeSwarm
       def get_start_time(session_dir)
         # Try to get from session metadata first
         metadata_file = File.join(session_dir, "session_metadata.json")
-        if File.exist?(metadata_file)
-          metadata = JSON.parse(File.read(metadata_file))
-          return Time.parse(metadata["start_time"]) if metadata["start_time"]
+        metadata = JsonHandler.parse_file(metadata_file)
+
+        if metadata && metadata["start_time"]
+          return Time.parse(metadata["start_time"])
         end
 
         # Fallback to directory creation time
@@ -179,7 +179,7 @@ module ClaudeSwarm
         session_metadata_file = File.join(session_dir, "session_metadata.json")
         return directories unless File.exist?(session_metadata_file)
 
-        metadata = JSON.parse(File.read(session_metadata_file))
+        metadata = JsonHandler.parse_file!(session_metadata_file)
         worktree_info = metadata["worktree"]
         return directories unless worktree_info && worktree_info["enabled"]
 

data/lib/claude_swarm/commands/show.rb

@@ -63,23 +63,22 @@ module ClaudeSwarm
 
       def find_session_path(session_id)
         # First check the run directory
-        run_symlink = File.join(File.expand_path("~/.claude-swarm/run"), session_id)
+        run_symlink = ClaudeSwarm.joined_run_dir(session_id)
         if File.symlink?(run_symlink)
           target = File.readlink(run_symlink)
           return target if Dir.exist?(target)
         end
 
         # Fall back to searching all sessions
-        Dir.glob(File.expand_path("~/.claude-swarm/sessions/*/*")).find do |path|
+        Dir.glob(ClaudeSwarm.joined_sessions_dir("*", "*")).find do |path|
           File.basename(path) == session_id
         end
       end
 
       def get_runtime_info(session_path)
         metadata_file = File.join(session_path, "session_metadata.json")
-        return unless File.exist?(metadata_file)
-
-        metadata = JSON.parse(File.read(metadata_file))
+        metadata = JsonHandler.parse_file(metadata_file)
+        return unless metadata
 
         if metadata["duration_seconds"]
           # Session has completed

data/lib/claude_swarm/configuration.rb

@@ -59,7 +59,7 @@ module ClaudeSwarm
     end
 
     def load_and_validate
-      @config = YAML.load_file(@config_path)
+      @config = YAML.load_file(@config_path, aliases: true)
       interpolate_env_vars!(@config)
       validate_version
       validate_swarm
@@ -248,7 +248,7 @@ module ClaudeSwarm
       case mcp["type"]
       when "stdio"
         raise Error, "MCP '#{mcp["name"]}' missing 'command'" unless mcp["command"]
-      when "sse"
+      when "sse", "http"
         raise Error, "MCP '#{mcp["name"]}' missing 'url'" unless mcp["url"]
       else
         raise Error, "Unknown MCP type '#{mcp["type"]}' for '#{mcp["name"]}'"

data/lib/claude_swarm/json_handler.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  # Centralized JSON handling for the Claude Swarm codebase
+  class JsonHandler
+    class << self
+      # Parse JSON string into Ruby object
+      # @param json_string [String] The JSON string to parse
+      # @param raise_on_error [Boolean] Whether to raise exception on error (default: false)
+      # @return [Object] The parsed Ruby object, or original string if parsing fails and raise_on_error is false
+      # @raise [JSON::ParserError] If the JSON is invalid and raise_on_error is true
+      def parse(json_string, raise_on_error: false)
+        JSON.parse(json_string)
+      rescue JSON::ParserError => e
+        raise e if raise_on_error
+
+        json_string
+      end
+
+      # Parse JSON string with exception raising
+      # @param json_string [String] The JSON string to parse
+      # @return [Object] The parsed Ruby object
+      # @raise [JSON::ParserError] If the JSON is invalid
+      def parse!(json_string)
+        parse(json_string, raise_on_error: true)
+      end
+
+      # Parse JSON from a file with exception raising
+      # @param file_path [String] Path to the JSON file
+      # @return [Object] The parsed Ruby object
+      # @raise [Errno::ENOENT] If the file does not exist
+      # @raise [JSON::ParserError] If the file contains invalid JSON
+      def parse_file!(file_path)
+        content = File.read(file_path)
+        parse!(content)
+      end
+
+      # Parse JSON from a file, returning nil on error
+      # @param file_path [String] Path to the JSON file
+      # @return [Object, nil] The parsed Ruby object or nil if file doesn't exist or contains invalid JSON
+      def parse_file(file_path)
+        parse_file!(file_path)
+      rescue Errno::ENOENT, JSON::ParserError
+        nil
+      end
+
+      # Generate pretty-formatted JSON string
+      # @param object [Object] The Ruby object to convert to JSON
+      # @param raise_on_error [Boolean] Whether to raise exception on error (default: false)
+      # @return [String, nil] The pretty-formatted JSON string, or nil if generation fails and raise_on_error is false
+      # @raise [JSON::GeneratorError] If the object cannot be converted to JSON and raise_on_error is true
+      def pretty_generate(object, raise_on_error: false)
+        JSON.pretty_generate(object)
+      rescue JSON::GeneratorError, JSON::NestingError => e
+        raise e if raise_on_error
+
+        nil
+      end
+
+      # Generate pretty-formatted JSON string with exception raising
+      # @param object [Object] The Ruby object to convert to JSON
+      # @return [String] The pretty-formatted JSON string
+      # @raise [JSON::GeneratorError] If the object cannot be converted to JSON
+      def pretty_generate!(object)
+        pretty_generate(object, raise_on_error: true)
+      end
+
+      # Write Ruby object to a JSON file with pretty formatting
+      # @param file_path [String] Path to the JSON file
+      # @param object [Object] The Ruby object to write
+      # @return [Boolean] True if successful, false if generation or write fails
+      def write_file(file_path, object)
+        json_string = pretty_generate!(object)
+        File.write(file_path, json_string)
+        true
+      rescue JSON::GeneratorError, JSON::NestingError, SystemCallError
+        false
+      end
+
+      # Write Ruby object to a JSON file with exception raising
+      # @param file_path [String] Path to the JSON file
+      # @param object [Object] The Ruby object to write
+      # @raise [JSON::GeneratorError] If the object cannot be converted to JSON
+      # @raise [SystemCallError] If the file cannot be written
+      def write_file!(file_path, object)
+        json_string = pretty_generate!(object)
+        File.write(file_path, json_string)
+      end
+    end
+  end
+end

data/lib/claude_swarm/mcp_generator.rb

@@ -73,7 +73,7 @@ module ClaudeSwarm
         "mcpServers" => mcp_servers,
       }
 
-      File.write(mcp_config_path(name), JSON.pretty_generate(config))
+      JsonHandler.write_file!(mcp_config_path(name), config)
     end
 
     def build_mcp_server_config(mcp)
@@ -86,9 +86,9 @@ module ClaudeSwarm
         }.tap do |config|
           config["env"] = mcp["env"] if mcp["env"]
         end
-      when "sse"
+      when "sse", "http"
         {
-          "type" => "sse",
+          "type" => mcp["type"],
           "url" => mcp["url"],
         }.tap do |config|
           config["headers"] = mcp["headers"] if mcp["headers"]
@@ -220,7 +220,7 @@ module ClaudeSwarm
       return unless Dir.exist?(state_dir)
 
       Dir.glob(File.join(state_dir, "*.json")).each do |state_file|
-        data = JSON.parse(File.read(state_file))
+        data = JsonHandler.parse_file!(state_file)
         instance_name = data["instance_name"]
         instance_id = data["instance_id"]
 

data/lib/claude_swarm/openai/chat_completion.rb

@@ -83,7 +83,7 @@ module ClaudeSwarm
         parameters[:tools] = @mcp_client.to_openai_tools if @available_tools&.any? && @mcp_client
 
         # Log the request parameters
-        @executor.logger.info { "Chat API Request (depth=#{depth}): #{JSON.pretty_generate(parameters)}" }
+        @executor.logger.info { "Chat API Request (depth=#{depth}): #{JsonHandler.pretty_generate!(parameters)}" }
 
         # Append to session JSON
         append_to_session_json({
@@ -98,7 +98,7 @@ module ClaudeSwarm
           response = @openai_client.chat(parameters: parameters)
         rescue StandardError => e
           @executor.logger.error { "Chat API error: #{e.class} - #{e.message}" }
-          @executor.logger.error { "Request parameters: #{JSON.pretty_generate(parameters)}" }
+          @executor.logger.error { "Request parameters: #{JsonHandler.pretty_generate!(parameters)}" }
 
           # Try to extract and log the response body for better debugging
           if e.respond_to?(:response)
@@ -127,7 +127,7 @@ module ClaudeSwarm
         end
 
         # Log the response
-        @executor.logger.info { "Chat API Response (depth=#{depth}): #{JSON.pretty_generate(response)}" }
+        @executor.logger.info { "Chat API Response (depth=#{depth}): #{JsonHandler.pretty_generate!(response)}" }
 
         # Append to session JSON
         append_to_session_json({
@@ -169,7 +169,7 @@ module ClaudeSwarm
 
       def execute_and_append_tool_results(tool_calls, messages)
         # Log tool calls
-        @executor.logger.info { "Executing tool calls: #{JSON.pretty_generate(tool_calls)}" }
+        @executor.logger.info { "Executing tool calls: #{JsonHandler.pretty_generate!(tool_calls)}" }
 
         # Append to session JSON
         append_to_session_json({
@@ -186,10 +186,10 @@ module ClaudeSwarm
 
             begin
               # Parse arguments
-              tool_args = tool_args_str.is_a?(String) ? JSON.parse(tool_args_str) : tool_args_str
+              tool_args = tool_args_str.is_a?(String) ? JsonHandler.parse!(tool_args_str) : tool_args_str
 
               # Log tool execution
-              @executor.logger.info { "Executing tool: #{tool_name} with args: #{JSON.pretty_generate(tool_args)}" }
+              @executor.logger.info { "Executing tool: #{tool_name} with args: #{JsonHandler.pretty_generate!(tool_args)}" }
 
               # Execute tool via MCP
               result = @mcp_client.call_tool(tool_name, tool_args)

data/lib/claude_swarm/openai/executor.rb

@@ -122,7 +122,7 @@ module ClaudeSwarm
         return unless @mcp_config && File.exist?(@mcp_config)
 
         # Read MCP config to find MCP servers
-        mcp_data = JSON.parse(File.read(@mcp_config))
+        mcp_data = JsonHandler.parse_file!(@mcp_config)
 
         # Build MCP configurations from servers
         mcp_configs = build_mcp_configs(mcp_data["mcpServers"])

data/lib/claude_swarm/openai/responses.rb

@@ -97,7 +97,7 @@ module ClaudeSwarm
         end
 
         # Log the request parameters
-        @executor.logger.info { "Responses API Request (depth=#{depth}): #{JSON.pretty_generate(parameters)}" }
+        @executor.logger.info { "Responses API Request (depth=#{depth}): #{JsonHandler.pretty_generate!(parameters)}" }
 
         # Append to session JSON
         append_to_session_json({
@@ -112,7 +112,7 @@ module ClaudeSwarm
           response = @openai_client.responses.create(parameters: parameters)
         rescue StandardError => e
           @executor.logger.error { "Responses API error: #{e.class} - #{e.message}" }
-          @executor.logger.error { "Request parameters: #{JSON.pretty_generate(parameters)}" }
+          @executor.logger.error { "Request parameters: #{JsonHandler.pretty_generate!(parameters)}" }
 
           # Try to extract and log the response body for better debugging
           if e.respond_to?(:response)
@@ -140,7 +140,7 @@ module ClaudeSwarm
         end
 
         # Log the full response
-        @executor.logger.info { "Responses API Full Response (depth=#{depth}): #{JSON.pretty_generate(response)}" }
+        @executor.logger.info { "Responses API Full Response (depth=#{depth}): #{JsonHandler.pretty_generate!(response)}" }
 
         # Append to session JSON
         append_to_session_json({
@@ -230,10 +230,10 @@ module ClaudeSwarm
 
           begin
             # Parse arguments
-            tool_args = JSON.parse(tool_args_str)
+            tool_args = JsonHandler.parse!(tool_args_str)
 
             # Log tool execution
-            @executor.logger.info { "Responses API - Executing tool: #{tool_name} with args: #{JSON.pretty_generate(tool_args)}" }
+            @executor.logger.info { "Responses API - Executing tool: #{tool_name} with args: #{JsonHandler.pretty_generate!(tool_args)}" }
 
             # Execute tool via MCP
             result = @mcp_client.call_tool(tool_name, tool_args)
@@ -283,7 +283,7 @@ module ClaudeSwarm
         end
 
         @executor.logger.info { "Responses API - Built conversation with #{conversation.size} function outputs" }
-        @executor.logger.debug { "Final conversation structure: #{JSON.pretty_generate(conversation)}" }
+        @executor.logger.debug { "Final conversation structure: #{JsonHandler.pretty_generate!(conversation)}" }
         conversation
       end
 
@@ -299,10 +299,10 @@ module ClaudeSwarm
 
           begin
             # Parse arguments
-            tool_args = JSON.parse(tool_args_str)
+            tool_args = JsonHandler.parse!(tool_args_str)
 
             # Log tool execution
-            @executor.logger.info { "Responses API - Executing tool: #{tool_name} with args: #{JSON.pretty_generate(tool_args)}" }
+            @executor.logger.info { "Responses API - Executing tool: #{tool_name} with args: #{JsonHandler.pretty_generate!(tool_args)}" }
 
             # Execute tool via MCP
             result = @mcp_client.call_tool(tool_name, tool_args)