From 2d17d6d162d3b65c10752036228a1e5b0c436179 Mon Sep 17 00:00:00 2001 From: issacboy123 Date: Thu, 20 Aug 2026 05:14:29 -0700 Subject: [PATCH] docs(coding-agent): document persistent subagent sessions --- packages/coding-agent/CHANGELOG.md | 1 + packages/coding-agent/docs/sessions.md | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index fd2a2be4e..58e0fa206 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -5,6 +5,7 @@ ### Added - Added `pi auth check` provider/model auth preflight with optional credential output ([#7152](https://github.com/earendil-works/pi/issues/7152)). +- Added durable, branch-scoped sub-agent rosters and child histories for saved sessions, with interrupted restoration and explicit wake without automatic work, replay, or result delivery. ### Changed diff --git a/packages/coding-agent/docs/sessions.md b/packages/coding-agent/docs/sessions.md index b6bb6421c..b4c30a981 100644 --- a/packages/coding-agent/docs/sessions.md +++ b/packages/coding-agent/docs/sessions.md @@ -27,6 +27,7 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f | `/new` | Start a new session | | `/name ` | Set the current session display name | | `/session` | Show session info | +| `/subagents` | Show sub-agents in the current session | | `/tree` | Navigate the current session tree | | `/fork` | Create a new session from a previous user message | | `/clone` | Duplicate the current active branch into a new session | @@ -34,6 +35,14 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f | `/export [file]` | Export session to HTML | | `/share` | Upload as a secret GitHub Gist and return its direct URL | +## Sub-agents in Saved Sessions + +Saved parent sessions automatically preserve their branch-scoped sub-agent roster and usable child histories. Reopening a parent restores terminal records as recorded and changes children that were queued or running to interrupted. Reopening does not resume provider work, replay the original task, or redeliver a completed result. + +An explicit wake resumes a child from its saved history when that history is usable. If the history is missing, unsafe, or invalid, Diffex creates an isolated replacement and runs only the wake message. A wake uses the child's complete captured model, thinking level, tools, and harness when all remain usable; otherwise it uses the complete current parent configuration and reports a warning rather than mixing configurations. + +Branch navigation and session-context resets reconcile the roster only after the transition is safe. In-memory parents and `--no-session` sessions keep sub-agents ephemeral. Setting `subagents: false` disables the sub-agent tools without erasing a saved roster. + ## Resuming and Deleting Sessions `/resume` opens an interactive session picker for the current project. `diffex -r` opens the same picker at startup.