diff --git a/strix/agents/factory.py b/strix/agents/factory.py index 334f4cfc6..542185f70 100644 --- a/strix/agents/factory.py +++ b/strix/agents/factory.py @@ -663,6 +663,7 @@ def build_strix_agent( system_prompt_context: dict[str, Any] | None = None, extra_tools: Sequence[Tool] | None = None, instructions_override: str | None = None, + model: str | None = None, ) -> SandboxAgent[Any]: """Build a SandboxAgent for either root or child use. @@ -675,6 +676,12 @@ def build_strix_agent( registered via ``register_agent_tools``. instructions_override: Use this verbatim as the system prompt instead of rendering the built-in scan prompt. + model: Per-agent model override. ``None`` (the default) leaves the + agent's own ``model`` unset, so it runs on the run-wide model + configured on ``RunConfig``. A non-``None`` value overrides that + for this agent only — every other agent in the scan is + unaffected. Used for deliberately spawning a "second opinion" + child on a different model; see ``strix.tools.agents_graph.tools.create_agent``. """ if instructions_override is not None: instructions = instructions_override @@ -720,7 +727,7 @@ def build_strix_agent( instructions=instructions, tools=tools, tool_use_behavior=_finish_tool_use_behavior, - model=None, + model=model, capabilities=[ Filesystem( configure_tools=_make_filesystem_configurator( @@ -755,7 +762,7 @@ def make_child_factory( without the graph tool knowing about runner internals. """ - def _factory(*, name: str, skills: list[str]) -> SandboxAgent[Any]: + def _factory(*, name: str, skills: list[str], model: str | None = None) -> SandboxAgent[Any]: return build_strix_agent( name=name, skills=skills, @@ -767,6 +774,7 @@ def make_child_factory( chat_completions_tools=chat_completions_tools, strict_tool_schemas=strict_tool_schemas, system_prompt_context=system_prompt_context, + model=model, ) return _factory diff --git a/strix/config/models.py b/strix/config/models.py index 3babbe37b..8dca45461 100644 --- a/strix/config/models.py +++ b/strix/config/models.py @@ -887,6 +887,29 @@ def is_known_openai_bare_model(model_name: str) -> bool: return bool(entry and entry.get("litellm_provider") == "openai") +def invalid_model_reason(model_name: str | None, *, api_base: str | None = None) -> str | None: + """Return why ``model_name`` is not a usable model string, or ``None`` if it is fine. + + Mirrors the CLI's hard-fail check in ``warm_up_llm`` (``strix.interface.main``): + empty is always invalid, and a bare name (no ``/`` prefix) must be a + known OpenAI model unless a custom ``LLM_API_BASE``/``api_base`` is configured, + since that could plausibly serve any bare name. This is a structural check only + — it says nothing about whether the model is a *good* choice (see + ``is_recommended_or_frontier_model`` for that, which is a warning, not a + rejection). + """ + name = (model_name or "").strip() + if not name: + return "model name is empty" + if "/" not in name and not is_known_openai_bare_model(name) and not api_base: + return ( + f"'{name}' is not a known OpenAI model. Bare names route to OpenAI by " + "default. If you meant a non-OpenAI provider, use the '/' " + "form, e.g. 'anthropic/claude-opus-4-7', 'deepseek/deepseek-v4-pro'." + ) + return None + + _ANTHROPIC_MODEL_MARKERS = ("anthropic", "claude", "sonnet", "opus", "haiku") diff --git a/strix/core/agents.py b/strix/core/agents.py index 4d3d65cc6..7afc36edf 100644 --- a/strix/core/agents.py +++ b/strix/core/agents.py @@ -160,6 +160,7 @@ class AgentCoordinator: *, task: str | None = None, skills: list[str] | None = None, + model: str | None = None, ) -> None: async with self._lock: self.statuses[agent_id] = "running" @@ -169,6 +170,7 @@ class AgentCoordinator: self.metadata[agent_id] = { "task": task or "", "skills": list(skills or []), + "model": model, } self.runtimes.setdefault(agent_id, AgentRuntime()) logger.info("agent.register %s (%s) parent=%s", agent_id, name, parent_id or "-") diff --git a/strix/core/execution.py b/strix/core/execution.py index dfcd39fa2..2ac115082 100644 --- a/strix/core/execution.py +++ b/strix/core/execution.py @@ -315,6 +315,7 @@ async def spawn_child_agent( task: str, skills: list[str], parent_history: list[Any], + model: str | None = None, event_sink: StreamEventSink | None = None, hooks: RunHooks[dict[str, Any]] | None = None, ) -> dict[str, Any]: @@ -323,13 +324,14 @@ async def spawn_child_agent( raise TypeError("Parent agent_id missing from context") child_id = uuid.uuid4().hex[:8] - child_agent = factory(name=name, skills=skills) + child_agent = factory(name=name, skills=skills, model=model) await coordinator.register( child_id, name, parent_id, task=task, skills=skills, + model=model, ) await _start_child_runner( @@ -345,6 +347,7 @@ async def spawn_child_agent( name=name, parent_id=parent_id, task=task, + model=model, initial_input=child_initial_input( name=name, child_id=child_id, @@ -414,7 +417,8 @@ async def respawn_subagents( ) child_skills = list(md.get("skills") or []) - child_agent = factory(name=name, skills=child_skills) + child_model = md.get("model") if isinstance(md.get("model"), str) else None + child_agent = factory(name=name, skills=child_skills, model=child_model) await _start_child_runner( parent_ctx=parent_ctx, coordinator=coordinator, @@ -428,6 +432,7 @@ async def respawn_subagents( name=name, parent_id=parent_id, task=str(md.get("task", "")), + model=child_model, initial_input=[], start_parked=start_parked, event_sink=event_sink, @@ -1001,6 +1006,7 @@ async def _start_child_runner( parent_id: str | None, task: str, initial_input: Any, + model: str | None = None, start_parked: bool = False, event_sink: StreamEventSink | None = None, hooks: RunHooks[dict[str, Any]] | None = None, @@ -1013,6 +1019,11 @@ async def _start_child_runner( child_ctx["agent_id"] = child_id child_ctx["parent_id"] = parent_id child_ctx["task"] = task + if model is not None: + # Lets ReportUsageHooks record/estimate this agent's cost against the + # model it actually runs on, not the run-wide default — see + # ``build_strix_agent``'s ``model`` override. + child_ctx["agent_model"] = model async def _child_loop() -> None: # A budget stop is a clean scan-wide shutdown, not a child failure: the diff --git a/strix/core/hooks.py b/strix/core/hooks.py index 21400c0b4..62f86db96 100644 --- a/strix/core/hooks.py +++ b/strix/core/hooks.py @@ -240,11 +240,14 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]): if not isinstance(agent_id, str) or not agent_id: agent_id = agent_name or "unknown" + agent_model = ctx.get("agent_model") + model = agent_model if isinstance(agent_model, str) and agent_model else self._model + try: report_state.record_sdk_usage( agent_id=agent_id, agent_name=agent_name, - model=self._model, + model=model, usage=response.usage, ) except Exception: diff --git a/strix/skills/coordination/root_agent.md b/strix/skills/coordination/root_agent.md index 28b47984b..925b4305d 100644 --- a/strix/skills/coordination/root_agent.md +++ b/strix/skills/coordination/root_agent.md @@ -100,6 +100,10 @@ Complex findings warrant specialized subagents: - Use message passing only when essential (requests/answers, critical handoffs) - Prefer batched updates over routine status messages +**Second Opinions** + +Every agent runs on the scan's configured model by default, but `create_agent` accepts an optional `model` override for the rare case where that isn't enough: deliberately re-reviewing already-covered surfaces (piling-up `needs_follow_up` entries, or a target under-covered relative to its size) with a differently-configured model, since different model families notice different things on the same input. This is not a general-purpose "pick a model for this agent" knob and nothing spawns it automatically — see the `scan_modes/second_opinion` skill before reaching for it. + ## Completion When all agents report completion: diff --git a/strix/skills/scan_modes/second_opinion.md b/strix/skills/scan_modes/second_opinion.md new file mode 100644 index 000000000..979a07ca0 --- /dev/null +++ b/strix/skills/scan_modes/second_opinion.md @@ -0,0 +1,44 @@ +--- +name: second-opinion +description: Deliberately re-review already-covered surfaces with a differently-configured model +--- + +# Second Opinion + +Every agent in a scan runs on the same model by default. That is the right default — it is predictable and it is what the operator configured — but different model families notice different things on the same input. A pass that already happened is not necessarily a pass that was thorough; a second, independent look from a different model can surface what the first one missed. This is a deliberate, operator-triggered capability, not something that fires on its own — nothing in Strix spawns a second-opinion agent automatically, and this skill does not ask you to either. + +## When to use this + +Reach for a second opinion when coverage on a scan that matters is thin or uncertain and there is still budget to spend on it: + +- `list_coverage(outcome="needs_follow_up")` is non-empty and piling up faster than it is being resolved — entries sitting open across multiple agents rather than one agent's temporary backlog. +- A target is large or high-value relative to how much of it has actually been exercised — e.g. a handful of endpoints marked `covered` on an API surface with dozens of routes. +- The scan is close to wrapping up and you (the root agent) judge that a fresh pass over what has already been reviewed is worth more than starting a new area from scratch. + +Do not reach for this to cover new ground — that is what an ordinary specialist agent is for. This is specifically for **re-examining surfaces someone already looked at**, with a model that might notice something the first pass didn't. + +Do not reach for this reflexively on every scan — it is another full agent's worth of tokens and time on top of the primary pass, and it needs a real driver (thin coverage on something that matters, not curiosity). + +## How to use this + +1. Call `list_coverage(outcome="needs_follow_up")` (and, if useful, look at what is marked `covered` on the target you're worried about) to build a concrete list of surfaces to re-check. A second opinion is only as good as the list of what it's being asked to re-examine — don't hand it a vague "look at the app again." +2. Call `create_agent` with `model` set to a different model string than the one this scan is running on, and a `task` that says explicitly this is a re-review, not fresh recon: + + ``` + create_agent( + name="Second Opinion: Auth Surface", + task=( + "Re-review these already-covered surfaces with fresh eyes: " + ". " + "The first pass marked these as needs_follow_up / covered but " + "coverage here is thin relative to the surface's size. Look for " + "anything the first pass could have missed, not new areas." + ), + model="anthropic/claude-opus-4-7", + skills=["auth"], + ) + ``` + +3. Treat its findings like any other subagent's: filed vulnerability reports and `update_coverage` calls on the entries it resolved. It reports back through the same `agent_finish` / completion-report flow as every other child. + +`model` accepts the same `/` strings as `STRIX_LLM` (e.g. `anthropic/claude-opus-4-7`, `openai/gpt-5.6`, `zai/glm-5.3`). Pick something meaningfully different from the scan's configured model — a second pass on the same model tends to repeat the same blind spots. diff --git a/strix/tools/agents_graph/tools.py b/strix/tools/agents_graph/tools.py index b7a17226a..692e4af88 100644 --- a/strix/tools/agents_graph/tools.py +++ b/strix/tools/agents_graph/tools.py @@ -12,6 +12,8 @@ from typing import Any, Literal, get_args from agents import RunContextWrapper, function_tool +from strix.config import load_settings +from strix.config.models import invalid_model_reason from strix.core.agents import Status, coordinator_from_context from strix.core.execution import notify_parent_on_terminal from strix.core.hooks import LLM_TURN_KEY @@ -595,6 +597,7 @@ async def create_agent( task: str, inherit_context: bool = True, skills: list[str] | None = None, + model: str | None = None, ) -> str: """Spawn a specialist child agent to run in parallel. @@ -640,6 +643,17 @@ async def create_agent( when starting a clean-slate task. skills: List of skill names (e.g. ``["xss", "sql_injection"]``). Max 5; prefer 1-3. + model: Optional. Leave unset — every child runs on the scan's + configured model by default. Set this only to deliberately get a + **second opinion** from a differently-configured model on + surfaces the scan has already reviewed (e.g. entries sitting at + ``needs_follow_up`` in ``list_coverage``, or a target you judge + under-covered relative to its size). This is not a general + "pick any model for this agent" knob — different model + families catch different things, so a second, independent pass + with fresh eyes can surface what the first pass missed. Accepts + the same ``/`` strings as ``STRIX_LLM`` + (e.g. ``"anthropic/claude-opus-4-7"``). """ inner = _ctx(ctx) coordinator = coordinator_from_context(inner) @@ -671,6 +685,16 @@ async def create_agent( default=str, ) + if model is not None: + api_base = load_settings().llm.api_base + model_error = invalid_model_reason(model, api_base=api_base) + if model_error: + return json.dumps( + {"success": False, "error": f"invalid model: {model_error}", "agent_id": None}, + ensure_ascii=False, + default=str, + ) + parent_history = list(ctx.turn_input) if inherit_context and ctx.turn_input else [] try: result = await spawner( @@ -679,6 +703,7 @@ async def create_agent( task=task, skills=skill_list, parent_history=parent_history, + model=model, ) except Exception as e: logger.exception("create_agent: scan runner failed to spawn child '%s'", name) diff --git a/tests/test_create_agent_model_override.py b/tests/test_create_agent_model_override.py new file mode 100644 index 000000000..33a60934f --- /dev/null +++ b/tests/test_create_agent_model_override.py @@ -0,0 +1,143 @@ +"""Tests for the optional per-agent ``model`` override on ``create_agent``. + +``create_agent`` normally spawns children on the scan's configured model. +``model`` lets the caller deliberately give one child a different model (a +"second opinion" specialist) without touching every other agent in the run. +These tests pin down the three contract points: omitting ``model`` must be a +no-op regression guard, a valid alternate model string must be threaded +through to the spawner unchanged, and an invalid model string must fail +cleanly instead of spawning anything or raising. +""" + +from __future__ import annotations + +import json +from typing import TYPE_CHECKING, Any, cast + +import pytest +from agents.tool_context import ToolContext + +import strix.tools.agents_graph.tools as agents_graph_tools +from strix.core.agents import AgentCoordinator +from strix.tools.agents_graph.tools import create_agent + + +if TYPE_CHECKING: + from collections.abc import Iterator + + +class _FakeLlmSettings: + def __init__(self, api_base: str | None = None) -> None: + self.api_base = api_base + + +class _FakeSettings: + def __init__(self, api_base: str | None = None) -> None: + self.llm = _FakeLlmSettings(api_base=api_base) + + +@pytest.fixture +def _no_api_base(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: + """Pin ``load_settings()`` so the bare-name validation path is deterministic.""" + + def _load_fake_settings() -> _FakeSettings: + return _FakeSettings() + + monkeypatch.setattr(agents_graph_tools, "load_settings", _load_fake_settings) + yield + + +async def _graph() -> AgentCoordinator: + coordinator = AgentCoordinator() + await coordinator.register("root", "strix", parent_id=None) + await coordinator.attach_runtime("root", resumable=False) + return coordinator + + +class _RecordingSpawner: + """Stand-in for the ``spawn_child_agent`` closure the runner puts in context.""" + + def __init__(self) -> None: + self.calls: list[dict[str, Any]] = [] + + async def __call__(self, **kwargs: Any) -> dict[str, Any]: + self.calls.append(kwargs) + return { + "success": True, + "agent_id": "child-1", + "name": kwargs.get("name"), + "parent_id": kwargs.get("parent_ctx", {}).get("agent_id"), + "message": "spawned", + } + + +async def _call_create_agent( + coordinator: AgentCoordinator, spawner: _RecordingSpawner, args: dict[str, Any] +) -> dict[str, Any]: + ctx = ToolContext( + context={ + "coordinator": coordinator, + "agent_id": "root", + "spawn_child_agent": spawner, + }, + tool_name=create_agent.name, + tool_call_id="call-1", + tool_arguments="{}", + ) + raw: str = await create_agent.on_invoke_tool(ctx, json.dumps(args)) + return cast("dict[str, Any]", json.loads(raw)) + + +@pytest.mark.asyncio +async def test_omitting_model_spawns_exactly_as_before(_no_api_base: None) -> None: + coordinator = await _graph() + spawner = _RecordingSpawner() + + result = await _call_create_agent( + coordinator, spawner, {"name": "Validator", "task": "check the thing"} + ) + + assert result["success"] is True + assert len(spawner.calls) == 1 + assert spawner.calls[0]["model"] is None + + +@pytest.mark.asyncio +async def test_valid_alternate_model_is_threaded_through_unchanged(_no_api_base: None) -> None: + coordinator = await _graph() + spawner = _RecordingSpawner() + + result = await _call_create_agent( + coordinator, + spawner, + { + "name": "Second Opinion", + "task": "re-review already-covered surfaces", + "model": "anthropic/claude-opus-4-7", + }, + ) + + assert result["success"] is True + assert len(spawner.calls) == 1 + assert spawner.calls[0]["model"] == "anthropic/claude-opus-4-7" + + +@pytest.mark.asyncio +async def test_invalid_model_string_returns_a_clean_error(_no_api_base: None) -> None: + coordinator = await _graph() + spawner = _RecordingSpawner() + + result = await _call_create_agent( + coordinator, + spawner, + { + "name": "Second Opinion", + "task": "re-review already-covered surfaces", + "model": "definitely-not-a-real-model", + }, + ) + + assert result["success"] is False + assert "invalid model" in result["error"] + assert result["agent_id"] is None + assert spawner.calls == []