pi-subagent: opt-in sessions, to follow up, resume after a timeout, or fork

run-agent.sh still runs with --no-session by default. --session saves the
run as session <name> under <workdir>/sessions/; --followup TEXT sends the
next message in it, from any provider and model; --fork FROM starts <name>
as a copy of FROM. A follow-up or fork inherits --tools, --thinking, --cwd
and --context-files, so a read-only subagent stays read-only, and the
earlier round's files move to <name>.round<N>.*.

Sessions are opened by file path: by id, pi looks only among sessions
started in the current directory and otherwise silently creates an empty
one, exit 0. A fresh retry moves the old session aside, since pi would
resume it given the same id.

pi-review-panel launches members with --session, so a contradiction can be
put to both reviewers before it is settled; verdicts are still tallied from
the original reviews.

From dot request 20261021-123436-work-laptop-d0adf2.

1 files changed, 58 insertions, 6 deletions

diff --git a/skills/pi-subagent/SKILL.md b/skills/pi-subagent/SKILL.md
index c5f1bfb..7b17e50 100644
--- a/skills/pi-subagent/SKILL.md
+++ b/skills/pi-subagent/SKILL.md
@@ -5,8 +5,9 @@ description: >-
   run in the background, and collects each one's final answer plus its actual
   billed cost. Covers a single delegated task, the same task fanned out to
   several models for independent answers, or a job split into separate tasks
-  run in parallel, followed by verifying what came back. Use when the user
-  asks for subagents, to hand something to another model, to get several
+  run in parallel, followed by verifying what came back; a run saved as a
+  session can be followed up, resumed after a timeout, or forked. Use when
+  the user asks for subagents, to hand something to another model, to get several
   models' takes, or to parallelize work across pi runs — and when another
   skill (such as pi-review-panel) builds on it. Spawning costs money: never
   start subagents on your own initiative without the user asking.
@@ -118,7 +119,8 @@ Always in the background, so you can keep working:
 
 Options go before the positionals: `--brief FILE` (default `$P/brief.md`),
 `--timeout SECS` (default 1800), `--thinking LEVEL` (default `high`),
-`--tools LIST`, `--cwd DIR`, `--context-files`, `--deliver TEXT`. Names must be
+`--tools LIST`, `--cwd DIR`, `--context-files`, `--deliver TEXT`, and
+`--session` to keep the conversation for a follow-up (§10). Names must be
 unique within a workdir; a natural scheme is `<provider-abbrev>-<model>` for a
 fan-out and `<part>` for a split.
 
@@ -164,8 +166,11 @@ ends with the fixed final line. Exit 124 is the timeout firing. `<name>.err`
 and `<name>.jsonl` say what happened otherwise.
 
 Retry a failure once, under the same name: `run-agent.sh` moves the failed
-run's files to `<name>.attempt<N>.*` first, cost included. If it fails twice,
-report it with its cost and carry on — one dead provider must not sink the job.
+run's files to `<name>.attempt<N>.*` first, cost included. A run started with
+`--session` that timed out after real progress is often better continued than
+retried: `--followup` it (§10), and it picks up with everything it had read
+and run. If it fails twice, report it with its cost and carry on — one dead
+provider must not sink the job.
 For a split, a failed part is a gap you either fill yourself or report.
 
 ## 7. Verify, then use
@@ -176,7 +181,11 @@ What comes back is raw material, not results:
   hallucinate line numbers, APIs, file contents and measurements, with
   confidence.
 - **Disagreement is where the answer is.** When answers conflict, run the
-  experiment that decides it and say who was right.
+  experiment that decides it and say who was right. With sessions (§10) you
+  can also put each side's claim to the other first — but a subagent
+  conceding or holding firm is not evidence either; the experiment is.
+- **Ask for the evidence.** With a session, a vague or surprising claim can be
+  followed up: "show the exact command and output behind X".
 - **Consensus is weak evidence.** Several models agreeing can all be making the
   same mistake, or testing the same wrong version. One claim you confirmed
   outranks four you didn't.
@@ -207,3 +216,46 @@ varies a lot across models, say so: it informs who to use next time.
 `$P` won't survive the session. If the answers matter, copy the `.md` outputs,
 the cost files, and any verification scripts somewhere durable in the project,
 and link those instead of `$P`.
+
+## 10. Follow up, resume, fork
+
+Off by default: a run saves nothing, and once it ends it can't be talked to
+again. Pass `--session` at launch when you expect to come back to it — a long
+run that may time out, a fan-out whose disagreements you'll want to put back
+to the subagents, anything you may need to question. It costs nothing extra
+until used. The session is kept as `$P/sessions/<timestamp>_<name>.jsonl`.
+
+Then, once that run has finished:
+
+```bash
+# Continue the same conversation. Provider and model may differ from before.
+"$SK/run-agent.sh" --followup "<message>" "$P" <provider> "<model>" <name>
+
+# Branch it into a new name; the original session is left as it was.
+"$SK/run-agent.sh" --fork <name> --followup "<message>" "$P" <provider> "<model>" <new-name>
+```
+
+- **Uses.** Continue a run that timed out ("You were cut off. Carry on from
+  where you stopped and deliver the full result"). Ask for the evidence behind
+  a claim. Put another subagent's contradicting finding to it ("Another
+  reviewer says X, because Y. Check it and say who is right, with evidence").
+  Fork to ask several different questions of the same context without them
+  seeing each other, or to hand a whole investigation to a different model —
+  it reads the full history, whoever produced it.
+- **The message is sent as written.** No brief, no `--deliver` wrapper, so say
+  what to deliver and end with the same fixed final line if you'll tally it.
+- **What carries over.** A follow-up or fork inherits `--tools`, `--thinking`,
+  `--cwd` and `--context-files` from the run it continues, so a read-only
+  subagent stays read-only; pass one again to change it.
+- **Outputs.** The earlier round's files move to `<name>.round<N>.*`, so every
+  answer is kept and every round is its own row in the cost table. Each
+  follow-up resends the whole conversation as input: a short question to a long
+  session is not cheap.
+- **Limits.** A run killed mid-step loses that step; everything before it is
+  in the session. `run-agent.sh` refuses to follow up or fork a run still in
+  flight. A fresh retry under the same name (no `--followup`) starts a new
+  conversation and moves the old session aside.
+- **Don't hand-roll the resume.** By id, pi looks only among sessions started
+  in the current directory, and where it finds none it silently starts a new,
+  empty one under that id — exit 0, and an answer from a model that remembers
+  nothing. `run-agent.sh` opens the session by its file path instead.