pi-squire 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- Every delegate now starts with `PI_UNATTENDED=1` in its environment, a
+  general signal that no human is watching the session. Delegates run as a
+  full TUI, so extensions that open a dialog, such as a handoff gate or an
+  approval prompt, waited on nobody and stalled the delegate; they can read
+  this variable to skip the dialog instead. The test that pins the child's
+  exact environment now includes it.
+
 ## [0.5.1] - 2026-10-14
 
 ### Changed
@@ -228,7 +257,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.5.1...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.7.0...HEAD
+[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
 [0.4.0]: https://github.com/gvanderclay/pi-squire/compare/v0.3.2...v0.4.0

package/README.md

@@ -178,7 +178,11 @@ variable of its own. `PI_DELEGATE_PARENT` and `PI_DELEGATE_AUTO_EXIT` are set
 for the child, never read as configuration by the parent. The window starts
 with the tmux server's environment plus only these from the parent:
 `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR` (when the parent has it
-set), `PI_DELEGATE_PARENT` and `PI_DELEGATE_AUTO_EXIT`. Anything else the
+set), `PI_DELEGATE_PARENT` and `PI_DELEGATE_AUTO_EXIT`, and it always gets `PI_UNATTENDED=1`.
+`PI_UNATTENDED=1` is a general signal, not specific to pi-squire: no human is
+watching this session, even though it runs in a TUI. Other extensions may read
+it to skip a dialog or confirmation instead of waiting on one, and any other
+runner that starts Pi unattended can set it too. Anything else the
 parent process has, such as a `CLAUDE_CONFIG_DIR` set by a shell alias,
 reaches the child only through a `session:launch` contributor. `--model` and
 `--thinking` override the agent's defaults for one call, and an unknown value
@@ -557,8 +561,8 @@ Other extensions may rely on:
 - the `[delegate]` result text and the closed-without-a-result text;
 - `AGENT.md`'s frontmatter keys and its location,
   `<agent dir>/agents/<name>/AGENT.md`;
-- the child environment variables `PI_DELEGATE_PARENT` and
-  `PI_DELEGATE_AUTO_EXIT`.
+- the child environment variables `PI_DELEGATE_PARENT`,
+  `PI_DELEGATE_AUTO_EXIT` and `PI_UNATTENDED=1`.
 
 A `message:*` provider must:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.5.1",
+	"version": "0.7.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/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 =
@@ -469,6 +485,8 @@ export default function delegate(
 			PI_CODING_AGENT_DIR: getAgentDir(),
 			[PARENT_ENV]: parent,
 			[AUTO_EXIT_ENV]: start.autoExit ? "1" : "0",
+			// A general signal for any extension: no human watches this session, so don't wait on a dialog.
+			PI_UNATTENDED: "1",
 		};
 		if (start.rest.length > 0) env[FALLBACK_ENV] = start.rest.join(",");
 		const sessionDir = process.env[SESSION_DIR_ENV];
@@ -549,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/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));
 		},
 	};
 }