ccherd 0.1.0__py3-none-any.whl

ccherd/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code sessions and subagents across several Claude accounts."""
+
+__version__ = "0.1.0"

ccherd/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

ccherd/agents.py

@@ -0,0 +1,253 @@
+"""Background subagents: their on-disk registry and the supervisor that runs their turns.
+
+Layout: <state dir>/<owner session id>/<agent name>/
+  meta.json       status, account, model, mode, claude session id, last result
+  stream.jsonl    every turn's `claude -p --output-format stream-json` output
+  inbox.jsonl     messages queued while no turn can take them
+  supervisor.log  stderr of the detached supervisor
+  lock            flock serializing every read-modify-write of meta.json and inbox
+
+The owner is the Claude session whose Bash ran `ccherd spawn`: CLAUDE_CODE_SESSION_ID
+is set in every tool subprocess, so each session gets its own list of agents.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import config
+from .permissions import mode_class
+from .procs import pid_alive, proc_start
+from .sessions import deliver, session_by_socket
+
+TERMINAL = {"idle", "failed", "killed", "lost"}
+EFFORTS = ["low", "medium", "high", "xhigh", "max"]
+RESULT_PREVIEW = 3000  # chars of the result carried in the completion notice
+NAME_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
+
+
+# --- registry -----------------------------------------------------------------
+
+
+def owner_id() -> str:
+    if os.environ.get("CCHERD_OWNER"):
+        return os.environ["CCHERD_OWNER"]
+    sid = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    if not sid:
+        raise SystemExit("ccherd: CLAUDE_CODE_SESSION_ID is not set - run this from inside a Claude session "
+                         "(or set CCHERD_OWNER to a label of your own)")
+    return sid
+
+
+def agent_dir(owner: str, name: str) -> Path:
+    if not NAME_RE.fullmatch(name):
+        raise SystemExit(f"ccherd: agent name {name!r} must be [A-Za-z0-9._-], max 64")
+    return config.STATE_DIR / owner / name
+
+
+def find_agent(name: str) -> Path | None:
+    """This session's agent called `name`, or None."""
+    if not NAME_RE.fullmatch(name):
+        return None
+    d = agent_dir(owner_id(), name)
+    return d if (d / "meta.json").is_file() else None
+
+
+def require_agent(name: str) -> Path:
+    d = find_agent(name)
+    if d is None:
+        raise SystemExit(f"ccherd: no agent {name!r} in this session (`ccherd agents`)")
+    return d
+
+
+def list_agents(all_owners: bool) -> list[tuple[Path, dict]]:
+    root = config.STATE_DIR
+    owners = [p for p in root.iterdir() if p.is_dir()] if all_owners and root.is_dir() else [root / owner_id()]
+    return [(m.parent, refreshed(m.parent)) for o in owners for m in sorted(o.glob("*/meta.json"))]
+
+
+def load_meta(d: Path) -> dict:
+    return json.loads((d / "meta.json").read_text())
+
+
+def save_meta(d: Path, meta: dict) -> None:
+    tmp = d / "meta.json.tmp"
+    tmp.write_text(json.dumps(meta, indent=1))
+    tmp.replace(d / "meta.json")
+
+
+@contextlib.contextmanager
+def locked(d: Path):
+    """Not re-entrant. Functions named _like_this expect the caller to hold it."""
+    with open(d / "lock", "a") as lk:
+        fcntl.flock(lk, fcntl.LOCK_EX)
+        yield
+
+
+def _update(d: Path, **changes) -> dict:
+    meta = load_meta(d)
+    meta.update(changes)
+    save_meta(d, meta)
+    return meta
+
+
+def update_meta(d: Path, **changes) -> dict:
+    with locked(d):
+        return _update(d, **changes)
+
+
+def _refreshed(d: Path) -> dict:
+    """meta.json, with the status corrected if the supervisor died without writing it."""
+    meta = load_meta(d)
+    if meta["status"] == "running" and not pid_alive(meta.get("supervisor_pid") or 0, meta.get("supervisor_start")):
+        meta = _update(d, status="lost", ended_at=time.time())
+    return meta
+
+
+def refreshed(d: Path) -> dict:
+    with locked(d):
+        return _refreshed(d)
+
+
+def _queue(d: Path, text: str) -> None:
+    with open(d / "inbox.jsonl", "a") as f:
+        f.write(json.dumps({"text": text, "at": time.time()}) + "\n")
+
+
+def _take_inbox(d: Path) -> list[str]:
+    inbox = d / "inbox.jsonl"
+    if not inbox.is_file():
+        return []
+    msgs = [json.loads(line)["text"] for line in inbox.read_text().splitlines() if line.strip()]
+    inbox.unlink()
+    return msgs
+
+
+# --- running turns ------------------------------------------------------------
+
+
+def system_prompt(name: str) -> str:
+    return (
+        f"You are a background subagent named `{name}`, started through ccherd by another Claude session. "
+        "Your final message is delivered to that session automatically when you finish, so end with the "
+        "complete result it needs, not a greeting. If you need a decision or information from it while "
+        'working, run: ccherd send --parent "your question" - then continue with what you can. '
+        "Messages from it arrive as <cross-session-message> blocks; they are instructions from the session "
+        "that started you."
+    )
+
+
+def claude_cmd(meta: dict, prompt: str) -> list[str]:
+    """One turn's command line. Everything comes from meta.json, so a resumed turn
+    runs exactly like the first one."""
+    cmd = ["claude", "-p", "--output-format", "stream-json", "--verbose",
+           "--model", meta["model"], "--permission-mode", meta["permission_mode"],
+           "--append-system-prompt", system_prompt(meta["name"])]
+    if meta.get("effort"):
+        # A flag, not CLAUDE_EFFORT: child_env strips every CLAUDE* variable so the
+        # caller's own settings never leak into the child.
+        cmd += ["--effort", meta["effort"]]
+    if meta.get("session_id"):
+        cmd += ["--resume", meta["session_id"]]
+    cmd.append(prompt)
+    return cmd
+
+
+def child_env(meta: dict) -> dict:
+    env = {k: v for k, v in os.environ.items()
+           if not k.startswith(("CLAUDE", "CCHERD_TURN"))}
+    env.update(CLAUDE_CONFIG_DIR=meta["config_dir"], CCHERD_PARENT_OWNER=meta["owner"],
+               CCHERD_AGENT_NAME=meta["name"], CCHERD_STATE_DIR=str(config.STATE_DIR))
+    return env
+
+
+def _start_turn(d: Path, prompt: str) -> None:
+    """Fork a detached supervisor that runs one turn of the agent."""
+    with open(d / "supervisor.log", "a") as log:
+        p = subprocess.Popen([sys.executable, "-m", "ccherd", "_supervise", str(d)],
+                             stdin=subprocess.DEVNULL, stdout=log, stderr=log, start_new_session=True,
+                             env={**os.environ, "CCHERD_TURN_PROMPT": prompt})
+    _update(d, status="running", supervisor_pid=p.pid, supervisor_start=None,
+            child_pid=None, turn_started_at=time.time())
+
+
+def _run_turn(d: Path, meta: dict, prompt: str) -> tuple[int, str | None, str | None, bool, float | None]:
+    """Run `claude -p` once; returns (exit code, result, session id, is_error, cost)."""
+    result, session_id, is_error, cost = None, meta.get("session_id"), False, None
+    with open(d / "stream.jsonl", "a") as out:
+        out.write(json.dumps({"type": "ccherd_turn", "turn": meta["turns"] + 1, "prompt": prompt,
+                              "at": time.time()}) + "\n")
+        out.flush()
+        child = subprocess.Popen(claude_cmd(meta, prompt), cwd=meta["cwd"], env=child_env(meta),
+                                 stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                 text=True)
+        update_meta(d, child_pid=child.pid)
+        for line in child.stdout:
+            out.write(line)
+            out.flush()
+            try:
+                ev = json.loads(line)
+            except ValueError:
+                continue
+            session_id = ev.get("session_id") or session_id
+            if ev.get("type") == "result":
+                result = ev.get("result")
+                is_error = bool(ev.get("is_error"))
+                cost = ev.get("total_cost_usd")
+        return child.wait(), result, session_id, is_error, cost
+
+
+def supervise(d: Path) -> int:
+    """Body of the detached supervisor: run turns until nothing is queued, then notify the owner."""
+    update_meta(d, supervisor_pid=os.getpid(), supervisor_start=proc_start(os.getpid()))
+    prompt = os.environ.pop("CCHERD_TURN_PROMPT")
+    while True:
+        meta = load_meta(d)
+        rc, result, session_id, is_error, cost = _run_turn(d, meta, prompt)
+        with locked(d):
+            # Status and inbox are settled under ONE lock: `ccherd send` queues only while
+            # it reads "running" under the same lock, so no message lands after the
+            # last drain and sits there unrun.
+            killed = load_meta(d)["status"] == "killed"
+            pending = [] if killed else _take_inbox(d)
+            if killed:
+                status = "killed"
+            elif pending and session_id:
+                status = "running"
+            else:
+                status = "failed" if (rc != 0 or is_error) else "idle"
+            meta = _update(d, status=status, session_id=session_id, turns=meta["turns"] + 1,
+                           child_pid=None, last_result=result, last_exit=rc, ended_at=time.time(),
+                           last_cost_usd=cost)
+        if status == "killed":
+            return 0
+        if status == "running":
+            # Messages that arrived while the turn was ending run as the next turn,
+            # so the owner gets one notice per settled state.
+            prompt = "\n\n".join(pending)
+            continue
+        notify_owner(meta, status, result)
+        return 0
+
+
+def notify_owner(meta: dict, status: str, result: str | None) -> None:
+    sess = session_by_socket(meta.get("owner_socket"))
+    if not sess:
+        return  # the owner is gone; the result stays readable via `ccherd result`
+    body = result or "(no result text)"
+    if len(body) > RESULT_PREVIEW:
+        body = body[:RESULT_PREVIEW] + f"\n[... truncated, full text: ccherd result {meta['name']}]"
+    head = (f"ccherd: subagent `{meta['name']}` is {status} (account {meta['account']}, {meta['model']}, "
+            f"turn {meta['turns']}). Reply with: ccherd send {meta['name']} \"...\"")
+    try:
+        deliver(sess, f"{head}\n\n{body}", sender=f"ccherd:{meta['name']}", mode=mode_class(meta["permission_mode"]))
+    except OSError:
+        pass

ccherd/api.py

@@ -0,0 +1,28 @@
+"""Read-only calls to the Anthropic OAuth API, with the token of one account."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from pathlib import Path
+
+BASE_URL = "https://api.anthropic.com/api/oauth"
+
+
+def get(path: str, token: str) -> dict:
+    """GET {BASE_URL}/{path}. Raises urllib.error.URLError, OSError or ValueError."""
+    req = urllib.request.Request(f"{BASE_URL}/{path}", headers={
+        "Authorization": f"Bearer {token}",
+        "anthropic-beta": "oauth-2025-04-20",
+    })
+    with urllib.request.urlopen(req, timeout=10) as r:
+        return json.load(r)
+
+
+def write_cache(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data))
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)

ccherd/cli.py

@@ -0,0 +1,100 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, agents, commands, doctor, setup
+from .permissions import MODES
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="ccherd", description="Claude Code sessions and subagents across several Claude accounts.")
+    p.add_argument("--version", action="version", version=f"ccherd {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True, metavar="COMMAND")
+
+    s = sub.add_parser("setup", help="choose accounts, install the skill (run inside your repo)")
+    s.add_argument("--dir", action="append", metavar="PATH", help="a config dir to use (repeatable; skips the picker)")
+    s.add_argument("--schema", action="append", metavar="PATH",
+                   help="use PATH and every numbered sibling, e.g. ~/.claude-work (repeatable; skips the picker)")
+    s.add_argument("--organization", metavar="NAME",
+                   help="use only accounts of this organization (as `ccherd doctor` names it)")
+    s.add_argument("--skill", choices=setup.SKILL_TARGETS, help="where to install the skill")
+    s.add_argument("--claude-local", action=argparse.BooleanOptionalAction, default=None,
+                   help="add a ccherd note to CLAUDE.local.md")
+    s.add_argument("--new", type=int, metavar="N",
+                   help="you have N subscriptions but no config dirs yet: create them and print how to log in")
+    s.add_argument("-y", "--yes", action="store_true", help="take the default for every question not answered by a flag")
+    s.set_defaults(fn=setup.run)
+
+    s = sub.add_parser("doctor", help="check claude CLI, logins, shared config and skill")
+    s.add_argument("--fix", action="store_true", help="link each account's skills, memories etc. to the primary")
+    s.add_argument("-y", "--yes", action="store_true", help="with --fix: do not ask")
+    s.set_defaults(fn=doctor.run)
+
+    s = sub.add_parser("accounts", help="usage and score per account")
+    s.add_argument("--model", help="score against this model's weekly limit too")
+    s.add_argument("--refresh", action="store_true", help="ignore the 60s cache")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=commands.accounts)
+
+    s = sub.add_parser("sessions", help="live sessions of all accounts")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=commands.sessions)
+
+    s = sub.add_parser("spawn", help="start a background subagent on the best account")
+    s.add_argument("name")
+    s.add_argument("task")
+    s.add_argument("--model", required=True, help="e.g. opus, sonnet, haiku")
+    s.add_argument("--effort", choices=agents.EFFORTS, help="claude's --effort for every turn of this agent")
+    s.add_argument("--account", default="auto", help="auto (default) or a label from `ccherd accounts`")
+    s.add_argument("--cwd", default=".")
+    s.add_argument("--permission-mode", choices=MODES,
+                   help="default: the calling session's current mode; only narrower modes are accepted")
+    s.set_defaults(fn=commands.spawn)
+
+    s = sub.add_parser("agents", help="this session's subagents")
+    s.add_argument("--all", action="store_true", help="every session's subagents")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=commands.list_agents)
+
+    s = sub.add_parser("send", help="message a subagent or any live session")
+    s.add_argument("target", nargs="?", help="agent name, session name or uds: address")
+    s.add_argument("text")
+    s.add_argument("--parent", action="store_true", help="from inside a subagent: message the session that started it")
+    s.set_defaults(fn=commands.send)
+
+    s = sub.add_parser("result", help="a subagent's last answer in full")
+    s.add_argument("name")
+    s.set_defaults(fn=commands.result)
+
+    s = sub.add_parser("log", help="a subagent's transcript")
+    s.add_argument("name")
+    s.add_argument("--tail", type=int, default=0)
+    s.set_defaults(fn=commands.log)
+
+    s = sub.add_parser("kill", help="stop a subagent and everything it started")
+    s.add_argument("name")
+    s.set_defaults(fn=commands.kill)
+
+    s = sub.add_parser("_supervise")  # internal: the detached process that runs one agent's turns
+    s.add_argument("dir")
+    s.set_defaults(fn=lambda a: agents.supervise(Path(a.dir)))
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = parser()
+    a = p.parse_args(argv)
+    if a.cmd == "send" and not a.parent and not a.target:
+        p.error("send needs a TARGET (or --parent)")
+    try:
+        return a.fn(a)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ccherd/commands.py

@@ -0,0 +1,211 @@
+"""The subcommands, one function each. Argument parsing lives in cli.py."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import time
+from argparse import Namespace
+
+from . import agents, config
+from .agents import TERMINAL, locked
+from .fmt import fmt_age, fmt_ts
+from .permissions import caller_mode, check_not_wider, mode_class
+from .sessions import deliver, find_session, live_sessions, session_by_socket
+from .usage import pick_account, rank_accounts
+
+
+def _own_account() -> str | None:
+    cur_path = config.current_dir().resolve()
+    return next((a.label for a in config.load_accounts() if a.dir.resolve() == cur_path), None)
+
+
+def _account(label: str) -> config.Account:
+    accounts = config.load_accounts()
+    for a in accounts:
+        if a.label == label:
+            return a
+    raise SystemExit(f"ccherd: no account {label!r} (have: {', '.join(a.label for a in accounts)})")
+
+
+def accounts(a: Namespace) -> int:
+    rows = rank_accounts(a.model, refresh=a.refresh)
+    if a.json:
+        print(json.dumps(rows, indent=1))
+        return 0
+    me = _own_account()
+    width = max([len(r["account"]) + 1 for r in rows] + [8])
+    print(f"{'account':{width}} {'5h':>5} {'5h reset':>16} {'week':>5} {'week reset':>16} {'%/h':>6} {'score':>6}  note")
+    for i, r in enumerate(rows):
+        pick = " <- auto" if i == 0 and r["score"] is not None else ""
+        label = r["account"] + ("*" if r["account"] == me else "")
+        sc = "-" if r["score"] is None else f"{r['score']:.2f}"
+        print(f"{label:{width}} {r.get('five_hour', 0):>4.0f}% {fmt_ts(r.get('five_hour_reset')):>16} "
+              f"{r.get('weekly', 0):>4.0f}% {fmt_ts(r.get('weekly_reset')):>16} {r.get('rate', 0):>6.2f} "
+              f"{sc:>6}  {r['reason']}{pick}")
+    print("* = this session's account; score = weekly % left per hour until reset x free share of the 5h window")
+    return 0
+
+
+def sessions(a: Namespace) -> int:
+    ss = live_sessions()
+    if a.json:
+        print(json.dumps(ss, indent=1))
+        return 0
+    mine = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    for s in sorted(ss, key=lambda s: (s["account"], s.get("name") or "")):
+        me = " (this session)" if s.get("sessionId") == mine else ""
+        print(f"[{s['account']}] {s.get('name') or '-':40} {s.get('status', '?'):5} "
+              f"uds:{s.get('messagingSocketPath')}  {s.get('cwd', '')}{me}")
+    return 0
+
+
+def spawn(a: Namespace) -> int:
+    owner = agents.owner_id()
+    d = agents.agent_dir(owner, a.name)
+    if (d / "meta.json").is_file():
+        meta = agents.refreshed(d)
+        state = "is" if meta["status"] not in TERMINAL else "exists,"
+        raise SystemExit(f"ccherd: agent {a.name!r} {state} {meta['status']} - `ccherd send {a.name}` "
+                         f"continues it, or pick another name")
+    caller = caller_mode()
+    mode = a.permission_mode or caller
+    check_not_wider(mode, caller)
+    account = _account(pick_account(a.model) if a.account == "auto" else a.account)
+    cwd = os.path.abspath(a.cwd)
+    d.mkdir(parents=True, mode=0o700)
+    agents.save_meta(d, {
+        "name": a.name, "owner": owner, "owner_socket": os.environ.get("CLAUDE_CODE_MESSAGING_SOCKET"),
+        "owner_account": _own_account(), "account": account.label, "config_dir": str(account.dir),
+        "model": a.model, "effort": a.effort, "permission_mode": "manual" if mode == "default" else mode,
+        "cwd": cwd, "created_at": time.time(), "status": "starting", "turns": 0, "session_id": None,
+    })
+    with locked(d):
+        agents._start_turn(d, a.task)
+    print(f"ccherd: started `{a.name}` on account {account.label} ({a.model}, effort {a.effort or 'default'}, "
+          f"{mode}) in {cwd}.\n     A notice arrives in this session when it finishes; `ccherd agents` shows its state.")
+    return 0
+
+
+def list_agents(a: Namespace) -> int:
+    rows = agents.list_agents(a.all)
+    if a.json:
+        print(json.dumps([m for _, m in rows], indent=1))
+        return 0
+    if not rows:
+        print("no subagents" + ("" if a.all else " for this session (--all for every session's)"))
+    for _, m in rows:
+        last = (m.get("last_result") or "").strip().splitlines()
+        owner = f" owner {m['owner'][:8]}" if a.all else ""
+        print(f"{m['name']:20} {m['status']:8} {m['account']:8} {m['model']:10} {m.get('effort') or '-':6} "
+              f"turns {m['turns']:<3} since {fmt_age(m.get('turn_started_at'))}{owner}  {last[0][:60] if last else ''}")
+    return 0
+
+
+def send(a: Namespace) -> int:
+    if a.parent:
+        return _send_to_parent(a.text)
+    d = agents.find_agent(a.target)
+    if d is None:
+        return _send_to_session(a.target, a.text)
+    return _send_to_agent(d, a.target, a.text)
+
+
+def _send_to_parent(text: str) -> int:
+    owner, name = os.environ.get("CCHERD_PARENT_OWNER"), os.environ.get("CCHERD_AGENT_NAME")
+    if not (owner and name):
+        raise SystemExit("ccherd: --parent works only inside a ccherd subagent")
+    meta = agents.load_meta(agents.agent_dir(owner, name))
+    sess = session_by_socket(meta.get("owner_socket"))
+    if not sess:
+        raise SystemExit("ccherd: the session that started you is no longer running")
+    deliver(sess, f"ccherd: subagent `{name}` asks:\n\n{text}\n\nAnswer with: ccherd send {name} \"...\"",
+            sender=f"ccherd:{name}", mode=mode_class(meta["permission_mode"]))
+    print("sent to parent")
+    return 0
+
+
+def _send_to_session(target: str, text: str) -> int:
+    # Assert THIS session's real current class. That is a true statement about the
+    # sender, so it grants nothing; without it a receiver that bypasses permissions
+    # holds the message for its user, and with it two bypass sessions talk directly.
+    sess = find_session(target)
+    mode = mode_class(caller_mode())
+    deliver(sess, text, mode=mode)
+    held = ("" if mode else " without a permission class (this session's mode is unreadable),"
+            " so a receiver that bypasses permissions holds it for its user's approval")
+    print(f"delivered to [{sess['account']}] {sess.get('name')}{held}. A receiver in a different permission "
+          f"class holds it for approval; ccherd gets no receipt either way. "
+          f"Replies arrive here as <cross-session-message from=\"uds:...\">.")
+    return 0
+
+
+def _send_to_agent(d, name: str, text: str) -> int:
+    # The agent keeps the mode it was spawned with. If this session has been
+    # narrowed since, it may no longer steer an agent that is allowed more.
+    check_not_wider(agents.load_meta(d)["permission_mode"], caller_mode())
+    with locked(d):
+        meta = agents._refreshed(d)
+        if meta["status"] not in ("running", "starting"):
+            if not meta.get("session_id"):
+                raise SystemExit(f"ccherd: `{name}` never got a session id (status {meta['status']}) - see `ccherd log`")
+            agents._start_turn(d, text)
+            print(f"resumed `{name}` on account {meta['account']} with your message")
+            return 0
+        child = next((s for s in live_sessions() if meta.get("child_pid") and s["pid"] == meta["child_pid"]), None)
+        if child is None:
+            agents._queue(d, text)
+            print(f"`{name}` has no inbox open right now - queued, it runs as its next turn")
+            return 0
+    # The owner chose this mode at spawn, so asserting it grants nothing new.
+    deliver(child, text, mode=mode_class(meta["permission_mode"]))
+    print(f"sent into running `{name}` (it reads it at its next tool round)")
+    return 0
+
+
+def result(a: Namespace) -> int:
+    m = agents.refreshed(agents.require_agent(a.name))
+    print(m.get("last_result") or f"(no result yet - status {m['status']})")
+    return 0
+
+
+def log(a: Namespace) -> int:
+    d = agents.require_agent(a.name)
+    stream = d / "stream.jsonl"
+    lines = stream.read_text().splitlines() if stream.is_file() else []
+    for line in lines[-a.tail:] if a.tail else lines:
+        try:
+            ev = json.loads(line)
+        except ValueError:
+            print(line)
+            continue
+        kind = ev.get("type")
+        if kind == "ccherd_turn":
+            print(f"\n=== turn {ev['turn']}: {ev['prompt'][:200]}")
+        elif kind == "assistant":
+            for c in ev.get("message", {}).get("content", []):
+                if c.get("type") == "text":
+                    print(f"[assistant] {c['text']}")
+                elif c.get("type") == "tool_use":
+                    print(f"[tool] {c.get('name')} {json.dumps(c.get('input'))[:160]}")
+        elif kind == "result":
+            print(f"[result] {'ERROR ' if ev.get('is_error') else ''}{(ev.get('result') or '')[:300]}")
+    return 0
+
+
+def kill(a: Namespace) -> int:
+    d = agents.require_agent(a.name)
+    m = agents.refreshed(d)
+    if m["status"] != "running":
+        print(f"`{a.name}` is {m['status']}, nothing to stop")
+        return 0
+    agents.update_meta(d, status="killed")
+    try:
+        # The supervisor leads its own session, so its pid is the process group of
+        # claude and every tool process claude started.
+        os.killpg(m["supervisor_pid"], signal.SIGTERM)
+    except (ProcessLookupError, KeyError, TypeError):
+        pass
+    print(f"stopped `{a.name}`")
+    return 0