pi-squire 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,40 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-20
+
+### Added
+
+- A delegate's footer shows that it is a delegate and whether auto-exit is
+  on: `👦 delegate · auto-exit on`, or
+  `👦 delegate · auto-exit off`. It follows the
+  setting as typing turns it off and `/auto-exit` turns it back on.
+
+### Changed
+
+- The parent's footer reads `👨 N delegates running` instead of
+  `⇄ N running`. Each side picks its icon at random per session: 👨 or 👩
+  for the parent, 👦 or 👧 for a delegate. The footer tests in
+  `test/delegate.test.ts` change to match.
+
+## [0.7.0] - 2026-10-19
+
+### Added
+
+- `delegate`, `delegation_status` and `delegation_close` declare an
+  `outputSchema` and return matching `structuredContent`, so a codemode
+  script gets objects instead of text. `delegation_status` gives each
+  delegation its derived `state` (`running`, `done`, `gone`, `closed`,
+  `window-closed` or `unknown`), also added to its details.
+  `delegation_close` returns one shape on every path:
+  `{ id, windowId, windowName, closed, alreadyClosed, killed }`; its details
+  gain the fields each path lacked. The model-facing text is unchanged.
+- The three tools declare MCP-style `annotations`: `delegation_status` is
+  read-only and idempotent; `delegation_close` is destructive and idempotent;
+  `delegate` is neither, and is the only one that reaches an open world,
+  since the delegate it starts calls a remote model and runs tools
+  unattended.
+
 ## [0.6.0] - 2026-10-15
 
 ### Added
@@ -239,7 +273,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.6.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/gvanderclay/pi-squire/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/gvanderclay/pi-squire/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/gvanderclay/pi-squire/compare/v0.5.1...v0.6.0
 [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

package/README.md

@@ -393,6 +393,10 @@ The parent resolves each delegation's auto-exit from the call
   notice: typed or RPC input, or a run the user stopped (Esc).
 - `/auto-exit` inside the delegate turns it on again for the next normal
   completion, whatever the launch said.
+- The footer shows that this is a delegate and whether auto-exit is on:
+  `👦 delegate · auto-exit on`, or
+  `👦 delegate · auto-exit off`, with 👦 or 👧
+  picked at random per session.
 
 There is no `subagent_done` tool: auto-exit off only means the window stays.
 
@@ -439,8 +443,9 @@ Delegate session: <session file or id>
   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.
+- The footer counts the running delegations (`👨 N delegates running`, with 👨 or 👩
+  picked at random per session), 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
   records are rebuilt synchronously at session start. A resume still
   recognises replies, including one that arrived while the parent was

package/package.json

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

package/src/child.ts

@@ -21,6 +21,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { activeMark, classify, type Response, recordLimit } from "./limits.ts";
+import { STATUS_KEY } from "./results.ts";
 
 /** The launch variable that carries the parent's resolved setting. */
 export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
@@ -104,6 +105,19 @@ function registerFallback(pi: ExtensionAPI): (model: string | undefined) => void
 	};
 }
 
+/** This delegate's footer icon, picked once per load. */
+const ICON = Math.random() < 0.5 ? "👦" : "👧";
+
+function showStatus(ctx: ExtensionContext, armed: boolean): void {
+	const { theme } = ctx.ui;
+	ctx.ui.setStatus(
+		STATUS_KEY,
+		armed
+			? `${ICON} delegate · auto-exit ${theme.fg("success", "on")}`
+			: `${ICON} delegate · auto-exit ${theme.fg("dim", "off")}`,
+	);
+}
+
 export function registerChild(pi: ExtensionAPI, parent: string): void {
 	registerTakeover(pi, parent);
 	const setLimited = registerFallback(pi);
@@ -112,10 +126,14 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 	/** Whether the run that just ended finished without the user stopping it. */
 	let completed = false;
 
+	// Reload and session replacement clear extension statuses, then start again.
+	pi.on("session_start", async (_event, ctx) => showStatus(ctx, armed));
+
 	function disarm(ctx: ExtensionContext): void {
 		if (!armed) return;
 		armed = false;
 		ctx.ui.notify(OFF_NOTICE, "info");
+		showStatus(ctx, armed);
 	}
 
 	// Typed text and RPC input are the user's; a prompt an extension sends is not.
@@ -166,6 +184,7 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 		handler: async (_args, ctx) => {
 			armed = true;
 			ctx.ui.notify(ON_NOTICE, "info");
+			showStatus(ctx, armed);
 		},
 	});
 }

package/src/index.ts

@@ -99,6 +99,22 @@ function parentTrust(parent: string): string {
 /** The flags `/delegate` takes before the task. */
 const FLAGS = ["--model", "--thinking", "--label", "--auto-exit", "--no-auto-exit"] as const;
 
+/** The `delegate` tool's structured result, which is also its details. */
+export const DelegateSchema = Type.Object({
+	outcome: Type.Literal("started"),
+	id: Type.String({ description: "The delegation id that delegation_status and delegation_close take." }),
+	agent: Type.String(),
+	model: Type.String({ description: "The provider/id it started on, after any fallback." }),
+	skipped: Type.Array(Type.Object({ model: Type.String(), reason: Type.String() }), {
+		description: "Earlier models in the fallback list that were passed over, and why.",
+	}),
+	notices: Type.Array(Type.String()),
+	thinking: Type.String(),
+	autoExit: Type.Boolean(),
+	windowId: Type.String(),
+	windowName: Type.String(),
+});
+
 const NOT_IN_TMUX = "this session is not inside tmux; start it in a tmux pane to open a delegate window";
 
 const USAGE =
@@ -551,6 +567,9 @@ export default function delegate(
 				}),
 			),
 		}),
+		outputSchema: DelegateSchema,
+		// Opens a new window each call and removes nothing. Open world: the delegate calls a remote model and runs its agent's tools unattended.
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
 		async execute(
 			_toolCallId: string,
 			params: {

package/src/results.ts

@@ -237,6 +237,7 @@ export function createResults(pi: ExtensionAPI): Results {
 	let ctx: ExtensionContext | undefined;
 	/** Whether the footer currently shows the entry, so a clear is sent only when needed. */
 	let footerShown = false;
+	const icon = Math.random() < 0.5 ? "👨" : "👩";
 
 	/** A delegation still going: no result and no recorded close. */
 	const running = (): Recorded[] =>
@@ -251,7 +252,7 @@ export function createResults(pi: ExtensionAPI): Results {
 		const visible = count > 0;
 		if (!visible && !footerShown) return;
 		footerShown = visible;
-		ctx.ui.setStatus(STATUS_KEY, visible ? `⇄ ${count} running` : undefined);
+		ctx.ui.setStatus(STATUS_KEY, visible ? `${icon} ${count} delegate${count === 1 ? "" : "s"} running` : undefined);
 	}
 
 	/** Rebuild the records from the session's entries, so a resume still recognises replies. */

package/src/tracking.ts

@@ -37,20 +37,76 @@ export type Tracking = {
 	stop(): void;
 };
 
-/** The one result every tool returns. */
+/** The one result every tool returns. `details` doubles as `structuredContent`, so it must match the tool's `outputSchema`; Pi does not check it. */
 export function toolResult(
 	payload: string,
-	details: unknown = {},
-): { content: { type: "text"; text: string }[]; details: unknown } {
-	return { content: [{ type: "text", text: payload }], details };
+	details: unknown,
+): { content: { type: "text"; text: string }[]; details: unknown; structuredContent: unknown } {
+	return { content: [{ type: "text", text: payload }], details, structuredContent: details };
 }
 
+/** Every tool here touches only local state: tmux, the session's entries and files under the agent directory. */
+const CLOSED_WORLD = { openWorldHint: false } as const;
+
+const DELEGATION_STATES: readonly DelegationState[] = ["closed", "done", "gone", "running", "window-closed", "unknown"];
+
+/** One delegation in `delegation_status`'s structured result; `viewDetails` builds it. */
+const DelegationSchema = Type.Object({
+	id: Type.String(),
+	name: Type.String(),
+	agent: Type.String(),
+	model: Type.String(),
+	thinking: Type.String(),
+	autoExit: Type.Boolean(),
+	windowId: Type.String(),
+	windowName: Type.String(),
+	state: Type.Union(
+		DELEGATION_STATES.map((state) => Type.Literal(state)),
+		{
+			description:
+				"running: window open, no result. done: a result arrived (see status, envelopePath). gone: the window went with no result; a late reply makes it done. closed: delegation_close recorded it. window-closed: the window is gone. unknown: tmux could not be asked. done and closed are final; gone and window-closed turn done if a late reply arrives.",
+		},
+	),
+	closed: Type.Boolean(),
+	closedWithoutResult: Type.Boolean(),
+	status: Type.Optional(Type.String({ description: "The result envelope's status: done, failed or stopped." })),
+	envelopePath: Type.Optional(Type.String()),
+	sessionPath: Type.Optional(Type.String()),
+	lastActiveAt: Type.Optional(
+		Type.String({ description: "ISO time the session file was last written; running only." }),
+	),
+});
+
+export const StatusSchema = Type.Object({
+	delegations: Type.Array(DelegationSchema),
+	marks: Type.Array(
+		Type.Object({
+			scope: Type.String(),
+			source: Type.Union([Type.Literal("reactive"), Type.Literal("proactive")]),
+			reason: Type.String(),
+			clearsAt: Type.String(),
+		}),
+	),
+	readingErrors: Type.Array(Type.Object({ provider: Type.String(), reason: Type.String(), at: Type.String() })),
+});
+
+export const CloseSchema = Type.Object({
+	id: Type.String(),
+	windowId: Type.String(),
+	windowName: Type.String(),
+	closed: Type.Literal(true),
+	alreadyClosed: Type.Boolean({ description: "An earlier delegation_close had recorded it; nothing was done." }),
+	killed: Type.Boolean({ description: "This call killed the delegate's window." }),
+});
+
 /** A tool as registered; `execute` takes the tool's own parameters, which the registration call does not check. */
 type ToolDef = {
 	name: string;
 	label: string;
 	description: string;
 	parameters: unknown;
+	outputSchema: unknown;
+	annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean; openWorldHint: boolean };
 	execute: (...args: never[]) => Promise<ReturnType<typeof toolResult>>;
 };
 
@@ -149,7 +205,7 @@ function viewText({ record, state, name, sessionPath, lastActive }: View): strin
 }
 
 /** The structured details for one delegation. */
-function viewDetails({ record, name, sessionPath, lastActive }: View): Record<string, unknown> {
+function viewDetails({ record, state, name, sessionPath, lastActive }: View): Record<string, unknown> {
 	return {
 		id: record.id,
 		name,
@@ -159,6 +215,7 @@ function viewDetails({ record, name, sessionPath, lastActive }: View): Record<st
 		autoExit: record.autoExit === true,
 		windowId: record.windowId,
 		windowName: record.windowName,
+		state,
 		closed: record.closed === true,
 		closedWithoutResult: record.gone === true && record.result === undefined && record.closed !== true,
 		status: record.result?.status,
@@ -267,6 +324,8 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		parameters: Type.Object({
 			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
 		}),
+		outputSchema: StatusSchema,
+		annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, ...CLOSED_WORLD },
 		async execute(
 			_toolCallId: string,
 			params: { id?: string },
@@ -310,6 +369,9 @@ function closeTool(results: Results, tmux: TmuxClient): ToolDef {
 		parameters: Type.Object({
 			id: Type.String({ description: "The delegation id to close." }),
 		}),
+		outputSchema: CloseSchema,
+		// Kills a window; a second close finds it recorded and does nothing.
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...CLOSED_WORLD },
 		async execute(
 			_toolCallId: string,
 			params: { id: string },
@@ -318,8 +380,15 @@ function closeTool(results: Results, tmux: TmuxClient): ToolDef {
 			_ctx: ExtensionContext,
 		): Promise<ReturnType<typeof toolResult>> {
 			const [record] = selectRecords(results, params.id);
-			if (record.closed === true)
-				return toolResult(`Delegation ${record.id} is already closed.`, { id: record.id, closed: true });
+			const closed = (alreadyClosed: boolean, killed: boolean) => ({
+				id: record.id,
+				windowId: record.windowId,
+				windowName: record.windowName,
+				closed: true,
+				alreadyClosed,
+				killed,
+			});
+			if (record.closed === true) return toolResult(`Delegation ${record.id} is already closed.`, closed(true, false));
 			let windows: TmuxWindow[];
 			try {
 				windows = await tmux.listWindows();
@@ -339,11 +408,7 @@ function closeTool(results: Results, tmux: TmuxClient): ToolDef {
 			const how = alive
 				? `killed window ${record.windowName} (${record.windowId})`
 				: `its window ${record.windowName} was already gone`;
-			return toolResult(`Closed delegation ${record.id}: ${how}.`, {
-				id: record.id,
-				windowId: record.windowId,
-				killed: alive,
-			});
+			return toolResult(`Closed delegation ${record.id}: ${how}.`, closed(false, alive));
 		},
 	};
 }