pi-squire 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-26
+
+### Changed
+
+- Delegates open in a companion tmux session, `<your session>-squire`, instead
+  of your own session, created on demand and removed by tmux with its last
+  window. pi-squire marks the session it creates (tmux session option
+  `@squire-companion`), so only a marked session counts as a companion: your
+  own session called `pi-squire` gets `pi-squire-squire`. Set
+  `"windowPlacement": "current"` in `<agent dir>/squire/settings.json` to open
+  them in your session as before; any other value refuses the launch.
+  The start message, `delegation_status` and the delegate card name the session,
+  and the `delegate` and `delegation_resume` results and the status details gain
+  an optional `windowSession`. `session:launch` is unchanged.
+- tmux 3.2 or later is now required (it was 3.0); `/delegate`, `/delegate-resume`
+  and the tools refuse an older tmux with its version.
+
+## [0.11.0] - 2026-10-26
+
+### Added
+
+- The `session:launch` payload gains a read-only `toolCallId`, the ID of the
+  `delegate` tool call that started the launch, so a listener can tie a
+  delegate's window to that call. It is `undefined` for a launch from the
+  `/delegate` command.
+- `delegation_resume` and `/delegate-resume <id> [--model …] [--thinking …] [--auto-exit|--no-auto-exit] <task>` reopen an exited delegate's own session (`pi --session <path>`) in a new window with a follow-up task. The resume is recorded as a new delegation with `resumedFrom`; mail, replies and usage-limit marks use the delegation's session id, so records from before resuming read as before. A delegate whose working directory is gone, one still running, one whose window is open and an older delegation of a resumed chain are refused. `delegation_status` shows `resumed from` and `resumed as`, results and closed-without-a-result messages name `resumedFrom`, and the latter point to `delegation_resume`. The `delegate` tool's description mentions it, and `--session` joins the launch invariants listed for `session:launch`. A resume emits `session:launch`
+  too, with `toolCallId` set to the `delegation_resume` call, or `undefined`
+  from `/delegate-resume`; unlike a launch's, it comes before the task is sent,
+  because a resume mails the task only once its window is open (mail for a
+  window that never opened would otherwise reach the next resume as a second
+  task; a failed send kills the new window). A resumed delegation is never
+  reported closed without a result.
+
 ## [0.10.0] - 2026-10-24
 
 ### Added
@@ -458,7 +491,9 @@ author's dotfiles; the changes below are against that copy.
 
 - The published file list includes `child.ts`, which `index.ts` imports.
 
-[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/gvanderclay/pi-squire/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/gvanderclay/pi-squire/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/gvanderclay/pi-squire/compare/v0.9.5...v0.10.0
 [0.9.5]: https://github.com/gvanderclay/pi-squire/compare/v0.9.4...v0.9.5
 [0.9.4]: https://github.com/gvanderclay/pi-squire/compare/v0.9.3...v0.9.4

package/README.md

@@ -16,9 +16,11 @@ You need:
   options the parent guidance uses, and the extension APIs the package relies
   on. Pi supplies the peer dependencies `@earendil-works/pi-coding-agent` and
   `typebox`.
-- tmux 3.0 or later, with the Pi session running in a tmux pane. That is the
-  first version with `new-window -e`. A window is opened in the pane's
-  session, so a client attached elsewhere does not matter.
+- tmux 3.2 or later, with the Pi session running in a tmux pane. That is the
+  first version with `new-session -e` and `display-popup`. Windows are placed
+  relative to the pane's session (see [Where delegate windows
+  open](#where-delegate-windows-open)), so a client attached elsewhere does
+  not matter.
 - A provider of `message:*`;
   [pi-session-mail](https://github.com/gvanderclay/pi-session-mail) is one
   example. Without a provider there is no way to send the task or get an
@@ -130,6 +132,39 @@ temporary folder, not as text on the command line.
   missing. In print mode (`pi -p`) Pi does not show the refusal notices, so
   the refusal is silent there.
 
+## Where delegate windows open
+
+By default a delegate's window opens in a **companion session** named after
+yours with `-squire` added: from the session `work`, delegates go to
+`work-squire`. Your own session stays as it is, even when its name already
+ends in `-squire`: a session called `pi-squire` gets `pi-squire-squire`.
+pi-squire marks each companion session it creates with the tmux session
+option `@squire-companion`; a parent that runs in a marked session uses it, so
+a delegate that delegates does not make `work-squire-squire`.
+
+- The session is created on demand, by the launch that needs it, and tmux
+  removes it with its last window, so it does not outlive its delegates.
+- `detach-on-destroy` is set to `off` (and the mark set) on that session only: if you are
+  looking at it when its last delegate exits, tmux moves you to your most
+  recent other session instead of detaching you. Your sessions and tmux's
+  global options are never changed.
+- The start message, the delegate card and the `delegate` and
+  `delegation_resume` results show the session the window opened in, as the
+  optional `windowSession`; they keep that name. `delegation_status` looks it
+  up each time, so it follows a window you move to another session, which is
+  still found, closed and resumed.
+
+To open windows in your own session, as before, set `windowPlacement` in
+`<agent dir>/squire/settings.json`, beside `worktreeRoot`:
+
+```json
+{ "windowPlacement": "current" }
+```
+
+The values are `companion` (the default when the setting is absent) and
+`current`. The file is read at each launch. Any other value refuses the launch
+with an error naming the file, before the task is sent or a window opens.
+
 ## Working directory
 
 `--cwd <dir>` (the `delegate` tool's `cwd`) runs the delegate in an existing
@@ -428,7 +463,7 @@ agent's `auto-exit`.
 
 ## Tools
 
-The model gets three tools. They share the command's launch path and the
+The model gets four tools. They share the command's launch path and the
 session's delegation records. None of them is registered inside a delegate.
 
 | Tool | Parameters | What it does |
@@ -436,6 +471,7 @@ session's delegation records. None of them is registered inside a delegate.
 | `delegate` | `agent`, `task`, optional `model`, `thinking`, `label`, `cwd` and `auto_exit` (boolean) | Validates the call the way the command does, starts the delegation without opening a dialog (except an unresolved [trust question](#project-trust) for `cwd`), and returns the delegation id at once without waiting for a result. |
 | `delegation_status` | optional `id` | Reports each delegation as running, done, closed or closed without a result, with the window, the delegate's session and the result envelope's path. |
 | `delegation_close` | `id` | Kills the window through tmux and records the close, so `delegation_status` reports it closed. |
+| `delegation_resume` | `id`, `task`, optional `model`, `thinking` and `auto_exit` | Reopens an exited delegate's own session in a new window with a follow-up task, and returns the new delegation's id at once (see [Resuming a delegation](#resuming-a-delegation)). |
 
 The `delegate` tool's description lists the current roster, one line per agent:
 its name, description, default model and thinking, auto-exit when it is off,
@@ -778,6 +814,59 @@ session or offer to fork it rather than open it when the delegate ran in
 another directory or its file lives in another storage directory. The
 absolute path opens that file directly.
 
+## Resuming a delegation
+
+An exited delegate can continue its own session with a follow-up task:
+
+```text
+/delegate-resume <id> [--model <provider/id>] [--thinking <level>] [--auto-exit | --no-auto-exit] <task…>
+```
+
+The model does the same with `delegation_resume` (`id` and `task`, optionally
+`model`, `thinking` and `auto_exit`), which returns the `delegate` tool's result
+plus `resumedFrom`. The command completes the ids that can still be resumed.
+
+- The delegate's own session file is reopened with `pi --session <absolute path>`
+  and the recorded `--session-dir`, in a new window named like the first. The
+  delegate keeps everything it read and decided; Pi appends to the same file.
+  Opening it yourself is `pi --session <path>`, outside this tool.
+- The resume is recorded as a **new delegation** with its own id and a
+  `resumedFrom` naming the old one. Its task goes to the old session's mail
+  address, and its result arrives as a `[delegate]` message that names
+  `resumed from <id>`. Status shows `resumed from <id>` on the new delegation and
+  `resumed as <id>` on the old one. A late reply to the old request still
+  settles the old delegation only, and a resumed delegation is never reported
+  closed without a result.
+- Unlike a launch, the task is mailed after the window opens: the session's
+  inbox outlives a failed attempt, so a task sent for a window that never
+  opened would reach the next resume as a second task. The reopened delegate
+  receives it once its mailbox starts. If the send fails, the new window is
+  killed and nothing is recorded.
+- A chain resumes from its newest delegation; resuming an older one is refused,
+  naming the newest.
+- It is refused, before anything is sent or opened, unless: the delegation is a
+  started one (not a workspace attempt); it is not `running` (mail a running
+  delegate instead) and tmux can be asked; no window with its id and name still
+  runs a program (an exited one is killed first; a window that merely shares the
+  name is ignored); its session file is found and the working directory in the
+  file's header still exists; its agent is still in the roster; and no other
+  resume of it is under way. A delegate whose window was killed mid-turn can be
+  resumed.
+- A removed working directory, a removed managed worktree included, makes a
+  delegation not resumable: Pi runs a reopened session in its stored directory.
+  The window opens in that directory, with project trust decided again for it as
+  for `cwd` (see [Project trust](#project-trust)); there is no `cwd` or
+  `worktree` for a resume, and no worktree is created.
+- Without `model` it continues on the model the delegate finished on, moving to
+  its agent's fallbacks when that one is unavailable or marked (see
+  [Usage limits](#usage-limits)). An explicit `model` is used alone and refused
+  rather than substituted. `thinking` and `auto_exit` default to the
+  delegation's own. The agent's prompt, tools and extensions are those of the
+  roster now.
+- `session:launch` is emitted as for any launch, with the same payload.
+- Not detected: a Pi process you opened yourself on the same session outside
+  pi-squire's window. Close it before resuming.
+
 ## Hooks
 
 The `js` block below is the contract's worked example, and
@@ -788,8 +877,10 @@ that block.
 
 ### `session:launch`
 
-`pi-squire` provides this hook. It emits `{ args, env, agent, cwd }` after the
-task has been sent and just before it opens the delegate's window.
+`pi-squire` provides this hook. It emits `{ args, env, agent, cwd, toolCallId }`
+just before it opens the delegate's window: for a launch, after the task has
+been sent; for a resume, before it is sent, since a resume mails the task once
+the window is open (see [Resuming a delegation](#resuming-a-delegation)).
 
 | Field | Meaning |
 | --- | --- |
@@ -797,15 +888,17 @@ task has been sent and just before it opens the delegate's window.
 | `env` | the child's environment, as `KEY`/`value` pairs |
 | `agent` | the agent's name, as in `<agent dir>/squire/agents/<name>/AGENT.md`; read it, do not change it |
 | `cwd` | the directory the window opens in, the parent's or the resolved `--cwd`; read it, do not change it |
+| `toolCallId` | the ID of the `delegate` or `delegation_resume` tool call that started the launch; absent when started from the `/delegate` or `/delegate-resume` command; read it, do not change it |
 
 Listeners may only append to `args` and add keys to `env`; there is no veto,
 and `pi-squire` passes both to tmux unchanged. Do all work synchronously: the
 emitter reads the payload the moment `emit` returns.
 
-`cwd`, the trust flag (`--approve` or `--no-approve`) and `--session-dir` are
-launch invariants that `pi-squire` chooses. The window opens in its own `cwd`,
+`cwd`, the trust flag (`--approve` or `--no-approve`), `--session-dir` and the
+session choice (`--session-id` for a new delegate, `--session` for a [resumed](#resuming-a-delegation)
+one) are launch invariants that `pi-squire` chooses. The window opens in its own `cwd`,
 whatever a listener assigns to the payload. A listener must not add another
-trust flag, `--session-dir` or a working-directory change to `args`, since
+trust flag, `--session-dir`, `--session` or `--session-id`, or a working-directory change to `args`, since
 that would launch a child whose trust or session storage the parent did not
 choose and cannot find; append only unrelated settings.
 
@@ -890,16 +983,17 @@ version and is listed under "Breaking" in [CHANGELOG.md](CHANGELOG.md).
 
 Other extensions may rely on:
 
-- the `session:launch` payload `{ args, env, agent, cwd }`, emitted
-  synchronously after the task is sent and before the window opens, with
+- the `session:launch` payload `{ args, env, agent, cwd, toolCallId }`, emitted
+  synchronously before the window opens (after the task is sent for a launch,
+  before it is sent for a resume), with
   `cwd`, the trust flag and `--session-dir` chosen by `pi-squire` (see
   [Hooks](#hooks));
 - the `message:send`, `message:inbound` and `message:scan` hooks, consumed as
   their sections document;
-- the `delegate`, `delegation_status` and `delegation_close` tool names,
+- the `delegate`, `delegation_status`, `delegation_close` and `delegation_resume` tool names,
   parameters, the recorded `workspace` shape and the `workspaceSnapshot`
   shape in results and status;
-- the `/delegate` syntax and flags;
+- the `/delegate` and `/delegate-resume` syntax and flags;
 - the `[delegate]` result text and the closed-without-a-result text;
 - `AGENT.md`'s frontmatter keys and its location,
   `<agent dir>/squire/agents/<name>/AGENT.md`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",