hud 0.6.18.dev1__tar.gz → 0.6.19.dev1__tar.gz

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hud
-Version: 0.6.18.dev1
+Version: 0.6.19.dev1
 Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-python
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-python/issues
@@ -38,7 +38,7 @@ Requires-Dist: anthropic>=0.98.0
 Requires-Dist: asyncssh>=2.23.0
 Requires-Dist: asyncvnc>=1.3.0
 Requires-Dist: fastmcp==3.2.0
-Requires-Dist: google-genai
+Requires-Dist: google-genai>=1.75.0
 Requires-Dist: httpx2<3,>=2.0.0
 Requires-Dist: httpx<1,>=0.23.0
 Requires-Dist: mcp<2.0,>=1.24.0
@@ -199,19 +199,6 @@ Each graded evaluation is a **trace** (the SDK's live handle is a `Run`). With `
 
 → [Quickstart](https://docs.hud.ai/v6/start/quickstart) · [Tasks & tasksets](https://docs.hud.ai/v6/reference/tasks)
 
-## Existing benchmarks
-
-The experimental `hud.integrations.harbor` adapter turns Harbor task directories into runnable HUD
-tasksets and can export authored HUD tasks back to Harbor folders.
-
-```python
-from hud.integrations import harbor
-
-taskset = await harbor.adapt("./benchmark")
-```
-
-→ [Harbor interop](https://docs.hud.ai/v6/advanced/harbor-convert)
-
 ## Capabilities & harnesses
 
 A **capability** is a connection the environment exposes; a **harness** attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities the harness opens.
@@ -234,6 +221,17 @@ A **capability** is a connection the environment exposes; a **harness** attaches
 
 From the [platform UI](https://hud.ai) you can run batches, compare models on the same taskset, and inspect every trace.
 
+Hosted Claude Code and Codex harnesses reach platform inference through an
+environment-owned, workspace-local endpoint. The endpoint is available only to
+`bwrap` workspaces with network isolation and is bound to the exact CLI process
+selected by the harness. Platform credentials stay in the environment-owned
+relay rather than the CLI environment, workspace manifest, or child processes.
+Codex therefore uses the environment sandbox instead of starting a nested
+Codex sandbox for process-bound hosted execution.
+The workspace probes its substrate and uses either seccomp notification or a
+ptrace-backed seccomp guard; it does not advertise process-bound connections
+when neither enforcement backend is available.
+
 → [Run & deploy](https://docs.hud.ai/v6/reference/runtime)
 
 ## Train on rewards

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/README.md

@@ -113,19 +113,6 @@ Each graded evaluation is a **trace** (the SDK's live handle is a `Run`). With `
 
 → [Quickstart](https://docs.hud.ai/v6/start/quickstart) · [Tasks & tasksets](https://docs.hud.ai/v6/reference/tasks)
 
-## Existing benchmarks
-
-The experimental `hud.integrations.harbor` adapter turns Harbor task directories into runnable HUD
-tasksets and can export authored HUD tasks back to Harbor folders.
-
-```python
-from hud.integrations import harbor
-
-taskset = await harbor.adapt("./benchmark")
-```
-
-→ [Harbor interop](https://docs.hud.ai/v6/advanced/harbor-convert)
-
 ## Capabilities & harnesses
 
 A **capability** is a connection the environment exposes; a **harness** attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities the harness opens.
@@ -148,6 +135,17 @@ A **capability** is a connection the environment exposes; a **harness** attaches
 
 From the [platform UI](https://hud.ai) you can run batches, compare models on the same taskset, and inspect every trace.
 
+Hosted Claude Code and Codex harnesses reach platform inference through an
+environment-owned, workspace-local endpoint. The endpoint is available only to
+`bwrap` workspaces with network isolation and is bound to the exact CLI process
+selected by the harness. Platform credentials stay in the environment-owned
+relay rather than the CLI environment, workspace manifest, or child processes.
+Codex therefore uses the environment sandbox instead of starting a nested
+Codex sandbox for process-bound hosted execution.
+The workspace probes its substrate and uses either seccomp notification or a
+ptrace-backed seccomp guard; it does not advertise process-bound connections
+when neither enforcement backend is available.
+
 → [Run & deploy](https://docs.hud.ai/v6/reference/runtime)
 
 ## Train on rewards

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/hud/__init__.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 # Apply patches to third-party libraries early, before other imports
 from . import patches as _patches  # noqa: F401
+from .capabilities import Connection
 from .clients import connect
 from .environment import Environment
 from .eval import (
@@ -38,6 +39,7 @@ from .version import __version__
 __all__ = [
     "Chat",
     "ComposeProject",
+    "Connection",
     "DockerRuntime",
     "Environment",
     "Grade",

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/hud/agents/__init__.py

@@ -1,7 +1,4 @@
-"""Agent implementations.
-
-The robot policy harness lives in :mod:`hud.agents.robot` (requires the ``robot`` extra).
-"""
+"""Agent implementations."""
 
 from __future__ import annotations
 
@@ -15,13 +12,16 @@ from hud.utils.gateway import resolve_gateway_model
 if TYPE_CHECKING:
     from typing import TypeAlias
 
-    from hud.agents.claude import ClaudeAgent, ClaudeSDKAgent, ClaudeSDKConfig
+    from hud.agents.claude import ClaudeAgent, ClaudeCLIAgent, ClaudeCLIConfig
+    from hud.agents.codex import CodexCLIAgent, CodexCLIConfig
     from hud.agents.gemini import GeminiAgent
     from hud.agents.openai import OpenAIAgent
     from hud.agents.openai_compatible import OpenAIChatAgent
     from hud.agents.tool_agent import ToolAgent as MCPAgent
 
-    GatewayAgent: TypeAlias = ClaudeAgent | GeminiAgent | OpenAIAgent | OpenAIChatAgent
+    GatewayAgent: TypeAlias = (
+        ClaudeAgent | ClaudeCLIAgent | CodexCLIAgent | GeminiAgent | OpenAIAgent | OpenAIChatAgent
+    )
 
 
 def create_agent(model: str, **kwargs: Any) -> GatewayAgent:
@@ -46,44 +46,22 @@ def create_agent(model: str, **kwargs: Any) -> GatewayAgent:
     if not settings.api_key:
         raise HudAuthenticationError("HUD_API_KEY is required to create a gateway agent")
 
-    agent_type, model_id = resolve_agent_model(model)
-    kwargs.setdefault("model", model_id)
-    kwargs["gateway"] = True
-    # cls/config_cls are matched unions; the pairing is correct by construction.
-    config = agent_type.config_cls(**kwargs)
-    return agent_type.cls(cast("Any", config))
-
-
-def resolve_agent_model(model: str) -> tuple[AgentType, str]:
-    """Resolve a catalog id/name/slug or an agent type without constructing a client."""
-    agent_type = next((candidate for candidate in AgentType if candidate.value == model), None)
-    if agent_type is not None:
-        return agent_type, model
-    try:
+    if model in {member.value for member in AgentType}:
+        agent_type = AgentType(model)
+    else:
         entry = resolve_gateway_model(model)
-    except HudAuthenticationError:
-        types = ", ".join(candidate.value for candidate in AgentType)
-        raise ValueError(
-            f"Resolving {model!r} needs the HUD model catalog; set HUD_API_KEY, or pass an "
-            f"agent type ({types}) and choose the model with its config."
-        ) from None
-    if entry.sdk_agent_type in ("operator", "gemini_cua"):
-        replacement = "openai" if entry.sdk_agent_type == "operator" else "gemini"
-        raise ValueError(
-            f"The {entry.sdk_agent_type} agent is no longer supported; use {replacement} with a "
-            "supported computer-use model."
-        )
-    try:
         agent_type = AgentType(entry.sdk_agent_type)
-    except ValueError as exc:
-        raise ValueError(f"Model {model!r} has invalid agent type metadata") from exc
-    return agent_type, entry.model_name or model
+        kwargs.setdefault("model", entry.model_name or model)
+    kwargs["gateway"] = True
+    return cast("GatewayAgent", agent_type.cls.load(kwargs))
 
 
 _LAZY_EXPORTS = {
     "ClaudeAgent": ("hud.agents.claude", "ClaudeAgent"),
-    "ClaudeSDKAgent": ("hud.agents.claude", "ClaudeSDKAgent"),
-    "ClaudeSDKConfig": ("hud.agents.claude", "ClaudeSDKConfig"),
+    "ClaudeCLIAgent": ("hud.agents.claude", "ClaudeCLIAgent"),
+    "ClaudeCLIConfig": ("hud.agents.claude", "ClaudeCLIConfig"),
+    "CodexCLIAgent": ("hud.agents.codex", "CodexCLIAgent"),
+    "CodexCLIConfig": ("hud.agents.codex", "CodexCLIConfig"),
     "GeminiAgent": ("hud.agents.gemini", "GeminiAgent"),
     "MCPAgent": ("hud.agents.tool_agent", "ToolAgent"),
     "OpenAIAgent": ("hud.agents.openai", "OpenAIAgent"),
@@ -92,14 +70,15 @@ _LAZY_EXPORTS = {
 
 __all__ = [
     "ClaudeAgent",
-    "ClaudeSDKAgent",
-    "ClaudeSDKConfig",
+    "ClaudeCLIAgent",
+    "ClaudeCLIConfig",
+    "CodexCLIAgent",
+    "CodexCLIConfig",
     "GeminiAgent",
     "MCPAgent",
     "OpenAIAgent",
     "OpenAIChatAgent",
     "create_agent",
-    "resolve_agent_model",
 ]
 
 

hud-0.6.19.dev1/hud/agents/base.py

@@ -0,0 +1,47 @@
+"""Agent ABC: the rollout contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, ClassVar, Generic, Self, cast
+
+from typing_extensions import TypeVar
+
+from hud.agents.types import AgentConfig
+
+if TYPE_CHECKING:
+    from hud.eval.run import Run
+    from hud.utils.serialization import JsonObject
+
+ConfigT_co = TypeVar("ConfigT_co", bound=AgentConfig, covariant=True, default=AgentConfig)
+
+
+class Agent(ABC, Generic[ConfigT_co]):
+    """Drives a live ``Run`` by recording its trajectory and final answer.
+
+    Subclasses implement ``__call__(run)``; callers do ``await agent(run)``. Stateless
+    per run — everything comes from ``run`` — so one instance drives many concurrent
+    rollouts. The caller owns lifecycle status, cancellation, and grading.
+
+    ``config`` is the agent's serializable identity: :meth:`dump` writes it and
+    :meth:`load` rebuilds the agent from it. Subclasses parametrize ``Agent[XConfig]``,
+    set ``config_cls = XConfig`` for construction, and, when they override
+    ``__init__``, call ``super().__init__(config)``.
+    """
+
+    config_cls: ClassVar[type[AgentConfig]] = AgentConfig
+    config: ConfigT_co
+
+    def __init__(self, config: ConfigT_co | None = None) -> None:
+        self.config = config or cast("ConfigT_co", self.config_cls())
+
+    @abstractmethod
+    async def __call__(self, run: Run) -> None:
+        """Fill ``run.trace`` with the trajectory and final answer."""
+
+    def dump(self) -> JsonObject:
+        return self.config.model_dump(mode="json")
+
+    @classmethod
+    def load(cls, data: JsonObject) -> Self:
+        return cls(cast("ConfigT_co", cls.config_cls.model_validate(data)))

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/hud/agents/browser_use/agent.py

@@ -24,7 +24,6 @@ from urllib.parse import urlsplit, urlunsplit
 from hud.agents.base import Agent
 from hud.agents.types import AgentStep, BrowserUseConfig
 from hud.settings import settings
-from hud.types import Step
 
 if TYPE_CHECKING:
     from hud.eval.run import Run
@@ -72,13 +71,10 @@ class _BrowserUseModule(Protocol):
     Agent: _AgentFactory
 
 
-class BrowserUseAgent(Agent):
+class BrowserUseAgent(Agent[BrowserUseConfig]):
     """Run the ``browser-use`` agent against an env's ``cdp/1.3`` capability."""
 
-    config: BrowserUseConfig
-
-    def __init__(self, config: BrowserUseConfig | None = None) -> None:
-        self.config = config or BrowserUseConfig()
+    config_cls = BrowserUseConfig
 
     async def __call__(self, run: Run) -> None:
         """Drive browser-use over the run's CDP capability, filling ``run.trace``.
@@ -107,18 +103,12 @@ class BrowserUseAgent(Agent):
 
         try:
             history = await sdk_agent.run(max_steps=self.config.max_steps)
-        except Exception as exc:
-            LOGGER.exception("browser-use run failed")
-            trace.status = "error"
-            run.record(Step(source="system", error=str(exc)))
-            return
         finally:
             with contextlib.suppress(Exception):
                 await browser.stop()
 
         successful = history.is_successful()
         content = history.final_result() or ""
-        trace.status = "error" if successful is False else "completed"
         trace.content = content
         trace.extra.update(
             {
@@ -133,7 +123,6 @@ class BrowserUseAgent(Agent):
             AgentStep(
                 content=content,
                 done=history.is_done(),
-                error=content if successful is False else None,
             ),
         )
 

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/hud/agents/claude/__init__.py

@@ -7,15 +7,15 @@ from .agent import (
     AsyncAnthropicBedrock,
     ClaudeAgent,
 )
-from .sdk import ClaudeSDKAgent, ClaudeSDKConfig
+from .sdk import ClaudeCLIAgent, ClaudeCLIConfig
 from .tools import ClaudeToolSearchTool, ClaudeWebFetchTool, ClaudeWebSearchTool
 
 __all__ = [
     "AsyncAnthropic",
     "AsyncAnthropicBedrock",
     "ClaudeAgent",
-    "ClaudeSDKAgent",
-    "ClaudeSDKConfig",
+    "ClaudeCLIAgent",
+    "ClaudeCLIConfig",
     "ClaudeToolSearchTool",
     "ClaudeWebFetchTool",
     "ClaudeWebSearchTool",

{hud-0.6.18.dev1 → hud-0.6.19.dev1}/hud/agents/claude/agent.py

@@ -48,6 +48,7 @@ from .tools.mcp_proxy import ClaudeMCPProxyTool
 if TYPE_CHECKING:
     from anthropic.types.beta import BetaTextCitation
 
+
 logger = logging.getLogger(__name__)
 
 ClaudeImageMediaType = Literal["image/jpeg", "image/png", "image/gif", "image/webp"]
@@ -93,6 +94,7 @@ def _stream_retry_delay(attempt: int, error: Exception) -> float:
 class ClaudeAgent(ToolAgent[BetaMessageParam, ClaudeConfig]):
     """Anthropic Claude agent. Drives SSH (coding), RFB (computer), and MCP capabilities."""
 
+    config_cls = ClaudeConfig
     tool_catalog = (
         ClaudeBashTool,
         ClaudeTextEditorTool,
@@ -101,7 +103,7 @@ class ClaudeAgent(ToolAgent[BetaMessageParam, ClaudeConfig]):
     )
 
     def __init__(self, config: ClaudeConfig | None = None) -> None:
-        self.config = config or ClaudeConfig()
+        super().__init__(config)
         self.anthropic_client: AsyncAnthropic | AsyncAnthropicBedrock = self._resolve_client()
 
     def _resolve_client(self) -> AsyncAnthropic | AsyncAnthropicBedrock:
@@ -360,26 +362,36 @@ class ClaudeAgent(ToolAgent[BetaMessageParam, ClaudeConfig]):
         if response is None:
             raise ValueError("Claude response missing after retries")
 
-        result = AgentStep(content="", done=True)
-        result.model = response.model
-        result.usage = Usage(
-            prompt_tokens=response.usage.input_tokens,
-            completion_tokens=response.usage.output_tokens,
-            cached_tokens=response.usage.cache_read_input_tokens,
+        return self.message_to_agent_step(response, citations_enabled=citations_enabled)
+
+    @classmethod
+    def message_to_agent_step(
+        cls,
+        response: BetaMessage,
+        *,
+        citations_enabled: bool = False,
+    ) -> AgentStep:
+        result = AgentStep(
+            content="",
+            done=True,
+            model=response.model,
+            usage=Usage(
+                prompt_tokens=response.usage.input_tokens,
+                completion_tokens=response.usage.output_tokens,
+                cached_tokens=response.usage.cache_read_input_tokens,
+            ),
         )
         text_parts: list[str] = []
         thinking_parts: list[str] = []
-        citations: list[Citation] = []
 
         for block in response.content:
             match block.type:
                 case "tool_use":
-                    arguments = dict(block.input) if block.input else {}
                     result.tool_calls.append(
                         MCPToolCall(
                             id=block.id,
                             name=block.name,
-                            arguments=arguments,
+                            arguments=dict(block.input) if block.input else {},
                             _meta=mcp_types.RequestParams.Meta.model_validate(
                                 {"citations_enabled": citations_enabled},
                             ),
@@ -387,9 +399,8 @@ class ClaudeAgent(ToolAgent[BetaMessageParam, ClaudeConfig]):
                     )
                     result.done = False
                 case "text":
-                    text_block = block
-                    text_parts.append(text_block.text)
-                    citations.extend(self._citation(c) for c in (text_block.citations or []))
+                    text_parts.append(block.text)
+                    result.citations.extend(cls._citation(c) for c in (block.citations or []))
                 case "thinking":
                     if block.thinking:
                         thinking_parts.append(block.thinking)
@@ -397,7 +408,6 @@ class ClaudeAgent(ToolAgent[BetaMessageParam, ClaudeConfig]):
                     pass
 
         result.content = "".join(text_parts)
-        result.citations = citations
         if thinking_parts:
             result.reasoning = "\n".join(thinking_parts)
         result.finish_reason = response.stop_reason

hud-0.6.19.dev1/hud/agents/claude/sdk/__init__.py

@@ -0,0 +1,7 @@
+"""Agent that runs the ``claude`` CLI over SSH."""
+
+from hud.agents.types import ClaudeCLIConfig
+
+from .agent import ClaudeCLIAgent
+
+__all__ = ["ClaudeCLIAgent", "ClaudeCLIConfig"]

hud-0.6.19.dev1/hud/agents/claude/sdk/agent.py

@@ -0,0 +1,219 @@
+"""ClaudeCLIAgent — runs ``claude`` CLI over SSH inside the env workspace.
+
+SSH-execs the ``claude`` CLI on the remote workspace so all built-in tools
+(Bash, Read, Write, Edit, Glob, Grep) operate on the env's filesystem.
+MCP capabilities from the manifest are written as MCP server config so the
+CLI can call env-hosted MCP tools too.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shlex
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any, cast
+
+import asyncssh
+
+from hud.agents.base import Agent
+from hud.agents.cli import (
+    PROCESS_BOUND_CREDENTIAL,
+    WINDOWS_SHELLS,
+    powershell,
+    powershell_quote,
+    resolve_executable,
+    run_jsonl,
+)
+from hud.agents.types import ClaudeCLIConfig
+from hud.settings import settings
+from hud.telemetry.context import get_trace_headers
+from hud.utils.gateway import routes_to_gateway
+from hud.utils.time import now_iso
+
+from . import computer_mcp
+from .events import ClaudeEvents
+
+if TYPE_CHECKING:
+    from hud.capabilities import Connection, SSHClient
+    from hud.eval.run import Run
+
+logger = logging.getLogger(__name__)
+
+INPUT_PATH = ".hud_input.jsonl"
+MCP_CONFIG_PATH = ".hud_mcp_config.json"
+RUN_SCRIPT_PATH = ".hud_run.bat"
+
+_MANAGED_CLAUDE_PATHS = {
+    "linux-x64": "/usr/local/lib/agents/claude/linux-x64/claude",
+    "linux-x64-musl": "/usr/local/lib/agents/claude/linux-x64-musl/claude",
+}
+
+
+class ClaudeCLIAgent(Agent[ClaudeCLIConfig]):
+    """Runs ``claude`` CLI over SSH inside the env workspace.
+
+    Stateless w.r.t. the env: driven by ``await agent(run)``. SSH is opened
+    live off the run. Environment MCP bindings are used directly; computer MCP
+    servers are bridged over the run's SSH connection.
+    """
+
+    config_cls = ClaudeCLIConfig
+
+    async def __call__(self, run: Run) -> None:
+        ssh = cast("SSHClient", await run.client.open("ssh"))
+        manifest = run.client.manifest
+        assert manifest is not None
+        shell = ssh.capability.params.get("shell", "bash")
+        windows = shell in WINDOWS_SHELLS
+        connection: Connection | None = run.connections.get("inference")
+        executable = await resolve_executable(
+            ssh, "claude", _MANAGED_CLAUDE_PATHS, run.runtime_config
+        )
+        rfb_count = sum(cap.protocol.partition("/")[0] == "rfb" for cap in manifest.bindings)
+
+        async with AsyncExitStack() as resources:
+            mcp_servers: dict[str, dict[str, Any]] = {}
+            for cap in manifest.bindings:
+                family = cap.protocol.partition("/")[0]
+                if family == "mcp":
+                    name = cap.name
+                    transport = "http" if cap.params["transport"] == "streamable-http" else "sse"
+                    server: dict[str, Any] = {"type": transport, "url": cap.url}
+                    if token := cap.params.get("auth_token"):
+                        server["headers"] = {"Authorization": f"Bearer {token}"}
+                elif family == "rfb":
+                    name = "computer-use" if rfb_count == 1 else f"computer-use-{cap.name}"
+                    server = await resources.enter_async_context(
+                        computer_mcp.bridge_computer_mcp(
+                            ssh,
+                            run.client.binding(cap.name),
+                            self.config.screenshot_encoding,
+                            shell=shell,
+                        )
+                    )
+                else:
+                    continue
+                if name in mcp_servers:
+                    raise RuntimeError(f"duplicate MCP server name {name!r}")
+                mcp_servers[name] = server
+
+            env: dict[str, str] = {
+                "ANTHROPIC_MODEL": self.config.model,
+                "ANTHROPIC_SMALL_FAST_MODEL": self.config.model,
+                "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+                "DISABLE_AUTOUPDATER": "1",
+                "IS_SANDBOX": "1",
+            }
+            if connection is not None or routes_to_gateway(
+                "anthropic", gateway=self.config.gateway
+            ):
+                if connection is not None:
+                    # The relay injects the scoped credential; the process never sees it.
+                    # AUTH_TOKEN sends Authorization: Bearer, the header Codex uses too.
+                    env["ANTHROPIC_BASE_URL"] = connection.client_url
+                    env["ANTHROPIC_AUTH_TOKEN"] = PROCESS_BOUND_CREDENTIAL
+                elif settings.api_key:
+                    env["ANTHROPIC_BASE_URL"] = settings.hud_gateway_url
+                    env["ANTHROPIC_API_KEY"] = settings.api_key
+                else:
+                    raise ValueError("HUD_API_KEY is required for HUD gateway routing")
+                env["CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS"] = "1"
+                env["DISABLE_AUTO_COMPACT"] = "1"
+                # Alias every model tier so background requests never bypass the gateway.
+                env["ANTHROPIC_DEFAULT_SONNET_MODEL"] = self.config.model
+                env["ANTHROPIC_DEFAULT_OPUS_MODEL"] = self.config.model
+                env["ANTHROPIC_DEFAULT_HAIKU_MODEL"] = self.config.model
+                env["CLAUDE_CODE_SUBAGENT_MODEL"] = self.config.model
+                if connection is None and (trace_headers := get_trace_headers()):
+                    env["ANTHROPIC_CUSTOM_HEADERS"] = "\n".join(
+                        f"{name}: {value}" for name, value in trace_headers.items()
+                    )
+            elif settings.anthropic_api_key:
+                env["ANTHROPIC_API_KEY"] = settings.anthropic_api_key
+
+            args = [
+                "--verbose",
+                "--input-format=stream-json",
+                "--output-format=stream-json",
+                "--print",
+                f"--permission-mode={self.config.permission_mode}",
+            ]
+            if self.config.max_steps > 0:
+                args.append(f"--max-turns={self.config.max_steps}")
+            if self.config.system_prompt:
+                args.extend(["--system-prompt", self.config.system_prompt])
+            for tool in self.config.allowed_tools:
+                args.extend(["--allowedTools", tool])
+            if mcp_servers:
+                args.extend(["--mcp-config", MCP_CONFIG_PATH])
+
+            if windows:
+                script = ";".join(
+                    [
+                        *(f"$env:{key}={powershell_quote(value)}" for key, value in env.items()),
+                        f"Get-Content -Raw -Encoding UTF8 {powershell_quote(INPUT_PATH)}"
+                        f" | & {powershell_quote(executable)} "
+                        f"{' '.join(powershell_quote(arg) for arg in args)}",
+                        "exit $LASTEXITCODE",
+                    ]
+                )
+                command = powershell(script)
+            else:
+                env_prefix = " ".join(f"{key}={shlex.quote(value)}" for key, value in env.items())
+                cli = " ".join(shlex.quote(arg) for arg in [executable, *args])
+                invocation = f"{env_prefix} {cli}"
+                if connection is not None:
+                    # A guarded connection is bound to the launched process, so exec the CLI itself.
+                    invocation = f"exec env {invocation}"
+                command = f'export PATH="$HOME/.local/bin:$PATH"; {invocation}'
+
+            input_text = (
+                json.dumps(
+                    {
+                        "type": "user",
+                        "message": {
+                            "role": "user",
+                            "content": [{"type": "text", "text": run.prompt_text}],
+                        },
+                    }
+                )
+                + "\n"
+            )
+            files: list[str] = []
+            try:
+                if mcp_servers:
+                    await ssh.write_text(
+                        MCP_CONFIG_PATH, json.dumps({"mcpServers": mcp_servers}, indent=2)
+                    )
+                    files.append(MCP_CONFIG_PATH)
+                if windows:
+                    await ssh.write_text(INPUT_PATH, input_text)
+                    await ssh.write_text(RUN_SCRIPT_PATH, f"@echo off\r\n{command}\r\n")
+                    files += [INPUT_PATH, RUN_SCRIPT_PATH]
+                    command = f"cmd /c {RUN_SCRIPT_PATH}"
+
+                logger.info("SSH exec claude CLI (%d chars)", len(command))
+                events = ClaudeEvents(run, started_at=now_iso())
+                returncode, stderr = await run_jsonl(
+                    ssh,
+                    command,
+                    events.consume,
+                    input_text=None if windows else input_text,
+                    connections=(connection,) if connection is not None else (),
+                )
+                logger.info("exit=%s stderr=%d", returncode, len(stderr))
+                events.finish(returncode=returncode, stderr=stderr)
+            finally:
+                if files:
+                    if windows:
+                        cleanup = f"cmd /c del /f /q {' '.join(files)} 2>nul"
+                    else:
+                        cleanup = "rm -f -- " + " ".join(shlex.quote(path) for path in files)
+                    try:
+                        await ssh.run(cleanup, check=False)
+                    except (OSError, asyncssh.Error):
+                        logger.warning("Failed to remove Claude CLI runtime files")
+
+
+__all__ = ["ClaudeCLIAgent"]