feat(migration): phase 5 — root agent factory + entry point

Three new modules that wire Phases 0-4 into a runnable Strix scan:

- strix/agents/sdk_prompt.py: standalone Jinja-based system prompt
  renderer. Reuses the existing strix/agents/StrixAgent/system_prompt.
  jinja template (508 lines, the actual production prompt) so behavior
  parity with the legacy LLM._load_system_prompt is byte-identical.
  Skill resolution mirrors LLM._get_skills_to_load (caller skills →
  scan_modes/<mode> → whitebox pair, deduped). Fail-soft: template
  errors return empty string and log; agent construction must never
  blow up on prompt load.

- strix/agents/sdk_factory.py: build_strix_agent(name, skills, is_root)
  assembles an agents.Agent. Root carries finish_scan and stops there;
  child carries agent_finish and stops there (C4). Caido tools come
  from CaidoCapability automatically — we don't include them in
  _BASE_TOOLS to avoid double-registration when the SDK runtime merges
  capability tools. model=None so RunConfig drives the model alias
  through MultiProvider rather than the SDK default. make_child_factory
  returns a closure over scan-level config (scan_mode, is_whitebox,
  interactive, scope context) for ctx.context['agent_factory'] — the
  Phase 3 create_agent tool calls it with (name, skills) per child.

- strix/sdk_entry.py: run_strix_scan() — the top-level coroutine.
  Builds the bus, brings up (or reuses) a sandbox session via
  session_manager, builds the root Agent and the child factory, builds
  the per-agent context dict, registers the root in the bus, builds
  the RunConfig, calls Runner.run, and cleans up the session in a
  finally. Cancels descendants before re-raising any exception (C9).
  cleanup_on_exit toggle preserves the cached session for resume
  scenarios. _build_root_task and _build_scope_context preserve the
  legacy StrixAgent.execute_scan task formatting + scope context shape
  so the prompt template sees identical inputs.

Tests: 21 new tests (10 for factory + prompt, 11 for entry point).
Factory: root vs child tool list parity, finish_scan/agent_finish
placement, tool_use_behavior dict shape, Caido absence (capability-
provided), make_child_factory closure semantics. Entry point (all
mocked, no real Docker/LLM): wiring shape verification — context dict
carries every field downstream consumers read, session manager called
with correct scan_id, cleanup runs even on Runner.run failure,
cleanup skipped when disabled, scan_id auto-generation, scan-level
config (scan_mode, is_whitebox) flows into the factory. Task and scope
builders verified against the same shape as legacy.

Per-file ruff ignores added: TC002 on sdk_factory (Tool used at
runtime in _BASE_TOOLS tuple), TC003 + PLR0912 on sdk_entry (Path
runtime-imported; _build_root_task's per-target-type branches are
intentional and well-bounded).

strix/agents/sdk_factory.py

@@ -0,0 +1,221 @@
+"""build_strix_agent — assemble an ``agents.Agent`` for root or child runs.
+
+This is the keystone that links Phase 2's SDK function tools, Phase 3's
+graph tools, Phase 4's CaidoCapability, and the rendered Jinja prompt
+from :mod:`strix.agents.sdk_prompt` into a single ``agents.Agent``
+instance ready for ``Runner.run``.
+
+Two flavors:
+
+- **Root** (``is_root=True``): the top-level scan agent. Carries
+  ``finish_scan`` (terminates the scan), no ``agent_finish`` (that's
+  for subagents). ``tool_use_behavior`` stops on ``finish_scan`` so
+  the model can't accidentally keep talking after marking the scan
+  complete.
+
+- **Child** (``is_root=False``): subagents spawned by the
+  ``create_agent`` graph tool. Carries ``agent_finish``, no
+  ``finish_scan``. ``tool_use_behavior`` stops on ``agent_finish``
+  (C4 — without this, the SDK loop would keep going to ``max_turns``
+  even after the child reported back to its parent).
+
+Caido tools come from ``CaidoCapability.tools()`` automatically via
+the SDK's capability merge — we don't include them here. Skills are
+injected via the prompt; the model can also load more at runtime via
+the ``load_skill`` tool.
+
+References:
+    - PLAYBOOK.md §4.3 (graph tool wiring)
+    - AUDIT.md §2.4 (C4 — stop_at_tool_names is required for subagents)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agents import Agent
+from agents.agent import StopAtTools
+from agents.tool import Tool
+
+from strix.agents.sdk_prompt import render_system_prompt
+from strix.tools.agents_graph.agents_graph_sdk_tools import (
+    agent_finish,
+    agent_status,
+    create_agent,
+    send_message_to_agent,
+    view_agent_graph,
+    wait_for_message,
+)
+from strix.tools.browser.browser_sdk_tool import browser_action
+from strix.tools.file_edit.file_edit_sdk_tools import (
+    list_files,
+    search_files,
+    str_replace_editor,
+)
+from strix.tools.finish.finish_sdk_tool import finish_scan
+from strix.tools.load_skill.load_skill_sdk_tool import load_skill
+from strix.tools.notes.notes_sdk_tools import (
+    create_note,
+    delete_note,
+    get_note,
+    list_notes,
+    update_note,
+)
+from strix.tools.python.python_sdk_tool import python_action
+from strix.tools.reporting.reporting_sdk_tools import create_vulnerability_report
+from strix.tools.terminal.terminal_sdk_tool import terminal_execute
+from strix.tools.thinking.thinking_sdk_tools import think
+from strix.tools.todo.todo_sdk_tools import (
+    create_todo,
+    delete_todo,
+    list_todos,
+    mark_todo_done,
+    mark_todo_pending,
+    update_todo,
+)
+from strix.tools.web_search.web_search_sdk_tool import web_search
+
+
+logger = logging.getLogger(__name__)
+
+
+# Tools every Strix agent has, root or child. The Caido proxy tools
+# (list_requests, view_request, send_request, ...) are NOT here —
+# CaidoCapability.tools() returns them and the SDK merges them in.
+_BASE_TOOLS: tuple[Tool, ...] = (
+    # Thinking + planning
+    think,
+    # Per-agent todos
+    create_todo,
+    list_todos,
+    update_todo,
+    mark_todo_done,
+    mark_todo_pending,
+    delete_todo,
+    # Shared notes (per-run JSONL store)
+    create_note,
+    list_notes,
+    get_note,
+    update_note,
+    delete_note,
+    # Web search (only registered if PERPLEXITY_API_KEY is set; the
+    # tool itself returns a structured error when not configured, so
+    # always exposing it is safe)
+    web_search,
+    # File edit (sandbox-bound)
+    str_replace_editor,
+    list_files,
+    search_files,
+    # Reporting
+    create_vulnerability_report,
+    # Skill loading
+    load_skill,
+    # Sandbox primitives
+    browser_action,
+    terminal_execute,
+    python_action,
+    # Multi-agent graph tools (the bus is in ctx.context)
+    view_agent_graph,
+    agent_status,
+    send_message_to_agent,
+    wait_for_message,
+    create_agent,
+)
+
+
+def build_strix_agent(
+    *,
+    name: str = "strix",
+    skills: list[str] | None = None,
+    is_root: bool,
+    scan_mode: str = "deep",
+    is_whitebox: bool = False,
+    interactive: bool = False,
+    system_prompt_context: dict[str, Any] | None = None,
+) -> Agent[Any]:
+    """Build an ``agents.Agent`` configured for either root or child use.
+
+    Args:
+        name: Agent name. Surfaces in traces and the bus's ``names`` map.
+            Defaults to ``"strix"`` for the root; create_agent passes
+            distinct names per child.
+        skills: Skills to preload into the system prompt. The agent can
+            also load more at runtime via the ``load_skill`` tool.
+        is_root: Selects the tool list and ``tool_use_behavior``.
+            Root carries ``finish_scan`` and stops there; child carries
+            ``agent_finish`` and stops there.
+        scan_mode: ``"deep"`` etc.; routes the scan-mode skill section
+            of the prompt template.
+        is_whitebox: Whitebox source-aware mode toggle. Adds two extra
+            skills to the prompt and gates whitebox-only behavior in
+            the create_agent / wiki integration.
+        interactive: Renders the interactive-mode communication block
+            in the system prompt.
+        system_prompt_context: Free-form dict the prompt template
+            renders into the ``system_prompt_context`` variable —
+            today carries the scan scope / authorization block.
+
+    Returns the ``Agent`` instance with ``model=None`` so the
+    ``RunConfig.model`` (built by ``make_run_config``) drives provider
+    selection. ``agents.Agent`` is generic on context type; we let
+    the caller's ``Runner.run(context=...)`` typing determine that.
+    """
+    instructions = render_system_prompt(
+        skills=skills,
+        scan_mode=scan_mode,
+        is_whitebox=is_whitebox,
+        interactive=interactive,
+        system_prompt_context=system_prompt_context,
+    )
+
+    # Tool list + termination tool depend on is_root. The tuple-then-
+    # list dance keeps _BASE_TOOLS immutable so concurrent agent builds
+    # can't accidentally mutate each other's tool list.
+    if is_root:
+        tools: list[Tool] = [*_BASE_TOOLS, finish_scan]
+        stop_at = ("finish_scan",)
+    else:
+        tools = [*_BASE_TOOLS, agent_finish]
+        stop_at = ("agent_finish",)
+
+    return Agent(
+        name=name,
+        instructions=instructions,
+        tools=tools,
+        tool_use_behavior=StopAtTools(stop_at_tool_names=list(stop_at)),
+        # model=None so ``RunConfig.model`` (e.g. ``strix/claude-sonnet-4.6``)
+        # routes through MultiProvider rather than the SDK's default.
+        model=None,
+    )
+
+
+def make_child_factory(
+    *,
+    scan_mode: str = "deep",
+    is_whitebox: bool = False,
+    interactive: bool = False,
+    system_prompt_context: dict[str, Any] | None = None,
+) -> Any:
+    """Return a callable suitable for ``ctx.context['agent_factory']``.
+
+    The Phase 3 ``create_agent`` graph tool reads
+    ``ctx.context['agent_factory']`` and calls it with ``name=`` and
+    ``skills=`` to build a child Agent. We snapshot the run-level
+    arguments (scan_mode, is_whitebox, etc.) into a closure so each
+    child inherits the right scan-level configuration without the
+    create_agent tool having to know about them.
+    """
+
+    def _factory(*, name: str, skills: list[str]) -> Agent[Any]:
+        return build_strix_agent(
+            name=name,
+            skills=skills,
+            is_root=False,
+            scan_mode=scan_mode,
+            is_whitebox=is_whitebox,
+            interactive=interactive,
+            system_prompt_context=system_prompt_context,
+        )
+
+    return _factory

strix/agents/sdk_prompt.py

@@ -0,0 +1,130 @@
+"""Standalone Jinja-based system-prompt renderer for SDK agents.
+
+The legacy ``LLM._load_system_prompt`` couples prompt rendering to the
+LLM client class. The SDK migration owns the model client through
+``MultiProvider`` instead, so we extract the rendering logic into a
+plain function that the SDK agent factory can call without pulling in
+the legacy ``LLM`` instance.
+
+Reuses the existing Jinja template at
+``strix/agents/StrixAgent/system_prompt.jinja`` (508 lines, expanding
+into the multi-section prompt with skills, tools, scan modes, etc.) so
+behavior parity is preserved verbatim — only the call site changes.
+
+References:
+    - HARNESS_WIKI.md §4.1 (system prompt assembly)
+    - PLAYBOOK.md §4 (per-tool migration contracts)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from strix.skills import load_skills
+from strix.tools import get_tools_prompt
+from strix.utils.resource_paths import get_strix_resource_path
+
+
+logger = logging.getLogger(__name__)
+
+
+# Hard-coded to the StrixAgent template since it's the only agent type
+# under the SDK migration. The legacy harness supported multiple agent
+# names but in practice only StrixAgent ships.
+_AGENT_NAME = "StrixAgent"
+
+
+def _resolve_skills(
+    *,
+    requested: list[str] | None,
+    scan_mode: str = "deep",
+    is_whitebox: bool = False,
+) -> list[str]:
+    """Build the deduped, ordered skills list for the prompt render.
+
+    Mirrors :py:meth:`LLM._get_skills_to_load` exactly so the rendered
+    prompt is byte-identical to the legacy path:
+
+    1. Whatever the caller asked for, in order.
+    2. ``scan_modes/<mode>`` (always).
+    3. Whitebox-specific skills if applicable.
+    """
+    ordered: list[str] = list(requested or [])
+    ordered.append(f"scan_modes/{scan_mode}")
+    if is_whitebox:
+        ordered.append("coordination/source_aware_whitebox")
+        ordered.append("custom/source_aware_sast")
+
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for skill in ordered:
+        if skill and skill not in seen:
+            deduped.append(skill)
+            seen.add(skill)
+    return deduped
+
+
+def render_system_prompt(
+    *,
+    skills: list[str] | None = None,
+    scan_mode: str = "deep",
+    is_whitebox: bool = False,
+    interactive: bool = False,
+    system_prompt_context: dict[str, Any] | None = None,
+) -> str:
+    """Render the StrixAgent system prompt.
+
+    Args:
+        skills: Skills the caller wants preloaded into the prompt
+            context (the agent can also load more at runtime via the
+            ``load_skill`` tool).
+        scan_mode: ``"deep" | "fast" | ...``. Maps to ``scan_modes/<mode>``
+            skill.
+        is_whitebox: When True, the source-aware whitebox skill stack
+            is loaded too.
+        interactive: When True, the prompt renders the interactive-mode
+            communication rules block.
+        system_prompt_context: Free-form dict that the template's
+            ``system_prompt_context`` variable receives — used today for
+            the scan-scope authorization block from
+            :py:meth:`StrixAgent._build_system_scope_context`.
+
+    Returns the rendered prompt string. If anything goes wrong (template
+    missing, render failure), returns an empty string and logs — same
+    fail-soft posture as the legacy method, because a missing prompt is
+    survivable but a hard failure during agent construction is not.
+    """
+    try:
+        prompt_dir = get_strix_resource_path("agents", _AGENT_NAME)
+        skills_dir = get_strix_resource_path("skills")
+        env = Environment(
+            loader=FileSystemLoader([prompt_dir, skills_dir]),
+            autoescape=select_autoescape(
+                enabled_extensions=(),
+                default_for_string=False,
+            ),
+        )
+
+        skills_to_load = _resolve_skills(
+            requested=skills,
+            scan_mode=scan_mode,
+            is_whitebox=is_whitebox,
+        )
+        skill_content = load_skills(skills_to_load)
+        env.globals["get_skill"] = lambda name: skill_content.get(name, "")
+
+        rendered = env.get_template("system_prompt.jinja").render(
+            get_tools_prompt=get_tools_prompt,
+            loaded_skill_names=list(skill_content.keys()),
+            interactive=interactive,
+            system_prompt_context=system_prompt_context or {},
+            **skill_content,
+        )
+    except Exception:
+        logger.exception("render_system_prompt failed; returning empty prompt")
+        return ""
+    else:
+        return str(rendered)

strix/sdk_entry.py

@@ -0,0 +1,282 @@
+"""Top-level SDK scan entry point.
+
+Replaces the legacy ``strix.cli.main → StrixAgent.execute_scan``
+pipeline with the SDK-native equivalent:
+
+1. Build the per-scan ``AgentMessageBus``.
+2. Bring up (or reuse) a sandbox session for ``scan_id`` via the
+   :mod:`strix.sandbox.session_manager`.
+3. Build the root ``Agent`` via :func:`build_strix_agent` and a
+   matching child factory via :func:`make_child_factory`.
+4. Build the root context dict (bus + sandbox bundle + agent_factory).
+5. Register the root in the bus.
+6. Build the ``RunConfig`` via the factory.
+7. Call ``Runner.run(...)`` and surface the result.
+8. ``finally`` cleanup the sandbox session.
+
+Phase 5 lands the wiring; the streaming accumulator + TUI integration
+land in Phase 5b. The entry point is intentionally not wired to the
+CLI yet — that's a follow-up under ``STRIX_USE_SDK_HARNESS=1`` (see
+PLAYBOOK §7.1 cutover plan).
+
+References:
+    - PLAYBOOK.md §3.3 (session manager), §4.3 (graph tools), §7.1
+    - AUDIT_R3.md C9 (cancel_descendants on cleanup)
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from agents import Runner
+
+from strix.agents.sdk_factory import build_strix_agent, make_child_factory
+from strix.orchestration.bus import AgentMessageBus
+from strix.orchestration.hooks import StrixOrchestrationHooks
+from strix.run_config_factory import (
+    STRIX_DEFAULT_MAX_TURNS,
+    make_agent_context,
+    make_run_config,
+)
+from strix.sandbox import session_manager
+
+
+if TYPE_CHECKING:
+    from agents.result import RunResult
+
+
+logger = logging.getLogger(__name__)
+
+
+def _build_root_task(scan_config: dict[str, Any]) -> str:
+    """Format the user-facing task for the root agent.
+
+    Mirrors :py:meth:`StrixAgent.execute_scan` (legacy) — collects each
+    target type into a labelled section, appends diff-scope context if
+    active, and tacks on user_instructions. The structured shape is
+    important for prompt parity: the system prompt template references
+    these section headers.
+    """
+    targets = scan_config.get("targets", []) or []
+    diff_scope = scan_config.get("diff_scope") or {}
+    user_instructions = scan_config.get("user_instructions", "") or ""
+
+    repos: list[str] = []
+    locals_: list[str] = []
+    urls: list[str] = []
+    ips: list[str] = []
+
+    for target in targets:
+        ttype = target.get("type")
+        details = target.get("details") or {}
+        workspace_subdir = details.get("workspace_subdir")
+        workspace_path = f"/workspace/{workspace_subdir}" if workspace_subdir else "/workspace"
+
+        if ttype == "repository":
+            url = details.get("target_repo", "")
+            cloned = details.get("cloned_repo_path")
+            repos.append(
+                f"- {url} (available at: {workspace_path})" if cloned else f"- {url}",
+            )
+        elif ttype == "local_code":
+            path = details.get("target_path", "unknown")
+            locals_.append(f"- {path} (available at: {workspace_path})")
+        elif ttype == "web_application":
+            urls.append(f"- {details.get('target_url', '')}")
+        elif ttype == "ip_address":
+            ips.append(f"- {details.get('target_ip', '')}")
+
+    parts: list[str] = []
+    if repos:
+        parts.append("\n\nRepositories:")
+        parts.extend(repos)
+    if locals_:
+        parts.append("\n\nLocal Codebases:")
+        parts.extend(locals_)
+    if urls:
+        parts.append("\n\nURLs:")
+        parts.extend(urls)
+    if ips:
+        parts.append("\n\nIP Addresses:")
+        parts.extend(ips)
+
+    if diff_scope.get("active"):
+        parts.append("\n\nScope Constraints:")
+        parts.append(
+            "- Pull request diff-scope mode is active. Prioritize changed files "
+            "and use other files only for context.",
+        )
+        for repo_scope in diff_scope.get("repos", []) or []:
+            label = (
+                repo_scope.get("workspace_subdir") or repo_scope.get("source_path") or "repository"
+            )
+            changed = repo_scope.get("analyzable_files_count", 0)
+            deleted = repo_scope.get("deleted_files_count", 0)
+            parts.append(f"- {label}: {changed} changed file(s) in primary scope")
+            if deleted:
+                parts.append(f"- {label}: {deleted} deleted file(s) are context-only")
+
+    task = " ".join(parts)
+    if user_instructions:
+        task = f"{task}\n\nSpecial instructions: {user_instructions}"
+    return task
+
+
+def _build_scope_context(scan_config: dict[str, Any]) -> dict[str, Any]:
+    """Produce the system_prompt_context block used by the prompt template.
+
+    Same shape as the legacy
+    :py:meth:`StrixAgent._build_system_scope_context` so the prompt
+    template's ``system_prompt_context.authorized_targets`` lookups
+    stay byte-identical.
+    """
+    authorized: list[dict[str, str]] = []
+    for target in scan_config.get("targets", []) or []:
+        ttype = target.get("type", "unknown")
+        details = target.get("details") or {}
+
+        if ttype == "repository":
+            value = details.get("target_repo", "")
+        elif ttype == "local_code":
+            value = details.get("target_path", "")
+        elif ttype == "web_application":
+            value = details.get("target_url", "")
+        elif ttype == "ip_address":
+            value = details.get("target_ip", "")
+        else:
+            value = target.get("original", "")
+
+        workspace_subdir = details.get("workspace_subdir")
+        workspace_path = f"/workspace/{workspace_subdir}" if workspace_subdir else ""
+        authorized.append(
+            {"type": ttype, "value": value, "workspace_path": workspace_path},
+        )
+
+    return {
+        "scope_source": "system_scan_config",
+        "authorization_source": "strix_platform_verified_targets",
+        "authorized_targets": authorized,
+        "user_instructions_do_not_expand_scope": True,
+    }
+
+
+async def run_strix_scan(
+    *,
+    scan_config: dict[str, Any],
+    scan_id: str | None = None,
+    image: str,
+    sources_path: Path,
+    tracer: Any | None = None,
+    interactive: bool = False,
+    max_turns: int = STRIX_DEFAULT_MAX_TURNS,
+    cleanup_on_exit: bool = True,
+) -> RunResult:
+    """Run one Strix scan end-to-end against a freshly-prepared sandbox.
+
+    Args:
+        scan_config: Same shape the legacy ``StrixAgent.execute_scan``
+            takes (targets, user_instructions, diff_scope, scan_mode,
+            is_whitebox, skills).
+        scan_id: Used to key the sandbox session cache. Auto-generated
+            if omitted — callers that want resume-after-crash semantics
+            should pass a stable id.
+        image: Docker image tag for the sandbox (e.g.
+            ``"strix-sandbox:0.1.13"``).
+        sources_path: Host directory mounted into ``/workspace/sources``.
+        tracer: Optional Strix tracer. Stored in context for the
+            telemetry hook chain. Pass ``None`` for unit tests.
+        interactive: Renders the interactive-mode prompt block on the
+            root agent.
+        max_turns: Cap on root-agent LLM turns. Mirrors legacy
+            ``AgentState.max_iterations`` (300).
+        cleanup_on_exit: When True (default), tears down the sandbox
+            session in a ``finally``. Set to False for resume scenarios
+            where the caller wants to preserve the container.
+
+    Returns the SDK ``RunResult`` from ``Runner.run``. Raises if the
+    sandbox bring-up fails or the run itself raises.
+    """
+    if scan_id is None:
+        scan_id = f"scan-{uuid.uuid4().hex[:8]}"
+    logger.info("Starting Strix scan %s", scan_id)
+
+    bus = AgentMessageBus()
+    root_id = uuid.uuid4().hex[:8]
+
+    bundle = await session_manager.create_or_reuse(
+        scan_id,
+        image=image,
+        sources_path=sources_path,
+    )
+
+    try:
+        scan_mode = str(scan_config.get("scan_mode") or "deep")
+        is_whitebox = bool(scan_config.get("is_whitebox", False))
+        skills = list(scan_config.get("skills") or [])
+        diff_scope = scan_config.get("diff_scope") or None
+        run_id = scan_config.get("run_id") or scan_id
+
+        scope_context = _build_scope_context(scan_config)
+
+        root_agent = build_strix_agent(
+            name="strix",
+            skills=skills,
+            is_root=True,
+            scan_mode=scan_mode,
+            is_whitebox=is_whitebox,
+            interactive=interactive,
+            system_prompt_context=scope_context,
+        )
+
+        await bus.register(root_id, "strix", parent_id=None)
+
+        agent_factory = make_child_factory(
+            scan_mode=scan_mode,
+            is_whitebox=is_whitebox,
+            interactive=interactive,
+            system_prompt_context=scope_context,
+        )
+
+        context = make_agent_context(
+            bus=bus,
+            sandbox_session=bundle["session"],
+            sandbox_client=bundle["client"],
+            sandbox_token=bundle["bearer"],
+            tool_server_host_port=bundle["tool_server_host_port"],
+            caido_host_port=bundle["caido_host_port"],
+            agent_id=root_id,
+            agent_name="strix",
+            parent_id=None,
+            tracer=tracer,
+            max_turns=max_turns,
+            is_whitebox=is_whitebox,
+            diff_scope=diff_scope,
+            run_id=run_id,
+            agent_factory=agent_factory,
+        )
+
+        run_config = make_run_config(
+            sandbox_session=bundle["session"],
+            sandbox_client=bundle["client"],
+        )
+
+        task_text = _build_root_task(scan_config)
+        return await Runner.run(
+            root_agent,
+            input=task_text,
+            run_config=run_config,
+            context=context,
+            hooks=StrixOrchestrationHooks(),
+            max_turns=max_turns,
+        )
+    except BaseException:
+        # Cancel any descendant tasks the root spawned before unwinding.
+        # cancel_descendants is idempotent and handles the empty-tree case.
+        await bus.cancel_descendants(root_id)
+        raise
+    finally:
+        if cleanup_on_exit:
+            await session_manager.cleanup(scan_id)