pi-optchat 0.10.0 → 0.10.2

package/docs/subagents.md

@@ -14,6 +14,10 @@ Your MCP servers (`~/.pi/agent/mcp.json`, the project's `.pi/mcp.json`) work in
 - 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.
 
+## Titles
+
+A spawn task may carry a `title`, a short label the agent writes for you. The Agents page, the agent view, the agent picker of a second terminal and an attached window's tab show it instead of the task's first line, and the child's reports start `[id · title]`. A task without one shows its first line, as before. The title is saved with the run, so it survives `/reload`.
+
 ## Model and thinking level
 
 Each task runs the profile's subagent model (`/optchat agents model`), unless the spawn sets that task's `model` (`provider/id`, as in `/model`) or `thinking`. The agent sets them only when you ask for them.
@@ -25,7 +29,7 @@ Each task runs the profile's subagent model (`/optchat agents model`), unless th
 
 ## Reports
 
-Each child reports to its parent as soon as it finishes, as one message starting `[id]`. The parent stays alive to receive reports; it never polls.
+Each child reports to its parent as soon as it finishes, as one message starting `[id]` (`[id · title]` with a title). The parent stays alive to receive reports; it never polls.
 
 - A failed child reports its error text.
 - A child whose request aborts with no stop (a provider abort) still reports `Task aborted: ...`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-optchat",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "pi": {
     "extensions": [

package/src/agent-view.ts

@@ -9,7 +9,8 @@ import type { Children } from './agents.ts';
 import { isHandingOff, type RunInfo } from './runs.ts';
 import { textContent } from './transcript.ts';
 import { record } from './cache.ts';
-import { elapsed, fit, oneLine } from './inspector.ts';
+import { agentLabel, elapsed, fit, oneLine } from './inspector.ts';
+import { isReport } from './report-message.ts';
 
 export type ViewTone = 'accent' | 'muted' | 'dim' | 'error' | 'warning' | 'success' | 'borderMuted';
 type ToolResult = Parameters<ToolExecutionComponent['updateResult']>[0];
@@ -23,14 +24,12 @@ const builtIns: Record<string, (cwd: string) => Renderers> = {
   grep: createGrepToolDefinition, find: createFindToolDefinition, ls: createLsToolDefinition,
 };
 
-/** Reports from the child's own agents start with their id, e.g. "[1a2b3c4d] ...". */
-const REPORT = /^\[[0-9a-f]{8}\] /;
 /** Connected windows prefix the main agent's guidance with this line. */
 const MAIN_PREFIX = '[Main agent guidance]\n';
 
 /** Who a user-role message in the child's conversation came from. Runs saved before senders were recorded count as the user's. */
 export function senderOf(text: string, guidance: Guidance = []): 'user' | 'manager' | 'report' {
-  if (REPORT.test(text)) return 'report';
+  if (isReport(text)) return 'report';
   if (text.startsWith(MAIN_PREFIX)) return 'manager';
   return guidance.findLast(g => g.text === text)?.from === 'manager' ? 'manager' : 'user';
 }
@@ -270,7 +269,7 @@ export class AgentView implements Component, Focusable {
     const left = ` ${dot} ${color('accent', run.id)}  `;
     const room = width - visibleWidth(left) - visibleWidth(right) - 3;
     if (room < 8) return truncateToWidth(`${left}${color('dim', right)}`, width);
-    const task = fit(oneLine(run.task), room);
+    const task = fit(agentLabel(run), room);
     return `${left}${task}${' '.repeat(Math.max(2, width - visibleWidth(left) - visibleWidth(task) - visibleWidth(right) - 1))}${color('dim', right)} `;
   }
   render(width: number): string[] {

package/src/agents.ts

@@ -11,7 +11,7 @@ import { memoryTools, searchTool } from './tools.ts';
 import { VIEW, type Memory } from './memory.ts';
 import type { ModelChoice } from './compactor.ts';
 import { cachePayload } from './cache.ts';
-import { CUT_OFF, RunHistory, isRunning, transition, sessionMessages, savedSession, undelivered, type RunInfo, type RunState, type FinishReason } from './runs.ts';
+import { CUT_OFF, reportHead, RunHistory, isRunning, transition, sessionMessages, savedSession, undelivered, sentText, type Guidance, type RunInfo, type RunState, type FinishReason } from './runs.ts';
 import { UsageLedger } from './usage.ts';
 import { fullChat, refreshFraction, textContent } from './transcript.ts';
 import { Type, type Static } from 'typebox';
@@ -19,13 +19,18 @@ import { result } from './tools.ts';
 import { handoffText, withUndelivered, type HandoffEvidence } from './handoff.ts';
 import { DEFAULT_SETTINGS, type Settings } from './settings.ts';
 import { THINKING } from './profiles.ts';
+import { oneLine } from './inspector.ts';
 
 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>; primed?: Promise<unknown>;
+  pendingReports: string[]; pendingGuidance: Guidance[]; wake?: () => void; completion?: Promise<void>; primed?: Promise<unknown>;
   /** 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'];
+  interruption?: Guidance[];
+  /** Guidance just handed to session.prompt(): the next user message is it, as Pi may rewrite the text (a /skill: line becomes the skill). */
+  prompting?: Guidance;
+  /** Every steer into Pi's queue, one at a time, so each knows which queued text is its own (see `steer`). */
+  steering: Promise<unknown>;
   /** 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. */
@@ -68,9 +73,10 @@ const packageName = (path: string): string | undefined => {
 /** A task's cwd may start with `~` and may be relative to the spawning agent's directory. */
 export const taskDirectory = (cwd: string, path = '.', windows = process.platform === 'win32') =>
   resolve(cwd, path.replace(windows ? /^~(?=$|[\\/])/ : /^~(?=$|\/)/, homedir()));
+const TITLE_DOC = 'Short label shown to the user, e.g. "Fix steering bug"';
 const CWD_DOC = 'Project directory the subagent works in (~ allowed); its AGENTS.md files load from there. Defaults to your current directory.';
 /** The spawn tools' tasks. What a task leaves out of model and thinking is the profile's subagent choice. */
-export const TASKS = Type.Array(Type.Object({ task: Type.String(), cwd: Type.Optional(Type.String({ description: CWD_DOC })),
+export const TASKS = Type.Array(Type.Object({ task: Type.String(), title: Type.Optional(Type.String({ description: TITLE_DOC })), cwd: Type.Optional(Type.String({ description: CWD_DOC })),
   model: Type.Optional(Type.String({ description: 'Leave unset for the profile\'s subagent model (named in your instructions). Set only when the user asks for a model, as provider/id from models().' })),
   thinking: Type.Optional(StringEnum(THINKING, { description: 'Leave unset for the profile\'s subagent level. Set only when the user asks for one.' })) }), { minItems: 1 });
 export type Task = Static<typeof TASKS>[number];
@@ -210,8 +216,9 @@ export class Children {
       if (event.type === 'turn_end' || event.type === 'agent_settled') this.options.usage?.backfill(live.session.sessionManager.getEntries(), live.info.parentSession, 'subagent', live.info.id);
       if (event.type === 'message_start' && event.message.role === 'user') {
         const text = textContent(event.message.content);
-        const guidance = live.info.guidance.find(g => g.state === 'queued' && g.text === text);
-        if (guidance) { guidance.state = 'delivered'; this.save(live.info); }
+        const guidance = live.prompting ?? live.info.guidance.find(g => g.state === 'queued' && sentText(g) === text);
+        live.prompting = undefined;
+        if (guidance) { if (text !== guidance.text) guidance.sent = text; guidance.state = 'delivered'; this.save(live.info); }
       }
       if (event.type === 'tool_execution_start') live.tools.set(event.toolCallId, { name: event.toolName, args: event.args, started: Date.now() });
       if (event.type === 'tool_execution_update') {
@@ -274,7 +281,7 @@ export class Children {
     launch.then(done, done);
     return launch;
   }
-  private async launchBatch({ tasks, cwd, depth, parentId, connected, signal, cancelled }: { tasks: { task: string; cwd?: string; model: Model<Api>; thinking: ModelChoice['thinking'] }[]; cwd: string; depth: number;
+  private async launchBatch({ tasks, cwd, depth, parentId, connected, signal, cancelled }: { tasks: (Omit<Task, 'model' | 'thinking'> & { model: Model<Api>; thinking: ModelChoice['thinking'] })[]; cwd: string; depth: number;
     parentId?: string; connected: boolean; signal?: AbortSignal; cancelled: () => boolean }) {
     const launched: LiveRun[] = [];
     let reserved = tasks.length;
@@ -286,9 +293,11 @@ export class Children {
         const id = randomUUID().slice(0, 8), directory = taskDirectory(cwd, task.cwd);
         const session = await this.open({ id, directory, depth, parentId, connected, model: task.model, thinking: task.thinking,
           sessionManager: SessionManager.create(directory, join(this.profileDirectory, 'runs')) });
-        const info: RunInfo = { id, task: task.task, cwd: directory, model: `${task.model.provider}/${task.model.id}`, thinking: session.thinkingLevel,
+        // One short line without brackets, so the `[id · title]` head of its reports stays parseable and small.
+        const title = oneLine(task.title ?? '').replace(/[[\]]/g, '').trim().slice(0, 128).trimEnd();
+        const info: RunInfo = { id, task: task.task, ...(title ? { title } : {}), cwd: directory, model: `${task.model.provider}/${task.model.id}`, thinking: session.thinkingLevel,
           parentSession: this.options.parentSession ?? '', parentId, depth, sessionFile: session.sessionFile, started: Date.now(), state: 'running', guidance: [], ...(connected ? { connected: true } : {}) };
-        const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [] };
+        const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [], steering: Promise.resolve() };
         launched.push(live); this.save(info); this.running.set(id, live);
         this.launching--; reserved--;
         session.subscribe(event => this.observe(live, event));
@@ -367,7 +376,7 @@ export class Children {
       parameters: Type.Object({ message: Type.String() }), execute: async (_id: string, args: { message: string }) => {
         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}`;
+        const text = `${reportHead(this.history.records.get(id) ?? { id })} ${connected ? 'Connected agent message' : 'Message from subagent (still running)'}: ${message}`;
         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.');
       },
@@ -378,7 +387,7 @@ export class Children {
     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);
+    if (parent.info.state === 'running') await this.steer(parent, text);
     else { parent.pendingReports.push(text); parent.wake?.(); } // A paused parent keeps it until the user resumes it.
     this.changed();
     return true;
@@ -407,7 +416,7 @@ export class Children {
           // 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));
+          const texts = new Set(guidance.map(sentText));
           await this.requeue(live, session.clearQueue().steering.filter(text => !texts.has(text)));
           live.interruption = undefined;
           if (!guidance.length) {
@@ -415,7 +424,7 @@ export class Children {
             if (transition(info, 'paused')) {
               this.save(info);
               // In a grouped spawn the note takes the run's place, so its siblings' reports are not held until the user comes back; its later report arrives on its own.
-              const note = `[${info.id}] Interrupted by the user; it waits for their next message, so no report until then.`, batch = live.batch;
+              const note = `${reportHead(info)} Interrupted by the user; it waits for their next message, so no report until then.`, batch = live.batch;
               live.batch = undefined;
               if (!info.connected) await (batch ? this.deliver(info, batch, note) : this.toParent(info.parentId, note))
                 .catch(error => this.warn(`Could not tell the parent about the interrupt: ${String(error)}`));
@@ -425,7 +434,7 @@ export class Children {
           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(interruptedWith(guidance.map(g => g.text)));
+          await session.prompt(interruptedWith(guidance.map(sentText)));
           continue;
         }
         const paused = info.state === 'paused';
@@ -438,7 +447,9 @@ export class Children {
         if (!paused && last?.role === 'assistant' && (last.stopReason === 'error' || last.stopReason === 'aborted') && !live.pendingReports.length && !this.directChildren(info.id).length) break;
         if (live.pendingGuidance.length) {
           transition(info, 'running'); this.save(info);
-          await session.prompt(live.pendingGuidance.shift()!);
+          live.prompting = live.pendingGuidance.shift()!;
+          // An extension command sends no message at all, so this can't outlive the prompt and claim a later one.
+          try { await session.prompt(live.prompting.text); } finally { live.prompting = undefined; }
           continue;
         }
         if (live.pendingReports.length) {
@@ -474,7 +485,7 @@ export class Children {
           // Pi's queue must be empty before the handoff turn, or it would take a cancelled message as new input. Guidance in it is
           // already marked undelivered; the rest (a child's message) joins the reports the window never read.
           await live.requeueing;
-          const guidance = new Set(info.guidance.map(g => g.text));
+          const guidance = new Set(info.guidance.map(sentText));
           const unread = [...live.pendingReports.splice(0), ...session.clearQueue().steering.filter(text => !guidance.has(text))];
           if (unread.length) info.handoff.unread = unread;
           transition(info, info.handoff.reason === 'complete' ? 'completed' : 'interrupted');
@@ -500,7 +511,7 @@ 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)}`); }
     // A deleted run's transcript is gone.
-    await this.deliver(info, live.batch, `[${info.id}] ${info.report}${this.deleting.has(info.id) ? '' : `\n\n${fullChat(info.id)}`}`);
+    await this.deliver(info, live.batch, `${reportHead(info)} ${info.report}${this.deleting.has(info.id) ? '' : `\n\n${fullChat(info.id)}`}`);
   }
   /** Sends a run's report to its parent; in a grouped spawn, only once every child of the spawn has one. */
   private async deliver(info: RunInfo, batch: LiveRun['batch'], text: string) {
@@ -539,12 +550,14 @@ export class Children {
     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 };
+    const guidance: Guidance = { text, date: Date.now(), state: 'queued', from: source };
     live.info.guidance.push(guidance); this.save(live.info);
     try {
       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.
+      if (live.info.state === 'running' && !live.interruption) {
+        const sent = await this.steer(live, text);
+        if (sent !== undefined && sent !== text) guidance.sent = sent;
+      } else { live.pendingGuidance.push(guidance); 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.`);
@@ -562,8 +575,8 @@ export class Children {
     // Nothing yields before the abort starts, so the run cannot finish in between and drop the messages.
     // They leave pendingGuidance and Pi's steering queue here, and execute() sends them in one prompt. Pi's queue must be empty
     // before the abort: after an aborted tool call Pi hands it to a request the abort cancels.
-    const texts = new Set(guidance.map(g => g.text));
-    live.pendingGuidance = live.pendingGuidance.filter(text => !texts.has(text));
+    live.pendingGuidance = live.pendingGuidance.filter(g => !guidance.includes(g));
+    const texts = new Set(guidance.map(sentText));
     // The rest of the queue (a child's tell_parent message) follows the interrupt's prompt, as reports to a paused run do.
     live.pendingReports.push(...live.session.clearQueue().steering.filter(text => !texts.has(text)));
     live.interruption = guidance;
@@ -578,11 +591,11 @@ export class Children {
     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);
+    const pending = live.pendingGuidance.indexOf(guidance);
     if (pending >= 0) live.pendingGuidance.splice(pending, 1);
     else {
       const steering = live.session.getSteeringMessages();
-      const at = steering.lastIndexOf(guidance.text);
+      const at = steering.lastIndexOf(sentText(guidance));
       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));
@@ -590,9 +603,16 @@ export class Children {
     live.info.guidance.splice(live.info.guidance.indexOf(guidance), 1); this.save(live.info);
     return guidance.text;
   }
+  /** Pi's steer(), returning what Pi queued, which may differ from `text` (a /skill: line becomes the skill): that is what the agent receives. */
+  private steer(live: LiveRun, text: string) {
+    // One at a time, so the newest entry in Pi's queue is this one's.
+    const sent = live.steering.then(async () => await live.session.steer(text) === 'queued' ? live.session.getSteeringMessages().at(-1) : undefined);
+    live.steering = sent.catch(() => undefined);
+    return sent;
+  }
   private requeue(live: LiveRun, texts: string[]) {
     const work: Promise<void> = (async () => {
-      try { for (const text of texts) await live.session.steer(text); }
+      try { for (const text of texts) await this.steer(live, 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;
@@ -634,7 +654,7 @@ export class Children {
       const info: RunInfo = { ...rest, state: 'running', started: Date.now(), parentSession: this.options.parentSession ?? run.parentSession,
         guidance: [...run.guidance, { text: prompt, date: Date.now(), state: 'queued', from: 'manager' }] };
       try { this.save(info); } catch (error) { this.history.records.set(id, run); await this.shutdown(session); this.dispose(session); throw error; }
-      const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [] };
+      const live: LiveRun = { session, info, updated: Date.now(), tools: new Map(), pendingReports: [], pendingGuidance: [], steering: Promise.resolve() };
       this.running.set(id, live);
       this.launching--; reserved = false;
       session.subscribe(event => this.observe(live, event));

package/src/browser.ts

@@ -88,7 +88,7 @@ const body = e => { const j = e.origin && e.text.startsWith('[Historical ') ? e.
 const short = (s, n) => { s = s.replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
 function who(e) {
   // Logs from before the work kind held reports as user messages starting "[id] "; another extension's shown custom message is tagged the same way.
-  if (e.kind === 'work' || e.kind === 'user' && /^\[[\w.:-]+\] /.test(e.text)) return ['Subagent', 'work', 'subagent report'];
+  if (e.kind === 'work' || e.kind === 'user' && /^\[[\w.:-]+(?: · [^\]\n]*)?\] /.test(e.text)) return ['Subagent', 'work', 'subagent report'];
   if (e.kind === 'user') return ['You', 'you', 'from you'];
   if (e.kind === 'talk') return ['OptChat', 'talk', 'reply'];
   if (e.kind === 'tool') return ['Tool call', 'tool', 'tool step'];

package/src/connected-window.ts

@@ -87,8 +87,8 @@ class LiveTurn implements Component {
 export async function openConnectedWindow(pi: ExtensionAPI, ctx: ExtensionContext, profile: string, setTitle: (title: string) => void = title => ctx.ui.setTitle(title), agentId?: string, activeOnly = false) {
   // Each window draws with its own transcript, so nothing from an earlier window carries over.
   transcript = undefined;
-  let started = false, ended = false, liveTurn: LiveTurn | undefined, live: LiveState | undefined, turn: AgentMessage[] = [];
-  const title = (state: WindowState) => setTitle(windowTitle(profile, state));
+  let label: string | undefined, started = false, ended = false, liveTurn: LiveTurn | undefined, live: LiveState | undefined, turn: AgentMessage[] = [];
+  const title = (state: WindowState) => setTitle(windowTitle(profile, state, label));
   const display = (text: string, details: Details = {}) => pi.sendMessage<Details>({ customType: 'optchat-connected', content: text, display: true, details }, { triggerTurn: false });
   const refresh = () => { if (liveTurn) { liveTurn.turn = turn; liveTurn.live = live; liveTurn.update(); } };
   /** A reply moves into the chat once all its tool calls have results, as Pi's own chat does when a tool finishes. */
@@ -103,8 +103,8 @@ export async function openConnectedWindow(pi: ExtensionAPI, ctx: ExtensionContex
   const hideLive = () => { live = undefined; liveTurn = undefined; ctx.ui.setWidget('optchat-connected', undefined); };
   const connection = await connectWindow(profilePath(profile), event => {
     if (event.name === 'started') {
-      started = true; showLive(); title('working');
-      ctx.ui.setStatus('optchat', `OptChat: ${profile} · ${agentId ? 'attached' : 'connected'} agent ${event.text} · /complete`);
+      label = event.title; started = true; showLive(); title('working');
+      ctx.ui.setStatus('optchat', `OptChat: ${profile} · ${agentId ? 'attached' : 'connected'} agent ${event.text}${label ? ` · ${label}` : ''} · /complete`);
     } else if (event.name === 'status') {
       live = event.live; refresh();
       // The tab says working exactly when the spinner spins.

package/src/index.ts

@@ -24,7 +24,7 @@ import { checkpoint } from './checkpoint.ts';
 import { memoryDirectory, pendingImport, prepareImport, runImport, discardImport } from './import/job.ts';
 import { chooseImport, showProgress } from './import/ui.ts';
 import { UsageLedger } from './usage.ts';
-import { oneLine, showInspector, type InspectorPage } from './inspector.ts';
+import { agentLabel, oneLine, showInspector, type InspectorPage } from './inspector.ts';
 import { showAgentView } from './agent-view.ts';
 import { inspectorShortcut, mountNavigation } from './navigation.ts';
 import { joinHeadless, listAttachableAgents, serveWindows } from './window-bridge.ts';
@@ -321,7 +321,7 @@ export default function optchat(pi: ExtensionAPI) {
           const listed = settled ? undefined : await listAttachableAgents(profilePath(name)).catch(() => undefined);
           const agents = listed ?? [];
           const hint = listed?.length === 0 ? '\nNo background agents are running. Ask the main agent to start one.' : '';
-          const labels = new Map(agents.map(agent => [`Open subagent ${agent.id} · ${agent.state} · ${oneLine(agent.task).slice(0, 80)}`, agent.id]));
+          const labels = new Map(agents.map(agent => [`Open subagent ${agent.id} · ${agent.state} · ${agentLabel(agent).slice(0, 80)}`, agent.id]));
           const choice = await ctx.ui.select(`${name} is open in another window\n${error.owner}${hint}`,
             [CONNECT, ...labels.keys(), ...(settled ? [] : [BACK])]);
           const agentId = choice && labels.get(choice);

package/src/inspector.ts

@@ -8,6 +8,8 @@ import { ranges, summarizeUsage, type UsageLedger, type UsageRange, type UsageRo
 
 export const clean = (text: string) => text.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '').replace(/\t/g, '  ');
 export const oneLine = (text: string) => clean(text).replace(/\n/g, ' ');
+/** How an agent is named to the user: its spawn title, else its task on one line. */
+export const agentLabel = (run: { task: string; title?: string }) => run.title ?? oneLine(run.task);
 export const count = (n: number) => n.toLocaleString('en-US');
 const units = ['', 'k', 'M', 'B'];
 /** 950, 12.3k, 164k, 2.4M: enough precision to compare rows at a glance. A value that rounds to 1000 moves up a unit. */
@@ -191,7 +193,7 @@ export class Inspector implements Component, Focusable {
       const rows = list.slice(this.top, this.top + this.height).map(run => {
         const live = children.live(run.id), tools = live ? [...live.tools.values()].map(t => t.name).join(', ') : '';
         const status = live ? `${run.state === 'stopping' ? 'stopping' : run.state === 'waiting' ? 'waiting for children' : run.state === 'paused' ? 'interrupted · waiting for you' : tools || (live.streaming ? 'responding' : 'working')} · ${elapsed(Date.now() - live.updated)} ago` : isHandingOff(run) ? 'handing off' : run.state;
-        return { run, task: `${'  '.repeat(run.depth - 1)}${run.parentId ? '↳ ' : ''}${oneLine(run.task)}`, status, time: elapsed((run.ended ?? Date.now()) - run.started) };
+        return { run, task: `${'  '.repeat(run.depth - 1)}${run.parentId ? '↳ ' : ''}${agentLabel(run)}`, status, time: elapsed((run.ended ?? Date.now()) - run.started) };
       });
       // Columns: task (flexible) · status · duration (right-aligned); status yields first on narrow screens.
       const timeWidth = Math.max(0, ...rows.map(r => r.time.length));

package/src/report-message.ts

@@ -2,7 +2,8 @@ import { getMarkdownTheme, type ExtensionAPI, type Theme } from '@earendil-works
 import { Box, Markdown, Text } from '@earendil-works/pi-tui';
 import { REPORT_TYPE, textContent, withoutFullChat } from './transcript.ts';
 
-const HEAD = /^\[([0-9a-f]{8})\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
+/** `[id]` or `[id · title]` (runs.ts `reportHead`); titles hold no brackets. */
+const HEAD = /^\[([0-9a-f]{8})(?: · ([^\]\n]*))?\] (?:(Message from subagent \(still running\)|Connected agent message): )?/;
 
 /** Sent with a report: `count` subagent reports joined in one message, when one spawn's reports arrive together. */
 export interface ReportDetails { count?: number }
@@ -13,8 +14,9 @@ export function reportParts(text: string, count = 1) {
   if (count > 1) return { label: `${count} subagent reports`, body: text };
   const match = HEAD.exec(text);
   if (!match) return { label: 'subagent', body: text };
-  const kind = match[2] === undefined ? 'report' : match[2].startsWith('Message') ? 'still running' : 'connected window';
-  return { label: `subagent ${match[1]} · ${kind}`, body: text.slice(match[0].length) };
+  const [, id, title, message] = match;
+  const kind = message === undefined ? 'report' : message.startsWith('Message') ? 'still running' : 'connected window';
+  return { label: `subagent ${id}${title ? ` · ${title}` : ''} · ${kind}`, body: text.slice(match[0].length) };
 }
 
 /** The theme's neutral grey, darkened on dark themes so the box recedes behind the conversation. */

package/src/runs.ts

@@ -12,6 +12,8 @@ export type RunState = typeof runStates[number];
 export type FinishReason = 'complete' | 'disconnected' | 'owner-stopped' | 'failed';
 export interface RunInfo {
   id: string; task: string; cwd: string; model: string; thinking: string;
+  /** The spawning agent's short label for the task, shown instead of it where there is room for one line. */
+  title?: string;
   parentSession: string; sessionFile?: string; started: number; ended?: number;
   parentId?: string; depth: number;
   state: RunState; report?: string;
@@ -20,9 +22,14 @@ export interface RunInfo {
   handoff?: { reason: FinishReason; text?: string; delivered?: boolean; unread?: string[] };
   /** Working when Pi closed or crashed: the next start resumes it (see `Children.resumeCutOff`). */
   cutOff?: boolean;
-  /** `from` is missing on runs saved before senders were recorded. */
-  guidance: { text: string; date: number; state: 'queued' | 'delivered' | 'undelivered'; from?: 'user' | 'manager' }[];
+  /** `from` is missing on runs saved before senders were recorded. `sent`: what Pi queued, when it rewrote `text` (a `/skill:` line becomes the skill itself). */
+  guidance: Guidance[];
 }
+export type Guidance = { text: string; date: number; state: 'queued' | 'delivered' | 'undelivered'; from?: 'user' | 'manager'; sent?: string };
+/** How a run's reports and messages start: `[id]`, or `[id · title]` (see `HEAD` in report-message.ts). */
+export const reportHead = (run: { id: string; title?: string }) => `[${run.id}${run.title ? ` · ${run.title}` : ''}]`;
+/** The text the agent receives, which is how Pi's queue and the session know the message. */
+export const sentText = (g: Guidance) => g.sent ?? g.text;
 const moves: Record<RunState, readonly RunState[]> = {
   running: ['waiting', 'paused', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
   waiting: ['running', 'paused', 'stopping', 'completed', 'failed', 'stopped', 'interrupted'],
@@ -53,6 +60,7 @@ function isRun(value: unknown): value is RunInfo {
     && typeof value.id === 'string' && /^[a-zA-Z0-9-]+$/.test(value.id)
     && runStates.includes(value.state as RunState) && typeof value.started === 'number' && Number.isFinite(value.started)
     && (value.ended === undefined || typeof value.ended === 'number')
+    && (value.title === undefined || typeof value.title === 'string')
     && (value.sessionFile === undefined || typeof value.sessionFile === 'string')
     && (value.report === undefined || typeof value.report === 'string')
     && (value.connected === undefined || typeof value.connected === 'boolean')
@@ -63,7 +71,7 @@ function isRun(value: unknown): value is RunInfo {
       && (value.handoff.unread === undefined || Array.isArray(value.handoff.unread) && value.handoff.unread.every(text => typeof text === 'string')))
     && typeof value.depth === 'number' && Number.isInteger(value.depth) && value.depth >= 1
     && (value.parentId === undefined || typeof value.parentId === 'string')
-    && Array.isArray(value.guidance) && value.guidance.every(g => record(g) && typeof g.text === 'string' && typeof g.date === 'number' && ['queued', 'delivered', 'undelivered'].includes(String(g.state)) && (g.from === undefined || g.from === 'user' || g.from === 'manager'));
+    && Array.isArray(value.guidance) && value.guidance.every(g => record(g) && typeof g.text === 'string' && typeof g.date === 'number' && ['queued', 'delivered', 'undelivered'].includes(String(g.state)) && (g.from === undefined || g.from === 'user' || g.from === 'manager') && (g.sent === undefined || typeof g.sent === 'string'));
 }
 export const CUT_OFF = 'Pi closed before this agent finished. Its partial transcript is retained.';
 export function sessionMessages(file: string): AgentMessage[] {

package/src/settings-page.ts

@@ -7,8 +7,8 @@ import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 
 type Role = 'compactor' | 'subagent';
 const ROLES: Record<Role, { label: string; description: string; applies: string }> = {
-  compactor: { label: 'Compactor model', description: 'Writes memory summaries, imports and connected-window handoffs. Shortcut: /optchat model.', applies: 'Applies to the next summary.' },
-  subagent: { label: 'Subagent model', description: 'Runs every subagent. Shortcut: /optchat agents model.', applies: 'Applies to subagents started after this.' },
+  compactor: { label: 'Compactor model', description: 'Writes memory summaries, imports and fallback handoffs. Shortcut: /optchat model.', applies: 'Applies to the next summary.' },
+  subagent: { label: 'Subagent model', description: 'Runs every subagent. Shortcut: /optchat agents model.', applies: 'Applies to new subagents.' },
 };
 const modelName = (choice: ModelChoice) => `${choice.provider}/${choice.model}`;
 export const showModel = (choice: ModelChoice) => `${modelName(choice)} · ${choice.thinking}`;

package/src/settings.ts

@@ -3,32 +3,32 @@ import { NODE } from './memory.ts';
 /** Per-profile choices where OptChat departs from Victor's recipe. Each default is the recipe's behaviour unless noted. */
 export const SETTINGS = {
   subagentLevels: { kind: 'number', label: 'Subagent levels', default: 1, min: 1, unit: '',
-    description: 'How many levels of subagents. 1: only the main agent starts subagents. 2: those subagents may start their own, and so on.',
-    applies: 'Applies to subagents started or resumed after this.' },
+    description: 'How deep subagents can nest. 1: only the main agent starts them.',
+    applies: 'Applies to new or resumed subagents.' },
   maxAgents: { kind: 'number', label: 'Max active agents', default: 8, min: 1, unit: '',
-    description: 'Subagents running at once in this profile, all levels together. It also caps how deep a chain can go.',
+    description: 'Subagents running at once, all levels together. Also caps chain depth.',
     applies: 'Applies to the next spawn.' },
   groupReports: { kind: 'toggle', label: 'Group subagent reports', default: false,
-    description: 'Off: each subagent reports as soon as it finishes, as in Victor\'s recipe. On: the subagents started by one spawn report together, in one message once the last of them finishes.',
+    description: 'On: subagents from one spawn report together, once the last finishes. Off: each reports when done (Victor\'s recipe).',
     applies: 'Applies to the next spawn.' },
   previousExchange: { kind: 'toggle', label: 'Previous exchange', default: true,
-    description: 'Send your last request and its answer in full with the next turn, so a follow-up reads the exact wording. Off: memory view only, as in Victor\'s recipe. On by default: a study found it costs little and saves zooms.',
+    description: 'Send your last request and its answer in full with the next turn, so follow-ups see the exact wording. Off: memory view only (Victor\'s recipe).',
     applies: 'Applies from the next turn.' },
   previousExchangeKB: { kind: 'number', label: 'Previous exchange limit', default: 16, min: 1, unit: 'KB',
-    description: 'A larger last exchange, usually a big paste, is left out and the model zooms into memory instead.',
+    description: 'A larger exchange, usually a big paste, is left out; the model zooms instead.',
     applies: 'Applies from the next turn.' },
   memorySearch: { kind: 'toggle', label: 'Memory search', default: false,
-    description: 'Give agents a search tool that finds original messages by plain text, newest first, for exact names, numbers, paths or errors the view doesn\'t show. Off: zoom and date only, as in Victor\'s recipe. Turning it on or off makes the next turn re-cache its prompt once.',
-    applies: 'Applies from the next turn, and to subagents started or resumed after this.' },
+    description: 'Lets agents search original messages by plain text. Off: zoom and date only (Victor\'s recipe). Toggling re-caches the prompt once.',
+    applies: 'Applies from the next turn and to new or resumed subagents.' },
   summaryAcceptBytes: { kind: 'number', label: 'Summary size tolerance', default: NODE * 1.25, min: NODE, unit: 'bytes',
-    description: `The compactor is always asked for ${NODE}-byte lines; a longer line up to this size is kept instead of retried. ${NODE}: strict, as in Victor's recipe. The default saves retries for a little more view space.`,
+    description: `Summary lines up to this size are kept instead of retried (the compactor aims for ${NODE}). ${NODE}: strict (Victor's recipe).`,
     applies: 'Applies to the next summary.' },
   jobs: { kind: 'number', label: 'Summaries at once', default: 8, min: 1, max: 64, unit: '',
-    description: 'Summaries built at once, by chat compaction and by an import. With N at once, a summary can see up to N−1 lines not summarized yet before it, so higher is faster but a little less accurate (at 8 that costs about 0.8 points per summary, #108). Higher also hits your provider\'s rate limits harder; the compactor retries what is refused. If your provider caps parallel requests, set it below that cap so the main turn has room.',
-    applies: 'Applies to the next import, and to chat once the profile opens again (e.g. after /reload).' },
+    description: 'Summaries built in parallel. Higher is faster, slightly less accurate and harder on rate limits; keep it below your provider\'s parallel cap.',
+    applies: 'Applies to the next import, and to chat after /reload.' },
   refreshAt: { kind: 'percent', label: 'Turn refresh threshold', default: 0.3, min: 0, max: 0.9,
-    description: 'Once the current turn\'s messages pass this share of the model\'s context window, they move into memory and the turn goes on with a fresh window: the rebuilt view, the task word for word, and its last tool call and result. 0%: off, as in Victor\'s recipe, and a long turn can run out of window. OPTCHAT_REFRESH_AT (a fraction, e.g. 0.3; 0 is off) overrides it. Subagents use Pi\'s own compaction at about the same point.',
-    applies: 'Applies from the next call, and to subagents started or resumed after this.' },
+    description: 'When a turn fills this share of the context window, it moves into memory and continues in a fresh window. 0%: off (Victor\'s recipe). OPTCHAT_REFRESH_AT overrides it.',
+    applies: 'Applies from the next call and to new or resumed subagents.' },
 } as const;
 
 export type SettingKey = keyof typeof SETTINGS;

package/src/title.ts

@@ -4,8 +4,9 @@ export type WindowState = StatusState | 'done' | 'disconnected';
 
 const agents = (count: number) => count > 0 ? ` · ${count} ${count === 1 ? 'agent' : 'agents'}` : '';
 export const mainTitle = (profile: string, working: boolean, running: number) => `${working ? '● ' : ''}π ${profile}${agents(running)}`;
-export const windowTitle = (profile: string, state: WindowState) =>
-  `${state === 'working' ? '● ' : ''}↳ ${profile}${state === 'done' || state === 'disconnected' ? ` · ${state}` : ''}`;
+/** `label`: the spawn title of the subagent an attached window shows. */
+export const windowTitle = (profile: string, state: WindowState, label?: string) =>
+  `${state === 'working' ? '● ' : ''}↳ ${profile}${label ? ` · ${label}` : ''}${state === 'done' || state === 'disconnected' ? ` · ${state}` : ''}`;
 /** A connected window's agent is working while it runs or stops, or waits on agents of its own; waiting with none means waiting for you. */
 export const statusState = (state: string, agents = 0): StatusState =>
   state === 'running' || state === 'stopping' || state === 'waiting' && agents > 0 ? 'working' : 'waiting';

package/src/transcript.ts

@@ -148,11 +148,11 @@ export function runTranscript(messages: readonly AgentMessage[]) {
   }).join('\n');
 }
 
-/** The status line naming running agents by id and the first words of their task; none while nothing runs. */
-export function atWork(runs: readonly { id: string; task: string }[]) {
+/** The status line naming running agents by id and the first words of their title or task; none while nothing runs. */
+export function atWork(runs: readonly { id: string; task: string; title?: string }[]) {
   if (!runs.length) return undefined;
-  return AT_WORK + runs.map(({ id, task }) => {
-    const words = flat(task).replaceAll('"', "'").split(/\s+/).filter(Boolean), start = words.slice(0, 6).join(' ');
+  return AT_WORK + runs.map(({ id, task, title }) => {
+    const words = flat(title ?? task).replaceAll('"', "'").split(/\s+/).filter(Boolean), start = words.slice(0, 6).join(' ');
     // Six words, but never more than 60 characters: a task can be one long word.
     const preview = [...start].slice(0, 60).join('');
     return `${id} "${preview}${words.length > 6 || preview.length < start.length ? '…' : ''}"`;

package/src/window-bridge.ts

@@ -24,6 +24,8 @@ export interface LiveState { state: string; model: string; streaming?: AgentMess
 export interface WindowEvent {
   kind: 'event'; name: 'started' | 'message' | 'status' | 'finished'; text: string; from?: 'user' | 'agent';
   message?: AgentMessage; live?: LiveState;
+  /** On `started` in an attached window: the subagent's spawn title, if it has one. */
+  title?: string;
 }
 type Frame = Request | Reply | WindowEvent;
 const errorText = (error: unknown) => error instanceof Error ? error.message : String(error);
@@ -38,7 +40,8 @@ function parse(value: unknown): Frame {
   const name = value.name, action = value.action, from = value.from;
   if (value.kind === 'event' && (name === 'started' || name === 'message' || name === 'status' || name === 'finished') && typeof value.text === 'string')
     return { kind: 'event', name, text: value.text, from: from === 'user' || from === 'agent' ? from : undefined,
-      message: isMessage(value.message) ? value.message : undefined, live: isLive(value.live) ? value.live : undefined };
+      message: isMessage(value.message) ? value.message : undefined, live: isLive(value.live) ? value.live : undefined,
+      title: typeof value.title === 'string' ? value.title : undefined };
   if (typeof value.id !== 'number' || !Number.isSafeInteger(value.id)) throw new Error('Invalid request ID');
   if (value.kind === 'reply' && (value.error === undefined || typeof value.error === 'string') && (value.text === undefined || typeof value.text === 'string'))
     return { kind: 'reply', id: value.id, error: value.error, text: value.text };
@@ -113,7 +116,7 @@ export async function serveWindows(directory: string, children: Children, availa
             const agents: AttachableAgent[] = available() ? children.history.list()
               .filter(info => !info.connected && !!children.live(info.id)
                 && (info.state === 'running' || info.state === 'waiting' || info.state === 'paused'))
-              .map(info => ({ id: info.id, task: info.task.slice(0, 200), state: info.state })) : [];
+              .map(info => ({ id: info.id, task: info.task.slice(0, 200), title: info.title, state: info.state })) : [];
             send({ kind: 'reply', id: frame.id, text: JSON.stringify(agents) }); return;
           } else if (frame.action === 'attach') {
             if (child) throw new Error('This window already has a conversation');
@@ -130,7 +133,7 @@ export async function serveWindows(directory: string, children: Children, availa
             // This socket borrows the existing session, never its lifetime, slot or report destination.
             // Other views (the main window's Agents page, other terminals) stay open alongside it.
             attached = true; child = id; finalMessages = live ? undefined : messages;
-            send({ kind: 'event', name: 'started', text: child });
+            send({ kind: 'event', name: 'started', text: child, title: info.title });
             drainMessages(messages, info);
           } else if (frame.action === 'start') {
             if (child) throw new Error('This window already has a conversation');
@@ -191,6 +194,10 @@ export async function serveWindows(directory: string, children: Children, availa
         if (task) { text = info.task; firstUser = false; }
         if (message.role === 'user') {
           // The task, and an interrupt, which continues with your queued messages, are yours too.
+          // Your messages show as you typed them, also inside an interrupt's prompt, not as the skill Pi expanded them into.
+          // Longest first: a skill sent without arguments is the start of the same skill sent with some.
+          const typed = info.guidance.flatMap(g => g.from === 'user' && g.sent ? [{ sent: g.sent, text: g.text }] : []).sort((a, b) => b.sent.length - a.sent.length);
+          for (const g of typed) text = text.replaceAll(g.sent, () => g.text);
           const yours = task || text.startsWith(INTERRUPTED) || info.guidance.some(g => g.from === 'user' && g.text === text.trim());
           if (text) send({ kind: 'event', name: 'message', from: yours ? 'user' : undefined, text: shorten(text, 200_000) });
           continue;
@@ -291,7 +298,7 @@ export async function connectWindow(directory: string, event: (event: WindowEven
   };
 }
 
-export interface AttachableAgent { id: string; task: string; state: string }
+export interface AttachableAgent { id: string; task: string; title?: string; state: string }
 /** Query the owner, not run metadata on disk: it knows which main/terminal views are actually open. */
 export async function listAttachableAgents(directory: string, timeout = 2000): Promise<AttachableAgent[]> {
   const deadline = Date.now() + timeout;
@@ -299,7 +306,7 @@ export async function listAttachableAgents(directory: string, timeout = 2000): P
   try {
     const agents: unknown = JSON.parse(await connection.request('list-agents', undefined, undefined, { timeout: Math.max(1, deadline - Date.now()) }) ?? '[]');
     if (!Array.isArray(agents) || !agents.every(agent => record(agent) && typeof agent.id === 'string'
-      && typeof agent.task === 'string' && (agent.state === 'running' || agent.state === 'waiting' || agent.state === 'paused')))
+      && typeof agent.task === 'string' && (agent.title === undefined || typeof agent.title === 'string') && (agent.state === 'running' || agent.state === 'waiting' || agent.state === 'paused')))
       throw new Error('Invalid background agent list from the profile owner');
     return agents;
   } finally { connection.close(); }