pi-optchat 0.6.8 → 0.7.1

package/README.md

@@ -48,6 +48,7 @@ For headless use, pass `--optchat-profile work`.
 | `/optchat agents` | Live agent tree and saved run history. |
 | `/optchat agents model` | Subagent model and effort for this profile. |
 | `/optchat usage` | Token usage and cost estimates. |
+| `/optchat activity` | Memory gauge: view size, summaries catching up, running agents. |
 | `/optchat instructions` | Edit this profile's `AGENTS.md`. |
 | `/optchat browse` | Open a readable snapshot of memory: the shape of what the model sees, summaries you can open down to the original messages, and search that shows where each message is folded. Run again to refresh. |
 | `/optchat import` | Import history, or resume/discard a paused import. |
@@ -76,8 +77,10 @@ Compression and subagents make extra model requests with your provider credentia
 | Subagent model | Opus 5.5, high | Same as `/optchat agents model`. Applies to new subagents. |
 | Subagent levels | 1 | 1: only the main agent starts subagents (the recipe). 2 or more: subagents may start their own, that many levels deep. Applies to subagents started or resumed after the change. |
 | Max active agents | 8 | Subagents running at once in the profile, all levels together, so it also caps how deep a chain can go. |
+| Group subagent reports | on | The subagents started by one spawn report together, in one message once the last of them finishes (the recipe). Off: each reports as soon as it finishes. Applies to the next spawn. |
 | Previous exchange | on | Replays your last request and answer in full with the next turn (see below). Off is the recipe. |
 | Previous exchange limit | 16 KB | A larger last exchange is left out. |
+| Memory search | off | Gives the agent, and subagents started or resumed after the change, a `search` tool over your original messages (see below). Off is the recipe: zoom and date only. Applies from the next turn. |
 | Summary size tolerance | 640 bytes | The compactor is always asked for 512-byte lines; a longer line up to this size is kept instead of retried. 512 is the recipe's strict rule. |
 
 Numbers must be whole numbers of at least 1 (512 for the summary size tolerance). Missing keys in an older `config.json` take their defaults.
@@ -92,7 +95,7 @@ Ask in plain words, for example: "Spawn an agent to investigate this repository
 
 - Children get the profile's memory view (frozen at launch), its instructions, read-only `zoom`/`date`, and normal coding tools plus your installed extensions.
 - Children also get the Pi built-in extensions the main session loaded: MCP, codemode and tool search. Your MCP servers (`~/.pi/agent/mcp.json`, the project's `.pi/mcp.json`) work in subagents, with the sign-ins you made in Pi. If MCP is off in the main session (`--no-mcp`, `-builtin:mcp` in settings, or an extension that replaces `/mcp`), it is off in subagents too. Each subagent opens its own server connections (stdio servers start once per subagent) and closes them when it ends.
-- Each child reports back on its own when it finishes. The parent stays alive to receive reports; it never polls.
+- The children of one spawn report together: when the last of them finishes, their reports reach the parent as one message, `[id] report` each, in spawn order. A stopped or failed child counts as finished, with its stop or error text as its report. Each finished report is journaled right away, so if Pi dies before the rest finish, the reports it already has are delivered at the next start. Turn **Group subagent reports** off to get each report as soon as its child finishes. Messages sent with `tell_parent`, connected windows and their handoffs are never held back, and a child resumed with `tell` reports on its own. The parent stays alive to receive reports; it never polls.
 - In the main chat, subagent messages and reports appear in a dark grey box labelled `↳ subagent <id> · still running` or `· report`, so they don't look like something you typed. The model still receives them as ordinary user messages. (One exception: reports recovered at startup, before your first message in the session, still show as plain user messages.)
 - The parent can send a running child guidance with `tell`, and the child can message its parent mid-run with `tell_parent` (a question, an early finding). It reaches the parent like a report, marked "still running": between tool calls if the parent is busy, or waking it if it's waiting.
 - `tell` to a finished child resumes it: the same agent (ID, parent, model, directory) reopens its saved transcript, gets the message as a new prompt, and sends a new report. This also works for children from earlier Pi sessions. Only the agent that started the child can resume it, and the resumed child takes one active slot. Connected windows can't be resumed, and a child whose transcript is missing must be spawned fresh.
@@ -101,9 +104,9 @@ Ask in plain words, for example: "Spawn an agent to investigate this repository
 - Stopping an agent stops its whole subtree. A failed parent stops its descendants.
 - Agents run inside the Pi process. Closing Pi stops them; there is no detached mode.
 
-## Agents and usage inspector
+## Agents, usage and activity inspector
 
-An **Agents | Usage** bar sits below the input.
+An **Agents | Usage | Activity** bar sits below the input.
 
 | Key | Action |
 | --- | --- |
@@ -111,7 +114,7 @@ An **Agents | Usage** bar sits below the input.
 | **Left/Right**, **Enter** | Pick and open a section |
 | **Escape**, **Up**, or typing | Back to the editor |
 | **F6** | Open Agents directly, keeping your draft |
-| **Tab** | Switch between Agents and Usage |
+| **Tab** | Cycle Agents, Usage and Activity |
 
 Set a different shortcut with `OPTCHAT_INSPECT_KEY=ctrl+shift+a pi`. If another extension supplies a custom editor, OptChat leaves its Down key alone; use the shortcut or commands instead.
 
@@ -121,17 +124,23 @@ Set a different shortcut with `OPTCHAT_INSPECT_KEY=ctrl+shift+a pi`. If another
 
 | Key | Action |
 | --- | --- |
-| **Escape** or **Ctrl+C** | Clear a draft, else back to the main chat |
-| **Ctrl+X** twice | Stop this agent and the agents it started |
+| **Escape** | Clear a draft, else back to the main chat |
+| **Ctrl+C** | Clear a draft, else interrupt the agent's current step. Never ends the agent: queued messages go to it at once and it carries on; with none queued it waits for you (**interrupted · waiting for you**) until your next message, or a `tell` from the main agent, resumes it |
+| **Up** (empty input) | Take your newest queued message back to edit; send it again, or clear it to drop it |
+| **Ctrl+X** twice | Stop this agent and the agents it started (the only key that ends it) |
 | **Page Up/Down**, mouse wheel | Scroll; back at the bottom it follows again. The wheel needs Pi's default fullscreen mode |
 | **Ctrl+O** | Expand tool output (Pi's own toggle) |
 
-Guidance shows as queued until delivered, or undelivered if the child stops first. Guidance you send is also saved in main memory. Reasoning is not shown. Transcripts stay browsable after restart, and browsing them makes no model calls.
+Guidance shows as queued until delivered, or undelivered if the child stops first. When you interrupt an agent with nothing queued, the agent that started it gets a one-line note instead of a report, so it isn't left waiting. Guidance you send is also saved in main memory. Reasoning is not shown. Transcripts stay browsable after restart, and browsing them makes no model calls.
 
 **Usage** shows this session, last hour, today, last 7 days, or all time (**Left/Right**): one row per role and model (main agent, subagents, compactor, imports) with estimated cost, share of the total, output tokens, and how much input came from the cache. Costs are API prices, not your subscription bill.
 
 ![Usage page](docs/screenshots/usage.png)
 
+**Activity** is a memory gauge: how many messages the profile holds and how much of the 128 KB view they fill, then either **Settled** or **Catching up · 12 of 40 summaries** with a progress bar counted from when the backlog last grew from empty. If summarizing keeps failing, the last error and the retry countdown show under it. It also counts running agents, and interrupted ones waiting for you; their list is on Agents. While summaries or agents are at work, the bar's Activity item gets a **●**.
+
+![Activity page](docs/screenshots/activity.png)
+
 - Costs are API-rate estimates, not your subscription bill. Unknown rates show zero.
 - Record counts are not request counts; retries and tool overhead can add records.
 - Main-agent tracking starts with v0.3.0 (resumed sessions are backfilled). Older records without a parent session are left out of **This session**.
@@ -146,13 +155,13 @@ Pick the destination profile, then run `/optchat import`.
 3. **Mode** (only if the profile already has history):
    - **Append**: keep existing summaries and add the import. Faster and cheaper.
    - **Rebuild by conversation start date**: regenerate the whole tree, ordered by conversation start.
-4. **Preview**: destination, new and duplicate counts, text size, rough token estimate, and compactor. This is not a price quote.
+4. **Preview**: destination, new and duplicate counts, text size, rough token estimate, and compactor. This is not a price quote: a big import costs about 3x that estimate in compactor input, because every message is summarized and then re-read in merges, each with the memory view as (mostly cached) context.
 
-**What gets imported**: user messages and final assistant replies, with original dates and source labels, as in Victor's recipe. Tool calls and results, intermediate commentary, reasoning, subagent transcripts, replayed context, and image/audio/file bytes are left out. ChatGPT alternate branches are labelled as alternatives. Imported records are marked as historical so old requests are not treated as new instructions.
+**What gets imported**: user messages and final assistant replies, with original dates and source labels, as in Victor's recipe. Tool calls and results, intermediate commentary, reasoning, subagent transcripts, replayed context, and image/audio/file bytes are left out. So is the output Claude Code logs for slash and shell commands; the command itself stays as typed (`/name args` or `!command`). So are the context messages Codex injects, such as the AGENTS.md instructions and the environment context. Dropped text never becomes a conversation's title. ChatGPT alternate branches are labelled as alternatives. Imported records are marked as historical so old requests are not treated as new instructions.
 
 **Claude Code memories**: the auto-memory topic files in `~/.claude/projects/*/memory/` (not `MEMORY.md`, which only indexes them), picked by project. Each file becomes one dated note in the memory tree, not part of the prompt. An edited file comes in again as a newer note.
 
-**Duplicates**: re-importing skips messages already present, even if titles or paths changed. Changed source messages can appear as a separate historical version.
+**Duplicates**: re-importing skips messages already present, even if titles or paths changed. A resumed Claude Code session copies earlier messages into its own file; those copies are matched by message id and text, so they come in once, also against messages an earlier import stored. Changed source messages can appear as a separate historical version.
 
 **Pausing**: **Pause import** (or Escape) saves progress, and so does restarting Pi. `/optchat import` then offers **Resume** or **Discard staged import**. While an import is pending, chat in that profile is blocked; other profiles still work. Imports need the main agent and its subagents to be idle.
 
@@ -212,14 +221,15 @@ To delete a profile, delete its folder. Your original Pi sessions are kept in Pi
 
 ## How it differs from the recipe
 
-The recipe's four prompts are kept verbatim in `src/prompts.ts`, along with its numbers: 512-byte summary nodes (by default summaries up to 640 bytes are accepted without a retry, as long as they are smaller than what they replace; see Summary size tolerance), a 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Anthropic requests get stable cache breakpoints on the view, and when that view is not cached yet, one compactor call goes first and the others wait until it starts answering, so they read the cache instead of each writing it. See `docs/victor-recipe.md` for notes.
+The recipe's four prompts are kept verbatim in `src/prompts.ts` (the view doc adds one sentence: you can zoom out too, from a message to the summaries above it), along with its numbers: 512-byte summary nodes (by default summaries up to 640 bytes are accepted without a retry, as long as they are smaller than what they replace; see Summary size tolerance), a 128,000-byte memory view, binary merges, 8 compression workers, fixed retry delays, 5 shortening attempts, and a 30,000-character tool output cap. Each compactor request shows a 512-byte example line for scale. It is a true line about OptChat itself, labelled as not from the chat and fenced off in `<example>` tags, with the text to summarize in `<input>` tags: shown bare, a made-up example was sometimes summarized as if it were chat and spread up the tree. Anthropic requests get stable cache breakpoints on the view, and when that view is not cached yet, one compactor call goes first and the others wait until it starts answering, so they read the cache instead of each writing it. See `docs/victor-recipe.md` for notes.
 
 Each run's context is the memory view, the previous exchange, and your new message. Deliberate additions (the ones that change the recipe's behaviour are settings, see [Settings](#settings)):
 
 1. **Previous exchange kept verbatim.** Your last request (with any steering) and the final answer are included in full, so "why is that?" refers to what you actually read. Tool calls and reasoning are not carried over. It comes on top of the 128,000-byte view. If it is over 16,000 bytes (about 4,000 tokens, usually a big paste; Previous exchange limit) it is left out entirely, and the model relies on the view and zoom as in Victor's recipe. A new Pi session starts with the memory view only.
-2. **Subagents** are built in with Pi's SDK rather than a separate package. Children report individually instead of per batch, and with Subagent levels above 1 they can delegate further.
-3. **Profiles**, the **inspector**, the **usage ledger**, **import**, and **connected windows** are additions. Import adds historical-record guidance to the prompts.
-4. **Not done**: computer use and hosting on an always-on machine.
+2. **Subagents** are built in with Pi's SDK rather than a separate package. With Subagent levels above 1 they can delegate further.
+3. **Memory search** (off by default). With the setting on, the agent also gets `search(text, before?)`: plain, case-insensitive text matching over the original messages, never the summaries (a summary can be wrong, and one fact repeats at every level of the tree), skipping logged zoom and search results. It returns 20 hits at a time, newest first, each with its id, the view line that holds it when that is a summary (`1234 (in 1024+256)`), its date and a snippet; `before: id` pages back, and `zoom(id, 1)` reads a hit. One line about it is added to the system prompt. Turning it on or off changes the cached prompt once.
+4. **Profiles**, the **inspector**, the **usage ledger**, **import**, and **connected windows** are additions. Import adds historical-record guidance to the prompts.
+5. **Not done**: computer use and hosting on an always-on machine.
 
 ## Development
 
@@ -242,12 +252,12 @@ npm run test:live  # paid Anthropic calls on synthetic data in a disposable prof
 
 Pi's [package directory](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) lists npm packages with the `pi-package` keyword, which the manifest already has. GitHub alone is not enough.
 
-```sh
-npm ci --ignore-scripts
-npm run check && npm test
-npm pack --dry-run
-npm publish --access public
-```
+Publishing a GitHub release publishes to npm. The [Publish workflow](.github/workflows/publish.yml) uses npm trusted publishing, so no token or `npm login` is involved:
+
+1. Merge a PR that bumps `version` in `package.json`.
+2. `gh release create vX.Y.Z --target main --generate-notes`
+
+The workflow checks that the tag matches `package.json`, runs the type check and tests, and publishes with provenance. It skips versions already on npm. To retry a tag, run it by hand: `gh workflow run publish.yml -f tag=vX.Y.Z`.
 
 ## Credits and license
 

package/docs/victor-recipe.md

@@ -10,12 +10,12 @@ The source remains upstream rather than duplicating the full article here. Its f
 
 ## Implementation mapping
 
-- `src/memory.ts`: append-only log, binary summary tree, compression scheduling, bounded view, zoom/date.
+- `src/memory.ts`: append-only log, binary summary tree, compression scheduling, bounded view, zoom/date, and the opt-in text search over original messages (`src/tools.ts` has the tool; not in the recipe, off by default).
 - `src/compactor.ts`: contextual compression and size retries.
-- `src/cache.ts`: stable Anthropic cache boundaries.
+- `src/cache.ts`: stable Anthropic cache boundaries. OpenAI requests get no marks: GPT-5.6 rejects the recipe's `prompt_cache_breakpoint` with a 400 (found by @aaaxn), so they rely on implicit prefix caching. OptChat doesn't set `reasoning.context` either: GPT-5.6 already defaults to the recipe's `"all_turns"`, and OpenAI documents it only for GPT-5.6 and GPT-6.1 Sol.
 - `src/transcript.ts`: fresh context per parent run, current-run tool loop retained. The previous completed exchange is also retained in full text (left out if over 16,000 bytes by default), an intentional addition to the summary-only recipe for conversational continuity.
 - `src/agents.ts`: asynchronous Pi SDK children and automatic completion reports.
-- `src/settings.ts`: per-profile settings for the departures from the recipe. Defaults are the recipe's (one subagent level), except the previous exchange (on) and the summary size tolerance (640 bytes, against the recipe's strict 512).
-- `src/import/`: profile-scoped historical imports retain user messages and final assistant replies, following the lighter history described in recipe section 10. Source adapters, final-reply detection, replay filtering, and ChatGPT branch labels are integration choices. Live-chat tool logging remains unchanged.
+- `src/settings.ts`: per-profile settings for the departures from the recipe. Defaults are the recipe's (one subagent level, no memory search), except the previous exchange (on) and the summary size tolerance (640 bytes, against the recipe's strict 512).
+- `src/import/`: profile-scoped historical imports retain user messages and final assistant replies, following the lighter history described in recipe section 10. An import hands `Memory` one message at a time, each once the one before it is summarized, so the compactor sees the view a live chat would have shown it. Source adapters, final-reply detection, replay filtering, and ChatGPT branch labels are integration choices. Live-chat tool logging remains unchanged.
 
 Profiles, native Pi UI, conversation import, and local Git checkpoints are integration choices described in the README.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-optchat",
-  "version": "0.6.8",
+  "version": "0.7.1",
   "type": "module",
   "pi": {
     "extensions": [
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --import ./test/support.ts --test test/*.test.ts",
     "test:live": "tsx test/live.ts"
   },
   "devDependencies": {

package/src/agent-view.ts

@@ -167,6 +167,7 @@ const statusOf = (run: RunInfo, children: Children) => {
   if (!live) return run.state;
   if (run.state === 'stopping') return 'stopping';
   if (run.state === 'waiting') return 'waiting for its agents';
+  if (run.state === 'paused') return 'interrupted · waiting for you';
   const tools = [...live.tools.values()].map(t => t.name);
   return tools.length ? `running ${tools.join(', ')}` : live.streaming ? 'writing' : 'working';
 };
@@ -207,7 +208,9 @@ export class AgentView implements Component, Focusable {
   private readonly close = () => { if (!this.ended) { this.dispose(); this.options.done(); } };
   dispose() { this.ended = true; clearInterval(this.timer); this.unsubscribe(); this.options.signal?.removeEventListener('abort', this.close); }
   invalidate() { this.editor.invalidate(); }
-  private get canMessage() { return ['running', 'waiting'].includes(this.options.children.live(this.options.id)?.info.state ?? ''); }
+  private get state() { return this.options.children.live(this.options.id)?.info.state ?? ''; }
+  private get canMessage() { return ['running', 'waiting', 'paused'].includes(this.state); }
+  private get canInterrupt() { return ['running', 'waiting'].includes(this.state); }
   private scroll(lines: number) { this.back = Math.max(0, Math.min(this.overflow, this.back + lines)); }
   /** Wheel scrolling, in Pi's default fullscreen mode; in "regular" mode the terminal keeps the wheel. */
   handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
@@ -226,12 +229,19 @@ export class AgentView implements Component, Focusable {
     if (this.ended) return;
     const { children, id } = this.options;
     const stopping = this.confirmStop; this.confirmStop = false; this.notice = '';
-    if ((matchesKey(data, 'escape') && !this.editor.isShowingAutocomplete()) || matchesKey(data, 'ctrl+c')) {
-      if (!this.editor.getText()) return this.close();
+    const escape = matchesKey(data, 'escape') && !this.editor.isShowingAutocomplete(), interrupt = matchesKey(data, 'ctrl+c');
+    if ((escape || interrupt) && this.editor.getText()) {
       this.editor.setText(''); // First press clears a draft, as in the main editor.
       return this.options.redraw();
     }
-    if (matchesKey(data, 'ctrl+x')) {
+    if (escape || interrupt && !this.canInterrupt) return this.close();
+    // Up on an empty input pulls the newest queued message back to edit: sending it queues the new text, clearing it drops it.
+    const pulled = matchesKey(data, 'up') && !this.editor.getText() && this.canMessage ? children.withdraw(id) : undefined;
+    if (pulled !== undefined) this.editor.setText(pulled);
+    else if (interrupt) {
+      children.interrupt(id).catch((error: unknown) => { this.notice = `Could not interrupt: ${error instanceof Error ? error.message : String(error)}`; })
+        .finally(() => { if (!this.ended) this.options.redraw(); });
+    } else if (matchesKey(data, 'ctrl+x')) {
       if (!children.live(id)) this.notice = 'This agent has already finished.';
       else if (stopping) children.stop(id).catch((error: unknown) => { this.notice = `Could not stop: ${String(error)}`; this.options.redraw(); });
       else this.confirmStop = true;
@@ -287,9 +297,12 @@ export class AgentView implements Component, Focusable {
     const end = lines.length - this.back;
     const body = lines.slice(Math.max(0, end - this.bodyHeight), end);
     while (body.length < this.bodyHeight) body.push('');
+    const editable = this.canMessage && run?.guidance.some(g => g.state === 'queued' && g.from === 'user');
+    const keys = [...this.editor.getText() ? ['Esc clear'] : ['Esc back to main', ...this.canInterrupt ? ['Ctrl+C interrupt'] : [], ...editable ? ['↑ edit queued'] : []],
+      ...live ? ['Ctrl+X stop'] : [], ...this.overflow ? [this.back ? 'PgDn newer' : 'PgUp older'] : []];
     const hint = this.confirmStop ? color('warning', ' Press Ctrl+X again to stop this agent and the agents it started')
       : this.notice ? color('error', ` ${this.notice}`)
-      : color('dim', ` ${this.editor.getText() ? 'Esc clear' : 'Esc back to main'}${live ? ' · Ctrl+X stop' : ''}${this.overflow ? this.back ? ' · PgDn newer' : ' · PgUp older' : ''}`);
+      : color('dim', ` ${keys.join(' · ')}`);
     const scrolled = this.back ? color('warning', `↑ ${this.back} lines up `) : '';
     const footer = [visibleWidth(hint) + visibleWidth(scrolled) < width ? `${hint}${' '.repeat(width - visibleWidth(hint) - visibleWidth(scrolled))}${scrolled}` : hint];
     // On a terminal too short for everything, the header goes first; the input and footer stay.

package/src/agents.ts

@@ -7,7 +7,7 @@ import * as sdk from '@earendil-works/pi-coding-agent';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { Api, Model } from '@earendil-works/pi-ai';
 import { SUBAGENT, VIEW_DOC } from './prompts.ts';
-import { memoryTools } from './tools.ts';
+import { memoryTools, SEARCH_DOC, searchTool } from './tools.ts';
 import { type Memory } from './memory.ts';
 import type { ModelChoice } from './compactor.ts';
 import { cachePayload } from './cache.ts';
@@ -23,12 +23,20 @@ export interface LiveRun {
   session: AgentSession; info: RunInfo; updated: number; streaming?: AgentMessage;
   tools: Map<string, { name: string; args: unknown; output?: unknown; started: number }>;
   pendingReports: string[]; pendingGuidance: string[]; wake?: () => void; completion?: Promise<void>;
+  /** Set by the user's interrupt: the queued guidance the run continues with once its current step is aborted; with none, it pauses. */
+  interruption?: RunInfo['guidance'];
+  /** Messages being steered back into Pi's queue after it was cleared; other queue changes wait for it. */
+  requeueing?: Promise<void>;
+  /** Shared by the children of one spawn whose reports are delivered together, in spawn order. */
+  batch?: { ids: string[]; reports: Map<string, string> };
 }
 interface Options { parentSession?: string; usage?: UsageLedger; createSession?: typeof createAgentSession;
   /** Names of the built-in extensions the main session loaded (see `loadedBuiltins`). */
   builtins?: () => Iterable<string>;
-  /** Read on every spawn, so a changed profile setting applies to the next one. */
-  settings?: () => Pick<Settings, 'subagentLevels' | 'maxAgents'>;
+  /** Journals the reports a main-agent spawn has so far while its other children still run (none: the batch was delivered), so a crash cannot lose them. */
+  hold?: (batch: string, texts: string[]) => void;
+  /** Read on every spawn, so a changed profile setting applies to the next one. Missing settings take their defaults. */
+  settings?: () => Partial<Settings>;
   summarizeHandoff?: (run: RunInfo, messages: AgentMessage[], descendants?: HandoffEvidence[]) => Promise<string> }
 
 // Subagents load the user's installed extensions, except any copy of OptChat itself: they get memory tools directly and must not open a profile.
@@ -47,6 +55,8 @@ export const taskDirectory = (cwd: string, path = '.', windows = process.platfor
   resolve(cwd, path.replace(windows ? /^~(?=$|[\\/])/ : /^~(?=$|\/)/, homedir()));
 export const CWD_DOC = 'Project directory the subagent works in (~ allowed); its AGENTS.md files load from there. Defaults to your current directory.';
 const isOptchat = (path: string) => packageName(path) === 'pi-optchat';
+/** Pi hands steering to a run only between tool calls, so one long command keeps the parent and the user from reaching it. */
+export const STEERABLE = 'Never block in a single command for more than about 60 seconds. To wait for something, poll in short separate tool calls (for example one `sleep 30` per call), so messages from your parent or the user can reach you between calls.';
 
 // Pi's CLI adds its built-in extensions (MCP, codemode, tool search) to its own session; SDK sessions such as
 // subagents must add them. Pi versions that do not export a factory simply do not get that extension.
@@ -72,7 +82,7 @@ export class Children {
   private readonly completions = new Set<Promise<void>>();
   constructor(private readonly memory: Memory, private readonly registry: ModelRegistry,
     private readonly choice: () => ModelChoice, private readonly instructions: () => string,
-    private readonly report: (text: string, once?: boolean) => Promise<void>, private readonly warn: (text: string) => void,
+    private readonly report: (text: string, options?: { once?: boolean; count?: number }) => Promise<void>, private readonly warn: (text: string) => void,
     private readonly profileDirectory = memory.directory, private readonly options: Options = {}) {
     this.history = new RunHistory(profileDirectory);
     for (const warning of this.history.warnings) warn(warning);
@@ -84,7 +94,7 @@ export class Children {
       } catch (error) { warn(`Could not backfill child usage for ${run.id}: ${String(error)}`); }
     }
   }
-  private get settings() { return this.options.settings?.() ?? DEFAULT_SETTINGS; }
+  private get settings(): Settings { return { ...DEFAULT_SETTINGS, ...this.options.settings?.() }; }
   private full(extra: number) { return this.running.size + this.launching + extra > this.settings.maxAgents; }
   get ids() { return [...this.running.keys()]; }
   get active() { return this.completions.size > 0 || this.launching > 0 || this.settling > 0; }
@@ -123,6 +133,14 @@ export class Children {
     } catch (error) { this.warn(`Could not record subagent activity: ${String(error)}`); }
   }
   async spawn(tasks: { task: string; cwd?: string }[], cwd: string, signal?: AbortSignal, parentId?: string, connected = false) {
+    return (await this.launch(tasks, cwd, signal, parentId, connected)).ids;
+  }
+  /** The spawn tools' answer, saying how this spawn's reports will come back. */
+  async start(tasks: { task: string; cwd?: string }[], cwd: string, signal?: AbortSignal, parentId?: string) {
+    const { ids, grouped } = await this.launch(tasks, cwd, signal, parentId);
+    return `Started: ${ids.join(', ')}. ${grouped && ids.length > 1 ? 'Their reports will arrive together, as one message, once all of them have finished.' : 'Reports will arrive automatically.'}`;
+  }
+  private async launch(tasks: { task: string; cwd?: string }[], cwd: string, signal: AbortSignal | undefined, parentId: string | undefined, connected = false) {
     for (const directory of tasks.map(t => taskDirectory(cwd, t.cwd))) if (!existsSync(directory) || !statSync(directory).isDirectory()) throw new Error(`No such directory: ${directory}`);
     if (this.closing) throw new Error('Profile is closing.');
     this.settling++;
@@ -131,7 +149,7 @@ export class Children {
     const cancelled = () => this.closing || (parentId !== undefined && this.running.get(parentId)?.info.state !== 'running');
     if (parentId && (!parent || parent.info.state !== 'running')) throw new Error('The parent is no longer running.');
     const depth = parent ? parent.info.depth + 1 : 1;
-    const { subagentLevels, maxAgents } = this.settings;
+    const { subagentLevels, maxAgents, groupReports } = this.settings;
     if (depth > subagentLevels) throw new Error(`Delegation depth limit reached: this profile allows ${subagentLevels} level${subagentLevels === 1 ? '' : 's'} of subagents.`);
     if (this.closing) throw new Error('Profile is closing.');
     if (this.full(tasks.length)) throw new Error(`Profile limit: at most ${maxAgents} active agents, including parents and descendants. Reduce the batch or continue without delegating.`);
@@ -140,15 +158,17 @@ export class Children {
     const model = this.registry.find(selected.provider, selected.model);
     if (!model) throw new Error(`Subagent model unavailable: ${selected.provider}/${selected.model}`);
     const launched = await this.track(this.launchBatch({ tasks, cwd, depth, parentId, connected, selected, model, signal, cancelled }));
-    // Each child reports independently. A slow sibling must not hold back a finished result.
+    // Grouped, the last child of this spawn to finish delivers every report; otherwise each reports on its own.
+    const batch = groupReports && !connected ? { ids: launched.map(c => c.info.id), reports: new Map<string, string>() } : undefined;
     for (const live of launched) {
+      live.batch = batch;
       const work = this.execute(live, `${view}\n\nYour task:\n${live.info.task}`).catch(error => this.warn(`Subagent completion failed: ${String(error)}`))
         .finally(() => { this.completions.delete(work); this.changed(); });
       this.completions.add(work);
       live.completion = work;
     }
     this.changed();
-    return launched.map(c => c.info.id);
+    return { ids: launched.map(c => c.info.id), grouped: batch !== undefined };
   }
   /** close() waits for launches, so shutdown never unlocks the profile under a child that is still opening. */
   private track<T>(launch: Promise<T>) {
@@ -195,9 +215,9 @@ export class Children {
   private async open(o: { id: string; directory: string; depth: number; parentId?: string; connected: boolean; provider: string; model: Model<Api>;
     thinking?: ModelChoice['thinking']; sessionManager: SessionManager }) {
     const { id, directory, depth, parentId, connected } = o;
-    const { subagentLevels, maxAgents } = this.settings, delegates = depth < subagentLevels;
+    const { subagentLevels, maxAgents, memorySearch } = this.settings, delegates = depth < subagentLevels;
     const delegation = delegates ? `You may delegate parts of your assigned task with spawn when useful. Child reports arrive automatically after your current run ends; the harness keeps you alive to receive them. Never poll, sleep, or wait in a tool for children. Finish your current work and return; you will be prompted with their results. The profile allows ${maxAgents} active agents total.` : 'You are at the maximum delegation depth. Complete your task with your own tools.';
-    const instructions = [this.instructions(), delegation, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
+    const instructions = [this.instructions(), delegation, STEERABLE, connected ? 'You are speaking directly with the user in a connected window. Continue this conversation across requests. Use tell_parent for questions or findings the main agent needs now. A handoff will be generated when the user completes or disconnects the window.'
       : 'Use tell_parent only when your parent needs something now (a blocking question, an important early finding, or when asked to). Your final answer is delivered automatically; do not repeat it with tell_parent.'].filter(Boolean).join('\n\n');
     // The user's settings list their installed packages; a copy in memory keeps the child from writing them back.
     const settingsManager = SettingsManager.inMemory({ ...SettingsManager.create(directory, getAgentDir()).getSettings(), compaction: { enabled: false }, cacheWarming: 'off' });
@@ -209,7 +229,7 @@ export class Children {
         if (provider) pi.registerProvider(o.provider, provider);
         // Same prompt as the main agent (AGENTS.md files, skills, cwd); only the OptChat preamble differs.
         pi.on('before_agent_start', event => {
-          event.systemPromptOptions.customPrompt = `${SUBAGENT}\n\n${VIEW_DOC}`;
+          event.systemPromptOptions.customPrompt = `${SUBAGENT}\n\n${VIEW_DOC}${memorySearch ? SEARCH_DOC : ''}`;
           event.systemPromptOptions.sections.instructions = instructions;
         });
         pi.on('before_provider_request', (event, ctx) => ctx.model?.api === 'anthropic-messages' ? cachePayload(event.payload) : event.payload);
@@ -218,7 +238,7 @@ export class Children {
     await loader.reload();
     const { session } = await (this.options.createSession ?? createAgentSession)({ cwd: directory, resourceLoader: loader, settingsManager,
       model: o.model, thinkingLevel: o.thinking, sessionManager: o.sessionManager,
-      customTools: [...memoryTools(() => this.memory), ...(delegates ? this.delegationTools(id, directory, subagentLevels, maxAgents) : []), this.parentTool(id, parentId, connected)],
+      customTools: [...memoryTools(() => this.memory), ...(memorySearch ? [searchTool(() => this.memory)] : []), ...(delegates ? this.delegationTools(id, directory, subagentLevels, maxAgents) : []), this.parentTool(id, parentId, connected)],
       excludeTools: delegates ? [] : ['spawn', 'tell'],
     });
     // Callers track the session only after this returns: clean up here if its extensions fail to start.
@@ -229,7 +249,7 @@ export class Children {
   private delegationTools(parentId: string, cwd: string, levels: number, maxAgents: number) {
     return [{ name: 'spawn', label: 'Delegate task', description: `Delegate parts of your task. Results arrive automatically after this run; never poll or sleep waiting. Maximum depth ${levels} and ${maxAgents} active agents per profile.`,
       parameters: Type.Object({ tasks: Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })) }), { minItems: 1 }) }),
-      execute: async (_id: string, args: { tasks: { task: string; cwd?: string }[] }, signal?: AbortSignal) => result(`Started: ${(await this.spawn(args.tasks, cwd, signal, parentId)).join(', ')}. Results will arrive automatically.`),
+      execute: async (_id: string, args: { tasks: { task: string; cwd?: string }[] }, signal?: AbortSignal) => result(await this.start(args.tasks, cwd, signal, parentId)),
     }, { name: 'tell', label: 'Guide child', description: 'Send guidance to one of your direct children. A finished child is resumed with its earlier conversation, and its new report arrives automatically.',
       parameters: Type.Object({ id: Type.String(), message: Type.String() }),
       execute: async (_id: string, args: { id: string; message: string }) => {
@@ -246,16 +266,21 @@ export class Children {
         const message = args.message.trim();
         if (!message) throw new Error('Message is empty.');
         const text = `[${id}] ${connected ? 'Connected agent message' : 'Message from subagent (still running)'}: ${message}`;
-        if (!parentId) { await this.report(text); return result('Message sent to the main agent.'); }
-        const parent = this.running.get(parentId);
-        if (!parent || !['running', 'waiting'].includes(parent.info.state)) throw new Error('Your parent is no longer running.');
-        if (parent.info.state === 'waiting') { parent.pendingReports.push(text); parent.wake?.(); }
-        else await parent.session.steer(text);
-        this.changed();
-        return result(`Message sent to parent ${parentId}.`);
+        if (!await this.toParent(parentId, text)) throw new Error('Your parent is no longer running.');
+        return result(parentId ? `Message sent to parent ${parentId}.` : 'Message sent to the main agent.');
       },
     };
   }
+  /** A mid-run message to a child's parent: false if that parent is no longer running. */
+  private async toParent(parentId: string | undefined, text: string) {
+    if (!parentId) { await this.report(text); return true; }
+    const parent = this.running.get(parentId);
+    if (!parent || !['running', 'waiting', 'paused'].includes(parent.info.state)) return false;
+    if (parent.info.state === 'running') await parent.session.steer(text);
+    else { parent.pendingReports.push(text); parent.wake?.(); } // A paused parent keeps it until the user resumes it.
+    this.changed();
+    return true;
+  }
   private async shutdown(session: AgentSession) {
     try { await session.extensionRunner.emit({ type: 'session_shutdown', reason: 'quit' }); }
     catch (error) { this.warn(`Subagent cleanup failed: ${String(error)}`); }
@@ -273,8 +298,36 @@ export class Children {
       if (this.closing || info.handoff || state === 'stopping') throw new Error('Stopped before its first request.');
       await session.prompt(prompt);
       while (info.state !== 'stopping') {
+        if (live.interruption) {
+          const guidance = live.interruption.filter(g => g.state === 'queued');
+          // Read Pi's queue only once a rebuild has landed, and take the interrupt's messages off it so they arrive once.
+          // Until this is done, tell() holds new messages in pendingGuidance, where the turn below or a pause picks them up.
+          await live.requeueing;
+          const texts = new Set(guidance.map(g => g.text));
+          await this.requeue(live, session.clearQueue().steering.filter(text => !texts.has(text)));
+          live.interruption = undefined;
+          if (!guidance.length) {
+            // Nothing to hand over: the run waits for its next message instead of ending, and whoever waits on its report hears why.
+            if (transition(info, 'paused')) {
+              this.save(info);
+              if (!info.connected) await this.toParent(info.parentId, `[${info.id}] Interrupted by the user; it waits for their next message, so no report until then.`)
+                .catch(error => this.warn(`Could not tell the parent about the interrupt: ${String(error)}`));
+            }
+            continue;
+          }
+          if (!transition(info, 'running')) continue; // A stop during the cleanup wins.
+          for (const g of guidance) g.state = 'delivered';
+          this.save(info);
+          await session.prompt(`Interrupted by the user:\n\n${guidance.map(g => g.text).join('\n\n')}`);
+          continue;
+        }
+        const paused = info.state === 'paused';
+        if (paused && !live.pendingGuidance.length) {
+          await new Promise<void>(resolve => { live.wake = resolve; }); live.wake = undefined;
+          continue;
+        }
         const last = session.messages.findLast(m => m.role === 'assistant');
-        if (last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted')) break;
+        if (!paused && last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted')) break;
         if (live.pendingGuidance.length) {
           transition(info, 'running'); this.save(info);
           await session.prompt(live.pendingGuidance.shift()!);
@@ -317,37 +370,92 @@ export class Children {
     }
     // A metadata failure must not suppress delivery of the actual result.
     try { this.save(info); } catch (error) { this.warn(`Could not save run metadata: ${String(error)}`); }
-    const text = `[${info.id}] ${info.report}`;
+    let text = `[${info.id}] ${info.report}`;
+    const batch = live.batch;
+    let count: number | undefined;
+    if (batch) {
+      batch.reports.set(info.id, text);
+      const texts = batch.ids.flatMap(id => batch.reports.get(id) ?? []);
+      if (texts.length < batch.ids.length) { if (!info.parentId) this.options.hold?.(batch.ids[0], texts); return; }
+      text = texts.join('\n\n'); count = texts.length;
+    }
     if (info.parentId) {
       const parent = this.running.get(info.parentId);
       if (parent && parent.info.state !== 'stopping') { parent.pendingReports.push(text); this.changed(); }
       return;
     }
-    if (this.closing) { this.memory.append('user', text); return; }
-    try { await this.report(text); }
+    if (this.closing) this.memory.append('user', text);
+    else try { await this.report(text, { count }); }
     catch (error) {
       this.memory.append('user', text);
       this.warn(`Subagent report saved but could not wake the parent: ${String(error)}`);
     }
+    if (batch && batch.ids.length > 1) this.options.hold?.(batch.ids[0], []);
   }
   /** `caller` is the agent sending a manager message: undefined for the main agent, else the parent subagent's ID. */
   async tell(id: string, message: string, source: 'manager' | 'user' = 'manager', caller?: string) {
     const live = this.running.get(id);
     if (!live && source === 'manager' && this.history.records.has(id)) return this.track(this.resume(id, message, caller));
-    if (live && !['running', 'waiting'].includes(live.info.state)) throw new Error(`${id} is finishing. Its report will arrive on its own${live.info.connected || source === 'user' ? '' : '; tell it again after that to resume it'}.`);
+    if (live && !['running', 'waiting', 'paused'].includes(live.info.state)) throw new Error(`${id} is finishing. Its report will arrive on its own${live.info.connected || source === 'user' ? '' : '; tell it again after that to resume it'}.`);
     if (!live) throw new Error(`No running subagent ${id}.`);
     const text = live.info.connected && source === 'manager' ? `[Main agent guidance]\n${message.trim()}` : message.trim(); if (!message.trim()) throw new Error('Message is empty.');
     if (source === 'user') this.memory.append('user', `Direct guidance to subagent [${id}]: ${text}`);
     const guidance: RunInfo['guidance'][number] = { text, date: Date.now(), state: 'queued', from: source };
     live.info.guidance.push(guidance); this.save(live.info);
     try {
-      if (live.info.state === 'waiting') { live.pendingGuidance.push(text); live.wake?.(); }
-      else await live.session.steer(text);
+      await live.requeueing; // Keeps the queue in the order messages were sent.
+      if (live.info.state === 'running' && !live.interruption) await live.session.steer(text);
+      else { live.pendingGuidance.push(text); live.wake?.(); } // Waiting, paused or being interrupted: this message starts its next turn.
     }
     catch (error) { guidance.state = 'undelivered'; this.save(live.info); throw error; }
     if (guidance.state === 'undelivered') throw new Error(`${id} finished before it read the message. Tell it again to resume it.`);
     return 'Message queued for the next tool boundary.';
   }
+  /**
+   * The user's Ctrl+C, never destructive: aborts the current step. With guidance queued, the run continues at once with it;
+   * with none, it pauses until the next message (from the user or a tell). Only stop() ends a run.
+   */
+  async interrupt(id: string): Promise<'continued' | 'paused'> {
+    const live = this.running.get(id);
+    if (live?.info.state === 'paused') return 'paused';
+    if (!live || !['running', 'waiting'].includes(live.info.state)) throw new Error(`No running subagent ${id}.`);
+    const guidance = live.info.guidance.filter(g => g.state === 'queued');
+    // Nothing yields before the abort starts, so the run cannot finish in between and drop the messages.
+    // They leave pendingGuidance here and Pi's steering queue in execute(), which then sends them in one prompt.
+    const texts = new Set(guidance.map(g => g.text));
+    live.pendingGuidance = live.pendingGuidance.filter(text => !texts.has(text));
+    live.interruption = guidance;
+    live.wake?.();
+    await live.session.abort();
+    return guidance.length ? 'continued' : 'paused';
+  }
+  /** Takes the user's newest undelivered message back off the queue, to edit it; undefined when there is none left to take. */
+  withdraw(id: string) {
+    const live = this.running.get(id);
+    const text = live?.info.guidance.findLast(g => g.state === 'queued' && g.from === 'user')?.text;
+    if (!live || text === undefined || live.requeueing || live.interruption) return undefined;
+    // The queue holds only texts, so of equal ones the last is taken back, record and queue entry alike.
+    const guidance = live.info.guidance.findLast(g => g.state === 'queued' && g.text === text)!;
+    const pending = live.pendingGuidance.lastIndexOf(guidance.text);
+    if (pending >= 0) live.pendingGuidance.splice(pending, 1);
+    else {
+      const steering = live.session.getSteeringMessages();
+      const at = steering.lastIndexOf(guidance.text);
+      if (at < 0) return undefined; // Already on its way to the agent.
+      // Pi cannot drop a single queued message: clear the queue and steer the rest back in order.
+      void this.requeue(live, live.session.clearQueue().steering.filter((_, i) => i !== at));
+    }
+    live.info.guidance.splice(live.info.guidance.indexOf(guidance), 1); this.save(live.info);
+    return guidance.text;
+  }
+  private requeue(live: LiveRun, texts: string[]) {
+    const work: Promise<void> = (async () => {
+      try { for (const text of texts) await live.session.steer(text); }
+      catch (error) { this.warn(`Could not requeue a message for ${live.info.id}: ${String(error)}`); }
+    })().finally(() => { if (live.requeueing === work) live.requeueing = undefined; });
+    live.requeueing = work;
+    return work;
+  }
   /** Reopens a finished child from its saved transcript, same ID, parent and model, and gives it a new message. */
   private async resume(id: string, message: string, caller: string | undefined) {
     const run = this.history.records.get(id)!, text = message.trim();
@@ -357,7 +465,7 @@ export class Children {
     if (run.parentId !== caller) {
       if (!run.parentId) throw new Error(`Only the main agent can resume ${id}.`);
       const parent = this.running.get(run.parentId);
-      throw new Error(parent && ['running', 'waiting'].includes(parent.info.state) ? `Only ${id}'s parent ${run.parentId} can resume it. Ask ${run.parentId} with tell.`
+      throw new Error(parent && ['running', 'waiting', 'paused'].includes(parent.info.state) ? `Only ${id}'s parent ${run.parentId} can resume it. Ask ${run.parentId} with tell.`
         : `Only ${id}'s parent ${run.parentId} can resume it, and that parent is no longer running. Resume ${run.parentId} instead, or spawn a new subagent.`);
     }
     if (this.closing) throw new Error('Profile is closing.');
@@ -376,7 +484,7 @@ export class Children {
       const session = await this.open({ id, directory: run.cwd, depth: run.depth, parentId: run.parentId, connected: false, provider, model, sessionManager: manager });
       // stop() cannot see this child until it is registered, so a parent stopped meanwhile must cancel it here.
       const parent = run.parentId ? this.running.get(run.parentId) : undefined;
-      if (this.closing || run.parentId && (!parent || !['running', 'waiting'].includes(parent.info.state))) {
+      if (this.closing || run.parentId && (!parent || !['running', 'waiting', 'paused'].includes(parent.info.state))) {
         await this.shutdown(session); this.dispose(session); throw new Error('Parent or profile is stopping.');
       }
       // The finished record stays untouched (and resumable) unless the new one is saved.
@@ -440,7 +548,7 @@ export class Children {
       handoff.text = `[${run.id}] Connected conversation ${handoff.reason === 'complete' ? 'completed by user' : `interrupted (${handoff.reason})`}. This describes the conversation ending, not proof that every task succeeded.\n${summary}\n${source}`;
       run.report = handoff.text; this.save(run);
     }
-    await this.report(handoff.text, true);
+    await this.report(handoff.text, { once: true });
     handoff.delivered = true; this.save(run);
   }
   async stop(id: string) {