pi-squire 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-21
+
+### Breaking
+
+- Agent definitions now live under `<agent dir>/squire/agents/<name>/AGENT.md`,
+  and only there. The old `<agent dir>/agents/<name>/AGENT.md` location is no
+  longer read, with no fallback or dual discovery, so an agent left there is
+  neither listed nor launched.
+- Pi 1.3.0 or later is now required. The raised floor supports structured
+  per-run system-prompt sections and `before_agent_start` preparation for runs
+  started by an idle custom-message result, so parent guidance and roster
+  metadata are current before each new run.
+
+### Added
+
+- Optional parent delegation guidance: Markdown in
+  `<agent dir>/squire/delegation_prompt.md` is inserted unchanged into the
+  `squire_parent_delegation` system-prompt section before each new run, only
+  while the `delegate` tool is active and not hidden. Missing, empty or deleted
+  files add no guidance; a read failure warns with the path, removes stale
+  guidance for that run, and leaves delegation working. The package ships no
+  default delegation or approval policy.
+- The `delegate` tool description now refreshes from the current roster before
+  each new run, including a run woken by an idle delegate result. A changed
+  agent description, addition or removal shows up in the run being prepared;
+  unchanged metadata is not re-registered.
+
+### Changed
+
+- The `delegate` tool now says to keep working or end the turn rather than poll
+  or send a blocking mail request merely to wait for a result, while a
+  substantive follow-up remains supported.
+
 ## [0.8.1] - 2026-10-20
 
 ### Fixed
@@ -285,7 +318,8 @@ 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.8.1...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/gvanderclay/pi-squire/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/gvanderclay/pi-squire/compare/v0.8.0...v0.8.1
 [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

package/README.md

@@ -10,13 +10,12 @@ answers with one message, which the parent session shows as a result.
 
 You need:
 
-- Pi 0.80.5 or later, on macOS or Linux (not Windows). Pi 1.0.0 is the version
-  pi-squire is tested with. The floor is the first installable release with
-  the `agent_settled` event (added in 0.80.4, which was never published to
-  npm); `--exclude-tools` needs 0.77.0 and `--session-id`
-  0.76.0. The extension uses the `pi.events` bus, `pi.registerCommand` and
-  `pi.registerTool`; Pi supplies the peer dependencies
-  `@earendil-works/pi-coding-agent` and `typebox`.
+- Pi 1.3.0 or later, on macOS or Linux (not Windows). Pi 1.3.0 is the version
+  pi-squire is tested with. It provides the per-run `before_agent_start`
+  preparation for idle custom-message results, the structured system-prompt
+  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.
@@ -45,8 +44,8 @@ The package has no runtime dependencies and no build step.
 
 The package ships no agents, so create one first. `<agent dir>` is Pi's agent
 directory: `~/.pi/agent`, or `PI_CODING_AGENT_DIR` when that is set. Save this
-as `<agent dir>/agents/scout/AGENT.md`, replacing `provider/model-id` with a
-model your Pi can use:
+as `<agent dir>/squire/agents/scout/AGENT.md`, replacing
+`provider/model-id` with a model your Pi can use:
 
 ```markdown
 ---
@@ -60,8 +59,10 @@ You research one question at a time and answer concisely, citing the files
 you read.
 ```
 
-The roster is read at call time, so no reload is needed. Then, from a Pi
-session running in tmux, hand it a task:
+The roster is read at call time, so no reload is needed. Delegation guidance
+for the parent is optional: save Markdown as
+`<agent dir>/squire/delegation_prompt.md`, and it is read before each run.
+Then, from a Pi session running in tmux, hand it a task:
 
 ```text
 /delegate scout --label first Which files define the command-line entry point?
@@ -75,10 +76,11 @@ closes its own window ([auto-exit](#auto-exit)).
 ## How a delegation works
 
 `/delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--auto-exit | --no-auto-exit] <task…>`
-reads the agent from `<agent dir>/agents/<name>/AGENT.md`, writes the task to
-the delegate's inbox through `message:send`, emits `session:launch` so other
-extensions can shape the launch, then opens a detached window running the
-parent's own Pi in the parent's working directory and agent root. The agent's
+reads the agent from `<agent dir>/squire/agents/<name>/AGENT.md`, writes
+the task to the delegate's inbox through `message:send`, emits
+`session:launch` so other extensions can shape the launch, then opens a
+detached window running the parent's own Pi in the parent's working directory
+and agent root. The agent's
 prompt reaches the child as a path to a private file under the system
 temporary folder, not as text on the command line.
 
@@ -112,8 +114,9 @@ temporary folder, not as text on the command line.
 
 ## Agents
 
-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
+The roster is read at call time from
+`<agent dir>/squire/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`, `tools`, `extensions` and `fallback`. The body is the delegate's system prompt,
@@ -173,8 +176,23 @@ add one.
 
 ## Configuration
 
-None beyond the roster. `pi-squire` reads no settings file and no environment
-variable of its own. `PI_DELEGATE_PARENT` and `PI_DELEGATE_AUTO_EXIT` are set
+`<agent dir>/squire/` holds the roster and the optional parent guidance file.
+`delegation_prompt.md` is Markdown, inserted unchanged as the
+`squire_parent_delegation` system-prompt section before each new run, including
+a run started by an idle delegate result. It is not a conversation or user
+message, is not duplicated in the `delegate` tool description or guidelines,
+and is not sent to the child. The guidance is added only while the `delegate`
+tool is active and not hidden; when delegation is inactive or hidden, the
+section is removed and tool selection is left as it was. A missing or whitespace-only
+file adds no section. Editing the file replaces the section at the next run;
+deleting it removes the section. A read failure other than a missing file
+warns with the path, removes stale guidance for that run, and leaves otherwise
+valid delegation working. The package ships no default delegation or approval
+policy.
+
+Refresh happens before a new run, not before every model request in a tool
+loop, and the extension does not watch the filesystem. `pi-squire` reads no
+settings file and no environment 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
@@ -213,13 +231,18 @@ and its excluded tools.
 
 The model picks an agent from these lines without reading files. The
 description also tells the model to turn `auto_exit` off when it means to keep
-talking to the delegate by mail after its result. A tool's description is
-fixed when it is registered, so the description is rebuilt at every session
-start, and a roster change shows up in the next session. Pi cannot list the
-session's tools while extensions load, so the description built then skips the
-`exclude-tools` check, and the one built at session start applies it. The
-roster itself is read at call time, and an unknown agent, model or thinking
-level is refused with close matches and nothing starts.
+talking to the delegate by mail after its result. It says a task must stand
+alone, that results arrive automatically, and that the parent should keep
+working or end its turn rather than poll or send a blocking mail request
+merely to wait; a substantive follow-up remains fine. The description is
+rebuilt at session start and before each new run when the exposed roster
+changes, so an edit, addition or removal shows up in the run being prepared,
+including a run woken by an idle delegate result. Unchanged metadata is not
+re-registered. Pi cannot list the session's tools while extensions load, so
+the description built then skips the `exclude-tools` check, and the one built
+after startup applies it. The roster itself is still read at call time, and an
+unknown agent, model or thinking level is refused with close matches and
+nothing starts.
 
 `delegation_status` reports one state per delegation:
 
@@ -485,7 +508,7 @@ has been sent and just before it opens the delegate's window.
 | --- | --- |
 | `args` | the child `pi`'s complete argument list, launcher first |
 | `env` | the child's environment, as `KEY`/`value` pairs |
-| `agent` | the agent's name, as in `<agent dir>/agents/<name>/AGENT.md`; read it, do not change it |
+| `agent` | the agent's name, as in `<agent dir>/squire/agents/<name>/AGENT.md`; 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
@@ -520,10 +543,6 @@ to the provider.
 Inside a delegate, `pi-squire` also takes over the task: a `request` whose
 `from` is the parent's address. It sets `handled` and sends the task as a user
 prompt labelled `[delegate]`, so the run starts the way a typed prompt does.
-Pi 1.0.0 starts a turn for an injected custom message without preparing the
-system prompt, so a fresh delegate's first request would otherwise carry no
-context files, skills or role paragraph
-([earendil-works/pi#5581](https://github.com/earendil-works/pi/issues/5581)).
 The provider still arms the automatic answer for a request a listener took
 over. Every other message to the delegate is left to the provider. `pi-squire` reads `from` and requires
 it to be the sender's address, which for a delegate is its session id; a reply
@@ -549,6 +568,16 @@ written just before a window closed is never mistaken for no reply. **If
 because a waiting reply cannot be ruled out. The provider's README carries the
 contract.
 
+## Testing limits
+
+The automated tests drive the extension through a fake Pi session. They check
+the registered tool definitions, the structured prompt options a simulated run
+preparation receives, file handling, visibility gating and the existing launch
+and result paths. They do not prove actual Pi event scheduling, final provider
+requests, compaction, cache behavior, or model obedience. The idle-result wake
+is simulated by dispatching the next preparation; the suite does not assert
+that the runtime emits it.
+
 ## Compatibility
 
 While pi-squire is below 1.0, breaking any contract below bumps the minor
@@ -565,7 +594,9 @@ Other extensions may rely on:
 - the `/delegate` syntax and flags;
 - 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`;
+  `<agent dir>/squire/agents/<name>/AGENT.md`;
+- the optional `<agent dir>/squire/delegation_prompt.md` file and the
+  `squire_parent_delegation` system-prompt section;
 - the child environment variables `PI_DELEGATE_PARENT`,
   `PI_DELEGATE_AUTO_EXIT` and `PI_UNATTENDED=1`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.8.1",
+	"version": "0.9.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",
@@ -44,14 +44,14 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-coding-agent": ">=1.3.0",
 		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.14",
-		"@earendil-works/pi-coding-agent": "1.0.0",
-		"@earendil-works/pi-tui": "1.0.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "26.6.3",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2"

package/src/agents.ts

@@ -1,4 +1,4 @@
-// The parent's agent roster: `<agent dir>/agents/<name>/AGENT.md`, read at
+// The parent's agent roster: `<agent dir>/squire/agents/<name>/AGENT.md`, read at
 // 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
@@ -179,14 +179,14 @@ function flag(value: unknown): boolean | undefined | null {
 }
 
 /**
- * Read every agent under `<agentDir>/agents/`, in name order. A directory
+ * Read every agent under `<agentDir>/squire/agents/`, in name order. A directory
  * with no `AGENT.md` is not an agent and is passed over quietly; an
  * `AGENT.md` that cannot be used is warned about and left out. `tools` are
  * the session's tool names, which `exclude-tools` is checked against;
  * undefined skips that check, as before the session's tools are known.
  */
 export function readRoster(agentDir: string, tools?: readonly string[]): Roster {
-	const dir = join(agentDir, "agents");
+	const dir = join(agentDir, "squire", "agents");
 	let names: string[];
 	try {
 		names = readdirSync(dir).sort();

package/src/child.ts

@@ -13,11 +13,11 @@
 // edxeth/pi-subagents' `auto-exit` (README "Child lifecycle", `cf6dbf4`).
 //
 // It also takes over the parent's task request on `message:inbound` and sends
-// it as a user prompt. Pi 1.0.0 starts a custom-message turn without preparing
-// the system prompt, so a fresh delegate's first request would carry no
-// AGENTS.md, skills or role addendum (earendil-works/pi#5581). The provider
-// still arms the automatic answer for a request a listener took over.
-// ponytail: drop the takeover once #5581 lands and the minimum Pi has it.
+// it as a user prompt, so the task starts through the same path as a typed
+// prompt, labelled `[delegate]`. Pi 1.2.0 already prepares the system prompt
+// for custom-message runs (earendil-works/pi#5581); this takeover remains the
+// package's pinned startup delivery path. The provider still arms the
+// automatic answer for a request a listener took over.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { activeMark, classify, type Response, recordLimit } from "./limits.ts";

package/src/index.ts

@@ -3,7 +3,7 @@
 //
 // `/delegate <agent> [--model <provider/id>] [--thinking <level>]
 // [--label <name>] [--auto-exit | --no-auto-exit] <task…>`
-// reads the agent from `<agent dir>/agents/<name>/AGENT.md`, writes the task
+// reads the agent from `<agent dir>/squire/agents/<name>/AGENT.md`, writes the task
 // to the delegate's inbox through `message:send`, emits `session:launch` so
 // listeners can add arguments and environment, then opens a window in the
 // parent's working directory running the parent's own Pi. The window and the
@@ -34,7 +34,7 @@
 // The `session:launch` contract this package provides, and the `message:*`
 // hooks it consumes, live in this package's README.
 import { randomUUID } from "node:crypto";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 
@@ -54,6 +54,10 @@ import { createTmuxClient, type TmuxClient } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
 
+/** The optional parent guidance file under `<agent dir>/squire/`. */
+const PARENT_PROMPT = "delegation_prompt.md";
+/** The parent system-prompt section this extension owns. */
+const PARENT_SECTION = "squire_parent_delegation";
 /** The hook a provider of `message:*` answers with the written request. */
 const SEND = "message:send";
 /** The hook emitted just before a delegate's window opens. */
@@ -325,13 +329,33 @@ function thinkingProblem(value: string): string | undefined {
 	}`;
 }
 
+/** Read `<agent dir>/squire/delegation_prompt.md`; missing or whitespace-only means no guidance. */
+function readParentPrompt(): { text?: string; error?: string } {
+	const path = join(getAgentDir(), "squire", PARENT_PROMPT);
+	try {
+		const text = readFileSync(path, "utf8");
+		return text.trim() === "" ? {} : { text };
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return {};
+		return {
+			error: `could not read ${path}: ${(err as Error).message}; parent delegation guidance is off for this run`,
+		};
+	}
+}
+
+/** Whether this run exposes `delegate` after tool selection and hidden declarations. */
+function delegateVisible(options: { selectedTools: string[]; hiddenTools: string[] }): boolean {
+	return options.selectedTools.includes("delegate") && !options.hiddenTools.includes("delegate");
+}
+
 /** 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. 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.";
+		"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. Do not poll delegation_status or send a blocking mail request merely to wait for the result; send a substantive follow-up only when you have something to add or ask. 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(),
+			"squire",
 			"agents",
 			"<name>",
 			"AGENT.md",
@@ -411,6 +435,7 @@ export default function delegate(
 			throw new Error(
 				`no agents are defined; add ${join(
 					getAgentDir(),
+					"squire",
 					"agents",
 					"<name>",
 					"AGENT.md",
@@ -541,11 +566,13 @@ export default function delegate(
 		}
 	}
 
-	/** The tool's description is fixed at registration, so it is rebuilt at every session start. */
-	const delegateTool = () => ({
+	/** The roster description last registered, so unchanged metadata is not registered again. */
+	let registeredDescription: string | undefined;
+
+	const delegateTool = (description: string) => ({
 		name: "delegate",
 		label: "Delegate",
-		description: toolDescription(currentRoster().agents),
+		description,
 		parameters: Type.Object({
 			agent: Type.String({ description: "Roster agent name to run." }),
 			task: Type.String({
@@ -619,11 +646,32 @@ export default function delegate(
 		},
 	});
 
+	const registerDelegate = (description: string): void => {
+		pi.registerTool(delegateTool(description) as never);
+		registeredDescription = description;
+	};
+
 	pi.on("session_start", (_event, ctx) => {
 		registry = ctx.modelRegistry;
 		tracking.restore(ctx);
-		// The roster is read at call time; the description can only be fixed here.
-		pi.registerTool(delegateTool() as never);
+		// The roster is read at call time; the description is rebuilt here and before each run.
+		registerDelegate(toolDescription(currentRoster().agents));
+	});
+
+	// One roster/prompt snapshot prepares this run: refresh the description only when
+	// it changed, and replace only this extension's prompt section from the same snapshot.
+	pi.on("before_agent_start", (event, ctx) => {
+		const description = toolDescription(currentRoster().agents);
+		const prompt = readParentPrompt();
+		const visible = delegateVisible(event.systemPromptOptions);
+		// Report a read failure even when guidance cannot be used, so it does not go unseen.
+		if (prompt.error !== undefined) ctx.ui.notify(`delegate: ${prompt.error}`, "warning");
+		if (visible && description !== registeredDescription) registerDelegate(description);
+		if (!visible || prompt.error !== undefined || prompt.text === undefined) {
+			delete event.systemPromptOptions.sections[PARENT_SECTION];
+			return;
+		}
+		event.systemPromptOptions.sections[PARENT_SECTION] = prompt.text;
 	});
 
 	pi.on("session_shutdown", () => {
@@ -680,6 +728,6 @@ export default function delegate(
 		},
 	});
 
-	pi.registerTool(delegateTool() as never);
+	registerDelegate(toolDescription(currentRoster().agents));
 	tracking.registerTools();
 }