@oai404iao/pi-subagent 0.2.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ Compatibility: Pi 0.84.2 or newer; tested against 0.84.2.
   - `fork`: one-shot child seeded through the parent's latest completed turn
 - **Two lifecycles**
   - foreground one-shot runs return the child's final answer
-  - background continuable runs return a child session id immediately
+  - background continuable runs return a durable agent id immediately
 - **Foreground-only policy** that removes background scheduling and lifecycle controls
 - **Independent context and session** for every child
 - **Bundled presets without filesystem writes by default**, with opt-in
@@ -242,6 +242,7 @@ See [`config.example.json`](config.example.json) and [`config.schema.json`](conf
   "defaultBackground": true,
   "reportDelivery": "wakeup",
   "inheritExtensions": false,
+  "openAIIdentity": false,
   "maxOutputBytes": 51200
 }
 ```
@@ -255,10 +256,21 @@ See [`config.example.json`](config.example.json) and [`config.schema.json`](conf
 | `defaultBackground` | `true` | Default scheduling for fresh `subagent` calls when background execution is enabled. |
 | `reportDelivery` | `wakeup` | `wakeup` starts/queues a parent turn; `quiet` waits for the parent's next turn. |
 | `inheritExtensions` | `false` | Load other Pi extensions in child runtimes. This package filters itself out; explicit agent tool ceilings still apply. |
+| `openAIIdentity` | `false` | For OpenAI Responses child models, inject only the named `pi-codex-minimal-tools` identity lifecycle inline. Codex Session/Thread/Turn/Window ids remain owned and serialized by that package. |
 | `maxOutputBytes` | `51200` | Cap for parent-visible foreground output, reports, and settlement notices. Full output remains in the child session. |
 
 Invalid configuration and unknown child tool names fail loud before the child's first model request.
 
+`openAIIdentity` and `inheritExtensions` are independent. The former adds only
+the lightweight Codex identity lifecycle even when normal extension inheritance
+is disabled. Enable `inheritExtensions` as well when the child should receive
+the complete separately installed Codex extension tool surface such as
+`web_search` and `apply_patch`.
+
+The Codex adapter is an optional package dependency. If an installation omits
+optional dependencies, `openAIIdentity: true` fails before the child starts
+with an actionable missing-adapter error.
+
 ### Foreground-only mode
 
 ```json
@@ -301,7 +313,11 @@ The caller waits for one isolated child run. Only the child's last non-empty ass
 
 ### Continuable
 
-The start tool resolves at prompt preflight acceptance and returns the stable child session id. When an activation settles:
+The start tool resolves at prompt preflight acceptance and returns the child's durable
+agent id (UUIDv7). Agent ids are independent of Pi session (file) ids: they are
+generated once per subagent, recorded in the child's session as `pi-subagent/agent`,
+and chained through `parentAgentId` in the descriptor, so children stay addressable
+even when a parent session is forked or re-created. When an activation settles:
 
 1. the runtime sends the parent a settlement notice with the stop reason and closing message;
 2. the child runtime is disposed once its owned descendants are done;

package/config.example.json

@@ -7,5 +7,6 @@
   "defaultBackground": true,
   "reportDelivery": "wakeup",
   "inheritExtensions": false,
+  "openAIIdentity": false,
   "maxOutputBytes": 51200
 }

package/config.schema.json

@@ -50,6 +50,11 @@
       "description": "Load the parent's other Pi extensions in child runtimes. pi-subagent itself is filtered out and explicit agent tool ceilings still apply.",
       "default": false
     },
+    "openAIIdentity": {
+      "type": "boolean",
+      "description": "Inject the pi-codex-minimal-tools identity lifecycle as a named inline extension for OpenAI Responses child models.",
+      "default": false
+    },
     "maxOutputBytes": {
       "type": "integer",
       "minimum": 1024,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oai404iao/pi-subagent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Durable, continuable subagents for Pi with spawn/fork providers and lifecycle controls.",
   "repository": {
     "type": "git",
@@ -37,6 +37,9 @@
     "@earendil-works/pi-tui": ">=0.84.2",
     "typebox": "*"
   },
+  "optionalDependencies": {
+    "@oai404iao/pi-codex-minimal-tools": "1.4.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.2",
     "@earendil-works/pi-ai": "^0.84.2",
@@ -84,5 +87,5 @@
       "optional": true
     }
   },
-  "gitHead": "ef42984c0e40ef1f26ead4b4c7d149b21280e66b"
+  "gitHead": "a93559be8f8b02739310c492b36270b13607fbf9"
 }

package/src/catalog.ts

@@ -4,7 +4,7 @@ import type { SessionView } from "./providers.ts";
 import type { CatalogDiagnostic, SubagentDescriptor } from "./types.ts";
 
 export interface PersistedDescriptor {
-	id: string;
+	agentId: string;
 	sessionFile: string;
 	descriptor: SubagentDescriptor;
 }
@@ -44,7 +44,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 				if (headerParent !== folded.descriptor.parentSessionFile) {
 					diagnostics.push({
 						kind: "diagnostic",
-						id: manager.getSessionId(),
+						piSessionId: manager.getSessionId(),
 						reason: "corrupt",
 						sessionFile: info.path,
 						...(headerParent ? { parentSessionFile: headerParent } : {}),
@@ -53,7 +53,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 					return;
 				}
 				descriptors.push({
-					id: manager.getSessionId(),
+					agentId: folded.descriptor.agentId,
 					sessionFile: info.path,
 					descriptor: folded.descriptor,
 				});
@@ -61,7 +61,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 				const headerParent = manager.getHeader()?.parentSession;
 				diagnostics.push({
 					kind: "diagnostic",
-					id: manager.getSessionId(),
+					piSessionId: manager.getSessionId(),
 					reason: "corrupt",
 					sessionFile: info.path,
 					...(headerParent ? { parentSessionFile: headerParent } : {}),
@@ -71,7 +71,7 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 		} catch (error) {
 			diagnostics.push({
 				kind: "diagnostic",
-				id: info.id,
+				piSessionId: info.id,
 				reason: "unavailable",
 				sessionFile: info.path,
 				...(info.parentSessionPath ? { parentSessionFile: info.parentSessionPath } : {}),
@@ -82,8 +82,11 @@ export async function readPersistedCatalog(session: SessionView): Promise<Persis
 
 	descriptors.sort(
 		(left, right) =>
-			left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) || left.id.localeCompare(right.id),
+			left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) ||
+			left.agentId.localeCompare(right.agentId),
+	);
+	diagnostics.sort((left, right) =>
+		left.piSessionId.localeCompare(right.piSessionId),
 	);
-	diagnostics.sort((left, right) => left.id.localeCompare(right.id));
 	return { descriptors, diagnostics };
 }

package/src/config.ts

@@ -13,6 +13,7 @@ export const DEFAULT_SETTINGS: Readonly<SubagentSettings> = {
 	defaultBackground: true,
 	reportDelivery: "wakeup",
 	inheritExtensions: false,
+	openAIIdentity: false,
 	maxOutputBytes: 50 * 1024,
 };
 
@@ -25,6 +26,7 @@ const CONFIG_KEYS = new Set([
 	"defaultBackground",
 	"reportDelivery",
 	"inheritExtensions",
+	"openAIIdentity",
 	"maxOutputBytes",
 ]);
 
@@ -147,6 +149,10 @@ function applyConfig(
 			config.inheritExtensions === undefined
 				? settings.inheritExtensions
 				: parseBoolean(config.inheritExtensions, "inheritExtensions", source),
+		openAIIdentity:
+			config.openAIIdentity === undefined
+				? settings.openAIIdentity
+				: parseBoolean(config.openAIIdentity, "openAIIdentity", source),
 		maxOutputBytes:
 			config.maxOutputBytes === undefined
 				? settings.maxOutputBytes

package/src/coordinator.ts

@@ -1,13 +1,13 @@
-import { randomUUID } from "node:crypto";
 import { join, relative, resolve } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Model } from "@earendil-works/pi-ai";
+import { type Model, uuidv7 } from "@earendil-works/pi-ai";
 import {
 	type AgentSessionEvent,
 	type AgentToolResult,
 	type AgentToolUpdateCallback,
 	type ExtensionAPI,
 	type ExtensionContext,
+	type InlineExtension,
 	type ModelRegistry,
 	type ToolDefinition,
 	type CreateAgentSessionRuntimeFactory,
@@ -75,6 +75,10 @@ import {
 
 const REPORT_CUSTOM_TYPE = "pi-subagent/report";
 const SETTLED_CUSTOM_TYPE = "pi-subagent/settled";
+const AGENT_CUSTOM_TYPE = "pi-subagent/agent";
+const LINEAGE_CUSTOM_TYPE = "pi-subagent/lineage";
+const AGENT_ID_PATTERN =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const MAX_TRACE_ITEMS = 100;
 const MAX_TRACE_TEXT = 4000;
 const BACKGROUND_CONTROL_TOOLS = new Set([
@@ -107,7 +111,7 @@ export type DelegationOutcome =
 	| { kind: "foreground"; details: DelegationDetails; result: SubagentRunResult };
 
 interface ParentRef {
-	id: string;
+	agentId: string;
 	depth: number;
 	cwd: string;
 	sessionManager: SessionView;
@@ -125,8 +129,8 @@ interface ParentRef {
 }
 
 interface Activation {
-	id: string;
-	epochId: string;
+	agentId: string;
+	runId: string;
 	descriptor: SubagentDescriptor;
 	parent: ParentRef;
 	runtime: AgentSessionRuntime;
@@ -158,7 +162,7 @@ interface CreateActivationOptions {
 }
 
 interface CatalogRecord {
-	id: string;
+	agentId: string;
 	descriptor: SubagentDescriptor;
 	sessionFile?: string;
 	active?: Activation;
@@ -191,6 +195,41 @@ function errorText(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Read the durable pi-subagent control id recorded for a session, if any.
+ *
+ * The latest entry wins because a copied/forked Pi session may contain older
+ * identity checkpoints.
+ */
+function readAgentId(session: Pick<SessionView, "getEntries">): string | undefined {
+	const entries = session.getEntries();
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (!entry) continue;
+		if (entry.type !== "custom" || entry.customType !== AGENT_CUSTOM_TYPE) continue;
+		const data = entry.data as { agentId?: unknown } | undefined;
+		if (
+			typeof data?.agentId === "string"
+			&& AGENT_ID_PATTERN.test(data.agentId)
+		) {
+			return data.agentId;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Resolve the provider-neutral control id for a session, creating it on first
+ * use. In-memory SessionManager instances retain custom entries too.
+ */
+function ensureAgentId(session: SessionView): string {
+	const existing = readAgentId(session);
+	if (existing) return existing;
+	const agentId = uuidv7();
+	session.appendCustomEntry(AGENT_CUSTOM_TYPE, { agentId });
+	return agentId;
+}
+
 function stopReasonHeadline(reason: SubagentStopReason): string {
 	switch (reason) {
 		case "completed":
@@ -213,6 +252,7 @@ function makeRuntimeSettings(descriptor: SubagentDescriptor): SubagentSettings {
 		defaultBackground: descriptor.runtime.defaultBackground,
 		reportDelivery: descriptor.runtime.reportDelivery,
 		inheritExtensions: descriptor.runtime.inheritExtensions,
+		openAIIdentity: descriptor.runtime.openAIIdentity,
 		maxOutputBytes: descriptor.runtime.maxOutputBytes,
 	};
 }
@@ -222,6 +262,29 @@ function isPathInside(parent: string, child: string): boolean {
 	return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
 }
 
+function isOpenAIResponsesModel(model: Model<any>): boolean {
+	return model.api === "openai-responses"
+		|| model.api === "openai-codex-responses";
+}
+
+async function loadCodexIdentityInlineExtension(
+	parentSessionManager: SessionView,
+): Promise<InlineExtension> {
+	try {
+		const integration = await import(
+			"@oai404iao/pi-codex-minimal-tools/subagent-inline"
+		);
+		return integration.createCodexSubagentInlineExtension({
+			parentSessionManager,
+		});
+	} catch (error) {
+		throw new Error(
+			"openAIIdentity requires @oai404iao/pi-codex-minimal-tools with its subagent-inline export",
+			{ cause: error },
+		);
+	}
+}
+
 export class SubagentCoordinator {
 	private readonly providers = new ProviderRegistry();
 	private readonly active = new Map<string, Activation>();
@@ -278,10 +341,15 @@ export class SubagentCoordinator {
 		const descriptor = folded.kind === "valid" ? folded.descriptor : undefined;
 		const modelRuntime = runtimeFromRegistry(ctx.modelRegistry);
 		return {
-			id: ctx.sessionManager.getSessionId(),
+			agentId: readAgentId(ctx.sessionManager) ?? ensureAgentId(
+				ctx.sessionManager as unknown as SessionView,
+			),
 			depth: descriptor?.depth ?? 0,
 			cwd: ctx.cwd,
-			sessionManager: ctx.sessionManager,
+			// ExtensionContext narrows the live SessionManager to a read-only
+			// view; appending the agent entry through the same instance keeps
+			// the in-memory tree and the session file consistent.
+			sessionManager: ctx.sessionManager as unknown as SessionView,
 			modelRuntime,
 			model: ctx.model,
 			thinkingLevel: ctx.thinkingLevel ?? "off",
@@ -362,12 +430,17 @@ export class SubagentCoordinator {
 		const model = this.resolveModel(parent, agent);
 		const thinkingLevel = agent.thinking ?? parent.thinkingLevel;
 		const prepared = await provider.prepare(parent, mode);
+		parent.agentId = ensureAgentId(parent.sessionManager);
+		const openAIIdentityEnabled =
+			settings.openAIIdentity && isOpenAIResponsesModel(model);
 		const descriptor: SubagentDescriptor = {
-			version: 1,
+			version: 2,
 			mode,
 			provider: providerName,
 			label: input.description.trim(),
-			parentSessionId: parent.id,
+			agentId: uuidv7(),
+			parentAgentId: parent.agentId,
+			parentPiSessionId: parent.sessionManager.getSessionId(),
 			...(parent.sessionManager.getSessionFile()
 				? { parentSessionFile: parent.sessionManager.getSessionFile() }
 				: {}),
@@ -385,9 +458,25 @@ export class SubagentCoordinator {
 				defaultBackground: settings.defaultBackground,
 				reportDelivery: settings.reportDelivery,
 				inheritExtensions: settings.inheritExtensions,
+				openAIIdentity: openAIIdentityEnabled,
 				maxOutputBytes: settings.maxOutputBytes,
 			},
 		};
+		prepared.sessionManager.appendCustomEntry(AGENT_CUSTOM_TYPE, {
+			agentId: descriptor.agentId,
+		});
+		prepared.sessionManager.appendCustomEntry(LINEAGE_CUSTOM_TYPE, {
+			version: 1,
+			agentId: descriptor.agentId,
+			parentAgentId: descriptor.parentAgentId,
+			parentPiSessionId: descriptor.parentPiSessionId,
+			relation: descriptor.provider,
+			agentName: descriptor.agent.name,
+			openAIIdentity: openAIIdentityEnabled,
+			...(descriptor.parentSessionFile
+				? { parentSessionFile: descriptor.parentSessionFile }
+				: {}),
+		});
 
 		let activation: Activation | undefined;
 		try {
@@ -399,7 +488,7 @@ export class SubagentCoordinator {
 				onUpdate,
 			});
 			if (mode === "continuable" && parent.activation) {
-				parent.activation.ownedChildren.add(activation.id);
+				parent.activation.ownedChildren.add(activation.agentId);
 			}
 			const started = this.startPrompt(activation, input.prompt, signal, mode === "continuable");
 			await started.accepted;
@@ -456,7 +545,7 @@ export class SubagentCoordinator {
 				prepared: coldPrepared,
 				isNew: false,
 			});
-			if (parent.activation) parent.activation.ownedChildren.add(activation.id);
+			if (parent.activation) parent.activation.ownedChildren.add(activation.agentId);
 		} else {
 			this.assertDirectParent(parent, activation.descriptor);
 		}
@@ -484,7 +573,7 @@ export class SubagentCoordinator {
 		const target = this.active.get(targetId);
 		if (!target) return;
 		if (!(await this.isDescendantOf(parent, target.descriptor))) {
-			throw new Error(`subagent ${targetId} is not a live descendant of ${parent.id}`);
+			throw new Error(`subagent ${targetId} is not a live descendant of ${parent.agentId}`);
 		}
 		target.status = "failed";
 		void target.runtime.session.abort().catch((error) => {
@@ -495,16 +584,16 @@ export class SubagentCoordinator {
 	async list(parent: ParentRef, scope: "children" | "descendants"): Promise<CatalogEntry[]> {
 		const catalog = await this.catalogRecords(parent);
 		const records = catalog.records;
-		const byId = new Map(records.map((record) => [record.id, record]));
+		const byId = new Map(records.map((record) => [record.agentId, record]));
 		const children: CatalogChild[] = [];
 		for (const record of records) {
 			if (record.descriptor.mode !== "continuable") continue;
-			const distance = this.distanceFrom(parent.id, record.descriptor, byId);
+			const distance = this.distanceFrom(parent.agentId, record.descriptor, byId);
 			if (distance === undefined || (scope === "children" && distance !== 1)) continue;
 			children.push({
 				kind: "child",
-				id: record.id,
-				parentId: record.descriptor.parentSessionId,
+				agentId: record.agentId,
+				parentAgentId: record.descriptor.parentAgentId,
 				depth: distance,
 				descriptor: record.descriptor,
 				...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
@@ -517,7 +606,8 @@ export class SubagentCoordinator {
 		}
 		children.sort(
 			(left, right) =>
-				left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) || left.id.localeCompare(right.id),
+				left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) ||
+				left.agentId.localeCompare(right.agentId),
 		);
 		const parentFile = parent.sessionManager.getSessionFile();
 		const diagnostics = parentFile
@@ -533,7 +623,7 @@ export class SubagentCoordinator {
 			throw new Error("report is available only to continuable subagents");
 		}
 		const truncated = truncateUtf8(output, child.descriptor.runtime.maxOutputBytes);
-		const content = `Background subagent ${child.id} reported:\n\n${truncated.text}${
+		const content = `Background subagent ${child.agentId} reported:\n\n${truncated.text}${
 			truncated.truncated ? `\n\n[Report truncated; ${truncated.omittedBytes} bytes omitted.]` : ""
 		}`;
 		await child.parent.deliver(
@@ -541,7 +631,7 @@ export class SubagentCoordinator {
 			content,
 			{
 				kind: "report",
-				childId: child.id,
+				childAgentId: child.agentId,
 				label: child.descriptor.label,
 				...(truncated.truncated ? { truncated: true } : {}),
 			},
@@ -653,7 +743,7 @@ export class SubagentCoordinator {
 							text: `message queued as the next turn for subagent ${params.subagent_id}`,
 						},
 					],
-					details: { kind: "control", action: "send", id: params.subagent_id } satisfies ControlDetails,
+					details: { kind: "control", action: "send", agentId: params.subagent_id } satisfies ControlDetails,
 				};
 			},
 		});
@@ -670,7 +760,7 @@ export class SubagentCoordinator {
 				await this.interrupt(this.parentForActivation(activation), params.agent_id);
 				return {
 					content: [{ type: "text", text: `interrupt requested for agent ${params.agent_id}` }],
-					details: { kind: "control", action: "interrupt", id: params.agent_id } satisfies ControlDetails,
+					details: { kind: "control", action: "interrupt", agentId: params.agent_id } satisfies ControlDetails,
 				};
 			},
 		});
@@ -706,7 +796,7 @@ export class SubagentCoordinator {
 				await this.report(activation, params.output);
 				return {
 					content: [{ type: "text", text: `report accepted by the agent that started you` }],
-					details: { kind: "control", action: "report", id: activation.id } satisfies ControlDetails,
+					details: { kind: "control", action: "report", agentId: activation.agentId } satisfies ControlDetails,
 				};
 			},
 		});
@@ -717,7 +807,7 @@ export class SubagentCoordinator {
 	outcomeToolResult(outcome: DelegationOutcome): AgentToolResult<DelegationDetails> {
 		if (outcome.kind === "continuable") {
 			return {
-				content: [{ type: "text", text: `started subagent ${outcome.details.id}` }],
+				content: [{ type: "text", text: `started subagent ${outcome.details.agentId}` }],
 				details: outcome.details,
 			};
 		}
@@ -740,10 +830,12 @@ export class SubagentCoordinator {
 		if (entries.length === 0) return "(no subagents)";
 		return entries
 			.map((entry) => {
-				if (entry.kind === "diagnostic") return `${entry.id} [diagnostic: ${entry.reason}]`;
+				if (entry.kind === "diagnostic") {
+					return `${entry.piSessionId} [diagnostic: ${entry.reason}]`;
+				}
 				const location =
-					scope === "descendants" ? ` parent=${entry.parentId} depth=${entry.depth}` : "";
-				return `${entry.id} [${entry.status}]${location} — ${entry.descriptor.label} (${entry.descriptor.agent.name})`;
+					scope === "descendants" ? ` parent=${entry.parentAgentId} depth=${entry.depth}` : "";
+				return `${entry.agentId} [${entry.status}]${location} — ${entry.descriptor.label} (${entry.descriptor.agent.name})`;
 			})
 			.join("\n");
 	}
@@ -801,6 +893,14 @@ export class SubagentCoordinator {
 				`cannot materialize subagent: model ${descriptor.model.provider}/${descriptor.model.id} is unavailable`,
 			);
 		}
+		const extensionFactories: InlineExtension[] =
+			descriptor.runtime.openAIIdentity && isOpenAIResponsesModel(model)
+				? [
+						await loadCodexIdentityInlineExtension(
+							options.parent.sessionManager,
+						),
+					]
+				: [];
 
 		const appendSystemPrompt = [
 			descriptor.agent.systemPrompt,
@@ -836,10 +936,13 @@ export class SubagentCoordinator {
 					noExtensions: !descriptor.runtime.inheritExtensions,
 					noThemes: true,
 					appendSystemPrompt,
+					extensionFactories,
 					extensionsOverride: (base) => ({
 						...base,
 						extensions: base.extensions.filter(
-							(extension) => !isPathInside(this.packageRoot, extension.resolvedPath),
+							(extension) =>
+								extension.resolvedPath.startsWith("<inline:")
+								|| !isPathInside(this.packageRoot, extension.resolvedPath),
 						),
 					}),
 				},
@@ -935,8 +1038,8 @@ export class SubagentCoordinator {
 			}
 
 			activation = {
-				id: runtime.session.sessionId,
-				epochId: randomUUID(),
+				agentId: descriptor.agentId,
+				runId: uuidv7(),
 				descriptor,
 				parent: options.parent,
 				runtime,
@@ -954,7 +1057,7 @@ export class SubagentCoordinator {
 				disposed: false,
 			};
 			activation.unsubscribe = runtime.session.subscribe((event) => this.observe(activation!, event));
-			this.active.set(activation.id, activation);
+			this.active.set(activation.agentId, activation);
 			return activation;
 		} catch (error) {
 			await runtime.dispose().catch(() => {});
@@ -968,7 +1071,7 @@ export class SubagentCoordinator {
 		signal: AbortSignal | undefined,
 		detachAtAcceptance: boolean,
 	): { accepted: Promise<void>; result: Promise<SubagentRunResult> } {
-		if (activation.currentRun) throw new Error(`subagent ${activation.id} is already running`);
+		if (activation.currentRun) throw new Error(`subagent ${activation.agentId} is already running`);
 		if (signal?.aborted) throw signal.reason ?? new Error("subagent start aborted");
 		activation.pendingSettlement = undefined;
 		activation.status = "running";
@@ -1111,7 +1214,7 @@ export class SubagentCoordinator {
 		const closing = truncated.text.trim()
 			? `Its closing message:\n\n${truncated.text}`
 			: "It left no closing message.";
-		const content = `Background subagent ${activation.id} ${stopReasonHeadline(result.stopReason)} and will do no further work unless you send it more.\n\n${closing}${
+		const content = `Background subagent ${activation.agentId} ${stopReasonHeadline(result.stopReason)} and will do no further work unless you send it more.\n\n${closing}${
 			truncated.truncated ? `\n\n[Closing message truncated; ${truncated.omittedBytes} bytes omitted.]` : ""
 		}`;
 		await activation.parent.deliver(
@@ -1119,7 +1222,7 @@ export class SubagentCoordinator {
 			content,
 			{
 				kind: "settled",
-				childId: activation.id,
+				childAgentId: activation.agentId,
 				label: activation.descriptor.label,
 				stopReason: result.stopReason,
 				...(truncated.truncated ? { truncated: true } : {}),
@@ -1130,7 +1233,7 @@ export class SubagentCoordinator {
 
 	private parentForActivation(activation: Activation): ParentRef {
 		return {
-			id: activation.id,
+			agentId: activation.agentId,
 			depth: activation.descriptor.depth,
 			cwd: activation.descriptor.cwd,
 			sessionManager: activation.runtime.session.sessionManager,
@@ -1140,7 +1243,7 @@ export class SubagentCoordinator {
 			projectTrusted: activation.parent.projectTrusted,
 			activation,
 			deliver: async (customType, content, details, delivery) => {
-				if (activation.disposed) throw new Error(`parent subagent ${activation.id} is no longer resident`);
+				if (activation.disposed) throw new Error(`parent subagent ${activation.agentId} is no longer resident`);
 				const session = activation.runtime.session;
 				if (delivery === "quiet") {
 					await session.sendCustomMessage(
@@ -1170,7 +1273,8 @@ export class SubagentCoordinator {
 		const truncated = truncateUtf8(output, activation.descriptor.runtime.maxOutputBytes);
 		const sessionFile = activation.runtime.session.sessionFile;
 		return {
-			id: activation.id,
+			agentId: activation.agentId,
+			piSessionId: activation.runtime.session.sessionId,
 			...(sessionFile ? { sessionFile } : {}),
 			output: truncated.truncated
 				? `${truncated.text}\n\n[Output truncated; ${truncated.omittedBytes} bytes omitted.${
@@ -1224,22 +1328,24 @@ export class SubagentCoordinator {
 		if (activation.published) return;
 		activation.published = true;
 		this.pi.events.emit("pi-subagent:start", {
-			runId: activation.epochId,
-			id: activation.id,
+			runId: activation.runId,
+			agentId: activation.agentId,
+			piSessionId: activation.runtime.session.sessionId,
+			parentAgentId: activation.descriptor.parentAgentId,
 			provider: activation.descriptor.provider,
 			mode: activation.descriptor.mode,
-			parentId: activation.descriptor.parentSessionId,
 		});
 	}
 
 	private emitEnd(activation: Activation, result: SubagentRunResult): void {
 		if (!activation.published) return;
 		this.pi.events.emit("pi-subagent:end", {
-			runId: activation.epochId,
-			id: activation.id,
+			runId: activation.runId,
+			agentId: activation.agentId,
+			piSessionId: activation.runtime.session.sessionId,
+			parentAgentId: activation.descriptor.parentAgentId,
 			provider: activation.descriptor.provider,
 			mode: activation.descriptor.mode,
-			parentId: activation.descriptor.parentSessionId,
 			stopReason: result.stopReason,
 			output: result.output,
 		});
@@ -1248,7 +1354,8 @@ export class SubagentCoordinator {
 	private detailsOf(activation: Activation, result?: SubagentRunResult): DelegationDetails {
 		return {
 			kind: "delegation",
-			id: activation.id,
+			agentId: activation.agentId,
+			piSessionId: activation.runtime.session.sessionId,
 			provider: activation.descriptor.provider,
 			mode: activation.descriptor.mode,
 			agent: activation.descriptor.agent.name,
@@ -1302,14 +1409,14 @@ export class SubagentCoordinator {
 		try {
 			await activation.runtime.dispose();
 		} finally {
-			if (this.active.get(activation.id) === activation) this.active.delete(activation.id);
+			if (this.active.get(activation.agentId) === activation) this.active.delete(activation.agentId);
 		}
 	}
 
 	private async releaseParentOwnership(activation: Activation): Promise<void> {
 		const owner = activation.parent.activation;
 		if (!owner) return;
-		owner.ownedChildren.delete(activation.id);
+		owner.ownedChildren.delete(activation.agentId);
 		if (
 			!owner.currentRun &&
 			owner.ownedChildren.size === 0 &&
@@ -1321,9 +1428,9 @@ export class SubagentCoordinator {
 	}
 
 	private assertDirectParent(parent: ParentRef, descriptor: SubagentDescriptor): void {
-		if (descriptor.parentSessionId !== parent.id) {
+		if (descriptor.parentAgentId !== parent.agentId) {
 			throw new Error(
-				`subagent ${descriptor.label} is not a direct child of ${parent.id}; message was not delivered`,
+				`subagent ${descriptor.label} is not a direct child of ${parent.agentId}; message was not delivered`,
 			);
 		}
 	}
@@ -1333,7 +1440,7 @@ export class SubagentCoordinator {
 		childId: string,
 	): Promise<{ descriptor: SubagentDescriptor; sessionFile: string } | undefined> {
 		const catalog = await readPersistedCatalog(parent.sessionManager);
-		const entry = catalog.descriptors.find((candidate) => candidate.id === childId);
+		const entry = catalog.descriptors.find((candidate) => candidate.agentId === childId);
 		return entry ? { descriptor: entry.descriptor, sessionFile: entry.sessionFile } : undefined;
 	}
 
@@ -1341,16 +1448,19 @@ export class SubagentCoordinator {
 		const persisted = await readPersistedCatalog(parent.sessionManager);
 		const records = new Map<string, CatalogRecord>();
 		for (const item of persisted.descriptors) {
-			records.set(item.id, {
-				id: item.id,
+			records.set(item.agentId, {
+				agentId: item.agentId,
 				descriptor: item.descriptor,
 				sessionFile: item.sessionFile,
 			});
 		}
+		const activeSessionIds = new Set(
+			[...this.active.values()].map((activation) => activation.runtime.session.sessionId),
+		);
 		for (const activation of this.active.values()) {
 			if (activation.descriptor.cwd !== parent.cwd) continue;
-			records.set(activation.id, {
-				id: activation.id,
+			records.set(activation.agentId, {
+				agentId: activation.agentId,
 				descriptor: activation.descriptor,
 				...(activation.runtime.session.sessionFile
 					? { sessionFile: activation.runtime.session.sessionFile }
@@ -1360,7 +1470,9 @@ export class SubagentCoordinator {
 		}
 		return {
 			records: [...records.values()],
-			diagnostics: persisted.diagnostics.filter((diagnostic) => !this.active.has(diagnostic.id)),
+			diagnostics: persisted.diagnostics.filter(
+				(diagnostic) => !activeSessionIds.has(diagnostic.piSessionId),
+			),
 		};
 	}
 
@@ -1369,7 +1481,7 @@ export class SubagentCoordinator {
 		descriptor: SubagentDescriptor,
 		byId: Map<string, CatalogRecord>,
 	): number | undefined {
-		let parentId = descriptor.parentSessionId;
+		let parentId = descriptor.parentAgentId;
 		let distance = 1;
 		const visited = new Set<string>();
 		while (true) {
@@ -1378,16 +1490,21 @@ export class SubagentCoordinator {
 			visited.add(parentId);
 			const parent = byId.get(parentId);
 			if (!parent) return undefined;
-			parentId = parent.descriptor.parentSessionId;
+			parentId = parent.descriptor.parentAgentId;
 			distance++;
 		}
 	}
 
 	private async isDescendantOf(parent: ParentRef, descriptor: SubagentDescriptor): Promise<boolean> {
 		const { records } = await this.catalogRecords(parent);
-		const byId = new Map(records.map((record) => [record.id, record]));
-		return this.distanceFrom(parent.id, descriptor, byId) !== undefined;
+		const byId = new Map(records.map((record) => [record.agentId, record]));
+		return this.distanceFrom(parent.agentId, descriptor, byId) !== undefined;
 	}
 }
 
-export { REPORT_CUSTOM_TYPE, SETTLED_CUSTOM_TYPE };
+export {
+	REPORT_CUSTOM_TYPE,
+	SETTLED_CUSTOM_TYPE,
+	AGENT_CUSTOM_TYPE,
+	LINEAGE_CUSTOM_TYPE,
+};

package/src/descriptor.ts

@@ -11,7 +11,7 @@ import type {
 } from "./types.ts";
 
 export const DESCRIPTOR_CUSTOM_TYPE = "pi-subagent/descriptor";
-export const DESCRIPTOR_VERSION = 1;
+export const DESCRIPTOR_VERSION = 2;
 
 const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const AGENT_SOURCES = new Set<AgentSource>(["bundled", "user", "project"]);
@@ -20,6 +20,8 @@ const PROVIDERS = new Set<SubagentProviderName>(["spawn", "fork"]);
 const REPORT_DELIVERIES = new Set<ReportDelivery>(["wakeup", "quiet"]);
 const AGENT_SCOPES = new Set<AgentScope>(["user", "project", "both"]);
 const AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** UUIDv7 with the standard RFC 9562 variant bits (version 7, variant 10xx). */
+const AGENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -46,6 +48,14 @@ function optionalString(value: unknown, field: string): string | undefined {
 	return value === undefined ? undefined : string(value, field);
 }
 
+function agentId(value: unknown, field: string): string {
+	const parsed = string(value, field);
+	if (!AGENT_ID_PATTERN.test(parsed)) {
+		throw new Error(`${field} must be a UUIDv7 agent id`);
+	}
+	return parsed;
+}
+
 function limitedString(value: unknown, field: string, maxLength: number): string {
 	const parsed = string(value, field);
 	if (parsed.length > maxLength) throw new Error(`${field} exceeds ${maxLength} characters`);
@@ -135,7 +145,9 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 		mode,
 		provider,
 		label: limitedString(input.label, "label", 200),
-		parentSessionId: string(input.parentSessionId, "parentSessionId"),
+		agentId: agentId(input.agentId, "agentId"),
+		parentAgentId: agentId(input.parentAgentId, "parentAgentId"),
+		parentPiSessionId: string(input.parentPiSessionId, "parentPiSessionId"),
 		...(optionalString(input.parentSessionFile, "parentSessionFile")
 			? { parentSessionFile: input.parentSessionFile as string }
 			: {}),
@@ -162,6 +174,7 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 			defaultBackground: boolean(runtime.defaultBackground, "runtime.defaultBackground"),
 			reportDelivery,
 			inheritExtensions: boolean(runtime.inheritExtensions, "runtime.inheritExtensions"),
+			openAIIdentity: boolean(runtime.openAIIdentity, "runtime.openAIIdentity"),
 			maxOutputBytes: boundedInteger(
 				runtime.maxOutputBytes,
 				"runtime.maxOutputBytes",

package/src/index.ts

@@ -78,11 +78,11 @@ function registerDelegationTool(
 			"This foreground-only tool waits for the child and returns its final answer. " +
 			"Independent sibling calls may still execute in parallel."
 		: defaultBackground
-			? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-				"Background mode is continuable and returns a durable child id; use send_message for later FIFO turns. " +
-				"Start independent children together in one assistant message."
-			: "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-				"This tool waits for the result by default; set run_in_background to true to return a durable child id.";
+		? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
+			"Background mode is continuable and returns a durable agent id; use send_message for later FIFO turns. " +
+			"Start independent children together in one assistant message."
+		: "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
+			"This tool waits for the result by default; set run_in_background to true to return a durable agent id.";
 	const promptGuidelines = !enableRunInBackground
 		? [
 				"Use subagent for focused independent work and give it a complete standalone prompt.",
@@ -214,7 +214,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		name: "send_message",
 		label: "Send Message",
 		description:
-			"Queue a message as a direct continuable child's next FIFO turn. If it is inactive, its persisted session is cold-resumed. " +
+			"Queue a message as a direct continuable child's next FIFO turn. If it is inactive, its persisted session is cold-resumed by agent id. " +
 			"This call returns acceptance only, never the child's answer.",
 		promptSnippet: "Send a later FIFO turn to a direct continuable subagent",
 		executionMode: "parallel",
@@ -230,7 +230,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 						text: `message queued as the next turn for subagent ${params.subagent_id}`,
 					},
 				],
-				details: { kind: "control", action: "send", id: params.subagent_id } satisfies ControlDetails,
+				details: { kind: "control", action: "send", agentId: params.subagent_id } satisfies ControlDetails,
 			};
 		},
 	});
@@ -250,7 +250,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			await coordinator.interrupt(parent, params.agent_id);
 			return {
 				content: [{ type: "text", text: `interrupt requested for agent ${params.agent_id}` }],
-				details: { kind: "control", action: "interrupt", id: params.agent_id } satisfies ControlDetails,
+				details: { kind: "control", action: "interrupt", agentId: params.agent_id } satisfies ControlDetails,
 			};
 		},
 	});
@@ -307,6 +307,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					: "foreground-first";
 			const sections = [
 				`Mode: ${schedulingMode}`,
+				`OpenAI identity inline: ${sessionSettings.openAIIdentity ? "enabled" : "disabled"}`,
 				sessionSettings.syncBundledAgents
 					? `Bundled presets: synchronized to ${agentSync?.userAgentsDir ?? coordinator.getUserAgentsDir()}`
 					: "Bundled presets: package defaults (no filesystem sync)",

package/src/providers.ts

@@ -9,6 +9,8 @@ export interface SessionView {
 	getSessionDir(): string;
 	getSessionFile(): string | undefined;
 	getSessionId(): string;
+	getEntries(): SessionEntry[];
+	appendCustomEntry(customType: string, data?: unknown): string;
 }
 
 export interface ProviderParent {

package/src/render.ts

@@ -46,7 +46,7 @@ export function renderDelegationResult(
 	const header = `${icon} ${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(
 		"muted",
 		`[${details.provider}/${details.mode}]`,
-	)} ${theme.fg("dim", details.id)}`;
+	)} ${theme.fg("dim", details.agentId)}`;
 
 	if (!options.expanded) {
 		const lines = [header, theme.fg("muted", details.label)];
@@ -102,7 +102,7 @@ export function renderParentMessage(
 		theme.fg("accent", icon) +
 			" " +
 			theme.fg("toolTitle", theme.bold(`subagent ${kind}`)) +
-			theme.fg("muted", ` ${details?.childId ?? "unknown"}${label}`),
+			theme.fg("muted", ` ${details?.childAgentId ?? "unknown"}${label}`),
 		outputPad,
 		0,
 	);

package/src/schemas.ts

@@ -87,7 +87,10 @@ export function forkDelegationParameters(agentNames?: readonly string[]) {
 
 export const SendMessageParameters = Type.Object(
 	{
-		subagent_id: Type.String({ description: "Durable id of a direct continuable child", minLength: 1 }),
+		subagent_id: Type.String({
+			description: "Durable agent id of a direct continuable child",
+			minLength: 1,
+		}),
 		message: Type.String({
 			description: "Message to enqueue as the child's next FIFO turn",
 			minLength: 1,
@@ -99,7 +102,7 @@ export const SendMessageParameters = Type.Object(
 export const InterruptParameters = Type.Object(
 	{
 		agent_id: Type.String({
-			description: "Id of a live child or deeper descendant whose current turn should stop",
+			description: "Agent id of a live child or deeper descendant whose current turn should stop",
 			minLength: 1,
 		}),
 	},

package/src/types.ts

@@ -16,6 +16,7 @@ export interface SubagentSettings {
 	defaultBackground: boolean;
 	reportDelivery: ReportDelivery;
 	inheritExtensions: boolean;
+	openAIIdentity: boolean;
 	maxOutputBytes: number;
 }
 
@@ -53,15 +54,22 @@ export interface SubagentRuntimeSnapshot {
 	defaultBackground: boolean;
 	reportDelivery: ReportDelivery;
 	inheritExtensions: boolean;
+	openAIIdentity: boolean;
 	maxOutputBytes: number;
 }
 
 export interface SubagentDescriptor {
-	version: 1;
+	version: 2;
 	mode: SubagentMode;
 	provider: SubagentProviderName;
 	label: string;
-	parentSessionId: string;
+	/** Durable pi-subagent control identity, independent of provider wire ids. */
+	agentId: string;
+	/** Durable control identity of the delegating pi-subagent. */
+	parentAgentId: string;
+	/** Pi session lookup key of the delegating agent; never used as a wire id. */
+	parentPiSessionId: string;
+	/** Path of the parent's session file at delegation time (attribute, not identity). */
 	parentSessionFile?: string;
 	depth: number;
 	cwd: string;
@@ -77,7 +85,8 @@ export interface SubagentUsage extends Usage {
 }
 
 export interface SubagentRunResult {
-	id: string;
+	agentId: string;
+	piSessionId?: string;
 	sessionFile?: string;
 	output: string;
 	stopReason: SubagentStopReason;
@@ -92,7 +101,8 @@ export interface TraceItem {
 
 export interface DelegationDetails {
 	kind: "delegation";
-	id: string;
+	agentId: string;
+	piSessionId?: string;
 	provider: SubagentProviderName;
 	mode: SubagentMode;
 	agent: string;
@@ -109,13 +119,13 @@ export interface DelegationDetails {
 export interface ControlDetails {
 	kind: "control";
 	action: "send" | "interrupt" | "list" | "report";
-	id?: string;
+	agentId?: string;
 }
 
 export interface CatalogChild {
 	kind: "child";
-	id: string;
-	parentId: string;
+	agentId: string;
+	parentAgentId: string;
 	depth: number;
 	descriptor: SubagentDescriptor;
 	sessionFile?: string;
@@ -124,7 +134,7 @@ export interface CatalogChild {
 
 export interface CatalogDiagnostic {
 	kind: "diagnostic";
-	id: string;
+	piSessionId: string;
 	reason: "corrupt" | "unavailable";
 	sessionFile?: string;
 	parentSessionFile?: string;
@@ -135,7 +145,7 @@ export type CatalogEntry = CatalogChild | CatalogDiagnostic;
 
 export interface ParentMessageDetails {
 	kind: "report" | "settled";
-	childId: string;
+	childAgentId: string;
 	label: string;
 	stopReason?: SubagentStopReason;
 	truncated?: boolean;