pi-squire 0.14.0 → 0.16.0

package/README.md

@@ -21,13 +21,15 @@ You need:
   relative to the pane's session (see [Where delegate windows
   open](#where-delegate-windows-open)), 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
+- A provider of the four `message:*` hooks, including `message:reply`;
+  [pi-session-mail](https://github.com/gvanderclay/pi-session-mail) **0.6.0 or
+  later** supplies them. 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:
+Upgrade pi-session-mail and pi-squire together, then restart or reload both
+parent and delegate sessions. Older mail providers are unsupported; there is
+no version negotiation or legacy automatic-answer path. Install both from npm:
 
 ```bash
 pi install npm:pi-session-mail
@@ -46,22 +48,24 @@ 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>/squire/agents/scout/AGENT.md`, replacing
-`provider/model-id` with a model your Pi can use:
+as `<agent dir>/agents/scout.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
+tools: read, grep, find, ls
 ---
 
 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. Delegation guidance
+Every field is optional: without `model` and `thinking` the delegate runs on
+your session's, and without `tools` it has your session's tools (see
+[Agents](#agents)). 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:
@@ -92,7 +96,8 @@ or opened.
 ## How a delegation works
 
 `/delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>]] [--auto-exit | --no-auto-exit] <task…>`
-reads the agent from `<agent dir>/squire/agents/<name>/AGENT.md`, writes
+reads the agent from `<agent dir>/agents/<name>.md` (or a trusted project's
+`.pi/agents/<name>.md`; see [Agents](#agents)), 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,
@@ -102,7 +107,8 @@ 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
+  `<agent>-<first 8 characters of the id>` without a label, where `<agent>` is
+  the agent's `display_name` when it has one. 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
@@ -136,28 +142,273 @@ temporary folder, not as text on the command line.
   resumes with another storage directory selected. A parent whose session
   directory is not an absolute path refuses to launch, before sending the
   task.
-- 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.
+- Delegates restore their identity and task state at session start. Delegation
+  tools are inactive unless the current agent opts in below `maxDepth`; launch
+  and resume admission enforce that boundary even through commands (see
+  [Nested delegation](#nested-delegation-unreleased)).
 - Without a UI the command and the `delegate` tool still work, except a
-  `--cwd` launch whose project trust needs a question (see
+  top-level launch whose project trust needs a question (a nested launch can
+  ask its attended root; see
   [Project trust](#project-trust)). 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.
 
+## Nested delegation (unreleased)
+
+This integration is not ready for production nested agents: descendant tree
+controls and full milestone validation remain required slices. Use only isolated
+development fixtures until the full nesting
+milestone is integrated and tested.
+
+The default `maxDepth` in `<agent dir>/squire/settings.json` is **1**: root
+(depth 0) → delegate (depth 1), with no grandchildren. Set `maxDepth: 2` for
+root → coordinator → worker. A readable value must be a positive safe integer;
+an absent/unreadable settings file uses the safe depth-1 default for exposure.
+Launch/resume refuses malformed, unreadable or non-object settings rather than
+risk silently losing configured tree caps.
+
+A coordinator's agent file opts in with
+`allow_nested_delegation: [worker, reviewer]`, or `true` for any current roster
+agent. Absent, false or an empty list grants no nesting. A list names exact
+agent identities; duplicates are removed. Other values (including null, empty
+scalars, quoted booleans, malformed lists and patterns) disable the agent with
+a path-specific warning. Unknown or unavailable names warn and cannot launch;
+known entries remain usable, and later roster changes apply normally.
+Below the limit the grant adds `delegate`,
+`delegation_status`, `delegation_close` and `delegation_resume` even with an
+explicit `tools` list, subject to the nested tool ceiling. Merely listing those
+tools (including by pattern) does not opt in and produces
+a roster warning. At the depth limit they are inactive and not passed onward.
+
+Every launch/resume re-reads the direct parent's current grant before side
+effects. A refusal names the permitted agents or depth/setting. Removing an
+agent from the grant blocks future launches/resumes, not existing work.
+Trusted project agents still shadow global definitions. Each launching session
+keeps the existing throttled quota checks and shared reactive usage-limit marks.
+
+A nested launch or resume resolves its requested tools, `delegateTools` additions
+and automatic nesting grants, then restricts them to operations available to its
+direct parent. This includes active model-only operations and registered
+codemode/deferred tools, not just displayed schemas. Inactive direct tools and
+hidden tools are excluded. Patterns become exact names; removed tools and
+restricted patterns are reported in the launch/resume notice. The final
+registration allowlist is enforced after synchronous `session:launch`
+customization, so additions cannot register or reach tool names outside the
+direct parent’s ceiling. Top-level launch selection is unchanged.
+
+Each agent keeps its own permission policy; squire does not inherit or compare
+effective policies. A granting agent with a `permission:` map (even `{}`) warns
+when a listed child lacks one; `true` checks all applicable roster agents.
+This is only a heuristic warning, not authorization or proof of lesser privilege.
+Permission policy parsing/enforcement remains the permission provider’s job.
+Tool-name restrictions and configuration permission rules are not filesystem
+isolation: tools such as bash can write files or start processes. The ceiling
+bounds tool names, not arbitrary extension code or the implementation an
+extension registers under an allowed name. Rules asking
+before changes to agent/squire configuration cannot promise interception of
+every indirect write by scripts or repository changes; exact shell handling
+belongs to the permission provider.
+
+A coordinator's task finishes child-first: no final task reply or auto-exit
+while any direct-child task is unfinished. Idle runs and open windows are not
+task completion; a finished `auto_exit: false` child does not hold the barrier.
+Child results steer only their direct parent. The coordinator must receive
+their outcomes in a model request and subsequently settle before reporting
+upstream. A result arriving during final settlement therefore requires another
+processing run, not just decrementing a count. Out-of-order work and rolling
+fan-out are supported; raw grandchild results are not independently forwarded
+to root.
+
+Task takeover and per-run guidance use the same current agent grant/depth check
+as tool exposure. Leaves keep the original final-message wording; only effective
+coordinators receive child-first final-report instructions. Manual reopening and
+grant changes use the current role, not the launch-time role.
+
+Intermediate failures, including exhausted fallbacks, keep the coordinator open
+while workers run. Child results can wake it again; its eventual final run
+determines done/failed. A user stop holds its task through failed runs as before.
+A confirmed vanished worker produces the existing closed-without-result
+outcome, which the coordinator processes without treating it as successful work.
+Unknown tmux state is not disappearance and does not release the barrier.
+
+Identity (direct parent, root, depth, own agent and ordered agent-name chain)
+and child-task facts survive manual reopening of the same Pi session with the
+same agent directory, without launch environment variables. Reopening does not
+adopt another parent's children. Closing/reloading/exiting a parent does not
+terminate its workers. Descendant views and exact-session restoration are
+available below, including explicit ancestor-scoped subtree close. Full integrated
+real-model/permission-forwarding validation is still required before production use.
+
+A nested launch/resume needing an unresolved trust decision asks the attended
+root directly, outside model task mail (see [Project trust](#project-trust)).
+Already-decided trust, inherited-directory trust and explicit approve/no-approve flags remain.
+
+### Tree-wide launch budgets
+
+All sessions beneath a root share these call-time settings in
+`<agent dir>/squire/settings.json`:
+
+| Setting | Meaning | Absent with maxDepth > 1 | Absent with maxDepth 1 |
+| --- | --- | --- | --- |
+| `maxConcurrentDelegates` | Unfinished delegations across the tree, including coordinators waiting for children | 16 | unlimited |
+| `maxDelegatesPerRoot` | Launches over that root session's lifetime, including resumes | 64 | unlimited |
+
+Both accept nonnegative safe integers; **0 means unlimited**. A changed setting
+applies to subsequent admissions. Lowering it never kills existing work. At a
+cap, launch/resume refuses with the current count and limit, before mail,
+worktree creation or killing an exited resume window. There is no launch queue.
+A finished task frees concurrency even if its `auto_exit: false` window stays
+open. It never refunds its lifetime launch. A coordinator's intermediate settle
+or a held user stop does not finish its task.
+
+Shared structural facts and reservations live under
+`<agent dir>/squire/trees/<encoded root session id>.json`. The registry indexes
+ownership, ancestry, resume chains and launch locators; local child-task records
+still own result delivery/processing. Publishing those saved parent facts is
+best-effort: failure warns but does not suppress result/gone messages, steer,
+close tracking or local outcome processing. Every admission reconciles durable
+facts under the registry lock before checking caps, so missed publication does
+not create spare capacity. True local child-task storage failures still block
+completion and admission. Frozen worker replies publish terminal accounting
+before transport, so a finished worker frees a slot even while its parent is
+absent. A failed worker-terminal publication retains the outbox and blocks auto-exit;
+retry/reopen preserves the existing answer. This accounting publication does
+not claim that the parent received or processed the reply.
+
+Admissions use a cross-process mutex on a **local filesystem**, not NFS, and
+atomically reserve both budgets. Short lock contention can wait up to five
+seconds, then refuses; cap exhaustion never waits for a slot. Lock contenders
+have unique files; only a process proven absent permits cleanup, never a lease
+expiry. A reused PID or unknown process state conservatively blocks cleanup.
+Keep the same agent directory when reopening a session. Registry corruption
+refuses admission instead of resetting the budget. Atomic replacement protects
+ordinary process restarts; these records do not promise power-loss durability.
+
+Confirmed pre-start failure refunds both reservations. After a tmux create may
+have been dispatched, an error/timeout is **uncertain**, not a refund. A child
+that starts publishes its own window locator to recover a lost tmux response.
+Subsequent admissions reconcile durable parent/worker facts and observed windows,
+even with the root/intermediate parent absent. Confirmed disappearance frees
+concurrency but is not success; the direct parent still processes its own
+missing-result notification or late reply. Unknown tmux state releases nothing.
+If neither start nor no-start can be established, the reservation remains
+charged; no timeout guesses it away or relaunches it. No parent-death watcher,
+repair daemon, mailbox scraping or implicit ownership transfer is involved.
+
+## Restoring and inspecting a delegation tree
+
+Reopen the **same Pi session id**, using the same agent directory, to restore its
+identity, direct-child tracking, polling, pending results and owed answers.
+Still-running windows are not recreated. Shared counts survive; reopening a
+historically gone but unfinished coordinator counts it toward concurrency again,
+without charging another lifetime launch. A Squire resume is different: it
+starts another delegation and spends another lifetime launch.
+
+Only one Squire runtime may act for an exact session identity. Process ownership
+uses the same cross-process lock as admission, with a per-runtime token and no
+time lease. A live/paused duplicate is refused and asked to shut down; it cannot
+launch, process outcomes, send final replies or start a trust service. Already-
+claimed matching Squire task/reply input is staged under
+`<agent dir>/squire/owners/<encoded session id>/inbound/` before acknowledgment,
+with an atomic per-envelope file, independent of the ownership lock. Only the
+owner drains it, in provider timestamp/path order, through normal handling;
+callbacks run outside the owner mutex and idle drain checks do not write lock
+files. If staging is unwritable, an active ready owner can process directly.
+A duplicate that cannot retain input reports the claimed path and asks for a
+resend: delivery cannot be lossless without writable storage.
+
+This safeguard covers Squire input, not ordinary mail/asks: a duplicate provider
+can deliver those only in the losing process, not to the owner. Its shutdown can
+also remove the shared running record, making the owner look not running to
+`session_mail_ask` until its next provider announcement (such as `agent_start`).
+Squire does not read or rewrite provider mailbox/running-record internals. Keep
+one Pi process per session. Ownership refusals name the PID and owner file; if
+stale/corrupt, verify the original owner has ended, stop affected Squire runtimes
+and repair only that record. Never remove live lock tickets or force adoption.
+
+Fresh sessions do not adopt earlier trees. At startup a fresh root inspects only
+this agent directory's newest **64** registry files, and only entries using its
+current session-storage directory. It reports at most **10** direct owners with
+positively matched live windows and explains reopening the owning session (or
+returning to its existing owner). Registry-content reads are limited to 1 MiB
+per tree and one **200 ms total cooperative notice budget**, including the tmux
+wait, with registry lock waits capped at the remaining budget or 20 ms. The scan
+yields between trees and reports unavailable tmux, unreadable owner records or
+truncated scope once. Individual filesystem operations cannot be preempted.
+Directory names/mtimes are enumerated, but no recursive
+session search, mailbox search or other agent-directory search occurs. Exact-id
+restoration is not restricted by this notice budget.
+
+Both `delegation_status` and `/delegates` show descendants: a root sees its tree;
+a coordinator sees only its own subtree, not siblings or unrelated roots.
+Hierarchy uses stable Pi session ids, not the new delegation id of a resume.
+Parent/root/depth, launch/result/session paths, workspaces, current verified
+window and resume history remain visible. Shared accounting is labeled separately
+from semantic result state: a finished accounting entry is not proof its direct
+parent received or processed the result. Registry-only rows without a complete
+launch record remain unknown. Views read foreign parents' facts but never inject
+grandchildren's raw results into the root conversation.
+
+Only the **direct parent** may resume a child. Ancestor visibility grants no
+resume authority; forked/cloned/copied history with a new Pi id grants none.
+Return to the original parent. Identity is read from exact-id durable state,
+written before launch; inherited launch environment cannot assign a new session
+to the old tree. Current allowlists, depth, caps, callable-tool ceiling and
+directory/source trust still apply to resume, including its picker. A live
+same-id Squire owner and obsolete local/shared resume chains are refused.
+
 ## Where delegate windows open
 
-By default a delegate's window opens in a **companion session** named after
-yours with `-squire` added: from the session `work`, delegates go to
-`work-squire`. Your own session stays as it is, even when its name already
-ends in `-squire`: a session called `pi-squire` gets `pi-squire-squire`.
-pi-squire marks each companion session it creates with the tmux session
-option `@squire-companion`; a parent that runs in a marked session uses it, so
-a delegate that delegates does not make `work-squire-squire`.
+By default a delegate's window opens in a shared **project companion session**
+named `<project>-delegate-session` on your existing tmux server. The owning
+root Pi session's project chooses it, not the parent tmux session or the
+delegate's working directory. Launching into another repository or creating a
+worktree there still uses the root's companion; resuming a delegate does too.
+
+Nested launches inherit the original root project: A → coordinator in B →
+worker in C all select A's companion. The preferred base name (for example,
+`A-delegate-session`) is saved as `rootPlacement` in the existing durable
+delegation identity and shared tree records, not recomputed from B/C or the
+containing tmux session. Reopening the **same** coordinator session without its
+launch environment restores that preference; it can launch or directly resume
+its workers while the root is absent, provided target trust is already resolved.
+Resume retains the original preference and still requires the direct parent.
+The saved preference is not a numbered selected session or a tmux locator:
+every open still applies the managed/unmarked selection rules below.
+
+In Git, the project name is the **main checkout's folder name**. Roots in
+repository subdirectories and linked worktrees therefore share the main
+checkout's companion. Outside Git, use the root working directory's folder
+name (a non-Git subdirectory has its own name). If Git inspection fails or
+cannot locate the main checkout identity, the launch reports a notice and
+uses the root working-directory basename instead.
+
+Project names preserve ASCII letters (including case), digits, hyphens and
+underscores. Runs of other characters become one hyphen, edge hyphens are
+trimmed, and an empty name becomes `project`: `Client API` uses
+`Client-API-delegate-session`.
+
+Multiple roots share a companion even across parent tmux sessions. Distinct
+paths with the same basename, separate clones named alike, and names that
+normalize identically intentionally share it. This groups windows only:
+delegation records, task mail, results, limits and close-all remain scoped to
+each root.
+
+pi-squire verifies the tmux session option `@squire-companion` before reusing
+an occupied name. An unmarked session is left untouched; numbered alternatives
+start at `<project>-delegate-session-2`, skipping unmarked alternatives too.
+Later launches reuse an existing managed alternative even if a lower name
+becomes free. Unexpected duplicate managed candidates use the first in numeric
+order, without moving windows or repairing sessions. Existing legacy companions
+and live windows are neither renamed nor migrated; only new launches and
+resumes use project naming.
 
 - The session is created on demand, by the launch that needs it, and tmux
   removes it with its last window, so it does not outlive its delegates.
+- Closing delegates (including close-all) kills only that root's tracked
+  windows. Manually killing the shared tmux companion session terminates
+  **all** its windows, including other roots' delegates.
 - `detach-on-destroy` is set to `off` (and the mark set) on that session only: if you are
   looking at it when its last delegate exits, tmux moves you to your most
   recent other session instead of detaching you. Your sessions and tmux's
@@ -176,22 +427,212 @@ To open windows in your own session, as before, set `windowPlacement` in
 ```
 
 The values are `companion` (the default when the setting is absent) and
-`current`. The file is read at each launch. Any other value refuses the launch
+`current`. The mode is read at each launch/resume independently of the saved
+project preference. Even a `current` launch saves the original root project for
+later companion launches; `current` itself still opens in the invoking pane's
+session. Missing or malformed `rootPlacement` in a recorded identity, or conflicting
+saved/launch identities, refuses restore/admission/resume. Identity-less records
+also cannot be resumed after this update, including by their original root
+(see [Resuming a delegation](#resuming-a-delegation)). There is
+no identity migration, directory relocation/rename tracking or companion repair.
+The file is read at each launch. Any other value refuses the launch
 with an error naming the file, before the task is sent or a window opens.
 
+<a id="direct-delegate-overview"></a>
+
+## Delegate overview
+
+In interactive Pi, Squire shows a compact **Delegates** tree above the editor.
+It lists this session's running direct delegates first, then finished delegates
+whose windows are still open, newest launch first within each group. A resumed
+delegate keeps one row keyed by its stable Pi session id, not by its new
+delegation id or mutable title. Failed and stopped results keep their actual
+outcome labels; an open window or quiet session is not evidence of success.
+
+Rows show the recorded delegate identity in bold, the current native Pi session
+title when available, and task state. No title is repeated when it matches the
+identity. The recorded launch model (or result model when available) and
+transcript-file age appear when space permits: model is
+dropped first, then file age, before identity/state are compressed. At very
+narrow widths the state glyph remains beside the truncated identity.
+`file … ago` is only a last-active hint from transcript mtime, not live tool
+activity. When available, a second line shows factual live activity (below).
+Each coordinator row summarizes **all descendant tasks**, at every depth,
+including tasks whose windows have exited. Counts are per delegation/launch id,
+not per stable session: a failed task and its resumed successor both count, so
+a retry cannot erase a known failure. Actual replies supply done/failed/stopped;
+saved gone/closed-without-result tasks count as missing. Shared registry
+finished/closed/closing flags are not successful replies or proof another
+parent processed an outcome. Missing parent facts or tree coverage are labeled
+unknown/partial/unavailable, never all done. Summary and activity share one
+secondary line; when both do not fit, the task summary wins.
+
+Delegates also see their ancestors vertically, root to direct parent, with the
+direct parent marked `(parent)` (including `root (parent)`). A connected
+**Delegates** branch contains only the current session's direct children.
+There is no current-session row or empty child heading; leaves show ancestors
+only. Ancestor rows and secondary lines do not consume child-entry slots.
+
+Configure it in the existing `<agent dir>/squire/settings.json`, alongside
+`windowPlacement`, worktree and nesting preferences:
+
+```json
+{
+  "delegateWidgetPlacement": "above",
+  "delegateWidgetMaxEntries": 3
+}
+```
+
+- `delegateWidgetPlacement`: `above` (default) or `below` the editor.
+- `delegateWidgetMaxEntries`: nonnegative safe integer, default **3**. Each
+  direct child consumes one slot. `+N more direct delegates` counts hidden
+  eligible direct children, not descendants. **0** hides child rows and restores
+  Squire's running-count footer while preserving ancestor rows/navigation;
+  zero children never produce an empty heading.
+- These preferences apply equally to roots and coordinators. Interactive views
+  re-read them about once a second; invalid widget preferences warn once per
+  distinct error and use the defaults without changing task state.
+
+Launch/result/close changes refresh promptly; an independent one-second observer
+keeps finished-open rows, window eligibility and later native title changes
+fresh even when the result poll has stopped. Only visible rows resolve titles and
+file metadata and live activity; overflow counts still include every eligible child. Closed/gone-only
+history without a live reattached session does not keep the observer listing
+windows. A positively reopened gone coordinator may appear at its current window
+with its missing-outcome history intact; reopening does not make its task running. A failed tmux listing is unknown,
+not proof that a window disappeared: running tasks remain eligible, but
+finished rows require a positively open matching window.
+
+Titles come from the latest complete native `session_info` in the delegate's
+known session file, including external /resume-picker renames and explicit
+clears. A small owner-only disposable title mirror under
+`<agent dir>/squire/session-titles/` covers sessions with no persisted title
+(including before the first transcript flush). Naming tools are optional;
+`/name`, `--name` and Pi's native setter work. Persisted metadata takes priority
+over that mirror: an external picker rename may differ temporarily from the
+child's own in-memory name. Files are read incrementally, with bounded work per
+refresh; very large existing transcripts may take several refreshes to catch up.
+
+### Factual live activity
+
+The secondary line follows actual Pi tool-execution events: `reading…`,
+`editing…`, `writing…`, `command call…`, or `using <tool name>…`. Parallel
+and nested calls are tracked by their actual call ids, not by tool name.
+Active nested calls take precedence over their orchestrator. A tool start is
+observed before permission interception: `command call…` means an outstanding
+call, not proof that a subprocess started or permission was granted. Squire
+does not inspect commands to guess intent, or display arguments, paths, tool
+results, thinking or provider payloads.
+
+Otherwise, while an assistant response streams, `response: …` shows a literal
+single-line excerpt bounded to 512 UTF-8 bytes. It clears when that message
+ends; a quick response may finish between refreshes and never appear. Calls
+clear on matching end, run end/settlement, stop, reload and shutdown. Known
+task results/close suppress activity even if a delegate's last snapshot remains.
+A settled or silent coordinator can still own unfinished child tasks: activity
+does not determine task completion, thinking or waiting for a human.
+
+This best-effort feed uses bounded owner-only atomic snapshots under
+`<agent dir>/squire/live-sessions/`, separate from title mirrors and durable
+task/tree state. Each runtime owns a unique generation; dead/reused processes
+are rejected and their own snapshots can be removed, while unknown or duplicate
+live owners make activity unavailable. No inactivity timeout or stale-state UI
+is introduced. The same private launch correlation distinguishes a resumed task
+from its stable Pi session. Manual reopen without this correlation does not
+supply task-row activity yet. Missing, corrupt or inaccessible telemetry never
+blocks task launch, reply delivery or settlement, and causes no chat or model
+calls. Publication requires positive Squire ownership at startup; later factual
+end/settlement observation continues even if task-owner processing fails or its
+record becomes unreadable, without re-enabling actions. Event publishing works
+in non-TUI delegates and with the list hidden.
+One child-entry slot may occupy two physical lines; there is no empty secondary
+line or tool-use counter.
+
+### Navigation
+
+At an **empty built-in prompt**, press **Down** to select the direct parent in a
+delegate session, or the first child at root. Up/Down traverse ancestors and
+eligible children in display order; only children scroll within the configured cap;
+hidden-above/below counts refer to direct children. Selection follows stable
+session identity through renames, reordering and resumes. Enter opens that
+child's details in the **same dashboard** as /delegates, scoped to that child's
+branch (including descendant and resume history, not its siblings). Press **b**
+for the branch list to select and inspect its workers. Initial details Escape
+returns directly to the compact list; details opened from the branch list return
+to that branch list first. Branch-list Escape returns to the compact list, then
+Escape again returns to the prompt; Up past the first compact row also leaves
+the list. A short hint appears only while the list owns these keys.
+Typing or any unrelated key leaves list navigation and passes that key through.
+While a widget-opened dashboard is loading or re-listing between actions, keys
+are absorbed only if the exact empty built-in prompt still owns focus: Escape
+cannot abort a run and action letters cannot leak into that prompt. Once a
+real dashboard, dialog, completion menu or unknown component owns input, its
+keys pass through normally.
+Cap zero never creates invisible selectable children; ancestors remain selectable
+and /delegates still works.
+
+Enter on an ancestor switches directly to its verified **current live tmux
+window**, not to the dashboard or a historical launch window. Root and leaf
+processes publish their own positive pane/window observation in the same
+disposable generation snapshot used for activity. The reader checks the elected
+exact-session owner, process incarnation, tmux server socket/PID/start identity,
+exact pane and window id **and** name. Current window placement is read from tmux;
+cwd, companion names and rootPlacement are never used to guess a root window.
+Own-pane observations refresh about once a second even while quiet or cap zero.
+A rename/move before the owner refreshes fails closed; a later positive update
+makes the new locator available. This navigates to the window, not a specific
+pane's keyboard focus.
+
+An exact-id manual reopen can supply a new locator without launch environment,
+while old task history stays unchanged. It still cannot supply launch-correlated
+task activity. Missing/unreadable/ambiguous metadata, a different server, a dead
+pane or no attached client reports an unavailable target. Navigation never
+adopts, recreates, kills or implicitly resumes an ancestor. New/forked session ids
+do not inherit ancestor authority from copied history.
+
+Squire owns only its widget key and its existing status entries. It does not
+replace your footer or editor, and cleans up observers/input listeners on
+shutdown or reload. Automatic navigation deliberately passes through custom
+editors, autocomplete, dialogs, permission questions and unrelated dashboards.
+It relies on **Pi TUI internals**, isolated in a small compatibility adapter:
+the concrete focus getter and exact built-in editor identity. Compatibility was
+tested with the installed **Pi 1.4.0 bundled CLI**, including regular/fullscreen
+mode changes. Unknown focus/editor/completion capabilities disable key capture
+rather than guessing; /delegates remains available. This is not a generic
+custom-editor integration or a supported Pi focus hook. JSON/RPC hosts retain
+the running-count status rather than receiving a terminal widget.
+
 ## Reaching delegates
 
 Delegate windows sit out of your way, so reach them from the parent. `/delegates`
-(or `alt+shift+d`) opens a panel of the delegations whose window is open: running,
-or done with auto-exit off, newest first. The model has no tool for any of this.
+(or `alt+shift+d`) opens the same dashboard used by widget Enter, at the overall
+view of its descendant hierarchy, including
+closed/history rows. Parents precede their children; resume history stays
+visible. Each row shows stable launch identity, the available current native Pi
+title, agent display label, semantic state/outcome and verified window availability.
+Enter opens selected details with identities, paths, result envelope, workspace
+and resume information. Historical launch windows are labeled separately from
+current verified windows. Lists and details scroll within the available screen.
+Widget entry uses the same screen for only its selected branch; `b` exposes that
+branch's list without widening its scope. A title change never changes routing.
+Metadata is refreshed when opening/reopening the screen after an action; the
+compact overview remains the live activity/summary view.
+Only a verified live window supports switch/peek; the model has no
+tool that moves the terminal. Any ancestor can explicitly close a selected
+subtree. The root also has a confirmed close-all action; shared companion names
+never grant control over another root.
 
 | Key | Does |
 |---|---|
-| `↑` / `↓` | select a delegation; `esc` leaves the panel |
-| `enter` | switch your tmux client to the window |
+| `↑` / `↓` | select a delegation in the list; scroll in details |
+| `enter` | open selected details; from details, switch your tmux client to its verified window |
+| `esc` | details → overall list → prompt; initial widget details → compact list; branch-list details → branch list → compact list |
+| `b` | widget entry only: show the selected branch list, preserving its target and history |
 | `p` | peek: a snapshot of the window's pane (`capture-pane`) in an overlay; `r` refreshes, `enter` switches, `esc` returns to the list |
-| `x` | close the delegation as `delegation_close` does; asks first only while it is running |
-| `n` | new delegate: the same form `/delegate` opens with no arguments (see [First use](#first-use)) |
+| `x` | explicitly close the selected subtree as `delegation_close` does; confirms running work and verified live navigation rows |
+| `a` | root only: confirm closing **all root** descendant subtrees, including absent coordinators, even when viewing one branch |
+| `r` | resume the selected eligible direct child, collecting a follow-up through the existing resume flow; descendants without authority are refused |
+| `n` | new child of the invoking session, not of the selected remote row: the same form `/delegate` opens with no arguments (see [First use](#first-use)) |
 
 Switch acts on the most recently active tmux client attached to the parent's
 session. With none attached it refuses with a notice; peek and close still
@@ -204,6 +645,22 @@ often rebound); the notice after a switch says so.
 without the panel: with no flag or with `--switch`, it switches; `--peek` opens
 the peek overlay. Ids complete from the open delegations.
 
+Dashboard switch/peek and `/delegate-open` share current-locator verification.
+For the latest known launch of a stable session, a positively observed current
+runtime supersedes its old launch window; a later lost/changed locator refuses
+rather than falling back to an old still-open window. Exact Pi pane liveness
+allows navigation even if a different active pane has exited, and peek captures
+that verified Pi pane. Legacy tracked windows still require matching id and
+name. Reattached process visibility does not rewrite historical gone/closed/
+result facts, invent task activity, or grant resume authority. Current telemetry
+is navigation evidence only: close still uses the existing shared control
+runner's durable locators/fences and reports partial failures honestly. A live
+reattached navigation window may remain open when it differs from the durable
+control locator; confirmation warns about that distinction. Current-locator
+supersession memory lasts only for this navigator runtime: after a restart,
+before the first positive live observation, a legacy id+name-verified historical
+window can still be offered.
+
 ## Working directory
 
 `--cwd <dir>` (the `delegate` tool's `cwd`) runs the delegate in an existing
@@ -304,10 +761,12 @@ is `/Users/me/.pi/agent/squire`, the matching relative override resolves to
 `/Users/me/.pi/agent/special-checkouts/feature-topic`. The Git branch remains
 `feature/topic`.
 
-The settings file is read only for managed creation. A missing file uses the
-built-in default; malformed or inaccessible settings, invalid templates and
-duplicate canonical repository keys refuse creation rather than silently
-falling back. They do not affect inherited or `cwd` launches. Placement does
+Worktree placement keys are read only for managed creation. A missing file
+uses the built-in default; invalid templates and duplicate canonical repository
+keys refuse creation rather than silently falling back. Those creation-key
+errors do not affect inherited or `cwd` launches, but malformed, inaccessible
+or non-object shared settings refuse every launch/resume because tree caps
+cannot be read safely. Placement does
 not choose a source checkout or base commit. Pi discovers `AGENTS.md`, skills
 and other project context from the created directory and its ancestors, so the
 chosen layout determines which instructions and skills apply. For a layout
@@ -366,9 +825,12 @@ command, and nothing acts on it.
 
 ### Project trust
 
-The delegate's trust flag for a `--cwd` directory is decided in the parent,
-before the task is sent or a window opens. A same-repository managed worktree
-uses the parent's current trust for that repository. The model has no trust input.
+The requesting parent resolves the delegate's trust flag before task mail,
+worktree creation or a window opens. Unresolved choices go to the root user,
+not to an intervening model or an unattended delegate UI. A same-repository
+managed worktree uses the requester's current trust for that repository.
+The model has no trust input; every launch/resume still passes explicit
+`--approve` or `--no-approve`.
 
 1. A directory in the parent's own repository, by Git's common directory, so
    including its linked worktrees, gets the parent's current trust, even a
@@ -386,8 +848,9 @@ uses the parent's current trust for that repository. The model has no trust inpu
    (`.pi/settings.json`, extensions, skills and the like, or an
    `.agents/skills` directory above it), the delegate starts with
    `--no-approve` and no question.
-4. Otherwise the parent asks, naming the directory, the main repository when
-   it is the key, and what each answer saves:
+4. Otherwise the root asks, naming the requesting agent chain, requester
+   session id, directory, the main repository when it is the key, and what each
+   answer saves:
    `Trust`, `Trust parent folder (<folder>)` (left out at the filesystem
    root), `Trust (this session only)`, `Do not trust` and
    `Do not trust (this session only)`. The two "this session only" answers
@@ -398,55 +861,178 @@ uses the parent's current trust for that repository. The model has no trust inpu
    the turn or tool call stops a launch that is waiting for or answering a
    question; nothing is saved, sent or opened.
 
-Without a UI a question cannot be asked, so the launch is refused: open Pi in
-that directory and answer its trust question first. A trust store that cannot
-be read or written also refuses the launch; nothing is granted by default.
+An unresolved nested question requires the same root Pi session to be running
+with dialog-capable UI (TUI or RPC), without `PI_UNATTENDED=1`. An absent or
+unavailable root refuses immediately; a disconnected root fails its pending
+launches, rather than waiting for the root to return. Already-resolved trust
+and resource-free targets need no root connection. A root's own trust in a
+different repository never supplies approval. For a top-level launch without UI,
+open Pi in the trust key directory named by the refusal (the source/main checkout
+for a managed worktree), answer its trust question, then delegate again.
+
+Root questions, local and remote together, are serialized, even while the
+root model is busy. Each request has a **10-minute deadline including queue
+wait**. Escape, tool/turn cancellation, requester or root shutdown/reload/session
+replacement, disconnection and expiry cancel that launch and dismiss its
+question; canceled queued requests are skipped. An unrelated root model run's
+abort does not cancel a remote request. Late decisions cannot save trust or
+start the canceled work. A new launch after reopening makes a new request;
+pending requests and decisions are never replayed.
+
+Squire uses an authenticated **127.0.0.1 loopback connection**, not mail or
+`session_mail_ask`, for this control. The root writes its random port and
+per-runtime token to the owner-only
+`<agent dir>/squire/trust/<SHA-256 of root id>.json` descriptor. Only squire
+reads it; no provider files, APIs or tool grants are needed. Unreachable
+endpoints fail at once (connection establishment is bounded to one second).
+A fresh client-nonce/HMAC handshake verifies the root before sending any
+question or secret, so a reused stale port cannot impersonate it. Root restart
+changes the token, invalidating old frames.
+The descriptor is transient and removed on ordinary shutdown; a crash can
+leave a harmless stale descriptor that cannot approve anything. Like the rest
+of squire, this is not an OS boundary against processes running as you.
+
+Only the live **requester** saves a persistent choice in that agent directory's
+Pi `trust.json`, after cancellation/deadline checks and before launch.
+The root holds the queue until the requester has applied the answer or
+disconnected, so queued requests re-read saved decisions. The two session-only
+choices save nothing and apply only to that launch. `Do not trust` launches
+untrusted; Escape cancels instead. A trust store that cannot be read or written
+refuses the launch; nothing is granted by default.
+
+Model questions still use `session_mail_ask` to the direct parent, parent by
+parent. Permission prompts remain with the permission provider, with each
+child's own agent policy: there is **no permission inheritance**. Its bridge
+can label a requester with `PI_DELEGATE_CHAIN` (comma-separated roster names,
+root downward including the current delegate); `session:launch.chain` is the
+corresponding frozen string array. Routing uses separate parent/root session
+ids, not chain names. Squire does not implement that permission bridge.
 
 ## Agents
 
-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,
-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
-(`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.
-
-`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
-with a warning; the agent still loads.
+An agent is one Markdown file, `<name>.md`, in the agents folders Pi agent
+tooling shares; the file name without `.md` is the agent's name (letters,
+digits, `_` or `-`). The roster is read at call time, so a new or edited file
+is usable without a reload.
+
+- `<agent dir>/agents/<name>.md` holds the global agents.
+- `<cwd>/.pi/agents/<name>.md` holds a project's agents, read only when Pi
+  reports the parent's project as trusted. A project file replaces the global
+  file of the same name. In an untrusted project only the global agents load,
+  so a cloned repository cannot change a delegate's prompt, model or tools.
+
+The body is the delegate's instructions, 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. Every frontmatter field is
+optional, and the [first-use example](#first-use) is a complete agent file:
+
+| Field | Meaning |
+| --- | --- |
+| `description` | Shown in the roster and the `delegate` tool's description. Defaults to the name. |
+| `display_name` | Shown instead of the name on the delegate card, in `/delegates` and in the window title (`<display_name>-<label>`). The agent is still called by its name. It may hold only ASCII letters, digits, `-` and `_`; any other value (a space, `#`, `.`, a non-ASCII letter, or an empty value) makes the file invalid, so the agent is disabled. |
+| `model` | One model: `provider/id` or an alias such as `sonnet`, passed to the child's `--model` unchanged, so Pi resolves it to one model. A `*` pattern makes the file invalid. Absent means the parent session's current model. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. Absent means the parent session's level; an unknown value is dropped with a warning and the parent's level applies. Pi clamps the level to the model. |
+| `tools` | The delegate's tools (see below): tool names for exactly those, or only `-name` entries for the parent session's current tools less those. Absent means the parent session's current tools; empty (`tools:` or `tools: []`) means no tools except the `delegateTools` setting. MCP tools follow the selection like any other. |
+| `fallback` | Models to try, in order, when `model` is usage-limited (see [Usage limits](#usage-limits)). Each entry is one model, like `model`; a `*` pattern, or a YAML list entry holding a comma, makes the file invalid. A comma-separated line (`fallback: a, b`) is two entries. |
+| `auto_exit` | `true` or `false`, default `true`; see [Auto-exit](#auto-exit). |
+| `allow_nested_delegation` | Unreleased: `true` or a YAML list of exact child agent names; grants nested delegation below `maxDepth`, subject to the parent tool ceiling (see [Nested delegation](#nested-delegation-unreleased)). Absent, false or an empty list grants none. Malformed values disable the agent; unavailable names warn. |
+| `prompt_mode` | `append` (the default) wraps the body in `<agent_instructions>` and `</agent_instructions>` lines; `replace` adds the body unwrapped. An empty body adds nothing either way. |
+| `enabled` | `false` leaves the agent out. A project file with `enabled: false` hides a global agent of the same name in that project. |
+| `locked` | `true`, or a list of `model` and `thinking`. A call to `delegate`, `/delegate` or a resume that passes a locked field does not get it: the agent's value is used (the parent's when the file sets none) and the result says which agent locked which field. Passing the agent's own value is the same as passing nothing: no notice, and its fallbacks still apply. A resume of a locked field runs on the file's value as it is now, not on what the delegate last ran on. `true` locks the fields the file sets. |
+
+Any other key, such as `max_turns`, `inherit_context` or `run_in_background`,
+is ignored without a warning and left for whatever else reads the file.
+Squire observes only whether `permission:` is a map for the nested-grant warning
+above; it leaves interpretation and enforcement to the permission provider.
+
+**Breaking frontmatter change:** use `auto_exit` instead of `auto-exit`.
+The old `auto-exit` and `extensions` fields are silently ignored, including
+malformed values and missing extension paths. In particular, an old
+`auto-exit: false` no longer keeps the delegate open: without `auto_exit: false`
+or a call override, auto-exit defaults to on. Agent-specific extension loading
+has been removed from both launch and resume. Normal Pi extension discovery
+and [`session:launch`](#sessionlaunch) customization remain available.
+The `--auto-exit` / `--no-auto-exit` flags, `/auto-exit` command and
+`PI_DELEGATE_AUTO_EXIT` environment variable are unchanged.
+
+`exclude-tools` is no longer read; a file that still has it gets a warning
+(use `tools` instead).
+
+`tools` lists the delegate's tools as a comma-separated or YAML list
+(`tools: read, grep` or `tools: [read, grep]`). Each entry of a YAML list
+names one tool: an entry holding a comma, such as `tools: ["read,-bash"]`,
+makes the file invalid. pi-squire works out the delegate's whole selection
+itself and always passes the child a plain list, `--tools read,grep`, which Pi
+treats as the whole selection, extension tools included; entries may be `*`
+patterns. It never passes Pi `+name` or `-name` entries. MCP tools follow the
+list like any other tool: an MCP tool (`mcp__<server>__<tool>`, or one of the
+MCP resource tools) that no entry names or matches is not registered in the
+delegate at all, so it is neither declared nor callable from `codemode` nor
+loadable by `tool_search`, whatever its exposure. Pi filters MCP tools by
+`--tools` only once an entry starts with `mcp__`, so when the list has no
+such entry pi-squire adds the entry `mcp__`, which names no tool; an empty
+selection is `--no-tools`, which removes MCP tools too. To give a delegate an
+MCP server's tools, name them, for example `mcp__docs__*`. An extension that
+turns tools on at run time can still add only tools the list allows. Top-level tool names
+are not checked against the parent's tools: normal Pi extension discovery
+or `session:launch` customization can provide tools in the child. Nested launches
+and resumes instead apply the direct parent’s callable-tool ceiling after all
+selection and customization, as described above; this is not filesystem isolation.
+
+- No `tools` field: the delegate gets the parent session's tools as they are
+  when the launch (or resume) starts: active tools for a top-level launch, or
+  available tools including codemode/deferred operations for a nested one, passed as
+  `--tools`, plus the `delegateTools` entries. A parent limited to `read`
+  gives such a delegate only `read`.
+- An empty `tools` field, `tools:` or `tools: []`: the delegate gets no tools
+  except the `delegateTools` entries. With none of those either, it starts
+  with `--no-tools`.
+- A `tools` list of tool names: exactly those tools, plus the
+  `delegateTools` entries.
+- A `tools` list of only `-name` entries (`tools: -bash, -write`): the
+  parent's tools, as with no `tools` field, less those, plus the
+  `delegateTools` entries. A `-name` entry may be a `*` pattern
+  (`-mcp__docs__*`).
+- A `+name` entry, or tool names and `-name` entries in one list, make the
+  file invalid, and the agent is disabled (see below).
+
+The delegation tools (`delegate`, `delegation_status`, `delegation_close`,
+`delegation_resume`) are removed from ordinary tool selections. An opted-in
+coordinator below `maxDepth` receives them automatically; a leaf has them
+inactive. Commands are still registered but cannot bypass admission. See the
+unreleased [nesting restrictions](#nested-delegation-unreleased).
+
+The delegate's result reaches the parent through the `message:*` provider's
+reply hook when squire settles the task, not through a tool, so a short `tools` list cannot
+stop it answering. To let a delegate message its parent mid-task, whatever its
+`tools`, list the tools your `message:*` provider gives a session for that in
+the `delegateTools` setting, in `<agent dir>/squire/settings.json` beside
+`windowPlacement` and `worktreeRoot`:
+
+```json
+{ "delegateTools": ["<tool or pattern>"] }
+```
+
+Each entry, a tool name or `*` pattern, is added to every delegate's tools,
+whether they come from its agent's `tools` or from the parent (after any
+`-name` entries are taken off). Top-level launches pass these to `--tools`
+unchanged; nested launches/resumes resolve and cap them by the direct parent’s
+available tools. The setting
+is empty by default, is read at each launch and resume, and a value that is
+not a list of names, or an entry that holds a comma or starts with `+` or
+`-`, refuses every launch with an error naming the file, before the task is sent or a window
+opens; it does not disable agents one by one.
+
+A `model` or `fallback` entry that is an exact `provider/id` in Pi's registry
+is checked as before: a model without credentials or with an active
+usage-limit mark is skipped for the next candidate. Anything else, such as an
+alias, goes to the child's `--model` unchanged, and Pi resolves it to one
+model; if Pi cannot, the child's Pi reports the error and its window closes
+without a result. When a running delegate moves to a fallback after a usage
+limit, it resolves each entry the way Pi resolves `--model`: an exact
+`provider/id`, or a bare id or alias such as `sonnet`, to one model, in the
+order the entries are listed. No entry may be a `*` pattern: a `model` or
+`fallback` entry with `*` makes the file invalid, and the agent is disabled.
 
 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
@@ -454,24 +1040,39 @@ 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.
-
-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, 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
+whatever `message:*` provider delivers the task. `prompt_mode: replace` builds
+the prompt exactly as every delegate was built before `prompt_mode` existed.
+
+An agent file that cannot be used is invalid, and its agent is disabled:
+frontmatter that is not readable YAML or not a set of fields, an `enabled` or
+`auto_exit` that is not `true` or `false`, a `tools` value that is not a list,
+a `tools` list with a `+name` entry or with tool names and `-name`
+entries mixed, a `tools` or `fallback` YAML list entry holding a comma, or a
+`model` or `fallback` entry with a `*` pattern. A disabled agent is left
+out of the roster and of the `delegate` tool's description, so the model never
+picks it, and a warning names the file and the reason when the session starts
+(and before a run, when a file turns invalid while the session runs). A call
+or resume that names it anyway is refused with that reason. A
+field that cannot be used (a `fallback` that is not a list, an unknown
+`thinking`, `prompt_mode` or `locked` entry) is dropped with a warning and the
+agent still loads. While the retired `<agent dir>/squire/agents/` folder
+exists, a warning says to move each `<name>/AGENT.md` to
+`<agent dir>/agents/<name>.md`. With no agents at all, `/delegate` says how to
 add one.
 
 ## Configuration
 
-`<agent dir>/squire/` holds the roster and the optional parent guidance file.
+`<agent dir>/squire/` holds the optional parent guidance file and
+`settings.json` (`maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`,
+`windowPlacement`, `worktreeRoot`, `delegateTools`, `delegateWidgetPlacement` and
+`delegateWidgetMaxEntries`); the
+agents live in `<agent dir>/agents/` (see [Agents](#agents)).
 `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`
+and is not copied into the launched child's prompt. An opted-in coordinator
+reads this same file for its own parent role. 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;
@@ -481,43 +1082,56 @@ 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
-set; `--session-dir` outranks it), `PI_DELEGATE_PARENT` and `PI_DELEGATE_AUTO_EXIT`, and it always gets `PI_UNATTENDED=1`.
+loop, and the extension does not watch the filesystem. `pi-squire` uses launch variables to bootstrap a delegate; durable session
+identity takes precedence when it reopens. The window starts with the tmux
+server's environment plus `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`
+(when set; `--session-dir` outranks it), and these delegate values:
+
+- `PI_DELEGATE_PARENT`: direct parent's session id;
+- `PI_DELEGATE_ROOT`: root session id;
+- `PI_DELEGATE_DEPTH`: child depth as a decimal string;
+- `PI_DELEGATE_AGENT`: this child's roster identity (not display name);
+- `PI_DELEGATE_CHAIN`: comma-separated agent names, root downward, including
+  the child last, e.g. `coordinator,worker`; names label requests, session ids route them;
+- `PI_DELEGATE_AUTO_EXIT`: `1` or `0`;
+- `PI_DELEGATE_FALLBACK`: remaining model candidates, when any.
+
+It always gets `PI_UNATTENDED=1`.
 `PI_UNATTENDED=1` is a general signal, not specific to pi-squire: no human is
 watching this session, even though it runs in a TUI. Other extensions may read
 it to skip a dialog or confirmation instead of waiting on one, and any other
 runner that starts Pi unattended can set it too. Anything else the
 parent process has, such as a `CLAUDE_CONFIG_DIR` set by a shell alias,
 reaches the child only through a `session:launch` contributor. `--model` and
-`--thinking` override the agent's defaults for one call, and an unknown value
+`--thinking` override the agent's defaults for one call, unless the agent
+locks them (see [Agents](#agents)), and an unknown value
 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`.
+agent's `auto_exit`.
 
 ## Tools
 
 The model gets four 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. In a delegate they are active only for an
+opted-in coordinator below `maxDepth`; admission also checks every launch/resume.
 
 | Tool | Parameters | What it does |
 | --- | --- | --- |
 | `delegate` | `agent`, `task`, optional `model`, `thinking`, `label`, `cwd` and `auto_exit` (boolean) | Validates the call the way the command does, starts the delegation without opening a dialog (except an unresolved [trust question](#project-trust) for `cwd`), 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. |
+| `delegation_close` | `id` | Explicitly fences and closes a descendant subtree using current verified windows. Returns per-member outcomes and complete/partial status; retains worktrees and branches. |
 | `delegation_resume` | `id`, `task`, optional `model`, `thinking` and `auto_exit` | Reopens an exited delegate's own session in a new window with a follow-up task, and returns the new delegation's id at once (see [Resuming a delegation](#resuming-a-delegation)). |
 
 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.
+its name and any display name, description, default model (or this session's)
+and fallbacks, thinking, auto-exit when it is off, its tools (`no tools` for
+an empty `tools` field, `this session's except …` for `-name` entries) and the
+fields it locks.
 
 ```text
-- scout — Read-only recon (default provider/model-id, thinking low, auto-exit off, no edit/write)
+- scout "Recon" — Read-only recon (default provider/model-id, thinking low, auto-exit off, tools: read/grep, locked: model)
 ```
 
 The model picks an agent from these lines without reading files. The
@@ -529,9 +1143,9 @@ 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
+re-registered. The description built while extensions load lists only the
+global agents, since the project's trust is known only once the session
+starts. 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.
 
@@ -611,10 +1225,63 @@ even when no delegation is recorded. The details gain a `marks` array of
 `{ scope, source, reason, clearsAt }` and a `readingErrors` array (see
 [Usage limits](#usage-limits)).
 
-`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.
+## Explicit subtree close
+
+`delegation_close` and the `/delegates` close actions enumerate persistent
+records and close the selected session and all its descendants, including work
+whose coordinator is offline. Any ancestor may close; unrelated trees, siblings
+outside the selected subtree and user windows remain untouched. Only the root
+has the panel's `a` close-all action. Close-all fences new root admissions too;
+neither action kills a companion tmux session wholesale.
+
+Admission is fenced under the shared tree lock **before** window effects.
+Already-reserved pre-dispatch launches cannot dispatch; an already-dispatched
+create stays charged and fenced until its outcome/current locator is known.
+The explicit call makes at most three passes, with two 25 ms waits for late
+locator publication, and otherwise returns partial. It never infers no-start
+from a timeout, dead opener, finished accounting or an empty tmux listing.
+There is no automatic close-repair daemon. Retry the explicit operation after
+positive create/window evidence becomes available; unknown launches are not
+refunded or relaunched speculatively.
+
+Only a window matching the **current recorded id and name** is killed, even
+if its program has exited or its tmux session moved. A same-id manually reopened
+coordinator can have a newer shared locator than its parent's launch history;
+close uses that locator. An already absent verified window records a close.
+Individual tmux or persistence errors do not erase successful members. A failed
+initial registry read/fence refuses before any kill; a post-kill publication
+failure reports the side effect and uncertainty, not successful completion.
+
+The tool's `details` and `structuredContent` match its output schema:
+`{id, windowId?, windowName?, closed, complete, alreadyClosed, killed, members,
+error?}`. Each member has `{id, sessionId, windowId?, windowName?, outcome,
+closed, killed, error?}`; outcome is `killed`, `absent`, `already-closed`,
+`not-started`, `pending` or `error`. Aggregate `closed/complete` is true only
+when every captured member is resolved; partial returns `isError:true` while
+retaining structured details. Repeat close visits unresolved descendants even
+if the selected coordinator alone was already closed. Unknown/out-of-scope
+ids and obsolete resumed records refuse without window effects.
+
+Confirmed shared closes are control/accounting facts, not fabricated worker
+results. The sole direct-parent owner imports them into its own durable
+child-task inbox as canceled/missing work, then processes them in a model run
+before finishing upstream. An offline coordinator does this on same-id reopen;
+the ancestor never writes its semantic state or emits raw grandchild reports.
+A stopped root retains its previous replay hold on reopen. Fresh live close
+outcomes wake normally, like other new outcomes. Real replies arriving before,
+during or after close are retained and correlated normally, not replaced by a
+success or cancellation envelope.
+
+Once the explicit operation is complete, a legitimate direct-parent resume can
+supersede that session's completed fence as a **new lifetime-counted delegation**.
+It still passes current authority/owner, chain, depth, grants, caps, tool-ceiling
+and trust checks. Failed pre-dispatch resumes leave the old fence effective.
+Closed descendants remain canceled; resuming a coordinator does not revive them.
+An unresolved active close cannot be bypassed by resume.
+
+Quit, crash, reload, session switch and auto-exit do **not** cascade. Close never
+removes worktrees, branches, session files or result envelopes. Existing narrow
+rollback of pristine resources on a known failed launch is unchanged.
 
 ## Usage limits
 
@@ -647,8 +1314,9 @@ The launch also passes the candidates after the chosen one to the delegate as
 `PI_DELEGATE_FALLBACK` (none for an explicit model). When a delegate's run
 ends on a usage limit, it switches its session to the first of them that has
 credentials and is not marked, adds a message saying so, and continues the
-task there, so work done so far is kept. Each fallback is tried once; when
-none is left, the run fails as before. A `done` result from such a delegate
+task there, so work done so far is kept. An alias resolves to one model, as
+it would in Pi's `--model`. Each model is tried once, never the one that just
+failed; when none is left, the run fails as before. A `done` result from such a delegate
 carries the `Usage limit:` line too, saying it finished on a fallback.
 
 Before a launch, pi-squire also reads the OpenCode Go quota for a paid
@@ -715,17 +1383,20 @@ mark, it changes nothing and lists the active marks. No tool clears marks.
 
 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`
+`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 (see [Reopening a delegate's session](#reopening-a-delegates-session)).
-- A failed run, such as one ending on a usage limit or another provider
-  error, exits like a normal completion; the parent still gets the failed
+- A failed final run, such as one ending on a usage limit or another provider
+  error after fallbacks are exhausted, exits like a normal completion; the parent still gets the failed
   reply and the session file stays. Only a run the user stopped never exits
   the delegate.
+- A coordinator cannot exit until its child tasks finish and their outcomes
+  are processed in a subsequently settled run. An intermediate failure sends
+  no final task reply and keeps it available for child results.
 - 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
@@ -733,7 +1404,8 @@ The parent resolves each delegation's auto-exit from the call
 - The footer shows that this is a delegate, its agent, and whether auto-exit
   is on: `👦 worker delegate · auto-exit on`, or
   `👦 worker delegate · auto-exit off`, with 👦 or 👧
-  picked at random per session.
+  picked at random per session. Its status key is `delegate-self`; its own
+  running-child count uses `delegate`, so the footers do not overwrite each other.
 
 There is no `subagent_done` tool: auto-exit off only means the window stays.
 
@@ -784,10 +1456,12 @@ Delegate session: <session file or id>
     5 non-blank lines with heading marks, backticks and bold stripped;
     expanded (Ctrl+O), it shows the result as Markdown, the quoted task, then
     the ids and files, with the home directory shown as `~`.
-- Stopping a delegate's run (Esc) sends no result: the provider holds the
+- Stopping a delegate's run (Esc) sends no result: pi-squire 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.
+  run that completes successfully sends the result, `done`, and its body opens
+  with a note that the user took over partway. Failed runs in between do not
+  answer a held task. Asks are different: the mail provider still owns their
+  replies, including `stopped` replies, and does not hold them.
 - A `failed` reply from a delegate that recorded a usage-limit mark (see
   [Usage limits](#usage-limits)) gets one more line right after `Status:`,
   for example `Usage limit: the delegate hit a usage limit on provider
@@ -818,15 +1492,26 @@ Delegate session: <session file or id>
   current tool calls, before the next model call. A follow-up would wait
   until the parent had answered, by which time it had often read the
   envelope itself, and the late result cost a second, redundant turn.
-- The footer counts the running delegations (`👨 N delegates running`, with 👨 or 👩
-  picked at random per session), clears one entry per result or close and
-  hides itself at zero.
+- The [direct-delegate overview](#direct-delegate-overview) replaces Squire’s
+  running-count entry in interactive Pi. With its cap set to zero, or in a
+  non-TUI host, the footer counts running delegations (`👨 N delegates running`,
+  with 👨 or 👩 picked at random per session), clears one entry per result or
+  close and hides itself at zero. The own-delegate badge stays separate.
 - 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.
+  once for ordinary transport retries. Unprocessed coordinator outcomes may
+  be replayed on reopening. A root retains outcomes until processing too: an
+  already-displayed result wakes a recovery turn without displaying the final
+  result again, and pending content is supplied to the next model request.
+  An explicit root user stop is persisted: reopening does not start that work
+  again automatically. Previously held outcomes wait for a later input or a
+  genuinely fresh outcome. New live results still steer/start a turn, and new
+  gone outcomes keep their normal wake delivery; they clear the held replay
+  state. Coordinator held-task semantics stay unchanged.
+- Plain replies, and requests not taken over as this delegate's task, are left
+  to the provider. Squire never answers those ordinary requests.
 
 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
@@ -838,7 +1523,8 @@ 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
-`followUp` with `triggerTurn`. A tick declares nothing when nobody answers
+`followUp` with `triggerTurn` (a coordinator uses `steer` to process the missing
+outcome before its final report). 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.
@@ -855,6 +1541,13 @@ absolute path opens that file directly.
 
 ## Resuming a delegation
 
+**Breaking resume change:** delegations recorded without the required
+original-root placement identity cannot be resumed after this update. This
+includes pre-nesting and identity-less records, even when their original root
+reopens them. The tool, command and picker refuse before trust resolution, mail,
+killing an exited window, reserving a launch or spawning a new window. There is
+no legacy identity synthesis or migration.
+
 An exited delegate can continue its own session with a follow-up task:
 
 ```text
@@ -890,16 +1583,20 @@ and it resumes as the command does.
   opened would reach the next resume as a second task. The reopened delegate
   receives it once its mailbox starts. If the send fails, the new window is
   killed and nothing is recorded.
-- A chain resumes from its newest delegation; resuming an older one is refused,
-  naming the newest.
+- Only its direct parent may resume it, preserving the original root/depth.
+  The current parent grant, depth/cap/tool-ceiling/trust checks are reapplied.
+  A chain resumes from its newest local/shared delegation; older records and
+  copied fork/clone history are refused, naming the owner or newest record.
 - It is refused, before anything is sent or opened, unless: the delegation is a
   started one (not a workspace attempt); it is not `running` (mail a running
   delegate instead) and tmux can be asked; no window with its id and name still
   runs a program (an exited one is killed first; a window that merely shares the
   name is ignored); its session file is found and the working directory in the
-  file's header still exists; its agent is still in the roster; and no other
+  file's header still exists; its agent is still in the roster and not disabled
+  (a disabled agent's refusal names its file and the reason); and no other
   resume of it is under way. A delegate whose window was killed mid-turn can be
-  resumed.
+  resumed after a completed close; an unresolved active subtree close refuses
+  resume until positively resolved by an explicit retry.
 - A removed working directory, a removed managed worktree included, makes a
   delegation not resumable: Pi runs a reopened session in its stored directory.
   The window opens in that directory, with project trust decided again for it as
@@ -908,9 +1605,17 @@ and it resumes as the command does.
 - Without `model` it continues on the model the delegate finished on, moving to
   its agent's fallbacks when that one is unavailable or marked (see
   [Usage limits](#usage-limits)). An explicit `model` is used alone and refused
-  rather than substituted. `thinking` and `auto_exit` default to the
-  delegation's own. The agent's prompt, tools and extensions are those of the
-  roster now.
+  rather than substituted. Without `thinking` it continues on the level the
+  delegate last ran on: the last thinking-level change on its session's
+  active branch (Pi records one at start, one per change, and one when a
+  model change clamps the level), or the delegation's recorded level when
+  the session has none. `auto_exit` defaults to the delegation's own. A
+  field the agent locks is the exception: it runs on the
+  agent file's current `model` (then its fallbacks, even when the delegate had
+  moved to a fallback) or `thinking`, a value passed for it is not used, with
+  a notice, and passing the file's own value is the same as passing nothing. The agent's prompt and tools are those of the
+  roster now, and an agent without a `tools` field gets the parent's tools as
+  they are at the resume.
 - `session:launch` is emitted as for any launch, with the same payload.
 - Not detected: a Pi process you opened yourself on the same session outside
   pi-squire's window. Close it before resuming.
@@ -925,7 +1630,8 @@ that block.
 
 ### `session:launch`
 
-`pi-squire` provides this hook. It emits `{ args, env, agent, cwd, toolCallId }`
+`pi-squire` provides this hook. It emits
+`{ args, env, agent, cwd, toolCallId, parent, root, depth, chain }`
 just before it opens the delegate's window: for a launch, after the task has
 been sent; for a resume, before it is sent, since a resume mails the task once
 the window is open (see [Resuming a delegation](#resuming-a-delegation)).
@@ -934,13 +1640,28 @@ the window is open (see [Resuming a delegation](#resuming-a-delegation)).
 | --- | --- |
 | `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>/squire/agents/<name>/AGENT.md`; read it, do not change it |
+| `agent` | the agent's name, as in `<agent dir>/agents/<name>.md` or `<cwd>/.pi/agents/<name>.md` (never its `display_name`); read it, do not change it |
 | `cwd` | the directory the window opens in, the parent's or the resolved `--cwd`; read it, do not change it |
 | `toolCallId` | the ID of the `delegate` or `delegation_resume` tool call that started the launch; absent when started from the `/delegate` or `/delegate-resume` command; read it, do not change it |
+| `parent` | Read-only direct parent session id. |
+| `root` | Read-only root session id; retained on resume. |
+| `depth` | Read-only numeric child depth, root = 0; retained on resume. |
+| `chain` | Read-only frozen array of roster agent names ordered root downward, including the current child last; no session ids. |
 
 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.
+and top-level launches pass both to tmux unchanged. For nested launches and
+resumes, after all listeners return, pi-squire resolves the final tool selection
+and appends an authoritative exact-name `--tools` registration allowlist bounded
+by the direct parent. This limits which tool names the child can register and
+reach, including names provided by hook-added extensions, late registrations
+and MCP. It does not
+limit extension code or implementations registered under allowed names;
+unrelated arguments/environment keys survive. For nested launches and resumes,
+final customized arguments that Pi cannot parse refuse the launch before the
+window opens.
+An empty final set also receives `--no-tools` and an empty allowlist so earlier
+selection flags cannot restore tools. Do all work synchronously: the emitter
+reads the payload the moment `emit` returns.
 
 `cwd`, the trust flag (`--approve` or `--no-approve`), `--session-dir` and the
 session choice (`--session-id` for a new delegate, `--session` for a [resumed](#resuming-a-delegation)
@@ -957,6 +1678,121 @@ pi.events.on("session:launch", (payload) => {
   payload.args.push("--auto");
   payload.env.GATE_MODE = "auto";
   payload.env.GATE_ROOT = payload.cwd;
+  payload.env.GATE_CHAIN = payload.chain.join(",");
+  payload.env.GATE_PARENT = payload.parent;
+  assert.equal(payload.chain.at(-1), payload.agent);
+  assert.ok(Number.isSafeInteger(payload.depth));
+  assert.ok(Object.isFrozen(payload.chain));
+});
+```
+
+### `squire:identity`
+
+`pi-squire` emits this synchronous, read-only notification from its identity
+restore handler in `session_start`, before its later asynchronous startup work.
+The payload is `{ sessionId, status, identity? }` for the active exact session id:
+
+- `status: "delegate"`: its saved identity passed Squire's validation and was
+  successfully persisted again. `identity` contains only
+  `{ parent, root, agent, chain, depth }`, with the same meanings as
+  `session:launch`.
+- `status: "root"`: no identity record exists for that exact id. This is absence
+  of Squire delegate identity, not proof that the session is an original root.
+- `status: "invalid"`: reading, validating or persisting its identity failed.
+  No prior identity or raw error is included; Squire's existing restore error
+  and launch/completion refusal remain in effect.
+
+The payload, identity projection and copied `chain` array are frozen. Internal
+placement and auto-exit state are not exposed. Environment variables, display
+labels and copied transcript entries are not identity authority.
+
+Pi 1.3 and 1.4 recreate the extension runtime and dispatch `session_start`
+after new, fork/clone and session switch/import; reload also dispatches it.
+Each restore reads only the destination's exact id, so a new/forked session
+without its own record reports `root`, not the source's delegate identity.
+This event does not adopt sessions or migrate records.
+
+Register listeners before Squire loads and do all observation synchronously.
+The bus does not replay notifications, await asynchronous listeners, acknowledge
+listener success or veto later startup; listener exceptions are reported by Pi.
+Consumers own resetting their state at session shutdown/replacement, matching
+`sessionId` to their current context, and handling missing or invalid
+notifications. A consumer that must initialize before another extension's
+`session_start` must load its listener before Squire, and Squire before that
+extension. This is an observation seam, not an authorization gate or a provider
+integration.
+
+```js squire:identity
+pi.events.on("squire:identity", (snapshot) => {
+  assert.ok(Object.isFrozen(snapshot));
+  assert.equal(typeof snapshot.sessionId, "string");
+  assert.ok(["root", "delegate", "invalid"].includes(snapshot.status));
+  if (snapshot.status === "delegate") {
+    assert.ok(Object.isFrozen(snapshot.identity));
+    assert.ok(Object.isFrozen(snapshot.identity.chain));
+    assert.equal(typeof snapshot.identity.root, "string");
+    assert.equal("rootPlacement" in snapshot.identity, false);
+  } else {
+    assert.equal("identity" in snapshot, false);
+  }
+});
+```
+
+### Process-local completion holds (v1)
+
+Squire composes external work with its existing completion predicate through a
+provider-neutral data table at `globalThis[Symbol.for("pi.completion-holds.v1")]`:
+
+```ts
+{
+  version: 1,
+  hosts: Map<sessionId, Map<hostName, runtimeToken>>,
+  holds: Map<sessionId, Map<holdId, { provider: string, ready: boolean }>>
+}
+```
+
+An active Squire runtime registers `"pi-squire"` with a fresh string runtime token
+only during its exact session's `session_start`, after process ownership is
+acquired. A losing duplicate does not advertise support. Every
+`session_shutdown`, including reload, removes only that runtime's matching host
+token. Stale shutdown cannot remove a replacement's registration.
+
+Providers must check for a well-formed, nonempty host map for the current exact
+session before promising a hold. Register a unique hold id with `ready:false`
+atomically before launching the work; refund only that provisional entry if
+launch fails. Keep accepted entries across reload, including while the provider
+is unavailable. Set `ready:true` only after the terminal result has been observed
+and successfully processed; the provider owns that decision and its normal-run
+commit, before Squire reads readiness at `agent_settled`. Squire neither observes
+external output nor decides whether an operation succeeded.
+
+All current-session holds must be well formed and ready before Squire sends a
+new final task reply, marks its tree entry finished, or auto-exits. An absent
+table or no holds preserves normal completion. A malformed table/version or
+malformed current-session host/hold entry blocks completion; Squire does not
+overwrite it to repair storage. Other sessions' holds do not block this session.
+An absent host does not invalidate already-ready entries; it refuses promises
+of new holds. Providers clear only their own holds at non-reload teardown;
+Squire never removes provider entries.
+
+This is trusted in-process extension data, not a model-callable release API,
+cross-process registry, durable reopen block, or authorization boundary. There
+are no callbacks in the table, fake child tasks, polling/continuation loops, or
+automatic model calls to keep a session alive. Ordinary shutdown cancels the
+provider's work; reopening does not recover these holds. Already-frozen reply
+outboxes retain their existing retry semantics.
+
+This executable observer loads after Squire and checks only the host contract:
+
+```js completion-holds:v1
+pi.on("session_start", (_event, ctx) => {
+  const table = globalThis[Symbol.for("pi.completion-holds.v1")];
+  assert.equal(table.version, 1);
+  assert.ok(table.hosts instanceof Map);
+  assert.ok(table.holds instanceof Map);
+  const hosts = table.hosts.get(ctx.sessionManager.getSessionId());
+  assert.ok(hosts instanceof Map);
+  assert.equal(typeof hosts.get("pi-squire"), "string");
 });
 ```
 
@@ -969,6 +1805,66 @@ 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:reply`
+
+After the final run settles (including fallback continuations and the durable
+child-first processing barrier), squire emits
+`{ to, inReplyTo, body, status }`: the direct parent's address, the owed request
+ids in batches of at most 50, the exact result text, and `done` or `failed`.
+The provider must synchronously set `envelope` or `error`; neither means no
+provider. Squire keeps the task owed until the write succeeds and completion
+is recorded. The provider's README owns the transport contract.
+
+Task ownership and a frozen final-answer outbox live in
+`<agent dir>/squire/task-replies/<session id>.json`, independently of Pi's
+buffered transcript. Atomic file replacement preserves pending answers over
+reload, restart, squire resume and manual reopening of the same session with
+the same agent directory. Identity and auto-exit state live separately in
+`<agent dir>/squire/identity/<encoded session id>.json`; manual reopening
+restores parent/root/depth/agent/chain, the original `rootPlacement` companion
+preference and the saved auto-exit setting. This internal placement scalar adds
+no launch environment variable or `session:launch` field. The
+launch-time remaining fallback list is not restored by a manual reopen;
+squire resume still supplies its current fallback candidates.
+
+Direct-child facts and pending result/gone outcomes live in
+`<agent dir>/squire/child-tasks/<encoded parent session id>.json`, independently
+of transcript buffering. Starts and terminal outcomes are saved locally before
+result injection. Restoring these facts precedes Squire task handling. If mail
+claims before that restoration (including delayed startup or a duplicate
+process), matching Squire input is staged durably for the sole owner.
+Each model request includes pending outcomes; only those observed by a request
+and followed by a non-stopped settlement are acknowledged. The task reply gate
+requires no unfinished children and no unprocessed outcomes. Storage failures, including incomplete transcript/child-identity restoration,
+block final completion/auto-exit and new launch/resume admission in roots and
+coordinators. Read-only admission checks the restored store health; a write
+preflight persists unchanged task facts before mail, windows, worktree creation
+or killing an exited resume window. Repair unhealthy storage and reload before
+launching again. An incomplete-restore latch also refuses incidental saves, so
+partial in-memory records cannot replace known pending obligations. These local
+task records remain the result-processing authority;
+the shared [tree registry](#tree-wide-launch-budgets) indexes their durable
+lifecycle facts without copying task bodies or processing outcomes.
+
+A failed write produces a visible `delegate: could not handle the task reply`
+error and blocks auto-exit. A frozen answer is retried on the next settled
+run, or on reload/reopen (starting on the next event-loop turn); the next
+run's text does not replace that answer. An async startup handler between
+squire and mail can delay provider initialization past that turn, so a failed
+startup attempt gets two additional reply attempts, 100 ms apart, on an
+unref'd timer. After those attempts, any failure is visible and no ongoing
+retry timer remains. Fix the provider or storage error and reload/reopen to
+retry without a model call. A successful startup retry does not itself close
+the window.
+
+Mail does not deduplicate replies. A crash after the envelope write but before
+completion recording can cause squire to resend the saved outbox. This is
+at-least-once transport, not atomic exactly-once delivery. The parent matches
+every correlated task id, records each as answered, and suppresses further
+final results for those ids even when a retry has a new envelope id. One
+envelope answering several owed tasks is shown once, using its last pending
+delegation for the displayed task quote.
+
 ### `message:inbound`
 
 `pi-squire` consumes this hook for answers: a reply whose `in_reply_to` names a
@@ -981,8 +1877,10 @@ 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.
-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
+Squire durably records its parent and request id before starting the task;
+it owns the answer through `message:reply`. The provider arms no automatic
+request answer. 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.
@@ -1008,7 +1906,12 @@ contract.
 
 ## Testing limits
 
-The automated tests drive the extension through a fake Pi session. They check
+The automated tests drive the extension through fake Pi lifecycles. The
+reusable `test/mail-harness.ts` runs multiple independent extension instances
+with the real, exactly pinned pi-session-mail 0.6.0 over an isolated shared
+mail root. Protocol tests cover correlation, asks, stops, fallback, pending
+answers, retries and duplicate delivery after the write/completion crash
+window. These are not real model runs or real process-crash tests. 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
@@ -1031,12 +1934,13 @@ version and is listed under "Breaking" in [CHANGELOG.md](CHANGELOG.md).
 
 Other extensions may rely on:
 
-- the `session:launch` payload `{ args, env, agent, cwd, toolCallId }`, emitted
+- the `session:launch` payload
+  `{ args, env, agent, cwd, toolCallId, parent, root, depth, chain }`, emitted
   synchronously before the window opens (after the task is sent for a launch,
   before it is sent for a resume), with
   `cwd`, the trust flag and `--session-dir` chosen by `pi-squire` (see
   [Hooks](#hooks));
-- the `message:send`, `message:inbound` and `message:scan` hooks, consumed as
+- the `message:send`, `message:reply`, `message:inbound` and `message:scan` hooks, consumed as
   their sections document;
 - the `delegate`, `delegation_status`, `delegation_close` and `delegation_resume` tool names,
   parameters, the recorded `workspace` shape and the `workspaceSnapshot`
@@ -1047,21 +1951,27 @@ Other extensions may rely on:
 - the `/delegates` command and its `alt+shift+d` shortcut, and `/delegate-open <id>` with its
   `--switch` and `--peek` flags;
 - the `[delegate]` result text and the closed-without-a-result text;
-- `AGENT.md`'s frontmatter keys and its location,
-  `<agent dir>/squire/agents/<name>/AGENT.md`;
+- the agent file's frontmatter keys and its locations,
+  `<agent dir>/agents/<name>.md` and, in a trusted project,
+  `<cwd>/.pi/agents/<name>.md`;
+- the `maxDepth`, `maxConcurrentDelegates`, `maxDelegatesPerRoot`, `delegateTools`,
+  `windowPlacement`, `worktreeRoot`, `delegateWidgetPlacement` and
+  `delegateWidgetMaxEntries` settings in
+  `<agent dir>/squire/settings.json`;
 - 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`.
+- the child environment variables `PI_DELEGATE_PARENT`, `PI_DELEGATE_ROOT`,
+  `PI_DELEGATE_DEPTH`, `PI_DELEGATE_AGENT`, `PI_DELEGATE_CHAIN`,
+  `PI_DELEGATE_AUTO_EXIT`, `PI_DELEGATE_FALLBACK` and `PI_UNATTENDED=1`.
 
 A `message:*` provider must:
 
-- implement `message:send`, `message:inbound` and `message:scan` as documented
-  under [Hooks](#hooks);
+- implement `message:send`, `message:reply`, `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.
+- write explicit request replies through `message:reply`, without automatically
+  answering requests at settle; asks remain separately owned by the provider.
 
 ## Contributing