@kushalkhemka/opensec-pi-subagents 0.20.1 → 0.20.3

package/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.3] - 2026-10-16
+
+Background agents survive a session switch, subagents run on the parent's model by default, and nested and workflow
+agents stay resumable after a restart. Also ports upstream `@tintinweb/pi-subagents` 0.20.0, 0.21.0 and 0.22.0
+(package-shipped agents and MCP for subagents are not ported).
+
+> **Possibly breaking:**
+> - **Subagents run on the parent's model and thinking level by default**; the `Agent` and nested tools no longer offer
+>   `model`/`thinking` unless `allowModelOverride` is on.
+> - **Background agents keep running across `/new`, `/resume`, `/fork` and `/reload`** when their session is saved.
+> - **Pi 1.1.0 or newer is required** (peer range `>=1.1.0`).
+> - **Background completions are delivered at the parent's next boundary.** `smart`, the default join mode, no longer
+>   combines a turn's agents into one notification after waiting for all of them; `group` does that, per parent turn.
+>   A completion pending when you press `Esc` now starts a turn once the interrupted turn stops.
+> - **An agent file's `isolated:` and `isolation:` win on every spawn path**, including RPC callers that pass their own
+>   value, and an `isolation: worktree` agent fails to start outside a git repository instead of running in place.
+
+### Added
+
+- **Background agents keep running across a session switch.** `/new`, `/resume`, `/fork` and `/reload` no longer stop them when their session is saved: the next session takes over the running agents. An agent belongs to the session that started it: other sessions do not list or address it, and a result that lands while another session is open is written into its own session and delivered as the usual notification when you return there. Quitting still stops every agent and saves worktrees.
+- **`ctrl+b` sends running foreground `Agent` calls to the background**, as in Claude Code; `b` in the conversation
+  viewer sends one ([tintinweb/pi-subagents#261](https://github.com/tintinweb/pi-subagents/pull/261)). The run keeps
+  going and its result arrives as a background notification. The key is configurable as `backgroundKey` in
+  `subagents.json` (`"off"` disables it).
+- **Fullscreen conversation observer** ([tintinweb/pi-subagents#357](https://github.com/tintinweb/pi-subagents/pull/357)):
+  in Pi's fullscreen mode an agent opened from FleetView, `/agents` or the workflow inspector fills the terminal, with
+  mouse-wheel scrolling, a draggable scrollbar following Pi's `fullscreenScrollbar`, clickable footer controls and a
+  `Ctrl+End` jump-to-latest marker that counts new messages. Built on this fork's incremental viewer: without a JIT, a
+  frame takes about 20 µs and a scroll step about 50 µs at 500 messages, whatever the transcript's length.
+- **Subagents load Pi's built-in codemode and tool search** (`builtin:codemode`, `builtin:tool-search`) as the main
+  session does ([tintinweb/pi-subagents#386](https://github.com/tintinweb/pi-subagents/pull/386)). Pi's built-in MCP
+  stays off for subagents, so no child starts its own `mcp.json` servers, unless an agent file names `builtin:mcp` in
+  `extensions:`.
+
+### Changed
+
+- **Subagents run on your model and thinking level.** By default every subagent runs on the parent's current model at the parent's current thinking level, on every spawn path: the `Agent` tool, nested delegation, workflow `agent()`, `@mentions`, scheduled jobs and cross-extension RPC. Per-call choices are ignored, and the `Agent` and nested tools no longer offer `model` or `thinking`, so the main model cannot pick cheaper models or lower effort on its own. An agent file's `model:` or `thinking:` still applies, and a resumed agent keeps what it ran with. The new `allowModelOverride` setting (`subagents.json` or `/agents → Settings → Model override`) restores the per-call overrides and the tool parameters.
+- **Background completions reach a busy parent before its next model call**, after its current tool batch, through
+  Pi's steering queue instead of a follow-up held until the parent stopped
+  ([tintinweb/pi-subagents#387](https://github.com/tintinweb/pi-subagents/pull/387)). Completions that finish together
+  arrive as one message and none waits for its siblings (`async` now means `smart`); an idle parent gets a turn about
+  200 ms after a completion; `group` batches by parent turn; `get_subagent_result` suppresses a notification any time
+  before it is sent ([tintinweb/pi-subagents#388](https://github.com/tintinweb/pi-subagents/pull/388)). Results that
+  land while another session is open, or that are still waiting when you switch away, are delivered the same way when
+  you return to their session.
+- **An agent file's `isolated:` and `isolation:` hold on every spawn path**: direct and fallback `@handle` mentions,
+  cross-extension RPC and registry spawns. A caller's value applies only when the file leaves the field unset; the
+  widget's `worktree` tag shows for every worktree agent. Workflow `agent()` calls keep Claude Code's rule (only the
+  script's `isolation` decides), and an agent reopened from its session file keeps its placement (upstream 0.21.0).
+- **Subagent tool scoping follows Pi's tool exposure**: only `direct`/`model-only` tools are activated, and
+  `defaultActive: false` tools only when named; `codemode`/`deferred` tools stay undeclared until codemode or
+  `tool_search` reaches them (upstream 0.21.0).
+- Pi peer floor `>=1.1.0`; `typebox` is a `"*"` peer and `@sinclair/typebox` is no longer declared
+  ([tintinweb/pi-subagents#384](https://github.com/tintinweb/pi-subagents/pull/384)).
+- The conversation viewer's regular mode reuses cached widths and chrome rows: without a JIT a frame costs about
+  20 µs instead of about 2 ms.
+
+### Fixed
+
+- **Nested agents and workflow children stay resumable after a restart**, `/resume`, `/fork` or `/reload`: their resume state is recorded in the parent session (`subagents:resume` entries), so a nested agent can be resumed by its owner and a workflow child with `agent({ resume })`. `resumeFromRunId` finds a run of the same session after a restart, and a child replayed from the journal can still be continued: the journal records which agent produced each answer.
+- `SubagentWorkflow` honours an agent file's `isolated: true`
+  ([tintinweb/pi-subagents#339](https://github.com/tintinweb/pi-subagents/pull/339)).
+- FleetView ends with a blank line above Pi's footer
+  ([tintinweb/pi-subagents#351](https://github.com/tintinweb/pi-subagents/issues/351)), and its arrow keys work under
+  any prompt editor that implements `getText`/`setText`
+  ([tintinweb/pi-subagents#374](https://github.com/tintinweb/pi-subagents/issues/374)).
+- The workflow stand-down recognises a lowercase `workflow` tool
+  ([tintinweb/pi-subagents#283](https://github.com/tintinweb/pi-subagents/issues/283)).
+
+## [0.20.2] - 2026-10-16
+
+### Changed
+
+- **Every project is trusted again by default**, as before 0.20.1: subagents load a project's `.pi` extensions and settings, and the extension uses its agents, skills, workflows and `subagents.json`, whatever Pi decided for the folder. To follow Pi's project trust decision instead (0.20.1's behaviour), set `"projectTrust": "pi"` in the global `~/.pi/agent/subagents.json`.
+
 ## [0.20.1] - 2026-10-16
 
 ### Fixed

package/README.md

@@ -32,8 +32,8 @@ Restart Pi or run `/reload` after installing. Update with `pi update --extension
 
 ### Requirements
 
-- Pi: this Node build loads and runs a real turn on Pi 0.87.1 and Pi 1.0.0 (both on Node). The peer-dependency
-  range is `>=0.84.0`; earlier versions were not re-tested.
+- Pi 1.1.0 or newer (peer range `>=1.1.0`, the test suite runs against Pi 1.1.0). `typebox` is a `"*"` peer that Pi
+  supplies; `@sinclair/typebox` is no longer used.
 - Install only one Subagents package at a time: the public and private packages expose the same tools.
 
 ## Features
@@ -72,6 +72,61 @@ Agent({ subagent_type: "Explore", prompt: "Find authentication code", descriptio
 | `/agents` | Inspect and manage agents: live conversations, settings, workflows, and scheduled jobs (`/agents → Scheduled jobs`). |
 | `@<agent> <message>` | With agent mentions enabled, sends a message to that agent, e.g. `@explore check the RPC path`. A finished agent is resumed (see [Resuming agents](#resuming-agents)). |
 
+### Background completions
+
+When a background agent (or workflow) finishes, the main session is notified, as in Claude Code:
+
+- A busy parent gets the notification after its current batch of tool calls, before its next model call; running tools
+  are not interrupted. Everything that finished during that batch arrives as one message.
+- An idle parent gets a turn about 200 ms after a completion, together with anything else that finished in that window.
+- If you interrupt the parent (`Esc`), what was waiting is kept and delivered once the interrupted turn has stopped,
+  starting a turn.
+- Reading a result with `get_subagent_result` (or the RPC `consume`) before the notification is sent suppresses it.
+- A result that lands while another session is open, or that is still waiting for its parent's boundary when you switch
+  away, is recorded in its own session and delivered the same way when you return there (see
+  [Switching sessions](#switching-sessions)).
+
+The join mode (`/agents → Settings → Join mode`, `defaultJoinMode`) decides whether a result waits for its siblings:
+
+| Mode | Behaviour |
+|---|---|
+| `smart` (default) | No waiting: each result is delivered at the parent's next boundary. `async` is accepted as an older name for it. |
+| `group` | The background agents spawned in one parent turn report together, in one notification once all of them have finished (a lone spawn reports alone). A 30 s timeout after the first completion sends a partial notification; stragglers follow within 15 s. |
+
+### Sending a foreground agent to the background
+
+While a foreground `Agent` call runs (`run_in_background: false`), press `ctrl+b` at the prompt to hand it to the
+background, as in Claude Code. The same run keeps going (session, in-flight turn, transcript and worktree); the blocked
+call returns what a `run_in_background` spawn returns, and the result arrives later as the usual background
+notification. `ctrl+b` hands off every running foreground call at once; a dim `(ctrl+b to run in background)` hint
+appears under one of them after 2 s. In the conversation viewer (FleetView, `/agents`), `b` hands off just that agent.
+
+- The key is claimed only while a foreground call runs and the prompt editor has focus; otherwise `ctrl+b` keeps its
+  editor meaning (cursor left). Rebind it with `"backgroundKey"` in `subagents.json` (a Pi key id such as `alt+b`), or
+  turn it off with `"backgroundKey": "off"`.
+- After the handoff, `Esc` on the parent turn no longer stops the agent; `x` in the viewer and `/agents` still do. The
+  run moves from the foreground to the background concurrency pool, over the limit if the pool is full.
+- Nested agents, workflow agents, queued spawns and resumed runs cannot be handed off.
+
+### Fullscreen conversation observer
+
+In Pi's fullscreen mode (`/settings → TUI mode → fullscreen`, Pi's default), an agent opened from FleetView, `/agents`
+or the workflow inspector fills the terminal; regular mode keeps the floating viewer. Neither replaces the main session
+or pauses an agent, and `Esc` returns to the previous view (while composing, the first `Esc` cancels the draft).
+
+- Mouse-wheel scrolling. Scrolling up pauses following; reaching the bottom resumes it.
+- A one-column scrollbar in Pi's style that follows Pi's `/settings → Fullscreen scrollbar`: `auto` appears while
+  scrolling or hovering and hides after a second, `always` stays, `hidden` removes it and its mouse target. Drag the
+  thumb, or click the track to page. The column is kept free in `auto` mode too, so the bar never re-wraps the text.
+- Clickable footer controls (steer, send to background, stop with two clicks, Markdown mode, close).
+- While scrolled away, the divider above the footer shows `[ ↓ N new messages · Ctrl+End ]` (conversation messages,
+  not streaming updates); click it or press `Ctrl+End` to jump back and follow, without losing a steering draft.
+- Mouse events are consumed, so they never scroll, select or click the main view underneath. Text selection, copying
+  and switching agents without leaving the observer are not implemented.
+- Cost: built on the viewer's incremental transcript, so scrolling, wheel and drags reuse cached lines, a frame checks
+  only the transcript's last message and draws only the visible rows, and nothing ticks while it is idle. Without a JIT
+  (Pi-Bolt), a frame or a scroll step costs well under a millisecond whatever the transcript's length.
+
 ### Resuming agents
 
 Every agent result names the agent: `Agent ID: <id>` (foreground and background results alike). Pass it back to continue
@@ -92,31 +147,97 @@ Agent({ resume: "<id>", prompt: "Now check the tests too", description: "Continu
   file, under the same id, for as long as that file exists. Sessions are saved by default (`rememberAgents`; turn it
   off and agents are resumable only for those ten minutes).
 - What survives a restart, `/resume`, `/fork` or `/reload`: finished agents of that session (on its branch, for a fork)
-  stay resumable by the model and by `@handle`. Agents still running are stopped, as before, and recorded as stopped
-  and resumable. `/new` starts with none. Nested agents can be resumed by their parent while their parent's manager
-  lives; across a restart only top-level agents are rebuilt.
+  stay resumable by the model and by `@handle`. `/new` starts with none. Nested agents and workflow children are
+  rebuilt too (their resume state is written to the parent session as `subagents:resume` entries, one small entry per
+  settled child): a nested agent stays resumable by the agent that owns it, once that agent is resumed under its id.
 - In workflows, `agent(prompt, { resume: label })` continues a child of the same run the same way, also after its record
-  was evicted.
+  was evicted. `resumeFromRunId` finds a run of the same session after a restart or `/resume` by its files, and a child
+  it replays from the journal can still be continued with `agent({ resume })`: the journal records which agent
+  produced each answer.
+
+### Switching sessions
+
+Background agents keep running when you switch sessions with `/new`, `/resume`, `/fork` or `/reload`, as long as the
+session that started them is saved (it has a session file).
+
+- An agent belongs to the session that started it. While another session is open it does not show in that session's
+  widget, FleetView, `/agents` lists or `@` suggestions, and `get_subagent_result`, `steer_subagent` and `resume` there
+  do not find it. It still counts toward the background concurrency limit.
+- If it finishes while another session is open, its result is written into its own session (a `subagents:record`
+  entry marked `pending`) and nothing is sent to the open session. When you return to its session the result arrives as
+  the usual completion notification, and the main agent takes a turn on it. The same happens after a restart if the
+  result was recorded but not yet delivered.
+- Its nested agents keep running with it. Foreground agents (Pi interrupts their tool call; send one to the background
+  with `ctrl+b` first to keep it), workflows, `@mention` prompts in flight and agents of a session kept only in memory
+  stop at a switch, as before, and are recorded as stopped.
+- Quitting (`/quit`, Ctrl+D, SIGTERM, SIGHUP) stops every agent and saves worktrees, as before. If Pi exits while a
+  switch is still in progress, the agents are recorded as stopped; their worktrees are recovered at the next start.
+- After updating this package, the first `/reload` (or switch) loads the new version, which cannot take over the old
+  version's running agents: they are stopped and recorded as stopped and resumable.
+
+### Model and thinking level
+
+A subagent runs on the parent's current model at the parent's current thinking level, on every spawn path: the `Agent`
+tool, nested delegation, workflow `agent()`, `@mentions`, scheduled jobs and cross-extension RPC. For a nested agent the
+parent is the agent that spawned it.
+
+- An agent file's own `model:` or `thinking:` is your configuration and always applies.
+- Per-call choices are ignored by default: the `Agent` tool and the nested tool do not offer `model` or `thinking`,
+  workflow `agent({ model, effort })` is ignored, and so are a scheduled job's and an RPC spawn's model and thinking
+  level. This keeps the main model from picking cheaper models or lower effort on its own.
+- A resumed agent keeps the model and thinking level it ran with.
+- `allowModelOverride: true` (project or global `subagents.json`, or `/agents → Settings → Model override`) restores the
+  per-call overrides and the tool parameters. The resolution changes at once; the tool parameters at the next session.
 
 ### Custom agents
 
 Put custom definitions in `.pi/agents/<name>.md` or the global Pi agents directory. Agents inherit the current parent's
-model and thinking level unless their definition or call overrides them.
+model and thinking level unless their definition sets one (see [Model and thinking level](#model-and-thinking-level)).
 
 `isolated: true` (on a call or in an agent file) removes extension and MCP tools, skills, `ext:` selectors and nested
 delegation. It is not a sandbox: the agent still inherits Pi's environment variables (including provider keys its
 `bash` can read), the parent's model registry and auth, global and trusted project settings (shell, command prefix,
 retry, compaction), and, for append-mode agents such as `general-purpose`, the parent's whole system prompt.
 
+The agent file wins over the caller for `isolated:` and `isolation:`; a call's value applies only when the file leaves
+the field unset. This holds on every spawn path: the `Agent` tool, `@handle` mentions (direct mode and the fallback
+when a mention clone fails), cross-extension RPC and the manager registry. So
+`isolation: off` in a file refuses a caller's `isolation: "worktree"`, and an `isolation: worktree` file gets its
+worktree even when the caller asked for none; outside a git repository such an agent fails to start instead of running
+in the main checkout. Two exceptions: in a workflow, only the script's `agent()` option decides `isolation` (as in Claude
+Code; `isolated:` from the file still applies), and an agent reopened from its session file continues where it ran
+(its `isolated:` is read from the file again).
+
 `tools:` limits built-in tools only. Tools registered by extensions stay available unless the file sets
 `extensions: false` (or names the extensions to load), or lists `ext:` selectors in `tools:`, which turns extension
 tools into an allowlist. The built-in `Explore` and `Plan` agents get `read`, `grep`, `find` and `ls` and no extension
 tools, so they cannot write files or run commands; a file named `Explore.md` or `Plan.md` replaces them if you want
 them to have more.
 
+Pi's built-in codemode and tool search (`builtin:codemode`, `builtin:tool-search`) load in subagents as in the main
+session: on with `extensions: true`, kept or dropped by `extensions:` and `exclude_extensions:` like any other
+extension (address them by the full `builtin:` name), and off for everyone with `-builtin:<name>` in Pi's `extensions`
+setting or `--no-extensions`. Pi's built-in MCP (`builtin:mcp`) is the exception: subagents do not load it, so no
+child starts its own set of `mcp.json` servers, unless the agent file names it, e.g. `extensions: ["*", builtin:mcp]`
+(`--no-mcp` still keeps it out). MCP tools are reached through codemode or `tool_search`, so an `ext:` allowlist must
+name that bridge too: `tools: "read, ext:builtin:codemode, ext:builtin:mcp/mcp__srv__search"`. A bare
+`mcp__<server>__<tool>` name in `tools:` is reported as an unknown built-in (`tools-error:`); name MCP tools with
+`ext:builtin:mcp/<tool>`.
+
+A subagent activates only the tools Pi itself would declare to the model: `direct` and `model-only` tools, minus those
+registered with `defaultActive: false` unless the agent names them (`ext:foo/bar`). `codemode` and `deferred` tools
+(Pi's MCP tools) stay undeclared until codemode or `tool_search` reaches them. Calls a tool makes through
+`ctx.executeTool()`, such as a codemode script calling another tool, go through the same scope check as the model's
+own calls; out-of-scope tools are blocked but can still appear in codemode's `searchTools()` and `tool_search` results.
+
 ### Project trust
 
-Subagents follow Pi's project trust decision for the parent session.
+By default (`projectTrust: "full"`) subagents and this extension trust every project: a child session loads the
+project's `.pi/extensions` and `.pi/settings.json`, and the extension uses the project's agents, skills, workflows and
+`subagents.json`, whatever Pi decided for the parent session.
+
+To have them follow Pi's project trust decision instead, set `"projectTrust": "pi"` in the global
+`~/.pi/agent/subagents.json` (a project's own file cannot change it). Then:
 
 - In a folder Pi does not trust, subagents load none of the project's `.pi/extensions`, `.pi/settings.json` (for
   example `shellCommandPrefix`), skills or prompts, exactly like the parent. This extension also ignores the project's
@@ -137,6 +258,8 @@ Subagents follow Pi's project trust decision for the parent session.
 | Setting | Default | Meaning |
 |---|---|---|
 | Background concurrency (`/agents → Settings`) | `10` | How many background agents run at once. |
+| `backgroundKey` (`subagents.json`) | `ctrl+b` | Key that sends running foreground `Agent` calls to the background (see [Sending a foreground agent to the background](#sending-a-foreground-agent-to-the-background)); `"off"` disables it. |
+| Model override (`/agents → Settings`, `allowModelOverride`) | `false` | Whether a spawn's own `model` / `thinking` (Agent tool, nested tool, workflow `agent()`, scheduled jobs, RPC) may choose the subagent's model and thinking level. Off: subagents run on the parent's current model and level unless their agent file sets one, and the tools do not offer the parameters. |
 | Tool timeout (`/agents → Settings`, `toolTimeoutSeconds`) | `1200` | Seconds one subagent tool call may run (`0` = no limit). A `bash` call is killed at the limit and the agent sees the timeout; any other tool still running a minute later is stopped and the agent is told to continue another way (up to 3 times per run). The main agent's `bash` calls get the same timeout when they set none; a timeout the main agent asks for is kept. |
 
 ## Notes

package/dist/agent-manager.d.ts

@@ -15,10 +15,13 @@
  */
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type ToolActivity } from "./agent-runner.js";
+import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import { getAgentConfig } from "./agent-types.js";
+import { sessionFileProblem } from "./session-file.js";
 import type { AgentInvocation, AgentRecord, AgentResumeState, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
 import { type LifetimeUsage } from "./usage.js";
 import type { CompiledSchema } from "./workflow/json-schema.js";
+import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, restoreWorktree } from "./worktree.js";
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
 export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
@@ -36,6 +39,38 @@ export type CompactionInfo = {
     reason: "manual" | "threshold" | "overflow";
     tokensBefore: number;
 };
+/** What the extension instance observes of the manager's agents. */
+export interface ManagerObservers {
+    onComplete?: OnAgentComplete;
+    onStart?: OnAgentStart;
+    onCompact?: OnAgentCompact;
+    onUsage?: OnAgentUsage;
+}
+/**
+ * The module functions the manager runs agents and worktrees with. Pi loads a
+ * fresh copy of this extension's modules for every session, and a manager kept
+ * across a session switch (session-handoff.ts) was built by an older copy: the
+ * adopting instance hands it its own, so new spawns see the current session's
+ * agent registry and settings. Runs already going keep the ones they started
+ * with. Unset, the manager uses its own module's imports.
+ */
+export interface ManagerServices {
+    runAgent: typeof runAgent;
+    resumeAgent: typeof resumeAgent;
+    createWorktree: typeof createWorktree;
+    cleanupWorktree: typeof cleanupWorktree;
+    restoreWorktree: typeof restoreWorktree;
+    isWorktreeIsolationEnabled: typeof isWorktreeIsolationEnabled;
+    pruneWorktrees: typeof pruneWorktrees;
+    sessionFileProblem: typeof sessionFileProblem;
+    /** The agent registry the current session loaded (an agent file's `isolation:`). */
+    getAgentConfig: typeof getAgentConfig;
+}
+/**
+ * This module's {@link ManagerServices}, for an instance adopting a manager
+ * built by another copy. Getters, so each import is read only when used.
+ */
+export declare function managerServices(): ManagerServices;
 /**
  * Whether a record is one of the session's own agents, rather than something
  * another agent or a workflow owns.
@@ -280,10 +315,19 @@ interface ResumeOptions {
  * or undefined when there is no session file to reopen.
  */
 export declare function resumeStateOf(record: AgentRecord): AgentResumeState | undefined;
+/** Session entry a top-level agent's final record goes into (with its resume state). */
+export declare const RECORD_ENTRY_TYPE = "subagents:record";
+/**
+ * Session entry an owned child's resume state goes into: a nested agent's or a
+ * workflow's. Kept apart from {@link RECORD_ENTRY_TYPE}, which other extensions
+ * read as the session's own agents, while an owned child reports only through
+ * its owner. Carries the resume state alone, so it stays small.
+ */
+export declare const RESUME_ENTRY_TYPE = "subagents:resume";
 /**
- * The resume states a session's `subagents:record` entries carry, oldest
- * first. Entries written before they carried one, or malformed ones, are
- * skipped: there is nothing to reopen them from.
+ * The resume states a session's `subagents:record` and `subagents:resume`
+ * entries carry, oldest first. Entries written before they carried one, or
+ * malformed ones, are skipped: there is nothing to reopen them from.
  */
 export declare function resumeStatesFromEntries(entries: readonly unknown[]): AgentResumeState[];
 export declare class AgentManager {
@@ -345,7 +389,41 @@ export declare class AgentManager {
     /** Pending releases, by record. */
     private releaseTimers;
     private sessionReleaseMs;
+    /** Set by an instance that adopted this manager; see {@link ManagerServices}. */
+    private services?;
+    /**
+     * The session whose agents the top-level surfaces show (`listAgents`,
+     * `resolveMention`, `hasRunning`, `waitForAll`). `null`: every agent — the
+     * default, and the only mode before a session has started.
+     */
+    private visibleOwner;
+    /**
+     * Arguments of spawns that have not reached `runAgent` yet (queued, or still
+     * creating their worktree), so a session switch can swap their context for a
+     * frozen copy before Pi invalidates it.
+     */
+    private pendingArgs;
     constructor(onComplete?: OnAgentComplete, maxConcurrent?: number, onStart?: OnAgentStart, onCompact?: OnAgentCompact, onUsage?: OnAgentUsage);
+    /** Replace what the extension observes of this manager's agents (an adopting instance, or parking). */
+    setObservers(observers: ManagerObservers): void;
+    /** Run new work with these module functions; see {@link ManagerServices}. */
+    useServices(services: ManagerServices): void;
+    private svc;
+    /**
+     * Show only the agents of this session (its file; undefined for one in
+     * memory) on the top-level surfaces, or every agent with `null`. Agents of
+     * other sessions keep running and are reachable by id internally — their
+     * nested tools, the workflow host — just not listed or addressable here.
+     */
+    setVisibleOwner(owner: string | undefined | null): void;
+    /** Whether the record belongs to the session the surfaces show. */
+    isVisible(record: Pick<AgentRecord, "ownerSession">): boolean;
+    /**
+     * Before a session switch: give every spawn that has not started its run yet
+     * a frozen copy of its context, since Pi invalidates the live one (every read
+     * throws) and the spawn reads it when it starts.
+     */
+    detachPendingContexts(): void;
     /** Update the max concurrent background agents limit. */
     setMaxConcurrent(n: number): void;
     getMaxConcurrent(): number;
@@ -438,12 +516,18 @@ export declare class AgentManager {
      * an aborted signal, so a `spawnAndWait` on it would wait forever — pi has no
      * tool-execution timeout to bail it out.
      *
-     * The listener is left in place when the agent starts. `startAgent` adds its
-     * own, so both fire on a later abort, but `abort()` on an already-stopped
-     * record is a no-op — so detaching would only be tidiness, and tidiness the
-     * `abortAll`/`dispose` paths could not offer anyway.
+     * The listener is removable (`record.detachParentAbort`): `startAgent`
+     * replaces it with its own, and `sendToBackground` must be able to take it
+     * off, or the caller that armed it could stop a run it no longer owns.
      */
     private armQueuedAbort;
+    /**
+     * Stop `record` when its caller's `signal` aborts, replacing any listener an
+     * earlier stage armed — at most one is live per record, so one call to
+     * `detachParentAbort` cuts the run loose from its caller.
+     */
+    private armParentAbort;
+    private detachParentAbort;
     /**
      * Kick off an agent's startup and register it under `startups`. The returned
      * promise never rejects — the failure is delivered through `awaitStartup`,
@@ -458,6 +542,7 @@ export declare class AgentManager {
      *   handle goes back.
      */
     private launch;
+    private dropPendingArgs;
     /**
      * Resolves once the agent is actually running, and rejects with the startup
      * failure (strict worktree isolation) that `spawn()` used to throw before the
@@ -506,6 +591,28 @@ export declare class AgentManager {
         id: string;
         record: AgentRecord;
     }>;
+    /**
+     * Hand a live run to the background without restarting it. The session,
+     * promise, in-flight turn, transcript and worktree all continue under the
+     * same id; what changes is who answers for it. The caller's parent-abort
+     * listener comes off (its Esc no longer reaches the run — `abort()` and
+     * `/agents` still do), the slot moves to the background pool, and the run
+     * then settles through the ordinary background path: `endRun` releases the
+     * run's live pool, and the settle reads the live `isBackground`, so the
+     * result is delivered as a background completion.
+     *
+     * Releasing the caller is the caller's job — the `Agent` tool races its own
+     * wake-up against `spawnAndWait`. This only refuses what it can see: a run
+     * nobody is blocking on (a background or detached spawn, one already handed
+     * off, or a foreground resume — `blocking` is cleared when the spawned run
+     * settles), one that reports through something other than the session (a
+     * nested child, a workflow's agent), and one that is stopped or queued.
+     *
+     * The background slot is taken even when the pool is full: suspending a
+     * live run is not an option, so it runs over the limit and queued
+     * background work waits for the count to drop, as with `bypassQueue`.
+     */
+    sendToBackground(id: string): boolean;
     /**
      * Resume an existing agent session with a new prompt.
      */
@@ -584,7 +691,10 @@ export declare class AgentManager {
     dropTombstone(idOrHandle: string): void;
     /** Evicted top-level agents whose conversation can still be reopened, newest first. */
     listTombstones(): AgentTombstone[];
+    /** The agents of the session the surfaces show (see {@link setVisibleOwner}), newest first. */
     listAgents(): AgentRecord[];
+    /** Every agent this manager holds, whichever session it belongs to, newest first. */
+    listAllAgents(): AgentRecord[];
     abort(id: string): boolean;
     /**
      * Settle a record that never left the queue as stopped. It still reaches
@@ -630,7 +740,7 @@ export declare class AgentManager {
      * commit and branch that preserve the agent's changes — finishes before the
      * process exits instead of racing it.
      */
-    awaitWorktreeCleanup(timeoutMs: number): Promise<void>;
+    awaitWorktreeCleanup(timeoutMs: number, ids?: ReadonlySet<string>): Promise<void>;
     /** Wait for all running and queued agents to complete (including queued ones). */
     waitForAll(): Promise<void>;
     /**