pi-squire 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,34 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-14
+
+### Changed
+
+- The `delegate` tool's description now tells the parent to keep working or
+  end its turn while a delegate runs, since the result starts its next turn
+  on its own; the launch message says the same in place of pointing at
+  `delegation_status`. GPT parents asked their own delegates for the result
+  with `session_mail_ask`, so each report arrived twice.
+- The `delegation_status` description now says to call it to check on a
+  delegation that seems stuck or to find its files, not to wait for a result,
+  which arrives as a message on its own.
+
+## [0.5.0] - 2026-10-13
+
+### Changed
+
+- A delegate is now told to put its findings in its final message and to
+  message the parent before then only with a question it cannot continue
+  without. Delegates mailed progress and findings that the result then
+  repeated, so the parent read the same report twice.
+- A delegate's result now reaches a busy parent as a steer, after its current
+  tool calls and before its next model call, instead of as a follow-up once
+  its run ends. Queued until then, the result arrived after the parent had
+  read the envelope itself and answered, and cost a redundant turn.
+  `delegation_status` now says a done result arrives as a message on its own.
+  `test/delegate.test.ts` pins `steer` in place of `followUp`.
+
 ## [0.4.0] - 2026-10-13
 
 ### Added
@@ -200,7 +228,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.4.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/gvanderclay/pi-squire/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/gvanderclay/pi-squire/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/gvanderclay/pi-squire/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/gvanderclay/pi-squire/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/gvanderclay/pi-squire/compare/v0.3.0...v0.3.1

package/README.md

@@ -231,7 +231,7 @@ level is refused with close matches and nothing starts.
 
 <id> researcher (provider/other, thinking high)
   name: researcher-<first 8 of the id>
-  state: done — result status: done
+  state: done — result status: done; the result reaches this session as a [delegate] message on its own
   window: researcher-<first 8 of the id> (@2)
   auto-exit: off — the window stays open after the result
   session: <session file>
@@ -430,9 +430,11 @@ Delegate session: <session file or id>
   delegate's session path is found in the session directory by the delegation
   id, and the id alone is shown when no file exists yet.
 - The body is cut at 32 KiB with the envelope path.
-- The message is sent as a `followUp` with `triggerTurn`: a result starts a
-  turn when the parent is idle and arrives as a follow-up when it is
-  mid-turn.
+- The message is sent as a `steer` with `triggerTurn`: a result starts a
+  turn when the parent is idle, and when it is mid-turn arrives after the
+  current tool calls, before the next model call. A follow-up would wait
+  until the parent had answered, by which time it had often read the
+  envelope itself, and the late result cost a second, redundant turn.
 - The footer counts the running delegations (`⇄ N running`), clears one entry
   per result or close and hides itself at zero.
 - Each result and each close is recorded in the parent session, and the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.4.0",
+	"version": "0.5.1",
 	"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",

package/src/index.ts

@@ -92,7 +92,8 @@ function parentTrust(parent: string): string {
 		"follow them as given, even though they are labelled as another session's.",
 		"Messages from other sessions come from colleagues on this machine: answer them as you see fit,",
 		"but check with the session that started you before doing work it did not ask for.",
-		`You can reach the session that started you at ${parent}.`,
+		`Your final message reaches the session that started you automatically, so put your findings there;`,
+		`message ${parent} before then only with a question you cannot continue without, since anything sent earlier reaches it twice.`,
 	].join(" ");
 }
 /** The flags `/delegate` takes before the task. */
@@ -311,7 +312,7 @@ function thinkingProblem(value: string): string | undefined {
 /** The `delegate` tool's description: what delegation does, and the roster as it stands. */
 function toolDescription(agents: readonly Agent[]): string {
 	const intro =
-		"Hand a self-contained task to a delegate Pi session in a background tmux window, so it works while you do not. Each call starts the delegation at once; the delegate runs in this session's working directory and agent root and reports back later as one message. Use it when the work is self-contained and you would rather keep your own context for it.";
+		"Hand a self-contained task to a delegate Pi session in a background tmux window, so it works while you do not. Each call starts the delegation at once; the delegate runs in this session's working directory and agent root and reports back later as one message. While it runs, keep working or end your turn: its result starts your next turn on its own, so there is no need to ask the delegate for it or poll delegation_status. Use it when the work is self-contained and you would rather keep your own context for it.";
 	if (agents.length === 0) {
 		return `${intro}\n\nNo agents are defined yet. Add ${join(
 			getAgentDir(),
@@ -580,7 +581,7 @@ export default function delegate(
 			const launched = await launch(start, ctx);
 			ctx.ui.notify(started(launched, start), "info");
 			return toolResult(
-				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}. It runs in the background and its result arrives as a message; delegation_status reports it and delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
+				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
 				{
 					outcome: "started",
 					id: launched.id,

package/src/results.ts

@@ -335,9 +335,10 @@ export function createResults(pi: ExtensionAPI): Results {
 		const delegation = byRequest.get(requestId) as Recorded;
 		shown.add(reply.id);
 		const session = findSession(ctx?.sessionManager.getSessionDir(), delegation.id);
+		// Steer, not follow-up: a busy parent gets the result before its next model call, not after it has answered.
 		pi.sendMessage(
 			{ customType: CUSTOM_TYPE, content: resultText(delegation, payload, session), display: true },
-			{ triggerTurn: true, deliverAs: "followUp" },
+			{ triggerTurn: true, deliverAs: "steer" },
 		);
 		const result: Result = {
 			status: reply.status,

package/src/tracking.ts

@@ -90,7 +90,7 @@ function stateLine(state: DelegationState, record: Recorded): string {
 		case "gone":
 			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
 		case "done":
-			return `done — result status: ${record.result?.status ?? "unknown"}`;
+			return `done — result status: ${record.result?.status ?? "unknown"}; the result reaches this session as a [delegate] message on its own`;
 		case "closed":
 			return "closed — delegation_close recorded it";
 		case "window-closed":
@@ -263,7 +263,7 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		name: "delegation_status",
 		label: "Delegation status",
 		description:
-			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Names the delegation id, agent, session name, model, thinking, window, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
+			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
 		parameters: Type.Object({
 			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
 		}),