@giladbarnea/pi-user-agents 0.0.2 → 0.0.4

package/INTERNALS.md

@@ -30,6 +30,23 @@ A plain `<user_agent>` tag follows it. The tag contains only the model and inher
 
 One selection rule builds the body. It keeps every user message. Before each next user message, it keeps only the latest assistant response. It applies the same rule after the final user message. Tool calls, thinking, tool results, and other message roles stay out.
 
+## Child session persistence
+
+Every dispatched agent gets a persisted `SessionManager.create(cwd, undefined, { parentSession })` rather than an in-memory one, so its conversation is an ordinary Pi session file from birth. `parentSession` is a *path*, and it records the main session that dispatched the agent — the same field `/fork` uses, surfaced by `SessionManager.list()` as `parentSessionPath`. There is no API to promote an in-memory session to disk later: `SessionManager` fixes `persist` at construction, and both `_persist()` and `_rewriteFile()` return early when it is false, so `setSessionFile()` on an in-memory manager sets a path and writes nothing.
+
+Two ordering constraints follow from `createAgentSession`:
+
+1. **Build the session while its manager is still empty.** Pi writes the `model_change` and `thinking_level_change` entries only on the empty-session path. Seed messages first and those entries never appear, so a resumed child falls back to `findInitialModel` instead of the model it was dispatched with.
+2. **Route the inherited snapshot through the session manager.** Persistence runs off message events, so the old `session.agent.state.messages = inherited` assignment never reached the file. `persistInheritedMessages` appends it entry by entry, then the agent state is set to the same list.
+
+That snapshot is already compaction-resolved, so at most one `compactionSummary` leads it. Each role takes its own append method — `appendCompaction`, `branchWithSummary`, `appendCustomMessageEntry`, `appendMessage` — because pi's own compaction and branch bookkeeping locates boundaries by entry type, and a summary written as a plain message entry would be invisible to it. `appendCompaction` wants a `firstKeptEntryId` the replay cannot know, but `buildContextEntries` only consults it for entries *before* the compaction entry; a leading compaction has none, so the value is never read.
+
+The file itself appears on the child's first assistant message (`_persist` defers until then). An agent dispatched with `-i` that never answers therefore leaves nothing behind, while an agent that inherited context has a file immediately.
+
+## Detaching
+
+`d` `d` ends the live child session and drops its widget row. The session file is untouched, and the transcript gets a `pi-user-agents-detached` custom entry naming the session id so it can be resumed later. Both detach paths funnel through `closeRunning` and `removeCompleted`, which is where the announcement is made; joining and session shutdown deliberately do not announce.
+
 ## Runtime sharing
 
 Child agent sessions share the parent's `ModelRuntime` instance. This is critical because extension-registered providers (like `claude-bridge`) use a global `Symbol.for` dedup guard — they register once per process and skip subsequent loads. A child session with its own fresh runtime would never receive the provider, leaving it without auth for bridge-backed models.
@@ -38,7 +55,7 @@ The shared runtime is extracted from the parent's `ModelRegistry` facade (`ctx.m
 
 ## Model name & alias resolution
 
-User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. The extension checks for an exact name match before falling through to the SDK's `resolveCliModel`, which only checks `model.id` (never `model.name`) and otherwise falls back to substring matching — where "opus" collides with dozens of built-in models across the catalog.
+User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. Other model values must exactly match a live model ID or canonical `provider/id` reference before the extension calls the SDK's `resolveCliModel`. Partial and custom model IDs are rejected.
 
 > **Note (known issue):** `enabledModels` (i.e., “Scoped models”) currently have no special role in how the extension resolves models. They should be promoted to the same precedence level as user-defined model names in a future fix.
 
@@ -48,7 +65,7 @@ Exact names should be unique: duplicate aliases silently select the first model,
 
 ### Semantic command coloring
 
-While you type, the editor paints `/agent` lines from the same semantic scan that drives submission parsing (see `PARSER_SPEC.md` §11): the command in the theme's `accent`, recognized leading options in `syntaxKeyword`, and valid values (quotes included) in `syntaxString`. Invalid thinking levels, unresolved model IDs or aliases, and unknown provider or tool names use `error`, as do explicitly blocked Pi options such as `-c`/`--continue` and options typed after the task prose has begun — along with their values. Validation comes from Pi's argument parser, model resolver, and live catalogs rather than a second editor grammar. Prose, unknown dash-words, quoted spans, and escaped words stay plain. All colors come from the active Pi theme, so custom themes and hot reload apply automatically.
+While you type, the editor paints `/agent` lines from the same semantic scan that drives submission parsing (see `PARSER_SPEC.md` §11): the command in the theme's `accent`, recognized leading options in `syntaxType`, and valid values (quotes included) in `syntaxString`. Invalid thinking levels, unresolved model IDs or aliases, and unknown provider or tool names use `error`, including blocked Pi options such as `-c`/`--continue` and `-p`/`--print`, plus options typed after the task prose has begun — along with their values. Validation comes from Pi's argument parser, model resolver, and live catalogs rather than a second editor grammar. Prose, unknown dash-words, quoted spans, and escaped words stay plain. All colors come from the active Pi theme, so custom themes and hot reload apply automatically.
 
 ### Eager argument completion
 

package/PARSER_SPEC.md

@@ -45,9 +45,10 @@ leading whitespace (unchanged from today).
 | `-i`, `--isolate` | boolean | Consumed here; `isolate = true` |
 | `-j`, `--join` | boolean | Consumed here; `context = true` |
 
-`-m` and `--model` are one semantic option. Both resolve once through Pi's
-`resolveCliModel()` path, and a preceding `--provider` scopes either spelling. `-j` is the
-extension's join option. A model option with no value and no remaining task ends in the normal
+`-m` and `--model` are one semantic option. Both require an exact live model ID, canonical
+`provider/id` reference, or user-defined alias before resolving through Pi's `resolveCliModel()`
+path. A preceding `--provider` scopes either spelling. `-j` is the extension's join option.
+A model option with no value and no remaining task ends in the normal
 **usage error**.
 
 ### 3b. Known pi options — declared statically; added to `forwardedArgs`
@@ -59,8 +60,7 @@ extension's join option. A model option with no value and no remaining task ends
 **Boolean** (consume no value):
 `--resume`/`-r`, `--no-session`, `--no-tools`/`-nt`, `--no-builtin-tools`/`-nbt`,
 `--no-extensions`/`-ne`, `--no-skills`/`-ns`, `--no-prompt-templates`/`-np`, `--no-themes`,
-`--no-context-files`/`-nc`, `--verbose`, `--approve`/`-a`, `--no-approve`/`-na`, `--offline`,
-`--print`/`-p`.
+`--no-context-files`/`-nc`, `--verbose`, `--approve`/`-a`, `--no-approve`/`-na`, `--offline`.
 
 Notes:
 - The shared declaration is a snapshot of `pi --help`; it is maintained by hand. There is no
@@ -77,7 +77,6 @@ Notes:
   The dequoted value is stored as **one element** in `forwardedArgs`
   (e.g. `["--system-prompt", "I am psyched"]`), so pi's `parseArgs` maps it as a single value.
   If a value opens with a quote but has no matching close, fall back to the whitespace-delimited token.
-- `--print`/`-p` is modeled as **boolean** here (pi's optional-value form would eat prose).
 
 Value examples:
 - `--system-prompt "I am psyched"` → value `I am psyched`.
@@ -86,8 +85,8 @@ Value examples:
 - `-m "gpt56s"` → `forwardedArgs` contains `--model`, `gpt56s`.
 
 ### 3c. Blocked pi options — rejected
-`-c`/`--continue`, `--theme <path>`, `--models`, `--export`, `--list-models`, `-h`/`--help`,
-`-v`/`--version`.
+`-c`/`--continue`, `-p`/`--print`, `--theme <path>`, `--models`, `--export`, `--list-models`,
+`-h`/`--help`, `-v`/`--version`.
 Appearing in **args mode** (leading) → hard **error**:
 `"/agent does not support <opt>; it would disrupt the background agent run."`
 
@@ -239,10 +238,9 @@ source spans:
 - `option` — a recognized, non-blocked leading option (extension-owned or forwarded);
 - `value` — the value consumed by a leading value-taking option. A quoted value's span
   includes its surrounding quotes;
-- `invalid-value` — a leading closed-set value rejected by the same canonical validation
-  used at submission and session creation: Pi's argument parser for thinking levels, the
-  child model resolver for model IDs and user-defined aliases, and the live provider and
-  tool catalogs;
+- `invalid-value` — a leading closed-set value rejected by the same validation used at
+  submission and session creation: Pi's argument parser for thinking levels, exact live model
+  IDs or user-defined aliases, and the live provider and tool catalogs;
 - `blocked` — a blocked option in args mode, plus the value a blocked value-taking option
   would consume (`--theme ./theme.json` yields two `blocked` tokens). Unlike
   `parseAgentCommand`, the scan never throws: it records the first blocked token and keeps
@@ -259,6 +257,6 @@ prose → usage error), so parsing and coloring cannot drift.
 cursor analysis (§10) and shifts token spans into editor-line coordinates.
 
 The editor coloring layer (`editor-coloring.ts`) maps token semantics onto Pi theme
-variables — command `accent`, options `syntaxKeyword`, valid values `syntaxString`, and
+variables — command `accent`, options `syntaxType`, valid values `syntaxString`, and
 invalid, blocked, or misplaced tokens `error` — by repainting the laid-out chunk text after
 word-wrap layout, so editing, wrapping, cursor behavior, and autocomplete are untouched.

package/README.md

@@ -36,17 +36,26 @@ The first preserves the session's knowledge before the context window fills, wit
 
 ### 2. Watch
 
-Every agent gets a row in a widget under the editor: status, task, live activity, and a one-cell context meter.
+Every agent gets a row in a widget under the editor: status, task, model, turn count, tool uses, elapsed time, a one-cell context meter, and the last line of live activity.
 
-```text
-✓ User agents
-  ↑↓ select · Enter view · x dispose · Esc back
-└─ ⏺ ✓ /agent ▇ i am testing the widget now - read a ton...
-     ⎿  Loaded several large Pi source and documentation...
-```
+<a href="screenshots/below-editor-widget.png">
+  <img src="screenshots/below-editor-widget.png" width="100%" alt="The user agents widget under the editor, showing one finished agent and its latest output">
+</a>
+
+<div align="center"><em>The widget sits under the editor and stays out of your way.</em></div>
+
+<br>
 
 Press `←` or `↓` from the editor to focus the widget, pick an agent, press `Enter`, and its overlay opens: the full conversation, streaming live, following the tail as it grows. Scroll up to pause following; `End` resumes it. Tool calls render as proper views — `read`, `edit`, `write`, `grep`, `find`, `ls`, and `bash` each get a dedicated format, everything else a readable generic one.
 
+<a href="screenshots/overlay.png">
+  <img src="screenshots/overlay.png" width="100%" alt="The agent overlay: a rendered bash call, its output, a todo update, and the final response, over the dimmed main conversation">
+</a>
+
+<div align="center"><em>The overlay, over a main conversation that never paused.</em></div>
+
+<br>
+
 The context meter is the agent's own footer gauge in one cell: it fills `▁▂▃▄▅▆▇█` against that agent's model context window and shifts color through the same stages as Pi's footer (dim, then muted at 40%, warning at 65%, error at 85%).
 
 ### 3. Steer
@@ -55,9 +64,19 @@ A background agent is not fire-and-forget — it's a session you can talk to.
 
 Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need; every completed turn posts its own result card.
 
-`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or disposal. In fact, nothing disposes an agent except you: pressing `x` twice, joining it, or ending the Pi session.
+`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or detaching. In fact, nothing ends an agent except you: pressing `d` twice, joining it, or ending the Pi session.
+
+### 4. Detach
+
+Every dispatched agent gets its own Pi session on disk, exactly like the one you're sitting in. When a row has served its purpose, press `d` twice: the agent stops, its row leaves the widget, and its session file is left untouched. The transcript records which one it was:
+
+```
+Detached session 0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce
+```
+
+Pick it back up whenever you like — `/resume 0199c4f2`, or `pi -r` and choose it from the list. It resumes as an ordinary Pi session with its full history, its model, and its thinking level, and from there it is a normal agent you talk to directly.
 
-### 4. Join — or don't
+### 5. Join — or don't
 
 This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
 
@@ -104,7 +123,7 @@ Everything goes through one command: `/agent [options] <task>`.
 | Editor | `←` / `↓` | Focus the agents widget |
 | Widget | `↑` `↓` · `Enter` | Select an agent · open its overlay |
 | Widget / overlay | `Ctrl+x` | Interrupt the current turn (agent stays alive) |
-| Widget / overlay | `x` `x` | Dispose the agent (twice to confirm) |
+| Widget / overlay | `d` `d` | Detach the agent, keeping its session (twice to confirm) |
 | Widget / overlay | `Esc` | Back |
 | Overlay | `Enter` | Steer mid-turn, or start another turn when idle |
 | Overlay | `j` | Join the conversation into the main context |
@@ -113,8 +132,9 @@ Everything goes through one command: `/agent [options] <task>`.
 
 ## Good to know
 
-- Result cards persist across session reloads; live agent sessions don't. After a reload you keep every card, not the steerable sessions.
-- Some accepted `pi` options have no effect on a background run (the session, approval, offline, API-key, and print families). They parse; they just don't do anything yet.
+- Every dispatch writes a real session file, so dispatched agents show up in `/resume` and `pi -r` alongside your own sessions. An agent that never answered leaves no file.
+- Result cards persist across session reloads; the widget doesn't. After a reload you keep every card, and every agent's session is still on disk — but the steerable rows are gone. Reach them with `/resume`.
+- Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet.
 - `c` copies via `pbcopy`, so it's macOS-only for now.
 - The overlay caps very large tool outputs and omits thinking entries.
 

package/agent-viewer.ts

@@ -32,7 +32,7 @@ import {
 } from "./tool-render/index.js";
 
 export type ViewableAgent = RunningAgent | CompletedAgent;
-export type AgentViewerAction = "hide" | "dispose";
+export type AgentViewerAction = "hide" | "detach";
 
 export type ActivityDescription = {
 	text: string;
@@ -141,7 +141,7 @@ function truncateMiddle(
 
 const VIEWER_CHROME_LINES = 6;
 const VIEWER_MIN_VIEWPORT = 3;
-const VIEWER_HEIGHT_PCT = 70;
+const VIEWER_HEIGHT_PCT = 85;
 
 /** Focus-capturing overlay that shows an agent's live or finished response. */
 export class AgentViewer implements Component {
@@ -149,7 +149,7 @@ export class AgentViewer implements Component {
 	private autoScroll = true;
 	private lastWidth = 0;
 	private justCopied = false;
-	private confirmingDispose = false;
+	private confirmingDetach = false;
 	private composer: Input | undefined;
 	/** Rich tool rendering is far too costly to repeat on every 100 ms widget tick. */
 	private renderedContent: { key: string; lines: string[] } | undefined;
@@ -166,22 +166,22 @@ export class AgentViewer implements Component {
 
 	handleInput(data: string): void {
 		if (matchesKey(data, "ctrl+x") && isLiveAgent(this.agent)) {
-			this.confirmingDispose = false;
+			this.confirmingDetach = false;
 			this.interrupt();
 			this.tui.requestRender();
 			return;
 		}
 		if (this.composer) {
-			this.confirmingDispose = false;
+			this.confirmingDetach = false;
 			this.composer.handleInput(data);
 			this.tui.requestRender();
 			return;
 		}
-		if (matchesKey(data, "x")) {
-			this.requestDispose();
+		if (matchesKey(data, "d")) {
+			this.requestDetach();
 			return;
 		}
-		this.confirmingDispose = false;
+		this.confirmingDetach = false;
 		if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 			this.done("hide");
 			return;
@@ -253,6 +253,7 @@ export class AgentViewer implements Component {
 			renderAgentContextMeter(this.agent, th),
 			th.fg("dim", status),
 			...stats.map((stat) => th.fg("dim", stat)),
+			th.fg("dim", this.agent.sessionId),
 		]
 			.filter(Boolean)
 			.join(` ${th.fg("dim", "·")} `);
@@ -310,8 +311,8 @@ export class AgentViewer implements Component {
 					mainContext ? th.fg("dim", mainContext) : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Esc hide") : "",
 					th.fg(
-						this.confirmingDispose ? "error" : "dim",
-						this.confirmingDispose ? "x again to confirm" : "x dispose",
+						this.confirmingDetach ? "error" : "dim",
+						this.confirmingDetach ? "d again to confirm" : "d detach",
 					),
 				].filter(Boolean),
 			);
@@ -325,12 +326,12 @@ export class AgentViewer implements Component {
 
 	dispose(): void {}
 
-	private requestDispose(): void {
-		if (this.confirmingDispose) {
-			this.done("dispose");
+	private requestDetach(): void {
+		if (this.confirmingDetach) {
+			this.done("detach");
 			return;
 		}
-		this.confirmingDispose = true;
+		this.confirmingDetach = true;
 		this.tui.requestRender();
 	}
 

package/command-line.ts

@@ -292,13 +292,13 @@ function booleanOptionsWithoutChildEffect(): AgentOptionDefinition[] {
 		legacyBooleanOption("approve", ["--approve", "-a"]),
 		legacyBooleanOption("no-approve", ["--no-approve", "-na"]),
 		legacyBooleanOption("offline", ["--offline"]),
-		legacyBooleanOption("print", ["--print", "-p"]),
 	];
 }
 
 function blockedOptions(): AgentOptionDefinition[] {
 	return [
 		blockedOption("continue", ["-c", "--continue"]),
+		blockedOption("print", ["-p", "--print"]),
 		blockedOption("theme", ["--theme"], "value"),
 		blockedOption("models", ["--models"]),
 		blockedOption("export", ["--export"]),

package/editor-coloring.ts

@@ -11,7 +11,7 @@ export type StyleTheme = { fg(color: ThemeColor, text: string): string };
 
 export const AGENT_SEMANTIC_COLORS: Record<AgentTokenSemantic | "command", ThemeColor> = {
 	command: "accent",
-	option: "syntaxKeyword",
+	option: "syntaxType",
 	value: "syntaxString",
 	"invalid-value": "error",
 	blocked: "error",
@@ -36,7 +36,7 @@ type ColoredEditor = ColoringRuntimeEditor & { [COLORED_EDITOR]?: true };
  * Map an editor line to theme-colored spans via the shared semantic scan.
  * Returns undefined for lines that are not agent commands.
  *
- * @example computeAgentColorSpans("/agent -m gpt56s go")?.[1] // { start: 7, end: 9, color: "syntaxKeyword" }
+ * @example computeAgentColorSpans("/agent -m gpt56s go")?.[1] // { start: 7, end: 9, color: "syntaxType" }
  */
 export function computeAgentColorSpans(
 	line: string,

package/index.ts

@@ -4,15 +4,22 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { registerAgentAutocomplete } from "./autocomplete.js";
 import { handleAgentCommand } from "./runner.js";
-import type { AgentCommandDetails, ExtensionAPI, RunningAgent } from "./shared.js";
-import { MESSAGE_TYPE } from "./shared.js";
+import type {
+	AgentCommandDetails,
+	DetachedEntryData,
+	ExtensionAPI,
+	RunningAgent,
+} from "./shared.js";
+import { DETACHED_ENTRY_TYPE, MESSAGE_TYPE } from "./shared.js";
 import { registerUserAgentRenderer } from "./transcript.js";
 import { UserAgentWidget } from "./widget.js";
 
 export default function userAgent(pi: ExtensionAPI): void {
 	const runningAgents = new Set<RunningAgent>();
-	const widget = new UserAgentWidget(runningAgents, (message) =>
-		pi.sendMessage(message, { triggerTurn: true }),
+	const widget = new UserAgentWidget(
+		runningAgents,
+		(message) => pi.sendMessage(message, { triggerTurn: true }),
+		(sessionId) => pi.appendEntry<DetachedEntryData>(DETACHED_ENTRY_TYPE, { sessionId }),
 	);
 	let shuttingDown = false;
 	let nextAgentNumber = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",
@@ -23,6 +23,7 @@
   "files": [
     "*.ts",
     "tool-render",
+    "screenshots",
     "README.md",
     "PARSER_SPEC.md",
     "INTERNALS.md",

package/runner.ts

@@ -96,7 +96,18 @@ async function startUserAgent(
 		services.modelRuntime.getModel(selectedModel.provider, selectedModel.id) ?? selectedModel;
 	const thinkingLevel = forwarded.thinkingLevel ?? pi.getThinkingLevel();
 	const inheritedMessages = parsed.isolate ? [] : buildInheritedMessages(ctx);
-	const runningAgent = createRunningAgent(nextAgentNumber(), command, model, parsed, invocation);
+	// A real session file from birth: the child outlives the widget row and stays resumable.
+	const childSessionManager = SessionManager.create(services.cwd, undefined, {
+		parentSession: ctx.sessionManager.getSessionFile(),
+	});
+	const runningAgent = createRunningAgent(
+		nextAgentNumber(),
+		childSessionManager.getSessionId(),
+		command,
+		model,
+		parsed,
+		invocation,
+	);
 
 	runningAgents.add(runningAgent);
 	logSteering(runningAgent.id, "agent-created", { command, taskLength: parsed.task.length });
@@ -117,6 +128,7 @@ async function startUserAgent(
 		forwarded,
 		inheritedMessages,
 		services,
+		childSessionManager,
 		runningAgent,
 		widget,
 	).finally(() => {
@@ -129,6 +141,7 @@ async function startUserAgent(
 
 function createRunningAgent(
 	sequenceNumber: number,
+	sessionId: string,
 	command: AgentCommandName,
 	model: Model,
 	parsed: ParsedAgentCommand,
@@ -136,6 +149,7 @@ function createRunningAgent(
 ): RunningAgent {
 	return {
 		id: `user-${sequenceNumber.toString(36)}`,
+		sessionId,
 		command,
 		inheritedContext: !parsed.isolate,
 		model: formatModel(model),
@@ -239,6 +253,30 @@ export function createAgentValueValidator(
 	};
 }
 
+/**
+ * Return whether a model value exactly names a live ID, canonical reference, or user alias.
+ *
+ * @example isExactCatalogModelReference([{ provider: "openai", id: "gpt-5" } as Model], "openai/gpt-5") // true
+ */
+function isExactCatalogModelReference(
+	models: readonly Model[],
+	value: string,
+	provider: string | undefined,
+): boolean {
+	const normalizedValue = value.toLowerCase();
+	const normalizedProvider = provider?.toLowerCase();
+	const exactAliasMatch = models.some(
+		(model) => model.name?.toLowerCase() === normalizedValue,
+	);
+	const exactReferenceMatch = models.some(
+		(model) =>
+			(normalizedProvider === undefined || model.provider.toLowerCase() === normalizedProvider) &&
+			(model.id.toLowerCase() === normalizedValue ||
+				`${model.provider}/${model.id}`.toLowerCase() === normalizedValue),
+	);
+	return exactAliasMatch || exactReferenceMatch;
+}
+
 /** Resolve forwarded runtime options against the child session's model runtime. */
 export function resolveForwardedOptions(
 	parsed: Args,
@@ -246,6 +284,10 @@ export function resolveForwardedOptions(
 ): ForwardedOptions {
 	const forwarded: ForwardedOptions = {};
 	if (parsed.model) {
+		if (!isExactCatalogModelReference(modelRuntime.getModels(), parsed.model, parsed.provider)) {
+			const display = parsed.provider ? `${parsed.provider}/${parsed.model}` : parsed.model;
+			throw new Error(`Model "${display}" not found in the live model catalog.`);
+		}
 		const nameMatch = modelRuntime
 			.getModels()
 			.find((m) => m.name?.toLowerCase() === parsed.model!.toLowerCase());
@@ -314,6 +356,7 @@ async function runAgentLifecycle(
 	forwarded: ForwardedOptions,
 	inheritedMessages: AgentMessage[],
 	services: AgentSessionServices,
+	childSessionManager: SessionManager,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<void> {
@@ -326,6 +369,7 @@ async function runAgentLifecycle(
 			forwarded,
 			inheritedMessages,
 			services,
+			childSessionManager,
 			runningAgent,
 			widget,
 		);
@@ -459,12 +503,15 @@ async function createChildSession(
 	forwarded: ForwardedOptions,
 	inheritedMessages: AgentMessage[],
 	services: AgentSessionServices,
+	childSessionManager: SessionManager,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<AgentSession> {
+	// Built while the session is still empty: that is the only path on which pi records the
+	// model and thinking level, and without those entries a resumed child falls back to defaults.
 	const { session } = await createAgentSessionFromServices({
 		services,
-		sessionManager: SessionManager.inMemory(services.cwd),
+		sessionManager: childSessionManager,
 		model,
 		thinkingLevel,
 		tools: forwarded.tools,
@@ -481,12 +528,38 @@ async function createChildSession(
 	await session.bindExtensions({ mode: "print" });
 	logSteering(runningAgent.id, "session-bound", { streaming: session.isStreaming });
 	if (inheritedMessages.length > 0) {
+		persistInheritedMessages(childSessionManager, inheritedMessages);
 		session.agent.state.messages = inheritedMessages;
 		logSteering(runningAgent.id, "context-inherited", { messageCount: inheritedMessages.length });
 	}
 	return session;
 }
 
+/**
+ * Mirror the inherited snapshot into the child's session file so a resumed child sees the
+ * same conversation the live one saw. Each role goes through its own append method: the
+ * snapshot is already compaction-resolved, so its summary leads the child's own branch.
+ */
+export function persistInheritedMessages(
+	sessionManager: SessionManager,
+	messages: readonly AgentMessage[],
+): void {
+	for (const message of messages) {
+		if (message.role === "compactionSummary")
+			sessionManager.appendCompaction(message.summary, "", message.tokensBefore);
+		else if (message.role === "branchSummary")
+			sessionManager.branchWithSummary(sessionManager.getLeafId(), message.summary);
+		else if (message.role === "custom")
+			sessionManager.appendCustomMessageEntry(
+				message.customType,
+				message.content,
+				message.display,
+				message.details,
+			);
+		else sessionManager.appendMessage(message);
+	}
+}
+
 /** Parks an idle agent until the user resumes it with another instruction (resolves with it) or retires it (resolves undefined). */
 export function waitForInstruction(
 	agent: RunningAgent,

package/shared.ts

@@ -40,6 +40,10 @@ export type AgentEntryData = {
 	details: AgentCommandDetails;
 };
 
+export type DetachedEntryData = {
+	sessionId: string;
+};
+
 export type AgentResultMessage = {
 	customType: string;
 	content: string;
@@ -67,6 +71,8 @@ export type AgentCommandDetails = {
 
 export type RunningAgent = {
 	id: string;
+	/** The child's own Pi session, resumable with `/resume <sessionId>` after the agent is detached. */
+	sessionId: string;
 	command: AgentCommandName;
 	inheritedContext: boolean;
 	model: string;
@@ -106,6 +112,7 @@ export type RunningAgent = {
 
 export type CompletedAgent = {
 	id: string;
+	sessionId: string;
 	command: AgentCommandName;
 	modelLabel: string;
 	task: string;
@@ -123,6 +130,7 @@ export type CompletedAgent = {
 };
 
 export const MESSAGE_TYPE = "pi-user-agents";
+export const DETACHED_ENTRY_TYPE = "pi-user-agents-detached";
 export const WIDGET_KEY = "pi-user-agents";
 export const STEERING_LOG_PATH = `${tmpdir()}/pi-user-agents-steer.log`;
 

package/transcript.ts

@@ -6,6 +6,7 @@ import type {
 	AgentEntryData,
 	AgentMessage,
 	AgentResultMessage,
+	DetachedEntryData,
 	ExtensionAPI,
 	ExtensionCommandContext,
 	RunningAgent,
@@ -13,6 +14,7 @@ import type {
 } from "./shared.js";
 import {
 	contextLabel,
+	DETACHED_ENTRY_TYPE,
 	escapeAttribute,
 	extractTag,
 	formatMs,
@@ -212,6 +214,11 @@ export function registerUserAgentRenderer(pi: ExtensionAPI): void {
 					)
 				: undefined,
 	);
+	pi.registerEntryRenderer<DetachedEntryData>(DETACHED_ENTRY_TYPE, (entry, _state, theme) =>
+		entry.data
+			? new Text(theme.fg("dim", `Detached session ${entry.data.sessionId}`), 0, 0)
+			: undefined,
+	);
 }
 
 function liveAgentCard(

package/widget.ts

@@ -49,12 +49,13 @@ export class UserAgentWidget {
 	private active = false;
 	private selectedIndex = 0;
 	private viewerOpen = false;
-	private disposeConfirmationTarget: ViewableAgent | undefined;
+	private detachConfirmationTarget: ViewableAgent | undefined;
 	private readonly completedAgents: CompletedAgent[] = [];
 
 	constructor(
 		private readonly runningAgents: Set<RunningAgent>,
 		private readonly sendJoinedResult: (message: AgentResultMessage) => void,
+		private readonly announceDetached: (sessionId: string) => void,
 	) {}
 
 	setUI(ui: UIContext): void {
@@ -63,7 +64,7 @@ export class UserAgentWidget {
 		this.ui = ui;
 		this.widgetRegistered = false;
 		this.tui = undefined;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 		this.inputUnsub = ui.onTerminalInput((data) => this.handleKey(data));
 	}
 
@@ -74,6 +75,7 @@ export class UserAgentWidget {
 	): void {
 		this.completedAgents.push({
 			id: agent.id,
+			sessionId: agent.sessionId,
 			command: agent.command,
 			modelLabel: agent.modelLabel,
 			task: agent.task,
@@ -140,7 +142,7 @@ export class UserAgentWidget {
 		this.widgetRegistered = false;
 		this.tui = undefined;
 		this.active = false;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 	}
 
 	private clear(): void {
@@ -155,7 +157,7 @@ export class UserAgentWidget {
 		}
 		this.active = false;
 		this.selectedIndex = 0;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 	}
 
 	private runningAgentsForWidget(): RunningAgent[] {
@@ -199,13 +201,13 @@ export class UserAgentWidget {
 		}
 
 		if (matchesKey(data, "down")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			this.selectedIndex = Math.min(entries.length - 1, this.selectedIndex + 1);
 			this.update();
 			return { consume: true };
 		}
 		if (matchesKey(data, "up")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			if (this.selectedIndex === 0) {
 				this.deactivate();
 				return { consume: true };
@@ -225,17 +227,17 @@ export class UserAgentWidget {
 			selected?.kind === "running" &&
 			isLiveAgent(selected.agent)
 		) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			this.interruptRunning(selected.agent);
 			return { consume: true };
 		}
 		if (matchesKey(data, "enter")) {
-			this.disposeConfirmationTarget = undefined;
+			this.detachConfirmationTarget = undefined;
 			if (selected) this.openSelected(selected.agent);
 			return { consume: true };
 		}
-		if (matchesKey(data, "x") && selected) {
-			if (!this.confirmDispose(selected.agent)) return { consume: true };
+		if (matchesKey(data, "d") && selected) {
+			if (!this.confirmDetach(selected.agent)) return { consume: true };
 			if (selected.kind === "running") this.closeRunning(selected.agent);
 			else this.dismissCompleted(selected.agent);
 			return { consume: true };
@@ -245,12 +247,12 @@ export class UserAgentWidget {
 		return undefined;
 	}
 
-	private confirmDispose(target: ViewableAgent): boolean {
-		if (this.disposeConfirmationTarget === target) {
-			this.disposeConfirmationTarget = undefined;
+	private confirmDetach(target: ViewableAgent): boolean {
+		if (this.detachConfirmationTarget === target) {
+			this.detachConfirmationTarget = undefined;
 			return true;
 		}
-		this.disposeConfirmationTarget = target;
+		this.detachConfirmationTarget = target;
 		this.update();
 		return false;
 	}
@@ -258,7 +260,7 @@ export class UserAgentWidget {
 	private deactivate(): void {
 		this.active = false;
 		this.selectedIndex = 0;
-		this.disposeConfirmationTarget = undefined;
+		this.detachConfirmationTarget = undefined;
 		this.update();
 	}
 
@@ -290,7 +292,7 @@ export class UserAgentWidget {
 							if (isRunningAgent(agent)) this.interruptRunning(agent);
 						},
 					),
-				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "70%" } },
+				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "85%" } },
 			)
 			.then(
 				(action) => this.onViewerClosed(agent, action),
@@ -298,10 +300,12 @@ export class UserAgentWidget {
 			);
 	}
 
+	/** Detaching ends the live session and leaves its session file on disk, untouched. */
 	private closeRunning(agent: RunningAgent): void {
 		agent.aborted = true;
 		void agent.session?.abort();
 		agent.retire?.();
+		this.announceDetached(agent.sessionId);
 		this.update();
 	}
 
@@ -368,12 +372,12 @@ export class UserAgentWidget {
 
 	private onViewerClosed(agent: ViewableAgent, action: AgentViewerAction): void {
 		this.viewerOpen = false;
-		if (action === "dispose" && isRunningAgent(agent) && this.runningAgents.has(agent)) {
+		if (action === "detach" && isRunningAgent(agent) && this.runningAgents.has(agent)) {
 			this.closeRunning(agent);
 			return;
 		}
 		const completedAgent = this.completedAgents.find((candidate) => candidate.id === agent.id);
-		if (action === "dispose" && completedAgent) this.removeCompleted(completedAgent);
+		if (action === "detach" && completedAgent) this.removeCompleted(completedAgent);
 		else this.update();
 	}
 
@@ -384,6 +388,7 @@ export class UserAgentWidget {
 	private removeCompleted(agent: CompletedAgent): void {
 		const index = this.completedAgents.indexOf(agent);
 		if (index >= 0) this.completedAgents.splice(index, 1);
+		this.announceDetached(agent.sessionId);
 		const total = this.entries().length;
 		if (total === 0) {
 			this.deactivate();
@@ -413,18 +418,18 @@ export class UserAgentWidget {
 			lines.push(truncateToWidth(`  ${theme.fg("dim", "←/↓ select agent")}`, width));
 		} else {
 			const selected = entries[this.selectedIndex];
-			const confirmingDispose = this.disposeConfirmationTarget === selected?.agent;
+			const confirmingDetach = this.detachConfirmationTarget === selected?.agent;
 			const segments = [theme.fg("accent", "↑↓ select"), theme.fg("accent", "Enter view")];
 			if (
-				!confirmingDispose &&
+				!confirmingDetach &&
 				selected?.kind === "running" &&
 				isLiveAgent(selected.agent)
 			)
 				segments.push(theme.fg("accent", "Ctrl+x interrupt"));
 			segments.push(
 				theme.fg(
-					confirmingDispose ? "error" : "accent",
-					confirmingDispose ? "x again to confirm" : "x dispose",
+					confirmingDetach ? "error" : "accent",
+					confirmingDetach ? "d again to confirm" : "d detach",
 				),
 				theme.fg("accent", "Esc back"),
 			);