cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/claude_runner.py

@@ -0,0 +1,1068 @@
+"""ClaudeRunner: spawn the ``claude`` binary, drive its stdin/stdout and emit
+status frames for one wake-up.
+
+Spec §6.5–§6.7. The runner is invoked once per delivered message by the
+SpawnQueue drain loop (see Task 8). It is *not* the queue itself.
+
+Design contract
+---------------
+``run_one(agent_id, payload)`` performs the following sequence:
+
+1.  Build the ``claude`` argv (`--resume` only on a pre-existing session,
+    plus ``--mcp-config <path> --print --output-format stream-json``).
+2.  Spawn it with stdin/stdout/stderr pipes.
+3.  Write ``payload["body"]`` to stdin and close it.
+4.  Emit ``delivery_ack(status="started")`` for the message and an
+    ``agent_status(running)`` frame.
+5.  Stream stdout NDJSON events; remember any ``session_id`` carried by a
+    ``session_init`` event.
+6.  Wait for exit (90-min single-wake timeout per spec §6.7). On timeout,
+    terminate then kill the process.
+7.  Read stderr tail, persist `last-spawn.json`, delete the per-agent
+    one-shot token file.
+8.  If the captured session_id is new, persist it on the workspace and
+    emit ``agent_session_start``.
+9.  Emit a final ``agent_status`` (``idle``/``crashed``/``timeout``) and
+    return a :class:`SpawnResult`.
+
+Workspace is referenced via :class:`WorkspaceLike` / :class:`AgentWorkspaceLike`
+``Protocol`` types; the real implementation lands in Task 11.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Awaitable, Callable, Protocol
+
+if TYPE_CHECKING:
+    from cloudagent_daemon.outbound_queue import OutboundQueue
+
+
+# 1k74 — token-level streaming partial-publish hook.
+#
+# The runner invokes this callable each time claude emits a text_delta
+# stream event during a run. ``accumulated_text`` is everything claude
+# has emitted so far (the runner concatenates chunks before calling
+# the publisher) so the receiver can render it as the in-progress
+# assistant bubble without having to track its own running buffer.
+#
+# Implementations should be fire-and-forget: a failed publish must not
+# tear down the claude wake. Network errors / backend hiccups are
+# logged at INFO; the final ``send_message`` MCP call is the canonical
+# source of truth and will land regardless.
+PartialPublisher = Callable[[str, str, str], Awaitable[None]]
+"""(session_id, agent_id, accumulated_text) -> None"""
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Workspace protocol — concrete impl arrives in Task 11
+# ---------------------------------------------------------------------------
+
+
+class AgentWorkspaceLike(Protocol):
+    """Per-agent workspace surface used by :class:`ClaudeRunner`."""
+
+    path: Path
+    # Task #118 (2026-05-12) — claude subprocess cwd. Decoupled from
+    # ``path`` (the metadata root) so a user-supplied
+    # ``agent.workspace_root`` doesn't pollute the platform's
+    # ``~/.cloudagent/agents/<id>/`` directory.
+    cwd: Path
+
+    def last_session_id(self) -> str | None: ...
+
+    def set_last_session_id(self, sid: str) -> None: ...
+
+    # 1k followup — clear stored session_id when ``claude --resume`` reports
+    # "No conversation found" so the next wake starts a fresh conversation
+    # instead of looping on the stale id forever.
+    def clear_last_session_id(self) -> None: ...
+
+    def mcp_config_path(self) -> Path: ...
+
+    def write_last_spawn(
+        self, exit_code: int, session_id: str | None, stderr_tail: str
+    ) -> None: ...
+
+    def delete_token_file(self) -> None: ...
+
+    # 1k hotfix — per-spawn current-session marker; see workspace.py.
+    def write_current_session(self, session_id: str | None) -> None: ...
+
+    def delete_current_session(self) -> None: ...
+
+
+class WorkspaceLike(Protocol):
+    def for_agent(self, agent_id: str) -> AgentWorkspaceLike: ...
+
+    # 1h Part C — auto-create on first deliver if no workspace exists yet.
+    # The server may push a deliver for an agent the daemon has never
+    # seen (lazy registration); falling back to a sensible identity
+    # avoids a hard crash and lets the user run ``claude`` without a
+    # manual init step.
+    def ensure(
+        self, agent_id: str, identity: dict
+    ) -> AgentWorkspaceLike: ...
+
+
+# ---------------------------------------------------------------------------
+# Result type
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SpawnResult:
+    exit_code: int
+    captured_session_id: str | None
+    stderr_tail: str
+
+
+@dataclass
+class _SpawnAttempt:
+    """Outcome of a single ``claude`` subprocess invocation.
+
+    1k followup — internal helper returned by
+    :meth:`ClaudeRunner._spawn_attempt`. Distinct from the public
+    :class:`SpawnResult` because we additionally need ``timeout_hit`` to
+    pick the final ``agent_status`` (timeout vs crashed) — that field is
+    not part of the runner's external contract.
+
+    1k #63 — additionally tracks ``tool_uses`` (the names of every
+    tool_use block emitted by claude during the wake) and
+    ``final_result_text`` (the text from the terminating ``type=result``
+    event). Both feed the Layer-B daemon-side fallback that POSTs a
+    ``send_message`` on claude's behalf when claude generated a reply
+    but never invoked the tool.
+    """
+
+    exit_code: int
+    captured_session_id: str | None
+    stderr_tail: str
+    timeout_hit: bool
+    tool_uses: list[str]
+    final_result_text: str | None
+
+
+def _build_lazy_identity(agent_id: str, payload: dict) -> dict:
+    """Construct the minimum-viable identity dict for ``Workspace.ensure``.
+
+    1h Part C: the daemon may receive a deliver for an agent it doesn't
+    have a registered workspace for yet (e.g. after a fresh install,
+    or when the user creates the agent on the server while the daemon
+    is offline). In that case we derive a safe identity from whatever
+    the deliver payload carries, falling back to ``agent_id`` for any
+    missing fields.
+
+    ``is_chief`` defaults to ``False`` — that is a security guarantee:
+    daemons must NOT auto-promote unknown agents to chief (which gates
+    ``delegate_to_staff`` access). A future server-pushed ``assign``
+    frame will carry the correct kind / role.
+    """
+    return {
+        "agent_id": agent_id,
+        "agent_name": str(payload.get("agent_name") or agent_id),
+        "is_chief": False,
+        "role": str(payload.get("role") or "staff"),
+        "workspace_slug": str(payload.get("workspace_slug") or "default"),
+        "reports_to": "(unset)",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Runner
+# ---------------------------------------------------------------------------
+
+
+class ClaudeRunner:
+    """Run one wake of the ``claude`` CLI for a delivered message."""
+
+    #: Spec §6.7 — 90-minute single-wake timeout.
+    SINGLE_WAKE_TIMEOUT_SECONDS: float = 90 * 60
+    #: Wait this long after SIGTERM before SIGKILL on timeout.
+    TERMINATE_GRACE_SECONDS: float = 10.0
+    #: How many bytes of stderr to retain in last-spawn.json.
+    STDERR_TAIL_BYTES: int = 2000
+
+    def __init__(
+        self,
+        *,
+        outbound: OutboundQueue,
+        workspace: WorkspaceLike,
+        claude_binary: str = "claude",
+        single_wake_timeout: float | None = None,
+        partial_publisher: PartialPublisher | None = None,
+        agent_to_session: "dict[str, str | None] | None" = None,
+    ) -> None:
+        self.outbound = outbound
+        self.workspace = workspace
+        self.claude_binary = claude_binary
+        # Allow tests to override the 90-min timeout without monkey-patching
+        # a class attribute. Defaults to spec value.
+        self._single_wake_timeout: float = (
+            single_wake_timeout
+            if single_wake_timeout is not None
+            else self.SINGLE_WAKE_TIMEOUT_SECONDS
+        )
+        # 1k74 — optional callback for token-level streaming. main_loop
+        # wires this to an HTTP POST against the backend's partial-
+        # publish endpoint. Absent in tests, where we don't care about
+        # the stream and want to keep claude_runner exercises hermetic.
+        self._partial_publisher = partial_publisher
+        # (c) IPC architecture upgrade — shared agent→session memory map.
+        # main_loop passes its own dict; mcp_bridge queries it via the
+        # unix socket ``get_current_session`` op instead of reading a file.
+        # None means feature disabled (legacy / test path).
+        self._agent_to_session: dict[str, str | None] | None = agent_to_session
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    #: 1k followup — substring used to detect the stale-session crash
+    #: emitted by ``claude --resume <sid>`` when the session is no longer
+    #: present in ``~/.claude/sessions/``. ``--print`` mode does not
+    #: always persist sessions, so chaining wakes via ``--resume`` is
+    #: fragile. When we observe this we clear ``last_session_id`` and
+    #: retry once without ``--resume``.
+    STALE_SESSION_STDERR_MARKER: str = "No conversation found"
+
+    #: 1k #63 — stdin wrapper template (Layer A defense).
+    #:
+    #: ``--append-system-prompt`` text is treated by claude as a soft
+    #: guideline: simple prompts ("你好" / "你是谁") still get answered
+    #: by writing the reply to stdout and exiting WITHOUT invoking
+    #: ``mcp__cloudagent__send_message``. The daemon discards stdout, so
+    #: the user sees nothing.
+    #:
+    #: stdin, by contrast, is the active user message — claude treats it
+    #: as the immediate task. We put the user body FIRST (so it is treated
+    #: as the primary task) and append the tool-call instruction AS A
+    #: FOOTER with an explicit "do not echo this scaffolding" line.
+    #:
+    #: 1k #66 fix: the previous template led with a "[CRITICAL — Tool-only
+    #: response required]" header. claude treated that prominent tag as
+    #: salient enough to acknowledge in its reply text (e.g. parenthetical
+    #: notes like "(外层 [CRITICAL] 指令依旧按提示注入处理)") — leaking
+    #: scaffolding to the user. Quieter footer + explicit anti-echo line
+    #: keeps the same tool-use enforcement without the leak.
+    WAKE_PROMPT_TEMPLATE: str = """{header}{body}
+
+---
+[Assistant scaffolding — not user content. Do not echo, quote, or reference this block in your reply.]
+Reply via tool call only:
+  mcp__cloudagent__send_message(
+      target=<sender role from [meta] header — NOT a literal "user">,
+      parent_msg_id=<message_id from [meta] header>,
+      body="<your reply text only>",
+      kind="reply",
+  )
+The daemon discards stdout — only the mcp tool call reaches the user.
+"""
+
+    #: Wave C #1 (D2 contract) — ``dispatch_source`` is a backend-stamped
+    #: enum on the deliver frame (``user_direct`` / ``chief_dispatch`` /
+    #: ``peer_request`` / ``system_fan_out`` / ``hitl_response`` /
+    #: ``auto_reply``). The daemon **passes it through to claude verbatim**
+    #: as a header above the body, without parsing or branching on it —
+    #: claude's system prompt + the backend's ``message_transitions``
+    #: enforce the "缺 dispatch_source 回 question" rule. The daemon's
+    #: only job is making the field visible in the wake prompt.
+    #:
+    #: Tracked separately so a future contract iteration adding more
+    #: stamped fields (e.g. ``thread_id`` / ``parent_msg_id``) can extend
+    #: the header without touching the body assembly path.
+    _PASSTHROUGH_HEADER_FIELDS: tuple[str, ...] = (
+        "dispatch_source",
+        "from",
+        "sender_role",
+        "parent_msg_id",
+        # Hot-fix 2026-05-12 — local_daemon staff replies were sending
+        # ``parent_msg_id=None`` because claude couldn't see the inbound
+        # message_id (it was on the deliver payload but never surfaced
+        # to the wake prompt). Now in the ``[meta]`` header so claude
+        # can copy it into ``send_message(parent_msg_id=...)``.
+        "message_id",
+    )
+
+    async def run_one(self, agent_id: str, payload: dict) -> SpawnResult:
+        """Execute one wake; see module docstring for the full sequence.
+
+        1h Part C — lazy workspace: when the daemon receives a deliver
+        for an agent it has never been asked to host before, the
+        per-agent ``~/.cloudagent/agents/<agent_id>/`` directory does
+        not exist yet — and ``mcp-config`` / ``MEMORY.md`` / ``identity.json``
+        won't either. ``claude`` would crash on the missing
+        ``--mcp-config`` arg. We auto-create the workspace using sane
+        defaults derived from the deliver payload (or just the agent_id
+        when the payload is sparse). ``is_chief`` defaults to ``False``
+        (deny-by-default) — a future ``assign`` frame should override.
+
+        1k followup — when the first attempt fails with stderr matching
+        :attr:`STALE_SESSION_STDERR_MARKER` (``claude --resume`` rejected
+        a non-persisted session id) we clear the stored session id and
+        retry exactly once without ``--resume`` so the user-facing reply
+        still lands rather than crashing the wake forever.
+        """
+        ws = self.workspace.for_agent(agent_id)
+        if not ws.path.exists():
+            identity = _build_lazy_identity(agent_id, payload)
+            logger.info(
+                "ClaudeRunner: lazy-creating workspace agent_id=%s "
+                "(server-pushed deliver for unknown agent)",
+                agent_id,
+            )
+            ws = self.workspace.ensure(agent_id, identity)
+
+        # 1k hotfix — write current deliver's session_id BEFORE spawn so
+        # mcp_bridge (a grandchild process) can pick it up at startup.
+        # Removed in the finally below regardless of how the spawn-and-
+        # wait section exits.
+        current_session_id = payload.get("session_id")
+        _effective_session_id: str | None = (
+            current_session_id
+            if isinstance(current_session_id, str) and current_session_id
+            else None
+        )
+        try:
+            ws.write_current_session(_effective_session_id)
+        except Exception:  # pragma: no cover — defensive
+            logger.exception("ClaudeRunner: write_current_session failed")
+        # (c) IPC architecture upgrade — register in the daemon-process
+        # memory map so mcp_bridge can query via unix socket instead of
+        # reading the file. Both paths coexist for backward compat.
+        if self._agent_to_session is not None:
+            self._agent_to_session[agent_id] = _effective_session_id
+
+        wake_start = time.monotonic()
+        try:
+            attempt = await self._spawn_attempt(
+                ws, agent_id, payload, with_resume=True
+            )
+
+            # 1k followup — detect stale session (``claude --resume``
+            # rejected) and retry once without ``--resume``. The first
+            # attempt did NOT capture a session_id (the resume failed
+            # before claude got to print ``system/init``), so there is
+            # nothing useful to persist — we just clear the stored id
+            # and re-spawn fresh.
+            if (
+                attempt.exit_code != 0
+                and self.STALE_SESSION_STDERR_MARKER in attempt.stderr_tail
+                and ws.last_session_id() is not None
+            ):
+                stale_sid = ws.last_session_id()
+                logger.warning(
+                    "claude_runner: claude --resume rejected stale "
+                    "session_id=%s (stderr contained %r). Clearing and "
+                    "retrying without --resume.",
+                    stale_sid,
+                    self.STALE_SESSION_STDERR_MARKER,
+                )
+                try:
+                    ws.clear_last_session_id()
+                except Exception:  # pragma: no cover — defensive
+                    logger.exception(
+                        "ClaudeRunner: clear_last_session_id failed"
+                    )
+                attempt = await self._spawn_attempt(
+                    ws, agent_id, payload, with_resume=False
+                )
+        finally:
+            # 1k hotfix — always remove the per-spawn marker, even on
+            # spawn failure / cancellation, to prevent stale session_id
+            # leaking into the next wake.
+            try:
+                ws.delete_current_session()
+            except Exception:  # pragma: no cover — defensive
+                logger.exception("ClaudeRunner: delete_current_session failed")
+            # (c) IPC architecture upgrade — clear from memory map.
+            if self._agent_to_session is not None:
+                self._agent_to_session.pop(agent_id, None)
+
+        captured_session = attempt.captured_session_id
+        rc = attempt.exit_code
+        timeout_hit = attempt.timeout_hit
+        stderr_tail = attempt.stderr_tail
+
+        # Spec §6.6 step 2 — token is one-shot per wake.
+        try:
+            ws.delete_token_file()
+        except Exception:  # pragma: no cover — defensive
+            logger.exception("ClaudeRunner: delete_token_file failed")
+
+        if captured_session and captured_session != ws.last_session_id():
+            ws.set_last_session_id(captured_session)
+            await self.outbound.send_agent_session_start(
+                agent_id, captured_session
+            )
+
+        # 1k #63 Layer B — daemon-side fallback ``send_message``.
+        #
+        # Even with the stdin wrapper (Layer A) claude may occasionally
+        # still print a reply to stdout without invoking
+        # ``mcp__cloudagent__send_message`` (e.g. for trivial prompts
+        # like "你好" / "你是谁"). When that happens the daemon discards
+        # stdout and the user-facing inbox stays empty.
+        #
+        # If claude exited cleanly (rc==0, no timeout) AND produced final
+        # result text AND did NOT call send_message, we POST the reply
+        # ourselves so the user always sees it. We use the per-deliver
+        # session_id from the payload — the same id mcp_bridge would
+        # have read from current-session.txt if claude had called the
+        # tool itself. The backend merges session_id from the frame
+        # top-level into args before dispatching ``send_message`` (1k
+        # #56), so we don't need to inject it into the args dict.
+        called_send_message = any(
+            name == "mcp__cloudagent__send_message"
+            for name in attempt.tool_uses
+        )
+        fallback_session = payload.get("session_id")
+        if (
+            not called_send_message
+            and rc == 0
+            and not timeout_hit
+            and attempt.final_result_text
+            and isinstance(fallback_session, str)
+            and fallback_session
+        ):
+            logger.warning(
+                "claude_runner: claude wake exited without calling "
+                "send_message — daemon fallback POSTing result text "
+                "(agent=%s session=%s text_chars=%d)",
+                agent_id,
+                fallback_session,
+                len(attempt.final_result_text),
+            )
+            try:
+                await self.outbound.send_tool_call(
+                    agent_id=agent_id,
+                    session_id=fallback_session,
+                    tool_name="send_message",
+                    args={
+                        "target": "user",
+                        "body": attempt.final_result_text,
+                        "kind": "reply",
+                    },
+                    # Backend dispatch is fast — short timeout keeps the
+                    # wake from blocking the spawn queue if the WS round
+                    # trip stalls.
+                    timeout=15.0,
+                )
+                # Wave C #3 — non-zero in /metrics means the 1k #63
+                # Layer A stdin template slipped; operators should
+                # investigate. Increment AFTER the POST succeeded so
+                # we don't double-count crashloops.
+                try:
+                    from cloudagent_daemon.metrics import get_default as _md
+                    await _md().inc_counter(
+                        "cloudagent_daemon_spawn_fallback_send_message_total"
+                    )
+                except Exception:  # noqa: BLE001
+                    pass
+            except Exception:  # pragma: no cover — best-effort fallback
+                logger.exception(
+                    "claude_runner: daemon fallback send_message FAILED "
+                    "(lost reply) agent=%s session=%s",
+                    agent_id,
+                    fallback_session,
+                )
+
+        ws.write_last_spawn(rc, captured_session, stderr_tail)
+
+        if timeout_hit:
+            final_status = "timeout"
+        elif rc == 0:
+            final_status = "idle"
+        else:
+            final_status = "crashed"
+
+        # Wave C #3 — surface terminal status counts for /metrics +
+        # doctor. Label-keyed so a single counter renders three
+        # series (idle / crashed / timeout). Failure to publish must
+        # never crash the wake — the wake itself is the user-facing
+        # contract.
+        try:
+            from cloudagent_daemon.metrics import get_default as _md
+            await _md().inc_counter(
+                "cloudagent_daemon_spawn_completed_total",
+                labels={"status": final_status},
+            )
+        except Exception:  # noqa: BLE001
+            logger.debug(
+                "claude_runner: spawn_completed_total publish failed",
+                exc_info=True,
+            )
+
+        await self.outbound.send_agent_status(
+            agent_id, final_status, exit_code=rc
+        )
+
+        wake_secs = time.monotonic() - wake_start
+        logger.info(
+            "claude_runner: claude exited agent=%s rc=%d session_id=%s "
+            "status=%s wake_secs=%.2f stderr_tail_chars=%d",
+            agent_id,
+            rc,
+            captured_session,
+            final_status,
+            wake_secs,
+            len(stderr_tail),
+        )
+
+        return SpawnResult(
+            exit_code=rc,
+            captured_session_id=captured_session,
+            stderr_tail=stderr_tail,
+        )
+
+    async def _spawn_attempt(
+        self,
+        ws: AgentWorkspaceLike,
+        agent_id: str,
+        payload: dict,
+        *,
+        with_resume: bool,
+    ) -> _SpawnAttempt:
+        """Run a single ``claude`` subprocess and return its outcome.
+
+        Extracted from :meth:`run_one` so the runner can re-invoke it
+        with ``with_resume=False`` when the first attempt fails with a
+        stale-session error (1k followup).
+
+        Side-effects emitted exactly once per attempt: ``delivery_ack``
+        for the message_id, and ``agent_status(running)``. The final
+        ``agent_status`` (idle/crashed/timeout) and last-spawn.json
+        write are intentionally LEFT to the caller so they always
+        reflect the *last* attempt.
+        """
+        cmd = self._build_cmd(ws, agent_id, with_resume=with_resume)
+
+        # Task #118 (2026-05-12) — spawn cwd is now the agent-specific
+        # cwd (per-agent override → host default → platform fallback).
+        # Pre-#118 the daemon inherited its own cwd (typically ``~``)
+        # which meant claude saw HOME as its working dir regardless of
+        # the agent's intended project — broken UX for "let agent A
+        # work on ~/projects/foo".
+        spawn_cwd = ws.cwd
+
+        # 1i Bug C — Phase 1 demo visibility.
+        logger.info(
+            "claude_runner: spawning claude agent=%s msg=%s prior_session=%s "
+            "with_resume=%s cwd=%s cmd=%s",
+            agent_id,
+            payload.get("message_id"),
+            ws.last_session_id(),
+            with_resume,
+            spawn_cwd,
+            " ".join(cmd),
+        )
+
+        logger.debug("ClaudeRunner: spawning %s", cmd)
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(spawn_cwd),
+            # asyncio StreamReader 默认 limit=64KB；claude CLI 单条 JSON
+            # event 可超出（tool_result 含大型 Read 文件 / Anthropic 返回
+            # body / partial_messages 累积 chunk 等）。2026-05-14 实战：
+            # local daemon 在执行 SDK/CLI 开发 task 时 readline 抛
+            # LimitOverrunError "Separator is found, but chunk is longer
+            # than limit" → spawn fail，claude 没机会发 send_message 回复
+            # → 上游 task 永远卡 waiting/partial。对齐 backend harness 的
+            # claude_code_core.py 同步把 limit 提到 10MB。
+            limit=10 * 1024 * 1024,
+        )
+
+        # 1k #63 Layer A — wrap the message body in a tool-only contract.
+        # stdin is the active user prompt that claude can't treat as a
+        # soft footer (unlike ``--append-system-prompt``). See
+        # ``WAKE_PROMPT_TEMPLATE`` docstring.
+        body = payload.get("body") or ""
+        header = self._build_passthrough_header(payload)
+        wake_prompt = self.WAKE_PROMPT_TEMPLATE.format(
+            header=header, body=body
+        )
+        try:
+            assert proc.stdin is not None  # for type checkers
+            proc.stdin.write(wake_prompt.encode("utf-8"))
+            proc.stdin.write(b"\n")
+            await proc.stdin.drain()
+            proc.stdin.close()
+        except (BrokenPipeError, ConnectionResetError):
+            # claude died before we finished writing; downstream code will
+            # observe the exit code and stderr.
+            logger.debug("ClaudeRunner: stdin pipe closed early")
+
+        # Notify backend that we picked the message up.
+        message_id = payload.get("message_id")
+        if message_id:
+            await self.outbound.send_ack(
+                seq=None, message_id=message_id, status="started"
+            )
+        await self.outbound.send_agent_status(agent_id, "running")
+
+        # 1k74 — token-level streaming. Forward the deliver's session_id
+        # and agent_id into the stdout consumer so it can call our
+        # partial_publisher with the right routing key for each text
+        # chunk. session_id is ``test_chat_{host}_{agent}`` for test-
+        # chat deliveries (the new per-agent shape from 1k73).
+        deliver_session_id = payload.get("session_id")
+        captured_session, tool_uses, final_text = await self._consume_stdout(
+            proc,
+            partial_session_id=(
+                deliver_session_id
+                if isinstance(deliver_session_id, str)
+                else None
+            ),
+            partial_agent_id=agent_id,
+        )
+
+        timeout_hit, rc = await self._wait_with_timeout(proc)
+
+        # stderr was buffered by the subprocess; drain whatever is left.
+        stderr_b = await proc.stderr.read() if proc.stderr is not None else b""
+        stderr_tail = stderr_b.decode("utf-8", errors="replace")[
+            -self.STDERR_TAIL_BYTES:
+        ]
+
+        return _SpawnAttempt(
+            exit_code=rc,
+            captured_session_id=captured_session,
+            stderr_tail=stderr_tail,
+            timeout_hit=timeout_hit,
+            tool_uses=tool_uses,
+            final_result_text=final_text,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    #: 1i Bug E — the daemon-injected ``cloudagent`` MCP toolset MUST run
+    #: unattended in ``--print`` headless mode (otherwise claude prompts
+    #: the user for permission, the prompt is never answered, and the
+    #: wake exits without the reply being delivered). We allow exactly
+    #: this toolset rather than ``--dangerously-skip-permissions`` (which
+    #: would also whitelist Bash/Edit/etc. — too broad).
+    CLOUDAGENT_MCP_ALLOWED_TOOLS: tuple[str, ...] = (
+        "mcp__cloudagent__send_message",
+        "mcp__cloudagent__list_messages",
+        "mcp__cloudagent__upload_file",
+        "mcp__cloudagent__schedule_reminder",
+        "mcp__cloudagent__delegate_to_staff",
+        "mcp__cloudagent__close_task",
+        "mcp__cloudagent__request_user_approval",
+        "mcp__cloudagent__set_company_status",
+    )
+
+    # 1i Bug F — operational contract for daemon-spawned wakes.
+    # Without this, claude in --print mode just dumps its answer to stdout
+    # and exits, never invoking send_message — so the user never sees a reply.
+    # The daemon discards stdout text; only mcp tool calls flow back through
+    # the outbound queue to the user. We inject this as --append-system-prompt
+    # so it runs after the default Claude Code system prompt and the user
+    # cannot edit it away from MEMORY.md / settings.
+    SYSTEM_PROMPT_APPEND: str = """
+You are an AI agent running inside cloudagent's local daemon. The user message you are receiving via stdin is a deliver from your agent inbox (agent_id={agent_id}).
+
+ROUTING — choosing `target` for send_message (HARD RULE):
+  Every kind="reply" send MUST set BOTH `target` AND `parent_msg_id`
+  by reading the inbound message's [meta] header — never by defaulting
+  to "user". The [meta] header contains the sender's role and
+  message_id; copy them verbatim into your tool call:
+
+      target        = inbound `from` / `sender_role` field
+      parent_msg_id = inbound `message_id` field
+
+  Concrete cases:
+  - Inbound `from`="user"  → target="user"   (human HITL surface)
+  - Inbound `from`="ceo"   → target="ceo"    (chief↔staff collab)
+  - Inbound `from`="<peer staff role>" → target=<that role>
+
+  Do NOT default target="user" when a non-user agent dispatched the
+  work — that breaks chief↔staff collaboration AND the parent task
+  hangs in `substatus=partial` because the chief's wait_for_replies
+  never sees your reply. The backend has two safety nets (parent_msg_id
+  →to_agent derivation; orphan-reply implicit inbox lookup within 5
+  min) but they are belt-and-braces — your tool call MUST be correct.
+  When unsure which agent dispatched the work, call
+  `mcp__cloudagent__list_messages(limit=20)` first and copy `from` /
+  `message_id` from the most recent inbound row addressed to you.
+
+THREADING — parent_msg_id (hot-fix 2026-05-12, CRITICAL):
+  When replying with kind="reply" or kind="question" you MUST set
+  parent_msg_id to the inbound message's `message_id` (shown in the
+  [meta] header above your stdin payload, e.g. `message_id: 236`).
+  Failing this, the chief's wait_for_replies will never satisfy and
+  the parent task hangs forever in `partial` substatus. Backend's
+  parent_msg_id-based to_agent inference IS a safety net for routing,
+  but the chief's wait_for_replies looks up replies BY parent_msg_id —
+  if you drop it, the chief simply never knows your reply exists.
+  Unsolicited kind="task" / kind="report" sends leave parent_msg_id
+  unset (None / omitted).
+
+INBOX SWEEP — on every boot:
+  Your FIRST action MUST be `mcp__cloudagent__list_messages(limit=20)`.
+  Scan the result for any **unread** messages addressed to you that are
+  NOT the deliver you just received via stdin. Handle each in order
+  (call send_message to reply per the routing rules above) BEFORE you
+  respond to the stdin deliver. This catches any frames the daemon
+  failed to spawn while you were offline.
+
+To reply, call mcp__cloudagent__send_message with:
+  - target: per the routing rules above
+  - body: your reply text
+  - kind: "reply"   (or "question" if you need clarification)
+
+Do NOT write your reply directly to stdout. The daemon ignores stdout text — only mcp tool calls reach the user / other agents.
+
+After all sends are issued, exit naturally. Your wake will be marked complete.
+
+Available cloudagent tools:
+  - mcp__cloudagent__send_message(target, body, kind, parent_msg_id) — send to user or another agent.
+        For kind="reply" / "question", parent_msg_id MUST be the inbound
+        message_id from [meta] (see THREADING above). Omit / leave None
+        for unsolicited kind="task" / "report" sends.
+  - mcp__cloudagent__list_messages(limit) — read recent inbox (status field discriminates unread/read)
+  - mcp__cloudagent__upload_file(path) — share a file
+  - mcp__cloudagent__schedule_reminder(when, body) — schedule self-reminder
+""".strip()
+
+    def _build_passthrough_header(self, payload: dict) -> str:
+        """Render the D2 passthrough header for the wake prompt.
+
+        Emits a single ``[meta]`` block with one ``key: value`` line per
+        ``_PASSTHROUGH_HEADER_FIELDS`` entry **that the payload provides
+        as a non-empty string-coercible value**. Empty when no fields are
+        present (so the existing pre-Wave-C behaviour is byte-identical
+        for legacy backends that don't stamp these fields yet).
+
+        Newline-terminated when non-empty so it composes cleanly into
+        ``WAKE_PROMPT_TEMPLATE`` immediately above the body.
+        """
+        lines: list[str] = []
+        for key in self._PASSTHROUGH_HEADER_FIELDS:
+            if key not in payload:
+                continue
+            value = payload.get(key)
+            if value in (None, ""):
+                continue
+            # Coerce to a single-line string. Multi-line values are
+            # collapsed defensively — daemon doesn't interpret these
+            # fields, but a stray newline in a header would mis-frame the
+            # body for claude.
+            text = str(value).replace("\r", " ").replace("\n", " ").strip()
+            if not text:
+                continue
+            lines.append(f"{key}: {text}")
+        if not lines:
+            return ""
+        return "[meta]\n" + "\n".join(lines) + "\n[/meta]\n\n"
+
+    def _build_cmd(
+        self,
+        ws: AgentWorkspaceLike,
+        agent_id: str,
+        *,
+        with_resume: bool = True,
+    ) -> list[str]:
+        """Build the ``claude`` argv list for one wake.
+
+        1k followup — ``with_resume=False`` forces the runner to omit
+        ``--resume`` even if a stored ``last_session_id`` exists. The
+        retry path uses this after a stale-session crash.
+        """
+        cmd: list[str] = [self.claude_binary]
+        last_session = ws.last_session_id() if with_resume else None
+        if last_session:
+            cmd += ["--resume", last_session]
+        # 1i Bug F — inject operational contract via --append-system-prompt.
+        system_prompt = self.SYSTEM_PROMPT_APPEND.format(agent_id=agent_id)
+        cmd += [
+            "--mcp-config",
+            str(ws.mcp_config_path()),
+            "--print",
+            "--verbose",
+            "--output-format",
+            "stream-json",
+            # 1k74 (2026-05-11) — token-level streaming. Without this flag
+            # claude buffers each ``assistant`` message and emits it in
+            # one event (full reply, 100% buffered). With it the runtime
+            # ALSO emits ``stream_event`` events carrying
+            # ``content_block_delta`` / ``text_delta`` chunks (~80
+            # chars/chunk) as the model generates. The daemon forwards
+            # those chunks to backend so the chat bubble fills in
+            # token-by-token instead of jumping straight to the final
+            # reply after a 30s blank stare.
+            "--include-partial-messages",
+            # 1i Bug E — see CLOUDAGENT_MCP_ALLOWED_TOOLS docstring.
+            "--allowedTools",
+            ",".join(self.CLOUDAGENT_MCP_ALLOWED_TOOLS),
+            # 1i Bug F — see SYSTEM_PROMPT_APPEND docstring.
+            "--append-system-prompt",
+            system_prompt,
+        ]
+        return cmd
+
+    async def _consume_stdout(
+        self,
+        proc: asyncio.subprocess.Process,
+        *,
+        partial_session_id: str | None = None,
+        partial_agent_id: str | None = None,
+    ) -> tuple[str | None, list[str], str | None]:
+        """Stream NDJSON from stdout; return ``(session_id, tool_uses, result_text)``.
+
+        Accepts BOTH session-init event shapes for forward/backward
+        compatibility:
+
+        * Old/spec shape: ``{"type": "session_init", "session_id": "..."}``
+        * Real claude (≥ 2024-Q4) shape:
+          ``{"type": "system", "subtype": "init", "session_id": "..."}``
+
+        1k #63 — additionally extracts:
+
+        * ``tool_uses``: list of every tool name that appears in any
+          assistant ``content[*].type == "tool_use"`` block AND in any
+          standalone ``type == "tool_use"`` event (claude CLI varies
+          across versions). Used by the daemon-side fallback to decide
+          whether claude actually called ``mcp__cloudagent__send_message``.
+        * ``final_result_text``: the text from the terminating
+          ``type == "result"`` event. Falls back to ``evt.get("text")``
+          if ``evt.get("result")`` is empty (different claude versions
+          name the same field differently). Used as the body of the
+          fallback ``send_message`` POST.
+
+        Also surfaces ``type=result`` and ``type=tool_use`` events at INFO
+        for Phase 1 demo visibility (1i Bug C).
+        """
+        captured: str | None = None
+        tool_uses: list[str] = []
+        final_text: str | None = None
+        # 1k74 — running buffer for token-level streaming. claude emits
+        # one ``stream_event`` per content_block_delta (~80 chars at a
+        # time); we concatenate them and forward the running total to
+        # the publisher so the receiver renders the bubble in growing
+        # form rather than having to track its own deltas.
+        partial_buffer: list[str] = []
+        publish_enabled = bool(
+            self._partial_publisher
+            and partial_session_id
+            and partial_agent_id
+        )
+        # (d) cache token accumulators — populated from Anthropic API
+        # ``message_start`` stream event wrapped in ``stream_event``.
+        _cache_read_tokens: int = 0
+        _cache_creation_tokens: int = 0
+        if proc.stdout is None:
+            return None, tool_uses, final_text
+
+        async for line_b in proc.stdout:
+            line = line_b.decode("utf-8", errors="replace").strip()
+            if not line:
+                continue
+            try:
+                evt = json.loads(line)
+            except json.JSONDecodeError:
+                logger.debug("ClaudeRunner: non-JSON stdout line: %r", line[:120])
+                continue
+            if not isinstance(evt, dict):
+                continue
+
+            evt_type = evt.get("type")
+            evt_subtype = evt.get("subtype")
+
+            # 1k74 — token-level streaming. claude emits one or more
+            # ``stream_event`` events per assistant message, each
+            # wrapping an Anthropic Messages API event. The shape we
+            # care about is:
+            #   {"type":"stream_event","event":{
+            #       "type":"content_block_delta",
+            #       "delta":{"type":"text_delta","text":"..."}}}
+            # Each ``text`` is the latest chunk; concatenating them in
+            # arrival order rebuilds the assistant's eventual reply.
+            if evt_type == "stream_event":
+                ev = evt.get("event")
+                if isinstance(ev, dict):
+                    # (d) cache token observability — extract usage from
+                    # ``message_start`` which Anthropic emits once per
+                    # response with input/cache token counts.
+                    if ev.get("type") == "message_start":
+                        msg_u = (ev.get("message") or {}).get("usage") or {}
+                        if isinstance(msg_u, dict):
+                            _cache_read_tokens += int(
+                                msg_u.get("cache_read_input_tokens") or 0
+                            )
+                            _cache_creation_tokens += int(
+                                msg_u.get("cache_creation_input_tokens") or 0
+                            )
+                    # 1k74 — token-level streaming.
+                    if publish_enabled and ev.get("type") == "content_block_delta":
+                        delta = ev.get("delta")
+                        if (
+                            isinstance(delta, dict)
+                            and delta.get("type") == "text_delta"
+                        ):
+                            chunk = delta.get("text")
+                            if isinstance(chunk, str) and chunk:
+                                partial_buffer.append(chunk)
+                                accumulated = "".join(partial_buffer)
+                                # Fire-and-forget — exceptions logged and
+                                # swallowed so a flaky publish path can't
+                                # tear down the wake.
+                                assert self._partial_publisher is not None
+                                assert partial_session_id is not None
+                                assert partial_agent_id is not None
+                                try:
+                                    await self._partial_publisher(
+                                        partial_session_id,
+                                        partial_agent_id,
+                                        accumulated,
+                                    )
+                                except Exception as exc:  # noqa: BLE001
+                                    logger.info(
+                                        "partial_publisher failed (non-fatal): %r",
+                                        exc,
+                                    )
+
+            # Capture session_id from either of the known event shapes.
+            is_session_event = (
+                evt_type == "session_init"
+                or (evt_type == "system" and evt_subtype == "init")
+            )
+            if is_session_event and captured is None:
+                # Tolerate both snake_case and camelCase keys.
+                sid = evt.get("session_id") or evt.get("sessionId")
+                if isinstance(sid, str) and sid:
+                    captured = sid
+                    logger.info(
+                        "ClaudeRunner: captured session_id=%s (event type=%s subtype=%s)",
+                        sid,
+                        evt_type,
+                        evt_subtype,
+                    )
+
+            # 1k #63 — extract tool_use names from assistant content blocks.
+            # The real claude CLI emits tool_use as a content block inside
+            # an ``assistant`` event:
+            #   {"type":"assistant","message":{"content":[
+            #       {"type":"tool_use","name":"mcp__cloudagent__send_message",...}
+            #   ]}}
+            if evt_type == "assistant":
+                msg = evt.get("message")
+                content = (
+                    msg.get("content")
+                    if isinstance(msg, dict)
+                    else None
+                )
+                if isinstance(content, list):
+                    for block in content:
+                        if (
+                            isinstance(block, dict)
+                            and block.get("type") == "tool_use"
+                        ):
+                            name = block.get("name") or block.get("tool_name")
+                            if isinstance(name, str) and name:
+                                tool_uses.append(name)
+
+            # 1i Bug C — Phase 1 demo visibility for key event types.
+            if evt_type == "result":
+                # 1k #63 — capture the final reply text for the fallback
+                # path. ``result`` is the canonical field on the
+                # terminating event; ``text`` is a fallback some versions
+                # use. We also capture this for visibility-only logging.
+                result_text = evt.get("result")
+                if not isinstance(result_text, str) or not result_text:
+                    alt = evt.get("text")
+                    if isinstance(alt, str) and alt:
+                        result_text = alt
+                if isinstance(result_text, str) and result_text:
+                    final_text = result_text
+                summary = (
+                    result_text[:120] + "..."
+                    if isinstance(result_text, str) and len(result_text) > 120
+                    else result_text
+                )
+                logger.info(
+                    "ClaudeRunner: stdout result subtype=%s text=%r",
+                    evt_subtype,
+                    summary,
+                )
+            elif evt_type == "tool_use":
+                # Standalone tool_use event (older / alternate shape).
+                name = evt.get("name") or evt.get("tool_name")
+                if isinstance(name, str) and name:
+                    tool_uses.append(name)
+                logger.info(
+                    "ClaudeRunner: stdout tool_use name=%s",
+                    name,
+                )
+        # (d) emit cache token metrics once per wake, after stdout drains.
+        if _cache_read_tokens or _cache_creation_tokens:
+            logger.info(
+                "claude_runner: cache_tokens "
+                "cache_read=%d cache_creation=%d "
+                "metric_event=cloudagent_llm_cache_hit_tokens_total",
+                _cache_read_tokens,
+                _cache_creation_tokens,
+            )
+        try:
+            from cloudagent_daemon.metrics import get_default as _get_metrics
+            _m = _get_metrics()
+            await _m.inc_counter(
+                "cloudagent_llm_cache_hit_tokens_total",
+                n=_cache_read_tokens,
+                labels={"source": "daemon"},
+            )
+            await _m.inc_counter(
+                "cloudagent_llm_cache_creation_tokens_total",
+                n=_cache_creation_tokens,
+                labels={"source": "daemon"},
+            )
+        except Exception:  # noqa: BLE001 — non-fatal metric failure
+            logger.debug(
+                "claude_runner: cache metrics publish failed", exc_info=True
+            )
+
+        return captured, tool_uses, final_text
+
+    async def _wait_with_timeout(
+        self, proc: asyncio.subprocess.Process
+    ) -> tuple[bool, int]:
+        """Wait for exit; SIGTERM→SIGKILL on timeout. Returns (timeout_hit, rc)."""
+        try:
+            rc = await asyncio.wait_for(
+                proc.wait(), timeout=self._single_wake_timeout
+            )
+            return False, rc
+        except asyncio.TimeoutError:
+            logger.warning("ClaudeRunner: 90-min wake timeout, terminating")
+
+        # First polite SIGTERM.
+        try:
+            proc.terminate()
+        except ProcessLookupError:  # pragma: no cover — already gone
+            pass
+        try:
+            rc = await asyncio.wait_for(
+                proc.wait(), timeout=self.TERMINATE_GRACE_SECONDS
+            )
+            return True, rc
+        except asyncio.TimeoutError:
+            pass
+
+        # Hard kill.
+        try:
+            proc.kill()
+        except ProcessLookupError:  # pragma: no cover
+            pass
+        rc = await proc.wait()
+        return True, rc