@mseep/open-computer-use 1.0.0

package/tests/orchestrator/test_sub_agent_dispatch.py

@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+"""TEST-04: end-to-end dispatch suite for mcp_tools.sub_agent.
+
+Mocks the subprocess boundary (cli_runtime.dispatch is replaced with an
+AsyncMock that returns a synthetic SubAgentResult) and asserts:
+
+1. The MCP tool signature is byte-identical to the v0.9.2.0 contract:
+   sub_agent(task, description, ctx, model='', max_turns=0,
+             working_directory='/home/assistant', resume_session_id='').
+2. dispatch routes to the correct adapter for each SUBAGENT_CLI value
+   ({claude, codex, opencode}) — verified by inspecting cli_runtime.resolve_cli()
+   under the active env at dispatch time.
+3. Cost-guardrail caveat (Phase 7 success criterion 5; PITFALLS.md Pitfall 4):
+   when SubAgentResult.cost_usd is None (codex always; opencode when usage
+   is missing), the rendered MCP result string contains the literal
+   "unavailable" and contains NO "$0.0" / "$0.00" substring.
+   When cost_usd is a float, the rendered string contains "$X.XXXX".
+
+The cost rendering branch was inlined into mcp_tools.sub_agent by Phase 5
+plan 05-05 (verified at mcp_tools.py:1092-1095). This suite is the
+regression guard that prevents future drift.
+
+Mirrors the env-scrub + module-reload pattern from
+tests/orchestrator/test_subagent_claude_compat.py so local-dev shells
+with model-override env vars exported do not break the assertions.
+"""
+
+import asyncio
+import importlib
+import inspect
+import os
+import sys
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+_SERVER_DIR = os.path.join(
+    os.path.dirname(__file__), "..", "..", "computer-use-server"
+)
+sys.path.insert(0, _SERVER_DIR)
+
+
+# ---------------------------------------------------------------------------
+# Env scrub — mirror test_subagent_claude_compat.py so local dev does not
+# poison the model-resolution assertions.
+# ---------------------------------------------------------------------------
+_DEV_ENV_VARS_TO_SCRUB = (
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    "CLAUDE_SUB_AGENT_DEFAULT_MODEL",
+    "CODEX_SUB_AGENT_DEFAULT_MODEL",
+    "OPENCODE_SUB_AGENT_DEFAULT_MODEL",
+    "CODEX_MODEL",
+    "OPENCODE_MODEL",
+    "OPENCODE_MODEL_ALIASES",
+)
+
+
+def _scrub_dev_env(monkeypatch):
+    for var in _DEV_ENV_VARS_TO_SCRUB:
+        monkeypatch.delenv(var, raising=False)
+
+
+def _make_result(*, cost_usd, text="OK", is_error=False, turns=1, returncode=0):
+    """Build a synthetic SubAgentResult.
+
+    Matches cli_adapters/result.py SubAgentResult fields exactly
+    (frozen dataclass: text, cost_usd, turns, is_error, session_id,
+    raw_events, returncode).
+    """
+    from cli_adapters.result import SubAgentResult
+    return SubAgentResult(
+        text=text,
+        cost_usd=cost_usd,
+        turns=turns,
+        is_error=is_error,
+        session_id="test-session",
+        raw_events=[],
+        returncode=returncode,
+    )
+
+
+def _make_ctx():
+    """Minimal FastMCP Context double — only the methods sub_agent calls."""
+    ctx = MagicMock()
+    ctx.report_progress = AsyncMock()
+    ctx.info = MagicMock()
+    ctx.warning = MagicMock()
+    ctx.error = MagicMock()
+    return ctx
+
+
+def _reload_runtime():
+    """Reload cli_runtime + mcp_tools so module-level env reads settle.
+
+    Order matters: docker_manager validates SUBAGENT_CLI at import time,
+    cli_runtime imports from docker_manager, mcp_tools imports from
+    cli_runtime.
+    """
+    for mod_name in ("docker_manager", "cli_runtime", "mcp_tools"):
+        if mod_name in sys.modules:
+            importlib.reload(sys.modules[mod_name])
+        else:
+            importlib.import_module(mod_name)
+
+
+def _unwrap_tool(tool_obj):
+    """Return the original async function behind FastMCP @mcp.tool() wrapping."""
+    return getattr(tool_obj, "fn", None) or getattr(tool_obj, "__wrapped__", None) or tool_obj
+
+
+def _install_common_stubs(monkeypatch, mcp_tools, fake_dispatch):
+    """Stub the side-effect-heavy collaborators so sub_agent can run on host.
+
+    - cli_dispatch: replaced with the per-test fake (the boundary under test)
+    - _get_or_create_container: opaque MagicMock (dispatch never touches it
+      because we stub cli_dispatch wholesale)
+    - _ensure_gitlab_token: no-op AsyncMock
+    - _execute_bash: returns an empty result so the marker-file write +
+      _stream_session_logs body bail immediately
+    - _validate_chat_id: returns a deterministic ('test', None) tuple so we
+      do not depend on contextvar state
+    - skill_manager: no real skills lookup
+    """
+    monkeypatch.setattr(mcp_tools, "cli_dispatch", fake_dispatch)
+    monkeypatch.setattr(
+        mcp_tools, "_get_or_create_container", lambda *a, **kw: MagicMock()
+    )
+    monkeypatch.setattr(
+        mcp_tools, "_ensure_gitlab_token", AsyncMock(return_value=None)
+    )
+    monkeypatch.setattr(
+        mcp_tools, "_execute_bash", lambda *a, **kw: {"output": "", "exit_code": 0}
+    )
+    monkeypatch.setattr(
+        mcp_tools, "_validate_chat_id", lambda: ("test", None)
+    )
+    monkeypatch.setattr(
+        mcp_tools.skill_manager, "get_user_skills_sync", lambda *a, **kw: []
+    )
+    monkeypatch.setattr(
+        mcp_tools.skill_manager, "build_sub_agent_skills_text", lambda *a, **kw: ""
+    )
+
+
+# ===========================================================================
+# Test 1 — MCP signature regression guard.
+# ===========================================================================
+
+def test_signature_is_byte_identical(monkeypatch):
+    """v0.9.2.0 contract: sub_agent(task, description, ctx, model='',
+    max_turns=0, working_directory='/home/assistant', resume_session_id='').
+
+    Any drift breaks every existing skill caller.
+    """
+    _scrub_dev_env(monkeypatch)
+    monkeypatch.setenv("SUBAGENT_CLI", "claude")
+    _reload_runtime()
+    import mcp_tools
+
+    fn = _unwrap_tool(mcp_tools.sub_agent)
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.items())
+    names = [n for n, _ in params]
+
+    assert names == [
+        "task", "description", "ctx",
+        "model", "max_turns", "working_directory", "resume_session_id",
+    ], f"sub_agent parameters drifted from v0.9.2.0 contract: {names}"
+
+    defaults = {n: p.default for n, p in params if p.default is not inspect.Parameter.empty}
+    assert defaults["model"] == ""
+    assert defaults["max_turns"] == 0
+    assert defaults["working_directory"] == "/home/assistant"
+    assert defaults["resume_session_id"] == ""
+
+
+# ===========================================================================
+# Test 2 — dispatch routes to the correct adapter per SUBAGENT_CLI value.
+# ===========================================================================
+
+@pytest.mark.parametrize("cli_value,expected_cli_str", [
+    ("claude", "claude"),
+    ("codex", "codex"),
+    ("opencode", "opencode"),
+])
+def test_dispatch_routes_to_correct_adapter(
+    monkeypatch, cli_value, expected_cli_str,
+):
+    """resolve_cli() inside the dispatch boundary must reflect SUBAGENT_CLI."""
+    _scrub_dev_env(monkeypatch)
+    monkeypatch.setenv("SUBAGENT_CLI", cli_value)
+    # Phase 2: opencode/codex no longer have hardcoded defaults — set the
+    # per-CLI default env so resolve_subagent_model("", ...) doesn't raise
+    # before fake_dispatch is reached. The actual id is irrelevant; the test
+    # only checks that dispatch was invoked with the right CLI.
+    if cli_value == "opencode":
+        monkeypatch.setenv("OPENCODE_SUB_AGENT_DEFAULT_MODEL", "anthropic/claude-sonnet-4-6")
+    elif cli_value == "codex":
+        monkeypatch.setenv("CODEX_SUB_AGENT_DEFAULT_MODEL", "gpt-5-codex")
+    _reload_runtime()
+    import cli_runtime
+    import mcp_tools
+
+    captured = {}
+
+    async def fake_dispatch(**kwargs):
+        captured.update(kwargs)
+        captured["_cli_seen"] = cli_runtime.resolve_cli()
+        # Codex never has cost; claude does; opencode optional.
+        cost = 0.0042 if cli_value == "claude" else None
+        return (
+            _make_result(cost_usd=cost, text="hello world"),
+            f"resolved-{cli_value}-model",
+            "sonnet",
+        )
+
+    _install_common_stubs(monkeypatch, mcp_tools, fake_dispatch)
+
+    fn = _unwrap_tool(mcp_tools.sub_agent)
+    # claude is the only CLI where 'sonnet' is a valid model alias for the
+    # default model resolution path that runs inside sub_agent BEFORE
+    # dispatch. For codex/opencode we pass an empty model so the per-CLI
+    # default kicks in inside resolve_subagent_model (called by the real
+    # dispatch — but we replace dispatch wholesale, so the model value is
+    # captured verbatim). Either way the model arg flows through to
+    # captured kwargs and we only assert the routing.
+    result = asyncio.run(fn(
+        task="hello", description="d", ctx=_make_ctx(),
+    ))
+
+    seen_cli = captured.get("_cli_seen")
+    assert seen_cli is not None, "fake_dispatch was not invoked"
+    assert seen_cli.value == expected_cli_str, (
+        f"resolve_cli() returned {seen_cli!r}; expected {expected_cli_str!r}"
+    )
+    # Sanity: dispatch was awaited once (captured kwargs are present).
+    assert "task" in captured
+    assert "system_prompt" in captured
+    # Result string carries the completion banner + the synthetic text.
+    assert "Sub-Agent Completed" in result, (
+        f"missing completion banner; first 300 chars: {result[:300]}"
+    )
+    assert "hello world" in result
+
+
+# ===========================================================================
+# Test 3 — cost rendering: cost_usd=None must render "unavailable".
+# ===========================================================================
+
+@pytest.mark.parametrize("cli_value", ["codex", "opencode"])
+def test_cost_rendering_unavailable_for_none(monkeypatch, cli_value):
+    """Pitfall 4 + Phase 7 success criterion 5.
+
+    cost_usd=None (codex always; opencode when usage is missing) must
+    render as the literal "unavailable" — NEVER as "$0.00" / "$0.0000",
+    which would mislead the operator into thinking the run was free.
+    """
+    _scrub_dev_env(monkeypatch)
+    monkeypatch.setenv("SUBAGENT_CLI", cli_value)
+    # Phase 2: per-CLI default env required for opencode/codex.
+    if cli_value == "opencode":
+        monkeypatch.setenv("OPENCODE_SUB_AGENT_DEFAULT_MODEL", "anthropic/claude-sonnet-4-6")
+    elif cli_value == "codex":
+        monkeypatch.setenv("CODEX_SUB_AGENT_DEFAULT_MODEL", "gpt-5-codex")
+    _reload_runtime()
+    import mcp_tools
+
+    async def fake_dispatch(**kwargs):
+        return (
+            _make_result(cost_usd=None, text="ok"),
+            "model-id",
+            "model-display",
+        )
+
+    _install_common_stubs(monkeypatch, mcp_tools, fake_dispatch)
+
+    fn = _unwrap_tool(mcp_tools.sub_agent)
+    result = asyncio.run(fn(
+        task="t", description="d", ctx=_make_ctx(),
+    ))
+
+    assert "unavailable" in result, (
+        f"expected literal 'unavailable' in result for cost_usd=None; "
+        f"first 400 chars: {result[:400]}"
+    )
+    # Negative assertions: never let a None cost render as a dollar amount.
+    assert "$0.0" not in result, (
+        f"cost_usd=None must NOT render as $0.0X; first 400 chars: {result[:400]}"
+    )
+    assert "$0.00" not in result
+    assert "$0.0000" not in result
+
+
+def test_cost_rendering_dollar_for_float(monkeypatch):
+    """Positive case: a float cost renders as $X.XXXX (4-decimal USD)."""
+    _scrub_dev_env(monkeypatch)
+    monkeypatch.setenv("SUBAGENT_CLI", "claude")
+    _reload_runtime()
+    import mcp_tools
+
+    async def fake_dispatch(**kwargs):
+        return (
+            _make_result(cost_usd=0.0042, text="ok"),
+            "claude-sonnet-4-6",
+            "sonnet",
+        )
+
+    _install_common_stubs(monkeypatch, mcp_tools, fake_dispatch)
+
+    fn = _unwrap_tool(mcp_tools.sub_agent)
+    result = asyncio.run(fn(
+        task="t", description="d", ctx=_make_ctx(),
+    ))
+
+    assert "$0.0042" in result, (
+        f"expected '$0.0042' for cost_usd=0.0042; first 400 chars: {result[:400]}"
+    )
+    assert "unavailable" not in result, (
+        "float cost must NOT render as 'unavailable'"
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-v"]))

package/tests/orchestrator/test_subagent_claude_compat.py

@@ -0,0 +1,367 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+"""ADAPT-02 byte-compat: ClaudeAdapter.build_argv must produce argv
+byte-identical to the v0.9.2.0 production claude_command (argv layer).
+
+The lifted code in cli_adapters/claude.py is DORMANT in Phase 4 (production
+path stays in mcp_tools.sub_agent through Phase 6). This snapshot test is
+the forcing function that prevents drift between the two copies, so when
+Phase 7 flips dispatch through cli_runtime, the change is provably zero
+regression for SUBAGENT_CLI=claude.
+
+The shell-execution wrapper (`cd <wd> && <headers_env> ...`) lives in
+mcp_tools.sub_agent and is NOT part of build_argv's contract — only the
+argv list itself is asserted byte-identical.
+"""
+
+import json
+import os
+import sys
+
+import pytest
+
+_SERVER_DIR = os.path.join(
+    os.path.dirname(__file__), "..", "..", "computer-use-server"
+)
+sys.path.insert(0, _SERVER_DIR)
+
+_FIXTURE_PATH = os.path.join(
+    os.path.dirname(__file__), "..", "fixtures", "cli", "claude_v0.9.2.0_argv.json"
+)
+
+
+@pytest.fixture(scope="module")
+def fixture():
+    with open(_FIXTURE_PATH) as f:
+        return json.load(f)
+
+
+def test_new_session_argv_byte_compat(fixture):
+    """NEW SESSION branch (resume_session_id == ""): 15-element argv with
+    --model + --append-system-prompt before the common flags."""
+    from cli_adapters.claude import ClaudeAdapter
+    adapter = ClaudeAdapter()
+    case = fixture["new_session"]
+    actual = adapter.build_argv(**case["inputs"])
+    assert actual == case["expected_argv"], (
+        f"build_argv NEW SESSION drifted from v0.9.2.0 baseline.\n"
+        f"  expected: {case['expected_argv']}\n"
+        f"  actual:   {actual}\n"
+    )
+    assert len(actual) == 15, f"expected 15-element argv, got {len(actual)}"
+
+
+def test_resume_argv_byte_compat(fixture):
+    """RESUME branch (resume_session_id non-empty): 13-element argv with
+    --resume <session_id> in place of --model + --append-system-prompt."""
+    from cli_adapters.claude import ClaudeAdapter
+    adapter = ClaudeAdapter()
+    case = fixture["resume"]
+    actual = adapter.build_argv(**case["inputs"])
+    assert actual == case["expected_argv"], (
+        f"build_argv RESUME drifted from v0.9.2.0 baseline.\n"
+        f"  expected: {case['expected_argv']}\n"
+        f"  actual:   {actual}\n"
+    )
+    assert len(actual) == 13, f"expected 13-element argv, got {len(actual)}"
+
+
+def test_disallowed_tools_value_is_unquoted(fixture):
+    """The original mcp_tools.py:957 emits `--disallowedTools 'AskUserQuestion,ExitPlanMode'`
+    inside a SHELL command string — the single quotes are shell quoting, not part
+    of the argv value. In argv form the value is the literal string
+    `AskUserQuestion,ExitPlanMode` with no quotes (RESEARCH.md line 215, plan
+    04-02 SUMMARY line 97)."""
+    for case_key in ("new_session", "resume"):
+        argv = fixture[case_key]["expected_argv"]
+        idx = argv.index("--disallowedTools")
+        assert argv[idx + 1] == "AskUserQuestion,ExitPlanMode", (
+            f"{case_key}: --disallowedTools value must be unquoted, got {argv[idx + 1]!r}"
+        )
+
+
+def test_parse_result_minimal_roundtrip():
+    """parse_result consumes Claude's --output-format json line and populates
+    SubAgentResult correctly. Smoke test (the format hasn't changed and won't
+    change in Phase 4) plus the Pitfall 4 zero-cost-becomes-None invariant."""
+    from cli_adapters.claude import ClaudeAdapter
+    adapter = ClaudeAdapter()
+    line = json.dumps({
+        "type": "result",
+        "result": "task complete",
+        "total_cost_usd": 0.123,
+        "num_turns": 5,
+        "is_error": False,
+        "session_id": "sess-xyz",
+    })
+    res = adapter.parse_result(stdout=line, stderr="", returncode=0)
+    assert res.text == "task complete"
+    assert res.cost_usd == 0.123
+    assert res.turns == 5
+    assert res.is_error is False
+    assert res.session_id == "sess-xyz"
+
+    # Pitfall 4: cost_usd -> None when 0.0 (render "unavailable", not "$0.00").
+    zero_cost_line = json.dumps({
+        "type": "result", "result": "x", "total_cost_usd": 0.0,
+        "num_turns": 0, "is_error": False, "session_id": "",
+    })
+    res2 = adapter.parse_result(stdout=zero_cost_line, stderr="", returncode=0)
+    assert res2.cost_usd is None
+    assert res2.turns is None
+    assert res2.session_id is None
+
+
+# === Phase 5 / plan 05-06: end-to-end dispatch byte-compat ===
+# Plan 05-05 flipped mcp_tools.sub_agent from inline claude_command to
+# cli_runtime.dispatch -> ClaudeAdapter -> _execute_bash_capture. These
+# tests assert the assembled shell command and the parsed SubAgentResult
+# are byte-identical to what v0.9.2.0 would have produced for the same
+# inputs.
+
+import asyncio
+import shlex as _shlex_mod
+from types import SimpleNamespace
+from unittest.mock import patch
+
+# WARNING 2 fix: scrub model-override env vars so local-dev shells (where
+# a developer might have e.g. ANTHROPIC_DEFAULT_SONNET_MODEL=my-deployment
+# exported) don't break the byte-compat assertions. CI is clean; local
+# dev gets the same guarantees.
+_DEV_ENV_VARS_TO_SCRUB = (
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    "CLAUDE_SUB_AGENT_DEFAULT_MODEL",
+    "CODEX_SUB_AGENT_DEFAULT_MODEL",
+    "OPENCODE_SUB_AGENT_DEFAULT_MODEL",
+    "CODEX_MODEL",
+    "OPENCODE_MODEL",
+    "OPENCODE_MODEL_ALIASES",
+)
+
+
+def _scrub_dev_env(monkeypatch):
+    for var in _DEV_ENV_VARS_TO_SCRUB:
+        monkeypatch.delenv(var, raising=False)
+
+
+def test_claude_dispatch_byte_compat(fixture, monkeypatch):
+    """SUBAGENT_CLI=claude (default): cli_runtime.dispatch builds the same
+    shell command as v0.9.2.0's mcp_tools.sub_agent inline claude_command,
+    and parse_result returns the same SubAgentResult.
+
+    We mock _execute_bash_capture to capture the shell command without
+    needing a Docker container, then return a known stdout that the
+    ClaudeAdapter.parse_result is expected to digest into a known
+    SubAgentResult.
+    """
+    _scrub_dev_env(monkeypatch)
+
+    # Drop modules so cli_runtime re-imports cleanly under the test env.
+    for mod in ("cli_runtime", "docker_manager"):
+        sys.modules.pop(mod, None)
+
+    # Import the freshly-loaded dispatch + Cli.
+    from cli_runtime import dispatch as cli_dispatch, Cli
+    # Sanity: default SUBAGENT_CLI resolves to claude.
+    from cli_runtime import resolve_cli
+    assert resolve_cli() == Cli.CLAUDE
+
+    # Inputs mirror the v0.9.2.0 NEW SESSION fixture. mcp_tools.sub_agent
+    # passes these via cli_dispatch(...).
+    case = fixture["new_session"]
+    inputs = case["inputs"]
+    expected_argv = case["expected_argv"]
+
+    # The captured shell command we expect dispatch to construct:
+    #   cd <wd> && [headers_env]<shlex.quote(argv) joined>
+    working_directory = "/home/assistant"
+    headers_env = ""  # No user_email path -> no ANTHROPIC_CUSTOM_HEADERS.
+    expected_quoted = " ".join(_shlex_mod.quote(a) for a in expected_argv)
+    expected_shell_cmd = (
+        f"cd {_shlex_mod.quote(working_directory)} && "
+        f"{headers_env}{expected_quoted}"
+    )
+
+    # Stub stdout fed to ClaudeAdapter.parse_result.
+    with open(_FIXTURE_PATH.replace("argv.json", "stdout.json")) as f:
+        stdout_fixture = json.load(f)
+    happy = stdout_fixture["happy_path"]
+
+    captured_cmd = {}
+
+    def _fake_capture(container, command, timeout=None):
+        captured_cmd["cmd"] = command
+        captured_cmd["timeout"] = timeout
+        return SimpleNamespace(
+            stdout=happy["stdout"],
+            stderr=happy["stderr"],
+            returncode=happy["returncode"],
+        )
+
+    with patch("cli_runtime._execute_bash_capture", side_effect=_fake_capture):
+        sub_result, model_id, model_display = asyncio.run(
+            cli_dispatch(
+                container=object(),  # opaque - _fake_capture ignores it
+                task=inputs["task"],
+                system_prompt=inputs["system_prompt"],
+                model="sonnet",  # alias resolves to inputs["model"] via resolve_subagent_model
+                max_turns=inputs["max_turns"],
+                timeout_s=inputs["timeout_s"],
+                working_directory=working_directory,
+                resume_session_id="",
+                plan_file="",
+                headers_env=headers_env,
+            )
+        )
+
+    # === Assert 1: shell command is byte-identical to v0.9.2.0 ===
+    assert captured_cmd["cmd"] == expected_shell_cmd, (
+        "Dispatch produced a shell command different from v0.9.2.0:\n"
+        f"  expected: {expected_shell_cmd}\n"
+        f"  actual:   {captured_cmd['cmd']}\n"
+    )
+    # Timeout passed through to the executor.
+    assert captured_cmd["timeout"] == inputs["timeout_s"]
+
+    # === Assert 2: parsed SubAgentResult matches the parse-side fixture ===
+    exp = happy["expected"]
+    assert sub_result.text == exp["text"]
+    assert sub_result.cost_usd == exp["cost_usd"]
+    assert sub_result.turns == exp["turns"]
+    assert sub_result.session_id == exp["session_id"]
+    assert sub_result.is_error is exp["is_error"]
+
+    # === Assert 3: model resolution preserved v0.9.2.0 alias semantics ===
+    # "sonnet" -> "claude-sonnet-4-6" (default), display "sonnet".
+    assert model_id == "claude-sonnet-4-6"
+    assert model_display == "sonnet"
+
+
+def test_claude_dispatch_resume_byte_compat(fixture, monkeypatch):
+    """RESUME branch byte-compat: same as above but with resume_session_id set.
+    Verifies the resume argv (no --model, no --append-system-prompt) is
+    assembled identically to v0.9.2.0."""
+    _scrub_dev_env(monkeypatch)
+
+    for mod in ("cli_runtime", "docker_manager"):
+        sys.modules.pop(mod, None)
+
+    from cli_runtime import dispatch as cli_dispatch
+    case = fixture["resume"]
+    inputs = case["inputs"]
+    expected_argv = case["expected_argv"]
+
+    working_directory = "/home/assistant"
+    headers_env = ""
+    expected_quoted = " ".join(_shlex_mod.quote(a) for a in expected_argv)
+    expected_shell_cmd = (
+        f"cd {_shlex_mod.quote(working_directory)} && "
+        f"{headers_env}{expected_quoted}"
+    )
+
+    captured_cmd = {}
+
+    def _fake_capture(container, command, timeout=None):
+        captured_cmd["cmd"] = command
+        return SimpleNamespace(
+            stdout='{"type": "result", "result": "resumed ok", '
+                   '"total_cost_usd": 0.05, "num_turns": 3, '
+                   '"is_error": false, "session_id": "abc-123-session"}',
+            stderr="",
+            returncode=0,
+        )
+
+    with patch("cli_runtime._execute_bash_capture", side_effect=_fake_capture):
+        sub_result, _, _ = asyncio.run(
+            cli_dispatch(
+                container=object(),
+                task=inputs["task"],
+                system_prompt=inputs["system_prompt"],
+                model="sonnet",
+                max_turns=inputs["max_turns"],
+                timeout_s=inputs["timeout_s"],
+                working_directory=working_directory,
+                resume_session_id=inputs["resume_session_id"],
+                plan_file="",
+                headers_env=headers_env,
+            )
+        )
+
+    assert captured_cmd["cmd"] == expected_shell_cmd, (
+        f"Resume dispatch shell command drifted from v0.9.2.0:\n"
+        f"  expected: {expected_shell_cmd}\n"
+        f"  actual:   {captured_cmd['cmd']}\n"
+    )
+    assert sub_result.text == "resumed ok"
+    assert sub_result.session_id == "abc-123-session"
+
+
+def test_claude_dispatch_with_headers_env_byte_compat(fixture, monkeypatch):
+    """Headers env (ANTHROPIC_CUSTOM_HEADERS path): when mcp_tools passes a
+    non-empty headers_env (because user_email is set), dispatch concatenates
+    it BEFORE the argv - exactly the v0.9.2.0 shape."""
+    _scrub_dev_env(monkeypatch)
+
+    for mod in ("cli_runtime", "docker_manager"):
+        sys.modules.pop(mod, None)
+    from cli_runtime import dispatch as cli_dispatch
+
+    case = fixture["new_session"]
+    inputs = case["inputs"]
+    expected_argv = case["expected_argv"]
+
+    working_directory = "/home/assistant"
+    # Mirrors mcp_tools.sub_agent's headers_env construction (already shlex.quote'd).
+    headers_env = (
+        f"ANTHROPIC_CUSTOM_HEADERS="
+        f"{_shlex_mod.quote('x-openwebui-user-email: alice@example.com')} "
+    )
+    expected_quoted = " ".join(_shlex_mod.quote(a) for a in expected_argv)
+    expected_shell_cmd = (
+        f"cd {_shlex_mod.quote(working_directory)} && "
+        f"{headers_env}{expected_quoted}"
+    )
+
+    captured_cmd = {}
+
+    def _fake_capture(container, command, timeout=None):
+        captured_cmd["cmd"] = command
+        return SimpleNamespace(
+            stdout='{"type": "result", "result": "ok", "total_cost_usd": 0.1, '
+                   '"num_turns": 1, "is_error": false, "session_id": "s1"}',
+            stderr="",
+            returncode=0,
+        )
+
+    with patch("cli_runtime._execute_bash_capture", side_effect=_fake_capture):
+        asyncio.run(
+            cli_dispatch(
+                container=object(),
+                task=inputs["task"],
+                system_prompt=inputs["system_prompt"],
+                model="sonnet",
+                max_turns=inputs["max_turns"],
+                timeout_s=inputs["timeout_s"],
+                working_directory=working_directory,
+                resume_session_id="",
+                plan_file="",
+                headers_env=headers_env,
+            )
+        )
+
+    assert captured_cmd["cmd"] == expected_shell_cmd, (
+        f"Dispatch with headers_env drifted from v0.9.2.0 contract:\n"
+        f"  expected: {expected_shell_cmd}\n"
+        f"  actual:   {captured_cmd['cmd']}\n"
+    )
+    # The ANTHROPIC_CUSTOM_HEADERS prefix appears verbatim (with the shell
+    # quoting that mcp_tools.sub_agent applied) - preserves GATEWAY-07
+    # contract from v0.8.12.9.
+    assert "ANTHROPIC_CUSTOM_HEADERS=" in captured_cmd["cmd"]
+    assert "x-openwebui-user-email: alice@example.com" in captured_cmd["cmd"]
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-v"]))