pi-squire 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -6,6 +6,37 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-10-09
+
+### Added
+
+- Agent frontmatter `extensions` lists extension paths loaded only by that
+  agent's delegate, each passed to its Pi as `-e` on top of its normal
+  extensions. `~` expands and relative paths resolve against the `AGENT.md`'s
+  directory; a path that does not exist leaves the agent out with a warning.
+- Agent frontmatter `tools` lists the delegate's visible tools, passed as
+  `--tools`. Without discovery tools such as `codemode` or `tool_search`, only
+  listed tools are visible; Pi can keep unlisted MCP tools registered unless
+  the list includes an `mcp__` entry, and discovery tools can expose them.
+  Names are not checked against the parent's tools, and `exclude-tools` still
+  applies alongside.
+
+### Fixed
+
+- The `delegate` tool treats `null` or the string `"null"` in `model`,
+  `thinking` or `label` as unset, so the agent's defaults apply. Before, a
+  `null` model crashed the call and `"null"` was refused as not provider/id.
+
+## [0.3.1] - 2026-10-03
+
+### Changed
+
+- With auto-exit on, a delegate whose run ends on a usage-limit error now
+  closes its window, as after a normal completion. The parent still gets the
+  `failed` reply and the session file stays. Other failures still leave the
+  window open. `test/harness.test.ts` now fails its run with a `400` instead
+  of a `429`, since a `429` is a usage limit and now exits.
+
 ## [0.3.0] - 2026-10-03
 
 ### Added
@@ -138,7 +169,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.3.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.3.2...HEAD
+[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
 [0.3.0]: https://github.com/gvanderclay/pi-squire/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/gvanderclay/pi-squire/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/gvanderclay/pi-squire/compare/v0.2.0...v0.2.1

package/README.md

@@ -116,7 +116,7 @@ The roster is read at call time from `<agent dir>/agents/<name>/AGENT.md`, one
 directory per agent, so a new agent is usable without a reload. Frontmatter
 carries `description`, `model` (`provider/id`) and `thinking`, and optionally
 `auto-exit` (`true` or `false`, default `true`; see [Auto-exit](#auto-exit)),
-`exclude-tools` and `fallback`. The body is the delegate's system prompt,
+`exclude-tools`, `tools`, `extensions` and `fallback`. The body is the delegate's system prompt,
 appended to Pi's own prompt; it reaches the child as a path to a private file
 under the system temporary folder, so the text stays off the command line. The
 [first-use example](#first-use) is a complete `AGENT.md`.
@@ -133,6 +133,23 @@ delegate's result reaches the parent through the `message:*` provider's reply
 when its run settles, not through a tool, so excluding tools cannot stop it
 answering.
 
+`tools` lists tools for the delegate as a comma-separated or YAML list
+(`tools: device_run`). It reaches the child as `--tools device_run`, which
+covers extension tools too. Without discovery tools such as `codemode` or
+`tool_search`, only the listed tools are visible. Pi can keep unlisted MCP
+tools registered unless the list includes an `mcp__` entry; discovery tools can
+also expose them. Names are not checked against the parent's tools, since a
+tool from one of the agent's own `extensions` exists only in the child. Empty or
+absent passes no flag. `exclude-tools` still applies alongside.
+
+`extensions` lists extension paths only this agent's delegate loads, as a
+comma-separated or YAML list. Each reaches the child as a repeated
+`-e <absolute path>`, on top of its normal extensions, so pi-squire and the
+`message:*` provider still load and the result still reaches the parent. `~`
+and `~/` expand to the home directory and a relative path resolves against the
+directory holding that `AGENT.md`. A path that does not exist when the roster
+is read leaves the agent out, with a warning.
+
 `fallback` lists models to try, in order, when the agent's `model` is
 usage-limited (see [Usage limits](#usage-limits)), as a comma-separated list
 or a YAML list of `provider/id`. An entry that is not `provider/id` is dropped
@@ -150,7 +167,8 @@ An `AGENT.md` that cannot be used is left out of the roster and named in a
 warning. That covers missing fields, a model that is not `provider/id`, an
 unknown thinking level, an `auto-exit` that is not `true` or `false`, an
 `exclude-tools` that is not a list of names or names a tool the session does
-not have, and an empty body. With no agents at all, `/delegate` says how to
+not have, a `tools` or `extensions` that is not a list, an extension path that
+does not exist, and an empty body. With no agents at all, `/delegate` says how to
 add one.
 
 ## Configuration
@@ -353,7 +371,9 @@ The parent resolves each delegation's auto-exit from the call
   down (`ctx.shutdown()`) on the next event-loop turn, after the settle
   reply has been sent, so its tmux window closes. The session file stays, and
   `pi --session <path>` reopens it.
-- A run that ended stopped or failed never exits the delegate.
+- A run that ended stopped, or failed on anything but a usage limit, never
+  exits the delegate. A usage-limit failure is final until the quota resets,
+  so it exits like a normal completion; the parent still gets the failed reply.
 - The user taking over turns it off for the rest of the session, with a
   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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"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/agents.ts

@@ -2,10 +2,15 @@
 // call time so a new agent is usable without a reload. Frontmatter carries
 // `description`, `model` and `thinking`, and optionally `auto-exit` (default
 // true) and `exclude-tools` (tools the delegate goes without, passed to its Pi
-// as `--exclude-tools`; each must be a tool the parent session has); the body
+// as `--exclude-tools`; each must be a tool the parent session has), `tools`
+// (the delegate's complete tool allowlist, passed as `--tools`, not checked
+// against the parent) and `extensions` (extra extension paths for the
+// delegate only, each passed as `-e`; `~` expands, relative paths resolve
+// against the AGENT.md's directory, and a missing path leaves the agent out); the body
 // is the delegate's system prompt. A file that is missing or malformed is left out, with a warning.
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
@@ -33,6 +38,10 @@ export type Agent = {
 	autoExit: boolean;
 	/** Tools the delegate goes without, from `exclude-tools`; empty means all of them. */
 	excludeTools: string[];
+	/** The delegate's complete tool allowlist, from `tools`; empty means no `--tools` flag. */
+	tools: string[];
+	/** Absolute paths of extra extensions the delegate loads, from `extensions`; empty when absent. */
+	extensions: string[];
 	/** Models to try, in order, when `model` is usage-limited; from `fallback`, empty when absent. */
 	fallback: string[];
 	/** The body of `AGENT.md`: the delegate's system prompt. */
@@ -96,6 +105,8 @@ function parseAgent(
 		return {
 			warning: `${path} has exclude-tools ${JSON.stringify(unknownTool)}, not a tool this session has; skipped`,
 		};
+	const launch = launchFields(path, frontmatter);
+	if ("warning" in launch) return launch;
 	// A bad fallback entry is dropped with a note; it never costs the agent.
 	const notes: string[] = [];
 	const listedFallback = toolList(frontmatter.fallback);
@@ -115,12 +126,41 @@ function parseAgent(
 			thinking: thinking as Thinking,
 			autoExit: autoExit ?? true,
 			excludeTools,
+			...launch,
 			fallback,
 			prompt: body,
 		},
 	};
 }
 
+/** The `tools` and `extensions` fields, or the warning that leaves the agent out. */
+function launchFields(
+	path: string,
+	frontmatter: Record<string, unknown>,
+): { tools: string[]; extensions: string[] } | { warning: string } {
+	const tools = toolList(frontmatter.tools);
+	if (tools === null)
+		return {
+			warning: `${path} has tools ${JSON.stringify(frontmatter.tools)}, not a comma-separated list of tool names; skipped`,
+		};
+	const paths = toolList(frontmatter.extensions);
+	if (paths === null)
+		return {
+			warning: `${path} has extensions ${JSON.stringify(frontmatter.extensions)}, not a comma-separated list of paths; skipped`,
+		};
+	const extensions = (paths ?? []).map((entry) => resolveExtension(entry, dirname(path)));
+	const absent = extensions.find((entry) => !existsSync(entry));
+	if (absent !== undefined) return { warning: `${path} has extension ${absent}, which does not exist; skipped` };
+	return { tools: tools ?? [], extensions };
+}
+
+/** An extension path as an absolute one: `~` is the home directory, a relative path is against the AGENT.md's directory. */
+function resolveExtension(entry: string, dir: string): string {
+	if (entry === "~") return homedir();
+	if (entry.startsWith("~/")) return join(homedir(), entry.slice(2));
+	return isAbsolute(entry) ? entry : resolve(dir, entry);
+}
+
 /** A list of names (tools or models), comma-separated or a YAML list of names; undefined when absent, null when it is neither. */
 function toolList(value: unknown): string[] | undefined | null {
 	if (value === undefined || value === null) return undefined;

package/src/child.ts

@@ -17,7 +17,7 @@
 // ponytail: drop the takeover once #5581 lands and the minimum Pi has it.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { type Response, recordLimit } from "./limits.ts";
+import { classify, type Response, recordLimit } from "./limits.ts";
 
 /** The launch variable that carries the parent's resolved setting. */
 export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
@@ -99,7 +99,9 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 		const stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
 		if (stopped) disarm(ctx);
 		if (!stopped && last?.stopReason === "error") recordUsageLimit(last, ctx, response);
-		completed = !stopped && last?.stopReason !== "error";
+		// A usage limit is final until the quota resets, so it ends the work like a completion.
+		const limited = typeof last?.errorMessage === "string" && classify(last.errorMessage) !== undefined;
+		completed = !stopped && (last?.stopReason !== "error" || limited);
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {

package/src/index.ts

@@ -17,7 +17,8 @@
 // call) the delegate closes its own window after a normal completion; the
 // delegate's side lives in `child.ts`. With it off the window stays open.
 // An agent's `exclude-tools` goes to the child as `--exclude-tools`; a name the
-// session has no tool for leaves the agent out of the roster.
+// session has no tool for leaves the agent out of the roster. Its `tools` goes
+// as `--tools` and each of its `extensions` as `-e`, both for the child alone.
 //
 // The model gets three tools. `delegate` takes agent, task and optional model
 // and thinking, validates them the way the command does, and starts the
@@ -308,7 +309,7 @@ function toolDescription(agents: readonly Agent[]): string {
 			"agents",
 			"<name>",
 			"AGENT.md",
-		)} with frontmatter description, model and thinking and the prompt as its body; /delegate explains the format too.`;
+		)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback) and the prompt as its body; /delegate explains the format too.`;
 	}
 	return [
 		intro,
@@ -318,7 +319,7 @@ function toolDescription(agents: readonly Agent[]): string {
 			(agent) =>
 				`- ${agent.name} — ${agent.description} (default ${[agent.model, ...agent.fallback.map((model) => `fallback ${model}`)].join(", ")}, thinking ${agent.thinking}${agent.autoExit ? "" : ", auto-exit off"}${
 					agent.excludeTools.length > 0 ? `, no ${agent.excludeTools.join("/")}` : ""
-				})`,
+				}${agent.tools.length > 0 ? `, tools: ${agent.tools.join("/")}` : ""})`,
 		),
 		"",
 		"`model` and `thinking` override the agent's defaults for this call; an unknown value is refused with close matches. `label` names the delegate's window and session; give one that says what the task is. `delegation_status` reports a delegation, and `delegation_close` ends one.",
@@ -387,7 +388,7 @@ export default function delegate(
 					"agents",
 					"<name>",
 					"AGENT.md",
-				)} with frontmatter description, model and thinking, and the prompt as its body`,
+				)} with frontmatter description, model and thinking (optionally auto-exit, exclude-tools, tools, extensions and fallback), and the prompt as its body`,
 			);
 		}
 		const agent = roster.agents.find((candidate) => candidate.name === request.agent);
@@ -447,6 +448,8 @@ export default function delegate(
 			start.model,
 			"--thinking",
 			start.thinking,
+			...start.agent.extensions.flatMap((extension) => ["-e", extension]),
+			...(start.agent.tools.length > 0 ? ["--tools", start.agent.tools.join(",")] : []),
 			...(start.agent.excludeTools.length > 0 ? ["--exclude-tools", start.agent.excludeTools.join(",")] : []),
 			"--append-system-prompt",
 			prompt,
@@ -536,18 +539,27 @@ export default function delegate(
 		}),
 		async execute(
 			_toolCallId: string,
-			params: { agent: string; task: string; model?: string; thinking?: string; label?: string; auto_exit?: boolean },
+			params: {
+				agent: string;
+				task: string;
+				model?: string | null;
+				thinking?: string | null;
+				label?: string | null;
+				auto_exit?: boolean | null;
+			},
 			_signal: unknown,
 			_onUpdate: unknown,
 			ctx: ExtensionContext,
 		) {
 			if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
+			// Some models fill every optional field with null or the string "null"; both mean unset.
+			const given = (value: string | null | undefined) => (value == null || value === "null" ? undefined : value);
 			const start = await validate(
 				{
 					agent: params.agent,
-					model: params.model,
-					thinking: params.thinking,
-					label: params.label,
+					model: given(params.model),
+					thinking: given(params.thinking),
+					label: given(params.label),
 					autoExit: typeof params.auto_exit === "boolean" ? params.auto_exit : undefined,
 					task: params.task ?? "",
 				},