pi-squire 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,63 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-02
+
+### Fixed
+
+- A delegate's task now arrives as a user prompt labelled `[delegate]` instead
+  of a `[mailbox]` message. Pi 1.0.0 started the injected message's turn
+  without the system prompt, so a fresh delegate saw no context files, skills
+  or role paragraph until after its first tool call, and could reject them as
+  an injection (earendil-works/pi#5581).
+
+## [0.2.0] - 2026-10-02
+
+### Breaking
+
+- A model without configured credentials is refused, by `/delegate` and the
+  `delegate` tool alike, instead of failing in the delegate's window.
+- A reply counts as a delegation's result only when it comes from the delegate
+  (`envelope.from` equals the delegation's id); a reply to its request from any
+  other sender is left to the provider as ordinary mail.
+- Providers must set `envelope.from` to the sender's address.
+- The `reply()` fixture in `test/poll.test.ts` now sends the delegation id as
+  `from` instead of `"d"`, to match.
+
+### Changed
+
+- The sources moved to `src/`, so load the package directory (`pi -e .`), not
+  `index.ts`. Installs through npm or git are unaffected.
+- Each check (a poll tick, a `delegation_status` call, a `delegation_close`
+  call) asks tmux once, however many delegations run, instead of once per
+  delegation.
+- The appended system prompt reaches the delegate as a path to a private file
+  under the system temporary folder, so its text stays off the command line
+  and out of `ps`. A `session:launch` listener now sees that path where the
+  prompt text was. The argv tests in `test/delegate.test.ts` read the prompt
+  from the file instead of from argv, a deliberate behaviour change.
+
+### Fixed
+
+- `delegation_status` details name a labelled delegation's session
+  (`scout-roster`), as its text does, instead of `<agent>-<first 8 of the id>`.
+- A recycled tmux window id is no longer mistaken for a delegate's window, nor
+  killed: a window counts as the delegate's only when its id and its name both
+  match.
+- A delegate whose program exited in a window kept open (`remain-on-exit`)
+  reads as gone instead of running.
+
+### Added
+
+- `session:launch` payloads carry the agent's name as `agent`.
+- The README's Install section names its requirements: tmux 3.0 or later, Pi
+  0.80.5 or later, the first installable release with `agent_settled` (tested
+  with Pi 1.0.0), macOS and Linux, and
+  `pi install npm:pi-session-mail` as an example `message:*` provider.
+- A README "Compatibility" section names the contracts other extensions rely
+  on, the below-1.0 rule that breaking one bumps the minor version, and what a
+  `message:*` provider must do.
+
 ## [0.1.0] - 2026-10-02
 
 The first public release. Before this repository the package lived in its
@@ -22,5 +79,7 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-squire/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/gvanderclay/pi-squire/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/gvanderclay/pi-squire/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/gvanderclay/pi-squire/releases/tag/v0.1.0

package/README.md

@@ -1,73 +1,114 @@
 # pi-squire
 
-Hands a task to a delegate Pi session in a background tmux window, through the
-`/delegate` command and the `delegate` tool.
+Starts a delegate Pi session in a background tmux window and shows you its result.
 
-`/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.
+You give a task to a named agent with the `/delegate` command, or the model does
+it with the `delegate` tool. The delegate works in its own tmux window and
+answers with one message, which the parent session shows as a result.
 
 ## Install
 
-Install the package from npm:
+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`.
+- 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.
+- A provider of `message:*`;
+  [pi-session-mail](https://github.com/gvanderclay/pi-session-mail) is one
+  example. Without a provider there is no way to send the task or get an
+  answer, so `/delegate` refuses rather than start a delegate that cannot
+  report back.
+
+With pi-session-mail as the provider, for example, install both from npm:
 
 ```bash
+pi install npm:pi-session-mail
 pi install npm:pi-squire
 ```
 
-To follow the latest commit instead, install it from GitHub:
+To follow the latest commit of pi-squire 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.
+The package has no runtime dependencies and no build step.
+
+## First use
+
+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:
+
+```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.
+```
+
+The roster is read at call time, so no reload is needed. 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?
+```
+
+A detached tmux window named `scout-first` opens in your working directory.
+When the delegate finishes, its answer reaches the parent as one `[delegate]`
+message that quotes the task (see [Results](#results)), and the delegate then
+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
+prompt reaches the child as a path to a private file under the system
+temporary folder, not as text on the command line.
+
+- 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. A `-` joins
+  it rather than `:`, 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. 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 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. They need tmux
+  and a provider of `message:*`, and refuse with a message when either is
+  missing. In print mode (`pi -p`) Pi does not show the refusal notices, so
+  the refusal is silent there.
 
 ## Agents
 
@@ -75,8 +116,10 @@ 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.
+and `exclude-tools`. 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`.
 
 `exclude-tools` names the tools the delegate goes without, as a
 comma-separated list (`exclude-tools: edit, write`) or a YAML list
@@ -85,42 +128,30 @@ comma-separated list (`exclude-tools: edit, write`) or a YAML list
 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
+(`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, and that message and every later one from the same address are
+instructions to follow as given. Other sessions are colleagues: the delegate
+may answer them, but checks with the parent before doing work the parent did
+not ask for. 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.
+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
+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
+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
@@ -128,13 +159,16 @@ 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
+is refused with close matches, and so is a model with no configured
+credentials. An API key that exists only as an environment variable in the
+parent's shell does not reach the delegate, so log in through Pi or make the
+variable part of the tmux server's environment. `--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.
+session's delegation records. None of them is registered inside a delegate.
 
 | Tool | Parameters | What it does |
 | --- | --- | --- |
@@ -142,9 +176,9 @@ session's delegation records; none of them is registered inside a delegate.
 | `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:
+The `delegate` tool's description lists the current roster, one line per agent:
+its name, description, default model and thinking, auto-exit when it is off,
+and its excluded tools.
 
 ```text
 - scout — Read-only recon (default provider/model-id, thinking low, auto-exit off, no edit/write)
@@ -154,10 +188,11 @@ 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.
+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.
 
 `delegation_status` reports one state per delegation:
 
@@ -167,21 +202,21 @@ model or thinking level is refused with close matches and nothing starts.
 <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)
+  window: scout-<first 8 of the 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)
+  window: researcher-<first 8 of the 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.
+  characters of its delegation 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.
@@ -195,13 +230,14 @@ model or thinking level is refused with close matches and nothing starts.
   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.
+  and no reply arrived (see [Results](#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
+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.
 
@@ -222,15 +258,13 @@ The parent resolves each delegation's auto-exit from the call
 - `/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.
+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:
+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>.
@@ -263,17 +297,19 @@ Delegate session: <session file or id>
 - 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
+  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
+provider claims waiting replies, and then lists the tmux windows once and
+matches each still-running delegation to a window by id and name (window ids
+restart with every tmux server). A window whose program has exited counts as
+gone. 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
@@ -292,13 +328,14 @@ 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.
+`pi-squire` provides this hook. It emits `{ args, env, agent }` 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 |
+| `agent` | the agent's name, as in `<agent dir>/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
@@ -324,12 +361,24 @@ 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
+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.
+envelope it names. A reply to a request this session did not delegate is left
+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
+from any other sender is left to the provider, even when it answers a recorded
+request. 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
@@ -349,3 +398,41 @@ 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.
+
+## Compatibility
+
+While pi-squire is below 1.0, breaking any contract below bumps the minor
+version and is listed under "Breaking" in [CHANGELOG.md](CHANGELOG.md).
+
+Other extensions may rely on:
+
+- the `session:launch` payload `{ args, env, agent }`, emitted synchronously
+  after the task is sent and before the window opens (see [Hooks](#hooks));
+- the `message:send`, `message:inbound` and `message:scan` hooks, consumed as
+  their sections document;
+- the `delegate`, `delegation_status` and `delegation_close` tool names and
+  parameters;
+- 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`;
+- the child environment variables `PI_DELEGATE_PARENT` and
+  `PI_DELEGATE_AUTO_EXIT`.
+
+A `message:*` provider must:
+
+- implement `message:send`, `message:inbound` and `message:scan` as documented
+  under [Hooks](#hooks);
+- set a reply's `from` to the sender's address, so the delegate's reply can be
+  matched to its task;
+- reply on its own when the delegate's run settles, since that reply is what
+  becomes the result.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to set up, run the tests and open a pull
+request. Changes by release are in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT, as stated in [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"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",
@@ -24,15 +24,11 @@
 	"packageManager": "pnpm@10.33.0",
 	"pi": {
 		"extensions": [
-			"./index.ts"
+			"./src/index.ts"
 		]
 	},
 	"files": [
-		"index.ts",
-		"child.ts",
-		"agents.ts",
-		"tmux.ts",
-		"results.ts",
+		"src",
 		"README.md",
 		"LICENSE",
 		"CHANGELOG.md"

package/{child.ts → src/child.ts}

@@ -8,6 +8,13 @@
 // 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`).
+//
+// 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.
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 /** The launch variable that carries the parent's resolved setting. */
@@ -19,7 +26,24 @@ const ON_NOTICE = "delegate: auto-exit is on; this delegate closes after its nex
 
 type Message = { role?: string; stopReason?: unknown };
 
-export function registerChild(pi: ExtensionAPI): void {
+type Inbound = { envelope?: { from?: unknown; kind?: unknown; body?: unknown }; handled?: boolean };
+
+export function registerChild(pi: ExtensionAPI, parent: string): void {
+	let current: ExtensionContext | undefined;
+	pi.on("session_start", async (_event, ctx) => {
+		current = ctx;
+	});
+	pi.events.on("message:inbound", (data) => {
+		const payload = data as Inbound;
+		const envelope = payload?.envelope;
+		if (payload.handled === true || envelope?.kind !== "request" || envelope.from !== parent) return;
+		payload.handled = true;
+		const text = `[delegate] Your task, from the session that started you (${parent}). Your final message this turn goes back to it automatically.\n\n${String(envelope.body ?? "")}`;
+		Promise.resolve(pi.sendUserMessage(text, { deliverAs: "steer" })).catch((err) =>
+			current?.ui.notify(`delegate: could not start the task: ${(err as Error).message}`, "error"),
+		);
+	});
+
 	let armed = process.env[AUTO_EXIT_ENV] === "1";
 	/** Whether the run that just ended finished normally: not stopped, not failed. */
 	let completed = false;