@giladbarnea/pi-user-agents 0.0.5 → 0.0.6

package/INTERNALS.md

@@ -67,6 +67,16 @@ The file itself appears on the child's first assistant message (`_persist` defer
 
 `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; squashing and session shutdown deliberately do not announce.
 
+## Attaching
+
+`/agent-attach <session-id>` reverses a detach. The id (or a unique prefix) resolves in one pass over the whole universe of candidates: the widget's rows (live and completed) united with file names in pi's default session directory for the cwd — the directory every dispatch creates children in. File names, not `SessionManager.list()`, because list() reads every session file whole, gigabytes in a mature project; the union, because a prefix unique among rows could otherwise mask an ambiguity with a detached file, and a live row whose file is not flushed yet must still resolve. A resolved id that is already a row short-circuits to the "View agent?" confirmation and nothing else — the idempotent case. The authority for "is a child of this session" is the child file's header: its `parentSession` path must equal the main session's file. That is the same field `/fork` writes, so a fork of the main session attaches too.
+
+The session file does not persist the dispatch options, so every dispatch writes a `pi-user-agents-dispatch` custom entry into the child — the forwarded pi tokens, the plain task, and the isolate flag. At attach the record replays through the same projections dispatch used (`buildChildResourceLoaderOptions`, `resolveToolOptions`), so `--tools`, `--no-extensions`, `--system-prompt` and friends survive the round trip instead of silently widening back to pi defaults. The model and thinking level deliberately come from the file, not the record: reattachment is pi's own resume path — `SessionManager.open` plus `createAgentSessionFromServices` on a non-empty manager takes `createAgentSession`'s has-existing-session branch — and the file reflects any later changes. A record-less child (dispatched before the record existed, or `/fork`-made) still attaches, with pi's default tools and resources.
+
+The dispatch preamble — built at the dispatch call site, sent verbatim by `runChildTurns` — doubles as the boundary marker: `splitAtDispatchBoundary` finds the first user message carrying it and recovers the child's own conversation for the overlay and the inherited base whose fingerprint re-arms the rebase fast-forward. The fingerprint compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries from a session file re-stamps their timestamps (and a branch summary's `fromId`), so `conversationFingerprint` drops those fields or a round-tripped base would never equal main's live context. Without a recognizable boundary (a fork child, or a child whose compaction summarized it away) the whole context attaches and the base is a sentinel that never matches, so `r` stays withheld.
+
+The attached agent parks idle first (`runAttachedTurns` waits for an instruction before running the shared turn loop), and its latest persisted response seeds `pendingSquashMessage`, so steering, `s`, and `r` work immediately without a new turn. A successful attach leaves an `Attached session …` breadcrumb — the detach line's counterpart — and both success states end with a "View agent?" confirmation that opens the overlay.
+
 ## 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.

package/README.md

@@ -95,6 +95,8 @@ 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.
 
+Or take it back as a background agent instead: `/agent-attach 0199c4f2` puts the session back in the widget — parked idle, restored as dispatched down to its `--tools` and the rest of its options — and offers to open it. A unique id prefix is enough, only this conversation's own agents qualify, and the transcript records the return: `Attached session 0199c4f2-…`.
+
 ### 5. Squash — or don't
 
 This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
@@ -154,7 +156,7 @@ Each row carries the agent's own footer gauge: it fills `▁▂▃▄▅▆▇
 
 ## Reference
 
-Everything goes through one command: `/agent [options] <task>`.
+Everything goes through one command: `/agent [options] <task>`. Its one companion, `/agent-attach <session-id>`, brings a detached session back into the widget.
 
 | Flag | Effect |
 |---|---|
@@ -187,6 +189,7 @@ Everything goes through one command: `/agent [options] <task>`.
 - [x] Agents stay alive until you end them — steer, interrupt, resume, across turns.
 - [x] Squash: a compact record of the exchange, delivered into the main context.
 - [x] Rebase: the raw conversation grafted onto the main session — fast-forward only, compaction-faithful.
+- [x] Attach: a detached session returns to the widget, restored as dispatched.
 - [x] Live syntax coloring and eager autocomplete for the `/agent` line.
 - [ ] Render an agent's compaction event in the overlay.
 - [ ] Wire the accepted-but-inert `pi` options.
@@ -194,7 +197,7 @@ Everything goes through one command: `/agent [options] <task>`.
 
 ## Under the hood
 
-Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase mechanism, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
+Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase and attach mechanisms, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
 
 ---
 

package/attach.ts

@@ -0,0 +1,339 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createAgentSessionFromServices, SessionManager } from "@earendil-works/pi-coding-agent";
+import { conversationFingerprint } from "./rebase.js";
+import {
+	assistantText,
+	buildChildResourceLoaderOptions,
+	createChildServices,
+	DISPATCH_PREAMBLE,
+	parseForwardedArgs,
+	reportAgentFailure,
+	resolveToolOptions,
+	runChildTurns,
+	subscribeToChildSession,
+	waitForInstruction,
+} from "./runner.js";
+import type {
+	AgentMessage,
+	AgentSession,
+	AttachedEntryData,
+	DispatchRecordData,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	Model,
+	RunningAgent,
+} from "./shared.js";
+import {
+	ATTACHED_ENTRY_TYPE,
+	DISPATCH_ENTRY_TYPE,
+	errorMessage,
+	formatModel,
+	formatModelLabel,
+	logSteering,
+} from "./shared.js";
+import { buildAgentResultMessage, reportCommandError } from "./transcript.js";
+import type { UserAgentWidget } from "./widget.js";
+
+/** A dispatch base that can never fingerprint-match a live context, so rebase stays withheld. */
+export const UNKNOWN_DISPATCH_BASE = "unknown-dispatch-base";
+
+export type DispatchBoundary = {
+	/** The main-session context the child inherited at dispatch — the rebase fast-forward base. */
+	base: AgentMessage[];
+	/** The child's own conversation, starting at the preambled dispatch message. */
+	conversation: AgentMessage[];
+	/** The dispatch task, preamble stripped. */
+	task: string;
+};
+
+/**
+ * Split a child's resolved context at its dispatch boundary — the first user message carrying
+ * the dispatch preamble. Undefined when no message carries it (a /fork child, or a child whose
+ * own compaction summarized the boundary away).
+ */
+export function splitAtDispatchBoundary(
+	messages: readonly AgentMessage[],
+): DispatchBoundary | undefined {
+	for (const [index, message] of messages.entries()) {
+		if (message.role !== "user") continue;
+		const text = userMessageText(message);
+		if (!text.startsWith(DISPATCH_PREAMBLE)) continue;
+		return {
+			base: messages.slice(0, index),
+			conversation: messages.slice(index),
+			task: text.slice(DISPATCH_PREAMBLE.length),
+		};
+	}
+	return undefined;
+}
+
+function userMessageText(message: Extract<AgentMessage, { role: "user" }>): string {
+	if (typeof message.content === "string") return message.content;
+	return message.content
+		.flatMap((part) => (part.type === "text" ? [part.text] : []))
+		.join("\n");
+}
+
+export type ChildSessionFileMatch = { sessionId: string; file: string };
+
+/**
+ * The session files in a directory whose id matches the query exactly or by prefix.
+ * Pi names session files `<timestamp>_<session-id>.jsonl`, so matching reads names only.
+ */
+export function matchChildSessionFiles(
+	query: string,
+	sessionDirectory: string,
+): ChildSessionFileMatch[] {
+	const fileNames = existsSync(sessionDirectory) ? readdirSync(sessionDirectory) : [];
+	return fileNames.flatMap((name) => {
+		const sessionId = sessionIdFromFileName(name);
+		if (sessionId === undefined || !sessionId.startsWith(query)) return [];
+		return [{ sessionId, file: join(sessionDirectory, name) }];
+	});
+}
+
+function sessionIdFromFileName(fileName: string): string | undefined {
+	if (!fileName.endsWith(".jsonl")) return undefined;
+	const separator = fileName.indexOf("_");
+	if (separator === -1) return undefined;
+	return fileName.slice(separator + 1, -".jsonl".length);
+}
+
+/** The dispatch record persisted in the child's file, or undefined for pre-record and /fork children. */
+export function readDispatchRecord(
+	childSessionManager: SessionManager,
+): DispatchRecordData | undefined {
+	for (const entry of childSessionManager.getEntries()) {
+		if (entry.type === "custom" && entry.customType === DISPATCH_ENTRY_TYPE)
+			return entry.data as DispatchRecordData | undefined;
+	}
+	return undefined;
+}
+
+/**
+ * Rebuild an idle, steerable RunningAgent from a reopened child session and its resolved model.
+ * The child's own conversation, task, latest response, and rebase base all come from the file;
+ * the dispatch record refines the task and context flag, and with no recognizable dispatch
+ * boundary the whole context attaches and rebase stays withheld.
+ */
+export function buildAttachedAgent(
+	sequenceNumber: number,
+	childSessionManager: SessionManager,
+	model: Model,
+	invocation: string,
+	record?: DispatchRecordData,
+): RunningAgent {
+	const contextMessages = childSessionManager.buildSessionContext().messages;
+	const boundary = splitAtDispatchBoundary(contextMessages);
+	const conversationMessages = structuredClone(boundary?.conversation ?? contextMessages);
+	const firstUserMessage = contextMessages.find((message) => message.role === "user");
+	const lastAssistantMessage = conversationMessages.findLast(
+		(message): message is Extract<AgentMessage, { role: "assistant" }> =>
+			message.role === "assistant",
+	);
+	const responseText = lastAssistantMessage ? assistantText(lastAssistantMessage).trim() : "";
+	const now = Date.now();
+	const agent: RunningAgent = {
+		id: `user-${sequenceNumber.toString(36)}`,
+		sessionId: childSessionManager.getSessionId(),
+		command: "agent",
+		inheritedContext: record
+			? !record.isolate
+			: boundary
+				? boundary.base.length > 0
+				: true,
+		model: formatModel(model),
+		modelLabel: formatModelLabel(model),
+		task:
+			record?.task ??
+			boundary?.task ??
+			(firstUserMessage === undefined ? "(no messages)" : userMessageText(firstUserMessage)),
+		invocation,
+		notifyMainAgent: false,
+		dispatchBaseFingerprint: boundary
+			? conversationFingerprint(boundary.base)
+			: UNKNOWN_DISPATCH_BASE,
+		mainContextState: "separate",
+		status: "idle",
+		startedAt: now,
+		turnStartedAt: now,
+		completedAt: now,
+		activeTools: new Map(),
+		toolUses: 0,
+		turnCount: 0,
+		responseText,
+		conversationMessages,
+		finished: Promise.resolve(),
+	};
+	if (responseText)
+		agent.pendingSquashMessage = buildAgentResultMessage(
+			agent,
+			{ ok: true, response: responseText },
+			{ display: false },
+		);
+	return agent;
+}
+
+/**
+ * The attached agent's lifecycle: bind the child's extensions, park until the user steers or
+ * retires it, then run turns exactly like a dispatched child. Every failure — the bind's
+ * included — settles through the shared error path, and the end shuts the child's extensions
+ * down.
+ */
+export async function runAttachedTurns(
+	pi: ExtensionAPI,
+	isShuttingDown: () => boolean,
+	session: AgentSession,
+	runningAgent: RunningAgent,
+	widget: UserAgentWidget,
+): Promise<void> {
+	let unsubscribe: (() => void) | undefined;
+	try {
+		await session.bindExtensions({ mode: "print" });
+		unsubscribe = subscribeToChildSession(session, runningAgent, widget);
+		// The user can detach during the extension bind, before this lifecycle parks.
+		if (runningAgent.aborted) return;
+		const instruction = await waitForInstruction(runningAgent, widget);
+		if (instruction !== undefined)
+			await runChildTurns(pi, isShuttingDown, instruction, session, runningAgent, widget);
+	} catch (error) {
+		reportAgentFailure(pi, isShuttingDown, runningAgent, widget, error);
+	} finally {
+		unsubscribe?.();
+		logSteering(runningAgent.id, "session-shutdown", { streaming: session.isStreaming });
+		await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+	}
+}
+
+export async function handleAttachCommand(
+	pi: ExtensionAPI,
+	runningAgents: Set<RunningAgent>,
+	widget: UserAgentWidget,
+	isShuttingDown: () => boolean,
+	nextAgentNumber: () => number,
+	args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	try {
+		await attachUserAgent(pi, runningAgents, widget, isShuttingDown, nextAgentNumber, args, ctx);
+	} catch (error) {
+		reportCommandError(pi, "agent-attach", args, ctx, errorMessage(error));
+	}
+}
+
+/**
+ * Reattach a detached child session as a live, parked agent row. Idempotent for a session
+ * that already has a row; errors for anything that is not a child session of this session.
+ * Both success states end by offering to open the agent's overlay.
+ */
+async function attachUserAgent(
+	pi: ExtensionAPI,
+	runningAgents: Set<RunningAgent>,
+	widget: UserAgentWidget,
+	isShuttingDown: () => boolean,
+	nextAgentNumber: () => number,
+	args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const query = args.trim();
+	if (!query || /\s/.test(query)) throw new Error("Usage: /agent-attach <child-session-id>");
+	if (ctx.hasUI) widget.setUI(ctx.ui);
+
+	// One resolution over the whole universe — attached rows and files on disk together — so a
+	// prefix unique among rows cannot mask an ambiguity with a detached session, and a live row
+	// whose file is not written yet still resolves. Dispatch creates children in pi's default
+	// session directory for the cwd; that is where the files are.
+	const attachedIds = widget.matchAttachedSessionIds(query);
+	const childSessionDirectory = SessionManager.create(ctx.cwd).getSessionDir();
+	const fileMatches = matchChildSessionFiles(query, childSessionDirectory);
+	const matchedSessionIds = [
+		...new Set([...attachedIds, ...fileMatches.map((match) => match.sessionId)]),
+	];
+	if (matchedSessionIds.length === 0) throw new Error(`No agent session matches "${query}"`);
+	if (matchedSessionIds.length > 1)
+		throw new Error(`"${query}" matches ${matchedSessionIds.length} sessions; use more characters`);
+	const sessionId = matchedSessionIds[0]!;
+
+	if (attachedIds.includes(sessionId)) {
+		await confirmViewAgent(ctx, widget, sessionId, "Agent already attached");
+		return;
+	}
+
+	const mainSessionFile = ctx.sessionManager.getSessionFile();
+	if (!mainSessionFile)
+		throw new Error("This session has no file; only a persisted session can attach agents");
+	const childSessionFile = fileMatches.find((match) => match.sessionId === sessionId)!.file;
+	const childSessionManager = SessionManager.open(childSessionFile);
+	if (childSessionManager.getHeader()?.parentSession !== mainSessionFile)
+		throw new Error(
+			`Session ${childSessionManager.getSessionId()} is not a child session of this session`,
+		);
+
+	// The record replays through the same projections dispatch uses; a record-less child (an old
+	// dispatch, or a /fork) restores pi defaults.
+	const record = readDispatchRecord(childSessionManager);
+	const dispatchArgs = parseForwardedArgs(record?.forwardedArgs ?? []);
+	const services = await createChildServices(
+		ctx,
+		buildChildResourceLoaderOptions(dispatchArgs, ctx.cwd),
+	);
+	// A non-empty session manager takes pi's resume path: messages, model, and thinking level
+	// are restored from the child's own file; tools and resources come from the dispatch record.
+	const { session, modelFallbackMessage } = await createAgentSessionFromServices({
+		services,
+		sessionManager: childSessionManager,
+		...resolveToolOptions(dispatchArgs),
+	});
+	const model = session.agent.state.model as Model | undefined;
+	if (!model) {
+		session.dispose();
+		throw new Error(modelFallbackMessage ?? "No model is available for the attached session");
+	}
+	if (modelFallbackMessage && ctx.hasUI) ctx.ui.notify(modelFallbackMessage, "warning");
+
+	const runningAgent = buildAttachedAgent(
+		nextAgentNumber(),
+		childSessionManager,
+		model,
+		`/agent-attach ${query}`,
+		record,
+	);
+	runningAgent.session = session;
+	runningAgents.add(runningAgent);
+	logSteering(runningAgent.id, "agent-attached", { sessionId: runningAgent.sessionId });
+	if (ctx.hasUI) {
+		widget.ensureTimer();
+		widget.update();
+	}
+	// No awaits between the add above and this assignment: every later failure settles inside
+	// the lifecycle, so the row can never outlive its own removal hook.
+	runningAgent.finished = runAttachedTurns(
+		pi,
+		isShuttingDown,
+		session,
+		runningAgent,
+		widget,
+	).finally(() => {
+		logSteering(runningAgent.id, "agent-disposed", { status: runningAgent.status });
+		runningAgent.session?.dispose();
+		runningAgents.delete(runningAgent);
+		widget.update();
+	});
+	// The detach breadcrumb's counterpart: after a reload the transcript still tells the truth.
+	pi.appendEntry<AttachedEntryData>(ATTACHED_ENTRY_TYPE, { sessionId: runningAgent.sessionId });
+	if (runningAgent.aborted) return;
+	await confirmViewAgent(ctx, widget, runningAgent.sessionId, "Agent attached");
+}
+
+/** The follow-up both success states share: offer to open the agent's overlay. */
+async function confirmViewAgent(
+	ctx: ExtensionCommandContext,
+	widget: UserAgentWidget,
+	sessionId: string,
+	title: string,
+): Promise<void> {
+	if (!ctx.hasUI) return;
+	const view = await ctx.ui.confirm(title, "View agent?");
+	if (view) widget.openViewer(sessionId);
+}

package/index.ts

@@ -2,6 +2,7 @@ import type {
 	MessageEndEvent,
 	MessageEndEventResult,
 } from "@earendil-works/pi-coding-agent";
+import { handleAttachCommand } from "./attach.js";
 import { registerAgentAutocomplete } from "./autocomplete.js";
 import { createRebaseDelivery, handleAgentCommand } from "./runner.js";
 import type {
@@ -52,6 +53,22 @@ export default function userAgent(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("agent-attach", {
+		description: "Reattach a detached agent session by id, back into the widget",
+		handler: async (args, ctx) => {
+			mainSessionContext = ctx;
+			await handleAttachCommand(
+				pi,
+				runningAgents,
+				widget,
+				() => shuttingDown,
+				() => ++nextAgentNumber,
+				args,
+				ctx,
+			);
+		},
+	});
+
 	pi.on("session_shutdown", async () => {
 		shuttingDown = true;
 		widget.dispose();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",

package/rebase.ts

@@ -8,10 +8,21 @@ type MainSessionManager = ExtensionCommandContext["sessionManager"];
  * Fingerprint a context snapshot for the rebase fast-forward precondition: the main session's
  * live context must still fingerprint-equal the base the child was dispatched from.
  *
+ * Compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries
+ * from a session file re-stamps their timestamps (and a branch summary's fromId), so a base
+ * round-tripped through a child's file would never equal main's live context otherwise.
+ *
  * @example conversationFingerprint([]) === conversationFingerprint([]) // true
  */
 export function conversationFingerprint(messages: readonly AgentMessage[]): string {
-	return JSON.stringify(messages);
+	return JSON.stringify(messages.map(fingerprintedMessage));
+}
+
+function fingerprintedMessage(message: AgentMessage): Omit<AgentMessage, "timestamp"> {
+	const { timestamp: _timestamp, ...content } = message;
+	if (content.role !== "branchSummary") return content;
+	const { fromId: _fromId, ...branchContent } = content;
+	return branchContent;
 }
 
 /** Rebuilding a session-sized context string is only worth doing when the branch tip moved. */

package/runner.ts

@@ -33,7 +33,9 @@ import type {
 	RunningAgent,
 	ThinkingLevel,
 } from "./shared.js";
+import type { DispatchRecordData } from "./shared.js";
 import {
+	DISPATCH_ENTRY_TYPE,
 	errorMessage,
 	formatModel,
 	formatModelLabel,
@@ -90,17 +92,10 @@ async function startUserAgent(
 ): Promise<void> {
 	const parsed = parseAgentCommand(args, command);
 	const parsedForwardedArgs = parseForwardedArgs(parsed.forwardedArgs);
-	const agentDir = getAgentDir();
-	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
-		projectTrusted: ctx.isProjectTrusted(),
-	});
-	const services = await createAgentSessionServices({
-		cwd: ctx.cwd,
-		agentDir,
-		settingsManager,
-		modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
-		resourceLoaderOptions: buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
-	});
+	const services = await createChildServices(
+		ctx,
+		buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
+	);
 	const forwarded = resolveForwardedOptions(parsedForwardedArgs, services.modelRuntime);
 	const selectedModel = forwarded.model ?? ctx.model;
 	if (!selectedModel) throw new Error("No current model is selected; pass -m MODELNAME");
@@ -112,6 +107,12 @@ async function startUserAgent(
 	const childSessionManager = SessionManager.create(services.cwd, undefined, {
 		parentSession: ctx.sessionManager.getSessionFile(),
 	});
+	// The dispatch record: /agent-attach restores tool and resource options from it later.
+	childSessionManager.appendCustomEntry(DISPATCH_ENTRY_TYPE, {
+		forwardedArgs: parsed.forwardedArgs,
+		task: parsed.task,
+		isolate: parsed.isolate,
+	} satisfies DispatchRecordData);
 	const runningAgent = createRunningAgent(
 		nextAgentNumber(),
 		childSessionManager.getSessionId(),
@@ -263,7 +264,7 @@ export function createRebaseDelivery(
 }
 
 /** Session inputs derived from forwarded pi CLI options, ready to hand to the child session. */
-type ChildResourceLoaderOptions = {
+export type ChildResourceLoaderOptions = {
 	systemPrompt?: string;
 	appendSystemPrompt?: string[];
 	additionalExtensionPaths?: string[];
@@ -276,14 +277,37 @@ type ChildResourceLoaderOptions = {
 	noContextFiles?: boolean;
 };
 
-type ForwardedOptions = {
-	model?: Model;
-	thinkingLevel?: ThinkingLevel;
+export type ChildToolOptions = {
 	tools?: string[];
 	excludeTools?: string[];
 	noTools?: "all" | "builtin";
 };
 
+type ForwardedOptions = ChildToolOptions & {
+	model?: Model;
+	thinkingLevel?: ThinkingLevel;
+};
+
+/** The cwd-bound services for one child session; the parent's ModelRuntime rides along (see INTERNALS). */
+export function createChildServices(
+	ctx: ExtensionCommandContext,
+	resourceLoaderOptions?: ChildResourceLoaderOptions,
+): Promise<AgentSessionServices> {
+	const agentDir = getAgentDir();
+	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
+		projectTrusted: ctx.isProjectTrusted(),
+	});
+	return createAgentSessionServices({
+		cwd: ctx.cwd,
+		agentDir,
+		settingsManager,
+		// The extension facade wraps the parent's runtime as a plain property; sharing it keeps
+		// extension-registered providers (their process-global dedup guard) available to the child.
+		modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
+		resourceLoaderOptions,
+	});
+}
+
 /** Parse forwarded pi CLI tokens once before model and session resolution. */
 export function parseForwardedArgs(forwardedArgs: string[]): Args {
 	const parsed = parseArgs(forwardedArgs);
@@ -382,12 +406,17 @@ export function resolveForwardedOptions(
 		}
 	}
 	if (parsed.thinking) forwarded.thinkingLevel = parsed.thinking;
+	return { ...forwarded, ...resolveToolOptions(parsed) };
+}
 
-	if (parsed.noTools) forwarded.noTools = "all";
-	else if (parsed.noBuiltinTools) forwarded.noTools = "builtin";
-	if (parsed.tools) forwarded.tools = parsed.tools;
-	if (parsed.excludeTools) forwarded.excludeTools = parsed.excludeTools;
-	return forwarded;
+/** Map parsed pi tool options onto child-session inputs; dispatch and attach share this. */
+export function resolveToolOptions(parsed: Args): ChildToolOptions {
+	const options: ChildToolOptions = {};
+	if (parsed.noTools) options.noTools = "all";
+	else if (parsed.noBuiltinTools) options.noTools = "builtin";
+	if (parsed.tools) options.tools = parsed.tools;
+	if (parsed.excludeTools) options.excludeTools = parsed.excludeTools;
+	return options;
 }
 
 export function buildChildResourceLoaderOptions(
@@ -449,29 +478,9 @@ async function runAgentLifecycle(
 			widget,
 		);
 		unsubscribe = subscribeToChildSession(session, runningAgent, widget);
-		await runChildTurns(pi, isShuttingDown, task, session, runningAgent, widget);
+		await runChildTurns(pi, isShuttingDown, DISPATCH_PREAMBLE + task, session, runningAgent, widget);
 	} catch (error) {
-		if (runningAgent.aborted) {
-			logSteering(runningAgent.id, "agent-aborted");
-			return;
-		}
-		const message = errorMessage(error);
-		logSteering(runningAgent.id, "agent-error", { error: message });
-		runningAgent.status = "error";
-		runningAgent.completedAt = Date.now();
-		runningAgent.error = message;
-		if (runningAgent.notifyMainAgent && isShuttingDown()) {
-			runningAgent.mainContextState = "separate";
-			return;
-		}
-		const resultMessage = buildAgentResultMessage(
-			runningAgent,
-			{ ok: false, error: message },
-			{ display: runningAgent.notifyMainAgent },
-		);
-		widget.addCompleted(runningAgent, resultMessage, { squashable: !runningAgent.notifyMainAgent });
-		if (postUserAgentResult(pi, isShuttingDown, runningAgent.notifyMainAgent, resultMessage))
-			runningAgent.status = "posted";
+		reportAgentFailure(pi, isShuttingDown, runningAgent, widget, error);
 	} finally {
 		unsubscribe?.();
 		if (session) {
@@ -481,16 +490,51 @@ async function runAgentLifecycle(
 	}
 }
 
-/** Run turns on an initialized child session until it posts, retires, or shuts down. */
+/** Settle a failed lifecycle: record the error and post the error card, unless the user aborted. */
+export function reportAgentFailure(
+	pi: ExtensionAPI,
+	isShuttingDown: () => boolean,
+	runningAgent: RunningAgent,
+	widget: UserAgentWidget,
+	error: unknown,
+): void {
+	if (runningAgent.aborted) {
+		logSteering(runningAgent.id, "agent-aborted");
+		return;
+	}
+	const message = errorMessage(error);
+	logSteering(runningAgent.id, "agent-error", { error: message });
+	runningAgent.status = "error";
+	runningAgent.completedAt = Date.now();
+	runningAgent.error = message;
+	if (runningAgent.notifyMainAgent && isShuttingDown()) {
+		runningAgent.mainContextState = "separate";
+		return;
+	}
+	const resultMessage = buildAgentResultMessage(
+		runningAgent,
+		{ ok: false, error: message },
+		{ display: runningAgent.notifyMainAgent },
+	);
+	widget.addCompleted(runningAgent, resultMessage, { squashable: !runningAgent.notifyMainAgent });
+	if (postUserAgentResult(pi, isShuttingDown, runningAgent.notifyMainAgent, resultMessage))
+		runningAgent.status = "posted";
+}
+
+/** Every dispatch prefixes its task with this; attach recognizes it as the child's dispatch boundary. */
+export const DISPATCH_PREAMBLE =
+	"You are running in an ephemeral, forked background process now, concurrently with the main session. ";
+
+/** Run turns on an initialized child session until it posts, retires, or shuts down. The initial instruction is sent verbatim. */
 export async function runChildTurns(
 	pi: ExtensionAPI,
 	isShuttingDown: () => boolean,
-	task: string,
+	initialInstruction: string,
 	session: AgentSession,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<void> {
-	let instruction = `You are running in an ephemeral, forked background process now, concurrently with the main session. ${task}`;
+	let instruction = initialInstruction;
 	while (true) {
 		const turnMessageStart = session.agent.state.messages.length;
 		if (!runningAgent.interruptRequested) {
@@ -745,7 +789,7 @@ export function subscribeToChildSession(
 	});
 }
 
-function assistantText(message: Extract<AgentMessage, { role: "assistant" }>): string {
+export function assistantText(message: Extract<AgentMessage, { role: "assistant" }>): string {
 	return message.content
 		.filter((part) => part.type === "text")
 		.map((part) => part.text)

package/shared.ts

@@ -15,7 +15,7 @@ export type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
 export type Theme = ExtensionCommandContext["ui"]["theme"];
 export type UIContext = ExtensionCommandContext["ui"];
 
-export type AgentCommandName = "agent";
+export type AgentCommandName = "agent" | "agent-attach";
 export type MainContextState = "separate" | "will-squash" | "squashed" | "rebased";
 export type AgentStatus =
 	| "starting"
@@ -44,6 +44,19 @@ export type DetachedEntryData = {
 	sessionId: string;
 };
 
+export type AttachedEntryData = {
+	sessionId: string;
+};
+
+/** Persisted in the child session at dispatch: the facts attach cannot recover from messages alone. */
+export type DispatchRecordData = {
+	/** The pi CLI tokens the dispatch forwarded, e.g. ["--tools", "read,grep"]. */
+	forwardedArgs: string[];
+	/** The plain task, without the dispatch preamble. */
+	task: string;
+	isolate: boolean;
+};
+
 export type RebaseStats = {
 	messageCount: number;
 	tokenEstimate: number;
@@ -75,7 +88,8 @@ export type AgentCommandDetails = {
 	agentId?: string;
 	command: AgentCommandName;
 	mainContextState?: MainContextState;
-	inheritedContext: boolean;
+	/** Absent on command-error cards: an error has no inherited-or-isolated notion. */
+	inheritedContext?: boolean;
 	model: string;
 	modelLabel: string;
 	task: string;
@@ -207,6 +221,8 @@ export class TimedConfirmation<Target> {
 export const MESSAGE_TYPE = "pi-user-agents";
 export const DETACHED_ENTRY_TYPE = "pi-user-agents-detached";
 export const REBASED_ENTRY_TYPE = "pi-user-agents-rebased";
+export const ATTACHED_ENTRY_TYPE = "pi-user-agents-attached";
+export const DISPATCH_ENTRY_TYPE = "pi-user-agents-dispatch";
 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,
+	AttachedEntryData,
 	DetachedEntryData,
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -14,6 +15,7 @@ import type {
 	Theme,
 } from "./shared.js";
 import {
+	ATTACHED_ENTRY_TYPE,
 	contextLabel,
 	DETACHED_ENTRY_TYPE,
 	escapeAttribute,
@@ -44,7 +46,6 @@ export function reportCommandError(
 		display: true,
 		details: {
 			command,
-			inheritedContext: command === "agent",
 			model: "",
 			modelLabel: "",
 			task: args.trim(),
@@ -222,6 +223,11 @@ export function registerUserAgentRenderer(pi: ExtensionAPI): void {
 			? new Text(theme.fg("dim", `Detached session ${entry.data.sessionId}`), 1, 0)
 			: undefined,
 	);
+	pi.registerEntryRenderer<AttachedEntryData>(ATTACHED_ENTRY_TYPE, (entry, _state, theme) =>
+		entry.data
+			? new Text(theme.fg("dim", `Attached session ${entry.data.sessionId}`), 1, 0)
+			: undefined,
+	);
 	pi.registerEntryRenderer<RebasedEntryData>(REBASED_ENTRY_TYPE, (entry, _state, theme) =>
 		entry.data ? new Text(theme.fg("dim", formatRebasedLine(entry.data)), 1, 0) : undefined,
 	);
@@ -324,7 +330,7 @@ function buildRendererParts(content: string, details: AgentCommandDetails | unde
 	const parts: string[] = [];
 	if (details?.modelLabel) parts.push(details.modelLabel);
 	else if (details?.model) parts.push(details.model);
-	if (details) parts.push(contextLabel(details.inheritedContext));
+	if (details?.inheritedContext !== undefined) parts.push(contextLabel(details.inheritedContext));
 	const mainContext = mainContextLabel(details?.mainContextState);
 	if (mainContext) parts.push(mainContext);
 	if (details?.turnCount) parts.push(formatTurns(details.turnCount));

package/widget.ts

@@ -266,6 +266,21 @@ export class UserAgentWidget {
 		this.update();
 	}
 
+	/** Session ids with a live row or completed card, matched by exact id or prefix. */
+	matchAttachedSessionIds(query: string): string[] {
+		return this.entries()
+			.map((entry) => entry.agent.sessionId)
+			.filter((sessionId) => sessionId.startsWith(query));
+	}
+
+	/** Open the overlay of the row holding this session, as if the user selected it. */
+	openViewer(sessionId: string): boolean {
+		const entry = this.entries().find((candidate) => candidate.agent.sessionId === sessionId);
+		if (!entry) return false;
+		this.openSelected(entry.agent);
+		return true;
+	}
+
 	private clampSelection(): void {
 		const total = this.entries().length;
 		if (total === 0) {