pi-squire 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this package are recorded here, in the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. The package
+follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-02
+
+The first public release. Before this repository the package lived in its
+author's dotfiles; the changes below are against that copy.
+
+### Added
+
+- Published to npm as `pi-squire`.
+- MIT license and package metadata, including `engines` (Node 22.19 or later).
+- CI on Node 22.19 and 24: lint, typecheck, tests, and a check of the
+  published file list.
+
+### Fixed
+
+- The published file list includes `child.ts`, which `index.ts` imports.
+
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/gvanderclay/pi-squire/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gage Vander Clay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# pi-squire
+
+Hands a task to a delegate Pi session in a background tmux window, through the
+`/delegate` command and the `delegate` tool.
+
+`/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 window
+and the child's Pi session share one name: `<agent>-<label>`, or
+`<agent>-<first 8 characters of the id>` without a label. A label is at most
+32 letters, digits, `_` or `-`, starting with a letter or digit; `-` rather
+than `:` joins it, since tmux reads `:` in a target as session and window.
+Labels need not be unique: the delegation id stays the handle for
+`delegation_status`, `delegation_close` and mail. The delegate id is fresh, so a
+delegate never reopens a live session, and it is also the delegate's mailbox
+address: the task waits in its inbox and is delivered at session start, with
+no handshake.
+
+Starting a delegation adds nothing to the parent's context — the model sees
+neither the command nor the task. The model can also start one itself with the
+`delegate` tool, which starts the delegation at once without opening a
+dialog, so several calls in one message each start their own;
+`delegation_status` and `delegation_close` let it check on a delegation
+and end one. When the delegate settles, its answer is taken over on
+`message:inbound` and shown to the parent as one result message that quotes
+the task. By default the delegate then closes its own window
+([auto-exit](#auto-exit)); with auto-exit off the window stays open so you can
+read it or keep working in it. Delegations are recorded in the parent session
+without the task text.
+
+Inside a delegate (`PI_DELEGATE_PARENT` set) the extension registers only
+auto-exit's side, the `/auto-exit` command and its handlers, so a delegate
+cannot start delegates of its own. Without a UI the command
+and the `delegate` tool still work; it needs tmux and a provider of `message:*`, and refuses with a
+message when either is missing.
+
+## Install
+
+Install the package from npm:
+
+```bash
+pi install npm:pi-squire
+```
+
+To follow the latest commit instead, install it from GitHub:
+
+```bash
+pi install git:github.com/gvanderclay/pi-squire
+```
+
+The package has no runtime dependencies and no build step. The `pi` manifest loads only
+`./index.ts`, and the tests under `test/` are neither loaded by Pi nor included
+in the npm tarball.
+Run them with `pnpm install && pnpm test`.
+
+## Requirements
+
+- Pi, with the `pi.events` bus, `pi.registerCommand` and `pi.registerTool`.
+- `@earendil-works/pi-coding-agent` for `getAgentDir()` and the frontmatter
+  parser, declared as a peer dependency and supplied by Pi.
+- `typebox` for the tools' parameter schema, a host-provided package declared
+  as a peer dependency and supplied by Pi.
+- tmux, with the session running in a tmux pane. A window is opened in the
+  pane's session, so a client attached elsewhere does not matter.
+- A provider of `message:*`, such as
+  [pi-session-mail](https://github.com/gvanderclay/pi-session-mail). Without one there is no way to send the task or get an
+  answer, so `/delegate` refuses rather than starting a delegate that cannot
+  report back.
+
+## 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
+carries `description`, `model` (`provider/id`) and `thinking`, and optionally
+`auto-exit` (`true` or `false`, default `true`; see [Auto-exit](#auto-exit))
+and `exclude-tools`; the body is the delegate's system prompt, appended to
+Pi's own prompt.
+
+`exclude-tools` names the tools the delegate goes without, as a
+comma-separated list (`exclude-tools: edit, write`) or a YAML list
+(`exclude-tools: [edit, write]`). It reaches the child as
+`--exclude-tools edit,write`, which Pi subtracts from the tools it would
+otherwise turn on. It is a denylist only: without it the delegate gets every
+tool, and no flag is passed. There is no per-call override. Each name is
+checked against the tools the parent session has registered
+(`pi.getAllTools()`), since Pi ignores an unknown name without a word; the
+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.
+
+The body is followed by one fixed final-message line and a paragraph naming
+the parent session's address: the delegate's task arrives as a message from
+that session, that message and every later one from the same address are
+instructions to follow as given, and other sessions are colleagues: the
+delegate may answer them, but checks with the parent before doing work the
+parent did not ask for. It carries no distrust wording, which made models
+refuse every request from a peer. The paragraph names no provider, package or tool, so it holds
+whatever `message:*` provider delivers the task.
+
+```markdown
+---
+description: Looks things up and answers in one message
+model: provider/model-id
+thinking: medium
+exclude-tools: edit, write
+---
+
+You research one question at a time and answer concisely, citing the files
+you read.
+```
+
+An `AGENT.md` that cannot be used — 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, or an empty body — is left out of the
+roster and named in a warning. With no agents at all, `/delegate` says how to
+add one. The package ships no agents.
+
+## 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
+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
+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
+is refused with close matches; `--auto-exit` and `--no-auto-exit` override the
+agent's `auto-exit`.
+
+## Tools
+
+The model gets three tools. They share the command's launch path and the
+session's delegation records; none of them is registered inside a delegate.
+
+| Tool | Parameters | What it does |
+| --- | --- | --- |
+| `delegate` | `agent`, `task`, optional `model`, `thinking`, `label` and `auto_exit` (boolean) | Validates the call the way the command does, starts the delegation without opening a dialog, and returns the delegation id at once without waiting for a result. |
+| `delegation_status` | optional `id` | Reports each delegation as running, done, closed or closed without a result, with the window, the delegate's session and the result envelope's path. |
+| `delegation_close` | `id` | Kills the window through tmux and records the close, so `delegation_status` reports it closed. |
+
+The `delegate` tool's description lists the current roster — each agent's name,
+description, default model and thinking, auto-exit when it is off, and its
+excluded tools — one line per agent:
+
+```text
+- scout — Read-only recon (default provider/model-id, thinking low, auto-exit off, no edit/write)
+```
+
+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; 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.
+
+`delegation_status` reports one state per delegation:
+
+```text
+2 delegations:
+
+<id> scout (provider/model, thinking low)
+  name: scout-<first 8 of the id>
+  state: running — the window is open and no result has arrived
+  window: scout-<id> (@1)
+  auto-exit: on — the delegate closes its window after a normal completion unless the user took over there
+  session: <the delegate's session file, or its id when there is none yet>
+
+<id> researcher (provider/other, thinking high)
+  name: researcher-<first 8 of the id>
+  state: done — result status: done
+  window: researcher-<id> (@2)
+  auto-exit: off — the window stays open after the result
+  session: <session file>
+  envelope: <the reply's path in the parent's cur/>
+```
+
+- **Name** is the delegate's Pi session name, its agent and the first 8
+  characters of its delegation id; the window keeps the full id.
+- **Running** means the window is open and no result has arrived. An open
+  window is connection, not task state: the delegate may still be working, or
+  waiting for the user, and only a result means done.
+- **Done** comes from the recorded result, and shows the envelope's status
+  (`done`, `failed` or `stopped`).
+- A delegate that closed itself by auto-exit reads **done**: its result
+  arrived before its window went. For a moment before the result is claimed
+  it can read closed, since the window is already gone.
+- **Auto-exit** reads off for delegations recorded before auto-exit existed.
+- **Closed** covers a close `delegation_close` recorded and a window that is no
+  longer there. A recorded close wins over a result, and a result wins over a
+  window that is gone.
+- **Closed without a result** is what the poll records when a window is gone
+  and no reply arrived (see Results). A result outranks it, so a late reply
+  turns it into **done**; a close from `delegation_close` outranks both.
+- When tmux cannot be asked about a window, the state is `unknown`, never
+  `closed`, because a failed check is not evidence the window is gone.
+
+`delegation_close` kills the window and records the close even when the
+result has already arrived; when the window is already gone it only records
+the close. An unknown or already closed id returns a message and kills
+nothing. The delegate's session file and result envelope stay on disk.
+
+## Auto-exit
+
+The parent resolves each delegation's auto-exit from the call
+(`auto_exit`, or `--auto-exit` / `--no-auto-exit`), then the agent's
+`auto-exit`, then on, and passes it to the child as `PI_DELEGATE_AUTO_EXIT`
+(`1` or `0`). Inside the delegate:
+
+- While it is on, a run that settles as a normal completion shuts the delegate
+  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.
+- 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
+  completion, whatever the launch said.
+
+The name and the take-over rule follow edxeth/pi-subagents' `auto-exit`
+(README "Child lifecycle"); unlike it, the default is on, and there is no
+`subagent_done` tool: auto-exit off only means the window stays.
+
+## Results
+
+A delegate answers its task with one reply through the `message:*` provider. `pi-squire` takes that
+reply over before the provider can inject it, and sends the parent one
+message labelled delegate output:
+
+```
+[delegate] Result from scout (provider/model), delegation <id>, request <request id>.
+Status: done
+Task, quoted from <sent/ copy>:
+> the task
+Envelope: <cur/ path>
+Delegate session: <session file or id>
+
+<the result>
+```
+
+- The header carries the agent, the model, the delegation id and the request
+  id; the status is the envelope's (`done`, `failed` or
+  `stopped`).
+- Stopping a delegate's run (Esc) sends no result: the provider holds the
+  task, so the delegation stays running while the user steers it. The next
+  run that completes sends the result, `done`, and its body opens with a note
+  that the user took over partway.
+- The task is quoted from the request copy the provider puts on the payload,
+  capped at 2 KiB with the copy's `sent/` path. A request with no copy is
+  named by id alone.
+- The envelope path is the claimed reply in the parent's `cur/`; the
+  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 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
+  records are rebuilt synchronously at session start; a resume still
+  recognises replies — including one that arrived while the parent was
+  closed — and still reports a recorded close as closed. A result is shown
+  once and never again.
+- Plain replies, and every request, are left to the provider.
+
+While any delegation is running (no result, no close), the parent polls every
+5 seconds; the timer does not keep the process alive and stops when nothing is
+running and on `session_shutdown`. Each tick first emits `message:scan`, so the
+provider claims waiting replies, and then asks tmux about each still-running
+window. A delegation whose window is gone and still has no result after that
+scan is recorded as closed without a result, a record separate from
+`delegation_close`'s, and the parent gets one `[delegate]` message naming the
+delegation, with the delegate session path when one is found, sent as a
+`followUp` with `triggerTurn`. A tick declares nothing when nobody answers
+`message:scan` or when tmux reports an error. A reply that arrives later is
+still delivered and makes the delegation done. A resumed session polls again
+for every delegation it restores as running.
+
+## Hooks
+
+The `js` block below is the contract's worked example, and
+`test/hooks.test.ts` extracts and runs it verbatim on a real `createEventBus`.
+Its scope is the test harness's: `pi` is the extension API. Write it as plain
+JavaScript so it stays runnable; the name after `js` is the test that runs
+that block.
+
+### `session:launch`
+
+`pi-squire` provides this hook. It emits `{ args, env }` after the task has been
+sent and just before it opens the delegate's window.
+
+| Field | Meaning |
+| --- | --- |
+| `args` | the child `pi`'s complete argument list, launcher first |
+| `env` | the child's environment, as `KEY`/`value` pairs |
+
+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
+emitter reads the payload the moment `emit` returns.
+
+```js session:launch
+// Any extension can shape a launch: append a flag and add an environment key.
+pi.events.on("session:launch", (payload) => {
+  payload.args.push("--auto");
+  payload.env.GATE_MODE = "auto";
+});
+```
+
+### `message:send`
+
+`pi-squire` consumes this hook to write the task; the provider writes the
+envelope from its own session's address and sets `envelope` (or `error`) on the
+payload before `emit` returns. **If neither is set, no provider is installed**
+and `pi-squire` refuses with a message naming `message:*`. The envelope's `id`
+is kept in the delegation's record, so an answer can be matched to it. The
+provider's own README carries the contract.
+
+### `message:inbound`
+
+`pi-squire` consumes this hook for answers: a reply whose `in_reply_to` names a
+recorded delegation's request is taken over — `pi-squire` sets `handled`, so
+the provider injects nothing, and shows the parent the result message above.
+The reply's request copies fill the quoted task and its `cur/` path is the
+envelope it names. A reply to a request this session did not delegate, and
+every request, is left to the provider. The provider's README carries the
+contract.
+
+`pi-squire` rebuilds its records synchronously in its own `session_start`, so it
+relies on the provider not emitting `message:inbound` from inside a
+`session_start` handler: mail waiting at session start must be claimed on a
+later event-loop turn, as pi-session-mail's `message:inbound` contract guarantees.
+That is what makes a result that arrived while the parent was closed reach the
+rebuilt records. Keep extensions whose `session_start` waits on I/O from
+loading between the provider and `pi-squire`.
+
+### `message:scan`
+
+`pi-squire` consumes this hook on every poll tick (see Results): it emits `{}`,
+and the provider claims the mail waiting in its inbox, emitting each reply as
+`message:inbound`, before setting `scanned` to `true` on the payload and
+returning from `emit`. Only then does `pi-squire` check windows, so a reply
+written just before a window closed is never mistaken for no reply. **If
+`scanned` is not set, nobody answered**, and the tick declares nothing closed,
+because a waiting reply cannot be ruled out. The provider's README carries the
+contract.

package/agents.ts

@@ -0,0 +1,161 @@
+// The parent's agent roster: `<agent dir>/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
+// as `--exclude-tools`; each must be a tool the parent session has); 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 { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+/** The levels `pi --thinking` accepts. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export type Thinking = (typeof THINKING_LEVELS)[number];
+
+export function isThinking(value: string): value is Thinking {
+	return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+/** An agent name is one safe path segment and one safe tmux window name. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/** `provider/id`; the id may itself contain slashes. */
+const MODEL = /^[^\s/]+\/\S+$/;
+
+export type Agent = {
+	name: string;
+	description: string;
+	model: string;
+	thinking: Thinking;
+	/** Whether the delegate closes itself after a normal completion; `auto-exit`, default true. */
+	autoExit: boolean;
+	/** Tools the delegate goes without, from `exclude-tools`; empty means all of them. */
+	excludeTools: string[];
+	/** The body of `AGENT.md`: the delegate's system prompt. */
+	prompt: string;
+};
+
+export type Roster = {
+	agents: Agent[];
+	/** One line per `AGENT.md` left out, naming its path and the reason. */
+	warnings: string[];
+};
+
+const field = (frontmatter: Record<string, unknown>, key: string): string | undefined => {
+	const value = frontmatter[key];
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+};
+
+/** Parse one `AGENT.md`; undefined with a reason when it cannot be an agent. */
+function parseAgent(
+	name: string,
+	path: string,
+	text: string,
+	tools: readonly string[] | undefined,
+): { agent?: Agent; warning?: string } {
+	let frontmatter: Record<string, unknown>;
+	let body: string;
+	try {
+		({ frontmatter, body } = parseFrontmatter(text) as { frontmatter: Record<string, unknown>; body: string });
+	} catch (err) {
+		return { warning: `${path} is not readable frontmatter (${(err as Error).message}); skipped` };
+	}
+	if (frontmatter === null || typeof frontmatter !== "object")
+		return { warning: `${path} has no frontmatter fields; skipped` };
+	const description = field(frontmatter, "description");
+	const model = field(frontmatter, "model");
+	const thinking = field(frontmatter, "thinking");
+	const missing = [
+		description === undefined ? "description" : undefined,
+		model === undefined ? "model" : undefined,
+		thinking === undefined ? "thinking" : undefined,
+	].filter((key): key is string => key !== undefined);
+	if (missing.length > 0) return { warning: `${path} has no ${missing.join(", ")}; skipped` };
+	if (!MODEL.test(model as string))
+		return { warning: `${path} has model ${JSON.stringify(model)}, not provider/id; skipped` };
+	if (!isThinking(thinking as string))
+		return {
+			warning: `${path} has thinking ${JSON.stringify(thinking)}, not one of ${THINKING_LEVELS.join(", ")}; skipped`,
+		};
+	if (body === "") return { warning: `${path} has no prompt body; skipped` };
+	const autoExit = flag(frontmatter["auto-exit"]);
+	if (autoExit === null)
+		return { warning: `${path} has auto-exit ${JSON.stringify(frontmatter["auto-exit"])}, not true or false; skipped` };
+	const listed = toolList(frontmatter["exclude-tools"]);
+	if (listed === null)
+		return {
+			warning: `${path} has exclude-tools ${JSON.stringify(frontmatter["exclude-tools"])}, not a comma-separated list of tool names; skipped`,
+		};
+	const excludeTools = listed ?? [];
+	const unknownTool = tools === undefined ? undefined : excludeTools.find((tool) => !tools.includes(tool));
+	if (unknownTool !== undefined)
+		return {
+			warning: `${path} has exclude-tools ${JSON.stringify(unknownTool)}, not a tool this session has; skipped`,
+		};
+	return {
+		agent: {
+			name,
+			description: description as string,
+			model: model as string,
+			thinking: thinking as Thinking,
+			autoExit: autoExit ?? true,
+			excludeTools,
+			prompt: body,
+		},
+	};
+}
+
+/** A tool list, 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;
+	const names = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : null;
+	if (names === null || !names.every((name) => typeof name === "string")) return null;
+	return names.map((name) => name.trim()).filter((name) => name !== "");
+}
+
+/** A true/false frontmatter value; undefined when absent, null when it is neither. */
+function flag(value: unknown): boolean | undefined | null {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value === "boolean") return value;
+	if (value === "true") return true;
+	if (value === "false") return false;
+	return null;
+}
+
+/**
+ * Read every agent under `<agentDir>/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");
+	let names: string[];
+	try {
+		names = readdirSync(dir).sort();
+	} catch {
+		return { agents: [], warnings: [] }; // no agents directory yet
+	}
+	const agents: Agent[] = [];
+	const warnings: string[] = [];
+	for (const name of names) {
+		const path = join(dir, name, "AGENT.md");
+		let text: string;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			continue;
+		}
+		if (!NAME.test(name)) {
+			warnings.push(`${path} is not under a usable agent name; skipped`);
+			continue;
+		}
+		const { agent, warning } = parseAgent(name, path, text, tools);
+		if (agent !== undefined) agents.push(agent);
+		else if (warning !== undefined) warnings.push(warning);
+	}
+	return { agents, warnings };
+}

package/child.ts

@@ -0,0 +1,67 @@
+// The delegate's side of `auto-exit`, registered only inside a delegate.
+//
+// The parent resolves the setting and passes it as `PI_DELEGATE_AUTO_EXIT`
+// (`1` on, `0` off). While it is on, the delegate shuts Pi down once a run
+// settles as a normal completion, so its tmux window closes; the settle
+// reply has been sent by then, since the shutdown waits for the next
+// event-loop turn. A run that ended stopped or failed never exits. The user
+// taking over — typing here, or stopping a run — turns it off for the rest of
+// the session, with a notice; `/auto-exit` turns it back on. Modelled on
+// edxeth/pi-subagents' `auto-exit` (README "Child lifecycle", `cf6dbf4`).
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** The launch variable that carries the parent's resolved setting. */
+export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
+
+const OFF_NOTICE =
+	"delegate: auto-exit is off for this session because you took over here; the window stays open. /auto-exit turns it back on.";
+const ON_NOTICE = "delegate: auto-exit is on; this delegate closes after its next normal completion.";
+
+type Message = { role?: string; stopReason?: unknown };
+
+export function registerChild(pi: ExtensionAPI): void {
+	let armed = process.env[AUTO_EXIT_ENV] === "1";
+	/** Whether the run that just ended finished normally: not stopped, not failed. */
+	let completed = false;
+
+	function disarm(ctx: ExtensionContext): void {
+		if (!armed) return;
+		armed = false;
+		ctx.ui.notify(OFF_NOTICE, "info");
+	}
+
+	// Typed text and RPC input are the user's; a prompt an extension sends is not.
+	pi.on("input", async (event, ctx) => {
+		if (event.source !== "extension") disarm(ctx);
+	});
+
+	// Stopped mid-text the last message says `aborted`; stopped during a tool
+	// call Pi 0.99.1 ends with an `error` message, and only the signal tells a
+	// stop from a real error. Either way it is the user taking over.
+	pi.on("agent_end", async (event, ctx) => {
+		let last: Message | undefined;
+		for (let i = event.messages.length - 1; i >= 0 && last === undefined; i--) {
+			const message = event.messages[i] as Message;
+			if (message?.role === "assistant") last = message;
+		}
+		const stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
+		if (stopped) disarm(ctx);
+		completed = !stopped && last?.stopReason !== "error";
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		const exit = armed && completed;
+		completed = false;
+		if (!exit) return;
+		// Later settle handlers (the `message:*` provider's reply among them) run first.
+		setImmediate(() => ctx.shutdown());
+	});
+
+	pi.registerCommand("auto-exit", {
+		description: "Close this delegate after its next normal completion",
+		handler: async (_args, ctx) => {
+			armed = true;
+			ctx.ui.notify(ON_NOTICE, "info");
+		},
+	});
+}