open_router_enhanced 2.2.0 → 2.2.1

data/docs/superpowers/plans/2026-06-27-openrouter-routing-features.md

@@ -1,913 +0,0 @@
-# OpenRouter Routing & Delegation Features Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add first-class, validated, ergonomic access to OpenRouter's Fusion, Subagent server tool, and Pareto Code Router features in the `open_router_enhanced` gem.
-
-**Architecture:** A thin ergonomic + validation layer on top of the existing `complete()` pipeline. A `Routing` mixin adds `fuse`/`pareto_complete` (which build `model:` + `plugins:` and delegate to `complete`); a `SubagentTool < Tool` subclass emits the `openrouter:subagent` server-tool shape; `Response#selected_model` exposes the resolved model. No changes to `complete()`'s core flow.
-
-**Tech Stack:** Ruby ≥ 3.2, RSpec, VCR + WebMock, Faraday. Spec/design at `docs/superpowers/specs/2026-06-27-openrouter-routing-features-design.md`.
-
-## Global Constraints
-
-- Ruby `>= 3.2.0`; do not add new runtime dependencies.
-- Module namespace is `OpenRouter`; gem name `open_router_enhanced`.
-- Files use `# frozen_string_literal: true`.
-- Fail-fast validation raises `ArgumentError` **before** any HTTP call.
-- VCR cassettes: record with `VCR_RECORD_NEW=1` only (never delete-and-rerecord — shared mutable on-disk model cache per project memory). Cassette dir: `spec/fixtures/vcr_cassettes/`. Default match: `method uri body`.
-- VCR integration recordings MUST use **cheap models only** (never the most expensive frontier models). Suggested cheap slugs below; if a slug is unavailable at record time, swap for another cheap/free model and update the spec's expected request body to match.
-- Server-tool shape for subagent: `{ type: "openrouter:subagent", parameters: {...} }` (no `function` key).
-- Plugin id strings: Fusion = `"fusion"`, Pareto = `"pareto-router"`. Router model aliases: `"openrouter/fusion"`, `"openrouter/pareto-code"`.
-
----
-
-### Task 1: `SubagentTool` server-tool class
-
-**Files:**
-- Create: `lib/open_router/subagent_tool.rb`
-- Modify: `lib/open_router.rb` (add require after line 21 `require_relative "open_router/tool"`)
-- Test: `spec/subagent_tool_spec.rb`
-
-**Interfaces:**
-- Consumes: `OpenRouter::Tool` (base class).
-- Produces: `OpenRouter::SubagentTool.new(model:, instructions: nil, max_completion_tokens: nil, temperature: nil, reasoning: nil)` with `#to_h => { type: "openrouter:subagent", parameters: {model:, ...}.compact }`. It is a `Tool`, so `serialize_tools` treats it via the `when Tool` branch.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/subagent_tool_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe OpenRouter::SubagentTool do
-  describe "#to_h" do
-    it "emits the openrouter:subagent server-tool shape with all fields" do
-      tool = described_class.new(
-        model: "z-ai/glm-5.2",
-        instructions: "Be concise.",
-        max_completion_tokens: 1024,
-        temperature: 0.2,
-        reasoning: { effort: "low" }
-      )
-
-      expect(tool.to_h).to eq(
-        type: "openrouter:subagent",
-        parameters: {
-          model: "z-ai/glm-5.2",
-          instructions: "Be concise.",
-          max_completion_tokens: 1024,
-          temperature: 0.2,
-          reasoning: { effort: "low" }
-        }
-      )
-    end
-
-    it "omits nil optional fields (compacted)" do
-      tool = described_class.new(model: "z-ai/glm-5.2")
-
-      expect(tool.to_h).to eq(
-        type: "openrouter:subagent",
-        parameters: { model: "z-ai/glm-5.2" }
-      )
-    end
-  end
-
-  describe "validation" do
-    it "raises ArgumentError when model is missing" do
-      expect { described_class.new(instructions: "hi") }
-        .to raise_error(ArgumentError, /model is required/)
-    end
-
-    it "raises ArgumentError when model is blank" do
-      expect { described_class.new(model: "  ") }
-        .to raise_error(ArgumentError, /model is required/)
-    end
-  end
-
-  it "is a Tool so it serializes through the tools array" do
-    tool = described_class.new(model: "z-ai/glm-5.2")
-    expect(tool).to be_a(OpenRouter::Tool)
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bundle exec rspec spec/subagent_tool_spec.rb`
-Expected: FAIL with `uninitialized constant OpenRouter::SubagentTool`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-Create `lib/open_router/subagent_tool.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require_relative "tool"
-
-module OpenRouter
-  # Represents the `openrouter:subagent` server tool, which lets an orchestrator
-  # model delegate self-contained subtasks to a cheaper worker model mid-generation.
-  #
-  # Unlike a function Tool, it serializes to the server-tool shape:
-  #   { type: "openrouter:subagent", parameters: { model:, instructions:, ... } }
-  #
-  # @example
-  #   sub = OpenRouter::SubagentTool.new(model: "z-ai/glm-5.2", instructions: "Be concise.")
-  #   client.complete(messages, model: "anthropic/claude-3.5-sonnet", tools: [sub])
-  class SubagentTool < Tool
-    SERVER_TOOL_TYPE = "openrouter:subagent"
-
-    def initialize(model:, instructions: nil, max_completion_tokens: nil,
-                   temperature: nil, reasoning: nil)
-      raise ArgumentError, "model is required for SubagentTool" if model.nil? || model.to_s.strip.empty?
-
-      @type = SERVER_TOOL_TYPE
-      @parameters_config = {
-        model: model,
-        instructions: instructions,
-        max_completion_tokens: max_completion_tokens,
-        temperature: temperature,
-        reasoning: reasoning
-      }.compact
-      # Intentionally skip Tool#validate_definition! (no function name/description).
-    end
-
-    def to_h
-      { type: @type, parameters: @parameters_config }
-    end
-
-    def name
-      @type
-    end
-
-    def description
-      "OpenRouter subagent server tool (worker: #{@parameters_config[:model]})"
-    end
-  end
-end
-```
-
-Add the require to `lib/open_router.rb` immediately after the `tool` require (line 21):
-
-```ruby
-require_relative "open_router/tool"
-require_relative "open_router/subagent_tool"
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `bundle exec rspec spec/subagent_tool_spec.rb`
-Expected: PASS (5 examples).
-
-- [ ] **Step 5: Verify it serializes through `complete` (hermetic, mocked post)**
-
-Append to `spec/subagent_tool_spec.rb` inside the top-level describe:
-
-```ruby
-  describe "serialization through Client#complete" do
-    let(:client) { OpenRouter::Client.new(access_token: "test-token") }
-    let(:mock_response) do
-      {
-        "id" => "chatcmpl-1",
-        "model" => "anthropic/claude-3.5-sonnet",
-        "choices" => [{ "message" => { "role" => "assistant", "content" => "done" }, "finish_reason" => "stop" }],
-        "usage" => { "prompt_tokens" => 1, "completion_tokens" => 1, "total_tokens" => 2 }
-      }
-    end
-
-    before do
-      # Keep the unit test hermetic: complete() calls warn_if_unsupported -> ModelRegistry.
-      allow(OpenRouter::ModelRegistry).to receive(:has_capability?).and_return(true)
-    end
-
-    it "passes the subagent tool through the tools array" do
-      sub = described_class.new(model: "z-ai/glm-5.2", instructions: "Be concise.")
-
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          tools: [{ type: "openrouter:subagent",
-                    parameters: { model: "z-ai/glm-5.2", instructions: "Be concise." } }]
-        )
-      ).and_return(mock_response)
-
-      client.complete([{ role: "user", content: "hi" }],
-                      model: "anthropic/claude-3.5-sonnet", tools: [sub])
-    end
-  end
-```
-
-Run: `bundle exec rspec spec/subagent_tool_spec.rb`
-Expected: PASS (6 examples).
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add lib/open_router/subagent_tool.rb lib/open_router.rb spec/subagent_tool_spec.rb
-git commit -m "feat: add SubagentTool for openrouter:subagent server tool"
-```
-
----
-
-### Task 2: `Routing` mixin with `pareto_complete`
-
-**Files:**
-- Create: `lib/open_router/routing.rb`
-- Modify: `lib/open_router.rb` (add require before `client` require at line 33)
-- Modify: `lib/open_router/client.rb` (require_relative + include the mixin)
-- Test: `spec/routing_spec.rb`
-
-**Interfaces:**
-- Consumes: `Client#complete(messages, options = nil, **kwargs)`.
-- Produces: `Client#pareto_complete(messages, min_coding_score: nil, **opts)` → delegates to `complete` with `model: "openrouter/pareto-code"` and a merged `pareto-router` plugin. Constants `OpenRouter::Routing::PARETO_CODE_MODEL` and `FUSION_MODEL`. Private helper `merge_plugin(opts_or_kwargs, plugin)` (used by Task 3 too).
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/routing_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe OpenRouter::Routing do
-  let(:client) { OpenRouter::Client.new(access_token: "test-token") }
-  let(:messages) { [{ role: "user", content: "Write a merge function." }] }
-  let(:mock_response) do
-    {
-      "id" => "chatcmpl-1",
-      "model" => "anthropic/claude-3.5-sonnet",
-      "choices" => [{ "message" => { "role" => "assistant", "content" => "ok" }, "finish_reason" => "stop" }],
-      "usage" => { "prompt_tokens" => 1, "completion_tokens" => 1, "total_tokens" => 2 }
-    }
-  end
-
-  describe "#pareto_complete" do
-    it "routes to openrouter/pareto-code with a pareto-router plugin" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          model: "openrouter/pareto-code",
-          plugins: [{ id: "pareto-router", min_coding_score: 0.8 }]
-        )
-      ).and_return(mock_response)
-
-      client.pareto_complete(messages, min_coding_score: 0.8)
-    end
-
-    it "omits min_coding_score when not given (server defaults apply)" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          model: "openrouter/pareto-code",
-          plugins: [{ id: "pareto-router" }]
-        )
-      ).and_return(mock_response)
-
-      client.pareto_complete(messages)
-    end
-
-    it "forwards extra options like temperature" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(model: "openrouter/pareto-code", temperature: 0.3)
-      ).and_return(mock_response)
-
-      client.pareto_complete(messages, min_coding_score: 0.5, temperature: 0.3)
-    end
-
-    it "merges into a caller-supplied plugins array without clobbering" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          plugins: [{ id: "web" }, { id: "pareto-router", min_coding_score: 0.7 }]
-        )
-      ).and_return(mock_response)
-
-      client.pareto_complete(messages, min_coding_score: 0.7, plugins: [{ id: "web" }])
-    end
-
-    it "raises ArgumentError when min_coding_score is out of range" do
-      expect { client.pareto_complete(messages, min_coding_score: 1.5) }
-        .to raise_error(ArgumentError, /min_coding_score/)
-      expect { client.pareto_complete(messages, min_coding_score: -0.1) }
-        .to raise_error(ArgumentError, /min_coding_score/)
-    end
-
-    it "raises ArgumentError when min_coding_score is not numeric" do
-      expect { client.pareto_complete(messages, min_coding_score: "high") }
-        .to raise_error(ArgumentError, /min_coding_score/)
-    end
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bundle exec rspec spec/routing_spec.rb`
-Expected: FAIL with `uninitialized constant OpenRouter::Routing` (or `undefined method pareto_complete`).
-
-- [ ] **Step 3: Write minimal implementation**
-
-Create `lib/open_router/routing.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-module OpenRouter
-  # Mixin providing ergonomic access to OpenRouter router/meta-model features
-  # (Fusion, Pareto Code Router). Builds the right model alias + plugin config
-  # and delegates to Client#complete.
-  module Routing
-    FUSION_MODEL = "openrouter/fusion"
-    PARETO_CODE_MODEL = "openrouter/pareto-code"
-
-    # Route to the cheapest code-capable model meeting a quality bar.
-    #
-    # @param min_coding_score [Float, nil] 0.0–1.0 (1.0 = best). Optional.
-    def pareto_complete(messages, min_coding_score: nil, **opts)
-      validate_min_coding_score!(min_coding_score)
-
-      plugin = { id: "pareto-router" }
-      plugin[:min_coding_score] = min_coding_score unless min_coding_score.nil?
-
-      kwargs = merge_plugin(opts, plugin)
-      complete(messages, model: PARETO_CODE_MODEL, **kwargs)
-    end
-
-    private
-
-    def validate_min_coding_score!(score)
-      return if score.nil?
-
-      unless score.is_a?(Numeric) && score >= 0.0 && score <= 1.0
-        raise ArgumentError, "min_coding_score must be a number between 0.0 and 1.0 (got #{score.inspect})"
-      end
-    end
-
-    # Merge a router plugin into any caller-supplied plugins, de-duped by :id.
-    def merge_plugin(opts, plugin)
-      existing = Array(opts[:plugins]).map { |p| p.transform_keys(&:to_sym) }
-      existing = existing.reject { |p| p[:id].to_s == plugin[:id].to_s }
-      opts.merge(plugins: existing + [plugin])
-    end
-  end
-end
-```
-
-Add require to `lib/open_router.rb` immediately before the `client` require (line 33):
-
-```ruby
-require_relative "open_router/routing"
-require_relative "open_router/client"
-```
-
-Modify `lib/open_router/client.rb` — add the require near the other mixin requires (after line 10 `require_relative "request_handler"`):
-
-```ruby
-require_relative "request_handler"
-require_relative "routing"
-```
-
-And add the include in the `Client` class body (after line 20 `include OpenRouter::RequestHandler`):
-
-```ruby
-    include OpenRouter::RequestHandler
-    include OpenRouter::Routing
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `bundle exec rspec spec/routing_spec.rb`
-Expected: PASS (6 examples).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/open_router/routing.rb lib/open_router/client.rb lib/open_router.rb spec/routing_spec.rb
-git commit -m "feat: add Routing mixin with pareto_complete"
-```
-
----
-
-### Task 3: `fuse` (Fusion) on the `Routing` mixin
-
-**Files:**
-- Modify: `lib/open_router/routing.rb`
-- Test: `spec/routing_spec.rb`
-
-**Interfaces:**
-- Consumes: `Client#complete`, `Routing#merge_plugin` (from Task 2).
-- Produces: `Client#fuse(messages, analysis_models: nil, judge: nil, preset: nil, max_tool_calls: nil, **opts)` → delegates to `complete` with `model: "openrouter/fusion"` and a merged `fusion` plugin `{ id: "fusion", analysis_models:, model: judge, preset:, max_tool_calls: }.compact`.
-
-- [ ] **Step 1: Write the failing test**
-
-Append a new describe block to `spec/routing_spec.rb`:
-
-```ruby
-  describe "#fuse" do
-    it "routes to openrouter/fusion with a fusion plugin (panel + judge)" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          model: "openrouter/fusion",
-          plugins: [{ id: "fusion",
-                      analysis_models: ["deepseek/deepseek-chat", "google/gemini-flash-1.5"],
-                      model: "deepseek/deepseek-chat" }]
-        )
-      ).and_return(mock_response)
-
-      client.fuse(messages,
-                  analysis_models: ["deepseek/deepseek-chat", "google/gemini-flash-1.5"],
-                  judge: "deepseek/deepseek-chat")
-    end
-
-    it "supports preset and max_tool_calls and omits nil fields" do
-      expect(client).to receive(:post).with(
-        path: "/chat/completions",
-        parameters: hash_including(
-          model: "openrouter/fusion",
-          plugins: [{ id: "fusion", preset: "general-budget", max_tool_calls: 4 }]
-        )
-      ).and_return(mock_response)
-
-      client.fuse(messages, preset: "general-budget", max_tool_calls: 4)
-    end
-
-    it "raises ArgumentError when analysis_models is empty" do
-      expect { client.fuse(messages, analysis_models: []) }
-        .to raise_error(ArgumentError, /analysis_models/)
-    end
-
-    it "raises ArgumentError when analysis_models has more than 8 entries" do
-      expect { client.fuse(messages, analysis_models: Array.new(9, "a/b")) }
-        .to raise_error(ArgumentError, /analysis_models/)
-    end
-
-    it "raises ArgumentError when max_tool_calls is out of range" do
-      expect { client.fuse(messages, max_tool_calls: 0) }
-        .to raise_error(ArgumentError, /max_tool_calls/)
-      expect { client.fuse(messages, max_tool_calls: 17) }
-        .to raise_error(ArgumentError, /max_tool_calls/)
-    end
-  end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bundle exec rspec spec/routing_spec.rb -e "#fuse"`
-Expected: FAIL with `undefined method 'fuse'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `lib/open_router/routing.rb`, add `fuse` above the `private` keyword (after `pareto_complete`):
-
-```ruby
-    # Fan a prompt out to a panel of models and synthesize one answer.
-    # NOTE: Fusion costs ~4–5x a single completion (panel calls + judge).
-    #
-    # @param analysis_models [Array<String>, nil] 1–8 panel model ids.
-    # @param judge [String, nil] synthesis model id (defaults to the fusion model server-side).
-    # @param preset [String, Symbol, nil] curated panel slug (e.g. "general-budget").
-    # @param max_tool_calls [Integer, nil] 1–16.
-    def fuse(messages, analysis_models: nil, judge: nil, preset: nil, max_tool_calls: nil, **opts)
-      validate_analysis_models!(analysis_models)
-      validate_max_tool_calls!(max_tool_calls)
-
-      plugin = {
-        id: "fusion",
-        analysis_models: analysis_models,
-        model: judge,
-        preset: preset&.to_s,
-        max_tool_calls: max_tool_calls
-      }.compact
-
-      kwargs = merge_plugin(opts, plugin)
-      complete(messages, model: FUSION_MODEL, **kwargs)
-    end
-```
-
-And add these validators in the `private` section (after `validate_min_coding_score!`):
-
-```ruby
-    def validate_analysis_models!(models)
-      return if models.nil?
-
-      unless models.is_a?(Array) && (1..8).cover?(models.size) && models.all? { |m| m.is_a?(String) && !m.strip.empty? }
-        raise ArgumentError, "analysis_models must be an array of 1–8 model id strings (got #{models.inspect})"
-      end
-    end
-
-    def validate_max_tool_calls!(value)
-      return if value.nil?
-
-      unless value.is_a?(Integer) && (1..16).cover?(value)
-        raise ArgumentError, "max_tool_calls must be an integer between 1 and 16 (got #{value.inspect})"
-      end
-    end
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `bundle exec rspec spec/routing_spec.rb`
-Expected: PASS (11 examples total).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/open_router/routing.rb spec/routing_spec.rb
-git commit -m "feat: add fuse for OpenRouter Fusion router"
-```
-
----
-
-### Task 4: `Response#selected_model`
-
-**Files:**
-- Modify: `lib/open_router/response.rb`
-- Test: `spec/response_selected_model_spec.rb`
-
-**Interfaces:**
-- Consumes: `Response#raw_response` (indifferent-access hash).
-- Produces: `Response#selected_model` → `String, nil` (the resolved `model` field from the API response).
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/response_selected_model_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe OpenRouter::Response do
-  describe "#selected_model" do
-    it "returns the model the router actually resolved" do
-      response = described_class.new(
-        "model" => "anthropic/claude-3.5-sonnet",
-        "choices" => [{ "message" => { "role" => "assistant", "content" => "hi" } }]
-      )
-      expect(response.selected_model).to eq("anthropic/claude-3.5-sonnet")
-    end
-
-    it "returns nil when the response has no model field" do
-      response = described_class.new("choices" => [])
-      expect(response.selected_model).to be_nil
-    end
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bundle exec rspec spec/response_selected_model_spec.rb`
-Expected: FAIL with `undefined method 'selected_model'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `lib/open_router/response.rb`, add this method after the `keys` method (near the other delegators, before `# Tool calling methods`):
-
-```ruby
-    # The concrete model the API/router actually used for this response.
-    # Useful for Pareto, Auto, and Fusion routing ("which model answered?").
-    #
-    # @return [String, nil]
-    def selected_model
-      @raw_response["model"]
-    end
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `bundle exec rspec spec/response_selected_model_spec.rb`
-Expected: PASS (2 examples).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/open_router/response.rb spec/response_selected_model_spec.rb
-git commit -m "feat: add Response#selected_model for resolved router model"
-```
-
----
-
-### Task 5: VCR integration — Pareto Code Router (happy + real error)
-
-**Files:**
-- Create: `spec/vcr/pareto_spec.rb`
-- Create (recorded): `spec/fixtures/vcr_cassettes/pareto_basic.yml`, `spec/fixtures/vcr_cassettes/pareto_error.yml`
-
-**Interfaces:**
-- Consumes: `Client#pareto_complete`, `Response#selected_model`, `OpenRouter::ServerError`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/vcr/pareto_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe "OpenRouter Pareto Code Router", :vcr do
-  let(:client) { OpenRouter::Client.new(access_token: ENV["OPENROUTER_API_KEY"]) }
-  let(:messages) { [{ role: "user", content: "Write a Ruby method that merges two sorted arrays." }] }
-
-  it "routes to the cheapest code-capable model meeting the score",
-     vcr: { cassette_name: "pareto_basic" } do
-    response = client.pareto_complete(messages, min_coding_score: 0.5, max_tokens: 200)
-
-    expect(response).to be_a(OpenRouter::Response)
-    expect(response.content).to be_a(String)
-    expect(response.content).not_to be_empty
-    # The router resolves to a concrete model, surfaced via selected_model.
-    expect(response.selected_model).to be_a(String)
-    expect(response.selected_model).not_to eq("openrouter/pareto-code")
-  end
-
-  it "propagates a real API error for an invalid request",
-     vcr: { cassette_name: "pareto_error" } do
-    # Bypass client-side validation to capture genuine server-side rejection:
-    # a malformed pareto-router plugin value the API rejects.
-    expect do
-      client.complete(
-        messages,
-        model: "openrouter/pareto-code",
-        plugins: [{ id: "pareto-router", min_coding_score: "definitely-not-a-number" }],
-        max_tokens: 50
-      )
-    end.to raise_error(OpenRouter::ServerError)
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails (no cassette yet)**
-
-Run: `bundle exec rspec spec/vcr/pareto_spec.rb`
-Expected: FAIL — VCR raises because no cassette exists and default record mode `:once` will try a live call without a key in CI, or (locally) records. To control recording explicitly, proceed to Step 3.
-
-- [ ] **Step 3: Record the cassettes against the live API (cheap model)**
-
-Run (requires `OPENROUTER_API_KEY` in env / `.env`):
-
-```bash
-VCR_RECORD_NEW=1 bundle exec rspec spec/vcr/pareto_spec.rb
-```
-
-Then inspect `spec/fixtures/vcr_cassettes/pareto_basic.yml`:
-- Confirm the recorded **request body** contains `"plugins":[{"id":"pareto-router","min_coding_score":0.5}]` and `"model":"openrouter/pareto-code"`.
-- If the live API expects `min_coding_score` elsewhere (e.g. top-level) or a different plugin id, update `lib/open_router/routing.rb` and the Task 2 unit spec to match reality, re-run unit specs green, then re-record with `VCR_RECORD_NEW=1`.
-- Confirm `pareto_error.yml` recorded a non-2xx response that the gem maps to `ServerError`. If the gem returns a 200 with an error body instead, adjust the test expectation to assert on the error surfaced in the response per the gem's actual error handling (check `request_handler.rb`), keeping the assertion truthful to recorded behavior.
-
-- [ ] **Step 4: Replay to verify green (cassette mode)**
-
-Run: `CI=true bundle exec rspec spec/vcr/pareto_spec.rb`
-Expected: PASS (2 examples), replaying cassettes with record mode `:none`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add spec/vcr/pareto_spec.rb spec/fixtures/vcr_cassettes/pareto_basic.yml spec/fixtures/vcr_cassettes/pareto_error.yml
-git commit -m "test: VCR integration for pareto_complete (happy + error)"
-```
-
----
-
-### Task 6: VCR integration — Subagent server tool
-
-**Files:**
-- Create: `spec/vcr/subagent_spec.rb`
-- Create (recorded): `spec/fixtures/vcr_cassettes/subagent_basic.yml`
-
-**Interfaces:**
-- Consumes: `OpenRouter::SubagentTool`, `Client#complete`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/vcr/subagent_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe "OpenRouter Subagent server tool", :vcr do
-  let(:client) { OpenRouter::Client.new(access_token: ENV["OPENROUTER_API_KEY"]) }
-
-  it "lets an orchestrator delegate to a cheap worker model",
-     vcr: { cassette_name: "subagent_basic" } do
-    sub = OpenRouter::SubagentTool.new(
-      model: "deepseek/deepseek-chat",
-      instructions: "Complete the task exactly as described. Be concise.",
-      max_completion_tokens: 256
-    )
-
-    response = client.complete(
-      [
-        { role: "system", content: "You are an orchestrator. Delegate routine subtasks to your subagent tool." },
-        { role: "user", content: "Summarize in one sentence: Ruby 3.2 added data classes and improved YJIT." }
-      ],
-      # Use a cheap orchestrator too; it must support tool calling.
-      model: "openai/gpt-4o-mini",
-      tools: [sub],
-      tool_choice: "auto",
-      max_tokens: 300
-    )
-
-    expect(response).to be_a(OpenRouter::Response)
-    expect(response.content).to be_a(String)
-    expect(response.content).not_to be_empty
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails (no cassette)**
-
-Run: `bundle exec rspec spec/vcr/subagent_spec.rb`
-Expected: FAIL — no cassette recorded yet.
-
-- [ ] **Step 3: Record against the live API (cheap orchestrator + worker)**
-
-Run:
-
-```bash
-VCR_RECORD_NEW=1 bundle exec rspec spec/vcr/subagent_spec.rb
-```
-
-Inspect `spec/fixtures/vcr_cassettes/subagent_basic.yml`:
-- Confirm the request body `tools` array contains `{"type":"openrouter:subagent","parameters":{"model":"deepseek/deepseek-chat",...}}`.
-- If the live API rejects the orchestrator model for server tools or names the parameters differently, adjust `lib/open_router/subagent_tool.rb` + the Task 1 unit spec to match, re-run unit specs green, then re-record.
-- If the chosen cheap models are unavailable, swap for other cheap/free models and update the spec + re-record.
-
-- [ ] **Step 4: Replay to verify green**
-
-Run: `CI=true bundle exec rspec spec/vcr/subagent_spec.rb`
-Expected: PASS (1 example).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add spec/vcr/subagent_spec.rb spec/fixtures/vcr_cassettes/subagent_basic.yml
-git commit -m "test: VCR integration for SubagentTool delegation"
-```
-
----
-
-### Task 7: VCR integration — Fusion (cheap panel)
-
-**Files:**
-- Create: `spec/vcr/fusion_spec.rb`
-- Create (recorded): `spec/fixtures/vcr_cassettes/fusion_basic.yml`
-
-**Interfaces:**
-- Consumes: `Client#fuse`, `Response#selected_model`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `spec/vcr/fusion_spec.rb`:
-
-```ruby
-# frozen_string_literal: true
-
-require "spec_helper"
-
-RSpec.describe "OpenRouter Fusion router", :vcr do
-  let(:client) { OpenRouter::Client.new(access_token: ENV["OPENROUTER_API_KEY"]) }
-  let(:messages) { [{ role: "user", content: "In one short paragraph, what is the CAP theorem?" }] }
-
-  it "fuses a budget panel into a single synthesized answer",
-     vcr: { cassette_name: "fusion_basic" } do
-    response = client.fuse(
-      messages,
-      # Cheap panel + cheap judge — never frontier models.
-      analysis_models: ["deepseek/deepseek-chat", "google/gemini-flash-1.5"],
-      judge: "deepseek/deepseek-chat",
-      max_tokens: 300
-    )
-
-    expect(response).to be_a(OpenRouter::Response)
-    expect(response.content).to be_a(String)
-    expect(response.content).not_to be_empty
-  end
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails (no cassette)**
-
-Run: `bundle exec rspec spec/vcr/fusion_spec.rb`
-Expected: FAIL — no cassette recorded yet.
-
-- [ ] **Step 3: Record against the live API (cheap panel — note ~4–5x cost)**
-
-Run:
-
-```bash
-VCR_RECORD_NEW=1 bundle exec rspec spec/vcr/fusion_spec.rb
-```
-
-Inspect `spec/fixtures/vcr_cassettes/fusion_basic.yml`:
-- Confirm request body `plugins` contains `{"id":"fusion","analysis_models":[...],"model":"deepseek/deepseek-chat"}`.
-- **Pin the flagged field name:** if the live API uses `models` instead of `analysis_models` (or a different judge key), update `lib/open_router/routing.rb`'s `fuse` plugin hash + the Task 3 unit spec to match, re-run unit specs green, then re-record.
-- Keep `max_tokens` modest to bound cost.
-
-- [ ] **Step 4: Replay to verify green**
-
-Run: `CI=true bundle exec rspec spec/vcr/fusion_spec.rb`
-Expected: PASS (1 example).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add spec/vcr/fusion_spec.rb spec/fixtures/vcr_cassettes/fusion_basic.yml
-git commit -m "test: VCR integration for fuse (Fusion router, budget panel)"
-```
-
----
-
-### Task 8: Docs + version bump to 2.2.0
-
-**Files:**
-- Modify: `lib/open_router/version.rb`
-- Modify: `README.md` (add a "Routing & Delegation" section)
-- Modify: `CHANGELOG.md` if present (check first; create entry under a new `## 2.2.0` heading only if the file exists)
-
-**Interfaces:** none (release task).
-
-- [ ] **Step 1: Confirm the full suite is green first**
-
-Run: `CI=true bundle exec rspec`
-Expected: PASS (entire suite, cassettes replayed in `:none` mode). Fix any failures before bumping.
-
-- [ ] **Step 2: Run the linter**
-
-Run: `bundle exec rubocop lib/open_router/routing.rb lib/open_router/subagent_tool.rb lib/open_router/response.rb`
-Expected: no offenses (auto-correct with `-a` if safe, re-run specs after).
-
-- [ ] **Step 3: Bump the version**
-
-Edit `lib/open_router/version.rb` — change the version constant to `"2.2.0"`.
-
-- [ ] **Step 4: Add README usage section**
-
-Add to `README.md` (under existing feature docs) — show real usage and the fusion cost note:
-
-```markdown
-## Routing & Delegation
-
-### Fusion — multi-model synthesis
-```ruby
-# Fan out to a budget panel and synthesize one answer.
-# Note: Fusion costs ~4–5x a single completion (panel + judge).
-response = client.fuse(messages,
-  analysis_models: ["deepseek/deepseek-chat", "google/gemini-flash-1.5"],
-  judge: "deepseek/deepseek-chat")
-response.selected_model # => the model that produced the synthesis
-```
-
-### Pareto Code Router — cheapest model over a quality bar
-```ruby
-response = client.pareto_complete(messages, min_coding_score: 0.8)
-response.selected_model # => e.g. "anthropic/claude-3.5-sonnet"
-```
-
-### Subagent — delegate subtasks to a cheaper worker
-```ruby
-sub = OpenRouter::SubagentTool.new(model: "deepseek/deepseek-chat",
-                                   instructions: "Be concise.")
-response = client.complete(messages,
-  model: "openai/gpt-4o-mini", tools: [sub], tool_choice: "auto")
-```
-
-All three raise `ArgumentError` on invalid arguments and surface API errors via the
-standard error handling / `:on_error` callback.
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/open_router/version.rb README.md
-git commit -m "chore: docs + bump version to 2.2.0 for routing features"
-```
-
----
-
-## Self-Review
-
-**Spec coverage:**
-- Fusion → Task 3 (`fuse`) + Task 7 (VCR). ✓
-- Subagent → Task 1 (`SubagentTool`) + Task 6 (VCR). ✓
-- Pareto → Task 2 (`pareto_complete`) + Task 5 (VCR). ✓
-- `selected_model` → Task 4. ✓
-- Validation / fail-fast → Tasks 1, 2, 3 (ArgumentError specs). ✓
-- Error handling (real API error) → Task 5 (`pareto_error` cassette). ✓
-- Plugin merge (no clobber) → Task 2. ✓
-- Cheap models for cassettes → Tasks 5–7 (explicit). ✓
-- Version bump + docs → Task 8. ✓
-- Field-name uncertainty (`analysis_models`, `min_coding_score` placement) → record-and-reconcile steps in Tasks 5 & 7. ✓
-
-**Placeholder scan:** No TBD/TODO; all code shown in full; cassette "swap if unavailable" instructions are real recording guidance, not placeholders.
-
-**Type consistency:** `pareto_complete`, `fuse`, `SubagentTool#to_h`, `Response#selected_model`, `merge_plugin`, `FUSION_MODEL`/`PARETO_CODE_MODEL` used consistently across tasks. `merge_plugin` defined in Task 2, reused in Task 3. ✓