feat(delegate_task): per-subagent model/provider overrides + model observability plugin

Summary

Two related additions:

1. Per-subagent model/provider overrides — adds model and provider parameters to delegate_task, allowing the calling agent to route individual subagents (or each task in a batch) to a specific model, independent of delegation.model in config.

2. model_observability plugin v2 — verifies that requested models actually reach the subagent. Surfaces ground-truth routing data (requested vs actual model, mismatch warnings, auto-router resolutions, Pareto-router resolutions) directly in delegate_task results via transform_tool_result.

These two components are designed together: the override exposes the parameter, the plugin verifies it was honored.

Components

Three pieces that form a complete system:

Patch (tools/delegate_tool.py, run_agent.py) — exposes the capability. Adds model and provider to the delegate_task schema and threads them through _dispatch_delegate_task(). Without this, any model arg passed by the LLM is silently discarded.

Skill (skills/autonomous-ai-agents/subagent-model-routing/SKILL.md) — tells the agent how to use it. Defines the routing decision matrix: which models belong in which tier, which tasks warrant which tier, and when to specify a model pin vs. let the auto-router decide. The skill is what turns the new parameter from "available" to "used correctly."

Plugin (plugins/model_observability/) — verifies it worked. Intercepts every delegate_task call, compares requested vs. actual model for each subagent, and injects the result back into the tool output before the LLM sees it. If a pin was silently dropped, the agent knows immediately rather than discovering it through degraded output quality.

Motivation

_build_child_agent() already accepted model=... (used by cron/scheduler.py) but the parameter was never plumbed through the tool schema or dispatch path. The result: any model arg passed by the LLM was silently discarded, and every subagent inherited delegation.model from config regardless of what the caller specified.

The observability plugin was built specifically to detect this class of silent failure. On main (without this patch), the plugin reports a mismatch on every delegation — confirmed by live instrumentation. On this branch, it reports clean matches for explicit pins and correctly distinguishes router resolutions from override mismatches.

Rebase note (2026-04-26)

Rebased onto main after upstream merged:

• 48ecb98f — _dispatch_delegate_task() helper consolidating the two hardcoded dispatch sites this PR originally patched. We accepted that refactor entirely and add model=/provider= to the single dispatch method instead.
• 9c9d9b7d — FileStateRegistry for concurrent subagent write safety.

TestRunAgentDispatchForwarding updated to verify _dispatch_delegate_task() directly.

API

Single-agent override

{
  "model": "anthropic/claude-haiku-4.5",
  "goal": "..."
}

Batch — per-task overrides

{
  "model": "anthropic/claude-opus-4.7",  // default for tasks that do not specify
  "tasks": [
    {"goal": "...", "model": "anthropic/claude-haiku-4.5"},  // overrides default
    {"goal": "..."}                                           // uses default above
  ]
}

Routing through OpenRouter (multi-provider batch)

provider is resolved once per delegate_task call, so per-task provider routing is not supported. To route tasks to different providers in a single batch, use provider="openrouter" at the top level — OpenRouter accepts provider-prefixed model strings and handles the downstream routing:

{
  "provider": "openrouter",
  "tasks": [
    {"goal": "...", "model": "anthropic/claude-haiku-4.5"},
    {"goal": "...", "model": "x-ai/grok-4.1-fast"},
    {"goal": "...", "model": "google/gemini-2.5-flash"}
  ]
}

Router requests

Router-style model IDs are requests for a routing policy, not concrete model pins:

• openrouter/auto → report as auto_router_resolutions
• openrouter/pareto-code → report as pareto_router_resolutions

These are expected to return a different concrete backend model. That is not an override mismatch.

Precedence

1. Per-task model (batch only)
2. Top-level model argument
3. delegation.model from config.yaml
4. Parent agent inherit

Error behavior

Model slugs are not validated locally — an unrecognized slug passes through and the provider returns an opaque invalid-model error. The model_observability plugin will log the attempt regardless. The _warn_model_provider_mismatch() guard catches the most common misconfiguration (provider-prefixed model string used with a non-aggregator provider) and logs a warning before the call fires.

Model Observability Plugin v2

Design

Four hooks, one enforcement chain:

pre_tool_call — scoping anchor only (always returns None).
Before delegate_task executes, captures the current JSONL byte offset and whether a model pin was specified. Stored in a tool_call_id-keyed stash. This is not a warning hook — the framework only enforces block from pre_tool_call. Its sole purpose is to give transform_tool_result a precise log read boundary, preventing bleed from prior delegations in the same session. Stash entries evict after 120s TTL.

transform_tool_result — enrichment and soft enforcement.
After delegate_task returns, reads JSONL entries past the saved offset (scoped to this call only), computes requested-vs-actual per subagent, and injects an observability block before the result reaches the LLM:

✓ sa-0: anthropic/claude-haiku-4.5 → anthropic/claude-4.5-haiku-20251001 [MATCH]
⚠ sa-1: requested anthropic/claude-opus-4.7 → actual google/gemini-2.5-flash [MISMATCH — override silently dropped]
→ sa-2: no model specified → auto-router resolved to google/gemini-2.5-flash-lite
→ sa-3: pareto-router resolved to deepseek/deepseek-v4-pro-20260423

post_api_request — JSONL logging backbone.
Logs every LLM API call to ~/.hermes/logs/model_usage.jsonl. Read by the other hooks.

on_session_start — session boundary marker.
Writes a boundary record so log readers can distinguish gateway incarnations and session-scoped runs.

All failure modes (missing log, failed delegation, stale stash, bad args) degrade silently — the plugin never interrupts the agent loop.

Why pre_tool_call as a scoping anchor rather than filtering by session_id

Filtering by session + subagent type still returns all delegations from the session. A long-running session with multiple delegate_task calls would aggregate unrelated records. The byte-offset approach costs one stat() call and gives exact per-invocation scoping with no false positives.

Live verification (2026-05-03)

Tested end-to-end with the gateway running from this branch:

Same test on main (without this patch): all three tasks report MISMATCH — confirming the patch is the differentiator.

Pareto router verification (2026-05-13)

After upstream added the OpenRouter Pareto Code router, the plugin needed to treat openrouter/pareto-code as a router request rather than a concrete model pin.

Live smoke after gateway restart:

• Request: model="openrouter/pareto-code", provider="openrouter"
• Task id: sa-0-7780e3fa
• Actual backend: deepseek/deepseek-v4-pro-20260423
• Result: inline observability contains pareto_router_resolutions
• Result: no override_mismatches

Reader-script output agreed:

Pareto-router: yes → deepseek/deepseek-v4-pro-20260423 ×1

Tests

Original PR coverage:

• tests/plugins/test_model_observability_v2.py — plugin lifecycle, hook registration, scoping, enrichment, mismatch/auto-router behavior, log isolation, edge cases
• tests/tools/test_delegate.py — delegate coverage including credential resolution, model/provider overrides, mismatch guard, OpenRouter auto smoke, and dispatch forwarding

Latest verification after Pareto-router compatibility update:

python -m pytest -o addopts='' \
  tests/plugins/test_model_observability_v2.py \
  tests/tools/test_delegate_tool_observability.py -q
# 41 passed

python -m pytest -o addopts='' tests/plugins -q --tb=short
# 587 passed

Files changed

• tools/delegate_tool.py — schema fields, handler, _resolve_delegation_credentials() overrides, delegate_task() signature, observability enrichment helpers, router-aware inline metadata
• run_agent.py — model=/provider= forwarded through _dispatch_delegate_task()
• plugins/model_observability/__init__.py + plugin.yaml — v2 plugin, 4 hooks, auto/Pareto-router classification
• tests/plugins/test_model_observability_v2.py — plugin regression tests, including Pareto-router resolution behavior
• tests/tools/test_delegate.py — delegate model/provider coverage
• tests/tools/test_delegate_tool_observability.py — inline observability metadata regression tests
• scripts/refresh_openrouter_models.py — weekly model catalog maintenance script (price delta tracking, tier exclusivity validation)
• skills/autonomous-ai-agents/subagent-model-routing/SKILL.md — agent-optimized routing skill

Backwards compatibility

All new parameters are optional. No behavior change when omitted. Observability enrichment degrades gracefully when log is absent.

Router requests are explicitly treated as router requests: openrouter/auto and openrouter/pareto-code may return concrete backend model names without being classified as override failures.

Prior art

#3172 (ReqX), #6771 (GusBot69), and #12715 (ViFigueiredo) all attempt per-call model overrides and remain open. None have been rebased onto the _dispatch_delegate_task() dispatch refactor (48ecb98f) that landed in main after they were submitted — all three would have merge conflicts against current main on their current branches. This PR is the only open implementation rebased onto that refactor.

The skill's escalation patterns are adapted from #3172 — credit to ReqX for that framing.