handoff

# Handoff to a fresh Dave session `/handoff` starts a **new** Dave agentic session in the *current worktree* and seeds it with the next task, so this session can wrap up while a fresh one picks up with clean context. It's a single `agentium spawn` call (see the `agentium` skill): one command spawns a sibling on this host + cwd, waits for it to come up, and delivers the task as its first message. ## 1. Decide the task The new session inherits **zero context** from this conversation, so the task has to be a self-contained prompt: what to build, the full `headway:board/word-id` card ref if there is one, and any constraint the fresh agent can't infer from the repo. Treat it like the prompt *you* were handed at the start of this session. (The new session will read the card itself, so the prompt only needs the ref plus a short TL;DR — not the card's full text.) - If the user already gave the task in the `/handoff` invocation, expand it into that self-contained prompt. - Otherwise **ask the user what the next session should work on**, then show them the exact prompt you're about to send and get their OK — it's the only thing the new agent will see. - Also pick a **short title** (a few words) for the session, so it's identifiable in `agentium list` — e.g. the headway card's title or a terse summary of the task. Set it with `--title` rather than letting it derive from the first message. - If the new session should **investigate and get approval before writing code**, pass `--permission-mode plan`. Writing "start in plan mode" in the prompt does **not** work: the session's backend has already launched in the host's default mode by the time it reads that first message. The flag is the only thing that actually sets it. ## 2. Spawn + send, in one command `agentium spawn` already defaults `--host`/`--cwd`/`--backend` to *this* session's own state (`$AGENTIUM_SESSION`), so a bare spawn starts a sibling in the same worktree on the same host — no need to look them up. `--prompt-file -` reads the first message from stdin, so a heredoc carries a long, multi-line prompt with **zero shell-escaping** (no wrestling with quotes, `$`, or newlines). `--wait` blocks (bounded) until the host answers with the new session's kind-31988 state; `.session` is its durable `agentium:` ref. ```bash ref=$(agentium spawn --title "<short title>" --wait --json --prompt-file - <<'EOF' | jq -r .session <the self-contained task prompt — as many lines as you like, no escaping> EOF ) echo "$ref" ``` Add `--permission-mode plan` when the task should be investigated and approved before any code is written. That's the whole handoff. Notes: - Use a **quoted** heredoc delimiter (`<<'EOF'`) so the shell doesn't expand `$` in the prompt body. - To hand off into a **different worktree**, add `--cwd /path/to/worktree` (a Dave host must be running on the target host to pick up the spawn). - If you're **not inside a Dave session** (`$AGENTIUM_SESSION` unset), there's nothing to inherit — pass `--host` and `--cwd` explicitly (fall back to `hostname` / `pwd`). - `--prompt-file <path>` also takes a real file if you'd rather write the prompt to your scratchpad first; it's mutually exclusive with `--prompt`. - **Pipe the JSON straight into `jq`.** Don't add `tail -1`, `head -1`, or `read -r` — you don't need them (the output is one line per record), and if you ever hit an older `agentium` that pretty-prints, they turn a *successful* spawn into an empty `$ref`, which looks like a failure and tempts a re-run. ## A `--wait` timeout does NOT mean nothing was created `spawn` publishes the command **before** it starts waiting. So a timeout means "we didn't see the host's answer in time" — not "nothing happened". A slow host still materializes the session and still delivers the `--prompt`, because the prompt rides the command. **Never re-run the spawn on a timeout.** Check first: ```bash agentium list --cwd "$(pwd)" ``` If the session is there, the handoff worked — take its ref and report it. Only if nothing appeared is it worth suspecting no Dave host is running on the target host (or that `--cwd` is wrong). Re-running is also *guarded* now, not just discouraged: an identical spawn within ten minutes is refused before publishing, naming the session it would have duplicated, and a host that does see a repeat answers it with the session it already made. `--allow-duplicate` overrides the guard when you genuinely want a second session in the same worktree. Treat the guard as a backstop, not a licence to retry blindly — check `list` first. ## 3. Report back Tell the user the new session's ref and how to watch it: handed off to <ref> — follow it with `agentium log <ref> -f` Then finish wrapping up *this* session per CLAUDE.md (commit, headway comment + move, etc.). The handoff doesn't excuse leaving the current work half-done. ## Notes - `agentium` needs a signing key; inside a Dave session it's already configured. If a command complains you're not logged in, see the `agentium` skill's "Logging in" section. - One handoff = one new session. To fan out several tasks, repeat `/handoff` (or spawn once per task); don't cram multiple unrelated tasks into one prompt.