agent-harness 0.11.0 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 635aae919a5bbbf99af4a24199b45507370c01ccbf637bfd8d9d0fa18bdb3c22
-  data.tar.gz: 30548d834ae0195030e98565007ced6ebf140f12f9a489ae10a6d423c40e087f
+  metadata.gz: 50b5bc213cf4a1b6f9441a06a82c38210c7e6907eb085e6cadf71e305e4b7897
+  data.tar.gz: 9785ea0b1b35f5aa52528741ce070287f2d433235ffeaf3d6df0ab7337f486b0
 SHA512:
-  metadata.gz: ac200425094b482ad90fd6492ba0bf4d612ed08560bacde517c988375d1d452b12aca7c34f8ed9519cf907daa87a07a96a4c044952126ce3cd9e37f2d6b9a788
-  data.tar.gz: a871de9fcc11224506f4220025016b3b7201ef97bc1e1aca918562c1f983b9dd175a93dbd6315a71a3a270234d3b9cd019f7deaa82030b984e11434ca86328f8
+  metadata.gz: 2343d812d85375faad3a55e0462eb228003ff5eddc1920fd1edb75aedf381e5b86e3062c191ee64d24c39f245c1f27ded7d0e74247526727901b6b5391c2518a
+  data.tar.gz: cfe73ff0ffce00f5e0be1726b3dc28d0cdb73aab6546988c19b79846c1d16014476302f2d258d13bb703124edbf86066a96cd43044047ebacc81ad0cf5c853e5

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.11.0"
+  ".": "0.11.2"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.11.2](https://github.com/viamin/agent-harness/compare/agent-harness/v0.11.1...agent-harness/v0.11.2) (2026-04-27)
+
+
+### Bug Fixes
+
+* 162: Support provider-agnostic MCP configuration ([#165](https://github.com/viamin/agent-harness/issues/165)) ([27f4814](https://github.com/viamin/agent-harness/commit/27f48146e99d8fdba0346235a3e5f19138266652))
+
+## [0.11.1](https://github.com/viamin/agent-harness/compare/agent-harness/v0.11.0...agent-harness/v0.11.1) (2026-04-26)
+
+
+### Bug Fixes
+
+* 163: Support provider-agnostic sub-agent definitions ([#166](https://github.com/viamin/agent-harness/issues/166)) ([1a00c35](https://github.com/viamin/agent-harness/commit/1a00c35f61c624b23f8d37b0d1b41e007d007ad3))
+
 ## [0.11.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.10.0...agent-harness/v0.11.0) (2026-04-25)
 
 

data/lib/agent_harness/configuration.rb

@@ -23,6 +23,7 @@ module AgentHarness
     attr_writer :command_executor
 
     attr_reader :providers, :orchestration_config, :callbacks, :custom_provider_classes
+    attr_reader :sub_agents, :tool_registry, :mcp_servers
 
     def initialize
       @logger = nil # Will use null logger if not set
@@ -36,6 +37,9 @@ module AgentHarness
       @orchestration_config = OrchestrationConfig.new
       @callbacks = CallbackRegistry.new
       @custom_provider_classes = {}
+      @sub_agents = {}
+      @tool_registry = ToolRegistry.new
+      @mcp_servers = {}
     end
 
     # Get or lazily initialize the command executor
@@ -74,6 +78,94 @@ module AgentHarness
       @custom_provider_classes[name.to_sym] = klass
     end
 
+    # Set MCP servers from an array of server definitions.
+    #
+    # @param servers [Array<Hash, McpServer>] server definitions
+    def mcp_servers=(servers)
+      normalized = McpConfigTranslator.normalize_servers(servers)
+      @mcp_servers = normalized.each_with_object({}) { |s, h| h[s.name.to_sym] = s }
+    end
+
+    # Load MCP server definitions from a configuration file.
+    #
+    # @param path [String] file path
+    def load_mcp_servers_file(path)
+      loaded = McpConfigLoader.load_file(path)
+      @mcp_servers = loaded.each_with_object({}) { |s, h| h[s.name.to_sym] = s }
+    end
+
+    # Configure a provider-agnostic sub-agent definition.
+    #
+    # @param name [Symbol, String] sub-agent name
+    # @param attributes [Hash] sub-agent attributes
+    # @yield [Hash] mutable attributes hash before validation
+    # @return [SubAgentConfig] registered sub-agent config
+    def sub_agent(name, attributes = {})
+      attributes = attributes.dup
+      yield(attributes) if block_given?
+      attributes[:name] = name
+
+      config = SubAgentConfig.from_hash(attributes)
+      @sub_agents[config.name] = config
+    end
+
+    # Load sub-agent definitions from a YAML or Markdown file.
+    #
+    # @param path [String] file path
+    # @return [Array<SubAgentConfig>] loaded sub-agents
+    def load_sub_agents(path)
+      SubAgentFileLoader.load(path).each do |sub_agent|
+        @sub_agents[sub_agent.name] = sub_agent
+      end
+    end
+
+    # Register a generic tool definition that sub-agents can reference.
+    #
+    # @param name [Symbol, String] tool name
+    # @param description [String, nil] tool description
+    # @param provider_mappings [Hash] provider-specific mappings
+    # @return [ToolDefinition]
+    def register_tool(name, description: nil, **provider_mappings)
+      @tool_registry.register(name, description: description, **provider_mappings)
+    end
+
+    # Register a named MCP server for later reference by sub-agents.
+    #
+    # @param name [Symbol, String] server name
+    # @param definition [Hash, McpServer, nil] server definition
+    # @param attributes [Hash] server attributes
+    # @return [McpServer]
+    def register_mcp_server(name, definition = nil, **attributes)
+      server = if definition.is_a?(McpServer)
+        definition
+      else
+        payload = (definition || attributes).dup
+        payload[:name] ||= name.to_s
+        McpServer.from_hash(payload)
+      end
+
+      @mcp_servers[name.to_sym] = server
+    end
+
+    # Resolve a named or inline sub-agent definition.
+    #
+    # @param reference [Symbol, String, Hash, SubAgentConfig, nil] sub-agent reference
+    # @return [SubAgentConfig, nil] resolved sub-agent config
+    def resolve_sub_agent(reference)
+      case reference
+      when nil
+        nil
+      when SubAgentConfig
+        reference
+      when Hash
+        SubAgentConfig.from_hash(reference)
+      else
+        @sub_agents.fetch(reference.to_sym) do
+          raise ConfigurationError, "Unknown sub-agent: #{reference}"
+        end
+      end
+    end
+
     # Register callback for token usage events
     #
     # @yield [TokenEvent] called when tokens are used
@@ -263,6 +355,67 @@ module AgentHarness
     end
   end
 
+  # Provider-agnostic tool definition used during sub-agent translation.
+  class ToolDefinition
+    attr_reader :name, :description, :provider_mappings
+
+    def initialize(name:, description: nil, provider_mappings: {})
+      @name = name.to_sym
+      @description = description
+      @provider_mappings = deep_dup(provider_mappings).each_with_object({}) do |(provider, value), mappings|
+        mappings[provider.to_sym] = value
+      end.freeze
+    end
+
+    def mapping_for(provider)
+      deep_dup(@provider_mappings[provider.to_sym])
+    end
+
+    def to_h
+      {name: @name, description: @description, provider_mappings: deep_dup(@provider_mappings)}
+    end
+
+    private
+
+    def deep_dup(value)
+      case value
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when Hash
+        value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+      else
+        value.dup
+      end
+    rescue TypeError
+      value
+    end
+  end
+
+  # Registry for canonical tool definitions referenced by sub-agents.
+  class ToolRegistry
+    def initialize
+      @tools = {}
+    end
+
+    def register(name, description: nil, **provider_mappings)
+      @tools[name.to_sym] = ToolDefinition.new(
+        name: name,
+        description: description,
+        provider_mappings: provider_mappings
+      )
+    end
+
+    def fetch(name)
+      @tools.fetch(name.to_sym) do
+        raise ConfigurationError, "Unknown tool: #{name}"
+      end
+    end
+
+    def registered?(name)
+      @tools.key?(name.to_sym)
+    end
+  end
+
   # Registry for event callbacks
   class CallbackRegistry
     def initialize

data/lib/agent_harness/mcp_config_loader.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module AgentHarness
+  class McpConfigLoader
+    ENV_VAR_PATTERN = /\$\{([A-Z0-9_]+)\}/
+
+    class << self
+      def load_file(path)
+        parsed = parse_file(path)
+        servers = parsed.is_a?(Hash) ? (parsed["servers"] || parsed[:servers] || parsed) : parsed
+
+        unless servers.is_a?(Array)
+          raise McpConfigurationError,
+            "MCP config file must contain a top-level servers array"
+        end
+
+        servers.map do |server|
+          McpServer.from_hash(interpolate_env(server))
+        end
+      end
+
+      private
+
+      def parse_file(path)
+        ext = File.extname(path).downcase
+        content = File.read(path)
+
+        case ext
+        when ".json"
+          JSON.parse(content)
+        when ".yml", ".yaml"
+          YAML.safe_load(content, aliases: false) || {}
+        else
+          raise McpConfigurationError,
+            "Unsupported MCP config file format '#{ext}'. Use .json, .yml, or .yaml"
+        end
+      rescue Errno::ENOENT => e
+        raise McpConfigurationError, "MCP config file not found: #{e.message}"
+      rescue JSON::ParserError, Psych::SyntaxError => e
+        raise McpConfigurationError, "Failed to parse MCP config file: #{e.message}"
+      end
+
+      def interpolate_env(value)
+        case value
+        when Array
+          value.map { |entry| interpolate_env(entry) }
+        when Hash
+          value.each_with_object({}) do |(key, entry), memo|
+            memo[key] = interpolate_env(entry)
+          end
+        when String
+          value.gsub(ENV_VAR_PATTERN) { ENV.fetch(Regexp.last_match(1), "") }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/mcp_config_translator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module McpConfigTranslator
+    module_function
+
+    def for_provider(provider, mcp_servers)
+      servers = normalize_servers(mcp_servers)
+
+      case provider.to_sym
+      when :anthropic, :claude, :claude_code
+        translate_for_claude(servers)
+      when :codex
+        translate_for_codex(servers)
+      when :openai
+        translate_for_openai(servers)
+      else
+        servers.map(&:to_h)
+      end
+    end
+
+    def normalize_servers(mcp_servers)
+      Array(mcp_servers).map do |server|
+        case server
+        when McpServer
+          server
+        when Hash
+          McpServer.from_hash(server)
+        else
+          raise McpConfigurationError, "MCP server must be a Hash or McpServer, got #{server.class}"
+        end
+      end
+    end
+
+    def translate_for_claude(mcp_servers)
+      {
+        mcpServers: mcp_servers.each_with_object({}) do |server, memo|
+          entry = server.stdio? ? {command: server.command} : {url: server.url}
+          entry[:args] = server.args if server.stdio? && !server.args.empty?
+          entry[:env] = server.env unless server.env.empty?
+          entry[:headers] = server.headers if server.http? && !server.headers.empty?
+          memo[server.name] = entry
+        end
+      }
+    end
+
+    def translate_for_codex(mcp_servers)
+      {
+        mcp_servers: mcp_servers.each_with_object({}) do |server, memo|
+          entry = server.stdio? ? {command: server.command, transport: server.transport} : {url: server.url, transport: server.transport}
+          entry[:args] = server.args if server.stdio? && !server.args.empty?
+          entry[:env] = server.env unless server.env.empty?
+          entry[:headers] = server.headers if server.http? && !server.headers.empty?
+          memo[server.name] = entry
+        end
+      }
+    end
+
+    def translate_for_openai(mcp_servers)
+      mcp_servers.map do |server|
+        unless server.http?
+          raise McpTransportUnsupportedError.new(
+            "Provider 'openai' only supports remote MCP servers over HTTP/SSE (server: '#{server.name}')",
+            provider: :openai
+          )
+        end
+
+        unsupported_headers = server.headers.keys - ["Authorization"]
+        unless unsupported_headers.empty?
+          raise McpConfigurationError,
+            "OpenAI MCP translation only supports the Authorization header (server: '#{server.name}')"
+        end
+
+        tool = {
+          type: "mcp",
+          server_label: server.name,
+          server_url: server.url,
+          require_approval: "never"
+        }
+        tool[:authorization] = server.headers["Authorization"] if server.headers.key?("Authorization")
+        tool
+      end
+    end
+  end
+end

data/lib/agent_harness/mcp_server.rb

@@ -10,7 +10,8 @@ module AgentHarness
   #   McpServer.new(
   #     name: "filesystem",
   #     transport: "stdio",
-  #     command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+  #     command: "npx",
+  #     args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
   #     env: { "DEBUG" => "0" }
   #   )
   #
@@ -23,21 +24,24 @@ module AgentHarness
   class McpServer
     VALID_TRANSPORTS = %w[stdio http sse].freeze
 
-    attr_reader :name, :transport, :command, :args, :env, :url
+    attr_reader :name, :transport, :command, :args, :env, :url, :headers
 
     # @param name [String] unique name for this MCP server
     # @param transport [String] one of "stdio", "http", "sse"
-    # @param command [Array<String>, nil] command to launch (stdio only)
+    # @param command [String, Array<String>, nil] executable to launch (stdio only).
+    #   Arrays are accepted for backwards compatibility and normalized into
+    #   +command+ plus +args+.
     # @param args [Array<String>, nil] additional args for the command
     # @param env [Hash<String,String>, nil] environment variables for the server process
     # @param url [String, nil] URL for HTTP/SSE transport
-    def initialize(name:, transport:, command: nil, args: nil, env: nil, url: nil)
+    # @param headers [Hash<String,String>, nil] HTTP headers for remote MCP servers
+    def initialize(name:, transport:, command: nil, args: nil, env: nil, url: nil, headers: nil)
       @name = name
       @transport = transport.to_s
-      @command = command
-      @args = args || []
+      @command, @args = normalize_command_and_args(command, args)
       @env = env || {}
       @url = url
+      @headers = headers || {}
 
       validate!
     end
@@ -63,7 +67,8 @@ module AgentHarness
         command: hash[:command],
         args: hash[:args],
         env: hash[:env],
-        url: hash[:url]
+        url: hash[:url],
+        headers: hash[:headers]
       )
     end
 
@@ -75,6 +80,12 @@ module AgentHarness
       %w[http sse].include?(@transport)
     end
 
+    def command_argv
+      return [] unless stdio?
+
+      [@command, *@args]
+    end
+
     # Check if the MCP server is reachable based on its transport type.
     #
     # For stdio servers, checks that a command is present.
@@ -101,6 +112,7 @@ module AgentHarness
         h[:args] = @args unless @args.empty?
       else
         h[:url] = @url
+        h[:headers] = @headers unless @headers.empty?
       end
       h[:env] = @env unless @env.empty?
       h
@@ -118,6 +130,7 @@ module AgentHarness
 
       validate_args!
       validate_env!
+      validate_headers!
       validate_stdio! if stdio?
       validate_http! if http?
       validate_no_stdio_only_fields_on_http! if http?
@@ -137,15 +150,17 @@ module AgentHarness
         "MCP server '#{@name}' env must be a Hash with String keys and values"
     end
 
-    def validate_stdio!
-      if @command.nil? || !@command.is_a?(Array) || @command.empty?
-        raise McpConfigurationError,
-          "MCP server '#{@name}' with stdio transport requires a non-empty command array"
-      end
+    def validate_headers!
+      return if @headers.is_a?(Hash) && @headers.keys.all? { |k| k.is_a?(String) } && @headers.values.all? { |v| v.is_a?(String) }
 
-      unless @command.all? { |c| c.is_a?(String) }
+      raise McpConfigurationError,
+        "MCP server '#{@name}' headers must be a Hash with String keys and values"
+    end
+
+    def validate_stdio!
+      if @command.nil? || !@command.is_a?(String) || @command.strip.empty?
         raise McpConfigurationError,
-          "MCP server '#{@name}' command must contain only strings"
+          "MCP server '#{@name}' with stdio transport requires a non-empty command string"
       end
 
       return if @url.nil?
@@ -173,6 +188,17 @@ module AgentHarness
         "MCP server '#{@name}' with #{@transport} transport should not have args (args are only valid for stdio)"
     end
 
+    def normalize_command_and_args(command, args)
+      normalized_args = args || []
+      return [command, normalized_args] unless command.is_a?(Array)
+
+      unless normalized_args.is_a?(Array)
+        return [command.first, normalized_args]
+      end
+
+      [command.first, command[1..] + normalized_args]
+    end
+
     def http_ping_ok?(timeout: 5)
       require "net/http"
       uri = URI.parse(@url)

data/lib/agent_harness/providers/anthropic.rb

@@ -15,6 +15,7 @@ module AgentHarness
     #   response = provider.send_message(prompt: "Hello!")
     class Anthropic < Base
       include RateLimitResetParsing
+      include McpConfigFileSupport
 
       # Model name pattern for Anthropic Claude models
       MODEL_PATTERN = /^claude-[\d.-]+-(?:opus|sonnet|haiku)(?:-\d{8})?$/i
@@ -756,85 +757,8 @@ module AgentHarness
         servers
       end
 
-      def write_mcp_config_file(mcp_servers, working_dir: nil)
-        require "tempfile"
-        require "tmpdir"
-        require "securerandom"
-
-        config = build_claude_mcp_config(mcp_servers)
-        config_json = JSON.generate(config)
-
-        if @executor.is_a?(DockerCommandExecutor)
-          # When running inside a Docker container, write the config file
-          # inside the container so the CLI process can read it.
-          # Track the path so cleanup_mcp_tempfiles! can remove it after execution.
-          container_path = "/tmp/agent_harness_mcp_#{SecureRandom.hex(8)}.json"
-          result = @executor.execute(
-            ["sh", "-c", "cat > #{container_path}"],
-            stdin_data: config_json,
-            timeout: 5
-          )
-          unless result.success?
-            raise McpConfigurationError,
-              "Failed to write MCP config inside container: #{result.stderr}"
-          end
-
-          @mcp_docker_config_paths ||= []
-          @mcp_docker_config_paths << container_path
-
-          container_path
-        else
-          dir = working_dir || Dir.tmpdir
-          file = Tempfile.new(["agent_harness_mcp_", ".json"], dir)
-          file.write(config_json)
-          file.close
-
-          # Hold a reference so the Tempfile is not garbage-collected (and
-          # therefore deleted) before the CLI process reads it.
-          # Cleaned up by cleanup_mcp_tempfiles! after execution.
-          @mcp_config_tempfiles ||= []
-          @mcp_config_tempfiles << file
-
-          file.path
-        end
-      end
-
-      def build_claude_mcp_config(mcp_servers)
-        servers = {}
-        mcp_servers.each do |server|
-          h = if server.stdio?
-            entry = {command: server.command.first}
-            remaining_args = server.command[1..] + server.args
-            entry[:args] = remaining_args unless remaining_args.empty?
-            entry
-          else
-            {url: server.url}
-          end
-          h[:env] = server.env unless server.env.empty?
-          servers[server.name] = h
-        end
-        {mcpServers: servers}
-      end
-
-      def cleanup_mcp_tempfiles!
-        if @mcp_config_tempfiles
-          @mcp_config_tempfiles.each do |file|
-            file.close unless file.closed?
-            file.unlink
-          rescue
-            nil
-          end
-          @mcp_config_tempfiles = nil
-        end
-
-        if @mcp_docker_config_paths
-          @mcp_docker_config_paths.each do |path|
-            @executor.execute(["rm", "-f", path], timeout: 5)
-          rescue
-            nil
-          end
-          @mcp_docker_config_paths = nil
-        end
+      def mcp_provider_key
+        :anthropic
       end
 
       def build_tool_control_flags(tools_option, skip_permission_mode: false)

data/lib/agent_harness/providers/base.rb

@@ -126,6 +126,8 @@ module AgentHarness
 
         # Coerce provider_runtime from Hash if needed
         options = normalize_provider_runtime(options)
+        options = normalize_sub_agent(options)
+        prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])
 
         # Normalize and validate MCP servers
         options = normalize_mcp_servers(options)
@@ -210,6 +212,7 @@ module AgentHarness
         end
 
         options = normalize_provider_runtime(options)
+        options = normalize_sub_agent(options)
         runtime = options[:provider_runtime]
         conversation ||= messages
         raise ArgumentError, "conversation or messages is required" unless conversation
@@ -217,6 +220,7 @@ module AgentHarness
 
         transport = resolve_chat_transport(options)
         messages = format_messages_for_transport(conversation, transport)
+        messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
         transport_opts = chat_transport_options(runtime, options)
         transport_opts[:on_chat_chunk] = on_chat_chunk if on_chat_chunk
         transport_opts[:observer] = observer if observer
@@ -415,7 +419,13 @@ module AgentHarness
       end
 
       def normalize_mcp_servers(options)
-        servers = options[:mcp_servers]
+        if options.key?(:mcp_servers)
+          servers = options[:mcp_servers]
+        else
+          # Configuration stores mcp_servers as a Hash keyed by name; extract values.
+          config_servers = AgentHarness.configuration.mcp_servers
+          servers = config_servers.is_a?(Hash) ? config_servers.values : config_servers
+        end
         return options if servers.nil?
 
         unless servers.is_a?(Array)
@@ -446,6 +456,33 @@ module AgentHarness
         options.merge(mcp_servers: normalized)
       end
 
+      def normalize_sub_agent(options)
+        sub_agent = options[:sub_agent]
+        return options unless sub_agent
+
+        resolved = AgentHarness.configuration.resolve_sub_agent(sub_agent)
+        translated = SubAgentTranslator.for_provider(
+          self.class.provider_name,
+          resolved,
+          tool_registry: AgentHarness.configuration.tool_registry,
+          mcp_servers: AgentHarness.configuration.mcp_servers
+        )
+
+        options.merge(sub_agent: resolved, translated_sub_agent: translated)
+      end
+
+      def apply_sub_agent_to_prompt(prompt, translated_sub_agent)
+        return prompt unless translated_sub_agent
+
+        [translated_sub_agent[:runtime_instructions], "User task:\n#{prompt}"].join("\n\n")
+      end
+
+      def apply_sub_agent_to_messages(messages, translated_sub_agent)
+        return messages unless translated_sub_agent
+
+        [{role: "system", content: translated_sub_agent[:runtime_instructions]}] + messages
+      end
+
       def command_execution_options(options)
         execution_options = {
           idle_timeout: options[:idle_timeout],

data/lib/agent_harness/providers/codex.rb

@@ -9,6 +9,7 @@ module AgentHarness
     # Provides integration with the OpenAI Codex CLI tool.
     class Codex < Base
       include RateLimitResetParsing
+      include McpConfigFileSupport
 
       SUPPORTED_CLI_VERSION = "0.116.0"
       SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.117.0").freeze
@@ -186,7 +187,7 @@ module AgentHarness
           vision: false,
           tool_use: true,
           json_mode: false,
-          mcp: false,
+          mcp: true,
           dangerous_mode: true
         }
       end
@@ -199,6 +200,27 @@ module AgentHarness
 
       def cli_env_overrides = {"PAID_CODEX_SUBSCRIPTION_AUTH" => "1"}
 
+      def send_message(prompt:, **options)
+        super
+      ensure
+        cleanup_mcp_tempfiles!
+      end
+
+      def supports_mcp?
+        true
+      end
+
+      def supported_mcp_transports
+        %w[stdio http sse]
+      end
+
+      def build_mcp_flags(mcp_servers, working_dir: nil)
+        return [] if mcp_servers.empty?
+
+        config_path = write_mcp_config_file(mcp_servers, working_dir: working_dir)
+        ["--mcp-config", config_path]
+      end
+
       def test_command_overrides
         ["--skip-git-repo-check", "--output-last-message"]
       end
@@ -449,6 +471,11 @@ module AgentHarness
           cmd += sandbox_bypass_flags
         end
 
+        # Add MCP server flags (validated/normalized by Base#send_message)
+        if options[:mcp_servers]&.any?
+          cmd += build_mcp_flags(options[:mcp_servers])
+        end
+
         if options[:session]
           cmd += session_flags(options[:session])
         end
@@ -1259,6 +1286,10 @@ module AgentHarness
         config_dir = ENV["CODEX_CONFIG_DIR"] || File.expand_path("~/.codex")
         File.join(config_dir, "config.json")
       end
+
+      def mcp_provider_key
+        :codex
+      end
     end
   end
 end

data/lib/agent_harness/providers/mcp_config_file_support.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  module Providers
+    # Shared concern for writing and cleaning up MCP configuration tempfiles.
+    #
+    # Include this module in any provider that needs to write MCP config files
+    # for CLI processes. The including class must define an +mcp_provider_key+
+    # method that returns the symbol passed to +McpConfigTranslator.for_provider+.
+    module McpConfigFileSupport
+      def write_mcp_config_file(mcp_servers, working_dir: nil)
+        require "tempfile"
+        require "tmpdir"
+        require "securerandom"
+
+        config = McpConfigTranslator.for_provider(mcp_provider_key, mcp_servers)
+        config_json = JSON.generate(config)
+
+        if @executor.is_a?(DockerCommandExecutor)
+          # When running inside a Docker container, write the config file
+          # inside the container so the CLI process can read it.
+          # Track the path so cleanup_mcp_tempfiles! can remove it after execution.
+          container_path = "/tmp/agent_harness_mcp_#{SecureRandom.hex(8)}.json"
+          result = @executor.execute(
+            ["sh", "-c", "cat > #{container_path}"],
+            stdin_data: config_json,
+            timeout: 5
+          )
+          unless result.success?
+            raise McpConfigurationError,
+              "Failed to write MCP config inside container: #{result.stderr}"
+          end
+
+          @mcp_docker_config_paths ||= []
+          @mcp_docker_config_paths << container_path
+
+          container_path
+        else
+          dir = working_dir || Dir.tmpdir
+          file = Tempfile.new(["agent_harness_mcp_", ".json"], dir)
+          file.write(config_json)
+          file.close
+
+          # Hold a reference so the Tempfile is not garbage-collected (and
+          # therefore deleted) before the CLI process reads it.
+          # Cleaned up by cleanup_mcp_tempfiles! after execution.
+          @mcp_config_tempfiles ||= []
+          @mcp_config_tempfiles << file
+
+          file.path
+        end
+      end
+
+      def cleanup_mcp_tempfiles!
+        if @mcp_config_tempfiles
+          @mcp_config_tempfiles.each do |file|
+            file.close unless file.closed?
+            file.unlink
+          rescue
+            nil
+          end
+          @mcp_config_tempfiles = nil
+        end
+
+        if @mcp_docker_config_paths
+          @mcp_docker_config_paths.each do |path|
+            @executor.execute(["rm", "-f", path], timeout: 5)
+          rescue
+            nil
+          end
+          @mcp_docker_config_paths = nil
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/sub_agent_config.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Canonical provider-agnostic sub-agent definition.
+  class SubAgentConfig
+    attr_reader :name, :description, :instructions, :model, :tools, :mcp_servers
+    attr_reader :constraints, :handoff_conditions, :type, :sub_agents, :routing
+
+    def initialize(name:, description:, instructions:, model: "default", tools: [],
+      mcp_servers: [], constraints: {}, handoff_conditions: [], type: nil,
+      sub_agents: [], routing: nil)
+      @name = normalize_name(name)
+      @description = validate_string!(:description, description)
+      @instructions = validate_string!(:instructions, instructions)
+      @model = normalize_model(model)
+      @tools = normalize_array(:tools, tools)
+      @mcp_servers = normalize_array(:mcp_servers, mcp_servers)
+      @constraints = normalize_hash(:constraints, constraints)
+      @handoff_conditions = normalize_array(:handoff_conditions, handoff_conditions)
+      @type = type&.to_sym
+      @sub_agents = normalize_array(:sub_agents, sub_agents)
+      @routing = routing.nil? ? nil : normalize_hash(:routing, routing)
+    end
+
+    def self.from_hash(hash)
+      unless hash.is_a?(Hash)
+        raise ConfigurationError, "Sub-agent definition must be a Hash, got #{hash.class}"
+      end
+
+      attrs = hash.each_with_object({}) do |(key, value), memo|
+        memo[key.to_sym] = value
+      end
+
+      %i[name description instructions].each do |field|
+        value = attrs[field]
+        next if value.is_a?(String) && !value.strip.empty?
+        next if value.is_a?(Symbol)
+
+        raise ConfigurationError, "#{field} is required"
+      end
+
+      new(**attrs)
+    end
+
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        instructions: @instructions,
+        model: @model,
+        tools: deep_dup(@tools),
+        mcp_servers: deep_dup(@mcp_servers),
+        constraints: deep_dup(@constraints),
+        handoff_conditions: deep_dup(@handoff_conditions),
+        type: @type,
+        sub_agents: deep_dup(@sub_agents),
+        routing: deep_dup(@routing)
+      }.compact
+    end
+
+    private
+
+    def normalize_name(name)
+      value = validate_string!(:name, name)
+      value.tr(" ", "_").to_sym
+    end
+
+    def normalize_model(model)
+      return "default" if model.nil?
+
+      validate_string!(:model, model)
+    end
+
+    def validate_string!(field, value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ConfigurationError, "#{field} must be a String or Symbol"
+      end
+
+      string = value.to_s.strip
+      raise ConfigurationError, "#{field} is required" if string.empty?
+
+      string
+    end
+
+    def normalize_array(field, value)
+      return [].freeze if value.nil?
+
+      unless value.is_a?(Array)
+        raise ConfigurationError, "#{field} must be an Array"
+      end
+
+      deep_dup(value).freeze
+    end
+
+    def normalize_hash(field, value)
+      return {}.freeze if value.nil?
+
+      unless value.is_a?(Hash)
+        raise ConfigurationError, "#{field} must be a Hash"
+      end
+
+      deep_dup(value).freeze
+    end
+
+    def deep_dup(value)
+      case value
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when Hash
+        value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+      else
+        value.dup
+      end
+    rescue TypeError
+      value
+    end
+  end
+end

data/lib/agent_harness/sub_agent_file_loader.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentHarness
+  # Loads canonical sub-agent definitions from YAML or Markdown files.
+  class SubAgentFileLoader
+    class << self
+      def load(path)
+        case File.extname(path).downcase
+        when ".yml", ".yaml"
+          load_yaml(path)
+        when ".md", ".markdown"
+          [load_markdown(path)]
+        else
+          raise ConfigurationError, "Unsupported sub-agent definition format: #{path}"
+        end
+      end
+
+      private
+
+      def load_yaml(path)
+        parsed = YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+        unless parsed.is_a?(Hash)
+          raise ConfigurationError, "YAML sub-agent definition must be a Hash"
+        end
+
+        agents = parsed["agents"] || parsed[:agents] || [parsed]
+        unless agents.is_a?(Array)
+          raise ConfigurationError, "YAML sub-agent definitions must provide an agents Array"
+        end
+
+        agents.map { |entry| SubAgentConfig.from_hash(entry) }
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid YAML in #{path}: #{e.message}"
+      end
+
+      def load_markdown(path)
+        content = File.read(path)
+        match = content.match(/\A---\s*\n(?<frontmatter>.*?)\n---\s*\n?(?<body>.*)\z/m)
+        raise ConfigurationError, "Markdown sub-agent definitions require YAML frontmatter" unless match
+
+        attrs = YAML.safe_load(match[:frontmatter], permitted_classes: [], aliases: false) || {}
+        unless attrs.is_a?(Hash)
+          raise ConfigurationError, "Markdown frontmatter must be a Hash"
+        end
+
+        attrs["instructions"] ||= match[:body].strip
+        SubAgentConfig.from_hash(attrs)
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid frontmatter in #{path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/agent_harness/sub_agent_translator.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentHarness
+  # Translates canonical sub-agent definitions into provider-specific formats.
+  module SubAgentTranslator
+    class << self
+      def for_provider(provider, sub_agent_config, tool_registry: AgentHarness.configuration.tool_registry,
+        mcp_servers: AgentHarness.configuration.mcp_servers)
+        config = normalize_sub_agent_config(sub_agent_config)
+        normalized_provider = normalize_provider(provider)
+        tools = resolve_tools(config.tools, provider: normalized_provider, tool_registry: tool_registry)
+        servers = resolve_mcp_servers(config.mcp_servers, mcp_servers: mcp_servers)
+
+        case normalized_provider
+        when :anthropic
+          translate_for_anthropic(config, tools: tools, mcp_servers: servers)
+        when :openai
+          translate_for_openai(config, tools: tools, mcp_servers: servers)
+        when :google
+          translate_for_google(config, tools: tools, mcp_servers: servers)
+        when :claude_code
+          translate_for_claude_code(config, tools: tools, mcp_servers: servers)
+        when :codex
+          translate_for_codex(config, tools: tools, mcp_servers: servers)
+        when :pi
+          translate_for_pi(config, tools: tools, mcp_servers: servers)
+        else
+          translate_generic(normalized_provider, config, tools: tools, mcp_servers: servers)
+        end
+      end
+
+      private
+
+      def normalize_sub_agent_config(sub_agent_config)
+        case sub_agent_config
+        when SubAgentConfig
+          sub_agent_config
+        when Hash
+          SubAgentConfig.from_hash(sub_agent_config)
+        else
+          raise ConfigurationError, "Sub-agent config must be a SubAgentConfig or Hash"
+        end
+      end
+
+      def normalize_provider(provider)
+        case provider.to_sym
+        when :claude then :anthropic
+        when :gemini then :google
+        else provider.to_sym
+        end
+      end
+
+      def resolve_tools(tool_refs, provider:, tool_registry:)
+        tool_refs.map do |tool|
+          case tool
+          when Symbol, String
+            mapping = tool_registry.fetch(tool).mapping_for(provider)
+            mapping.nil? ? tool.to_s : mapping
+          when Hash
+            deep_dup(tool)
+          else
+            raise ConfigurationError, "Unsupported tool reference #{tool.inspect} in sub-agent definition"
+          end
+        end
+      end
+
+      def resolve_mcp_servers(server_refs, mcp_servers:)
+        server_refs.map do |server|
+          resolved = case server
+          when McpServer
+            server
+          when Symbol, String
+            mcp_servers.fetch(server.to_sym) do
+              raise ConfigurationError, "Unknown MCP server: #{server}"
+            end
+          when Hash
+            McpServer.from_hash(server)
+          else
+            raise ConfigurationError, "Unsupported MCP server reference #{server.inspect} in sub-agent definition"
+          end
+
+          resolved.to_h
+        end
+      end
+
+      def translate_for_anthropic(config, tools:, mcp_servers:)
+        {
+          provider: :anthropic,
+          format: :agent_sdk,
+          agent: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_openai(config, tools:, mcp_servers:)
+        {
+          provider: :openai,
+          format: :responses,
+          assistant: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            metadata: {
+              mcp_servers: mcp_servers,
+              constraints: deep_dup(config.constraints)
+            }
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_google(config, tools:, mcp_servers:)
+        {
+          provider: :google,
+          format: :adk,
+          agent: {
+            name: config.name.to_s,
+            description: config.description,
+            instruction: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_claude_code(config, tools:, mcp_servers:)
+        frontmatter = {
+          "name" => config.name.to_s,
+          "description" => config.description,
+          "model" => config.model,
+          "tools" => tools,
+          "mcp_servers" => mcp_servers,
+          "constraints" => deep_dup(config.constraints)
+        }.delete_if { |_key, value| value.respond_to?(:empty?) ? value.empty? : value.nil? }
+
+        {
+          provider: :claude_code,
+          format: :markdown,
+          content: build_markdown_definition(frontmatter, config.instructions),
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_codex(config, tools:, mcp_servers:)
+        {
+          provider: :codex,
+          format: :delegated_prompt,
+          definition: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_for_pi(config, tools:, mcp_servers:)
+        frontmatter = {
+          "name" => config.name.to_s,
+          "description" => config.description,
+          "model" => config.model,
+          "tools" => tools,
+          "mcp_servers" => mcp_servers
+        }.delete_if { |_key, value| value.respond_to?(:empty?) ? value.empty? : value.nil? }
+
+        {
+          provider: :pi,
+          format: :skill_markdown,
+          content: build_markdown_definition(frontmatter, config.instructions),
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def translate_generic(provider, config, tools:, mcp_servers:)
+        {
+          provider: provider,
+          format: :generic,
+          definition: {
+            name: config.name.to_s,
+            description: config.description,
+            instructions: config.instructions,
+            model: config.model,
+            tools: tools,
+            mcp_servers: mcp_servers,
+            constraints: deep_dup(config.constraints)
+          },
+          runtime_instructions: runtime_instructions(config)
+        }
+      end
+
+      def runtime_instructions(config)
+        <<~TEXT.strip
+          Sub-agent role: #{config.name}
+          Description: #{config.description}
+
+          Follow these sub-agent instructions exactly:
+          #{config.instructions}
+        TEXT
+      end
+
+      def build_markdown_definition(frontmatter, instructions)
+        <<~MARKDOWN
+          ---
+          #{YAML.dump(frontmatter).sub(/\A---\s*\n/, "").strip}
+          ---
+          #{instructions}
+        MARKDOWN
+      end
+
+      def deep_dup(value)
+        case value
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        when Hash
+          value.each_with_object({}) { |(key, entry), copy| copy[key] = deep_dup(entry) }
+        else
+          value.dup
+        end
+      rescue TypeError
+        value
+      end
+    end
+  end
+end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.11.0"
+  VERSION = "0.11.2"
 end

data/lib/agent_harness.rb

@@ -77,6 +77,23 @@ module AgentHarness
       conductor.send_message(prompt, provider: provider, executor: executor, **options)
     end
 
+    # Resolve a canonical sub-agent definition by name or inline payload.
+    #
+    # @param reference [Symbol, String, Hash, SubAgentConfig]
+    # @return [SubAgentConfig]
+    def sub_agent(reference)
+      configuration.resolve_sub_agent(reference)
+    end
+
+    # Translate a canonical sub-agent definition into a provider-specific format.
+    #
+    # @param reference [Symbol, String, Hash, SubAgentConfig] sub-agent reference
+    # @param provider [Symbol, String] target provider
+    # @return [Hash] provider-specific sub-agent definition
+    def translate_sub_agent(reference, provider:)
+      SubAgentTranslator.for_provider(provider, sub_agent(reference))
+    end
+
     # Get a provider instance
     # @param name [Symbol] the provider name
     # @return [Providers::Base] the provider instance
@@ -261,6 +278,11 @@ end
 # Core components
 require_relative "agent_harness/errors"
 require_relative "agent_harness/mcp_server"
+require_relative "agent_harness/mcp_config_loader"
+require_relative "agent_harness/mcp_config_translator"
+require_relative "agent_harness/sub_agent_config"
+require_relative "agent_harness/sub_agent_file_loader"
+require_relative "agent_harness/sub_agent_translator"
 require_relative "agent_harness/provider_runtime"
 require_relative "agent_harness/execution_preparation"
 require_relative "agent_harness/configuration"
@@ -281,6 +303,7 @@ require_relative "agent_harness/providers/adapter"
 require_relative "agent_harness/providers/base"
 require_relative "agent_harness/providers/token_usage_parsing"
 require_relative "agent_harness/providers/rate_limit_reset_parsing"
+require_relative "agent_harness/providers/mcp_config_file_support"
 require_relative "agent_harness/providers/anthropic"
 require_relative "agent_harness/providers/aider"
 require_relative "agent_harness/providers/codex"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - Bart Agapinan
@@ -107,6 +107,8 @@ files:
 - lib/agent_harness/error_taxonomy.rb
 - lib/agent_harness/errors.rb
 - lib/agent_harness/execution_preparation.rb
+- lib/agent_harness/mcp_config_loader.rb
+- lib/agent_harness/mcp_config_translator.rb
 - lib/agent_harness/mcp_server.rb
 - lib/agent_harness/openai_compatible_transport.rb
 - lib/agent_harness/orchestration/circuit_breaker.rb
@@ -126,12 +128,16 @@ files:
 - lib/agent_harness/providers/gemini.rb
 - lib/agent_harness/providers/github_copilot.rb
 - lib/agent_harness/providers/kilocode.rb
+- lib/agent_harness/providers/mcp_config_file_support.rb
 - lib/agent_harness/providers/mistral_vibe.rb
 - lib/agent_harness/providers/opencode.rb
 - lib/agent_harness/providers/rate_limit_reset_parsing.rb
 - lib/agent_harness/providers/registry.rb
 - lib/agent_harness/providers/token_usage_parsing.rb
 - lib/agent_harness/response.rb
+- lib/agent_harness/sub_agent_config.rb
+- lib/agent_harness/sub_agent_file_loader.rb
+- lib/agent_harness/sub_agent_translator.rb
 - lib/agent_harness/text_transport.rb
 - lib/agent_harness/token_tracker.rb
 - lib/agent_harness/version.rb