optio-claudecode 0.1.0__py3-none-any.whl

optio_claudecode/__init__.py

@@ -0,0 +1,48 @@
+"""optio-claudecode — run Anthropic Claude Code as an optio task."""
+
+import logging as _logging
+
+from optio_agents import HookContext, HookContextProtocol
+from optio_host import (
+    HostCommandError,
+    RunResult,
+    SSHConfig,
+)
+
+from optio_claudecode.session import create_claudecode_task, run_claudecode_session
+from optio_claudecode.types import (
+    ClaudeCodeTaskConfig,
+    DeliverableCallback,
+    HookCallback,
+    PermissionMode,
+)
+from optio_claudecode.seed_manifest import (
+    CLAUDE_SEED_MANIFEST,
+    CLAUDE_SEED_SUFFIX,
+    delete_seed,
+    list_seeds,
+)
+
+
+# asyncssh emits per-connection INFO lines that flood worker stdout
+# once an SSH-backed session starts. Quiet by default.
+_logging.getLogger("asyncssh").setLevel(_logging.WARNING)
+
+
+__all__ = [
+    "create_claudecode_task",
+    "run_claudecode_session",
+    "ClaudeCodeTaskConfig",
+    "DeliverableCallback",
+    "HookCallback",
+    "PermissionMode",
+    "SSHConfig",
+    "HookContext",
+    "HookContextProtocol",
+    "HostCommandError",
+    "RunResult",
+    "CLAUDE_SEED_MANIFEST",
+    "CLAUDE_SEED_SUFFIX",
+    "delete_seed",
+    "list_seeds",
+]

optio_claudecode/host_actions.py

@@ -0,0 +1,424 @@
+"""Claudecode-specific actions over a generic Host.
+
+Free functions; each takes a Host or HookContext and uses only generic
+primitives (run_command, resolve_host_home, etc.). No isinstance branches.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import shlex
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from optio_agents import HookContextProtocol
+    from optio_host import Host
+    from optio_host.host import ProcessHandle
+
+
+# ttyd's ready banner takes a few forms across versions:
+#   * 1.7.x with lws logging:  "N:  Listening on port: 33449"
+#   * older builds:            "Listening on port 7681"
+#   * some forks log a URL:    "[INFO] listening on http://127.0.0.1:7681/"
+# The `port[\s:]+` branch covers the first two (colon OR whitespace
+# between "port" and the digits). The URL branch covers the third.
+# Both expose the captured port number as the first non-None group.
+_TTYD_READY_RE = re.compile(
+    r"(?:port[\s:]+(\d+))|(?:http://[^\s]+?:(\d+)(?:/|\s|$))"
+)
+
+
+_DEFAULT_INSTALL_SUBDIR = ".local/bin"
+
+_CLAUDE_INSTALL_URL = "https://claude.ai/install.sh"
+
+# Pinned ttyd version. Update with care; the URL pattern below is
+# tsl0922/ttyd's release-asset convention as of 1.7.x.
+_TTYD_VERSION = "1.7.7"
+_TTYD_RELEASE_BASE = (
+    f"https://github.com/tsl0922/ttyd/releases/download/{_TTYD_VERSION}"
+)
+
+
+async def _resolve_install_dir(host: "Host", install_dir: str | None) -> str:
+    """Return ``install_dir`` if given, else ``<host_home>/<DEFAULT_INSTALL_SUBDIR>``."""
+    if install_dir is not None:
+        return install_dir
+    host_home = await host.resolve_host_home()
+    return f"{host_home}/{_DEFAULT_INSTALL_SUBDIR}"
+
+
+async def _claude_present(host: "Host", claude_path: str) -> bool:
+    """Return True iff ``claude_path`` is an executable file on the host
+    that produces version output when invoked with --version."""
+    cmd = f"[ -x {shlex.quote(claude_path)} ] && {shlex.quote(claude_path)} --version"
+    result = await host.run_command(cmd)
+    return result.exit_code == 0 and "Claude Code" in result.stdout
+
+
+async def ensure_claude_installed(
+    hook_ctx: "HookContextProtocol",
+    *,
+    install_if_missing: bool = True,
+    install_dir: str | None = None,
+) -> str:
+    """Ensure the ``claude`` binary is present on the host behind ``hook_ctx``.
+
+    The framework looks for a symlink at ``<install_dir>/claude``. When
+    missing and ``install_if_missing=True``, it runs the vendor install
+    script (``curl -fsSL https://claude.ai/install.sh | bash``) on the
+    host. The script downloads + checksum-verifies + places the native
+    binary under ``~/.local/share/claude/versions/<v>/`` and creates a
+    symlink at ``~/.local/bin/claude``. The framework re-checks for the
+    symlink after the install runs.
+
+    Returns the absolute path of the ``claude`` symlink on the host.
+
+    Raises RuntimeError when the binary is absent and either
+    ``install_if_missing=False`` or the install fails.
+    """
+    host = hook_ctx._host
+    resolved_install_dir = await _resolve_install_dir(host, install_dir)
+    claude_path = f"{resolved_install_dir}/claude"
+
+    hook_ctx.report_progress(None, "Checking claude installation…")
+    if await _claude_present(host, claude_path):
+        return claude_path
+
+    if not install_if_missing:
+        raise RuntimeError(
+            f"claude not present at {claude_path!r} on host and "
+            f"install_if_missing=False; nothing to do."
+        )
+
+    hook_ctx.report_progress(None, "Installing claude (vendor install.sh)…")
+    install_cmd = f"curl -fsSL {shlex.quote(_CLAUDE_INSTALL_URL)} | bash"
+    result = await host.run_command(install_cmd)
+    if result.exit_code != 0:
+        raise RuntimeError(
+            f"claude install failed on host (exit {result.exit_code}): "
+            f"{result.stderr.strip()[:300]}"
+        )
+
+    if not await _claude_present(host, claude_path):
+        raise RuntimeError(
+            f"claude install reported success but {claude_path!r} is still "
+            f"not executable on the host. Inspect the host's "
+            f"~/.local/bin and ~/.local/share/claude/versions for diagnostics."
+        )
+    return claude_path
+
+
+async def _ttyd_present(host: "Host", ttyd_path: str) -> bool:
+    cmd = f"[ -x {shlex.quote(ttyd_path)} ] && {shlex.quote(ttyd_path)} --version"
+    result = await host.run_command(cmd)
+    # ttyd writes its version banner to stdout OR stderr depending on
+    # version — accept either.
+    blob = (result.stdout or "") + (result.stderr or "")
+    return result.exit_code == 0 and "ttyd" in blob.lower()
+
+
+async def _detect_ttyd_asset_name(host: "Host") -> str:
+    """Return the upstream release-asset filename for the host's arch/OS.
+
+    Raises RuntimeError on unsupported (OS, arch) combinations.
+    """
+    r_arch = await host.run_command("uname -m")
+    if r_arch.exit_code != 0:
+        raise RuntimeError(
+            f"uname -m failed on host (exit {r_arch.exit_code}): "
+            f"{r_arch.stderr.strip()[:200]}"
+        )
+    arch = r_arch.stdout.strip()
+    r_os = await host.run_command("uname -s")
+    if r_os.exit_code != 0:
+        raise RuntimeError(
+            f"uname -s failed on host (exit {r_os.exit_code}): "
+            f"{r_os.stderr.strip()[:200]}"
+        )
+    os_name = r_os.stdout.strip()
+    if os_name != "Linux":
+        raise RuntimeError(
+            f"unsupported host OS {os_name!r} for ttyd auto-install "
+            f"(v1 supports Linux only; macOS support requires uploading "
+            f"a Darwin binary or pre-installing ttyd manually)."
+        )
+    if arch not in {"x86_64", "aarch64", "armv7l"}:
+        raise RuntimeError(
+            f"unsupported host arch {arch!r} for ttyd auto-install. "
+            f"See https://github.com/tsl0922/ttyd/releases for available "
+            f"prebuilt assets."
+        )
+    return f"ttyd.{arch}"
+
+
+async def ensure_ttyd_installed(
+    hook_ctx: "HookContextProtocol",
+    *,
+    install_if_missing: bool = True,
+    install_dir: str | None = None,
+) -> str:
+    """Ensure ``ttyd`` is present on the host behind ``hook_ctx``.
+
+    When missing and ``install_if_missing=True``, downloads the
+    appropriate static prebuilt asset from ``tsl0922/ttyd`` GitHub
+    Releases via ``hook_ctx.download_file`` (so byte-progress shows in
+    the dashboard).
+
+    Returns the absolute path of the ``ttyd`` binary on the host.
+
+    Raises RuntimeError on (a) absent binary with
+    ``install_if_missing=False``; (b) unsupported (OS, arch); (c) any
+    install sub-step failing.
+    """
+    host = hook_ctx._host
+    resolved_install_dir = await _resolve_install_dir(host, install_dir)
+    ttyd_path = f"{resolved_install_dir}/ttyd"
+
+    hook_ctx.report_progress(None, "Checking ttyd installation…")
+    if await _ttyd_present(host, ttyd_path):
+        return ttyd_path
+
+    if not install_if_missing:
+        raise RuntimeError(
+            f"ttyd not present at {ttyd_path!r} on host and "
+            f"install_ttyd_if_missing=False; nothing to do."
+        )
+
+    hook_ctx.report_progress(None, "Detecting ttyd release asset…")
+    asset = await _detect_ttyd_asset_name(host)
+    url = f"{_TTYD_RELEASE_BASE}/{asset}"
+
+    r = await host.run_command(f"mkdir -p {shlex.quote(resolved_install_dir)}")
+    if r.exit_code != 0:
+        raise RuntimeError(
+            f"mkdir -p {resolved_install_dir!r} failed (exit {r.exit_code}): "
+            f"{r.stderr.strip()[:200]}"
+        )
+
+    hook_ctx.report_progress(None, f"Downloading ttyd ({asset})…")
+    await hook_ctx.download_file(url, ttyd_path)
+
+    r = await host.run_command(f"chmod +x {shlex.quote(ttyd_path)}")
+    if r.exit_code != 0:
+        raise RuntimeError(
+            f"chmod +x {ttyd_path!r} failed (exit {r.exit_code}): "
+            f"{r.stderr.strip()[:200]}"
+        )
+
+    if not await _ttyd_present(host, ttyd_path):
+        raise RuntimeError(
+            f"ttyd install completed but {ttyd_path!r} is still not "
+            f"executable on the host. Check the downloaded asset and "
+            f"chmod result."
+        )
+    return ttyd_path
+
+
+async def plant_home_files(
+    host: "Host",
+    *,
+    credentials_json: dict[str, Any] | bytes | str | None,
+    claude_config: dict[str, Any] | None,
+) -> None:
+    """Plant per-task claude state under <workdir>/home/.claude/.
+
+    Creates <workdir>/home/.claude/ (mkdir -p), writes the credentials
+    payload and settings.json when supplied, and chmod-600s the
+    credentials file. ``credentials_json`` accepts a dict (re-encoded as
+    JSON), bytes (decoded as UTF-8 verbatim), or a string (written
+    verbatim).
+    """
+    workdir = host.workdir.rstrip("/")
+    home_claude_rel = "home/.claude"
+    home_claude_abs = f"{workdir}/{home_claude_rel}"
+
+    r = await host.run_command(f"mkdir -p {shlex.quote(home_claude_abs)}")
+    if r.exit_code != 0:
+        raise RuntimeError(
+            f"mkdir -p {home_claude_abs!r} failed (exit {r.exit_code}): "
+            f"{r.stderr.strip()[:200]}"
+        )
+
+    if credentials_json is not None:
+        if isinstance(credentials_json, dict):
+            payload = json.dumps(credentials_json)
+        elif isinstance(credentials_json, bytes):
+            payload = credentials_json.decode("utf-8")
+        else:
+            payload = credentials_json
+        cred_rel = f"{home_claude_rel}/.credentials.json"
+        await host.write_text(cred_rel, payload)
+        cred_abs = f"{workdir}/{cred_rel}"
+        r = await host.run_command(f"chmod 600 {shlex.quote(cred_abs)}")
+        if r.exit_code != 0:
+            raise RuntimeError(
+                f"chmod 600 {cred_abs!r} failed (exit {r.exit_code}): "
+                f"{r.stderr.strip()[:200]}"
+            )
+
+    if claude_config is not None:
+        settings_rel = f"{home_claude_rel}/settings.json"
+        await host.write_text(settings_rel, json.dumps(claude_config, indent=2))
+
+
+def build_ttyd_argv(
+    *,
+    ttyd_path: str,
+    claude_path: str,
+    workdir: str,
+    bind_iface: str,
+    port: int,
+    extra_env: dict[str, str] | None,
+    claude_flags: list[str],
+) -> list[str]:
+    """Construct the full argv for the ttyd subprocess.
+
+    Layout:
+      <ttyd_path> -W -i <iface> -p <port> -m 1 -T xterm-256color --
+      env HOME=<workdir>/home PATH=<home>/.local/bin:... [<extra-env...>]
+      bash -c 'mkdir -p <home>/.local/bin && ln -sf <claude_path> <home>/.local/bin/claude
+               && cd <workdir> && <claude_path> [<claude_flags...>]; rc=$?;
+               <append DONE (rc 0) | ERROR: claude exited <rc> to optio.log>'
+
+    claude is installed under the *real* host home's ``.local/bin`` (that's
+    where ``resolve_host_home`` points at install time), but the session
+    runs HOME-isolated (``HOME=<workdir>/home``). So at launch we symlink
+    claude into the isolated home's ``.local/bin`` and prepend that dir to
+    PATH — otherwise claude warns that ``~/.local/bin`` is missing / not on
+    PATH. Any caller-/shim-supplied PATH (e.g. browser shims) is merged in,
+    not dropped.
+    """
+    workdir_clean = workdir.rstrip("/")
+    home_dir = f"{workdir_clean}/home"
+    home_local_bin = f"{home_dir}/.local/bin"
+    claude_link = f"{home_local_bin}/claude"
+
+    extra = dict(extra_env or {})
+    base_path = extra.pop("PATH", None) or os.environ.get(
+        "PATH", "/usr/local/bin:/usr/bin:/bin",
+    )
+    env_assignments: list[str] = [
+        f"HOME={home_dir}",
+        f"PATH={home_local_bin}:{base_path}",
+    ]
+    for k, v in extra.items():
+        env_assignments.append(f"{k}={v}")
+
+    claude_argv = " ".join(shlex.quote(c) for c in [claude_path, *claude_flags])
+    # Symlink claude into the isolated home's bin (idempotent; skipped when
+    # the install dir already IS that bin, which would make ln a same-file
+    # error).
+    link_cmd = (
+        f"mkdir -p {shlex.quote(home_local_bin)} && "
+        f"{{ [ {shlex.quote(claude_path)} = {shlex.quote(claude_link)} ] || "
+        f"ln -sf {shlex.quote(claude_path)} {shlex.quote(claude_link)} ; }} && "
+    )
+    # Run claude (NOT exec) so that when it exits — e.g. the operator types
+    # `exit` without writing DONE — the wrapper appends a terminal protocol
+    # line. The driver's optio.log tail then completes the session and its
+    # teardown reaps the (otherwise lingering) ttyd. ttyd 1.7 has no
+    # "exit when child exits" flag; -o/-q key off *client* disconnect and
+    # would kill live tasks on a tab close, so they are the wrong lever.
+    log_path = f"{workdir_clean}/optio.log"
+    bash_payload = (
+        f"{link_cmd}cd {shlex.quote(workdir_clean)} && {claude_argv}; rc=$?; "
+        f'if [ "$rc" = 0 ]; then echo DONE >> {shlex.quote(log_path)}; '
+        f"else printf 'ERROR: claude exited %s\\n' \"$rc\" >> {shlex.quote(log_path)}; fi"
+    )
+    return [
+        ttyd_path,
+        "-W",
+        "-i", bind_iface,
+        "-p", str(port),
+        "-m", "1",
+        "-T", "xterm-256color",
+        "--",
+        "env",
+        *env_assignments,
+        "bash", "-c", bash_payload,
+    ]
+
+
+async def launch_ttyd_with_claude(
+    host: "Host",
+    *,
+    ttyd_path: str,
+    claude_path: str,
+    bind_iface: str,
+    extra_env: dict[str, str] | None,
+    claude_flags: list[str],
+    ready_timeout_s: float = 30.0,
+) -> "tuple[ProcessHandle, int]":
+    """Spawn ttyd wrapping claude under HOME-isolation. Wait for ready.
+
+    Always passes ``-p 0`` so the OS picks a free port; the actual port
+    is parsed from ttyd's stdout/stderr ready banner.
+
+    Returns ``(handle, port)``. Caller is responsible for terminating
+    the handle.
+    """
+    argv = build_ttyd_argv(
+        ttyd_path=ttyd_path,
+        claude_path=claude_path,
+        workdir=host.workdir,
+        bind_iface=bind_iface,
+        port=0,
+        extra_env=extra_env,
+        claude_flags=claude_flags,
+    )
+    # launch_subprocess takes a single shell-string passed to `sh -c`.
+    # Quote each argv element to survive shell parsing.
+    command = " ".join(shlex.quote(a) for a in argv)
+    handle = await host.launch_subprocess(command)
+
+    async def _read_port() -> int:
+        async for raw in handle.stdout:
+            line = raw.decode("utf-8", errors="replace").rstrip() if isinstance(raw, bytes) else str(raw).rstrip()
+            m = _TTYD_READY_RE.search(line)
+            if m:
+                port_str = m.group(1) or m.group(2)
+                return int(port_str)
+        raise RuntimeError("ttyd exited before printing a listening URL")
+
+    try:
+        port = await asyncio.wait_for(_read_port(), timeout=ready_timeout_s)
+    except asyncio.TimeoutError:
+        await host.terminate_subprocess(handle, aggressive=True)
+        raise TimeoutError(
+            f"ttyd did not print a listening URL within {ready_timeout_s}s"
+        )
+    except BaseException:
+        await host.terminate_subprocess(handle, aggressive=True)
+        raise
+    return handle, port
+
+
+def build_claude_flags(
+    *,
+    permission_mode: str | None,
+    allowed_tools: list[str] | None,
+    disallowed_tools: list[str] | None,
+    resuming: bool = False,
+) -> list[str]:
+    """Translate ClaudeCodeTaskConfig permission knobs to an argv list.
+
+    Empty lists are treated as None: no flag is emitted.
+    When ``resuming`` is True, ``--continue`` is appended so claude picks
+    up the most recent conversation in ``home/.claude/projects/<cwd>/``.
+    Validation of ``permission_mode`` values lives in
+    ``ClaudeCodeTaskConfig.__post_init__``.
+    """
+    out: list[str] = []
+    if permission_mode is not None:
+        out += ["--permission-mode", permission_mode]
+    if allowed_tools:
+        out += ["--allowed-tools", ",".join(allowed_tools)]
+    if disallowed_tools:
+        out += ["--disallowed-tools", ",".join(disallowed_tools)]
+    if resuming:
+        out += ["--continue"]
+    return out

optio_claudecode/prompt.py

@@ -0,0 +1,132 @@
+"""AGENTS.md composer for optio-claudecode.
+
+Renders the claudecode resume section and forwards to the shared
+``optio_agents.prompt.compose_agents_md``. The resume text is byte-identical
+to optio-opencode's, with one added bullet: ``home/.claude/`` (credentials,
+settings, conversation transcript) is preserved across resumes — claudecode
+needs this because all sensitive agent-continuity state lives there.
+"""
+
+from optio_agents.prompt import (
+    BASE_PROMPT_POST,
+    compose_agents_md as _compose_agents_md_host,
+)
+from optio_agents.protocol import build_log_channel_prompt
+
+
+__all__ = ["BASE_PROMPT_POST", "compose_agents_md"]
+
+
+RESUME_SECTION_TEMPLATE = """## Resumes
+
+This harness may pause your session, save your context to a database,
+terminate the underlying process, and later rehydrate it. From your
+point of view the conversation is fully continuous — you keep your
+prior context and will not "notice" the resume.
+
+**A resume can happen at any point, not only at the start.** The host
+environment may have changed across a resume — different host,
+different running processes, files outside this workdir gone — even
+though your context remembers everything as alive and well.
+
+**The workdir (this directory) is preserved across resumes, with two
+caveats:**
+
+- {excludes_clause}
+- **Anything outside the workdir is not preserved.**
+
+- **Your `home/.claude/` directory — credentials, settings, and the
+  conversation transcript — IS preserved across resumes**, so your
+  identity and history travel with you even when the underlying process
+  and host change.
+
+{outside_clause}
+
+### Detecting a resume: `resume.log`
+
+Each session start (fresh or resumed) appends one line to
+`./resume.log`. Line format:
+
+```
+<ISO 8601 UTC timestamp>[ REFRESHED:<comma-separated filenames>]
+```
+
+The very first line is the original launch timestamp; each subsequent
+line is a resume. The optional `REFRESHED:` suffix signals that the
+harness rewrote the listed files on that resume (e.g.
+`2026-05-28T13:15:42Z REFRESHED:AGENTS.md`) — your in-memory copy of
+those files is stale and must be re-read before continuing.
+
+**At the start of every new incoming user message, read
+`./resume.log` first.** Compare the latest line to the value you
+remembered last time you checked. If a new line has appeared, treat
+the situation as a resume:
+
+- Verify any tools, processes, or files you previously gathered
+  outside the workdir are still where you left them.
+- Re-establish anything that's gone (re-launch a server, re-fetch a
+  file, etc.) before continuing.
+- **If the latest line carries a `REFRESHED:` suffix, re-read each
+  listed file** (e.g. `cat ./AGENTS.md`) — the harness updated it
+  since your last context snapshot and the version you remember is
+  out of date.
+- Then resume the work you were doing.
+
+If a resume slips past unnoticed, a failing tool call is the
+next-best signal — re-check `./resume.log` then.
+"""
+
+
+def _render_resume_section(workdir_exclude: list[str] | None) -> str:
+    """Render the RESUME_SECTION_TEMPLATE with the effective exclude list."""
+    from optio_host.archive import DEFAULT_WORKDIR_EXCLUDES
+    effective = workdir_exclude if workdir_exclude is not None else DEFAULT_WORKDIR_EXCLUDES
+    if not effective:
+        excludes_clause = (
+            "**No paths are excluded** — every file in the workdir is preserved."
+        )
+        outside_clause = (
+            "If you need to stash large data, place it outside the workdir "
+            "(e.g. `/tmp/`) — but remember it may be missing when you next look."
+        )
+    else:
+        excludes_str = ", ".join(f"`{p}`" for p in effective)
+        excludes_clause = (
+            f"**Paths matching the snapshot exclude list are NOT preserved**, "
+            f"even inside the workdir. The current exclude list is: {excludes_str}."
+        )
+        outside_clause = (
+            "If you need to stash large data, place it outside the workdir "
+            "(e.g. `/tmp/`) or inside an excluded subdirectory — but remember "
+            "any such location may be missing when you next look."
+        )
+    return RESUME_SECTION_TEMPLATE.format(
+        excludes_clause=excludes_clause,
+        outside_clause=outside_clause,
+    )
+
+
+def compose_agents_md(
+    consumer_instructions: str,
+    *,
+    documentation: str | None = None,
+    workdir_exclude: list[str] | None = None,
+    supports_resume: bool = True,
+) -> str:
+    """Render <workdir>/AGENTS.md for an optio-claudecode task.
+
+    Renders the claudecode resume section when ``supports_resume`` is
+    True and forwards everything else to the shared host composer.
+
+    ``documentation`` is the keyword-protocol block; the session passes
+    ``get_protocol(browser="redirect").documentation``. Defaults (for
+    unit tests / standalone callers) to claudecode's ``redirect`` docs.
+    """
+    if documentation is None:
+        documentation = build_log_channel_prompt("redirect")
+    resume_section = _render_resume_section(workdir_exclude) if supports_resume else None
+    return _compose_agents_md_host(
+        consumer_instructions,
+        documentation=documentation,
+        resume_section=resume_section,
+    )

optio_claudecode/seed_manifest.py

@@ -0,0 +1,80 @@
+"""claudecode adopter of the generic optio-agents seed engine.
+
+Defines the claudecode seed manifest (HOME layout + capture-time include
+triage + consume-time rekey), the Mongo collection suffix, and ergonomic
+`delete_seed` / `list_seeds` wrappers that bind the suffix for consuming
+apps.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from optio_agents import seeds
+from optio_host.host import Host
+
+_LOG = logging.getLogger(__name__)
+
+CLAUDE_SEED_SUFFIX = "_claudecode_seeds"
+CLAUDE_SEED_MANIFEST_VERSION = 1
+
+
+async def _rekey_claude_json_projects(host: Host) -> None:
+    """Rewrite the single `projects` entry in home/.claude.json to the new
+    cwd, preserving its value (trust flags, allowedTools, MCP enablement)
+    so an autonomous task isn't blocked by claude's trust prompt.
+
+    Empty / multi-entry / missing / malformed -> left as-is (a fresh trust
+    prompt is the safe fallback).
+    """
+    workdir = host.workdir.rstrip("/")
+    path = f"{workdir}/home/.claude.json"
+    try:
+        raw = await host.fetch_bytes_from_host(path)
+    except FileNotFoundError:
+        return
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        _LOG.warning("seed: .claude.json is not valid JSON; leaving projects as-is")
+        return
+    projects = data.get("projects")
+    if not isinstance(projects, dict) or len(projects) != 1:
+        return
+    (old_value,) = projects.values()
+    data["projects"] = {workdir: old_value}
+    await host.put_file_to_host(
+        json.dumps(data).encode("utf-8"), path,
+    )
+
+
+CLAUDE_SEED_MANIFEST = seeds.SeedManifest(
+    home_subdir="home",
+    include=[
+        ".claude/.credentials.json",
+        ".claude/settings.json",
+        ".claude/mcp-needs-auth-cache.json",
+        ".claude/plugins",
+        ".claude.json",
+    ],
+    version=CLAUDE_SEED_MANIFEST_VERSION,
+    consume_transform=_rekey_claude_json_projects,
+)
+
+
+async def delete_seed(db, prefix: str, seed_id: str):
+    """Delete a claudecode seed doc; returns its GridFS blobId (or None).
+
+    Ergonomic wrapper binding `CLAUDE_SEED_SUFFIX` so consuming apps don't
+    need to know the collection suffix. The caller still removes the
+    returned blob from GridFS.
+    """
+    return await seeds.delete_seed(
+        db, prefix=prefix, suffix=CLAUDE_SEED_SUFFIX, seed_id=seed_id,
+    )
+
+
+async def list_seeds(db, prefix: str) -> list[dict]:
+    """List claudecode seeds as [{seedId, createdAt}, ...]."""
+    return await seeds.list_seeds(db, prefix=prefix, suffix=CLAUDE_SEED_SUFFIX)