fwdit 0.1.2__py3-none-any.whl

fwd/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: fwd
+description: Move a coding project or active Claude Code/Codex workflow to remote compute with fwd. Use for remote development, SSH, RunPod, Lambda Cloud, Slurm, extra CPU/GPU/memory, persistent remote agents, durable commands, synchronization, attaching, stopping, or destroying remote sessions.
+---
+
+# fwd remote development
+
+Use `fwd` to provision or reuse remote compute, synchronize the current project, prepare its tools, and run a persistent coding agent or command in tmux. Invoking this skill means the user wants fwd used.
+
+## Workflow
+
+1. Preserve the user's task, requested target, hardware, and shutdown requirements. Use the caller's agent (`codex` from Codex, `claude` from Claude) unless the user specifies another.
+2. If a provider machine must be chosen, inspect exact values before launch with `fwd up --machines` or `fwd up TARGET --machines`. Prefer CPU unless the user requests a GPU; never guess or abbreviate a provider identifier.
+3. Launch without taking over the terminal: `fwd up --detach --agent AGENT`, adding `--target TARGET` and `--machine MACHINE` only when selected. Never use a bare/reuse/attach form as a tool call.
+4. Read the exact session name and live state from `fwd ls --json`.
+5. Send the preserved task with `fwd send --name SESSION agent "TASK"`. Stream and iterate by default; use `--detach` only when the user asks to background the task.
+6. Inspect changed work with `fwd diff -q SESSION`, use `fwd diff SESSION` when details matter, and retrieve accepted files with `fwd pull --name SESSION`.
+7. Report the result and exact commands the user may need, especially `fwd attach SESSION`, `fwd send --name SESSION --ls`, and `fwd stop SESSION`.
+
+If setup is required, follow the exact flags printed by fwd. Do not open an interactive setup wizard or invent target values.
+
+For a requested shell command instead of agent work, use `fwd send --name SESSION -- COMMAND...`. Reattach with `fwd send --name SESSION TASK_ID`; cancel only that task with `fwd send --name SESSION TASK_ID --stop`.
+
+If `fwd` is unavailable, install the published distribution with `uv tool install fwdit`. If `uv` is unavailable, report that Python 3.12+, `uv`, `ssh`, and `rsync` are required instead of improvising another installer.
+
+## Safe automation
+
+- Prefer `--json` for `fwd ls`, `fwd doctor`, `fwd info`, and task listings. Diagnostics remain on stderr.
+- Never run bare `fwd`, `fwd TARGET`, `fwd attach`, `fwd a`, `fwd up --reuse`, or `fwd up --attach` as a tool call; they can take over a human terminal. Hand the exact attach command to the user.
+- Do not use `--restart` unless the user authorizes restarting stopped billable compute.
+- Do not use `--creds` unless the user authorizes copying live Claude credentials. GitHub setup defaults on; use `--no-setup-github` when credentials must stay local.
+- Never force `stop`, `rm`, or stop-after past a dirty or unreachable worktree unless the user explicitly accepts losing remote-only changes.
+- Never run `fwd rm --all --force` unless the user explicitly requests destruction of every tracked remote resource.
+- Run `fwd uninstall --force` only for an explicit local-uninstall request after explaining that it does not destroy remote resources; prefer `fwd rm --all` first.
+- Prefer `fwd diff -q` before push or pull. Exit 0 means synchronized, 1 different, and 2 error.
+- If upload exceeds `sync.max_size_gb`, confirm the directory is intentional before using the exact project-scoped limit command printed by fwd.
+- Missing `npx` or a failed optional skill refresh must not block normal fwd commands.
+- If preparation fails after provisioning and sync, give the human `fwd attach SESSION --raw` for a recovery shell. This does not authorize restarting stopped compute.
+
+## Stop after work
+
+For supported backends, use remote-owned shutdown so it survives local disconnection:
+
+```sh
+fwd up --stop-after -- COMMAND...
+fwd send --name SESSION --stop-after agent "TASK"
+fwd send --name SESSION stopafter
+fwd send --name SESSION cancel stopafter
+```
+
+Confirm the lifecycle task with `fwd send --name SESSION --ls --json`. Stop-after refuses a dirty remote worktree; never force it without explicit acceptance of data loss.
+
+Lambda does not support remote stop-after because its broad API key stays local. Retrieve durable results, then tell the user to run `fwd stop SESSION` from a connected machine.
+
+## Useful commands
+
+```sh
+fwd up --detach --target runpod --agent codex
+fwd up --detach --new --target runpod --agent codex
+fwd up -- COMMAND...
+fwd send --name SESSION agent "TASK"
+fwd send --name SESSION -- COMMAND...
+fwd send --name SESSION --ls --json
+fwd diff -q SESSION
+fwd pull --name SESSION outputs/
+fwd ls --all-projects --json
+fwd doctor --json
+```
+
+## References
+
+- Read [targets and configuration](references/targets-and-config.md) for resolution, setup, defaults, machines, and backend behavior.
+- Read [commands and lifecycle](references/commands-and-lifecycle.md) for launch, durable tasks, synchronization, ports, attachment, stopping, and destruction.
+- Read [agent transfer](references/agent-transfer.md) before launching Claude Code or Codex when transcripts, settings, skills, authentication, or remote control matter.
+
+`fwd --help` and `fwd COMMAND --help` are authoritative for the installed version.

fwd/__init__.py

@@ -0,0 +1,22 @@
+"""fwd — move local coding work and agent sessions to remote compute.
+
+The package is layered deliberately so that each layer can be developed and tested in isolation:
+
+- ``sshexec``      : the only place that shells out to ``ssh``; everything remote goes through an ``SSHEndpoint``.
+- ``config``/``state`` : pure data layers (TOML config, ``~/.fwd/state.json``) with no side effects beyond file IO.
+- ``backends/*``   : provisioning strategies behind the ``Provisioner`` protocol; they return a ``TargetInfo`` and know nothing about Claude.
+- ``sync``/``remote`` : mechanical project and remote-environment setup.
+- ``agents/*``     : class-based coding-agent integrations and their state-transfer helpers.
+- ``ops/*``        : orchestration of the above into user-facing operations.
+- ``cli``          : thin Typer surface that only parses flags and delegates to ``ops``.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    # The distribution is named fwdit because the fwd name is owned by an unrelated PyPI project; the import package and command intentionally remain fwd.
+    __version__ = version("fwdit")
+except PackageNotFoundError:
+    # Keep source-tree imports useful before the project has been installed, while installed builds always report their tag-derived package metadata.
+    __version__ = "0.0.0"

fwd/agents/README.md

@@ -0,0 +1,71 @@
+# Adding a coding agent
+
+Coding-agent integrations are class-based plugins inside this package. General launch, attach, and send code depends
+only on `Agent`, so a new built-in agent should normally require one new Python module plus one registry entry.
+
+## Implement the contract
+
+Create `src/fwd/agents/<name>.py` and subclass `Agent` from `base.py`:
+
+```python
+from typing import Mapping
+
+from fwd.agents.base import Agent
+from fwd.tooling.requirements import MY_AGENT
+
+
+class MyAgent(Agent):
+    name = "my-agent"
+    command = ("my-agent",)
+    tools = (MY_AGENT,)
+
+    def startup_command(self, flags: Mapping[str, object]) -> str:
+        return "my-agent"
+
+    def send_command(self, message: str, flags: Mapping[str, object], *, tmux_session: str = "", remote_dir: str = "") -> tuple[str, ...]:
+        return ("my-agent", "--print", message)
+```
+
+`name` is the magic `fwd up <name>` selector. `command` is persisted in session state and must uniquely resolve the
+agent. `tools` uses the shared requirement resolver, which reuses working remote binaries before attempting installs.
+
+Every agent automatically receives the shared `[agents.<name>]` runtime policy from `Agent.launch_flags()`:
+`full_access`, `args`, and environment defaults. Use `runtime_args()`, `with_environment_defaults()`, and
+`environment_command()` in the implementation so interactive, restarted, and non-interactive send commands behave
+consistently. An implementation owns the exact full-access CLI option and must suppress its default when configured
+arguments already select a permission or sandbox policy.
+
+Override `prepare_local()` when an agent must create files before the project sync. The returned object is opaque to
+the launcher and is passed to `prepare_remote()` after bootstrap and tool installation. Override `prepare_remote()`
+to upload settings or import conversation state, and return serializable flags needed by `startup_command()` or a
+later restart. Keep optional state transfer best-effort: failure to copy convenience state should not discard a
+successfully provisioned machine.
+
+Set `remote_home_entry` to the product-owned hidden directory when authentication, conversations, or managed payloads
+live beneath remote `$HOME`. Backends with disposable homes ask the shared base implementation to relocate that
+directory beneath the tool prefix before resolving tools; other backends leave the user's home untouched.
+
+Override `launch_flags()` only if the agent owns special CLI/config behavior. Agent-independent orchestration should
+never test `agent.name`; put that decision in the implementation instead.
+
+Override `prepare_send()` when an agent needs a remote helper before constructing its turn command. `send_command()`
+receives the exact primary tmux session and remote project directory so a pane-backed integration can address the
+long-lived conversation rather than guessing from global history.
+
+Optional remote-control setup also belongs in the agent implementation because products expose different models.
+Claude decorates its long-lived interactive command, while Codex starts a separate managed app-server daemon beside
+the primary TUI. Probe both CLI support and compatible account authentication, degrade to the normal terminal session
+when unavailable, and never make remote-control enrollment a prerequisite for launching the agent.
+Codex must invoke the standalone binary at `~/.codex/packages/standalone/current/codex` for daemon probes and startup;
+the npm/Bun CLI exposing the same subcommand help does not establish that the managed daemon payload is installed.
+
+## Register and test it
+
+Import and instantiate the class in `agents/__init__.py`. The registry is explicit so CLI startup, packaging, and
+tests remain deterministic.
+
+Add focused tests for exact command resolution, required tools, startup/send argv, and any state-transfer safety
+rules. If the agent copies user files, use a strict allowlist and exclude authentication by default.
+
+Agent-specific state helpers belong in this package (for example `claude_state.py` and `codex_state.py`), beside the
+class that owns them. Do not add agent branches to `ops/launch.py`, `ops/send.py`, or the bootstrap script.

fwd/agents/__init__.py

@@ -0,0 +1,27 @@
+"""Class-based coding-agent registry.
+
+Each supported coding agent lives in one module and implements :class:`Agent`. The launch and send layers consume
+only that contract, which keeps agent-specific state transfer and command construction out of general orchestration.
+"""
+
+from __future__ import annotations
+
+from fwd.agents.base import Agent, AgentLaunchOptions
+from fwd.agents.claude import ClaudeAgent
+from fwd.agents.codex import CodexAgent
+
+AGENTS: dict[str, Agent] = {agent.name: agent for agent in (ClaudeAgent(), CodexAgent())}
+
+# Compatibility name for integrations written against the original data-only registry. It deliberately aliases the
+# richer class contract rather than preserving a second abstraction.
+AgentSpec = Agent
+
+
+def resolve(command: tuple[str, ...]) -> Agent | None:
+    """Return the registered agent for an exact magic command, otherwise ``None``."""
+    if len(command) != 1:
+        return None
+    return AGENTS.get(command[0])
+
+
+__all__ = ["AGENTS", "Agent", "AgentLaunchOptions", "AgentSpec", "resolve"]

fwd/agents/base.py

@@ -0,0 +1,127 @@
+"""Common contract for remotely hosted coding agents.
+
+The launch pipeline has three agent extension points: prepare local state before project synchronization, prepare
+remote state after tools are installed, and build the long-lived command placed in tmux. Send support belongs here
+too, so the CLI never needs to branch on an agent name.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import shlex
+from typing import Any, Mapping
+
+from fwd.config import Config
+from fwd.sshexec import SSHEndpoint
+from fwd.tooling import ToolRequirement
+from fwd.agents.remote_state import install_persistent_home
+
+ENVIRONMENT_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentLaunchOptions:
+    """Agent-related CLI switches passed to every implementation.
+
+    The current switches describe Claude's optional transfer modes. Other agents reject unsupported non-default
+    options through :meth:`Agent.launch_flags`; a future cross-agent option can be added here without changing launch
+    orchestration.
+    """
+
+    session: bool = False
+    handoff: bool = False
+    user_config: bool = False
+    creds: bool = False
+
+    def any(self) -> bool:
+        """Return whether the caller explicitly requested any agent-specific behavior."""
+        return any((self.session, self.handoff, self.user_config, self.creds))
+
+
+class Agent(ABC):
+    """Base class every built-in coding agent implements.
+
+    Implementations own their executable requirements, state/config transfer, startup and resume commands, and send
+    protocol. General launch orchestration calls these hooks at fixed lifecycle points and treats the returned local
+    state as opaque, so adding an agent does not require editing the launch pipeline.
+    """
+
+    name: str
+    command: tuple[str, ...]
+    tools: tuple[ToolRequirement, ...]
+    remote_home_entry: str | None = None
+
+    def launch_flags(self, config: Config, options: AgentLaunchOptions) -> dict[str, Any]:
+        """Resolve CLI/config options into serializable session flags.
+
+        Agents with no special launch flags accept only the default option set. This catches accidental use of
+        Claude-only switches without teaching the orchestrator which implementation owns them.
+        """
+        if options.any():
+            raise ValueError(f"agent {self.name!r} does not support --session, --handoff, --user-config, or --creds")
+        runtime = config.agent(self.name)
+        invalid_names = sorted(name for name in runtime.environment if not ENVIRONMENT_NAME.fullmatch(name))
+        if invalid_names:
+            raise ValueError(f"agent {self.name!r} has invalid environment variable name(s): {', '.join(invalid_names)}")
+        return {
+            "agent_full_access": runtime.full_access,
+            "agent_args": list(runtime.args),
+            "agent_environment": dict(runtime.environment),
+        }
+
+    def runtime_args(self, flags: Mapping[str, object]) -> list[str]:
+        """Return the configured argv extension recorded with the session."""
+        value = flags.get("agent_args")
+        return [str(part) for part in value] if isinstance(value, list) else []
+
+    def with_environment_defaults(self, command: str, flags: Mapping[str, object]) -> str:
+        """Export configured variables only when the remote shell has not already defined them."""
+        value = flags.get("agent_environment")
+        if not isinstance(value, dict) or not value:
+            return command
+        exports = []
+        for name, default in value.items():
+            if not isinstance(name, str) or not ENVIRONMENT_NAME.fullmatch(name):
+                continue
+            exports.append(f'[ "${{{name}+x}}" = x ] || export {name}={shlex.quote(str(default))}')
+        return f"{'; '.join(exports)}; exec {command}" if exports else command
+
+    def environment_command(self, command: list[str], flags: Mapping[str, object]) -> tuple[str, ...]:
+        """Return argv for a non-interactive agent command with the same environment defaults as the TUI."""
+        plain = shlex.join(command)
+        wrapped = self.with_environment_defaults(plain, flags)
+        return tuple(command) if wrapped == plain else ("bash", "-lc", wrapped)
+
+    def prepare_local(self, local_cwd: Path, flags: dict[str, Any]) -> object | None:
+        """Prepare state that must exist before project synchronization and return opaque transfer state."""
+        del local_cwd, flags
+        return None
+
+    def prepare_remote_home(self, endpoint: SSHEndpoint, tool_prefix: str, *, ephemeral: bool) -> None:
+        """Relocate product-owned home state when the backend reports that the normal remote home is disposable."""
+        if ephemeral and self.remote_home_entry is not None:
+            install_persistent_home(endpoint, tool_prefix, self.remote_home_entry)
+
+    def prepare_remote(self, endpoint: SSHEndpoint, remote_dir: str, flags: dict[str, Any], local_state: object | None) -> dict[str, Any]:
+        """Install settings/state after bootstrap and return additional serializable session flags."""
+        del endpoint, remote_dir, flags, local_state
+        return {}
+
+    def restart_command(self, flags: Mapping[str, object]) -> str:
+        """Build the command used when restarting an existing session without retransferring state."""
+        return self.startup_command(flags)
+
+    @abstractmethod
+    def startup_command(self, flags: Mapping[str, object]) -> str:
+        """Build the long-lived command placed in the session's primary tmux pane."""
+
+    def prepare_send(self, endpoint: SSHEndpoint, flags: Mapping[str, object]) -> None:
+        """Ensure optional remote helpers required by a later send command are ready."""
+        del endpoint, flags
+
+    @abstractmethod
+    def send_command(self, message: str, flags: Mapping[str, object], *, tmux_session: str = "", remote_dir: str = "") -> tuple[str, ...]:
+        """Build a command that sends one message into the agent's current conversation."""

fwd/agents/claude.py

@@ -0,0 +1,178 @@
+"""Claude Code agent integration.
+
+Claude is the most stateful built-in agent: local preparation may export a transcript or generate a handoff document,
+while remote preparation can upload config, credentials, and the relocated transcript. Those details live here so
+the general launch pipeline sees the same hooks it sees for Codex or any future agent.
+"""
+
+from __future__ import annotations
+
+import shlex
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Mapping
+
+from fwd import ui
+from fwd.agents.base import Agent, AgentLaunchOptions
+from fwd.agents import claude_state
+from fwd.config import Config
+from fwd.sshexec import SSHEndpoint
+from fwd.tooling.requirements import CLAUDE
+
+HANDOFF_PROMPT = "Read HANDOFF.md, then continue the work it describes"
+HANDOFF_MAX_AGE_SECONDS = 15 * 60
+
+
+def build_command(*, resume_id: str | None, use_handoff: bool, remote_control_name: str | None = None, runtime_args: tuple[str, ...] = ()) -> str:
+    """Build a Claude startup command with the selected context and optional cross-device control."""
+    command = ["claude", *runtime_args]
+    if resume_id:
+        command.extend(("--resume", resume_id))
+    elif use_handoff:
+        command.append(HANDOFF_PROMPT)
+    plain_command = shlex.join(command)
+    if not remote_control_name:
+        return plain_command
+    remote_command = shlex.join(["claude", "--remote-control", remote_control_name, *command[1:]])
+    fallback = f"{remote_command} || {{ printf '%s\\n' 'Claude Remote Control unavailable; starting a normal terminal session.' >&2; exec {plain_command}; }}"
+    return f"bash -lc {shlex.quote(fallback)}"
+
+
+def _remote_control_status(endpoint: SSHEndpoint) -> int:
+    """Return 0 when Remote Control can start, 2 when supported but not account-authenticated, or 1 when absent."""
+    probe = endpoint.run(
+        "claude --help 2>&1 | grep -q -- '--remote-control' || exit 1; "
+        "status=$(claude auth status --json 2>/dev/null) || exit 2; "
+        "printf %s \"$status\" | grep -Eq '\"authMethod\"[[:space:]]*:[[:space:]]*\"claude\\.ai\"' || exit 2; "
+        "printf %s \"$status\" | grep -Eq '\"subscriptionType\"[[:space:]]*:[[:space:]]*\"(pro|max|team|enterprise)\"' || exit 2; "
+        "printf fwd-claude-remote-control-ready",
+        check=False,
+    )
+    if probe.returncode == 2:
+        return 2
+    return 0 if probe.returncode == 0 and probe.stdout.strip() == "fwd-claude-remote-control-ready" else 1
+
+
+def fresh_handoff(local_cwd: Path) -> Path | None:
+    """Return a recent HANDOFF.md so repair launches avoid another expensive local agent run."""
+    handoff = local_cwd / "HANDOFF.md"
+    if not handoff.is_file():
+        return None
+    try:
+        age = time.time() - handoff.stat().st_mtime
+    except OSError:
+        return None
+    return handoff if 0 <= age < HANDOFF_MAX_AGE_SECONDS else None
+
+
+class ClaudeAgent(Agent):
+    """Transfer optional Claude state and construct commands that resume the same conversation."""
+
+    name = "claude"
+    command = ("claude",)
+    tools = (CLAUDE,)
+    remote_home_entry = ".claude"
+
+    def launch_flags(self, config: Config, options: AgentLaunchOptions) -> dict[str, Any]:
+        """Merge explicit transfer switches with Claude config, preserving handoff/session precedence."""
+        runtime_flags = super().launch_flags(config, AgentLaunchOptions())
+        if options.handoff:
+            want_session, want_handoff = False, True
+        elif options.session:
+            want_session, want_handoff = True, config.claude.handoff
+        else:
+            want_session, want_handoff = config.claude.session, config.claude.handoff
+        return {
+            **runtime_flags,
+            "session": want_session,
+            "handoff": want_handoff,
+            "user_config": options.user_config or config.claude.user_config,
+            "creds": options.creds or config.claude.creds,
+        }
+
+    def _runtime_args(self, flags: Mapping[str, object]) -> list[str]:
+        """Apply bypassPermissions by default while respecting an explicitly configured permission-mode argument."""
+        configured = self.runtime_args(flags)
+        permission_flags = {"--permission-mode", "--dangerously-skip-permissions", "--allow-dangerously-skip-permissions"}
+        has_permission_mode = any(part in permission_flags or part.startswith("--permission-mode=") for part in configured)
+        access = ["--permission-mode", "bypassPermissions"] if bool(flags.get("agent_full_access", True)) and not has_permission_mode else []
+        return [*access, *configured]
+
+    def prepare_local(self, local_cwd: Path, flags: dict[str, Any]) -> object | None:
+        """Export a resumable transcript and ensure any requested handoff is present before project sync."""
+        bundle: Path | None = None
+        if flags["session"]:
+            with ui.step("Exporting Claude session transcript"):
+                bundle = claude_state.export_session_bundle(local_cwd, Path(tempfile.mkdtemp(prefix="fwd-session-")))
+            if bundle is None:
+                flags["session"] = False
+                if flags["handoff"]:
+                    ui.info("falling back to a handoff document")
+        if flags["handoff"]:
+            existing = fresh_handoff(local_cwd)
+            if existing is not None:
+                age = (time.time() - existing.stat().st_mtime) / 60
+                ui.info(f"reusing HANDOFF.md from {age:.0f} min ago (delete it to force regeneration)")
+            else:
+                with ui.step("Generating HANDOFF.md"):
+                    claude_state.make_handoff(local_cwd)
+        return bundle
+
+    def prepare_remote(self, endpoint: SSHEndpoint, remote_dir: str, flags: dict[str, Any], local_state: object | None) -> dict[str, Any]:
+        """Install requested state, import the transcript, and enable supported cross-device control."""
+        if flags["user_config"]:
+            with ui.step("Uploading Claude user config"):
+                claude_state.upload_user_config(endpoint)
+        if flags["creds"]:
+            creds_json: str | None = None
+            with ui.step("Copying Claude credentials"):
+                creds_json = claude_state.read_keychain_creds()
+                if creds_json:
+                    claude_state.upload_creds(endpoint, creds_json)
+            if creds_json:
+                ui.warn("a live Claude token now exists on the remote machine at ~/.claude/.credentials.json (mode 600)")
+            else:
+                ui.warn("no local Claude credentials found; you will need to log in inside the remote session")
+
+        resume_id: str | None = None
+        if isinstance(local_state, Path):
+            with ui.step("Importing Claude session transcript"):
+                remote_home = endpoint.run('printf %s "$HOME"').stdout.strip() or f"/home/{endpoint.user}"
+                resume_id = claude_state.import_session_bundle(endpoint, local_state, remote_dir, remote_home)
+        if flags["session"] and not resume_id:
+            if flags["handoff"]:
+                ui.warn("could not install the transcript remotely; the session will start from HANDOFF.md instead")
+            else:
+                ui.warn(f"could not install the transcript remotely; starting a fresh session (try {ui.command('up --handoff')!r})")
+        remote_control_name: str | None = None
+        remote_control_status = _remote_control_status(endpoint)
+        if remote_control_status == 0:
+            remote_control_name = f"fwd: {Path(remote_dir).name}"
+            ui.info(f"Claude Remote Control enabled as {remote_control_name!r}")
+        elif remote_control_status == 2:
+            ui.info("Claude Remote Control is installed but requires a claude.ai Pro, Max, Team, or Enterprise login on the remote")
+        return {"resume_id": resume_id, "remote_control_name": remote_control_name}
+
+    def startup_command(self, flags: Mapping[str, object]) -> str:
+        """Start Claude with the context chosen during this launch."""
+        resume_id = flags.get("resume_id")
+        command = build_command(
+            resume_id=resume_id if isinstance(resume_id, str) else None,
+            use_handoff=bool(flags.get("handoff")) and not resume_id,
+            remote_control_name=flags.get("remote_control_name") if isinstance(flags.get("remote_control_name"), str) else None,
+            runtime_args=tuple(self._runtime_args(flags)),
+        )
+        return self.with_environment_defaults(command, flags)
+
+    def send_command(self, message: str, flags: Mapping[str, object], *, tmux_session: str = "", remote_dir: str = "") -> tuple[str, ...]:
+        """Send a streaming Claude turn, resuming the exact transferred conversation when known."""
+        del tmux_session, remote_dir
+        command = ["claude", *self._runtime_args(flags), "--print", "--verbose", "--output-format", "stream-json"]
+        resume_id = flags.get("resume_id")
+        if isinstance(resume_id, str) and resume_id:
+            command.extend(("--resume", resume_id))
+        else:
+            command.append("--continue")
+        command.append(message)
+        return self.environment_command(command, flags)